Guidance for AI agents building and running acceptance tests in the Optimism monorepo. For guidance on writing new tests — DSL patterns, naming, what to avoid — see writing-acceptance-tests.md. See dev-workflow.md for tool versions and general workflow.
Acceptance tests live in op-acceptance-tests/tests/ and run full in-process devnet scenarios. They exercise the entire stack — contracts, Go services, and Rust binaries — in a single go test process. This means all dependencies must be built locally before running them.
All just targets below automatically build dependencies (contracts, cannon prestates, Rust binaries) before running tests. The builds are incremental — re-running is fast when nothing changed.
Prerequisites: mise tools must be installed (see dev-workflow.md), and a working C toolchain (clang or gcc) must be available for Rust builds.
Always set RUST_JIT_BUILD=1 when running locally. This lets the test framework automatically build any Rust binaries it needs (e.g. op-reth) using cargo’s rebuild detection, so you don’t have to pre-build them separately.
Run from op-acceptance-tests/:
# Run a single test
RUST_JIT_BUILD=1 cd op-acceptance-tests && mise exec -- just test -run TestMyTest ./op-acceptance-tests/tests/base/
# Run a package
RUST_JIT_BUILD=1 cd op-acceptance-tests && mise exec -- just test ./op-acceptance-tests/tests/base/...
The just test target builds deps, then runs go test -count=1 -timeout 30m with your arguments.
RUST_JIT_BUILD=1 cd op-acceptance-tests && mise exec -- just acceptance-test
Runs all test packages with gotestsum, structured logging, and auto-tuned parallelism.
Gate files in op-acceptance-tests/gates/ list package subsets:
RUST_JIT_BUILD=1 cd op-acceptance-tests && mise exec -- just acceptance-test base
This runs only packages listed in gates/base.txt.
Some tests (e.g. superfaultproofs, interop fault proofs) require a reproducible kona prestate. This is not handled by build-deps or RUST_JIT_BUILD:
mise exec -- just reproducible-prestate-kona
Requires Docker. If Docker is not available in your environment, ask the user to run this command for you.
build-deps DoesThe just build-deps target (called automatically by just test and just acceptance-test) runs these steps when not in CI:
mise install (ensures gotestsum, forge, etc. are available)cd packages/contracts-bedrock && just install && just build-no-testsjust cannon-prestates (builds cannon, op-program, and prestate artifacts)just build-rust-release (kona-node, op-rbuilder, rollup-boost)You can also run just build-deps directly to pre-build without running tests.
acceptance-test only)When using just acceptance-test, the runner auto-detects CPU count and sets:
ACCEPTANCE_TEST_JOBS — number of packages to test in parallel (default: CPU count)ACCEPTANCE_TEST_PARALLEL — go test -parallel value per package (default: CPU count / 2)ACCEPTANCE_TEST_TIMEOUT — per-package timeout (default: 2h)Override with environment variables:
ACCEPTANCE_TEST_PARALLEL=2 ACCEPTANCE_TEST_TIMEOUT=1h cd op-acceptance-tests && mise exec -- just acceptance-test
acceptance-test only)When using just acceptance-test, logs are written to op-acceptance-tests/logs/testrun-<timestamp>/:
all.log — full test outputraw_go_events.log — JSON test eventsflaky-tests.txt — tests marked with MarkFlaky()Results XML goes to op-acceptance-tests/results/results.xml.
When using just test, output goes to stdout only.
cd op-acceptance-tests && mise exec -- just build-deps or mise exec -- just cannon-prestates from the repo root.cd packages/contracts-bedrock && mise exec -- just build-no-tests.mise exec -- just build-rust-release from the repo root.mise install to install all pinned tools.