Changeset View
Changeset View
Standalone View
Standalone View
doc/functional-tests.md
| Show First 20 Lines • Show All 271 Lines • ▼ Show 20 Lines | |||||
| - Call `network_thread_start()` after all `P2PInterface` objects are created to | - Call `network_thread_start()` after all `P2PInterface` objects are created to | ||||
| start the networking thread. (Continue with the test logic in your existing | start the networking thread. (Continue with the test logic in your existing | ||||
| thread.) | thread.) | ||||
| - Can be used to write tests where specific P2P protocol behavior is tested. | - Can be used to write tests where specific P2P protocol behavior is tested. | ||||
| Examples tests are `p2p_unrequested_blocks.py`, `p2p_compactblocks.py`. | Examples tests are `p2p_unrequested_blocks.py`, `p2p_compactblocks.py`. | ||||
| #### Comptool | |||||
| - Comptool is a Testing framework for writing tests that compare the block/tx acceptance | |||||
| behavior of a bitcoind against 1 or more other bitcoind instances. It should not be used | |||||
| to write static tests with known outcomes, since that type of test is easier to write and | |||||
| maintain using the standard BitcoinTestFramework. | |||||
| - Set the `num_nodes` variable (defined in `ComparisonTestFramework`) to start up | |||||
| 1 or more nodes. If using 1 node, then `--testbinary` can be used as a command line | |||||
| option to change the bitcoind binary used by the test. If using 2 or more nodes, | |||||
| then `--refbinary` can be optionally used to change the bitcoind that will be used | |||||
| on nodes 2 and up. | |||||
| - Implement a (generator) function called `get_tests()` which yields `TestInstance`s. | |||||
| Each `TestInstance` consists of: | |||||
| - A list of `[object, outcome, hash]` entries | |||||
| * `object` is a `CBlock`, `CTransaction`, or | |||||
| `CBlockHeader`. `CBlock`'s and `CTransaction`'s are tested for | |||||
| acceptance. `CBlockHeader`s can be used so that the test runner can deliver | |||||
| complete headers-chains when requested from the bitcoind, to allow writing | |||||
| tests where blocks can be delivered out of order but still processed by | |||||
| headers-first bitcoind's. | |||||
| * `outcome` is `True`, `False`, or `None`. If `True` | |||||
| or `False`, the tip is compared with the expected tip -- either the | |||||
| block passed in, or the hash specified as the optional 3rd entry. If | |||||
| `None` is specified, then the test will compare all the bitcoind's | |||||
| being tested to see if they all agree on what the best tip is. | |||||
| * `hash` is the block hash of the tip to compare against. Optional to | |||||
| specify; if left out then the hash of the block passed in will be used as | |||||
| the expected tip. This allows for specifying an expected tip while testing | |||||
| the handling of either invalid blocks or blocks delivered out of order, | |||||
| which complete a longer chain. | |||||
| - `sync_every_block`: `True/False`. If `False`, then all blocks | |||||
| are inv'ed together, and the test runner waits until the node receives the | |||||
| last one, and tests only the last block for tip acceptance using the | |||||
| outcome and specified tip. If `True`, then each block is tested in | |||||
| sequence and synced (this is slower when processing many blocks). | |||||
| - `sync_every_transaction`: `True/False`. Analogous to | |||||
| `sync_every_block`, except if the outcome on the last tx is "None", | |||||
| then the contents of the entire mempool are compared across all bitcoind | |||||
| connections. If `True` or `False`, then only the last tx's | |||||
| acceptance is tested against the given outcome. | |||||
| - For examples of tests written in this framework, see | |||||
| `p2p_invalid_block.py` and `feature_block.py`. | |||||
| ### test-framework modules | ### test-framework modules | ||||
| #### [test_framework/authproxy.py](test_framework/authproxy.py) | #### [test_framework/authproxy.py](test_framework/authproxy.py) | ||||
| Taken from the [python-bitcoinrpc repository](https://github.com/jgarzik/python-bitcoinrpc). | Taken from the [python-bitcoinrpc repository](https://github.com/jgarzik/python-bitcoinrpc). | ||||
| #### [test_framework/test_framework.py](test_framework/test_framework.py) | #### [test_framework/test_framework.py](test_framework/test_framework.py) | ||||
| Base class for functional tests. | Base class for functional tests. | ||||
| #### [test_framework/util.py](test_framework/util.py) | #### [test_framework/util.py](test_framework/util.py) | ||||
| Generally useful functions. | Generally useful functions. | ||||
| #### [test_framework/mininode.py](test_framework/mininode.py) | #### [test_framework/mininode.py](test_framework/mininode.py) | ||||
| Basic code to support P2P connectivity to a bitcoind. | Basic code to support P2P connectivity to a bitcoind. | ||||
| #### [test_framework/comptool.py](test_framework/comptool.py) | |||||
| Framework for comparison-tool style, P2P tests. | |||||
| #### [test_framework/script.py](test_framework/script.py) | #### [test_framework/script.py](test_framework/script.py) | ||||
| Utilities for manipulating transaction scripts (originally from python-bitcoinlib) | Utilities for manipulating transaction scripts (originally from python-bitcoinlib) | ||||
| #### [test_framework/blockstore.py](test_framework/blockstore.py) | |||||
| Implements disk-backed block and tx storage. | |||||
| #### [test_framework/key.py](test_framework/key.py) | #### [test_framework/key.py](test_framework/key.py) | ||||
| Wrapper around OpenSSL EC_Key (originally from python-bitcoinlib) | Wrapper around OpenSSL EC_Key (originally from python-bitcoinlib) | ||||
| #### [test_framework/bignum.py](test_framework/bignum.py) | #### [test_framework/bignum.py](test_framework/bignum.py) | ||||
| Helpers for script.py | Helpers for script.py | ||||
| #### [test_framework/blocktools.py](test_framework/blocktools.py) | #### [test_framework/blocktools.py](test_framework/blocktools.py) | ||||
| Helper functions for creating blocks and transactions. | Helper functions for creating blocks and transactions. | ||||