Headless Web3 Provider

headless-web3-provider fork by ENS. It uses viem, has fewer dependencies and supports EIP-6963 (ported from this PR).

Headless MetaMask for testing Ethereum apps.

Install

pnpm i -D @ensdomains/headless-web3-provider viem

About

The headless-web3-provider library emulates a Web3 wallet similar to Metamask and provides programmatic control over various operations, such as switching networks, connecting a wallet, and sending transactions, making it useful for end-to-end testing of Ethereum-based applications. It allows to programmatically accept or decline operations, making it handy for test automation.

Supported methods

| Method | Confirmable | | -------------------------- | ----------- | | eth_requestAccounts | Yes | | eth_accounts | Yes | | eth_sendTransaction | Yes | | wallet_addEthereumChain | Yes | | wallet_switchEthereumChain | Yes | | wallet_requestPermissions | Yes | | personal_sign | Yes | | eth_signTypedData | Yes | | eth_signTypedData_v1 | Yes | | eth_signTypedData_v3 | Yes | | eth_signTypedData_v4 | Yes | | eth_call | No | | eth_estimateGas | No | | eth_blockNumber | No | | eth_getBlockByNumber | No | | eth_getTransactionByHash | No | | eth_getTransactionReceipt | No | | eth_chainId | No | | net_version | No |

Examples

Playwright

Below given a simple example. More complex scenarios you can find in tests/e2e folder.

Setup (add a fixture):

// tests/fixtures.js
import { test as base } from '@playwright/test'
import { injectHeadlessWeb3Provider } from '@ensdomains/headless-web3-provider'
import { anvil } from 'viem/chains'

export const test = base.extend({
  // signers - the private keys that are to be used in the tests
  signers: [process.env.PRIVATE_KEY],

  // injectWeb3Provider - function that injects web3 provider instance into the page
  injectWeb3Provider: async ({ signers }, use) => {
    await use((page, privateKeys = signers) =>
      injectHeadlessWeb3Provider(
       { page, privateKeys, chains: [anvil] }
      )
    )
  },
})

Usage:

// tests/e2e/example.spec.js
import { test } from '../fixtures'

test('connect the wallet', async ({ page, injectWeb3Provider }) => {
  // Inject window.ethereum instance
  const wallet = await injectWeb3Provider(page)

  await page.goto('https://metamask.github.io/test-dapp/')

  // Request connecting the wallet
  await page.getByRole('button', { name: 'Connect', exact: true }).click()

  // You can either authorize or reject the request
  await wallet.authorize(Web3RequestKind.RequestAccounts)

  // Verify if the wallet is really connected
  await test.expect(page.locator('text=Connected')).toBeVisible()
  await test
    .expect(page.locator('text=0x8b3a08b22d25c60e4b2bfd984e331568eca4c299'))
    .toBeVisible()
})