diff options
Diffstat (limited to 'src/test/README.md')
| -rw-r--r-- | src/test/README.md | 56 |
1 files changed, 35 insertions, 21 deletions
diff --git a/src/test/README.md b/src/test/README.md index a6e89aac80..7e0f245ee8 100644 --- a/src/test/README.md +++ b/src/test/README.md @@ -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,35 +40,46 @@ 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 -`bitcoind`. Use `--` to separate these sets of arguments: +```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 --log_level=all --run_test=getarg_tests -- -printtoconsole=1 +build/src/test/test_bitcoin --run_test=getarg_tests/doubledash ``` -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. +The `--log_level=` (or `-l`) argument controls the verbosity of the test output. -... or to run just the doubledash test: +The `test_bitcoin` runner also accepts some of the command line arguments accepted by +`bitcoind`. Use `--` to separate these sets of arguments: ```bash -build/src/test/test_bitcoin --run_test=getarg_tests/doubledash +build/src/test/test_bitcoin --log_level=all --run_test=getarg_tests -- -printtoconsole=1 ``` -`test_bitcoin` creates a temporary working (data) directory with a randomly -generated pathname within `test_common_Bitcoin Core/`, which in turn is within +The `-printtoconsole=1` after the two dashes sends debug logging, which +normally goes only to `debug.log` within the data directory, to the +standard terminal output as well. + +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)). This data directory looks like a simplified form of the standard `bitcoind` data @@ -73,7 +89,7 @@ have a `debug.log` file, for example. The location of the temporary data directory can be specified with the `-testdatadir` option. This can make debugging easier. The directory path used is the argument path appended with -`/test_common_Bitcoin Core/<test-name>/datadir`. +`/test_common bitcoin/<test-name>/datadir`. The directory path is created if necessary. Specifying this argument also causes the data directory not to be removed after the last test. This is useful for looking at @@ -83,11 +99,11 @@ so no leftover state is used.) ```bash $ build/src/test/test_bitcoin --run_test=getarg_tests/doubledash -- -testdatadir=/somewhere/mydatadir -Test directory (will not be deleted): "/somewhere/mydatadir/test_common_Bitcoin Core/getarg_tests/doubledash/datadir" +Test directory (will not be deleted): "/somewhere/mydatadir/test_common bitcoin/getarg_tests/doubledash/datadir" Running 1 test case... *** No errors detected -$ ls -l '/somewhere/mydatadir/test_common_Bitcoin Core/getarg_tests/doubledash/datadir' +$ ls -l '/somewhere/mydatadir/test_common bitcoin/getarg_tests/doubledash/datadir' total 8 drwxrwxr-x 2 admin admin 4096 Nov 27 22:45 blocks -rw-rw-r-- 1 admin admin 1003 Nov 27 22:45 debug.log @@ -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 |