{"id":13479023,"url":"https://github.com/paritytech/zombienet","last_synced_at":"2025-05-15T06:03:00.544Z","repository":{"id":37004587,"uuid":"409639597","full_name":"paritytech/zombienet","owner":"paritytech","description":"A cli tool to easily spawn ephemeral Polkadot/Substrate networks and perform tests against them.","archived":false,"fork":false,"pushed_at":"2025-04-03T11:22:50.000Z","size":15308,"stargazers_count":172,"open_issues_count":78,"forks_count":93,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-05-08T00:13:04.419Z","etag":null,"topics":["kubernetes","polkadot","substrate","testing-tools"],"latest_commit_sha":null,"homepage":"https://paritytech.github.io/zombienet/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/paritytech.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-09-23T15:08:03.000Z","updated_at":"2025-04-28T20:33:31.000Z","dependencies_parsed_at":"2023-01-17T12:47:09.598Z","dependency_job_id":"78b879c6-e3e0-4b88-824c-7042891c2878","html_url":"https://github.com/paritytech/zombienet","commit_stats":{"total_commits":674,"total_committers":36,"mean_commits":18.72222222222222,"dds":0.5311572700296736,"last_synced_commit":"b99b52b88f5fbd8da3ad7b98740e9a1cefa87551"},"previous_names":[],"tags_count":223,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paritytech%2Fzombienet","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paritytech%2Fzombienet/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paritytech%2Fzombienet/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paritytech%2Fzombienet/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/paritytech","download_url":"https://codeload.github.com/paritytech/zombienet/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254047571,"owners_count":22005828,"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":["kubernetes","polkadot","substrate","testing-tools"],"created_at":"2024-07-31T16:02:07.879Z","updated_at":"2025-05-15T06:03:00.483Z","avatar_url":"https://github.com/paritytech.png","language":"TypeScript","funding_links":[],"categories":["TypeScript","Libraries","Developer"],"sub_categories":["Multisig Wallets","Tooling"],"readme":"\n![ci](https://github.com/paritytech/zombienet/actions/workflows/ci.yml/badge.svg)  [![GitLab Status](https://gitlab.parity.io/parity/zombienet/pipelines/pipeline.svg)](https://gitlab.parity.io/parity/zombienet/pipelines)\n\n# Zombienet\n\n\u003cdiv align=\"center\"\u003e\n\u003cp\u003eA cli tool to easily spawn ephemeral Polkadot/Substrate networks and perform tests against them.\u003c/p\u003e\n\u003c/div\u003e\n\n## :warning: :construction: Under Active Development :construction: :warning:\n\nThis project is still in early stage and very much a work in progress. More features will be added,\ndocs may be missing or outdated and api/config may change.\n\nNOTE: `polkadot-collator` has recently been renamed `polkadot-parachain`.\n\n---\n\n## What is Zombienet?\n\nZombienet aims to be a testing framework for Substrate based blockchains, providing a simple **cli**\ntool that allows users to spawn and test ephemeral networks. The assertions used in the tests can\ninclude on-chain storage, metrics, logs and custom javascript scripts that interact with the chain.\nTo make it easy to define those, zombienet has a `natural language` built-in allowing developers to\nwrite tests as smooth as possible.\n\nInternally zombienet is a `javascript` library, designed to run on `Node.js` and support different\nbackend `providers` to run the *nodes*, at this moment `kubernetes`, `podman` and `native` are\nsupported.\n\n## Usage\n\nZombienet releases are available in `github`. Each one provides an executable for both `linux` and\n`macos` created with [pkg](https://github.com/vercel/pkg) and allows to run `zombienet` cli\n*without* having `Node.js` installed **but** each `provider` defines its own requirements (e.g.\n`k8s`, `podman`).\n\n**Note:** Currently, it is only possible to use `podman` for Zombienet users on Linux machines.\nAlthough `podman` comes with support for macOS, it is done using an internal VM and the Zombienet provider code expects `podman` to be running natively.\n\n### Using Binaries on MacOS\n\nAfter you have downloaded `zombienet-macos-arm64` or `zombienet-macos-x64`, you will need to:\n\n- Move the binary to your working directory.\n- Rename the binary to just `zombienet` without any `macos-\u003cversion\u003e` extension for convenience.\n- Enable the binary to be executable:\n\t```bash\n\tchmod +x ./zombienet\n\t```\n- Remove the binary from quarantine:\n\t```bash\n\txattr -d com.apple.quarantine ./zombienet\n\t```\n\nThen you should be able to access the binary:\n\n```bash\n./zombienet help\n```\n\n### Install from NPM\n\nIf you have `Node.js`, you can install `zombienet` locally via NPM:\n\n```bash\nnpm i @zombienet/cli -g\n```\n\nThen you should be able to access the `zombienet` command:\n\n```\nzombienet help\n```\n\n## Status\n\nAt the moment Zombienet *only* works with `local` chains (e.g. rococo-local, polkadot-local, etc).\n\n## Requirements by provider\n\n### With kubernetes\n\nZombienet should work with any `k8s` cluster (e.g [GKE](https://cloud.google.com/kubernetes-engine),\n[docker-desktop](https://docs.docker.com/desktop/kubernetes/), [kind](https://kind.sigs.k8s.io/))\n**but** you need to have `kubectl` installed to interact with your cluster.\n\nAlso, you need *permission* to create resources (e.g `namespaces`, `pods` and `cronJobs`) in the\ntarget cluster.\n\n#### Using `Zombienet` GKE cluster (internally).\n\nZombienet project has it's own `k8s` cluster in GCP, to use it please ping\n\u003cb\u003eJavier\u003c/b\u003e(@javier:matrix.parity.io) in element to gain access and steps to use.\n\n### With Podman\n\n__:warning: Zombienet currently only supports podman v2 or older, for newer version you will need to apply [this patch](https://github.com/paritytech/zombienet/issues/827#issuecomment-1592000242) manually! :warning:__\n\nZombienet supports [Podman](https://podman.io/) *rootless* as provider, you only need to have\n`podman` installed in your environment to use and either set in the *network* file or with the\n`--provider` flag in the cli. `Podman` for `zombienet` is currently only supported for Linux machines.\nThis is mostly related to paths and directories used by\nstore configuration (chain-spec) and the data directory.\n\n### With Native\n\nZombienet `native` provider allows you to run the nodes as a local process in your environment. You\nonly need to have the `binaries` used in your `network` (e.g `polkadot` or `polkadot-parachain`).\nTo use it either set in the *network* file or with the `--provider` flag in the cli.\n\n**NOTE:** The `native` provider **only** uses the `command` config for nodes/collators, both relative\nand absolute paths are supported. You can use `default_command` config to set the binary to spawn\nall the `nodes` in the relay chain.\n\n*Alternative:* You can set the `command` to the binary directly if is available in your `PATH`.\n\n## Features by provider\n\n### kubernetes\n\nWith `k8s` zombienet use \"Prometheus operator\" (if it is available) to offload the\n`monitoring/visibility` layer, so only the network's pods are deployed by zombienet.\n\n### Podman\n\nWith `podman` zombienet deploys a couple of extra pods to add a layer of monitoring/visibility to\nthe running network. In particular pods for `prometheus`, `tempo` and `grafana` are deployed. Also,\n`grafana` is configured to have `prometheus` and `tempo` as datasource.\n\nTo access those services you can find the `url` in the output of zombinet:\n\n```bash\n  Monitor: prometheus - url: http://127.0.0.1:34123\n\n  Monitor: tempo - url: http://127.0.0.1:34125\n\n  Monitor: grafana - url: http://127.0.0.1:41461\n```\n\n*Note*: Grafana is deployed with the default admin access.\n\nOnce the network is stopped, by `ctrl+c` on a running spawn or by finishing the test, these pods are\nremoved with the rest of the pods launched by zombienet.\n\n### Native\n\nNative provider doesn't run any extra layer/process at the moment.\n\n---\n\n### Cli usage\n\n*For this example we will use the `macos` version of the executable*\n\n```bash\n❯ ./zombienet-macos\nUsage: zombienet [options] [command]\n\nOptions:\n  -c, --spawn-concurrency \u003cconcurrency\u003e  Number of concurrent spawning process to launch, default is 1\n  -p, --provider \u003cprovider\u003e              Override provider to use (choices: \"podman\", \"kubernetes\", \"native\")\n                                         default: kubernetes\n  -l, --logType \u003clogType\u003e                Type of logging on the console - defaults to 'table' (choices: \"table\", \"text\", \"silent\")\n  -d, --dir \u003cpath\u003e                       Directory path for placing the network files instead of random temp one (e.g. -d /home/user/my-zombienet)\n  -f, --force                            Force override all prompt commands\n  -m, --monitor                          Start as monitor, do not auto cleanup network\n  -h, --help                             display help for command\n\nCommands:\n  spawn \u003cnetworkConfig\u003e [creds]  Spawn the network defined in the config\n  test \u003ctestFile\u003e                Run tests on the network defined\n  version                        Prints zombienet version\n  help [command]                 display help for command\n```\n\n---\n\n### Configuration files and examples\n\n#### Spawning\n\nOne of the goals of `zombienet` is to easily spawn ephemeral networks, providing a simple but\npowerful *cli* that allows you to declare the desired network in `toml` or `json` format. You can\ncheck the [definition spec](https://paritytech.github.io/zombienet/network-definition-spec.html) to view the available options.\n\nA **minimal** configuration example with two validators and one parachain:\n\n```toml\n[settings]\ntimeout = 1000\n\n[relaychain]\ndefault_image = \"paritypr/polkadot-debug:master\"\nchain = \"rococo-local\"\n\n  [[relaychain.nodes]]\n  name = \"alice\"\n\n  [[relaychain.nodes]]\n  name = \"bob\"\n\n[[parachains]]\nid = 100\n\n  [parachains.collator]\n  name = \"collator01\"\n  image = \"paritypr/colander:master\"\n  command = \"adder-collator\"\n```\n\nThen you can spawn the network by running the following command:\n\n```bash\n❯ ./zombienet-macos spawn --provider native examples/0001-small-network.toml\n```\n\nNote that the command expects two binaries `polkadot` and `adder-collator` to be installed on your system. See further down for how to get them.\n\nYou can follow the output of the `steps` to spawn the network and once the network is launched a\nmessage with the `node`s information like this one is shown\n\n\n```bash\n┌──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐\n│                                                       Network launched 🚀🚀                                                  │\n├─────────────────────────┬────────────────────────────────────────────────────────────────────────────────────────────────────┤\n│ Namespace               │ zombie-72a1e2ffad0ad73167061bbd560e0766                                                            │\n├─────────────────────────┼────────────────────────────────────────────────────────────────────────────────────────────────────┤\n│ Provider                │ native                                                                                             │\n├─────────────────────────┴────────────────────────────────────────────────────────────────────────────────────────────────────┤\n│                                                         Node Information                                                     │\n├─────────────────────────┬────────────────────────────────────────────────────────────────────────────────────────────────────┤\n│ Name                    │ alice                                                                                              │\n├─────────────────────────┼────────────────────────────────────────────────────────────────────────────────────────────────────┤\n│ Direct Link             │ https://polkadot.js.org/apps/?rpc=ws://127.0.0.1:45589#/explorer                                   │\n├─────────────────────────┼────────────────────────────────────────────────────────────────────────────────────────────────────┤\n│ Prometheus Link         │ http://127.0.0.1:44107/metrics                                                                     │\n├─────────────────────────┼────────────────────────────────────────────────────────────────────────────────────────────────────┤\n│ Log Cmd                 │ tail -f  /tmp/zombie-85391d4649f2829bb26b30d6c0328bcb_-15819-BNFoSs5qusWH/alice.log                │\n├─────────────────────────┴────────────────────────────────────────────────────────────────────────────────────────────────────┤\n│                                                         Node Information                                                     │\n├─────────────────────────┬────────────────────────────────────────────────────────────────────────────────────────────────────┤\n│ Name                    │ bob                                                                                                │\n├─────────────────────────┼────────────────────────────────────────────────────────────────────────────────────────────────────┤\n│ Direct Link             │ https://polkadot.js.org/apps/?rpc=ws://127.0.0.1:46459#/explorer                                   │\n├─────────────────────────┼────────────────────────────────────────────────────────────────────────────────────────────────────┤\n│ Prometheus Link         │ http://127.0.0.1:43831/metrics                                                                     │\n├─────────────────────────┼────────────────────────────────────────────────────────────────────────────────────────────────────┤\n│ Log Cmd                 │ tail -f  /tmp/zombie-85391d4649f2829bb26b30d6c0328bcb_-15819-BNFoSs5qusWH/bob.log                  │\n├─────────────────────────┴────────────────────────────────────────────────────────────────────────────────────────────────────┤\n│                                                         Node Information                                                     │\n├─────────────────────────┬────────────────────────────────────────────────────────────────────────────────────────────────────┤\n│ Name                    │ collator01                                                                                         │\n├─────────────────────────┼────────────────────────────────────────────────────────────────────────────────────────────────────┤\n│ Direct Link             │ https://polkadot.js.org/apps/?rpc=ws://127.0.0.1:42607#/explorer                                   │\n├─────────────────────────┼────────────────────────────────────────────────────────────────────────────────────────────────────┤\n│ Prometheus Link         │ http://127.0.0.1:38281/metrics                                                                     │\n├─────────────────────────┼────────────────────────────────────────────────────────────────────────────────────────────────────┤\n│ Log Cmd                 │ tail -f  /tmp/zombie-85391d4649f2829bb26b30d6c0328bcb_-15819-BNFoSs5qusWH/collator01.log           │\n├─────────────────────────┼────────────────────────────────────────────────────────────────────────────────────────────────────┤\n│ Parachain ID            │ 100                                                                                                │\n└─────────────────────────┴────────────────────────────────────────────────────────────────────────────────────────────────────┘\n│ ChainSpec Path          │ /tmp/zombie-85391d4649f2829bb26b30d6c0328bcb_-15819-BNFoSs5qusWH/rococo-local-100.json             │\n└─────────────────────────┴────────────────────────────────────────────────────────────────────────────────────────────────────┘\n\n```\n\nBoth the `prometheus` and the `node` links are accessible in your local machine to get the `metrics`\nor connect to the node.\n\n#### Using `env` variables in network config\n\nZombienet can also make *replacements* in the network config using environment variables. To define\na replacement you need to use the `{{ENV_VAR_NAME}}` syntax.\n\nFor example, from the previous example but using `env` variables could be:\n\n```toml\n[relaychain]\ndefault_image = \"{{ZOMBIENET_INTEGRATION_TEST_IMAGE}}\"\nchain = \"rococo-local\"\n\n  [[relaychain.nodes]]\n  name = \"alice\"\n\n  [[relaychain.nodes]]\n  name = \"bob\"\n\n[[parachains]]\nid = 100\nadd_to_genesis = false\n\n  [parachains.collator]\n  name = \"collator01\"\n  image = \"{{COL_IMAGE}}\"\n  command = \"adder-collator\"\n```\n\nThen you can `export` the needed values before you run the command to spawn the network again:\n\n```bash\n❯ export ZOMBIENET_INTEGRATION_TEST_IMAGE=docker.io/paritypr/polkadot-debug:master\n❯ export COL_IMAGE=docker.io/paritypr/colander:master\n\n./zombienet-macos spawn examples/0001-small-network.toml\n```\n\n##### Teardown\n\nYou can teardown the network (and cleanup the used resources) by terminating the process (`ctrl+c`).\n\n---\n\n#### Testing\n\nThe other goal of `zombienet` is to provide a way to perform test/assertions against the spawned\nnetwork, using a set of `natural language expressions` that allow you to make assertions based on\nmetrics, logs and some `built-in` function that query the network using `polkadot.js`. Those\nassertions should be defined in a *.zndsl test*, and the `dsl` (**D**omain **S**pecific **L**anguage) and format is documented in\n[here](https://paritytech.github.io/zombienet/cli/test-dsl-definition-spec.html).\n\nThe following is a small example to spawn a network (using the previous `simple network\ndefinition`) and assert that:\n- Both `nodes` are running\n- The defined `parachain` is registered\n- The defined `parachain` is producing blocks and produced at least 10 within 200 seconds.\n\n```feature\nDescription: Simple Network Smoke Test\nNetwork: ./0001-small-network.toml\nCreds: config\n\nalice: is up\nbob: is up\nalice: parachain 100 is registered within 225 seconds\nalice: parachain 100 block height is at least 10 within 200 seconds\n```\n\nOther examples are provided in the [examples](examples) directory.\n\n---\n\n## Development\n\n### Requirements\n\n- [Node.js](https://nodejs.org/) if you are not using the self contained linux or macos\n  [releases](https://github.com/paritytech/zombienet/releases).\n- [Kubernetes](https://kubernetes.io) cluster to use `kubernetes` target (`kubectl` command installed).\n- [Podman](https://podman.io) to use `podman` target.\n\n### Installation\n\nYou need first to *clone* this repository and run:\n\n```bash\n❯ cd zombienet/javascript\n❯ npm i \u0026\u0026 npm run build\n```\n\n### Download and install needed artifacts (optional)\n\nFor an easier and faster setup of your local environment, run:\n\n```bash\n❯ cd zombinet/javascript\n❯ npm i \u0026\u0026 npm run zombie -- setup \u003cbinaries\u003e\n```\n\nThis allows to use the `setup` script, making everything ready for a ZombieNet dev environment.\n\nYou can use the following arguments:\n\n`--help` shows the different options and commands for using the Zombienet CLI.\n`--binaries` or `-b`: enables providing the binaries that you want to be downloaded and installed during the setup. Possible options: `all`, `polkadot`, `polkadot-parachain`. *Note:* Downloading `polkadot` will automatically download also the binaries of `polkadot-prepare-worker`, `polkadot-execute-worker`. Since Polkadot v1.0 all 3 binaries are needed for the node to run as a validator;\nFor example:\n\n```bash\n❯ cd zombinet/javascript\n❯ npm i \u0026\u0026 npm run zombie -- setup polkadot polkadot-parachain\n```\n\n\u003e Note: If you are using macOS please clone the [polkadot-sdk repo](https://github.com/paritytech/polkadot-sdk) and run it locally. At the moment there is no `polkadot` binary for MacOs.\n\nThe command above will retrieve the binaries provided and try to download and prepare those binaries for usage.\nAt the end of the download, the `setup` script will provide a command to run in your local environment in order to add the directory where the binaries were downloaded in your $PATH var, for example:\n\n```bash\nPlease add the dir to your $PATH by running the command: export PATH=/home/\u003cuser\u003e/zombienet/dist:$PATH\n```\n\n### Build adder-collator (needed for running examples with native provider)\n\nYou can build it from source like this\n\n```bash\n❯ git clone git@github.com:paritytech/polkadot-sdk.git\n❯ cd polkadot-sdk\n❯ cargo build --profile testnet -p test-parachain-adder-collator\n❯ export PATH=$(pwd)/target/testnet:$PATH\n```\n\n\n### Using Zombienet\n\nWith the above steps completed, the `zombienet` CLI is ready to run:\n\n```bash\n❯ cd zombinet/javascript\n❯ npm run zombie\n\nUsage: zombienet [options] [command]\n\nOptions:\n  -c, --spawn-concurrency \u003cconcurrency\u003e    Number of concurrent spawning process to launch, default is 1\n  -p, --provider \u003cprovider\u003e                Override provider to use (choices: \"podman\", \"kubernetes\", \"native\")\n  -l, --logType \u003clogType\u003e                  Type of logging - defaults to 'table' (choices: \"table\", \"text\", \"silent\")\n  -d, --dir \u003cpath\u003e                         Directory path for placing the network files instead of random temp one\n                                           (e.g. -d /home/user/my-zombienet)\n  -f, --force                              Force override all prompt commands\n  -h, --help                               display help for command\n\nCommands:\n  spawn [options] \u003cnetworkConfig\u003e [creds]  Spawn the network defined in the config\n  test \u003ctestFile\u003e [runningNetworkSpec]     Run tests on the network defined\n  setup [options] \u003cbinaries...\u003e            Setup is meant for downloading and making dev environment of ZombieNet ready\n  convert \u003cfilePath\u003e                       Convert is meant for transforming a (now deprecated) polkadot-launch configuration to zombienet configuration\n  version                                  Prints zombienet version\n  help [command]                           display help for command\n```\n\nWith [nix](https://zero-to-nix.com/) run `nix run github:paritytech/zombienet` or add `inputs.zombienet.url = \"github:paritytech/zombienet\";` to flake.\n\n\n## Projects using Zombienet\n\nBelow can be found some of the projects that are currently using Zombienet as integration or as a testing framework:\n\n**In Parity:**\n\n- [Cumulus](https://github.com/paritytech/cumulus/tree/master/zombienet/tests)\n- [Polkadot](https://polkadot.network/) in the [testing pipeline](https://github.com/paritytech/polkadot/blob/eafdfc36492384e16e1c253be9d5097fb3f33c60/scripts/ci/gitlab/pipeline/zombienet.yml);\n- [Substrate](https://github.com/paritytech/substrate/tree/master/zombienet)\n\n**In the Polkadot ecosystem:**\n\n- [Acurast](https://github.com/Acurast/acurast-substrate/blob/10c3160a297ae6c3092ee692e6d3b632896fca65/Makefile)\n- [Composable](https://github.com/ComposableFi/composable) via `nix run \"composable#devnet-picasso\"`\n- [Gossamer](https://github.com/ChainSafe/gossamer/issues/2843)\n- [Oak/Turing/Neumann](https://github.com/OAK-Foundation/OAK-blockchain/tree/master/zombienets)\n- [Hydradx](https://github.com/galacticcouncil/HydraDX-node/tree/master/launch-configs/zombienet)\n- [InvArch](https://github.com/InvArch/InvArch-Node/blob/34a6e2216bc79c9bcee2f2f4c0cd8243fe4dfc93/zombienet/rococo-and-tinkernet+basilisk.toml)\n- [Mangata](https://github.com/mangata-finance/mangata-node/tree/develop/devops/zombienet)\n- [Manta/Phala](https://github.com/Manta-Network/manta-indexer/pull/30)\n- [Moonbeam](https://github.com/moonbeam-foundation/moonbeam/tree/master/test)\n- [T3rn](https://github.com/t3rn/t3rn/tree/development/tests/zombienet)\n\n\n## Acknowledgement\n\nThis project takes inspiration and some patterns from\n[polkadot-launch](https://github.com/paritytech/polkadot-launch) and\n[simnet](https://gitlab.parity.io/parity/simnet/-/tree/master).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fparitytech%2Fzombienet","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fparitytech%2Fzombienet","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fparitytech%2Fzombienet/lists"}