证书

Credentials 是一个针对 BrowserContext 的虚拟 WebAuthn 认证器。它允许测试在页面中注册通行密钥并应答 navigator.credentials.create() / navigator.credentials.get() 仪式，而无需真实的认证器或硬件安全密钥。

有两种常见的使用方法：

🌐 There are two common ways to use it:

用法：播种已知凭据

const context = await browser.newContext();

// A passkey your backend already provisioned for a test user.
await context.credentials.create('example.com', {
  id: knownCredentialId, // base64url
  userHandle: knownUserHandle, // base64url
  privateKey: knownPrivateKey, // base64url PKCS#8 (DER)
  publicKey: knownPublicKey, // base64url SPKI (DER)
});
await context.credentials.install();

const page = await context.newPage();
await page.goto('https://example.com/login');
// The page's navigator.credentials.get() is answered with the seeded passkey.

用法：捕获一个通行密钥，然后重新使用它

// setup test: let the app register a passkey, then save it.
const context = await browser.newContext();
await context.credentials.install();

const page = await context.newPage();
await page.goto('https://example.com/register');
await page.getByRole('button', { name: 'Create a passkey' }).click();

// Read back the passkey the page registered — it includes the private key.
const [credential] = await context.credentials.get({ rpId: 'example.com' });
fs.writeFileSync('playwright/.auth/passkey.json', JSON.stringify(credential));

// later test: seed the captured passkey so the app starts already enrolled.
const credential = JSON.parse(fs.readFileSync('playwright/.auth/passkey.json', 'utf8'));
const context = await browser.newContext();
await context.credentials.create(credential.rpId, credential);
await context.credentials.install();

const page = await context.newPage();
await page.goto('https://example.com/login');
// navigator.credentials.get() resolves the captured passkey — already signed in.

默认

---

方法

🌐 Methods

create

Added in: v1.61 credentials.create

生成一个虚拟的 WebAuthn 凭证并返回它。

🌐 Seeds a virtual WebAuthn credential and returns it.

仅使用 rpId 即可生成新的 ECDSA P-256 密钥对、凭证 ID 和用户句柄。生成的凭证是可发现的（驻留型），因此页面可以通过用户名-然后密码密钥流程或无用户名的密码密钥流程来解析它。返回的对象包含私钥和公钥，因此可以将其保存到磁盘，并在稍后的测试中重新生成。

🌐 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.

要导入已知凭证，请同时提供id、userHandle、privateKey和publicKey四项信息。

🌐 To import a known credential, supply all four of id, userHandle, privateKey and publicKey together.

在导航到使用 WebAuthn 的页面之前调用 credentials.install()。

🌐 Call credentials.install() before navigating to a page that uses WebAuthn.

用法

await credentials.create(rpId);
await credentials.create(rpId, options);

参数

• rpId string#

  依赖方 ID（通常是网站的有效域名）。

• options Object (optional)

  • id string (optional)#

    Base64url 编码的凭证 ID。如果省略，会自动生成。

  • privateKey string (optional)#

    Base64url 编码的 PKCS#8（DER）私钥。如果省略，则自动生成。

  • publicKey string (optional)#

    Base64url 编码的 SPKI (DER) 公钥。如果省略则自动生成。

  • userHandle string (optional)#

    Base64url 编码的用户标识。如果省略，会自动生成。

返回

• Promise<Object>#

  • id string

    Base64url 编码的凭证 ID。

  • rpId string

    依赖方ID。

  • userHandle string

    Base64url 编码的用户标识符。

  • privateKey string

    Base64url 编码的 PKCS#8（DER）私钥。

  • publicKey string

    Base64url 编码的 SPKI（DER）公钥。

---

delete

Added in: v1.61 credentials.delete

通过其 ID 从身份验证器中移除凭证。适用于当前持有的任何凭证——包括使用 credentials.create() 创建的凭证以及页面自己通过调用 navigator.credentials.create() 注册的凭证。

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

用法

await credentials.delete(id);

参数

• id string#

  Base64url 编码的凭证 ID。

返回

• Promise<void>#

---

get

Added in: v1.61 credentials.get

返回身份验证器当前持有的每个凭证，可选择按 rpId 或 id 进行过滤。这包括通过 credentials.create() 创建的凭证以及页面通过调用 navigator.credentials.create() 自行注册的凭证。

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

每个返回的凭证都包含其私钥和公钥，因此应用刚注册的通行密钥可以被保存，并在以后的测试中通过 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.create() — see the second example in the class overview.

用法

await credentials.get();
await credentials.get(options);

参数

• options Object (optional)

  • id string (optional)#

    只返回具有此 base64url 编码 ID 的凭据。

  • rpId string (optional)#

    仅返回此依赖方 ID 的凭据。

返回

• Promise<Array<Object>>#

  • id string

  • rpId string

  • userHandle string

  • privateKey string

  • publicKey string

---

install

Added in: v1.61 credentials.install

将虚拟 WebAuthn 身份验证器安装到上下文中，覆盖所有当前和将来的页面中的 navigator.credentials.create() 和 navigator.credentials.get()。在页面首次接触 navigator.credentials 之前调用此操作。

🌐 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.

要求：在调用 credentials.install() 之前，不会有任何拦截，页面会看到平台原生的（或不存在的）WebAuthn 行为。使用 credentials.create() 创建凭证但不安装，会填充认证器，但页面永远不会看到这些凭证。

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

用法

await credentials.install();

返回

• Promise<void>#