Menu
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.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
| name | erigon-test-race |
| description | 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. |
Runs the full test suite with Go's -race flag. Catches concurrency bugs that normal tests miss. Takes 30–60 minutes.
make test-all-race no longer downloads any fixture tarballs. EEST spec tests 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.
Use the dedicated EEST race shards:
make eest-spec-{rlptests,transactiontests,difficultytests}-legacy-race
make eest-spec-blocktests-stable-race-{pre-cancun,cancun,prague,osaka}-{sequential,parallel}
make eest-spec-blocktests-devnet-race-amsterdam-{sequential,parallel}
make eest-spec-blocktests-legacy-consensus-race-{sequential,parallel}
make eest-spec-blocktests-legacy-constantinople-race-{constantinople,constantinople-fix,other-forks}-{sequential,parallel}
make eest-spec-blocktests-legacy-cancun-race-{berlin,shanghai,cancun,london,paris,other-forks}-{sequential,parallel}
These targets build a race-instrumented evm.race binary automatically (see EEST_SPEC_RACE_SHARDS in the root Makefile). The stable, devnet, and legacy blocktest -sequential / -parallel pairs pin both commitment modes; execution remains parallel in every pair. 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.
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).
ERIGON_EXECUTION_TESTS_TMPDIR=$path make test-all-race
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/...
Areas historically susceptible to races in Erigon:
execution/exec3/ — parallel executor, SharedDomains, AsyncTxp2p/ — sentry, peer managertxpool/ — concurrent transaction poolcl/ — caplin consensus layer goroutinespath=$(bash tools/create-ramdisk) && make lint && ERIGON_EXECUTION_TESTS_TMPDIR=$path make test-all-raceThe All tests (with -race) workflow (test-all-erigon-race.yml) runs Go package race checks, while EEST spec tests (test-eest-spec.yml) runs the evm.race fixture shards above. Both are part of the CI gate.
Build pristine State Actor datadirs and run repeatable benchmarkoor performance benchmarks against a locally built Erigon image using protected native Linux OverlayFS. Use for first-time benchmarkoor setup, Glamsterdam compute or stateful repricing suites, local client image overrides, pristine-state protection, result extraction, before/after MGas/s comparisons, and cross-client ranking tables.
Run Erigon CI checks locally and/or trigger them remotely on a branch via GitHub Actions workflow_dispatch. Use this when you need to verify a branch passes all CI before or after pushing — especially for branches like bal-devnet-2 that don't auto-trigger on push/PR events.
Implement a new EIP for a hardfork under development in Erigon. Use when the user asks to implement, port, or wire up an EIP — covers spec lookup, dep analysis, prior-work check, implementation, lint, tests, and a wrap-up saved to `agentspecs/`.
Run the full Erigon test suite locally using GOGC=80 make test-all. Use this before marking a PR ready for review. Equivalent to the "All tests" CI workflow.
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.
Run Ethereum Hive integration tests against a local Erigon build, including engine, RPC compatibility, stable and devnet EEST EngineX, and RLP suites. Use when setting up an ephemeral Hive environment, selecting or running Hive suites, interpreting Hive failures, or cleaning up Hive test resources.