{"id":19783654,"url":"https://github.com/intersectmbo/cardano-node-tests","last_synced_at":"2025-04-06T13:11:48.695Z","repository":{"id":37024379,"uuid":"286954688","full_name":"IntersectMBO/cardano-node-tests","owner":"IntersectMBO","description":"System and end-to-end (E2E) tests for cardano-node.","archived":false,"fork":false,"pushed_at":"2025-03-31T16:38:08.000Z","size":18581,"stargazers_count":57,"open_issues_count":47,"forks_count":30,"subscribers_count":28,"default_branch":"master","last_synced_at":"2025-04-01T17:14:39.238Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://tests.cardano.intersectmbo.org/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/IntersectMBO.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE-OF-CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-08-12T08:06:11.000Z","updated_at":"2025-03-31T16:38:11.000Z","dependencies_parsed_at":"2023-10-11T13:42:07.413Z","dependency_job_id":"a6dff7bf-c0f2-4b4f-9db5-305f96804379","html_url":"https://github.com/IntersectMBO/cardano-node-tests","commit_stats":null,"previous_names":["intersectmbo/cardano-node-tests","input-output-hk/cardano-node-tests"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IntersectMBO%2Fcardano-node-tests","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IntersectMBO%2Fcardano-node-tests/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IntersectMBO%2Fcardano-node-tests/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IntersectMBO%2Fcardano-node-tests/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/IntersectMBO","download_url":"https://codeload.github.com/IntersectMBO/cardano-node-tests/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247485290,"owners_count":20946398,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-12T06:08:55.398Z","updated_at":"2025-04-06T13:11:48.672Z","avatar_url":"https://github.com/IntersectMBO.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# README for cardano-node-tests\n\n[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)\n\nSystem and end-to-end (E2E) tests for cardano-node.\n\nCheck this [documentation](https://tests.cardano.intersectmbo.org) for more details.\n\n## Running tests using GitHub Actions\n\nThe easiest way to run the tests is by using GitHub Actions.\n\n1. Fork this repository.\n1. Enable GitHub Actions in your fork (\"Settings\" / \"Actions\" / \"General\" / \"Actions permissions\", check \"Allow all actions and reusable workflows\").\n1. Go to \"Actions\", select \"01 Regression tests\" (or \"02 Regression tests with db-sync\").\n1. Select \"Run workflow\".\n\n![Run workflow](https://user-images.githubusercontent.com/2352619/209117914-ef3afb38-2b8b-4a4f-a03f-c9b52bccc5ba.png)\n\n## Running tests using Nix\n\n1. Install and configure Nix by following the [cardano-node documentation](https://github.com/IntersectMBO/cardano-node/blob/master/doc/getting-started/building-the-node-using-nix.md).\n\n1. Clone this repository.\n\n1. Run the tests:\n\n    ```sh\n    ./.github/regression.sh\n    ```\n\n---\n\n**NOTE** \u003c!-- markdownlint-disable-line MD036 --\u003e\n\nWhen using `CI_BYRON_CLUSTER`, it takes approximately 30 minutes for the local cluster instance to progress from Byron to Conway. If it seems that the tests are stuck, they are likely just waiting for the local cluster instances to fully start.\n\n---\n\n## Running individual tests on a persistent local cluster using Nix\n\nSometimes it is useful to run individual tests and keep the local cluster running between test runs.\n\n1. Run a Nix shell that has all the needed dependencies:\n\n    ```sh\n    nix flake update --accept-flake-config --override-input cardano-node \"github:IntersectMBO/cardano-node/master\"  # change `master` to the revision you want\n    nix develop --accept-flake-config\n    ```\n\n1. Prepare the testing environment:\n\n    ```sh\n    source ./prepare_test_env.sh conway\n    ```\n\n1. Start the cluster instance:\n\n    ```sh\n    ./dev_workdir/conway_fast/start-cluster\n    ```\n\n1. Run some tests:\n\n    ```sh\n    pytest -s -k test_minting_one_token cardano_node_tests/tests/tests_plutus\n    # or run some tests and see all the executed `cardano-cli` commands\n    pytest -s --log-level=debug -k test_minting_one_token cardano_node_tests/tests/tests_plutus\n    ```\n\n1. Stop the cluster instance:\n\n    ```sh\n    ./dev_workdir/conway_fast/stop-cluster\n    ```\n\nTo reuse the existing testing environment in another Nix shell, source the `.source` file that was generated during setup:\n\n```sh\nsource ./dev_workdir/.source\n```\n\n## Variables for configuring test runs\n\nTest execution can be configured using environment variables.\n\n* `SCHEDULING_LOG` – specifies the path to the file where log messages for tests and the cluster instance scheduler are stored.\n* `PYTEST_ARGS` – specifies additional arguments for pytest (default: unset).\n* `MARKEXPR` – specifies marker expression for pytest (default: unset).\n* `TEST_THREADS` – specifies the number of pytest workers (default: 20).\n* `CLUSTERS_COUNT` – number of cluster instances that will be started (default: 9).\n* `CLUSTER_ERA` – cluster era for Cardano node – used for selecting the correct cluster start script (default: conway).\n* `COMMAND_ERA` – era for cardano-cli commands – can be used for creating Shelley-era (Allegra-era, ...) transactions (default: unset).\n* `NUM_POOLS` – number of stake pools created in each cluster instance (default: 3).\n* `ENABLE_LEGACY` – use legacy networking instead of the default P2P networking (default: unset).\n* `MIXED_P2P` – use a mix of P2P and legacy networking; half of the stake pools using legacy and the other half P2P (default: unset).\n* `UTXO_BACKEND` – 'mem' or 'disk', default is 'mem' (or legacy) backend if unset (default: unset).\n* `SCRIPTS_DIRNAME` – path to a directory with local cluster start/stop scripts and configuration files (default: unset).\n* `BOOTSTRAP_DIR` – path to a bootstrap directory for the given testnet (genesis files, config files, faucet data) (default: unset).\n* `KEEP_CLUSTERS_RUNNING` – don't stop cluster instances after the test run is finished.\n  (WARNING: this implies interactive behavior when running tests using the `./.github/regression.sh` script).\n* `PORTS_BASE` – base port number for the range of ports used by cluster instances (default: 23000).\n\nWhen running tests using the `./.github/regression.sh` script, you can also use:\n\n* `CI_BYRON_CLUSTER` – start local cluster in Byron era, and progress to later eras by HFs (same effect as `SCRIPTS_DIRNAME=conway`).\n* `NODE_REV` – revision of `cardano-node` (default: 'master').\n* `DBSYNC_REV` – revision of `cardano-db-sync` (default: unset; db-sync is not used by default).\n* `CARDANO_CLI_REV` – revision of `cardano-cli` (default: unset; cardano-cli bundled in cardano-node repo is used by default).\n* `PLUTUS_APPS_REV` – revision of `plutus-apps` (default: 'main').\n\nFor example:\n\n* Running tests on local cluster instances, each with 6 stake pools and a mix of P2P and legacy networking:\n\n    ```sh\n    NUM_POOLS=6 MIXED_P2P=1 ./.github/regression.sh\n    ```\n\n* Running tests on local cluster instances using 15 pytest workers, Conway cluster era, cluster scripts that start a cluster directly in Conway era, and selecting only tests without 'long' marker that also match the given `-k` pytest argument:\n\n    ```sh\n    TEST_THREADS=15 CLUSTER_ERA=conway SCRIPTS_DIRNAME=conway_fast PYTEST_ARGS=\"-k 'test_stake_pool_low_cost or test_reward_amount'\" MARKEXPR=\"not long\" ./.github/regression.sh\n    ```\n\n* Running tests on Shelley-qa testnet with '8.0.0' release of `cardano-node`:\n\n    ```sh\n    NODE_REV=8.0.0 BOOTSTRAP_DIR=~/tmp/shelley_qa_config/ ./.github/regression.sh\n    ```\n\n## Local usage for test development (useful only for test developers)\n\nInstall and configure Nix by following the [cardano-node documentation](https://github.com/IntersectMBO/cardano-node/blob/master/doc/getting-started/building-the-node-using-nix.md).\nInstall and configure Poetry by following the [Poetry documentation](https://python-poetry.org/docs/#installation).\n\n### Preparing Python virtual environment\n\nCreate a Python virtual environment and install this package together with development requirements:\n\n```sh\nmake install\n```\n\n### Running development cluster\n\nWhen running tests, the testing framework starts and stops cluster instances as needed. That is not ideal for test development, as starting a cluster instance can take up to several epochs (to get from Byron to Conway). To keep the Cardano cluster running between test runs, start it in 'development mode':\n\n1. Change directory to 'cardano-node' repository:\n\n    ```sh\n    cd ../cardano-node\n    ```\n\n1. Update and checkout the desired commit/tag:\n\n    ```sh\n    git checkout master\n    git pull origin master\n    git fetch --all --tags\n    git checkout tags/\u003ctag\u003e\n    ```\n\n1. Launch the devops shell:\n\n    ```sh\n    nix develop .#devops\n    ```\n\n1. Run a fresh login shell on top of the current Nix shell (to get the correct environment variables):\n\n    ```sh\n    /bin/bash --login\n    ```\n\n1. Change directory back to 'cardano-node-tests' repository:\n\n    ```sh\n    cd ../cardano-node-tests\n    ```\n\n1. Activate the virtual environment:\n\n    ```sh\n    source \"$(poetry env info --path)\"/bin/activate\n    ```\n\n1. Add the virtual environment to `PYTHONPATH`:\n\n    ```sh\n    export PYTHONPATH=\"$(echo $VIRTUAL_ENV/lib/python3*/site-packages)\":$PYTHONPATH\n    ```\n\n1. Set environment variables:\n\n    ```sh\n    export CARDANO_NODE_SOCKET_PATH=\"$PWD/dev_workdir/state-cluster0/bft1.socket\" DEV_CLUSTER_RUNNING=1\n    mkdir -p \"${CARDANO_NODE_SOCKET_PATH%/*}\"\n    ```\n\n1. Prepare cluster scripts for starting the local cluster directly in Conway era:\n\n    ```sh\n    prepare-cluster-scripts -c -d dev_workdir/conway_fast -s cardano_node_tests/cluster_scripts/conway_fast/\n    ```\n\n1. Start the cluster instance in development mode:\n\n    ```sh\n    ./dev_workdir/conway_fast/start-cluster\n    ```\n\nAfter the cluster starts, keys and configuration files are available in the `./dev_workdir/state-cluster0` directory. The pool-related files and keys are located in the `nodes` subdirectory, genesis keys in the `shelley` and `byron` subdirectories, and payment address with initial funds and related keys in the `byron` subdirectory. The local faucet address and related key files are stored in the `addrs_data` subdirectory.\n\n### Restarting development cluster\n\nTo restart the running cluster (e.g., after upgrading `cardano-node` and `cardano-cli` binaries), run:\n\n```sh\n./scripts/restart_dev_cluster.sh\n```\n\n---\n\n**NOTE** \u003c!-- markdownlint-disable-line MD036 --\u003e\n\nRestarting the running development cluster is useful mainly when using the \"conway\" start scripts (not the \"conway_fast\" version). It takes approximately 30 minutes for the local cluster instance to progress from Byron to Conway. Starting the local cluster using the \"conway_fast\" version takes less than 1 minute.\n\n---\n\n### Checking the development environment\n\nTo check that the development environment was correctly set up, run the `make check_dev_env` script.\n\n```text\n$ make check_dev_env\n'cardano-node' available: ✔\n'cardano-cli' available: ✔\n'python' available: ✔\n'pytest' available: ✔\n'nix-shell' available: ✔\n'jq' available: ✔\n'supervisord' available: ✔\n'supervisorctl' available: ✔\n'bech32' available: ✔\ninside nix shell: ✔\nin repo root: ✔\nDEV cluster: ✔\npython works: ✔\nin python venv: ✔\nvenv in PYTHONPATH: ✔\ncardano-node-tests installed: ✔\npytest works: ✔\nsame version of node and cli: ✔\nsocket path set: ✔\nsocket path correct: ✔\nsocket path exists: ✔\ncluster era: default\ncommand era: latest\nusing dbsync (optional): ✔\ndbsync available: ✔\n'psql' available: ✔\nP2P network (optional): -\n```\n\n### Running individual tests\n\nExample:\n\n```sh\npytest -k \"test_name1 or test_name2\" cardano_node_tests\npytest -m \"not long\" cardano_node_tests\npytest -m smoke cardano_node_tests/tests/test_governance.py\n```\n\n### Running linters\n\nIt is sufficient to activate the Python virtual environment before running linters; a development cluster is not needed:\n\n1. Activate the virtual environment:\n\n    ```sh\n    source \"$(poetry env info --path)\"/bin/activate\n    ```\n\n1. Run linters:\n\n    ```sh\n    make lint\n    ```\n\n### Installing `cardano-clusterlib` in development mode\n\nSometimes it is useful to test local changes made to [cardano-clusterlib](https://github.com/IntersectMBO/cardano-clusterlib-py).\nTo install cardano-clusterlib in development mode:\n\n1. Activate the virtual environment:\n\n    ```sh\n    source \"$(poetry env info --path)\"/bin/activate\n    ```\n\n1. Update the virtual environment (answer 'y' to the question \"Install into the current virtual env? [y/N]\"):\n\n    ```sh\n    make install\n    ```\n\n1. Uninstall `cardano-clusterlib` installed by Poetry:\n\n    ```sh\n    pip uninstall cardano-clusterlib\n    ```\n\n1. Change directory to 'cardano-clusterlib-py' repository:\n\n    ```sh\n    cd ../cardano-clusterlib-py\n    ```\n\n1. Install `cardano-clusterlib` in development mode:\n\n    ```sh\n    pip install -e . --config-settings editable_mode=compat\n    ```\n\n1. Change directory back to 'cardano-node-tests' repository:\n\n    ```sh\n    cd -\n    ```\n\n1. Check that you are really using cardano-clusterlib files from your local repository:\n\n    ```sh\n    python -c 'from cardano_clusterlib import clusterlib_klass; print(clusterlib_klass.__file__)'\n    ```\n\nNote that after you run `poetry install` (e.g., through running `make install`), Poetry will reinstall `cardano-clusterlib`. If you want to keep using cardano-clusterlib in development mode, you'll need to repeat the steps above.\n\n### Updating dependencies using Poetry\n\nEdit `pyproject.toml` and run:\n\n```sh\n./poetry_update_deps.sh\n```\n\n### Building documentation\n\nBuild and deploy documentation:\n\n```sh\nmake doc\n```\n\n## Contributing\n\nInstall this package and its dependencies as described above.\n\nRun `pre-commit install` to set up the Git hook scripts that will check your changes before every commit. Alternatively, run `make lint` manually before pushing your changes.\n\nFollow the [Google Python Style Guide](https://google.github.io/styleguide/pyguide.html), with the exception that formatting is handled automatically by [Ruff](https://github.com/astral-sh/ruff) (through the `pre-commit` command).\n\nSee the [CONTRIBUTING](https://github.com/IntersectMBO/cardano-node-tests/blob/master/CONTRIBUTING.md) document for more details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fintersectmbo%2Fcardano-node-tests","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fintersectmbo%2Fcardano-node-tests","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fintersectmbo%2Fcardano-node-tests/lists"}