diff options
author | Wladimir J. van der Laan <laanwj@protonmail.com> | 2019-08-19 16:08:45 +0200 |
---|---|---|
committer | Wladimir J. van der Laan <laanwj@protonmail.com> | 2019-08-19 16:08:53 +0200 |
commit | bd62f8d6eed83a3e8249177513e2a29d6af0dc0e (patch) | |
tree | 75a0ee7038d4eacfad67c63b1e311da887ea9184 | |
parent | 83112db129de1ad5a606a92352a4b3240ad8e96b (diff) | |
parent | 8616c81f08c8118003e035808b3f237b3bb211a9 (diff) | |
download | bitcoin-bd62f8d6eed83a3e8249177513e2a29d6af0dc0e.tar.xz |
Merge #16645: doc: initial RapidCheck property-based testing documentation
8616c81f08c8118003e035808b3f237b3bb211a9 doc: initial RapidCheck property-based testing documentation (Jon Atack)
Pull request description:
This commit proposes documentation that would have been helpful to me when setting up RapidCheck to work correctly with Bitcoin Core. I tested these instructions repeatedly with Linux (Debian 4.19 / GCC 8.3) and macOS (10.14.6 / AppleClang 10).
The markdown version can be seen at https://github.com/jonatack/bitcoin/blob/rapidcheck-documentation/doc/rapidcheck.md.
ACKs for top commit:
fanquake:
ACK 8616c81f08c8118003e035808b3f237b3bb211a9 - Thanks for updating.
Tree-SHA512: 9c2a65f0eb99f59e9adfea82855f217727a8a9d30618c1c0bdd2a73ae9c1ee61bc7efd59fc8703a666d182ad4220e22d6034ac3109311e6573dad00dfa4b06ea
-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. |