diff options
Diffstat (limited to 'test/README.md')
| -rw-r--r-- | test/README.md | 40 |
1 files changed, 21 insertions, 19 deletions
diff --git a/test/README.md b/test/README.md index 0d1e06c0ad..74adc644b8 100644 --- a/test/README.md +++ b/test/README.md @@ -13,13 +13,15 @@ interfaces. - [util](/test/util) which tests the utilities (bitcoin-util, bitcoin-tx, ...). - [lint](/test/lint/) which perform various static analysis checks. -The util tests are run as part of `make check` target. The fuzz tests, functional +The util tests are run as part of `ctest` invocation. The fuzz tests, functional tests and lint scripts can be run as explained in the sections below. # Running tests locally Before tests can be run locally, Bitcoin Core must be built. See the [building instructions](/doc#building) for help. +The following examples assume that the build directory is named `build`. + ## Fuzz tests See [/doc/fuzzing.md](/doc/fuzzing.md) @@ -45,19 +47,19 @@ set PYTHONUTF8=1 Individual tests can be run by directly calling the test script, e.g.: ``` -test/functional/feature_rbf.py +build/test/functional/feature_rbf.py ``` or can be run through the test_runner harness, eg: ``` -test/functional/test_runner.py feature_rbf.py +build/test/functional/test_runner.py feature_rbf.py ``` You can run any combination (incl. duplicates) of tests by calling: ``` -test/functional/test_runner.py <testname1> <testname2> <testname3> ... +build/test/functional/test_runner.py <testname1> <testname2> <testname3> ... ``` Wildcard test names can be passed, if the paths are coherent and the test runner @@ -65,34 +67,34 @@ is called from a `bash` shell or similar that does the globbing. For example, to run all the wallet tests: ``` -test/functional/test_runner.py test/functional/wallet* -functional/test_runner.py functional/wallet* (called from the test/ directory) -test_runner.py wallet* (called from the test/functional/ directory) +build/test/functional/test_runner.py test/functional/wallet* +functional/test_runner.py functional/wallet* # (called from the build/test/ directory) +test_runner.py wallet* # (called from the build/test/functional/ directory) ``` but not ``` -test/functional/test_runner.py wallet* +build/test/functional/test_runner.py wallet* ``` Combinations of wildcards can be passed: ``` -test/functional/test_runner.py ./test/functional/tool* test/functional/mempool* +build/test/functional/test_runner.py ./test/functional/tool* test/functional/mempool* test_runner.py tool* mempool* ``` Run the regression test suite with: ``` -test/functional/test_runner.py +build/test/functional/test_runner.py ``` Run all possible tests with ``` -test/functional/test_runner.py --extended +build/test/functional/test_runner.py --extended ``` In order to run backwards compatibility tests, first run: @@ -107,7 +109,7 @@ By default, up to 4 tests will be run in parallel by test_runner. To specify how many jobs to run, append `--jobs=n` The individual tests and the test_runner harness have many command-line -options. Run `test/functional/test_runner.py -h` to see them all. +options. Run `build/test/functional/test_runner.py -h` to see them all. #### Speed up test runs with a RAM disk @@ -130,7 +132,7 @@ For example running the test suite with `--jobs=100` might need a 4 GiB RAM disk To use, run the test suite specifying the RAM disk as the `cachedir` and `tmpdir`: ```bash -test/functional/test_runner.py --cachedir=/mnt/tmp/cache --tmpdir=/mnt/tmp +build/test/functional/test_runner.py --cachedir=/mnt/tmp/cache --tmpdir=/mnt/tmp ``` Once finished with the tests and the disk, and to free the RAM, simply unmount the disk: @@ -151,7 +153,7 @@ Configure the RAM disk size, expressed as the number of blocks, at the end of th (`4096 MiB * 2048 blocks/MiB = 8388608 blocks` for 4 GiB). To run the tests using the RAM disk: ```bash -test/functional/test_runner.py --cachedir=/Volumes/ramdisk/cache --tmpdir=/Volumes/ramdisk/tmp +build/test/functional/test_runner.py --cachedir=/Volumes/ramdisk/cache --tmpdir=/Volumes/ramdisk/tmp ``` To unmount: @@ -193,14 +195,14 @@ pkill -9 bitcoind ##### Data directory cache A pre-mined blockchain with 200 blocks is generated the first time a -functional test is run and is stored in test/cache. This speeds up +functional test is run and is stored in build/test/cache. This speeds up test startup times since new blockchains don't need to be generated for each test. However, the cache may get into a bad state, in which case tests will fail. If this happens, remove the cache directory (and make sure bitcoind processes are stopped as above): ```bash -rm -rf test/cache +rm -rf build/test/cache killall bitcoind ``` @@ -236,7 +238,7 @@ aggregate log by running the `combine_logs.py` script. The output can be plain text, colorized text or html. For example: ``` -test/functional/combine_logs.py -c <test data directory> | less -r +build/test/functional/combine_logs.py -c <test data directory> | less -r ``` will pipe the colorized logs from the test into less. @@ -297,7 +299,7 @@ See this link for considerations: https://www.kernel.org/doc/Documentation/secur Often while debugging RPC calls in functional tests, the test might time out before the process can return a response. Use `--timeout-factor 0` to disable all RPC timeouts for that particular -functional test. Ex: `test/functional/wallet_hd.py --timeout-factor 0`. +functional test. Ex: `build/test/functional/wallet_hd.py --timeout-factor 0`. ##### Profiling @@ -321,7 +323,7 @@ For ways to generate more granular profiles, see the README in ### Util tests -Util tests can be run locally by running `test/util/test_runner.py`. +Util tests can be run locally by running `build/test/util/test_runner.py`. Use the `-v` option for verbose output. ### Lint tests |