cardano-node-tests

System and end-to-end (E2E) tests for cardano-node.

📘 Check the documentation site for full usage guides, setup instructions, and details.

---

🚀 Running Tests with GitHub Actions

Run tests easily using GitHub Actions:

1. Fork this repository.

2. Enable GitHub Actions in your fork:

   • Go to Settings ➝ Actions ➝ General ➝ Actions permissions
   • Check ✅ Allow all actions and reusable workflows

3. Navigate to the Actions tab, then choose:

   • 01 Regression tests, or
   • 02 Regression tests with db-sync, or
   • 03 Upgrade tests

4. Click Run workflow to start testing.

---

🖥️ Running Tests Locally

The preferred way is via runner/runc.sh, which builds a container image and runs tests inside it using podman or docker. If the host has /nix, it is bind-mounted into an Alpine container; otherwise a self-contained NixOS container is used — no local Nix installation required.

./runner/runc.sh ./runner/regression.sh

Run a specific test:

./runner/runc.sh -- TEST_THREADS=0 CLUSTERS_COUNT=1 PYTEST_ARGS="-k test_minting_one_token" ./runner/regression.sh

A specific Linux distro can be selected (Ubuntu, Debian, Linux Mint, or NixOS):

./runner/runc.sh --ubuntu-container=24.04 -- ./runner/regression.sh

ℹ️ Run ./runner/runc.sh without arguments to see all available options.

Alternatively, with Nix available on the host, tests can be run directly:

./runner/regression.sh

Or run the upgrade test suite:

./runner/load-gh-env.sh runner/env_nightly_upgrade CI_BYRON_CLUSTER=false ./runner/node_upgrade.sh

---

🧪 Running Individual Tests with Custom Binaries

1. Add your custom cardano-cli / cardano-node binaries to the .bin directory.

2. Run a specific test:

./runner/runc.sh -- TEST_THREADS=0 CLUSTERS_COUNT=1 PYTEST_ARGS="-k 'test_minting_and_burning_sign[asset_name-build_raw-submit_cli]'" ./runner/regression.sh

3. Clean up by removing binaries from .bin after tests complete.

ℹ️ Pro Tip: Enable full CLI command logging:

PYTEST_ARGS="... --log-level=debug" ./runner/regression.sh

---

🔁 Persistent Local Testnet for Repeated Testing

For workflows requiring repeated test runs on a persistent testnet cluster:

1. Start a Nix shell:

nix flake update --accept-flake-config --override-input cardano-node github:IntersectMBO/cardano-node/master
nix develop --accept-flake-config

2. Set up the local test environment:

make test-env

3. Activate the environment:

source ./dev_workdir/activate

4. Launch the local testnet cluster:

make start-cluster

5. Run your tests:

pytest -s -k test_minting_one_token cardano_node_tests/tests/tests_plutus
pytest -s --log-level=debug -k test_minting_one_token cardano_node_tests/tests/tests_plutus

6. Stop the testnet cluster:

make stop-cluster

ℹ️ Pro Tip: Next time, you can omit step 2 if the environment is already set up.

---

⚙️ Test Configuration Variables

You can fine-tune test runs using these environment variables:

Variable	Description
BOOTSTRAP_DIR	Bootstrap testnet directory.
CLUSTERS_COUNT	Number of clusters to launch (default: 9).
COMMAND_ERA	CLI command target era.
KEEP_CLUSTERS_RUNNING	Don't shut down clusters after tests.
MARKEXPR	Marker expression for pytest filtering.
MAX_TESTS_PER_CLUSTER	Max tests per cluster (default: 8).
NUM_POOLS	Number of stake pools (default: 3).
PORTS_BASE	Starting port number for cluster services.
SCHEDULING_LOG	Path to scheduler log output.
TESTNET_VARIANT	Name of the testnet variant to use.
UTXO_BACKEND	Backend type: mem, disk, disklmdb or empty.
MIXED_UTXO_BACKENDS	List of UTXO backends for mixed setup.
ENABLE_TX_GENERATOR	Enable tx-generator (default: false).
PROTOCOL_VERSION	Cardano protocol version to use (default: 10).
USE_GENESIS_MODE	Switch to using GenesisMode (default: false).
ALLOW_UNSTABLE_ERROR_MESSAGES	Allow tests to pass with unstable error messages.

Additional for regression.sh

Variable	Description
CARDANO_CLI_REV	cardano-cli version.
CI_BYRON_CLUSTER	Run cluster from Byron ➝ Conway (slow start).
DBSYNC_REV	cardano-db-sync version.
NODE_REV	cardano-node version (default: master).
PYTEST_ARGS	Extra options passed to pytest.
TEST_THREADS	Number of pytest workers (default: 20).

💡 Usage Examples

Run with 6 pools and mixed networking:

NUM_POOLS=6 ./runner/regression.sh

Run selective tests with filtering:

TEST_THREADS=15 PYTEST_ARGS="-k 'test_stake_pool_low_cost or test_reward_amount'" MARKEXPR="not long" ./runner/regression.sh

Run on preview testnet with specific node revision:

NODE_REV=10.6.3 BOOTSTRAP_DIR=~/tmp/preview_config/ ./runner/regression.sh

ℹ️ Pro Tip: All the examples above can be prefixed with ./runner/runc.sh -- to run inside the containerized environment.

---

💻 Local Development for Test Authors

While the setup described in Persistent Local Testnet for Repeated Testing is sufficient for most test development, test authors may require a more customizable environment, such as editable installs, different testnet variants, or multiple testnet cluster instances.

Install Nix and uv before proceeding.

Set Up Python Environment

make install

Activate Dev Environment

cd ../cardano-node
git checkout <tag>
cd ../cardano-node-tests
make update-node-bins repo=../cardano-node
source .source.dev

Validate Dev Environment

make check-dev-env

Start Development Testnet Cluster

make cluster-scripts
make start-cluster

The default cluster variant is conway_fast. Override with TESTNET_VARIANT=<variant>, e.g. make cluster-scripts TESTNET_VARIANT=conway_slow.

Keys and configs are stored under /var/tmp/cardonnay-of-$USER/state-cluster0.

Run Individual Tests

pytest -k "test_missing_tx_out or test_multiple_same_txins" cardano_node_tests
pytest -m smoke cardano_node_tests/tests/test_cli.py

Run Linters

make lint

ℹ️ Pro Tip: Run make init-lint to initialize linters and activate Git hooks.

Reinstall cardano-clusterlib in Editable Mode

make reinstall-editable repo=../cardano-clusterlib-py

⚠️ After each dependencies update, repeat the step above to retain dev mode.

Update uv Lockfile

This step is required after modifying dependencies in pyproject.toml.

make update-uv-lock

Build and Deploy Documentation

make doc

---

🤝 Contributing

• Follow the Google Python Style Guide.
• See CONTRIBUTING.md for full guidelines.