1
- Regression tests of RPC interface
2
- =================================
1
+ Regression tests
2
+ ================
3
3
4
4
### [ python-bitcoinrpc] ( https://github.com/jgarzik/python-bitcoinrpc )
5
5
Git subtree of [ https://github.com/jgarzik/python-bitcoinrpc ] ( https://github.com/jgarzik/python-bitcoinrpc ) .
@@ -12,6 +12,28 @@ Base class for new regression tests.
12
12
### [ test_framework/util.py] ( test_framework/util.py )
13
13
Generally useful functions.
14
14
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
+
15
37
Notes
16
38
=====
17
39
@@ -49,3 +71,82 @@ to recover with:
49
71
rm -rf cache
50
72
killall bitcoind
51
73
```
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