Skip to main content

Maintainer Guide

This guide explains how to integrate ZecKit into a CI pipeline, where ZecKit fits in your testing story, and how to debug failures.

What ZecKit does (and does not do)​

ZecKit helps you run a local Zcash devnet environment (typically via Docker), including supporting services like a faucet, miner, and indexer (depending on your setup/backend).

ZecKit does not automatically run your application’s test suite. You still add the steps that build your project and execute your tests.

Step 1 — Initialize CI​

Run:

zeckit init

What this creates​

.github/workflows/zeckit-e2e.yml
If the workflow already exists

Compare changes before overwriting so you don’t lose project-specific CI steps.

Generated workflow (example)​

This is a representative GitHub Actions workflow shape (your generated file may differ slightly):

name: ZecKit E2E CI

on:
  push:
    branches: [main, master]
  pull_request:
    branches: [main, master]

jobs:
  zeckit-e2e:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Code
        uses: actions/checkout@v4

      - name: Start ZecKit devnet
        uses: intelliDean/ZecKit@main
        with:
          backend: 'lwd'
          image_prefix: 'ghcr.io/intellidean/zeckit'
          startup_timeout_minutes: '20'

Understanding the ZecKit Action step​

uses: intelliDean/ZecKit@main

This step is responsible for bringing up the ZecKit devnet environment in CI (commonly via Docker) and waiting until it is ready enough for your downstream steps to run.

Configuration options​

backend​

backend: 'lwd'

Common values:

  • lwd
  • zaino

Many teams prefer zaino for faster iteration:

backend: 'zaino'

image_prefix​

image_prefix: 'ghcr.io/intellidean/zeckit'

Change this only if you are testing custom images or using your own registry.

startup_timeout_minutes​

startup_timeout_minutes: '20'

CI runners are often slower than laptops. If startup times out, increase this value:

startup_timeout_minutes: '25'
tip

CI environments are slower than local machines—give the devnet enough time to become healthy before your tests start.

Step 2 — Add your own tests​

ZecKit prepares the blockchain environment; you define how your project is tested.

Example: shell smoke test (GitHub Actions)​

- name: Run smoke test
  run: |
    chmod +x ./smoke_test.sh
    ./smoke_test.sh

Example: smoke test script​

#!/usr/bin/env bash
set -euo pipefail

echo "Checking faucet..."
curl -fsS http://localhost:8080/stats

echo "Running app logic..."
# Replace with your actual logic
echo "Test complete"

Example: run your project’s normal test command​

- name: Run application tests
  run: |
    # Node.js
    npm test

    # Python
    # pytest

    # Rust
    # cargo test

    # Custom
    # ./run-tests.sh
ZecKit is not your test runner

ZecKit does not automatically execute your application tests. It provides the devnet environment your tests depend on.

Step 3 — Testing strategies​

Option A — Use ZecKit’s built-in test command​

- name: Run ZecKit test
  run: zeckit test

Option B — Run your own integration tests​

- name: Run app tests
  run: ./smoke_test.sh

Option C — Combined flow​

- name: Install dependencies
  run: npm ci

- name: Run tests
  run: npm test

Step 4 — Validate CI locally (before you push)​

Option 1 — ZecKit CLI​

zeckit up
zeckit test

Option 2 — Sample project​

Repository: zeckit-contributor-sample

git clone https://github.com/Supercoolkayy/zeckit-contributor-sample
cd zeckit-contributor-sample
./test-local.sh

Option 3 — Run your app against a local devnet​

zeckit up
./run-tests.sh
important

Always validate locally (or in a dev container) before relying on CI to catch environment issues.

Debugging CI failures​

Start here if CI is red:

Common symptoms​

SymptomWhat it usually meansWhat to try
Devnet not ready / timeoutsCI is too slow or services need more timeIncrease startup_timeout_minutes
Faucet has no balanceMining/sync not caught up yetWait longer, check logs, restart devnet
Services unhealthyStill initializing or bad stateWait, or reset (zeckit down --purge locally)
Tests fail but devnet looks fineApplication/test issueRe-run with stricter checks: zeckit test --check

Logs and artifacts​

Depending on your CI setup, useful artifacts often include container logs and ZecKit run output. Start with:

docker ps

…and inspect logs for the relevant containers (names vary by setup).

Customizing CI​

Change backend​

backend: 'zaino'

Use custom images​

image_prefix: 'ghcr.io/your-org/zeckit'

Add build steps​

- name: Install dependencies
  run: npm ci

- name: Build app
  run: npm run build

Best practices​

  • Prefer zaino when you want faster CI iteration (if it matches your testing needs).
  • Keep smoke tests small and deterministic.
  • Test locally before pushing.
  • Increase startup timeouts when runners are noisy.
  • Reset local devnet state when debugging weird failures.
success

You should now be able to generate a CI workflow, plug in your own tests, and debug the most common failure modes.