E2E testing passkeys

This guide shows how to test passkey enrollment and sign-in through your application with Playwright. The browser creates and signs a WebAuthn credential, so the test covers your UI, Authsignal configuration, and server-side verification without requiring Touch ID or a physical security key.

Choose a Playwright API

Playwright 1.61 or later: use browserContext.credentials for enrollment, sign-in, credential seeding, and credential persistence.
Chromium CDP: use the Chrome DevTools Protocol WebAuthn domain when you need authenticator events or controls for invalid signatures, user verification, user presence, or credential backup flags.

Start with browserContext.credentials unless a test needs one of the Chrome-specific controls.

Prerequisites

An Authsignal tenant. Use a dedicated test tenant so automated traffic does not affect production users or analytics.
Passkeys enabled for the tenant.
An application integrated with Authsignal’s pre-built UI, Web SDK, or an identity-provider integration, with a way to provision and reset test users.
Playwright 1.61 or later.

Install the virtual authenticator before the page first calls navigator.credentials.create() or navigator.credentials.get(). It is scoped to the BrowserContext, so enrollment and sign-in can share the same passkey. The example below uses a custom UI built with the Authsignal Web SDK. Replace the routes and selectors with those from your application. With the Authsignal pre-built UI or an identity-provider integration, the navigation will differ but the assertions remain the same.

tests/passkey.spec.ts

import { test, expect } from "@playwright/test";
import { createTestUser } from "./utils/fixtures";

test("a user enrolls a passkey and signs back in", async ({
  context,
  page,
}) => {
  await context.credentials.install();

  const user = await createTestUser();
  const rpId = "yourapp.com";

  await page.goto("https://yourapp.com/login");
  await page.getByRole("textbox", { name: "Email" }).fill(user.email);
  await page.getByRole("textbox", { name: "Password" }).fill(user.password);
  await page.getByRole("button", { name: "Sign in" }).click();

  // Your app calls authsignal.passkey.signUp() behind this button.
  await page.getByRole("button", { name: "Set up a passkey" }).click();

  await expect
    .poll(async () => {
      const credentials = await context.credentials.get({ rpId });
      return credentials.length;
    })
    .toBe(1);

  await expect(page.getByText("Passkey created")).toBeVisible();

  await page.goto("https://yourapp.com/logout");
  await page.goto("https://yourapp.com/login");

  // Your app calls authsignal.passkey.signIn() behind this button.
  await page
    .getByRole("button", { name: "Sign in with a passkey" })
    .click();

  await expect(page.getByText(`Welcome, ${user.email}`)).toBeVisible();
});

context.credentials.get() confirms that the browser created a credential for the expected relying party. The final UI assertion confirms that Authsignal accepted it and the application established a session.

Reuse credentials across tests

You can capture a credential after enrollment and seed it into another browser context:

const [credential] = await context.credentials.get({ rpId: "yourapp.com" });

const nextContext = await browser.newContext();
await nextContext.credentials.create(credential.rpId, credential);
await nextContext.credentials.install();

Playwright can also include virtual WebAuthn credentials in its storage state:

await context.storageState({
  path: "playwright/.auth/passkey.json",
  credentials: true,
});

Restoring that storage state installs the virtual authenticator automatically. The stored credential contains its private key, so treat the file as a secret and keep it out of version control.

Use CDP for advanced Chromium tests

Playwright’s first-class API covers most enrollment and sign-in tests. Chrome’s CDP integration adds failure injection, authenticator events, and credential-state controls.

utils/page-helpers.ts

import { Page } from "@playwright/test";

export async function setupWebAuthn(page: Page) {
  const client = await page.context().newCDPSession(page);

  await client.send("WebAuthn.enable", { enableUI: false });

  const { authenticatorId } = await client.send(
    "WebAuthn.addVirtualAuthenticator",
    {
      options: {
        protocol: "ctap2",
        transport: "internal",
        hasResidentKey: true,
        hasUserVerification: true,
        isUserVerified: true,
        automaticPresenceSimulation: true,
      },
    },
  );

  return { client, authenticatorId };
}

The main options are:

transport: "internal" models a platform authenticator such as Touch ID or Windows Hello. Use "usb" or "nfc" to model the reported transport of a roaming security key.
hasResidentKey: true allows discoverable credentials, which are required for username-free sign-in and passkey autofill.
hasUserVerification: true declares support for user verification. isUserVerified: true makes that verification succeed.
automaticPresenceSimulation: true resolves user-presence checks without waiting for a physical touch.

Chrome recommends enableUI: false for automated tests. Set it to true in a headed debugging session if you want Chrome’s WebAuthn UI to remain visible.

A CDP session only works with Chromium. Do not install both CDP and browserContext.credentials in the same browser context.

Wait for authenticator events

const credentialAdded = new Promise<void>((resolve) => {
  client.once("WebAuthn.credentialAdded", () => resolve());
});

await page.getByRole("button", { name: "Create a passkey" }).click();
await credentialAdded;

await expect(page.getByText("Passkey created")).toBeVisible();

The event confirms that the authenticator created a credential, not that the server accepted it. Keep the application-level assertion after the event.

Test failure paths with CDP

User verification fails

Set userVerificationRequirement to "required" in the tenant’s passkey authenticator configuration, then make user verification fail on the next ceremony:

await client.send("WebAuthn.setUserVerified", {
  authenticatorId,
  isUserVerified: false,
});

This makes verification fail; it does not simulate a user dismissing an operating-system prompt.

Invalid authenticator response

Override parts of the response to confirm that invalid assertions are rejected:

await client.send("WebAuthn.setResponseOverrideBits", {
  authenticatorId,
  isBogusSignature: true,
});

isBogusSignature replaces the signature with zeros. isBadUP clears the user-presence flag, and isBadUV clears the user-verification flag. A bogus signature and missing user presence must be rejected. Whether a missing user-verification flag is invalid depends on the requirement in the WebAuthn request. After each test, reset the override. Any field omitted from setResponseOverrideBits is reset to false.

User presence times out

Turn off automatic presence simulation to leave the ceremony pending:

await client.send("WebAuthn.setAutomaticPresenceSimulation", {
  authenticatorId,
  enabled: false,
});

Use this to test your application’s abort or timeout behavior. Explicitly cancel the request, navigate away, or wait for the timeout the application promises to enforce instead of adding a fixed sleep.

Stale credential

To test a stale passkey, enroll it in the browser, delete the corresponding authenticator through the Authsignal Server API, and attempt sign-in again. With credential syncing enabled, the Web SDK handles the unknown_credential response and the CDP authenticator emits credentialDeleted:

const credentialDeleted = new Promise<void>((resolve) => {
  client.once("WebAuthn.credentialDeleted", () => resolve());
});

await page
  .getByRole("button", { name: "Sign in with a passkey" })
  .click();
await credentialDeleted;

const { credentials } = await client.send("WebAuthn.getCredentials", {
  authenticatorId,
});

expect(credentials).toHaveLength(0);

This confirms that the stale credential was removed from the browser.

Device-bound and backed-up credentials

The WebAuthn backup eligibility (BE) and backup state (BS) flags describe whether a credential can be backed up and whether it is currently backed up. Change them for a test with CDP:

await client.send("WebAuthn.setCredentialProperties", {
  authenticatorId,
  credentialId,
  backupEligibility: false,
  backupState: false,
});

The combinations represent:

false / false: a single-device credential
true / false: a multi-device credential that is not currently backed up
true / true: a backed-up multi-device credential

Authsignal exposes these values as credentialDeviceType and credentialBackedUp on the enrolled authenticator.

Test passkey autofill separately

Passkey autofill uses conditional mediation and requires a discoverable credential. Configure it as described in Using passkey autofill, then test it separately from button-triggered sign-in. A conditional request can remain pending while the page is open, so starting another WebAuthn request at the same time can introduce a race.

Other test runners

Virtual authenticators are not specific to Playwright:

Selenium 4: uses the WebAuthn virtual-authenticator commands from the WebDriver specification. See Selenium’s Virtual Authenticator documentation.
WebdriverIO: exposes the same WebDriver commands, including addVirtualAuthenticator.
Puppeteer: can open a CDP session and use the same WebAuthn.* methods shown above.

What a virtual authenticator will not catch

A virtual authenticator is suited to protocol and integration testing. It does not faithfully reproduce:

Apple Passwords, Google Password Manager, or Windows Hello account pickers
A real biometric or security-key prompt
Phone-assisted QR authentication
Passkey sync between physical devices
The range of AAGUID and attestation behavior seen on production authenticators

Keep real-device coverage for these cases. Review passkey best practices on web when deciding which UX behavior to test outside CI.

Knowledge base

Authsignal Portal

Testing

Call Connect

Video walkthroughs

Help

E2E testing passkeys

Choose a Playwright API

Prerequisites

Reuse credentials across tests

Use CDP for advanced Chromium tests

Wait for authenticator events

Test failure paths with CDP

User verification fails

Invalid authenticator response

User presence times out

Stale credential

Device-bound and backed-up credentials

Test passkey autofill separately

Other test runners

What a virtual authenticator will not catch

​Choose a Playwright API

​Prerequisites

​Test enrollment and sign-in together

​Reuse credentials across tests

​Use CDP for advanced Chromium tests

​Wait for authenticator events

​Test failure paths with CDP

​User verification fails

​Invalid authenticator response

​User presence times out

​Stale credential

​Device-bound and backed-up credentials

​Test passkey autofill separately

​Other test runners

​What a virtual authenticator will not catch

Choose a Playwright API

Prerequisites

Test enrollment and sign-in together

Reuse credentials across tests

Use CDP for advanced Chromium tests

Wait for authenticator events

Test failure paths with CDP

User verification fails

Invalid authenticator response

User presence times out

Stale credential

Device-bound and backed-up credentials

Test passkey autofill separately

Other test runners

What a virtual authenticator will not catch