diff options
| -rw-r--r-- | doc/rapidcheck.md | 84 |
1 files changed, 84 insertions, 0 deletions
diff --git a/doc/rapidcheck.md b/doc/rapidcheck.md new file mode 100644 index 0000000000..397a907f17 --- /dev/null +++ b/doc/rapidcheck.md @@ -0,0 +1,84 @@ +# RapidCheck property-based testing for Bitcoin Core + +## Concept + +Property-based testing is experimentally being added to Bitcoin Core with +[RapidCheck](https://github.com/emil-e/rapidcheck), a C++ framework for +property-based testing inspired by the Haskell library +[QuickCheck](https://hackage.haskell.org/package/QuickCheck). + +RapidCheck performs random testing of program properties. A specification of the +program is given in the form of properties which functions should satisfy, and +RapidCheck tests that the properties hold in a large number of randomly +generated cases. + +If an exception is found, RapidCheck tries to find the smallest case, for some +definition of smallest, for which the property is still false and displays it as +a counter-example. For example, if the input is an integer, RapidCheck tries to +find the smallest integer for which the property is false. + +## Running + +If RapidCheck is installed, Bitcoin Core will automatically run the +property-based tests with the unit tests during `make check`, unless the +`--without-rapidcheck` flag is passed when configuring. + +For more information, run `./configure --help` and see `--with-rapidcheck` under +Optional Packages. + +## Setup + +The following instructions have been tested with Linux Debian and macOS. + +1. Clone the RapidCheck source code and cd into the repository. + + ```shell + git clone https://github.com/emil-e/rapidcheck.git + cd rapidcheck + ``` + +2. Build RapidCheck (requires CMake to be installed). + + ```shell + cmake -DCMAKE_POSITION_INDEPENDENT_CODE:BOOL=true -DRC_ENABLE_BOOST_TEST=ON $(pwd) + make && make install + ``` + +3. Configure Bitcoin Core with RapidCheck. + + `cd` to the directory of your local bitcoin repository and run + `./configure`. In the output you should see: + + ```shell + checking rapidcheck.h usability... yes + checking rapidcheck.h presence... yes + checking for rapidcheck.h... yes + [...] + Options used to compile and link: + [...] + with test = yes + with prop = yes + ``` + +4. Build Bitcoin Core with RapidCheck. + + Now you can run `make` and should see the property-based tests compiled with + the unit tests: + + ```shell + Making all in src + [...] + CXX test/gen/test_bitcoin-crypto_gen.o + CXX test/test_bitcoin-key_properties.o + ``` + +5. Run the unit tests with `make check`. The property-based tests will be run + with the unit tests. + + ```shell + Running tests: crypto_tests from test/crypto_tests.cpp + [...] + Running tests: key_properties from test/key_properties.cpp + ``` + +That's it! You are now running property-based tests in Bitcoin Core. |