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:
Fork this repository.
Enable GitHub Actions in your fork:
Go to
Settings
βActions
βGeneral
βActions permissions
Check β
Allow all actions and reusable workflows
Navigate to the
Actions
tab, then choose:01 Regression tests
, or02 Regression tests with db-sync
Click
Run workflow
to start testing.
π οΈ Running Tests Locally with Nixο
Install and configure Nix using the official guide.
Clone this repository.
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ο
Add your custom
cardano-cli
/cardano-node
binaries to the.bin
directory.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
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:
Start a Nix shell:
nix flake update --accept-flake-config --override-input cardano-node github:IntersectMBO/cardano-node/master nix develop --accept-flake-config
Prepare the test environment:
source ./prepare_test_env.sh conway
Launch the cluster:
./dev_workdir/conway_fast/start-cluster
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
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 |
---|---|
|
Path to scheduler log output. |
|
Extra options passed to pytest. |
|
Marker expression for pytest filtering. |
|
Number of pytest workers (default: 20). |
|
Max tests per cluster (default: 8). |
|
Number of clusters to launch (default: 9). |
|
Cluster era (default: |
|
CLI command target era. |
|
Number of stake pools (default: 3). |
|
Use legacy networking. |
|
Use a mix of P2P and legacy networking. |
|
Backend type: |
|
Name of the testnet variant to use. |
|
Bootstrap testnet directory. |
|
Donβt shut down clusters after tests. |
|
Starting port number for cluster services. |
βΆοΈ Additional for regression.sh
ο
Variable |
Description |
---|---|
|
Run cluster from Byron β Conway (slow). |
|
|
|
|
|
|
|
|
π‘ 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
π€ Contributingο
Run
pre-commit install
to activate Git hooks.Follow the Google Python Style Guide.
Use Ruff (via
pre-commit
) for formatting.See CONTRIBUTING.md for full guidelines.