mirrors/bitcoin
1
0
Fork 0
mirror of https://github.com/bitcoin/bitcoin.git synced 2024-11-20 10:38:42 +01:00
Code Issues Projects Releases Wiki Activity

Merge #16645: doc: initial RapidCheck property-based testing documentation

Browse Source 
8616c81f08 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 8616c81f08 - Thanks for updating.

Tree-SHA512: 9c2a65f0eb99f59e9adfea82855f217727a8a9d30618c1c0bdd2a73ae9c1ee61bc7efd59fc8703a666d182ad4220e22d6034ac3109311e6573dad00dfa4b06ea
This commit is contained in:
Wladimir J. van der Laan 2019-08-19 16:08:45 +02:00
commit bd62f8d6ee
No known key found for this signature in database
GPG Key ID: 1E4AED62986CD25D
1 changed files with 84 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

84
doc/rapidcheck.md Normal file
View File

@ -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.