1- Regression tests of RPC interface
2- =================================
1+ Regression tests
2+ ================
33
44### [ python-bitcoinrpc] ( https://github.com/jgarzik/python-bitcoinrpc )
55Git subtree of [ https://github.com/jgarzik/python-bitcoinrpc ] ( https://github.com/jgarzik/python-bitcoinrpc ) .
@@ -12,6 +12,28 @@ Base class for new regression tests.
1212### [ test_framework/util.py] ( test_framework/util.py )
1313Generally useful functions.
1414
15+ ### [ test_framework/mininode.py] ( test_framework/mininode.py )
16+ Basic code to support p2p connectivity to a bitcoind.
17+
18+ ### [ test_framework/comptool.py] ( test_framework/comptool.py )
19+ Framework for comparison-tool style, p2p tests.
20+
21+ ### [ test_framework/script.py] ( test_framework/script.py )
22+ Utilities for manipulating transaction scripts (originally from python-bitcoinlib)
23+
24+ ### [ test_framework/blockstore.py] ( test_framework/blockstore.py )
25+ Implements disk-backed block and tx storage.
26+
27+ ### [ test_framework/key.py] ( test_framework/key.py )
28+ Wrapper around OpenSSL EC_Key (originally from python-bitcoinlib)
29+
30+ ### [ test_framework/bignum.py] ( test_framework/bignum.py )
31+ Helpers for script.py
32+
33+ ### [ test_framework/blocktools.py] ( test_framework/blocktools.py )
34+ Helper functions for creating blocks and transactions.
35+
36+
1537Notes
1638=====
1739
@@ -49,3 +71,82 @@ to recover with:
4971rm -rf cache
5072killall bitcoind
5173```
74+
75+ P2P test design notes
76+ ---------------------
77+
78+ ## Mininode
79+
80+ * ``` mininode.py ``` contains all the definitions for objects that pass
81+ over the network (``` CBlock ``` , ``` CTransaction ``` , etc, along with the network-level
82+ wrappers for them, ``` msg_block ``` , ``` msg_tx ``` , etc).
83+
84+ * P2P tests have two threads. One thread handles all network communication
85+ with the bitcoind(s) being tested (using python's asyncore package); the other
86+ implements the test logic.
87+
88+ * ``` NodeConn ``` is the class used to connect to a bitcoind. If you implement
89+ a callback class that derives from ``` NodeConnCB ``` and pass that to the
90+ ``` NodeConn ``` object, your code will receive the appropriate callbacks when
91+ events of interest arrive. NOTE: be sure to call
92+ ``` self.create_callback_map() ``` in your derived classes' ``` __init__ ```
93+ function, so that the correct mappings are set up between p2p messages and your
94+ callback functions.
95+
96+ * You can pass the same handler to multiple ``` NodeConn ``` 's if you like, or pass
97+ different ones to each -- whatever makes the most sense for your test.
98+
99+ * Call ``` NetworkThread.start() ``` after all ``` NodeConn ``` objects are created to
100+ start the networking thread. (Continue with the test logic in your existing
101+ thread.)
102+
103+ * RPC calls are available in p2p tests.
104+
105+ * Can be used to write free-form tests, where specific p2p-protocol behavior
106+ is tested. Examples: ``` p2p-accept-block.py ``` , ``` maxblocksinflight.py ``` .
107+
108+ ## Comptool
109+
110+ * Testing framework for writing tests that compare the block/tx acceptance
111+ behavior of a bitcoind against 1 or more other bitcoind instances, or against
112+ known outcomes, or both.
113+
114+ * Set the ``` num_nodes ``` variable (defined in ``` ComparisonTestFramework ``` ) to start up
115+ 1 or more nodes. If using 1 node, then ``` --testbinary ``` can be used as a command line
116+ option to change the bitcoind binary used by the test. If using 2 or more nodes,
117+ then ``` --refbinary ``` can be optionally used to change the bitcoind that will be used
118+ on nodes 2 and up.
119+
120+ * Implement a (generator) function called ``` get_tests() ``` which yields ``` TestInstance ``` s.
121+ Each ``` TestInstance ``` consists of:
122+ - a list of ``` [object, outcome, hash] ``` entries
123+ * ``` object ``` is a ``` CBlock ``` , ``` CTransaction ``` , or
124+ ``` CBlockHeader ``` . ``` CBlock ``` 's and ``` CTransaction ``` 's are tested for
125+ acceptance. ``` CBlockHeader ``` s can be used so that the test runner can deliver
126+ complete headers-chains when requested from the bitcoind, to allow writing
127+ tests where blocks can be delivered out of order but still processed by
128+ headers-first bitcoind's.
129+ * ``` outcome ``` is ``` True ``` , ``` False ``` , or ``` None ``` . If ``` True ```
130+ or ``` False ``` , the tip is compared with the expected tip -- either the
131+ block passed in, or the hash specified as the optional 3rd entry. If
132+ ``` None ``` is specified, then the test will compare all the bitcoind's
133+ being tested to see if they all agree on what the best tip is.
134+ * ``` hash ``` is the block hash of the tip to compare against. Optional to
135+ specify; if left out then the hash of the block passed in will be used as
136+ the expected tip. This allows for specifying an expected tip while testing
137+ the handling of either invalid blocks or blocks delivered out of order,
138+ which complete a longer chain.
139+ - ``` sync_every_block ``` : ``` True/False ``` . If ``` False ``` , then all blocks
140+ are inv'ed together, and the test runner waits until the node receives the
141+ last one, and tests only the last block for tip acceptance using the
142+ outcome and specified tip. If ``` True ``` , then each block is tested in
143+ sequence and synced (this is slower when processing many blocks).
144+ - ``` sync_every_transaction ``` : ``` True/False ``` . Analogous to
145+ ``` sync_every_block ``` , except if the outcome on the last tx is "None",
146+ then the contents of the entire mempool are compared across all bitcoind
147+ connections. If ``` True ``` or ``` False ``` , then only the last tx's
148+ acceptance is tested against the given outcome.
149+
150+ * For examples of tests written in this framework, see
151+ ``` invalidblockrequest.py ``` and ``` p2p-fullblocktest.py ``` .
152+
0 commit comments