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.

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