Playwright.Credentials (Playwright v1.65.0-rc.3)

Copy Markdown View Source

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 three common ways to use it:

Usage: seed a known credential

context = Browser.new_context!(browser)

# A passkey your backend already provisioned for a test user.
# All base64url: the private key PKCS#8 (DER), the public key SPKI (DER).
BrowserContext.credentials(context)
|> Credentials.create!("example.com",
  id: known_credential_id,
  user_handle: known_user_handle,
  private_key: known_private_key,
  public_key: known_public_key
)

BrowserContext.credentials(context) |> Credentials.install!()

page = BrowserContext.new_page!(context)
Page.goto!(page, "https://example.com/login")
# The page's navigator.credentials.get() is answered with the seeded passkey.

Usage: capture a credential, then reuse it

# setup test: let the app register a passkey, then save the storage state with it.
context = Browser.new_context!(browser)
BrowserContext.credentials(context) |> Credentials.install!()

page = BrowserContext.new_page!(context)
Page.goto!(page, "https://example.com/register")
Page.get_by_role(page, :button, name: "Create a passkey") |> Locator.click!()

# Read back the passkey the page registered — it includes the private key.
[credential] = BrowserContext.credentials(context) |> Credentials.get!(rp_id: "example.com")
File.write!("playwright/.auth/passkey.json", JSON.encode!(credential))
# later test: seed the captured passkey so the app starts already enrolled.
credential = File.read!("playwright/.auth/passkey.json") |> JSON.decode!()
context = Browser.new_context!(browser)

BrowserContext.credentials(context)
|> Credentials.create!(credential["rpId"],
  id: credential["id"],
  user_handle: credential["userHandle"],
  private_key: credential["privateKey"],
  public_key: credential["publicKey"],
  sign_count: credential["signCount"]
)

BrowserContext.credentials(context) |> Credentials.install!()

page = BrowserContext.new_page!(context)
Page.goto!(page, "https://example.com/login")
# navigator.credentials.get() resolves the captured passkey — already signed in.

Usage: save credentials in the storage state, restore later

See authentication guide for examples of using saving and restoring the storage state.

Defaults

Since Playwright 1.61.

The examples alias the modules they use (alias Playwright.{Locator, Page}).

Summary

Types

Options of create/3, see its docs.

Options of get/2, see its docs.

t()

A Credentials handle. Compare handles with ==, their fields are internal.

Functions

Seeds a virtual WebAuthn credential and returns it.

Like create/3, but returns the value and raises on error.

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

Like delete/2, but returns the value and raises on error.

Returns every credential currently held by the authenticator, optionally filtered by :rp_id or :id. This includes both credentials seeded with Playwright.Credentials.create/3 and credentials the page registered itself by calling navigator.credentials.create().

Like get/2, but returns the value and raises on error.

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.

Like install/1, but returns the value and raises on error.

Types

create_options()

@type create_options() ::
  [
    id: String.t(),
    private_key: String.t(),
    public_key: String.t(),
    sign_count: integer(),
    user_handle: String.t()
  ]
  | %{
      optional(:id) => String.t(),
      optional(:private_key) => String.t(),
      optional(:public_key) => String.t(),
      optional(:sign_count) => integer(),
      optional(:user_handle) => String.t()
    }
  | %{
      id: String.t(),
      rpId: String.t(),
      userHandle: String.t(),
      privateKey: String.t(),
      publicKey: String.t(),
      signCount: integer()
    }

Options of create/3, see its docs.

get_options()

@type get_options() ::
  [id: String.t(), rp_id: String.t()]
  | %{optional(:id) => String.t(), optional(:rp_id) => String.t()}

Options of get/2, see its docs.

t()

@type t() :: %Playwright.Credentials{_browserContext: term()}

A Credentials handle. Compare handles with ==, their fields are internal.

Functions

create(credentials, rp_id, options \\ [])

@spec create(t(), String.t(), create_options()) ::
  {:ok,
   %{
     id: String.t(),
     rpId: String.t(),
     userHandle: String.t(),
     privateKey: String.t(),
     publicKey: String.t(),
     signCount: integer()
   }}
  | {:error, Playwright.error()}

Seeds a virtual WebAuthn credential and returns it.

With only rp_id, 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, :user_handle, :private_key and :public_key together. Pass :sign_count as well to continue from the signature counter the relying party has already seen.

Call Playwright.Credentials.install/1 before navigating to a page that uses WebAuthn.

In Elixir, the options may also be a result of this function (a map with the JS keys), as JS passes one: create!(credentials, known.rpId, known). Its fields that are no options are ignored.

Since Playwright 1.61.

Arguments

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

Options

  • :id (String.t/0) - Base64url-encoded credential id. Auto-generated if omitted.
  • :private_key (String.t/0) - Base64url-encoded PKCS#8 (DER) private key. Auto-generated if omitted.
  • :public_key (String.t/0) - Base64url-encoded SPKI (DER) public key. Auto-generated if omitted.
  • :sign_count (integer/0) - Since Playwright 1.64. Initial value of the signature counter. The counter is incremented by one on every successful navigator.credentials.get() assertion, so the first assertion reports signCount + 1. Defaults to 0.
  • :user_handle (String.t/0) - Base64url-encoded user handle. Auto-generated if omitted.

create!(credentials, rp_id, options \\ [])

@spec create!(t(), String.t(), create_options()) :: %{
  id: String.t(),
  rpId: String.t(),
  userHandle: String.t(),
  privateKey: String.t(),
  publicKey: String.t(),
  signCount: integer()
}

Like create/3, but returns the value and raises on error.

delete(credentials, id)

@spec delete(t(), String.t()) :: :ok | {:error, Playwright.error()}

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

Since Playwright 1.61.

Arguments

  • id - Base64url-encoded credential id.

delete!(credentials, id)

@spec delete!(t(), String.t()) :: :ok

Like delete/2, but returns the value and raises on error.

get(credentials, options \\ [])

@spec get(t(), get_options()) ::
  {:ok,
   [
     %{
       id: String.t(),
       rpId: String.t(),
       userHandle: String.t(),
       privateKey: String.t(),
       publicKey: String.t(),
       signCount: integer()
     }
   ]}
  | {:error, Playwright.error()}

Returns every credential currently held by the authenticator, optionally filtered by :rp_id or :id. This includes both credentials seeded with Playwright.Credentials.create/3 and credentials the page registered itself by calling navigator.credentials.create().

Each returned credential includes its private and public keys and the current signature counter, so a passkey the app just registered can be saved and re-seeded into a later test with Playwright.Credentials.create/3 — see the second example in the class overview.

Since Playwright 1.61.

Options

  • :id (String.t/0) - Only return the credential with this base64url-encoded id.
  • :rp_id (String.t/0) - Only return credentials for this relying party id.

get!(credentials, options \\ [])

@spec get!(t(), get_options()) :: [
  %{
    id: String.t(),
    rpId: String.t(),
    userHandle: String.t(),
    privateKey: String.t(),
    publicKey: String.t(),
    signCount: integer()
  }
]

Like get/2, but returns the value and raises on error.

install(credentials)

@spec install(t()) :: :ok | {:error, Playwright.error()}

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 Playwright.Credentials.install/1 is called, no interception is in place and the page sees the platform's native (or absent) WebAuthn behaviour. Seeding credentials with Playwright.Credentials.create/3 without installing populates the authenticator, but the page will never see those credentials.

Since Playwright 1.61.

install!(credentials)

@spec install!(t()) :: :ok

Like install/1, but returns the value and raises on error.