bitcoin-testing-core-test-framework
/bitcoin-testing-core-test-framework
Bitcoin Core's Python functional test framework: BitcoinTestFramework, TestNode, setup_network, sync_blocks, descriptors helpers, miniscript helpers. USE WHEN: writing tests against bitcoind, contributing to Bitcoin Core, testing custom mempool policies.
- Author
- claude-dev-suite ↗
- Repository
- claude-dev-suite ↗
- Licence
- MIT
- Last repository change
- 21.10.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 21.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Bitcoin Core's Python functional test framework: BitcoinTestFramework, TestNode, setup_network, sync_blocks, descriptors helpers, miniscript helpers. USE WHEN: writing tests against bitcoind, contributing to Bitcoin Core, testing custom mempool policies.
Original author description
Bitcoin Core's Python functional test framework: BitcoinTestFramework, TestNode, setup_network, sync_blocks, descriptors helpers, miniscript helpers. USE WHEN: writing tests against bitcoind, contributing to Bitcoin Core, testing custom mempool policies.
How it works
- Architecture
- Components
- Key methods
- Use cases
- Compared
- Common issues
- See also
SKILL.md preview
---
name: bitcoin-testing-core-test-framework
description: |
Bitcoin Core's Python functional test framework: BitcoinTestFramework,
TestNode, setup_network, sync_blocks, descriptors helpers, miniscript
helpers.
USE WHEN: writing tests against bitcoind, contributing to Bitcoin
Core, testing custom mempool policies.
allowed-tools: Read, Grep, Glob
---
# Bitcoin Core Test Framework
Python framework used by Bitcoin Core's own test suite. Located in
`test/functional/` of the bitcoin/bitcoin repo.
## Architecture
```python
from test_framework.test_framework import BitcoinTestFramework
class MyTest(BitcoinTestFramework):
def set_test_params(self):
self.num_nodes = 2
self.extra_args = [["-fallbackfee=0.00001"], []]
def run_test(self):
node0 = self.nodes[0]
node1 = self.nodes[1]
addr = node0.getnewaddress()
# Mining goes through the framework helper, generator node first;
# it syncs all nodes afterwards.
self.generatetoaddress(node0, 101, addr)
# ...
if __name__ == "__main__":
MyTest().main()
```
Run. Since the CMake migration in Bitcoin Core 29.0 (April 2025) the
runnable tests are configured into the build directory:
```bash
build/test/functional/feature_my_test.py
build/test/functional/test_runner.py --jobs=8 feature_my_test.py
```
## Components
- `BitcoinTestFramework` — base class.
- `TestNode` — wraps bitcoind + RPC.
- `MiniWallet` — minimal in-test wallet (no full descriptor wallet).
- `messages.py` — wire format (CTxIn, CTxOut, CTransaction).
- `script.py` — Script construction (CScript, opcodes).
- `descriptors.py` — descriptor parsing helpers.
- `key.py` — secp256k1 helpers.
- `wallet_util.py` — wallet helpers.
- `psbt.py` — PSBT utilities.
## Key methods
Unless noted, these are methods on the framework, not on `TestNode`.
- `generate(generator, n, sync_fun=None)` — mine n blocks with the
`generator` node, then `sync_fun()` if a callable was passed, else
`sync_all()`. Any callable substitutes for the sync;
`sync_fun=self.no_op` is the idiom for skipping it.
- `generatetoaddress(generator, n, address)`,
`generateblock(generator, ...)`,
`generatetodescriptor(generator, ...)` — same generator-first shape.
- `sync_blocks(nodes=None, wait=1, timeout=60)` — wait for tips to match.
- `sync_mempools(nodes=None, wait=1, timeout=60)` — wait for mempool sync.
- `sync_all(nodes=None)` — both of the above.
- `connect_nodes(a, b)` / `disconnect_nodes(a, b)` — manage peers.
- `restart_node(i, extra_args=)` — restart with new args.
- `wait_until(test_function, timeout=60, check_interval=0.05)` — poll
until True. `TestNode` carries a method of the same name and
signature, scoped to that one node.
Do not call the mining RPCs on a node directly. Since Bitcoin Core 23.0
(April 2022) `node.generatetoaddress()`, `node.generateblock()` and
`node.generatetodescriptor()` have been guarded by a keyword-only
argument that only the framework helpers pass; Bitcoin Core 29.0
(April 2025) renamed that guard from `invalid_call` to
`called_by_framework` and attached the message "Direct call of this
mining RPC is discouraged". `node.generate()` has no guard of its own —
it dispatches to `generatetoaddress`, so a direct call fails with
`TypeError` for the missing keyword-only argument instead.
## Use cases
- **Bitcoin Core PR contributions**: each new feature needs a
functional test.
- **Custom mempool policy testing**.
- **Reproducing bugs** with full bitcoind behaviour.
- **Soft fork testing** on signet.
## Compared
| Aspect | Core Test Framework | Polar | Nigiri |
|--------|---------------------|-------|--------|
| Granularity | finest (per-node, per-msg) | coarser (UI-driven) | medium |
| Speed | fast (in-process) | slow (Docker) | medium |
| LN testing | via add-ons | primary | optional |
| Use case | Core development | Lightning dev | Stack dev |
## Common issues
- **Sync issues** when nodes have very different chain state — there is
no force flag; the `self.generate*` helpers already `sync_all()`. If a
sync still times out, raise `sync_blocks(timeout=...)` (default 60s,
multiplied by `--timeout-factor`) or pass `sync_fun=self.no_op` and
sync explicitly at a point where the tips can actually converge.
- **Mocktime** confusing if not set explicitly — chain time can lag
real time during long runs.
- **Subprocess port conflicts** if multiple test runs overlap.
## See also
- [regtest/SKILL.md](../regtest/SKILL.md)
- [fuzz/SKILL.md](../fuzz/SKILL.md)
- [property-based/SKILL.md](../property-based/SKILL.md)
Versions
The database has no other skills named bitcoin-testing-core-test-framework.
Database snapshot: 13.11.2026 · package version beba7e705a03 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 95bitcoin-libraries-corepc
corepc: the rust-bitcoin org's Bitcoin Core JSON-RPC stack. `corepc-types` (per-Core-version response types + version-agnostic `model` types), `corepc-client` (blocking/async test client), `bitcoind` (spin up regtest nodes for integration tests). USE WHEN: talking to bitcoind… - 95bitcoin-core-rpc
Bitcoin Core JSON-RPC interface: authentication (cookie, rpcauth), wallet vs node RPCs, common verbs (getblockchaininfo, getrawtransaction, scantxoutset, importdescriptors, walletprocesspsbt, submitpackage, testmempoolaccept), error handling. USE WHEN: scripting bitcoind,… - 100init-tests
Scaffold test infrastructure for any project. Sets up the test framework, directory structure, fixtures, helpers, and initial test stubs. Supports Vitest, Jest, Go testing, pytest, and more. Use when the user says "init tests", "set up testing", "add test infrastructure",… - 95blockchain-bitcoin
Use this skill when asked about Bitcoin internals, Bitcoin Core, Bitcoin Script, Taproot, mining, Proof of Work, Lightning Network, BIP standards, Ordinals, BRC-20, Runes, Bitcoin L2s (Stacks, RSK, Babylon), and Bitcoin protocol development. Languages: C++, Rust, Python,… - 90testing-python
Stratégie de Tests Python 3.14+. Use when writing tests, reviewing test coverage, or setting up testing. - 100python-testing
Guidelines for writing and running tests in the Agent Framework Python codebase. Use this when creating, modifying, or running tests.