Skip to main content

Credentials

Credentials is a virtual WebAuthn authenticator scoped to a BrowserContext. It lets tests register passkeys and answer navigator.credentials.create() / navigator.credentials.get() ceremonies in the page, without a real authenticator or hardware security key.

There are two common ways to use it:

Usage: seed a known credential

var context = await browser.NewContextAsync();

// A passkey your backend already provisioned for a test user.
await context.Credentials.CreateAsync("example.com", new()
{
    Id = knownCredentialId, // base64url
    UserHandle = knownUserHandle, // base64url
    PrivateKey = knownPrivateKey, // base64url PKCS#8 (DER)
    PublicKey = knownPublicKey, // base64url SPKI (DER)
});
await context.Credentials.InstallAsync();

var page = await context.NewPageAsync();
await page.GotoAsync("https://example.com/login");
// The page's navigator.credentials.get() is answered with the seeded passkey.

Usage: capture a passkey, then reuse it

// setup test: let the app register a passkey, then save it.
var context = await browser.NewContextAsync();
await context.Credentials.InstallAsync();

var page = await context.NewPageAsync();
await page.GotoAsync("https://example.com/register");
await page.GetByRole(AriaRole.Button, new() { Name = "Create a passkey" }).ClickAsync();

// Read back the passkey the page registered — it includes the private key.
var credentials = await context.Credentials.GetAsync(new() { RpId = "example.com" });
File.WriteAllText("playwright/.auth/passkey.json", JsonSerializer.Serialize(credentials[0]));
// later test: seed the captured passkey so the app starts already enrolled.
var credential = JsonSerializer.Deserialize<VirtualCredential>(
    File.ReadAllText("playwright/.auth/passkey.json"));
var context = await browser.NewContextAsync();
await context.Credentials.CreateAsync(credential.RpId, new()
{
    Id = credential.Id,
    UserHandle = credential.UserHandle,
    PrivateKey = credential.PrivateKey,
    PublicKey = credential.PublicKey,
});
await context.Credentials.InstallAsync();

var page = await context.NewPageAsync();
await page.GotoAsync("https://example.com/login");
// navigator.credentials.get() resolves the captured passkey — already signed in.

Defaults

Methods​

CreateAsync​

Added in: v1.61 credentials.CreateAsync

Seeds a virtual WebAuthn credential and returns it.

With only rpId, generates a fresh ECDSA P-256 keypair, credential id and user handle. The seeded credential is discoverable (resident), so the page can resolve it from both username-then-passkey and usernameless passkey flows. The returned object carries the private and public keys, so it can be persisted to disk and re-seeded in a later test.

To import a known credential, supply all four of Id, UserHandle, PrivateKey and PublicKey together.

Call Credentials.InstallAsync() before navigating to a page that uses WebAuthn.

Usage

await Credentials.CreateAsync(rpId, options);

Arguments

  • rpId string#

    Relying party id (typically the site's effective domain).

  • options CredentialsCreateOptions? (optional)

    • Id string? (optional)#

      Base64url-encoded credential id. Auto-generated if omitted.

    • PrivateKey string? (optional)#

      Base64url-encoded PKCS#8 (DER) private key. Auto-generated if omitted.

    • PublicKey string? (optional)#

      Base64url-encoded SPKI (DER) public key. Auto-generated if omitted.

    • UserHandle string? (optional)#

      Base64url-encoded user handle. Auto-generated if omitted.

Returns

  • Create#

    • id string

      Base64url-encoded credential id.

    • rpId string

      Relying party id.

    • userHandle string

      Base64url-encoded user handle.

    • privateKey string

      Base64url-encoded PKCS#8 (DER) private key.

    • publicKey string

      Base64url-encoded SPKI (DER) public key.

DeleteAsync​

Added in: v1.61 credentials.DeleteAsync

Removes a credential from the authenticator by its id. Works for any credential currently held — both those seeded with Credentials.CreateAsync() and those the page registered itself by calling navigator.credentials.create().

Usage

await Credentials.DeleteAsync(id);

Arguments

  • id string#

    Base64url-encoded credential id.

Returns

GetAsync​

Added in: v1.61 credentials.GetAsync

Returns every credential currently held by the authenticator, optionally filtered by RpId or Id. This includes both credentials seeded with Credentials.CreateAsync() and credentials the page registered itself by calling navigator.credentials.create().

Each returned credential includes its private and public keys, so a passkey the app just registered can be saved and re-seeded into a later test with Credentials.CreateAsync() — see the second example in the class overview.

Usage

await Credentials.GetAsync(options);

Arguments

  • options CredentialsGetOptions? (optional)

    • Id string? (optional)#

      Only return the credential with this base64url-encoded id.

    • RpId string? (optional)#

      Only return credentials for this relying party id.

Returns

InstallAsync​

Added in: v1.61 credentials.InstallAsync

Installs the virtual WebAuthn authenticator into the context, overriding navigator.credentials.create() and navigator.credentials.get() in all current and future pages. Call this before the page first touches navigator.credentials.

Required: until Credentials.InstallAsync() is called, no interception is in place and the page sees the platform's native (or absent) WebAuthn behaviour. Seeding credentials with Credentials.CreateAsync() without installing populates the authenticator, but the page will never see those credentials.

Usage

await Credentials.InstallAsync();

Returns