testing.evm_snapshot_fixture

Documentation for eth_defi.testing.evm_snapshot_fixture Python module.

EVM snapshot/revert helper for per-test isolation on module-scope Anvil forks.

Use this when a test module shares one Anvil fork fixture (scope="module") to keep per-test state isolation cheap. Each test brackets in evm_snapshot and reverts on exit, so the fork warms up once per module instead of once per test.

Usage in a conftest or test file:

import pytest
from eth_defi.provider.anvil import AnvilLaunch, fork_network_anvil
from eth_defi.testing.evm_snapshot_fixture import evm_snapshot_revert


@pytest.fixture(scope="module")
def anvil_base_fork(...) -> AnvilLaunch:
    launch = fork_network_anvil(JSON_RPC_BASE, fork_block_number=N, ...)
    try:
        yield launch
    finally:
        launch.close()


@pytest.fixture(autouse=True)
def _evm_snapshot(anvil_base_fork):
    yield from evm_snapshot_revert(anvil_base_fork)

See the Anvil fork caching design doc for the full strategy: docs/superpowers/specs/2026-05-27-anvil-fork-caching-design.md

Functions

evm_snapshot_revert(fork)

Snapshot EVM state before, revert after — generator helper for autouse fixtures.

evm_snapshot_revert(fork)

Snapshot EVM state before, revert after — generator helper for autouse fixtures.

Yields once after taking the snapshot, then reverts on resume. Designed to be used with yield from inside a per-file @pytest.fixture(autouse=True) so each test sees a clean state on a module-scope Anvil fork.

Parameters: fork – Object with a json_rpc_url attribute, typically AnvilLaunch. The fixture that yields fork should itself be scope="module" or scope="session" — otherwise the snapshot/revert dance buys nothing.
Returns: Generator yielding None once, then performing the revert on resume.
Raises: RuntimeError – If the evm_snapshot RPC call returns a non-result (e.g. an older Anvil build or a non-Anvil backend snuck in via a different fixture).
Return type: collections.abc.Iterator[None]

Note

evm_revert restores EVM state and storage but does not reset block timestamp. Tests asserting on block.timestamp == X must call evm_setNextBlockTimestamp themselves.