# Erigon Test Hive

> Run Erigon Hive simulator tests locally or via GitHub Actions. Tests EL/CL protocol interoperability (engine API, RPC compat, EEST fixtures). Requires Docker and either `act` (for CI simulation) or direct hive invocation.

- Skill: `erigontech/erigon-test-hive` (Agent Skill)
- Install (CLI): `npx skillmds@latest add erigontech/erigon-test-hive`
- Raw SKILL.md: https://api.skillmd.com/api/skills/erigontech/erigon-test-hive/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: erigontech (https://skillmd.com/u/erigontech)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/erigontech/erigon-test-hive

---


# Erigon Hive Tests

Runs Hive simulator tests for EL/CL protocol interoperability. Three modes:
1. **`make test-hive`** — uses `act` (nektos) to simulate the GitHub Actions workflow locally
2. **`make hive-local`** — builds hive and runs suites directly (no `act` needed)
3. **`make eest-devnet`** — runs the CI-equivalent Glamsterdam `consume-enginex` shard

## Prerequisites

- Docker running
- `GITHUB_TOKEN` environment variable set (for `make test-hive` via `act`)
- `act` installed (for `make test-hive`): https://nektosact.com/installation/index.html

## Docker Resource Warning

**Hive creates many Docker containers and images per test run.** Without cleanup, these accumulate and exhaust disk space and memory. Always run the cleanup steps below — even after a clean run.

Hive spawns per test:
- One container per EL client instance (erigon)
- One container per simulator (e.g., `ethereum/engine`, `eels/consume-enginex`)
- Intermediate build images for each client Dockerfile

The CI workflow always runs `docker system prune -af --volumes` on exit (even on failure). Replicate this locally.

## Commands

### Via act (mirrors CI exactly)

```bash
export GITHUB_TOKEN=<your-token>

# Run standard hive suite (engine API, RPC compat, EEST)
make test-hive

# Run EEST-only suite
SUITE=eest make test-hive
```

### Direct hive run (no act required)

```bash
# Build erigon Docker image and run engine/rpc-compat suites
make hive-local
```

### Direct EEST EngineX runs

```bash
# Runs the unsharded stable EngineX fixtures
make eest-hive

# Matches the CI glamsterdam-devnet shard
make eest-devnet
```

`make eest-devnet` selects Amsterdam and `BPO2ToAmsterdam`, enables parallel
execution and BAL validation, and uses the CI simulator parallelism and timeout
flags. Use `SUITE=eest make test-hive` to exercise the complete stable/devnet
matrix.

## Cleanup (ALWAYS run after hive tests)

Hive leaves behind stopped containers, dangling images, and build caches. Run this after every hive test run, including after failures or ctrl+c:

```bash
# Stop all running hive-related containers
docker ps --filter "name=hive" -q | xargs -r docker stop

# Full prune: removes all stopped containers, unused images, build cache, volumes
docker system prune -af --volumes
```

### Automated cleanup with trap (recommended for direct hive invocations)

Wrap hive invocations in a script with a trap so cleanup runs on exit/ctrl+c:

```bash
cleanup() {
  echo "Cleaning up Docker resources..."
  docker ps --filter "name=hive" -q | xargs -r docker stop 2>/dev/null || true
  docker system prune -af --volumes
  echo "Docker cleanup complete"
}
trap cleanup EXIT INT TERM

cd temp/<hive-dir>/hive
./hive --sim ethereum/engine --sim.limit=".*cancun.*" --client erigon
```

### Check what's accumulated

```bash
# Show disk usage by Docker
docker system df

# List dangling images
docker images --filter dangling=true

# List stopped containers from hive
docker ps -a --filter "name=hive" --format "table {{.Names}}\t{{.Status}}\t{{.Size}}"
```

## When a Suite Fails — Drill Down

Hive outputs test results to `temp/*/hive/workspace/logs/`. View results in the hiveview browser:

```bash
# hiveview serves results at http://localhost:3000
cd temp/<hive-dir>/hive
./hiveview --serve --logdir ./workspace/logs
```

Re-run a single suite by specifying the simulator and limit:
```bash
cd temp/<hive-dir>/hive

# Run only the failing simulator
./hive --sim ethereum/engine --sim.limit=exchange-capabilities --client erigon

# Run with a specific test pattern
./hive --sim ethereum/engine --sim.limit=".*cancun.*" --sim.parallelism=4 --client erigon

# Run stable EEST EngineX simulator (URL pinned in test-fixtures.json)
./hive --sim ethereum/eels/consume-enginex --sim.limit="" --sim.parallelism=4 --client erigon \
  --sim.buildarg fixtures=$(jq -r '."eest_stable".url' test-fixtures.json)
```

## Suites Covered

| Suite | Description |
|-------|-------------|
| `engine/exchange-capabilities` | Engine API capability negotiation |
| `engine/withdrawals` | Withdrawals support |
| `engine/cancun` | Cancun/EIP-4844 blob txs |
| `engine/api` | Engine API conformance |
| `engine/auth` | JWT authentication |
| `rpc-compat` | RPC compatibility with reference |
| `eels/consume-enginex` | Stable and fork-partitioned devnet EEST EngineX tests |

## Related Skill

For an **interactive, ephemeral hive workflow** (handles versioned EEST fixtures, Dockerfile setup, BAL workarounds, per-suite parallelism), use the `/hive-test` skill instead:
```
/hive-test eest-devnet       # run devnet (BAL/glamsterdam) tests
/hive-test engine rpc-compat # run engine + rpc suites
/hive-test all               # run everything
```
The `/hive-test` skill also covers detailed cleanup via `./hive --cleanup` + `docker image prune -f`.

This skill (`erigon-test-hive`) documents the Makefile targets for reference — use `/hive-test` when you need a full guided run.

## CI Equivalent

| Local command | CI workflow | File |
|---------------|-------------|------|
| `make test-hive` | Test Hive | `test-hive.yml` |
| `SUITE=eest make test-hive` | Hive EEST tests | `test-hive-eest.yml` |
| `make eest-devnet` | Hive EEST `glamsterdam-devnet` shard | `test-hive-eest.yml` |

To dispatch remotely on a branch:
```bash
gh workflow run "Test Hive" --ref <branch>
```

## Troubleshooting

| Problem | Solution |
|---------|----------|
| `act command not found` | Install from https://nektosact.com/installation/index.html |
| `GITHUB_TOKEN` not set | `export GITHUB_TOKEN=$(gh auth token)` |
| Docker build fails | Ensure `make erigon` succeeded first (builds binary used in Docker image) |
| Hive clone fails | Check network; hive is cloned fresh each run into `temp/` |
| EEST fixtures 404 | Check the URL pinned in `test-fixtures.json`; the version must match a released tag |
| Disk full / OOM | Run `docker system prune -af --volumes` — previous hive runs left dangling images/containers |
| Containers stuck running | `docker ps --filter "name=hive" -q \| xargs -r docker stop` |