Skip to main content
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.