The young person's guide to the test_framework #10612

  33 | -Running tests locally
  34 | -=====================
  35 | +#### Running the tests
  36 |  
  37 | -Build for your system first. Be sure to enable wallet, utils and daemon when you configure. Tests will not run otherwise.
  38 | +individual tests can be run by directly calling the test script, eg:

---

 197 | +            getdata_request.inv.append(CInv(2, block))
 198 | +            node2.send_message(getdata_request)
 199 | +
 200 | +        # wait_until() will loop until a predicate condition is met. Use it to test properties of the
 201 | +        # ConnNodeCB objects.
 202 | +        assert wait_until(lambda: sorted(blocks) == sorted(list(node2.block_receive_map.keys())), timeout=5)

---

 147 | +        # node object. Instead there's some __getattr__() magic going on under
 148 | +        # the covers to dispatch unrecognised attribute calls to the RPC
 149 | +        # interface.
 150 | +
 151 | +        # Logs are nice. Do plenty of them. They can be used in place of comments for
 152 | +        # breaking the test into sub-sections.

---

 154 | +
 155 | +- when run through the test_runner harness, *all* logs are written to
 156 | +  `test_framework.log` and no logs are output to the console.
 157 | +- when run directly, *all* logs are written to `test_framework.log` and INFO
 158 | +  level and above are output to the console.
 159 | +- when run on Travis, no logs are output to the console. However, if a test

---

  99 | +a callback class that derives from `NodeConnCB` and pass that to the
 100 | +`NodeConn` object, your code will receive the appropriate callbacks when
 101 |  events of interest arrive.
 102 |  
 103 | -* You can pass the same handler to multiple ```NodeConn```'s if you like, or pass
 104 | +- You can pass the same handler to multiple `NodeConn`'s if you like, or pass

---

 104 | +        self.setup_nodes()
 105 | +
 106 | +        # In this test, we're not connecting node2 to node0 or node1. Calls to
 107 | +        # sync_all() should not include node2, since we're not expecting it to
 108 | +        # sync.
 109 | +        connect_nodes_bi(self.nodes, 0, 1)

---

 137 | +        NetworkThread().start()
 138 | +        # wait_for_verack ensures that the p2p connection is fully up.
 139 | +        node0.wait_for_verack()
 140 | +
 141 | +        # Generating a block on one of the nodes will get us out of IBD
 142 | +        blocks = [int(self.nodes[0].generate(nblocks=1)[0], 16)]

---

 171 | +combine_logs.py -c <test data directory> | less -r
 172 | +```
 173 | +
 174 | +will pipe the colorized logs from the test into less.
 175 | +
 176 | +Use --tracerpc to trace out all the RPC calls and responses to the console. For

---

  73 |  
  74 | -P2P test design notes
  75 | ----------------------
  76 | +- `/src/rpc/*` for RPCs
  77 | +- `/src/wallet/rpc*` for wallet RPCs
  78 | +- `ProcessMessage()` in `/sfrc/net_processing.cpp` for parsing p2p messages

---

 152 | @@ -153,6 +153,7 @@
 153 |      # These are python files that live in the functional tests directory, but are not test scripts.
 154 |      "combine_logs.py",
 155 |      "create_cache.py",
 156 | +    "example_test.py",

---

 196 | +            getdata_request = msg_getdata()
 197 | +            getdata_request.inv.append(CInv(2, block))
 198 | +            node2.send_message(getdata_request)
 199 | +
 200 | +        # wait_until() will loop until a predicate condition is met. Use it to test properties of the
 201 | +        # ConnNodeCB objects.

---

  96 | -                        (default: ../../src)
  97 | -  --tmpdir=TMPDIR       Root directory for datadirs
  98 | -  --tracerpc            Print out all RPC calls as they are made
  99 | -  --coveragedir=COVERAGEDIR
 100 | -                        Write tested RPC commands into this directory
 101 | +The p2p and RPC ports used by the bitcoind nodes-under-test are chosen to make

---

 109 | +bitcoind process running when the tests are started.
 110 | +
 111 | +If there are zombie bitcoind processes after test failure, you can kill them by running:
 112 | +
 113 | +```bash
 114 | +killall bitcoind

---

 184 | +##### Attaching a debugger
 185 | +
 186 | +A python debugger can be attached to tests at any point. Just add the line:
 187 | +
 188 | +```py
 189 | +import pdb; pdb.set_trace()

---

  64 | +  arguments instead of positional arguments to make the intent of the call
  65 | +  clear to readers.
  66 |  
  67 | -### [test_framework/blocktools.py](test_framework/blocktools.py)
  68 | -Helper functions for creating blocks and transactions.
  69 | +#### RPC and p2p definitions

---