How to Test WebAuthn Passkeys with Playwright: Complete 2026 Guide

1. Why Testing WebAuthn Passkeys Is Harder Than It Looks

WebAuthn passkeys replace passwords with public-key cryptography bound to a hardware or platform authenticator. When a user clicks “Register a Passkey” in your application, the browser calls navigator.credentials.create(), which triggers an authenticator prompt that is entirely outside the DOM. No amount of Playwright locators can interact with the native browser dialog that asks the user to scan a fingerprint, enter a PIN, or tap a security key. In headless mode, that dialog never appears at all, which means the ceremony simply hangs forever unless you provide an alternative authenticator.

The solution is Chrome DevTools Protocol (CDP). Chromium exposes a WebAuthn domain that lets you create virtual authenticators, configure their capabilities (resident keys, user verification, transport type), and programmatically manage credentials. Playwright provides access to CDP sessions through page.context().newCDPSession(page), giving you complete control over the authenticator without any browser dialog.

There are five structural reasons this flow is hard to test reliably. First, the WebAuthn API operates outside the DOM, so traditional locator strategies cannot interact with authentication prompts. Second, the creation ceremony and assertion ceremony have different data flows, and a test that works for registration will not automatically work for login. Third, resident keys (discoverable credentials) and non-resident keys (server-side credentials) behave differently in the authenticator. Fourth, user verification levels (required, preferred, discouraged) change the authenticator response format. Fifth, conditional UI (passkey autofill) requires the mediation: "conditional" parameter and an autocomplete="webauthn" input attribute, introducing yet another code path your tests must cover.

2. Setting Up Virtual Authenticators via CDP

Every WebAuthn test in this guide depends on a virtual authenticator created through the Chrome DevTools Protocol. The virtual authenticator intercepts all navigator.credentials calls and responds as if a real hardware key or platform biometric were present. You configure the authenticator before your first test and remove it in teardown.

The fixture above creates a CTAP2 virtual authenticator with internal transport (simulating a platform authenticator like Touch ID or Windows Hello). The key configuration options are:

• protocol: 'ctap2' selects the CTAP2 protocol, which supports resident keys and user verification. Use 'u2f' only if you are testing legacy security key flows.
• hasResidentKey: true enables discoverable credentials. Passkeys are always resident keys (the credential is stored on the authenticator itself).
• isUserVerified: true tells the virtual authenticator to automatically pass user verification (biometric or PIN). Set to false to test verification failure scenarios.
• automaticPresenceSimulation: true makes the authenticator respond instantly to every ceremony, skipping the “tap your key” prompt.

A critical constraint: the WebAuthn CDP domain is Chromium only. Firefox and WebKit do not expose virtual authenticator APIs, so all WebAuthn tests in your suite must run with the chromium project. Configure this in your playwright.config.ts:

9. Common Pitfalls That Break WebAuthn Test Suites

WebAuthn testing with virtual authenticators is powerful but introduces failure modes that do not exist in other types of E2E tests. The following pitfalls are sourced from real Chromium bug reports, Playwright GitHub issues, and Stack Overflow threads.

One particularly subtle issue involves the privateKey format when seeding credentials via WebAuthn.addCredential. The CDP expects a Base64-encoded PKCS#8 key. If you provide a raw key or use the wrong encoding, the credential will be created but assertion ceremonies will produce invalid signatures, causing server-side verification to fail. The test passes from the browser's perspective (the authenticator responds), but your backend rejects the assertion. Always generate keys using crypto.subtle.generateKey with the P-256 curve and export in pkcs8 format.

10. Writing These Scenarios in Plain English with Assrt

The Playwright code above is thorough, but it requires deep knowledge of the Chrome DevTools Protocol, CTAP2 options, credential data structures, and PKCS#8 key encoding. Assrt lets you describe WebAuthn scenarios in plain English and handles the virtual authenticator setup, credential seeding, and CDP plumbing automatically.

import { test as base, type CDPSession } from '@playwright/test';

const test = base.extend<{ cdp: CDPSession; authenticatorId: string }>({
  cdp: async ({ page }, use) => {
    const client = await page.context().newCDPSession(page);
    await client.send('WebAuthn.enable');
    await use(client);
    await client.send('WebAuthn.disable');
  },
  authenticatorId: async ({ cdp }, use) => {
    const { authenticatorId } = await cdp.send(
      'WebAuthn.addVirtualAuthenticator',
      { options: { protocol: 'ctap2', transport: 'internal',
        hasResidentKey: true, hasUserVerification: true,
        isUserVerified: true, automaticPresenceSimulation: true } }
    );
    await use(authenticatorId);
    await cdp.send('WebAuthn.removeVirtualAuthenticator', { authenticatorId });
  },
});

test('register passkey', async ({ page, cdp, authenticatorId }) => {
  await page.goto('/login');
  await page.getByLabel('Email').fill('testuser@example.com');
  await page.getByLabel('Password').fill('SecureP@ss123');
  await page.getByRole('button', { name: 'Sign In' }).click();
  await page.waitForURL('/dashboard');
  await page.goto('/settings/security');
  await page.getByRole('button', { name: 'Add a Passkey' }).click();
  await expect(page.getByText('Passkey registered successfully')).toBeVisible();
  const { credentials } = await cdp.send('WebAuthn.getCredentials', { authenticatorId });
  expect(credentials).toHaveLength(1);
});

Here is a complete Assrt test file covering the core scenarios from this guide:

Assrt compiles each scenario into the same Playwright TypeScript shown in the preceding sections. The generated code includes the CDP session setup, virtual authenticator provisioning, credential seeding, and proper teardown. When the WebAuthn specification evolves or Chromium updates its CDP domain, Assrt regenerates the underlying code while your scenario files stay unchanged.

Start with the registration happy path. Once it passes in CI, add the assertion ceremony, then conditional UI, then the UV failure path, then the cross-origin scenario. In a single afternoon you can build complete WebAuthn passkey coverage that most applications never achieve by hand, because most teams never get past the “how do I even trigger a ceremony without a real authenticator?” question.