mirrors/bitcoin
1
0
Fork 0
mirror of https://github.com/bitcoin/bitcoin.git synced 2025-03-27 02:36:47 +01:00
Code Issues Projects Releases Wiki Activity

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
`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
Unit tests will be automatically compiled if dependencies were met
during the generation of the Bitcoin Core build system
and tests weren't explicitly disabled.
Assuming the build directory is named `build`, the unit tests can be run
with `ctest --test-dir build`, which includes unit tests from subtrees.
The unit tests can be run with `ctest --test-dir build`, which includes unit
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
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
`test_bitcoin` accepts the command line arguments from the boost framework.
For example, to run just the `getarg_tests` suite of tests:
The `test_bitcoin` runner accepts command line arguments from the Boost
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
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
test case is entered, for example.
or
`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:
```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
normally goes only to `debug.log` within the data directory, also to the
standard terminal output.
normally goes only to `debug.log` within the data directory, to the
standard terminal output as well.
... or to run just the doubledash test:
```bash
build/src/test/test_bitcoin --run_test=getarg_tests/doubledash
```
`test_bitcoin` creates a temporary working (data) directory with a randomly
Running `test_bitcoin` creates a temporary working (data) directory with a randomly
generated pathname within `test_common bitcoin/`, which in turn is within
the system's temporary directory (see
[`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
will be created for each individual test.
Run `test_bitcoin --help` for the full list of tests.
### Adding test cases
To add a new unit test file to our test suite, you need