Bitcoin Regtest Mode: Development and Testing Guide

What is Regtest?

Regtest (regression test) mode creates a completely local, private blockchain that only exists on your machine. Unlike testnet (which is a public test network) or signet (a centrally-signed test network), regtest gives you total control: you mine blocks instantly, there's no waiting for confirmations, and you start with a clean chain every time.

Regtest is the standard development environment for Bitcoin applications. It lets you test transaction flows, wallet operations, and edge cases without spending real Bitcoin or waiting for block confirmations.

Setting Up Regtest

Start Bitcoin Core in regtest mode:

bitcoind -regtest -daemon

Or add regtest=1 to your bitcoin.conf. The regtest data directory is separate from mainnet, so your real wallet and blockchain data are untouched.

Regtest starts with an empty blockchain — just the genesis block. There are no pre-existing transactions, no difficulty, and no peers. You control everything.

You can run multiple regtest nodes on the same machine by using different data directories and ports, which is useful for testing peer-to-peer scenarios.

Mining Blocks

In regtest, mining is instant — no proof-of-work difficulty. Use generatetoaddress to mine blocks and collect the coinbase reward:

bitcoin-cli -regtest generatetoaddress 101 $(bitcoin-cli -regtest getnewaddress)

This mines 101 blocks. Why 101? Coinbase outputs require 100 confirmations before they can be spent. Mining 101 blocks gives you one mature, spendable coinbase reward (50 BTC in regtest).

For more advanced testing, generateblock lets you mine a block containing specific transactions. This gives you precise control over which transactions confirm and in what order — essential for testing time-sensitive protocols.

Creating Test Scenarios

With regtest, you can simulate any scenario:

Basic payments: use sendtoaddress to send BTC between wallets, then mine a block to confirm.

Unconfirmed transactions: send a transaction but don't mine a block — it stays in the mempool for testing zero-confirmation handling.

Double spends: create two conflicting transactions spending the same UTXO and test how your application handles them.

Reorgs: mine a competing chain fork by connecting two separate regtest nodes, letting them mine independently, then connecting them. The shorter chain gets reorganized.

Fee bumping: send a low-fee transaction, then use bumpfee or RBF to replace it before mining.

Multisig workflows: create multisig addresses and practice the full PSBT signing flow without risking real funds.

Development Workflow Tips

Script your setup — write a shell script or Python script that starts regtest, creates wallets, mines initial blocks, and sets up your test state. Run it fresh at the start of each test session for clean reproducibility.

Use named wallets — createwallet lets you create descriptive wallets like 'alice', 'bob', and 'merchant' for testing multi-party scenarios.

Reset quickly — to start fresh, stop bitcoind, delete the regtest data directory, and restart. No multi-gigabyte blockchain to re-download.

Automate testing — combine regtest with your test framework. Mine blocks programmatically between test steps to control confirmation timing. The deterministic nature of regtest makes tests reproducible.

Pair with bitcoin-cli — for quick manual testing, bitcoin-cli -regtest gives you direct RPC access. Keep a terminal open with it for exploring state while your application runs.