bitcoin_proptest/
lib.rs

1/*!
2
3# Rust Bitcoin Proptest Strategies
4
5Proptest strategies for Bitcoin-related code.
6
7This collection of generators (called _strategies_ in proptest's terminology) helps
8developers of Bitcoin-related software written in Rust supply random data – both valid and
9invalid – to their property-based tests.
10
11## Basic rules
12
131. unless documentation specifies, the strategy generates anything, i. e. all possible variants, both valid and invalid, as long as type permits, for example:
14   - “Generates descriptors” means any type, both valid and invalid
15   - “Generates valid descriptors” means any type, all valid
161. every strategy also has an adjacent strategy called `build` where inputs (in form of strategies) can be specified, for example:
17   - to generate PKH descriptor, some public key needs to be supplied
18   - [`descriptor::pkh()`](prop::bitcoin::descriptor::pkh::string()) will use a strategy generating any possible valid public key
19   - [`descriptor::pkh::valid::build(impl Strategy<DescriptorPublicKey>)`](prop::bitcoin::descriptor::pkh::valid::build()) allows
20     to supply custom strategy for generating public keys
21
22## Organization
23
24All strategies are placed in module [`prop`] sorted by category. Inside each category, there is typically
25a nested set of modules that further specify properties of the strategies. The modules are usually
26organized as `prop::category::what::what::what::how()` where `how()` is the strategy returning a specific
27format of `what`, for example: `prop::secp256k1::public_key::invalid::compressed::vec()`.
28
29If a strategy (in form of function) is placed at the same level as other modules, they typically generate
30mix of all modules at that level. For example `prop::secp256k1::public_key::valid::vec()` will generate
31byte vectors of both compressed an uncompressed public keys and `prop::secp256k1::public_key::vec()` will
32generate valid and invalid, compressed as well as uncompressed public keys.
33
34## Example
35
36 ```rust
37#[cfg(test)]
38mod tests {
39  proptest! {
40     #[test]
41     // generates valid hex-encoded public keys, both compressed and uncompressed
42     fn pubkey_parsing(s in prop::secp256k1::public_key::valid::hex()) {
43        prop_assert!(s.len() == 66 || s.len() == 130);
44        prop_assert!(my_parser(s).is_ok());
45     }
46  }
47}
48```
49
50## Binary
51
52An accompanying binary (in form of an example) allows to print samples of strategies with textual outputs. By default
5310 samples are printed, their number can be modified by passing argument `-n`. Description of all arguments can be
54displayed using `--help`.
55
56```sh
57$> cargo run --example samples -- --list
58
59bitcoin/address
60bitcoin/address/p2pkh
61bitcoin/address/p2wpkh
62bitcoin/address/p2sh
63bitcoin/address/p2shwpkh
64bitcoin/bip32/xpriv
65bitcoin/bip32/xpub
66bitcoin/descriptor/pkh
67bitcoin/descriptor/pkh/valid
68bitcoin/descriptor/pkh/invalid
69[…]
70
71$> cargo run --example samples -- bitcoin/address
72
73mgV22Th8EoBjK3F8gkq12darpYKfZhRVVC
742N4H6BHitgp1X3XxBJchXDC7Js8vuwn9nLR
752NEWWVbyXiFEJy1rijrqWAYWsKuPfgq4iSG
762MwBxE5uhRjMn6oQCVDCibtxgLq5eYmai4Y
771FS9MqvDR5e23TmmkG3UgxWhHwmxChkTAd
783AmhvjgGiqpUX8bDNGiv75cr1oF9j5sEp1
792MvdWb16UVVzJg1BatV7UHR1paKH2TVdX79
80mhss96DFw9FsdqBx2kWN4w1irRixh1f2Me
81mtodi2dJnPP4GBbTqsbRD9Z4JdHc9mMwMW
8219WsVuhxY2h9czLcgrhvW5a5hUAUsDNjB6
83```
84*/
85
86#![deny(missing_docs)]
87
88/// Collection of all proptest strategies.
89pub mod prop {
90
91    /// Bitcoin strategies.
92    pub mod bitcoin;
93
94    /// Secp256k1 strategies.
95    pub mod secp256k1;
96}
bitcoin_proptest/lib.rs

bitcoin_proptest/
lib.rs
