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

  4. Click Run workflow to start testing.


πŸ› οΈ Running Tests Locally with Nix

  1. Install and configure Nix using the official guide.

  2. Clone this repository.

  3. Run the test suite:

    ./.github/regression.sh
    

ℹ️ NOTE: Using CI_BYRON_CLUSTER will cause the local cluster to progress from Byron ➝ Conway, which takes approximately 40 minutes.


πŸ§ͺ Running Individual Tests with Custom Binaries

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

  2. Run a specific test:

    TEST_THREADS=0 CLUSTERS_COUNT=1 PYTEST_ARGS="-k 'test_minting_and_burning_sign[asset_name-build_raw-submit_cli]'" ./.github/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" ./.github/regression.sh

πŸ” Persistent Local Cluster for Repeated Testing

For workflows requiring repeated test runs on a persistent 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. Prepare the test environment:

    source ./prepare_test_env.sh conway
    
  3. Launch the cluster:

    ./dev_workdir/conway_fast/start-cluster
    
  4. 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
    
  5. Stop the cluster:

    ./dev_workdir/conway_fast/stop-cluster
    

To reuse the same environment in another shell:

source ./dev_workdir/.source

βš™οΈ Test Configuration Variables

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

Variable

Description

SCHEDULING_LOG

Path to scheduler log output.

PYTEST_ARGS

Extra options passed to pytest.

MARKEXPR

Marker expression for pytest filtering.

TEST_THREADS

Number of pytest workers (default: 20).

MAX_TESTS_PER_CLUSTER

Max tests per cluster (default: 8).

CLUSTERS_COUNT

Number of clusters to launch (default: 9).

CLUSTER_ERA

Cluster era (default: conway).

COMMAND_ERA

CLI command target era.

NUM_POOLS

Number of stake pools (default: 3).

ENABLE_LEGACY

Use legacy networking.

MIXED_P2P

Use a mix of P2P and legacy networking.

UTXO_BACKEND

Backend type: mem or disk.

TESTNET_VARIANT

Name of the testnet variant to use.

BOOTSTRAP_DIR

Bootstrap testnet directory.

KEEP_CLUSTERS_RUNNING

Don’t shut down clusters after tests.

PORTS_BASE

Starting port number for cluster services.

▢️ Additional for regression.sh

Variable

Description

CI_BYRON_CLUSTER

Run cluster from Byron ➝ Conway (slow).

NODE_REV

cardano-node version (default: master).

DBSYNC_REV

cardano-db-sync version.

CARDANO_CLI_REV

cardano-cli version.

PLUTUS_APPS_REV

plutus-apps version (default: main).

πŸ’‘ Usage Examples

Run with 6 pools and mixed networking:

NUM_POOLS=6 MIXED_P2P=1 ./.github/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" ./.github/regression.sh

Run on preview testnet with specific node revision:

NODE_REV=10.4.1 BOOTSTRAP_DIR=~/tmp/preview_config/ ./.github/regression.sh

πŸ’» Local Development for Test Authors

Install Nix and Poetry before proceeding.

🐍 Set Up Python Environment

make install

🧱 Start Development Cluster

cd ../cardano-node
git checkout <tag>
nix develop .#devops
/bin/bash --login  # fresh shell needed
cd ../cardano-node-tests
source "$(poetry env info --path)"/bin/activate
export PYTHONPATH="$(echo $VIRTUAL_ENV/lib/python3*/site-packages):$PYTHONPATH"
export CARDANO_NODE_SOCKET_PATH="$PWD/dev_workdir/state-cluster0/bft1.socket" DEV_CLUSTER_RUNNING=1
mkdir -p "${CARDANO_NODE_SOCKET_PATH%/*}"
prepare-cluster-scripts -c -d dev_workdir/conway_fast -t conway_fast
./dev_workdir/conway_fast/start-cluster

Keys and configs are stored under ./dev_workdir/state-cluster0.

βœ… Validate Environment

make check_dev_env

πŸ§ͺ Run Individual Tests

pytest -k "test_name1 or test_name2" cardano_node_tests
pytest -m "not long" cardano_node_tests
pytest -m smoke cardano_node_tests/tests/test_governance.py

🧹 Run Linters

source "$(poetry env info --path)"/bin/activate
make lint

🧰 Use cardano-clusterlib in Dev Mode

source "$(poetry env info --path)"/bin/activate
make install
pip uninstall cardano-clusterlib
cd ../cardano-clusterlib-py
pip install -e . --config-settings editable_mode=compat
cd -
python -c 'from cardano_clusterlib import clusterlib_klass; print(clusterlib_klass.__file__)'

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

πŸ“¦ Update Poetry Dependencies

./poetry_update_deps.sh

πŸ“š Build Documentation

make doc

🀝 Contributing