aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--doc/rapidcheck.md84
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.