@hemilabs/anvil-fork-setup

Start an Anvil fork before your tests and stop it after. The core startAnvilFork works in any Node test runner; a /vitest helper adds globalSetup ergonomics for Vitest. If Foundry is not installed, it will be installed automatically.

Install

npm add -D @hemilabs/anvil-fork-setup

Vitest

1. Create a globalSetup file

// test/e2e/setup.ts
import { anvilFork } from "@hemilabs/anvil-fork-setup/vitest";

export default anvilFork({
  chainId: 43111,
  forkUrl: "https://rpc.hemi.network/rpc",
});

2. Add it to your Vitest config

// vitest.config.ts
import { defineConfig } from "vitest/config";

export default defineConfig({
  test: {
    globalSetup: ["test/e2e/setup.ts"],
    testTimeout: 30_000, // RPC calls can be slow
  },
});

3. Enable types for inject

Create a type declaration file and include it in your tsconfig.json:

// test/e2e/env.d.ts
/// <reference types="@hemilabs/anvil-fork-setup/vitest" />

// tsconfig.json
{
  "include": ["src/**/*.ts", "test/e2e/env.d.ts"],
}

This makes inject("anvilUrl") type-safe in your test files.

Usage in tests

The Anvil fork URL is available via Vitest's inject:

import { inject } from "vitest";

const anvilUrl = inject("anvilUrl");

Example: reading from the fork with viem

// test/e2e/public.test.ts
import { createTestClient, erc20Abi, http } from "viem";
import { readContract } from "viem/actions";
import { hemi } from "viem/chains";
import { describe, expect, inject, it } from "vitest";

const tokenAddress = "0x99e3dE3817F6081B2568208337ef83295b7f591D";

describe("public actions e2e", function () {
  it("should read the token name", async function () {
    const client = createTestClient({
      chain: hemi,
      mode: "anvil",
      transport: http(inject("anvilUrl")),
    });

    const name = await readContract(client, {
      address: tokenAddress,
      abi: erc20Abi,
      functionName: "name",
    });

    expect(typeof name).toBe("string");
  });
});

Example: writing to the fork

Use inject("anvilUrl") as the transport URL and Anvil's default test account from @hemilabs/anvil-fork-setup/utils:

// test/e2e/wallet.test.ts
import { TEST_PRIVATE_KEY } from "@hemilabs/anvil-fork-setup/utils";
import { createTestClient, erc20Abi, http } from "viem";
import { mnemonicToAccount, privateKeyToAccount } from "viem/accounts";
import {
  readContract,
  waitForTransactionReceipt,
  writeContract,
} from "viem/actions";
import { hemi } from "viem/chains";
import { describe, expect, inject, it } from "vitest";

const tokenAddress = "0x99e3dE3817F6081B2568208337ef83295b7f591D";
const anvilMnemonic =
  "test test test test test test test test test test test junk";

const account = privateKeyToAccount(TEST_PRIVATE_KEY);
const spender = mnemonicToAccount(anvilMnemonic, { addressIndex: 1 });

describe("wallet actions e2e", function () {
  it("should approve and verify allowance", async function () {
    const client = createTestClient({
      account,
      chain: hemi,
      mode: "anvil",
      transport: http(inject("anvilUrl")),
    });

    const hash = await writeContract(client, {
      address: tokenAddress,
      abi: erc20Abi,
      functionName: "approve",
      args: [spender.address, 1000n],
    });

    expect(hash).toMatch(/^0x[0-9a-f]{64}$/i);

    const receipt = await waitForTransactionReceipt(client, { hash });
    expect(receipt.status).toBe("success");

    const result = await readContract(client, {
      address: tokenAddress,
      abi: erc20Abi,
      functionName: "allowance",
      args: [account.address, spender.address],
    });
    expect(result).toBe(1000n);
  });
});

Conditional E2E execution

You may want to skip E2E tests locally and only run them in CI. One approach is to gate the globalSetup and test inclusion on an environment variable:

// vitest.config.ts
import { defineConfig } from "vitest/config";

const isCI = process.env.CI === "true";

export default defineConfig({
  test: {
    clearMocks: true,
    ...(isCI
      ? { globalSetup: ["test/e2e/setup.ts"], testTimeout: 30_000 }
      : { exclude: ["test/e2e/**", "node_modules/**"] }),
  },
});

This way npm test runs only unit tests locally, while CI (which sets CI=true) includes E2E tests with the Anvil fork. You can add a convenience script for running E2E locally:

{
  "scripts": {
    "test": "vitest run",
    "test:e2e": "CI=true vitest run"
  }
}

Any other runner

startAnvilFork is just an async function that returns { url, pid, stop }, so it slots into any runner's global setup hook — Playwright (globalSetup), Jest (globalSetup), Mocha (mochaGlobalSetup), node:test, and so on. Playwright is shown below as a worked example.

Use startAnvilFork from the main entry inside Playwright's globalSetup. It runs once in the runner process before all tests, and the function it returns is used as the global teardown — so the same stop() handle stops the fork. No extra projects or state files needed.

1. Start the fork in a globalSetup file

// tests/global-setup.ts
import { startAnvilFork } from "@hemilabs/anvil-fork-setup";

export default async function globalSetup() {
  const { url, stop } = await startAnvilFork({
    chainId: 43111,
    forkUrl: "https://rpc.hemi.network/rpc",
  });
  process.env.ANVIL_URL = url;
  return stop;
}

2. Reference it in the config

// playwright.config.ts
import { defineConfig } from "@playwright/test";

export default defineConfig({
  globalSetup: "./tests/global-setup",
});

3. Use the fork in tests

process.env set in globalSetup is visible to all test workers, so read the fork URL from there:

import { test } from "@playwright/test";

test("reads from the fork", async () => {
  const anvilUrl = process.env.ANVIL_URL!;
  // Use anvilUrl as the RPC transport, e.g. with viem:
  // createClient({ transport: http(anvilUrl) })
});

[!NOTE] If you need the fork's startup to appear in the HTML report or UI mode, use Project Dependencies instead: a setup project starts the fork and persists pid and url to a file, and a teardown project reads it and calls process.kill(pid).

API

startAnvilFork(options): Promise<AnvilForkHandle>

Runner-agnostic. Starts an Anvil fork and resolves once it is ready.

import { startAnvilFork } from "@hemilabs/anvil-fork-setup";

const { url, pid, stop } = await startAnvilFork({
  chainId: 43111,
  forkUrl: "https://rpc.hemi.network/rpc",
});

AnvilForkHandle:

| Field | Type | Description | | -------- | --------------------- | ----------------------------------------------------------------------------------------- | | url | string | Where the fork is listening, e.g. http://127.0.0.1:8545. | | pid | number | PID of the spawned anvil process. Use process.kill(pid) to stop from another process. | | stop() | () => Promise<void> | Stop the fork and wait until the process has exited. Safe to call multiple times. |

anvilFork(options) (from /vitest)

Vitest globalSetup factory. Wraps startAnvilFork, provides anvilUrl via Vitest's provide, and returns a teardown function.

TEST_ADDRESS / TEST_PRIVATE_KEY (from /utils)

Anvil's deterministic test account #0 (derived from the default mnemonic "test test test test test test test test test test test junk"), as plain constants — no viem dependency required.

import {
  TEST_ADDRESS,
  TEST_PRIVATE_KEY,
} from "@hemilabs/anvil-fork-setup/utils";

| Export | Value | | ------------------ | -------------------------------------------------------------------- | | TEST_ADDRESS | 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266 | | TEST_PRIVATE_KEY | 0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80 |

Options

| Option | Type | Required | Default | Description | | --------- | -------- | -------- | ------- | --------------------------- | | chainId | number | Yes | — | Chain ID for the Anvil fork | | forkUrl | string | Yes | — | RPC URL to fork from | | port | number | No | 8545 | Port for the Anvil instance |

License

MIT