phantom/bitcoin
1
0
Fork 0
mirror of https://github.com/bitcoin/bitcoin.git synced 2025-04-29 14:59:39 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions 1

Unit test runner documentation fix and improvements

Browse source 
- Running `test_bitcoin --help` prints the list of arguments that may be passed,
  not the list of tests, so fix that.

- Improve the content and order of the unit test documentation.
This commit is contained in:
Jon Atack 2024-09-12 12:22:36 -06:00
parent be768dbd18
commit 282f0e9255
1 changed files with 32 additions and 18 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

50
src/test/README.md
View file

@ -10,14 +10,19 @@ The build system is set up to compile an executable called `test_bitcoin`
that runs all of the unit tests. The main source file for the test library is found in that runs all of the unit tests. The main source file for the test library is found in
`util/setup_common.cpp`. `util/setup_common.cpp`.
The examples in this document assume the build directory is named
`build`. You'll need to adapt them if you named it differently.
### Compiling/running unit tests ### Compiling/running unit tests
Unit tests will be automatically compiled if dependencies were met Unit tests will be automatically compiled if dependencies were met
during the generation of the Bitcoin Core build system during the generation of the Bitcoin Core build system
and tests weren't explicitly disabled. and tests weren't explicitly disabled.
Assuming the build directory is named `build`, the unit tests can be run The unit tests can be run with `ctest --test-dir build`, which includes unit
with `ctest --test-dir build`, which includes unit tests from subtrees. tests from subtrees.
Run `test_bitcoin --list_content` for the full list of tests.
To run the unit tests manually, launch `build/src/test/test_bitcoin`. To recompile To run the unit tests manually, launch `build/src/test/test_bitcoin`. To recompile
after a test file was modified, run `cmake --build build` and then run the test again. If you after a test file was modified, run `cmake --build build` and then run the test again. If you
@ -35,17 +40,34 @@ the `src/qt/test/test_main.cpp` file.
### Running individual tests ### Running individual tests
`test_bitcoin` accepts the command line arguments from the boost framework. The `test_bitcoin` runner accepts command line arguments from the Boost
For example, to run just the `getarg_tests` suite of tests: framework. To see the list of arguments that may be passed, run:
```
test_bitcoin --help
```
For example, to run only the tests in the `getarg_tests` file, with full logging:
```bash ```bash
build/src/test/test_bitcoin --log_level=all --run_test=getarg_tests build/src/test/test_bitcoin --log_level=all --run_test=getarg_tests
``` ```
`log_level` controls the verbosity of the test framework, which logs when a or
test case is entered, for example.
`test_bitcoin` also accepts some of the command line arguments accepted by ```bash
build/src/test/test_bitcoin -l all -t getarg_tests
```
or to run only the doubledash test in `getarg_tests`
```bash
build/src/test/test_bitcoin --run_test=getarg_tests/doubledash
```
The `--log_level=` (or `-l`) argument controls the verbosity of the test output.
The `test_bitcoin` runner also accepts some of the command line arguments accepted by
`bitcoind`. Use `--` to separate these sets of arguments: `bitcoind`. Use `--` to separate these sets of arguments:
```bash ```bash
@ -53,16 +75,10 @@ build/src/test/test_bitcoin --log_level=all --run_test=getarg_tests -- -printtoc
``` ```
The `-printtoconsole=1` after the two dashes sends debug logging, which The `-printtoconsole=1` after the two dashes sends debug logging, which
normally goes only to `debug.log` within the data directory, also to the normally goes only to `debug.log` within the data directory, to the
standard terminal output. standard terminal output as well.
... or to run just the doubledash test: Running `test_bitcoin` creates a temporary working (data) directory with a randomly
```bash
build/src/test/test_bitcoin --run_test=getarg_tests/doubledash
```
`test_bitcoin` creates a temporary working (data) directory with a randomly
generated pathname within `test_common bitcoin/`, which in turn is within generated pathname within `test_common bitcoin/`, which in turn is within
the system's temporary directory (see the system's temporary directory (see
[`temp_directory_path`](https://en.cppreference.com/w/cpp/filesystem/temp_directory_path)). [`temp_directory_path`](https://en.cppreference.com/w/cpp/filesystem/temp_directory_path)).
@ -97,8 +113,6 @@ If you run an entire test suite, such as `--run_test=getarg_tests`, or all the t
(by not specifying `--run_test`), a separate directory (by not specifying `--run_test`), a separate directory
will be created for each individual test. will be created for each individual test.
Run `test_bitcoin --help` for the full list of tests.
### Adding test cases ### Adding test cases
To add a new unit test file to our test suite, you need To add a new unit test file to our test suite, you need