Skip to content
Skills Library
Programming · Testing

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.

Licence
MIT
Last repository change
21.10.2026

Assessment and security

95/ 100Class: good
Format20 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 21.10.2026, without references to retired models or APIs.

Licence

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

  1. Architecture
  2. Components
  3. Key methods
  4. Use cases
  5. Compared
  6. Common issues
  7. See also
Original SKILL.md headings · 112 lines, 552 words
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.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.