Foundry Anvil Testcontainers NodeJS Module

Description

This repository provides a Testcontainers module for Node.js to run a customized Anvil node in your E2E tests.

This Typescript module provides a Fluent API style method of configuring and starting the Anvil node. And during your test execution, the module provides a viem test client and streamlined helper methods to interact with the node.

Base image: https://github.com/foundry-rs/foundry/blob/master/Dockerfile

Built using Anvil: https://getfoundry.sh/anvil/reference/anvil

Foundry image: ghcr.io/foundry-rs/foundry:v1.6.0-rc1

Custom image: hellaweb3/foundry-anvil:1.6

Custom image DockerHub

---

Usage

Install the module:

pnpm add -D @hellaweb3/foundryanvil-testcontainers-nodejs

Setup

Use the AnvilContainer module to start up a new Anvil testcontainer in your test suite.

• Set up the container in a beforeAll hook.
• Add an afterAll hook to stop the container.

describe("AnvilContainer", () => {
  let container: StartedAnvilContainer;

  beforeAll(async () => {
    const options = new AnvilOptions()
      .logs.verboseLogs(LogVerbosity.Five)
      .logs.jsonLogFormat()
      .account.withRandomMnemonic()
      .evm.autoImpersonate();

    container = await new AnvilContainer(options).start();
  }, 60000);

  afterAll(async () => {
    if (container) await container.stop();
  });
});

Test

The StartedAnvilContainer provides a viem test client that you can use to interact with the node.

• Access the viem test client via container.client.
• Use container test helpers like addresses() and sendEthTransaction().

it("test send transaction", async () => {
  let addresses = await container.addresses();

  const receipt: TransactionReceipt = await container.sendEthTransaction(
    addresses[0],
    addresses[1],
    "1",
  );

  expect(receipt.status).toBe("success");
});

---

Scripts

Script	Description
pnpm dev	Start development mode with watch
pnpm build	Build for production
pnpm test	Run tests
pnpm eslint	Lint code
pnpm typecheck	Run TypeScript type checking

---

Forking Options

Configure the Anvil node to fork from a remote RPC URL:

const options = new AnvilOptions().fork
  .withForkUrl(`https://mainnet.infura.io/v3/${INFURA_KEY}`)
  .fork.withForkBlockNumber(17500000);

const container = await new AnvilContainer(options).start();

---

Configuration Options

The AnvilContainer can be highly customized using the AnvilOptions class. Options are organized into logical modules to make configuration intuitive.

Review the Foundry Docs for more details.

Account Options

Configure development accounts, balances, and mnemonics.

• Use-case: Setup specific pre-funded accounts or use a known mnemonic to ensure predictable addresses across test runs.

Option	Description
withAccounts(count: number)	Sets the number of dev accounts to generate and configure.
withBalance(balance: number)	Sets the balance of every dev account in Ether.
withDerivationPath(path: string)	Sets the derivation path of the child key to be derived.
withMnemonic(mnemonic: string)	Sets the BIP39 mnemonic phrase used for generating accounts.
withRandomMnemonic(words?: number)	Automatically generates a BIP39 mnemonic phrase.
withMnemonicSeedUnsafe(seed: string)	Generates a BIP39 mnemonic phrase from a given seed.

const options = new AnvilOptions().account
  .withAccounts(10)
  .account.withBalance(1000)
  .account.withRandomMnemonic();

const container = await new AnvilContainer(options).start();

EVM Options

Fine-tune the EVM behavior, gas limits, and hardforks.

• Use-case: Test contract deployments that exceed default code size limits or simulate specific Ethereum hardforks.

Option	Description
withHardfork(hardfork: Hardfork)	Sets the EVM hardfork to use.
autoImpersonate(enabled?: boolean)	Enables automatic impersonation on startup.
withBlockBaseFeePerGas(fee: bigint | number)	Sets the base fee in a block.
withChainId(chainId: number)	Sets the chain ID.
withCodeSizeLimit(size: number)	EIP-170: Contract code size limit in bytes.
disableBlockGasLimit(enabled?: boolean)	Disable the call.gas_limit <= block.gas_limit constraint.
disableCodeSizeLimit(enabled?: boolean)	Disable EIP-170: Contract code size limit.
disableMinPriorityFee(enabled?: boolean)	Disable the enforcement of a minimum suggested priority fee.
withGasLimit(limit: bigint | number)	Sets the block gas limit.
withGasPrice(price: bigint | number)	Sets the gas price.
disableDefaultCreate2Deployer(enabled?: boolean)	Disable the default create2 deployer.
disablePoolBalanceChecks(enabled?: boolean)	Disable pool balance checks.
withMemoryLimit(limit: number)	The memory limit per EVM execution in bytes.
withPrintTraces(enabled?: boolean)	Enable printing of traces for executed transactions and eth_call to stdout.
withStepsTracing(enabled?: boolean)	Enable steps tracing used for debug calls returning geth-style traces.

const options = new AnvilOptions().evm
  .withHardfork(Hardfork.London)
  .evm.withCodeSizeLimit(32128)
  .evm.autoImpersonate();

Forking Options

Fork from a remote RPC endpoint to test against real-world state.

• Use-case: Integration tests that interact with existing protocols (e.g., Uniswap, Aave) on Mainnet or L2s.

Option	Description
withComputeUnitsPerSecond(cups: number)	Sets the number of assumed available compute units per second for this provider.
withForkUrl(url: string)	Fetch state over a remote endpoint instead of starting from an empty state.
withForkBlockNumber(blockNumber: number)	Fetch state from a specific block number over a remote endpoint.
withForkChainId(chainId: number)	Specify chain id to skip fetching it from remote endpoint.
withForkHeader(header: string)	Headers to use for the rpc client.
withForkRetryBackoff(backoff: number)	Initial retry backoff on encountering errors.
withForkTransactionHash(hash: string)	Fetch state from after a specific transaction hash has been applied.
noRateLimit(enabled?: boolean)	Disables rate limiting for this node's provider.
noStorageCaching(enabled?: boolean)	Explicitly disables the use of RPC caching.
withRetries(retries: number)	Number of retry requests for spurious networks.
withTimeout(timeout: number)	Timeout in ms for requests sent to remote JSON-RPC server.

const options = new AnvilOptions().fork
  .withForkUrl("https://mainnet.infura.io/v3/YOUR_KEY")
  .fork.withForkBlockNumber(18000000);

Mining Options

Control block production and mining behavior.

• Use-case: Simulate a real-time mining interval to test frontend polling logic or time-dependent contract features.

Option	Description
withBlockTime(seconds: number)	Sets the block time in seconds for interval mining.
withMixedMining(enabled?: boolean)	Enable mixed mining.
withNoMining(enabled?: boolean)	Disable auto and interval mining, and mine on demand instead.
withBlockNumber(number: number)	Sets the number of the genesis block.
withSlotsInAnEpoch(slots: number)	Slots in an epoch.

const options = new AnvilOptions().mining
  .withBlockTime(1) // Mine a block every second
  .mining.withMixedMining();

Logging Options

Adjust output verbosity and format for better debugging.

• Use-case: Enable JSON logging for automated log analysis or increase verbosity to debug failing transactions.

Option	Description
withColor(color: Color)	The color of the log messages.
withMarkdownFormat(enabled?: boolean)	Format log messages as Markdown.
quiet(enabled?: boolean)	Do not print log messages.
verboseLogs(logVerbosity: LogVerbosity)	Sets the verbosity level of the log messages.
jsonLogFormat(enabled?: boolean)	Format log messages as JSON.
disableConsoleLog(enabled?: boolean)	Disable printing of console.log invocations to stdout.

const options = new AnvilOptions().logs
  .verboseLogs(LogVerbosity.Three)
  .logs.jsonLogFormat();

Network Options

Enable features specific to certain networks like Celo or Optimism.

• Use-case: E2E tests for cross-chain applications or protocols deployed on Optimism or Celo.

Option	Description
withCelo(enabled?: boolean)	Enable Celo network features.
withOptimism(enabled?: boolean)	Enable Optimism network features.

const options = new AnvilOptions().network
  .withOptimism();

Server Options

Configure the RPC server settings, CORS, and IPC.

• Use-case: Testing IPC connections or adjusting CORS settings for local web application development.

Option	Description
withIpc(path?: string)	Launch an ipc server at the given path or default path.
withThreads(threads: number)	Number of threads to use.
withAllowOrigin(origin: string)	The cors allow_origin header.
withCachePath(path: string)	Path to the cache directory where persisted states are stored.
noCors(enabled?: boolean)	Disable CORS.
noRequestSizeLimit(enabled?: boolean)	Disable the default request body size limit.

const options = new AnvilOptions().server
  .withAllowOrigin("*")
  .server.noCors();

State Options

Manage chain state, persistence, and snapshots.

• Use-case: Speed up test suites by loading a pre-configured state instead of re-deploying contracts every time.

Option	Description
withConfigOut(path: string)	Writes output of anvil as json to user-specified file.
withDumpState(path: string)	Dump the state and block environment of chain on exit.
withInit(path: string)	Initialize the genesis block with the given genesis.json file.
withLoadState(path: string)	Initialize the chain from a previously saved state snapshot.
withMaxPersistedStates(count: number)	Max number of states to persist on disk.
withOrder(order: Order)	How transactions are sorted in the mempool.
withPreserveHistoricalStates(enabled?: boolean)	Preserve historical state snapshots when dumping the state.
withPruneHistory(count?: number)	Don't keep full chain history.
withStateInterval(seconds: number)	Interval in seconds at which the state is to be dumped to disk.
withState(path: string)	Alias for both --load-state and --dump-state.
withTimestamp(timestamp: number)	The timestamp of the genesis block.
withTransactionBlockKeeper(count: number)	Number of blocks with transactions to keep in memory.

const options = new AnvilOptions().state
  .withLoadState("path/to/state.json")
  .state.withDumpState("path/to/new-state.json");

---

Tools

• Bunchee - Zero-config bundler for npm packages
• Jest - Testing framework

Module Formats

This library exports both ESM and CommonJS formats, with full TypeScript support:

• dist/index.js - ESM
• dist/index.cjs - CommonJS
• dist/index.d.ts - TypeScript declarations

Publishing

# Build the package
pnpm run build

# Publish to npm
np --no-publish

# Trigger GitHub release workflow
git push origin --tags

This will trigger the release.yml and publish.yml workflows.

---

Contracts

WETH: https://etherscan.io/address/0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2#code

---

Using a Custom Docker Image

Build the docker image:

docker build -t hellaweb3/foundry-anvil:1.6 .

Run the docker image:

docker run -p 8545:8545 hellaweb3/foundry-anvil:1.6

Push the docker image:

docker push hellaweb3/foundry-anvil:1.6

Use cast to test the connection:

cast block-number

Use script to test the connection:

node ./scripts/get-block-number.ts

Maintainers

Maintained by Hella Labs.

License

MIT