dAppwright

E2E testing for dApps using Playwright + MetaMask & Coinbase Wallet

Installation

$ npm install -s @tenkeylabs/dappwright
$ yarn add @tenkeylabs/dappwright

Usage

Quick setup with Hardhat

  # test.spec.ts

  import { test as base, expect } from '@playwright/test';
  import { BrowserContext } from 'playwright-core';
  import { bootstrap, Dappwright, getWallet, MetaMaskWallet } from '@tenkeylabs/dappwright';

  export const test = base.extend<{ wallet: Dappwright }, { walletContext: BrowserContext }>({
    walletContext: [
      async ({}, use) => {
        // Launch context with extension
        const [wallet, _, context] = await bootstrap("", {
          wallet: "metamask",
          version: MetaMaskWallet.recommendedVersion,
          seed: "test test test test test test test test test test test junk", // Hardhat's default https://hardhat.org/hardhat-network/docs/reference#accounts
          headless: false,
        });

        await use(context);
        await context.close();
      },
      { scope: 'worker' },
    ],
    context: async ({ walletContext }, use) => {
      await use(walletContext);
    },
    wallet: async ({ walletContext }, use) => {
      const wallet = await getWallet("metamask", walletContext);
      await use(wallet);
    },
  });

  test.beforeEach(async ({ page }) => {
    await page.goto("http://localhost:8080");
  });

  test("should be able to connect", async ({ wallet, page }) => {
    await page.click("#connect-button");
    await wallet.approve();

    const connectStatus = page.getByTestId("connect-status");
    await expect(connectStatus).toHaveValue("connected");

    await page.click("#switch-network-button");

    const networkStatus = page.getByTestId("network-status");
    await expect(networkStatus).toHaveValue("31337");
  });

Alternative Setups

There are a number of different ways integrate dAppwright into your test suite. For some other examples, please check out dAppwright's example application repo.

Running in CI / Headless Environments

⚠️ Important: Browser extensions do not work properly in Chromium's headless mode. You must use headless: false combined with a virtual framebuffer (xvfb-run) in CI environments.

Why headless: true doesn't work

Chromium's headless mode (even with --headless=new) does not reliably support browser extension popup windows. Wallet extensions like MetaMask and Coinbase Wallet rely on popups for connection and transaction approval flows, causing tests to hang when these popups fail to open.

GitHub Actions Example

jobs:
  e2e:
    runs-on: ubuntu-latest
    container:
      image: mcr.microsoft.com/playwright:v1.56.1-jammy
    steps:
      - uses: actions/checkout@v4
      - name: Install dependencies
        run: npm ci
      - name: Run tests
        run: xvfb-run --auto-servernum npx playwright test

Key points:

• Set headless: false in your dAppwright configuration
• Use xvfb-run to provide a virtual display on Linux CI
• On macOS/Windows, simply use headless: false (xvfb not needed)
• See dAppwright's own CI workflow for a working example

Special Thanks

This project is a fork of the Chainsafe and Decentraland version of dAppeteer.