Skip to content

Test Client

A function to create a Test Client

A Test Client is an interface to "test" JSON-RPC API methods accessible through a local Ethereum test node such as Anvil or Hardhat such as mining blocks, impersonating accounts, setting fees, etc through Test Actions.

The createTestClient function sets up a Test RPC Client with a given Transport.

Import

import { createTestClient } from 'viem'

Usage

Initialize a Client with your desired Chain, Transport (e.g. http) and mode (e.g. "anvil").

import { createTestClient, http } from 'viem'
import { foundry } from 'viem/chains'
 
const client = createTestClient({
  chain: foundry,
  mode: 'anvil',
  transport: http(), 
})

Then you can consume Test Actions:

const mine = await client.mine({ blocks: 1 })

Extending with Public & Wallet Actions

When interacting with a Ethereum test node, you may also find yourself wanting to interact with Public Actions and Wallet Actions with the same chain and transport. Instead of creating three different Clients, you can instead just extend the Test Client with those actions:

import { createTestClient, http, publicActions, walletActions } from 'viem'
import { foundry } from 'viem/chains'
 
const client = createTestClient({
  chain: foundry,
  mode: 'anvil',
  transport: http(), 
})
  .extend(publicActions) 
  .extend(walletActions) 
 
const blockNumber = await client.getBlockNumber() // Public Action
const hash = await client.sendTransaction({ ... }) // Wallet Action
const mine = await client.mine({ blocks: 1 }) // Test Action

Parameters

mode

  • Type: "anvil" | "hardhat" | "ganache"

Mode of the Test Client.

const client = createTestClient({
  chain: foundry,
  mode: 'anvil', 
  transport: http(), 
})

transport

Transport of the Test Client.

const client = createTestClient({
  chain: foundry,
  mode: 'anvil', 
  transport: http(),  
})

account (optional)

  • Type: Account | Address

The Account to use for the Client. This will be used for Actions that require an account as an argument.

Accepts a JSON-RPC Account or Local Account (Private Key, etc).

import { privateKeyToAccount } from 'viem/accounts'
 
const client = createTestClient({
  account: privateKeyToAccount('0x...'), 
  chain: foundry,
  mode: 'anvil',
  transport: http(),
})

chain (optional)

Chain of the Test Client.

const client = createTestClient({
  chain: foundry, 
  mode: 'anvil',
  transport: http(), 
})

cacheTime (optional)

  • Type: number
  • Default: client.pollingInterval

Time (in ms) that cached data will remain in memory.

const client = createTestClient({
  cacheTime: 10_000, 
  chain: foundry,
  mode: 'anvil',
  transport: http(),
})

name (optional)

  • Type: string
  • Default: "Test Client"

A name for the Client.

const client = createTestClient({
  chain: foundry,
  mode: 'anvil', 
  name: 'Anvil Client',  
  transport: http(),
})

pollingInterval (optional)

  • Type: number
  • Default: 4_000

Frequency (in ms) for polling enabled Actions.

const client = createTestClient({
  chain: foundry,
  mode: 'anvil', 
  pollingInterval: 10_000,  
  transport: http(),
})