Struct AnvilNode 

pub struct AnvilNode { /* private fields */ }

Available on crate feature anvil only.

Community Testcontainers Implementation for Foundry Anvil

This is a community implementation of the Testcontainers interface for Foundry Anvil.

Anvil is Foundry’s fast local Ethereum node for development and testing. It’s an ideal tool for rapid iteration on smart contract development and provides a clean, lightweight alternative to running a full node.

Example

use testcontainers_modules::{
    anvil::{AnvilNode, ANVIL_PORT},
    testcontainers::runners::AsyncRunner,
};

// Start an Anvil node
let node = AnvilNode::default().start().await?;

// Get the RPC endpoint URL
let host_port = node.get_host_port_ipv4(ANVIL_PORT).await?;
let rpc_url = format!("http://localhost:{host_port}");

// Use with your favorite Ethereum library (alloy, ethers, web3, etc.)
// let provider = Provider::try_from(rpc_url)?;

Advanced Configuration

use testcontainers_modules::anvil::AnvilNode;

// Configure chain ID and forking
let node = AnvilNode::default()
    .with_chain_id(1337)
    .with_fork_url("https://eth.llamarpc.com")
    .with_fork_block_number(18_000_000)
    .start().await?;

Usage

The endpoint of the container is intended to be injected into your provider configuration, so that you can easily run tests against a local Anvil instance.

To use the latest Foundry image, you can use the latest() method:

let node = AnvilNode::latest().start().await?;

Users can use a specific Foundry image in their code with ImageExt::with_tag.

use testcontainers::core::ImageExt;
let node = AnvilNode::default().with_tag("nightly").start().await?;

Implementations

impl AnvilNode

pub fn latest() -> Self

Create a new AnvilNode with the latest Foundry image

pub fn with_tag(self, tag: impl Into<String>) -> Self

Use a specific Foundry image tag

pub fn with_chain_id(self, chain_id: u64) -> Self

Specify the chain ID - this will be Ethereum Mainnet by default

pub fn with_fork_url(self, fork_url: impl Into<String>) -> Self

Specify the fork URL to fork from a live network

Example

let node = AnvilNode::default()
    .with_fork_url("https://eth.llamarpc.com")
    .start().await?;

pub fn with_fork_block_number(self, block_number: u64) -> Self

Specify the fork block number (requires with_fork_url to be set)

Example

let node = AnvilNode::default()
    .with_fork_url("https://eth.llamarpc.com")
    .with_fork_block_number(18_000_000)
    .start().await?;

pub fn with_state_mount(self, host_dir: impl AsRef<Path>) -> Self

Mount a host directory for anvil state at /state inside the container

Use this method to bind mount a host directory to the container’s /state directory. This allows you to persist state across container restarts.

Arguments

• host_dir - Path on the host machine to mount (will be mounted to /state in container)

Note

When using this method, specify container paths (starting with /state/) in with_load_state_path and with_dump_state_path.

Example

let temp_dir = std::env::temp_dir().join("anvil-state");
let node = AnvilNode::default()
    .with_state_mount(&temp_dir)
    .with_dump_state_path("/state/state.json")
    .start().await?;

pub fn with_load_state_path(self, path: impl Into<String>) -> Self

Configure Anvil to initialize from a previously saved state snapshot. Equivalent to passing --load-state <PATH>.

Arguments

• path - Path to the state file (container-internal path, typically /state/... if using with_state_mount)

Example

let node = AnvilNode::default()
    .with_state_mount("/host/path/to/state")
    .with_load_state_path("/state/state.json")
    .start().await?;

pub fn with_dump_state_path(self, path: impl Into<String>) -> Self

Configure Anvil to dump the state on exit to the given file or directory. Equivalent to passing --dump-state <PATH>.

Arguments

• path - Path where state should be saved (container-internal path, typically /state/... if using with_state_mount)

Example

let node = AnvilNode::default()
    .with_state_mount("/host/path/to/state")
    .with_dump_state_path("/state/state.json")
    .start().await?;

pub fn with_state_interval(self, seconds: u64) -> Self

Configure periodic state persistence interval in seconds. Equivalent to passing --state-interval <SECONDS>.

Example

let node = AnvilNode::default()
    .with_state_mount("/host/path/to/state")
    .with_dump_state_path("/state/state.json")
    .with_state_interval(30) // Save every 30 seconds
    .start().await?;

Trait Implementations

impl Clone for AnvilNode

fn clone(&self) -> AnvilNode

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for AnvilNode

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for AnvilNode

fn default() -> AnvilNode

Returns the “default value” for a type.

impl Image for AnvilNode

fn cmd(&self) -> impl IntoIterator<Item = impl Into<Cow<'_, str>>>

Returns the CMD this image needs to be created with.

fn entrypoint(&self) -> Option<&str>

Returns the entrypoint this image needs to be created with.

fn env_vars( &self, ) -> impl IntoIterator<Item = (impl Into<Cow<'_, str>>, impl Into<Cow<'_, str>>)>

Returns the environment variables that needs to be set when a container is created.

fn mounts(&self) -> impl IntoIterator<Item = &Mount>

Returns the mounts that needs to be created when a container is created.

fn expose_ports(&self) -> &[ContainerPort]

Returns the ports that needs to be exposed when a container is created.

fn name(&self) -> &str

The name of the docker image to pull from the Docker Hub registry.

fn tag(&self) -> &str

Implementations are encouraged to include a tag that will not change (i.e. NOT latest) in order to prevent test code from randomly breaking because the underlying docker suddenly changed.

fn ready_conditions(&self) -> Vec<WaitFor>

Returns a list of conditions that need to be met before a started container is considered ready.

fn copy_to_sources(&self) -> impl IntoIterator<Item = &CopyToContainer>

Returns the files to be copied into the container at startup.

fn exec_after_start( &self, cs: ContainerState, ) -> Result<Vec<ExecCommand>, TestcontainersError>

Returns the commands that needs to be executed after a container is started i.e. commands to be run in a running container.

fn exec_before_ready( &self, cs: ContainerState, ) -> Result<Vec<ExecCommand>, TestcontainersError>

Returns commands that will be executed after the container has started, but before the Image::ready_conditions are awaited for.