cardano-node-tests

Ruff

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).

CLUSTER_ERA

Cluster era (default: conway).

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