How to Test MetaMask Connect with Playwright: Complete 2026 Guide

The fastest way to test MetaMask integration is to bypass the extension entirely and inject a mock provider into window.ethereumbefore your dApp code runs. This gives you full control over every RPC response, every account address, and every chain ID. The technique uses Playwright's page.addInitScript() to execute code before any page JavaScript loads.

The mock provider needs to implement the EIP-1193 interface: a request() method that accepts an object with method and params properties, plus an event emitter for accountsChanged and chainChanged events. Your dApp should not be able to distinguish the mock from a real MetaMask installation.

The mock provider handles the most common RPC methods that dApps call during a connect flow. When your dApp calls eth_requestAccounts, the mock immediately returns the configured accounts without any popup or user interaction. This makes the tests fast and deterministic, typically completing in under 2 seconds.

What to Assert Beyond the UI

Synpress is the de facto framework for automating MetaMask in Playwright tests. It extends Playwright with MetaMask-specific fixtures that handle extension loading, wallet setup, popup automation, and network configuration. Under the hood, Synpress downloads a compatible MetaMask build, launches Chromium with the extension flags, imports your seed phrase during a global setup step, and provides helper methods to approve connection requests, confirm transactions, and switch networks.

The key insight is that MetaMask's popup is a separate Pageobject in Playwright's browser context. When your dApp triggers eth_requestAccounts, MetaMask opens a new popup window. Synpress listens for the context.on("page")event, waits for the popup to load, finds the "Connect" button inside it, and clicks it. Without Synpress, you would write this plumbing yourself.

import { testWithSynpress, MetaMask } from '@synthetixio/synpress';
import basicSetup from './wallet-setup/basic.setup';

const test = testWithSynpress(basicSetup);
const { expect } = test;

test('connects MetaMask wallet', async ({
  context, page, metamaskPage, extensionId,
}) => {
  await page.goto('/');
  await page.getByRole('button', { name: /connect wallet/i }).click();
  const metamask = new MetaMask(
    context, metamaskPage,
    basicSetup.walletPassword, extensionId
  );
  await metamask.connectToDapp();
  await expect(page.getByText('0xf39F...2266')).toBeVisible();
});

Chain switching is one of the most common user interactions in multi-chain dApps. When your application calls wallet_switchEthereumChain, MetaMask shows a confirmation popup asking the user to approve the network switch. If the requested chain is not yet configured in the user's MetaMask, the dApp typically follows up with wallet_addEthereumChain, which triggers a different popup asking the user to add the new network. Your tests need to handle both flows and verify the dApp updates its UI to reflect the new chain.

With the mock provider, chain switching is straightforward because you control the response directly. With the real extension, you need to capture the popup, find the "Approve" button, and click it. Synpress provides metamask.approveNewNetwork() and metamask.approveSwitchNetwork() helpers for this.

Transaction signing is the most security-sensitive interaction in any dApp. When your application calls eth_sendTransaction, MetaMask presents a confirmation popup showing the recipient, value, gas estimate, and total cost. The user must review these details and click "Confirm" to broadcast the transaction. Your tests need to verify that the dApp correctly formats the transaction parameters, handles the confirmation, processes the returned transaction hash, and updates the UI to show pending and confirmed states.

For personal_sign and eth_signTypedData_v4 (EIP-712), the popup shows the message being signed. Testing these signing methods is critical for dApps that use signature-based authentication (Sign-In with Ethereum) or off-chain order signing (NFT marketplaces, DEX limit orders).

import { testWithSynpress, MetaMask } from '@synthetixio/synpress';
import basicSetup from './wallet-setup/basic.setup';
const test = testWithSynpress(basicSetup);

test('confirms ETH transfer', async ({
  context, page, metamaskPage, extensionId,
}) => {
  await page.goto('/');
  const metamask = new MetaMask(
    context, metamaskPage,
    basicSetup.walletPassword, extensionId
  );
  await page.getByRole('button', { name: /connect wallet/i }).click();
  await metamask.connectToDapp();
  await page.getByLabel('Recipient').fill('0x7099...79C8');
  await page.getByLabel('Amount').fill('0.01');
  await page.getByRole('button', { name: /send/i }).click();
  await metamask.confirmTransaction();
  await expect(page.getByText(/submitted/i)).toBeVisible();
});

EIP-6963 (Multi Injected Provider Discovery) replaced the legacy window.ethereum convention with an event-based protocol. Instead of wallets fighting over a single global variable, each wallet dispatches an eip6963:announceProvider event containing its provider info (name, icon, UUID, rdns) and the actual EIP-1193 provider object. dApps listen for these events and present a wallet selection UI. This is now the standard approach used by libraries like wagmi, RainbowKit, and Web3Modal.

Testing EIP-6963 requires you to simulate multiple wallets announcing themselves. You dispatch custom events from your test setup, each carrying a different provider with different accounts, and verify that your dApp renders all available wallets and connects to the one the user selects.

Users frequently switch between accounts in MetaMask, and your dApp must handle the accountsChanged event to update its state. When MetaMask emits this event with an empty array, it means the user disconnected the dApp. When it emits with a different address, the user switched accounts. Both cases require the dApp to update balances, permissions, and UI state.

Testing this with the mock provider is elegant: you call the mock's emit() method directly from your test to simulate MetaMask firing accountsChanged. With the real extension, Synpress provides methods to switch accounts within MetaMask, and the extension fires the event to the dApp automatically.

test('updates UI on account switch', async ({ page }) => {
  await injectMockProvider(page, {
    accounts: ['0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266'],
  });
  await page.goto('http://localhost:3000');
  await page.getByRole('button', { name: /connect/i }).click();
  await expect(page.getByText('0xf39F...2266')).toBeVisible();
  await page.evaluate(() => {
    window.ethereum.selectedAddress =
      '0x70997970C51812dc3A010C7d01b50e0d17dc79C8';
    window.ethereum.emit('accountsChanged',
      ['0x70997970C51812dc3A010C7d01b50e0d17dc79C8']);
  });
  await expect(page.getByText('0x7099...79C8')).toBeVisible();
});