// 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.
| 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 (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.
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 goroutinesgit submodule update --init --recursive --force && path=$(bash tools/create-ramdisk) && make lint && ERIGON_EXECUTION_TESTS_TMPDIR=$path make test-all-raceThere 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/...
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 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 benchmarkoor performance benchmarks against a locally-built Erigon binary and produce per-test MGas/s comparison tables. Covers image build, dataset reset, run invocation, result parsing, and before/after comparisons.
Run an ephemeral Erigon instance with a temporary datadir. Use this whenever the user wants to spin up a temporary, throwaway, or sandboxed Erigon node for quick testing, launch a second Erigon instance alongside an existing one, clone a datadir into a temp copy for safe experimentation, or find and clean up leftover ephemeral datadirs and processes from previous sessions. Handles port conflict detection and automatic port offsetting. Trigger on any mention of temporary/throwaway/ephemeral/disposable Erigon instances, running erigon briefly for testing or debugging, starting a second/additional erigon node, or cleaning up old temp erigon data.
Reference for all Erigon network ports. Use this when running multiple Erigon instances to avoid port conflicts. Lists every CLI flag that binds a port, its default value, and the protocol used.