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 with clock skew on one pool node:

./runner/runc.sh -- TIME_DRIFT_POOL=1 TIME_DRIFT_SPEC='+0 x1.008' ./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

Analyzing Failures

In Claude Code, /analyze-failures [run_dir] triages a finished run (run_workdir by default, also artifacts downloaded from a CI run) and answers where a run's logs and artifacts live.

---

🧪 Running Individual Tests with Custom Binaries

1. Create the .bin directory in the repo root and add your custom cardano-cli / cardano-node / cardano-db-sync binaries there.

   ⚠️ When running in a container via runner/runc.sh, .bin entries must be statically linked binaries, or - for containers that bind-mount the host /nix store (the default when the host has /nix) - symlinks pointing directly into /nix or binaries whose dynamic dependencies all live under /nix. A NixOS container has its own /nix store, so only statically linked binaries work there.

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:

   ./dev_workdir/local_fast/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:

   ./dev_workdir/local_fast/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:

Additional for regression.sh

💡 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 local_fast. Override with TESTNET_VARIANT=<variant>, e.g. make cluster-scripts TESTNET_VARIANT=local_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.