Skip to content

Zombienet

Introduction

Zombienet is a testing framework designed for Polkadot SDK-based blockchain networks. It enables developers to efficiently deploy and test ephemeral blockchain environments on platforms like Kubernetes, Podman, and native setups. With its simple CLI and Domain Specific Language (DSL) for writing tests, Zombienet streamlines network spawning, testing, and performance validation.

Key features include:

  • Multi-provider support: Run networks on Kubernetes, Podman, or locally as native processes.
  • Network orchestration: Spawn relay chains with multiple validators and parachains with collators.
  • Test DSL: Write natural-language test scripts to evaluate metrics, logs, events, and on-chain storage.
  • Monitoring integration: Built-in support for Prometheus, Grafana, and Tempo on supported providers.

Install Zombienet

Zombienet releases are available on the Zombienet repository. Choose one of the following installation methods:

Download the appropriate executable for your operating system from the latest release page. Each release includes executables for Linux and macOS.

Make the downloaded file executable:

chmod +x zombienet-macos-arm64

macOS Gatekeeper: Unidentified Developer

If macOS blocks the app with "cannot be opened because it is from an unidentified developer":

Remove the quarantine attribute so the terminal can run it by running the following command:

xattr -d com.apple.quarantine zombienet-macos-arm64

Verify the installation:

./zombienet-macos-arm64 version

Optionally, move the executable to your PATH:

mv zombienet-macos-arm64 /usr/local/bin/zombienet

Now you can use the zombienet command directly:

zombienet version

For Nix users, the Zombienet repository provides a flake.nix file. You need Flakes enabled.

Run Zombienet directly:

nix run github:paritytech/zombienet/INSERT_ZOMBIENET_VERSION -- \
spawn INSERT_ZOMBIENET_CONFIG_FILE_NAME.toml

Or include Zombienet in your current shell:

nix shell github:paritytech/zombienet/INSERT_ZOMBIENET_VERSION

Run Zombienet using Docker:

docker run -it --rm \
-v $(pwd):/home/nonroot/zombie-net/host-current-files \
paritytech/zombienet

Inside the container, set up the necessary binaries:

npm run zombie -- setup polkadot polkadot-parachain

Add the binaries to your PATH:

export PATH=/home/nonroot/zombie-net:$PATH

Spawn a network:

npm run zombie -- -p native spawn host-current-files/minimal.toml

Providers

Zombienet supports different backend providers for running nodes: Kubernetes, Podman, and native (local processes). Specify the provider using the --provider flag or in your network configuration file:

zombienet spawn network.toml --provider INSERT_PROVIDER

Or set it in the configuration:

network.toml
[settings]
provider = "INSERT_PROVIDER"
...

Ensure to replace INSERT_PROVIDER with the appropriate provider: kubernetes, podman, or native.

Kubernetes

Kubernetes is compatible with GKE, Docker Desktop, and kind.

  • Requirements: Install kubectl and ensure proper cluster permissions.
  • Features: Uses Prometheus operator for monitoring when available.

Podman

Podman is a daemonless container engine for Linux. Zombienet supports Podman rootless as a provider.

  • Requirements: Install Podman on Linux.

  • Features: Deploys Prometheus, Tempo, and Grafana for monitoring. Services are accessible at http://127.0.0.1:34123 (Prometheus), http://127.0.0.1:34125 (Tempo), and http://127.0.0.1:41461 (Grafana).

Native

The native provider runs nodes as local processes on your machine.

  • Requirements: Have the necessary binaries (polkadot, polkadot-parachain) in your PATH. Install them using:

    zombienet setup polkadot polkadot-parachain

    For custom binaries, specify the path in your configuration or add them to your PATH:

    export PATH=$PATH:INSERT_PATH_TO_BINARY

  • Features: No additional monitoring features.

Configure Zombienet

Zombienet uses JSON or TOML configuration files to define network topology, nodes, and parameters. The Zombienet repository provides example configurations.

Basic Configuration

A minimal configuration includes settings, relay chain configuration, and parachain configuration.

Polkadot TestNet chain specs

For Polkadot TestNet, use chain specs from the official Polkadot TestNet chain specs repository. Download the needed files and set chain_spec_path in your config. To download Polkadot Hub TestNet specs, you can use the following command:

wget https://paseo-r2.zondax.ch/chain-specs/paseo-asset-hub.json
basic-network.toml
[settings]
timeout = 1000

[relaychain]
chain = "paseo"
default_command = "polkadot"

    [[relaychain.nodes]]
    name = "alice"
    validator = true

    [[relaychain.nodes]]
    name = "bob"
    validator = true

[[parachains]]
id = 1000
chain_spec_path = "./paseo-asset-hub.json"

    [parachains.collator]
    name = "collator-01"
    command = "polkadot-parachain"
basic-network.json
{
  "settings": {
    "timeout": 1000
  },
  "relaychain": {
    "chain": "paseo",
    "default_command": "polkadot",
    "nodes": [
      {
        "name": "alice",
        "validator": true
      },
      {
        "name": "bob",
        "validator": true
      }
    ]
  },
  "parachains": [
    {
      "id": 1000,
      "chain_spec_path": "./paseo-asset-hub.json",
      "collator": {
        "name": "collator-01",
        "command": "polkadot-parachain"
      }
    }
  ]
}

CLI Commands

Zombienet provides the following commands:

  • spawn <networkConfig>: Spawn the network defined in the configuration file.
  • test <testFile>: Run tests on the spawned network.
  • setup <binaries>: Download and set up polkadot or polkadot-parachain binaries.
  • convert <filePath>: Convert a polkadot-launch configuration to Zombienet format.
  • version: Print Zombienet version.
  • help: Print help information.

Common flags:

  • -p, --provider: Override the provider.
  • -d, --dir: Specify directory for network files.
  • -m, --monitor: Start as monitor without auto cleanup.
  • -c, --spawn-concurrency: Number of concurrent spawning processes.

Spawn a Network

To spawn a network, create a configuration file and run:

zombienet spawn network.toml --provider native

Zombienet will:

  1. Download or locate the required binaries.
  2. Generate chain specifications.
  3. Start relay chain validators.
  4. Register and start parachain collators.
  5. Display connection endpoints and logs.

Access the running nodes via the provided RPC endpoints (typically ws://127.0.0.1:9944 for the first node).

Write Tests

Zombienet provides a Domain Specific Language (DSL) for writing tests in .zndsl files. Tests can evaluate:

  • Metrics from Prometheus
  • Log patterns
  • System events
  • On-chain storage
  • Custom JavaScript/TypeScript scripts

Test File Structure

Test files contain a header and body:

example-test.zndsl
Description: Example test suite
Network: ./network.toml
Creds: config

# Test assertions
alice: is up
bob: is up
alice: parachain 1000 is registered within 200 seconds
alice: parachain 1000 block height is at least 10 within 300 seconds

Run Tests

Execute tests using:

zombienet test example-test.zndsl --provider native

The test runner will execute each assertion and report pass/fail status.

Common Assertions

Some frequently used assertions include:

  • Well-known functions: alice: is up, alice: parachain 100 is registered within 225 seconds
  • Metrics: alice: reports node_roles is 4
  • Logs: alice: log line matches glob "Imported #1" within 10 seconds
  • System events: alice: system event matches ""paraId":[0-9]+" within 10 seconds
  • Custom scripts: alice: js-script ./script.js return is greater than 1 within 200 seconds

Configuration Reference

For detailed configuration options, see:

Where to Go Next

Last update: February 26, 2026
| Created: January 14, 2026