qa/README.md

   1 The [pull-tester](/qa/pull-tester/) folder contains a script to call
   2 multiple tests from the [rpc-tests](/qa/rpc-tests/) folder.
   3
   4 Every pull request to the bitcoin repository is built and run through
   5 the regression test suite. You can also run all or only individual
   6 tests locally.
   7
   8 Test dependencies
   9 =================
  10 Before running the tests, the following must be installed.
  11
  12 Unix
  13 ----
  14 The python3-zmq library is required. On Ubuntu or Debian it can be installed via:
  15 ```
  16 sudo apt-get install python3-zmq
  17 ```
  18
  19 OS X
  20 ------
  21 ```
  22 pip3 install pyzmq
  23 ```
  24
  25 Running tests
  26 =============
  27
  28 You can run any single test by calling
  29
  30     qa/pull-tester/rpc-tests.py <testname>
  31
  32 Or you can run any combination of tests by calling
  33
  34     qa/pull-tester/rpc-tests.py <testname1> <testname2> <testname3> ...
  35
  36 Run the regression test suite with
  37
  38     qa/pull-tester/rpc-tests.py
  39
  40 Run all possible tests with
  41
  42     qa/pull-tester/rpc-tests.py -extended
  43
  44 By default, tests will be run in parallel. To specify how many jobs to run,
  45 append `-parallel=n` (default n=4).
  46
  47 If you want to create a basic coverage report for the rpc test suite, append `--coverage`.
  48
  49 Possible options, which apply to each individual test run:
  50
  51 ```
  52   -h, --help            show this help message and exit
  53   --nocleanup           Leave bitcoinds and test.* datadir on exit or error
  54   --noshutdown          Don't stop bitcoinds after the test execution
  55   --srcdir=SRCDIR       Source directory containing bitcoind/bitcoin-cli
  56                         (default: ../../src)
  57   --tmpdir=TMPDIR       Root directory for datadirs
  58   --tracerpc            Print out all RPC calls as they are made
  59   --coveragedir=COVERAGEDIR
  60                         Write tested RPC commands into this directory
  61 ```
  62
  63 If you set the environment variable `PYTHON_DEBUG=1` you will get some debug
  64 output (example: `PYTHON_DEBUG=1 qa/pull-tester/rpc-tests.py wallet`).
  65
  66 A 200-block -regtest blockchain and wallets for four nodes
  67 is created the first time a regression test is run and
  68 is stored in the cache/ directory. Each node has 25 mature
  69 blocks (25*50=1250 BTC) in its wallet.
  70
  71 After the first run, the cache/ blockchain and wallets are
  72 copied into a temporary directory and used as the initial
  73 test state.
  74
  75 If you get into a bad state, you should be able
  76 to recover with:
  77
  78 ```bash
  79 rm -rf cache
  80 killall bitcoind
  81 ```
  82
  83 Writing tests
  84 =============
  85 You are encouraged to write tests for new or existing features.
  86 Further information about the test framework and individual rpc
  87 tests is found in [qa/rpc-tests](/qa/rpc-tests).