Skip to main content

Documentation Index

Fetch the complete documentation index at: https://onchaintestkit.xyz/llms.txt

Use this file to discover all available pages before exploring further.

This quickstart guide will help you set up OnchainTestKit and write your first blockchain test in minutes. We’ll create a simple test that connects a wallet and performs a transaction.

​
Prerequisites

Before you begin, ensure you have:
  • Node.js ≥ 14
  • npm, yarn, or bun (this guide uses yarn)
  • Foundry installed for Anvil local node
Need to install Foundry? Run:
curl -L https://foundry.paradigm.xyz | bash
foundryup

​
Quick Setup

1

Install dependencies

Install OnchainTestKit and Playwright:
yarn add -D @coinbase/onchaintestkit @playwright/test
yarn playwright install --with-deps
2

Download wallet extensions

Prepare the wallet extensions for testing:
# Download MetaMask
yarn prepare-metamask

# Download Coinbase Wallet  
yarn prepare-coinbase
3

Create environment variables

Create a .env file in your project root:
.env
# Test wallet seed phrase (NEVER use production wallets!)
E2E_TEST_SEED_PHRASE="test test test test test test test test test test test junk"
This is a test seed phrase. Never use your real wallet seed phrase in tests!
4

Create your first test

Create e2e/connectWallet.spec.ts:
e2e/connectWallet.spec.ts
import { createOnchainTest } from "@coinbase/onchaintestkit"
import { configure } from "@coinbase/onchaintestkit"
import { baseSepolia } from "viem/chains"

// Configure MetaMask
const config = configure()
  .withLocalNode({
    chainId: baseSepolia.id,
    forkUrl: process.env.E2E_TEST_FORK_URL, // This can be mainnet or testnet sepolia url
    forkBlockNumber: BigInt(process.env.E2E_TEST_FORK_BLOCK_NUMBER ?? "0"),
    hardfork: "cancun",
  })
  .withMetaMask()
  .withSeedPhrase({
    seedPhrase: DEFAULT_SEED_PHRASE ?? "",
    password: DEFAULT_PASSWORD,
  })
  // Add the network with the actual port in a custom setup
  .withNetwork({
    name: "Base Sepolia",
    chainId: baseSepolia.id,
    symbol: "ETH",
    // placeholder for the actual rpcUrl, which is auto injected by the node fixture
    rpcUrl: "http://localhost:8545",
  })
  .build()

// Create test with configuration
const test = createOnchainTest(config)

test.describe("Wallet Connection", () => {
  test("should connect to MetaMask", async ({ page, metamask }) => {
    if (!metamask) throw new Error("MetaMask not initialized")

    await page.getByTestId('ockConnectButton').first().click();
    console.log('[connectWallet] Wallet connect modal opened');

    // Select MetaMask from wallet options
    await page
      .getByTestId('ockModalOverlay')
      .first()
      .getByRole('button', { name: 'MetaMask' })
      .click();
    console.log('[connectWallet] MetaMask option clicked');

    // Handle MetaMask connection request
    await metamask.handleAction(BaseActionType.CONNECT_TO_DAPP);
    console.log('[connectWallet] MetaMask handleAction finished, URL after connect:', page.url());
  })
})
5

Run your test

Execute your test:
yarn playwright test e2e/connectWallet.spec.ts
To see the browser in action:
yarn playwright test e2e/connectWallet.spec.ts --headed
Want to see more real-world examples? Check out the comprehensive test examples in the OnchainTestKit repository. These examples cover:
  • Token swaps
  • NFT minting
  • Multiple wallet interactions
  • Complex transaction flows
  • And much more!

​
What’s Next?

Installation Guide

Detailed installation instructions and troubleshooting

Configuration

Learn about advanced configuration options

Writing Tests

Deep dive into writing comprehensive tests

Smart Contracts

Test smart contract interactions

​
Common Issues

Make sure you’ve run the prepare commands:
yarn prepare-metamask
yarn prepare-coinbase
Increase the test timeout in your config:
test.setTimeout(60000) // 60 seconds
The local node might be using a port that’s already taken. OnchainTestKit automatically handles port allocation for parallel tests.