/cardano-node-tests

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

Primary LanguagePythonApache License 2.0Apache-2.0

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
  1. 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
  1. Prepare the test environment:
source ./prepare_test_env.sh conway
  1. Launch the cluster:
./dev_workdir/conway_fast/start-cluster
  1. 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
  1. 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.5.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

🔧 Activate Dev Environment

cd ../cardano-node
git checkout <tag>
nix develop .#devops
/bin/bash --login  # fresh shell needed
cd ../cardano-node-tests
source .source.dev

🧱 Start Development Cluster

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

🧰 Reinstall cardano-clusterlib in Editable Mode

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

🧪 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

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

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

📦 Update Poetry Dependencies

./poetry_update_deps.sh

📚 Build Documentation

make doc

🤝 Contributing