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

Type: 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)

Type: Chain

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(),
})

rpcSchema (optional)

Type: RpcSchema
Default: TestRpcSchema

Typed JSON-RPC schema for the client.

import { rpcSchema } from 'viem'
 
type CustomRpcSchema = [{ 
  Method: 'eth_wagmi', 
  Parameters: [string] 
  ReturnType: string
}] 
 
const client = createTestClient({
  chain: foundry,
  rpcSchema: rpcSchema<CustomRpcSchema>(), 
  transport: http()
})
 
const result = await client.request({ 
  method: 'eth_waeth_wagmi 
  params: ['hello'], 
})