How to Test WalletConnect Flow with Playwright: Complete 2026 Guide

1. Why Testing WalletConnect Is Harder Than It Looks

WalletConnect v2 connects a browser-based dApp to a mobile wallet through a relay server. The standard user experience is: your dApp renders a QR code containing a pairing URI, the user scans it with their mobile wallet, the wallet and dApp negotiate a session over the relay, and then signing requests flow back and forth through that persistent session. The QR code handoff is the fundamental obstacle for automated testing. There is no phone in your CI environment, no camera to scan with, and no way to interact with a mobile wallet from a Playwright script running in a headless browser.

The complexity goes deeper than the QR code. WalletConnect v2 uses a topic-based publish/subscribe model over a WebSocket relay. The pairing URI contains a symmetric key that both sides use to encrypt messages. The session proposal specifies which chains, JSON-RPC methods, and events the dApp requires, and the wallet must approve each one explicitly. Chain switching sends a separate wallet_switchEthereumChain request that the wallet can reject. Disconnection can originate from either side, and both sides must handle the session_delete event gracefully.

There are five structural reasons this flow resists test automation. First, the QR code is a visual artifact that cannot be clicked or filled like a form field. Second, the relay is an external service that introduces network latency and occasional connectivity drops. Third, session proposals involve cryptographic key exchange that must happen in the correct order. Fourth, each signing request requires explicit wallet-side approval, which in production means tapping a button on a phone. Fifth, chain switching may trigger additional prompts on the wallet side that are invisible to the dApp.

The solution is to bypass the QR code entirely. Instead of scanning, you extract the raw pairing URI from the dApp, feed it to a programmatic wallet (a Node.js script using the WalletConnect SDK), and simulate the wallet side of every interaction. The sections below show you exactly how.

2. Setting Up a Reliable Test Environment

Testing WalletConnect requires three components running in parallel: your dApp in a browser (driven by Playwright), a programmatic wallet that acts as the signer, and access to the WalletConnect relay (either the public relay or a local one). The programmatic wallet is a Node.js process that uses the @walletconnect/web3wallet SDK to pair, approve sessions, and sign transactions without any UI.

Environment Variables

Programmatic Wallet Helper

The core of your test infrastructure is a programmatic wallet that simulates what a real mobile wallet does. It connects to the WalletConnect relay, listens for session proposals, and responds to signing requests. This helper runs as a background process during your test suite.

Playwright Configuration

3. Scenario: Bypassing the QR Code via Pairing URI

The first and most critical scenario is establishing a WalletConnect session without scanning a QR code. Every dApp that implements WalletConnect generates a pairing URI (starting with wc:) and encodes it into a QR code for the user to scan. That same URI is available in the DOM or via JavaScript evaluation on the page. Your test extracts it, passes it to the programmatic wallet, and the pairing completes over the relay just as it would with a real phone.

Most dApps that use the WalletConnect Web3Modal also provide a “Copy to clipboard” button next to the QR code, or store the URI in a data attribute on the QR container element. Some dApps expose it through the window.walletconnect object or emit it as a custom DOM event. The extraction method depends on the dApp, but one of these approaches will work for virtually every implementation.

import { test, expect } from '@playwright/test';
import { createTestWallet, pairAndApprove } from '../helpers/walletconnect-wallet';

test('bypass QR code and pair', async ({ page }) => {
  const wallet = await createTestWallet();
  await page.goto('/');
  await page.getByRole('button', { name: /connect wallet/i }).click();

  await expect(page.locator('[class*="walletconnect"]'))
    .toBeVisible({ timeout: 10_000 });

  const uri = await page.evaluate(() => {
    const qr = document.querySelector('[data-uri]');
    if (qr) return qr.getAttribute('data-uri');
    const input = document.querySelector('input[value^="wc:"]');
    return input?.value || null;
  });

  expect(uri).toMatch(/^wc:[a-f0-9]+@2/);
  const topic = await pairAndApprove(wallet, uri!, ['eip155:1']);
  expect(topic).toBeTruthy();

  await expect(page.getByText(/connected|0xf39F/i))
    .toBeVisible({ timeout: 15_000 });
});

4. Scenario: Session Proposal Approval

After pairing, the dApp sends a session proposal that specifies which blockchain namespaces, chains, JSON-RPC methods, and events it requires. The wallet must review this proposal and approve or reject it. In a real wallet app, this is a confirmation screen the user taps. In your test, the programmatic wallet evaluates the proposal and approves it with the correct accounts and chains.

Testing the session proposal is important because a mismatch between what the dApp requests and what the wallet approves will cause silent failures later. If the dApp requires eth_signTypedData_v4 but the wallet only approves personal_sign, the dApp will not discover the problem until it tries to request a typed signature and gets an error. Your test should verify that the proposal includes all required methods and that the approval response matches.

# scenarios/walletconnect-session-proposal.assrt
describe: Validate session proposal and approve with correct namespaces

given:
  - the dApp is running
  - a programmatic test wallet is ready

steps:
  - connect to the dApp via QR bypass
  - inspect the session proposal

expect:
  - the proposal requires the eip155 namespace
  - required chains include eip155:1
  - required methods include eth_sendTransaction and personal_sign
  - required events include chainChanged and accountsChanged
  - after approval the dApp shows connected state

5. Scenario: Chain Switching (Ethereum to Polygon)

Many dApps support multiple EVM chains and let users switch between them. When a user selects a different chain in the dApp UI, the dApp sends a wallet_switchEthereumChain request through the WalletConnect session. The wallet receives this request, switches its active chain, and emits a chainChanged event back to the dApp. Testing this flow verifies that chain switching propagates correctly through the relay and that both the dApp and wallet end up on the same chain.

If the wallet does not support the requested chain, it should return a 4902 error code (chain not added). Your dApp should then attempt to add the chain via wallet_addEthereumChain before retrying the switch. Both the success and failure paths need test coverage.

test('chain switch: Ethereum to Polygon', async ({ page }) => {
  const wallet = await createTestWallet();
  await page.goto('/');
  // ... connect and pair ...
  const sessionTopic = await pairAndApprove(wallet, uri!, ['eip155:1', 'eip155:137']);

  wallet.on('session_request', async (event) => {
    if (event.params.request.method === 'wallet_switchEthereumChain') {
      await wallet.respondSessionRequest({
        topic: event.topic,
        response: { id: event.id, jsonrpc: '2.0', result: null },
      });
      await wallet.emitSessionEvent({
        topic: event.topic,
        event: { name: 'chainChanged', data: 137 },
        chainId: 'eip155:137',
      });
    }
  });

  await page.getByRole('button', { name: /network/i }).click();
  await page.getByRole('option', { name: /polygon/i }).click();
  await expect(page.getByText(/polygon/i)).toBeVisible();
});

6. Scenario: Transaction Signing and Confirmation

The core value of WalletConnect is enabling a dApp to request transaction signatures from a remote wallet. When the user initiates an on-chain action (minting an NFT, swapping tokens, sending ETH), the dApp constructs a transaction object and sends an eth_sendTransaction request through the WalletConnect session. The wallet receives the request, shows the user a confirmation screen, signs the transaction with the private key, broadcasts it to the network, and returns the transaction hash.

In your test environment, the programmatic wallet skips the confirmation screen and signs immediately. For a complete test, you also want to verify that the dApp correctly handles the returned transaction hash: showing a pending state, polling for confirmation, and updating the UI once the transaction is mined. If you are using a local Hardhat or Anvil node, the transaction confirms instantly. On a testnet, you may need to wait.

7. Scenario: Wallet Rejection and Error Handling

Users reject transactions. They open their wallet, see the gas fee, and decide not to proceed. The wallet sends back a JSON-RPC error with code 4001(User Rejected Request). Your dApp must handle this gracefully: dismiss the pending state, show an appropriate error message, and allow the user to retry. Many dApps fail this scenario silently, leaving the user stuck in a “waiting for wallet” state forever.

Beyond user rejection, your test suite should cover other error scenarios: the relay connection dropping mid-request, the session expiring, and the wallet returning an insufficient funds error. Each of these produces a different error code and message that your dApp should handle distinctly.

# scenarios/walletconnect-rejection.assrt
describe: Wallet rejects a transaction and dApp handles it gracefully

given:
  - wallet is connected to the dApp
  - wallet is configured to reject all signing requests

steps:
  - initiate a send transaction in the dApp
  - fill in recipient and amount
  - click confirm

expect:
  - the dApp shows a rejection or error message
  - the dApp is not stuck in a pending state
  - the send button is enabled again for retry

8. Scenario: Graceful Disconnect Flow

WalletConnect sessions can be terminated by either the dApp or the wallet. When the user clicks “Disconnect” in the dApp, it sends a session_deleteevent through the relay, and both sides clean up their local session state. When the wallet disconnects (the user removes the dApp from their wallet's session list), the dApp receives the session_delete event and should revert to an unauthenticated state. Both directions need test coverage because the failure mode is different for each.

A common bug is the dApp failing to clean up its local state after a wallet-initiated disconnect. The user's wallet shows no active session, but the dApp still shows a connected address and attempts to send signing requests to a dead session. Testing both disconnect directions catches this class of bug.

test('wallet-initiated disconnect', async ({ page }) => {
  const wallet = await createTestWallet();
  // ... connect and pair ...
  const sessionTopic = await pairAndApprove(wallet, uri!, ['eip155:1']);

  await expect(page.getByText(/connected|0xf39F/i))
    .toBeVisible({ timeout: 15_000 });

  // Wallet initiates disconnect
  await wallet.disconnectSession({
    topic: sessionTopic,
    reason: { code: 6000, message: 'User disconnected' },
  });

  // dApp should revert to disconnected state
  await expect(page.getByRole('button', { name: /connect wallet/i }))
    .toBeVisible({ timeout: 15_000 });
  await expect(page.getByText(/0xf39F/i))
    .not.toBeVisible({ timeout: 5_000 });
});

9. Common Pitfalls That Break WalletConnect Test Suites

Relay Connectivity Timeouts

The WalletConnect relay (relay.walletconnect.org) is an external service. In CI environments with restricted network egress or behind corporate firewalls, the WebSocket connection may fail silently or time out. The symptom is your test hanging indefinitely at the pairing step. Always set explicit timeouts on the pairing operation and add retry logic. Consider running a local relay (the WalletConnect team publishes a Docker image) for fully isolated CI pipelines.

Stale Session State Between Test Runs

WalletConnect SDKs persist session data in local storage (browser side) and a local database (wallet side). If your tests do not clean up sessions between runs, leftover sessions from previous tests can cause pairing failures or unexpected “already connected” states. Clear the browser's local storage in your test setup and call wallet.getActiveSessions() to disconnect any lingering sessions before each test.

Project ID Rate Limits

Every WalletConnect Project ID has rate limits on the relay. Free tier projects allow a limited number of pairings per day. If you run your test suite frequently or in parallel across multiple CI runners, you will exhaust this limit. The relay returns a 429 status on the WebSocket upgrade, and the SDK silently fails to connect. Use a dedicated Project ID for CI with a higher tier, or batch your tests to minimize pairing operations by reusing sessions across related test cases.

Namespace Mismatch Between dApp and Wallet

The session proposal specifies required namespaces (chains, methods, events), and the wallet must approve namespaces that satisfy all requirements. If your programmatic wallet approves eip155:1 but the dApp also requires eip155:137, the session will be established but chain switching to Polygon will fail. Always inspect the proposal's requiredNamespaces and build your approval response dynamically from it, rather than hardcoding chains.

WebSocket Connection Racing

The WalletConnect relay uses WebSocket connections, and both the dApp and wallet need active connections before messages can flow. If your test extracts the pairing URI and immediately feeds it to the programmatic wallet, the wallet's WebSocket connection may not be established yet. The pairing message gets lost, and the test times out. Add an explicit wait for the wallet's relay connection to be ready before attempting to pair. The core.relayer.subscriber.on('created') event signals that the relay connection is active.

10. Writing These Scenarios in Plain English with Assrt

The Playwright code in this guide is substantial. The QR bypass scenario alone is over 40 lines of TypeScript that deeply couples your test to DOM selectors, the WalletConnect SDK API, and the specific element structure of your dApp's connect modal. When your dApp upgrades from Web3Modal v3 to v4, or switches from WalletConnect to a different wallet connection library, every selector breaks. Assrt lets you describe the intent of each scenario in plain English, generates the Playwright implementation, and regenerates it when the underlying page structure changes.

The QR bypass scenario from Section 3 illustrates this well. In Playwright, you need to know the exact CSS selector for the QR container, the data attribute name, and the fallback extraction strategies. In Assrt, you describe what you want: “extract the pairing URI from the QR modal.” Assrt resolves the correct extraction method at runtime by analyzing the live DOM.

Assrt compiles each scenario into the same Playwright TypeScript you saw in the preceding sections, committed to your repo as real tests. When your dApp switches from @web3modal/react to @reown/appkit, Assrt detects the selector failures, analyzes the new DOM structure, and opens a pull request with updated locators. Your scenario files remain untouched.

Start with the QR bypass scenario. Once it passes in CI, add session proposal validation, then chain switching, then transaction signing, then rejection handling, then disconnect. Within an afternoon you will have complete WalletConnect coverage that most Web3 dApps never achieve manually.