OpenParable
Skip to content
← Back to skills

Erigon Test Race

Testing & Quality
erigon-test-race

Erigon Test Race is an Agent Skill for testing & quality published in the erigontech/erigon repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Run Erigon tests with Go race detector to find data races and concurrency bugs. Use this for concurrency-sensitive changes (parallel executor, p2p, txpool). Takes 30-60 minutes.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/erigontech/erigon/blob/HEAD/.claude/skills/erigon-test-race/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/erigon-test-race, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Erigon Race Detector Tests

Runs the full test suite with Go's -race flag. Catches concurrency bugs that normal tests miss. Takes 30–60 minutes.

Prerequisite: Test fixtures

make test-all-race no longer downloads any fixture tarballs. EEST spec tests (state/blockchain/engine-x) moved out of go test ./... and into the dedicated eest-spec-* Makefile targets driven by the EEST spec tests workflow (test-eest-spec.yml); the consensus spec test (cl/spectest) is skipped here via ERIGON_SKIP_CL_SPECTEST=true (set automatically by the Makefile) and runs only in test-integration-caplin.yml.

If you want race coverage on the EEST blocktests, use the dedicated race shards — make eest-spec-blocktests-stable-race-{pre-cancun,cancun,prague,osaka}-{sequential,parallel} and make eest-spec-blocktests-devnet-race-amsterdam. These build a race-instrumented evm.race binary automatically (see EEST_SPEC_RACE_SHARDS in the root Makefile); the -sequential / -parallel split pins ERIGON_EXEC3_PARALLEL so race coverage hits both modes. For the consensus spec suite or other Go packages, pass GOFLAGS='-race' or invoke go test -race against the relevant package directly.

Pitfall: stale evm.race binary. make eest-spec-<race-shard> lists evm.race as a prereq and go build is cache-aware, so a stale binary gets rebuilt. Calling bash tools/run-eest-spec-test.sh <shard> directly with EVM_BIN=build/bin/evm.race bypasses the rebuild and silently runs an old race-instrumented binary against current fixtures — race reports against code that no longer exists, missed races against code that does. After pulling or switching branches: rm -f build/bin/evm.race && make evm.race before re-running.

One side prerequisite still applies for tests make test-all-race does run:

git submodule update --init --recursive --force            # only for legacy-tests (TestLegacyCancunState)

The CI workflow handles this in setup-erigon; locally you must do it yourself.

Prerequisite: Create RAM Disk

Before running make test-all-race, create a RAM disk and export its path as ERIGON_EXECUTION_TESTS_TMPDIR:

path=$(bash tools/create-ramdisk)

Then prepend ERIGON_EXECUTION_TESTS_TMPDIR=$path to the test command (see below). The execution/tests suite does heavy temp-file I/O; backing that with tmpfs avoids disk bottlenecks and matches how CI runs the same workflow (ramdisk: true in test-all-erigon-race.yml, which invokes the same tools/create-ramdisk script via setup-erigon).

The script is cross-platform (Linux tmpfs, macOS hdiutil, Windows ImDisk). Linux requires sudo to mount tmpfs at /mnt/erigon-ramdisk. Override size with RAMDISK_SIZE_MB (default 2048).

Command

ERIGON_EXECUTION_TESTS_TMPDIR=$path make test-all-race

When Tests Fail — Drill Down

Race detector output includes the goroutine stack traces that caused the race:

==================
WARNING: DATA RACE
Read at 0x00c0001a2b40 by goroutine 45:
  github.com/erigontech/erigon/execution/exec3.(*parallelExecutor).applyLoop()
      /path/to/exec3_parallel.go:123 +0x4f8

Previous write at 0x00c0001a2b40 by goroutine 23:
  github.com/erigontech/erigon/execution/exec3.(*parallelExecutor).executeBlocks()
      /path/to/exec3.go:456 +0x2a0
==================

Re-run just the failing package with race:

go test -race --timeout 60m ./execution/exec3/...
go test -race --timeout 60m -run TestName ./path/to/package/...

Run without race first to confirm the test passes normally, then add -race:

# 1. Confirm test logic is correct (fast)
go test -short -run TestName ./path/to/package/...

# 2. Check for races (slower)
go test -race -run TestName ./path/to/package/...

Known Race-Prone Areas

Areas historically susceptible to races in Erigon:

  • execution/exec3/ — parallel executor, SharedDomains, AsyncTx
  • p2p/ — sentry, peer manager
  • txpool/ — concurrent transaction pool
  • cl/ — caplin consensus layer goroutines

When to Use

  • After changes to the parallel executor or concurrent code paths
  • For concurrency-sensitive fixes before merging
  • Race check gate: git submodule update --init --recursive --force && path=$(bash tools/create-ramdisk) && make lint && ERIGON_EXECUTION_TESTS_TMPDIR=$path make test-all-race

CI Equivalent

There is no dedicated race CI workflow — the "All tests" workflow does not run with -race by default. This is a local-only check.

To run a subset with race via CI, consider running locally or using:

go test -race --timeout 60m ./execution/exec3/... ./execution/stagedsync/...