Differential D4002 Diff 11099 doc/functional-tests.md

Changeset 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)			#### [test_framework/comptool.py](test_framework/comptool.py)
	FabienUnsubmitted Not Done Inline Actions Kill'em all ! Fabien: Kill'em all !
	Framework for comparison-tool style, P2P tests.			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)			#### [test_framework/blockstore.py](test_framework/blockstore.py)
	FabienUnsubmitted Not Done Inline Actions Kill'em all ! Fabien: Kill'em all !
	Implements disk-backed block and tx storage.			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.