Playwright is a framework for Web Testing and Automation. It allows testing Chromium, Firefox and WebKit with a single API.
TypeScript automationchromechromiume2e-testingelectronend-to-end-testingfirefoxjavascriptplaywrighttesttest-automationtestingtesting-toolswebwebkit
feat(webauthn): include credentials in storageState (#41215)
Dmitry Gozman0beb571f6c69
diff --git a/docs/src/api/class-browsercontext.md b/docs/src/api/class-browsercontext.mdindex 518b2f6059..03589a5f4c 100644--- a/docs/src/api/class-browsercontext.md+++ b/docs/src/api/class-browsercontext.md@@ -1549,7 +1549,7 @@ Whether to emulate network being offline for the browser context.- `name` <[string]>- `value` <[string]>-Returns storage state for this browser context, contains current cookies, local storage snapshot and IndexedDB snapshot.+Returns storage state for this browser context, contains current cookies, local storage snapshot, IndexedDB snapshot and virtual WebAuthn credentials.## async method: BrowserContext.storageState* since: v1.8@@ -1566,10 +1566,21 @@ Returns storage state for this browser context, contains current cookies, localSet to `true` to include [IndexedDB](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API) in the storage state snapshot.If your application uses IndexedDB to store authentication tokens, like Firebase Authentication, enable this.+### option: BrowserContext.storageState.credentials+* since: v1.61+- `credentials` ?<boolean>++Set to `true` to include the context's virtual WebAuthn [`property: BrowserContext.credentials`] (passkeys) in the storage+state snapshot. The captured credentials carry their private keys, so they can be re-seeded into a later context via the+[`option: Browser.newContext.storageState`] option or [`method: BrowserContext.setStorageState`].+Note that restoring the storage state that contains credentials will automatically install the virtual WebAuthn authenticator (see [`method: Credentials.install`]), and prevent all real authenticators from working in this context.+## async method: BrowserContext.setStorageState* since: v1.59-Clears the existing cookies, local storage and IndexedDB entries for all origins and sets the new storage state.+Clears the existing cookies, local storage, IndexedDB entries and virtual WebAuthn credentials, and sets the new storage+state. When the storage state contains credentials, the virtual WebAuthn authenticator is installed (equivalent to+[`method: Credentials.install`]), preventing all real authenticators from working in this context.**Usage**diff --git a/docs/src/api/class-credentials.md b/docs/src/api/class-credentials.mdindex 4931be7729..16e056402c 100644--- a/docs/src/api/class-credentials.md+++ b/docs/src/api/class-credentials.md@@ -5,14 +5,15 @@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:+There are three common ways to use it:- **Seed a known credential.** The passkey already exists — for example, your backend provisionedit for a test user. Import it with [`method: Credentials.create`] so the app under test can signin right away. See the first example below.- **Capture a credential, then reuse it.** Let the app register a passkey once in a setup test,- read it back with [`method: Credentials.get`], and seed it into later tests — the same way- [`method: BrowserContext.storageState`] reuses signed-in state. See the second example below.+ read it back with [`method: Credentials.get`], and seed it into later tests. See the second example below.+- **Save credentials in the storage state, restore later.** Let the app register a passkey in a+ setup test and save it as part of the storage state by setting [`option: BrowserContext.storageState.credentials`]. See [authentication guide](../auth.md) for examples.**Usage: seed a known credential**@@ -103,10 +104,10 @@ 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**+**Usage: capture a credential, then reuse it**```js-// setup test: let the app register a passkey, then save it.+// setup test: let the app register a passkey, then save the storage state with it.const context = await browser.newContext();await context.credentials.install();@@ -264,6 +265,10 @@ await page.GotoAsync("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](../auth.md) for examples of using saving and resotring the storage state.+**Defaults**- The authenticator presents itself as a **platform** authenticator (`authenticatorAttachment` isdiff --git a/docs/src/auth.md b/docs/src/auth.mdindex 1853f6d62e..20d23d0247 100644--- a/docs/src/auth.md+++ b/docs/src/auth.md@@ -271,9 +271,9 @@ existing authentication state instead.Playwright provides a way to reuse the signed-in state in the tests. That way you can login only once and then skip the log in step for all of the tests.-Web apps use cookie-based or token-based authentication, where authenticated state is stored as [cookies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies), in [local storage](https://developer.mozilla.org/en-US/docs/Web/API/Storage) or in [IndexedDB](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API). Playwright provides [`method: BrowserContext.storageState`] method that can be used to retrieve storage state from authenticated contexts and then create new contexts with prepopulated state.+Web apps use cookie-based or token-based authentication, where authenticated state is stored as [cookies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies), in [local storage](https://developer.mozilla.org/en-US/docs/Web/API/Storage), in [IndexedDB](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API), or as passkeys ([WebAuthn](https://developer.mozilla.org/en-US/docs/Web/API/Web_Authentication_API) credentials). Playwright provides [`method: BrowserContext.storageState`] method that can be used to retrieve storage state from authenticated contexts and then create new contexts with prepopulated state.-Cookies, local storage and IndexedDB state can be used across different browsers. They depend on your application's authentication model which may require some combination of cookies, local storage or IndexedDB.+Cookies, local storage, IndexedDB and virtual WebAuthn credentials (passkeys) can be used across different browsers. They depend on your application's authentication model which may require some combination of cookies, local storage, IndexedDB or passkeys.The following code snippet retrieves state from an authenticated context and creates a new context with that state.@@ -397,74 +397,6 @@ export const test = baseTest.extend<{}, { workerStorageState: string }>({});```-### Passkeys (WebAuthn)-* langs: js--**When to use**-- Your app signs users in with passkeys (WebAuthn), and you want tests to start already enrolled.--**Details**--[`property: BrowserContext.credentials`] is a virtual WebAuthn authenticator. Unlike cookie or local storage state, a passkey is seeded **imperatively** with [`method: Credentials.create`] and [`method: Credentials.install`], so it lives in a [`context` fixture override](./test-fixtures.md#overriding-fixtures) rather than in the `storageState` config option.--If your backend already provisioned a passkey for the test user, seed it directly — no setup project required:--```js title="playwright/fixtures.ts"-import { test as baseTest } from '@playwright/test';-export * from '@playwright/test';--export const test = baseTest.extend({- context: async ({ context }, use) => {- // A passkey your backend provisioned for the test user.- await context.credentials.create('example.com', {- id: process.env.PASSKEY_ID,- userHandle: process.env.PASSKEY_USER_HANDLE,- privateKey: process.env.PASSKEY_PRIVATE_KEY,- publicKey: process.env.PASSKEY_PUBLIC_KEY,- });- await context.credentials.install();- await use(context);- },-});-```--Otherwise, let the app register a passkey once in a [setup project](#basic-shared-account-in-all-tests), capture it with [`method: Credentials.get`], and save it to disk:--```js title="tests/passkey.setup.ts"-import { test as setup } from '@playwright/test';-import fs from 'fs';--setup('enroll passkey', async ({ context, page }) => {- await context.credentials.install();- await page.goto('https://example.com/register');- // The app calls navigator.credentials.create() to register the passkey.- await page.getByRole('button', { name: 'Create a passkey' }).click();-- // Read back the registered passkey, including its private key, and save it.- const [credential] = await context.credentials.get({ rpId: 'example.com' });- fs.writeFileSync('playwright/.auth/passkey.json', JSON.stringify(credential));-});-```--Then seed the captured passkey into every test's context:--```js title="playwright/fixtures.ts"-import { test as baseTest } from '@playwright/test';-import fs from 'fs';-export * from '@playwright/test';--export const test = baseTest.extend({- context: async ({ context }, use) => {- const credential = JSON.parse(fs.readFileSync('playwright/.auth/passkey.json', 'utf8'));- await context.credentials.create(credential.rpId, credential);- await context.credentials.install();- await use(context);- },-});-```--Declare the `setup` project as a [dependency](./test-projects.md#dependencies) of your testing projects, just like in the [basic flow](#basic-shared-account-in-all-tests). The saved `passkey.json` contains a private key, so keep it under `playwright/.auth` and out of source control (see [Core concepts](#core-concepts)).-### Multiple signed in roles* langs: js@@ -656,7 +588,7 @@ test('admin and user', async ({ adminPage, userPage }) => {### Session storage-Reusing authenticated state covers [cookies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies), [local storage](https://developer.mozilla.org/en-US/docs/Web/API/Storage) and [IndexedDB](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API) based authentication. Rarely, [session storage](https://developer.mozilla.org/en-US/docs/Web/API/Window/sessionStorage) is used for storing information associated with the signed-in state. Session storage is specific to a particular domain and is not persisted across page loads. Playwright does not provide API to persist session storage, but the following snippet can be used to save/load session storage.+Reusing authenticated state covers [cookies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies), [local storage](https://developer.mozilla.org/en-US/docs/Web/API/Storage), [IndexedDB](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API) and passkey ([WebAuthn](https://developer.mozilla.org/en-US/docs/Web/API/Web_Authentication_API)) based authentication. Rarely, [session storage](https://developer.mozilla.org/en-US/docs/Web/API/Window/sessionStorage) is used for storing information associated with the signed-in state. Session storage is specific to a particular domain and is not persisted across page loads. Playwright does not provide API to persist session storage, but the following snippet can be used to save/load session storage.```js// Get session storage and store as env variablediff --git a/packages/playwright-client/types/types.d.ts b/packages/playwright-client/types/types.d.tsindex bfdaf7a204..8d99c632fe 100644--- a/packages/playwright-client/types/types.d.ts+++ b/packages/playwright-client/types/types.d.ts@@ -9635,7 +9635,10 @@ export interface BrowserContext {setOffline(offline: boolean): Promise<void>;/**- * Clears the existing cookies, local storage and IndexedDB entries for all origins and sets the new storage state.+ * Clears the existing cookies, local storage, IndexedDB entries and virtual WebAuthn credentials, and sets the new+ * storage state. When the storage state contains credentials, the virtual WebAuthn authenticator is installed+ * (equivalent to [credentials.install()](https://playwright.dev/docs/api/class-credentials#credentials-install)),+ * preventing all real authenticators from working in this context.** **Usage***@@ -9700,11 +9703,24 @@ export interface BrowserContext {}): Promise<void>;/**- * Returns storage state for this browser context, contains current cookies, local storage snapshot and IndexedDB- * snapshot.+ * Returns storage state for this browser context, contains current cookies, local storage snapshot, IndexedDB+ * snapshot and virtual WebAuthn credentials.* @param options*/storageState(options?: {+ /**+ * Set to `true` to include the context's virtual WebAuthn+ * [browserContext.credentials](https://playwright.dev/docs/api/class-browsercontext#browser-context-credentials)+ * (passkeys) in the storage state snapshot. The captured credentials carry their private keys, so they can be+ * re-seeded into a later context via the+ * [`storageState`](https://playwright.dev/docs/api/class-browser#browser-new-context-option-storage-state) option or+ * [browserContext.setStorageState(storageState)](https://playwright.dev/docs/api/class-browsercontext#browser-context-set-storage-state).+ * Note that restoring the storage state that contains credentials will automatically install the virtual WebAuthn+ * authenticator (see [credentials.install()](https://playwright.dev/docs/api/class-credentials#credentials-install)),+ * and prevent all real authenticators from working in this context.+ */+ credentials?: boolean;+/*** Set to `true` to include [IndexedDB](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API) in the storage* state snapshot. If your application uses IndexedDB to store authentication tokens, like Firebase Authentication,@@ -18888,7 +18904,7 @@ export interface Coverage {* `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:+ * There are three common ways to use it:** **Usage: seed a known credential***@@ -18909,10 +18925,10 @@ export interface Coverage {* // The page's navigator.credentials.get() is answered with the seeded passkey.* ```*- * **Usage: capture a passkey, then reuse it**+ * **Usage: capture a credential, then reuse it**** ```js- * // setup test: let the app register a passkey, then save it.+ * // setup test: let the app register a passkey, then save the storage state with it.* const context = await browser.newContext();* await context.credentials.install();*@@ -18937,6 +18953,10 @@ export interface Coverage {* // navigator.credentials.get() resolves the captured passkey — already signed in.* ```*+ * **Usage: save credentials in the storage state, restore later**+ *+ * See [authentication guide](https://playwright.dev/docs/auth) for examples of using saving and resotring the storage state.+ ** **Defaults***/export interface Credentials {diff --git a/packages/playwright-core/src/client/browserContext.ts b/packages/playwright-core/src/client/browserContext.tsindex e450deaeb8..b16b5dfc2d 100644--- a/packages/playwright-core/src/client/browserContext.ts+++ b/packages/playwright-core/src/client/browserContext.ts@@ -459,8 +459,8 @@ export class BrowserContext extends ChannelOwner<channels.BrowserContextChannel>});}- async storageState(options: { path?: string, indexedDB?: boolean } = {}): Promise<StorageState> {- const state = await this._channel.storageState({ indexedDB: options.indexedDB });+ async storageState(options: { path?: string, indexedDB?: boolean, credentials?: boolean } = {}): Promise<StorageState> {+ const state = await this._channel.storageState({ indexedDB: options.indexedDB, credentials: options.credentials });if (options.path) {await mkdirIfNeeded(this._platform, options.path);await this._platform.fs().promises.writeFile(options.path, JSON.stringify(state, undefined, 2), 'utf8');diff --git a/packages/playwright-core/src/client/channels.d.ts b/packages/playwright-core/src/client/channels.d.tsindex 3d116fac27..3387f0c599 100644--- a/packages/playwright-core/src/client/channels.d.ts+++ b/packages/playwright-core/src/client/channels.d.ts@@ -973,6 +973,7 @@ export type BrowserNewContextParams = {storageState?: {cookies?: SetNetworkCookie[],origins?: SetOriginStorage[],+ credentials?: VirtualCredential[],},};export type BrowserNewContextOptions = {@@ -1047,6 +1048,7 @@ export type BrowserNewContextOptions = {storageState?: {cookies?: SetNetworkCookie[],origins?: SetOriginStorage[],+ credentials?: VirtualCredential[],},};export type BrowserNewContextResult = {@@ -1124,6 +1126,7 @@ export type BrowserNewContextForReuseParams = {storageState?: {cookies?: SetNetworkCookie[],origins?: SetOriginStorage[],+ credentials?: VirtualCredential[],},};export type BrowserNewContextForReuseOptions = {@@ -1198,6 +1201,7 @@ export type BrowserNewContextForReuseOptions = {storageState?: {cookies?: SetNetworkCookie[],origins?: SetOriginStorage[],+ credentials?: VirtualCredential[],},};export type BrowserNewContextForReuseResult = {@@ -1594,24 +1598,29 @@ export type BrowserContextSetOfflineOptions = {export type BrowserContextSetOfflineResult = void;export type BrowserContextStorageStateParams = {indexedDB?: boolean,+ credentials?: boolean,};export type BrowserContextStorageStateOptions = {indexedDB?: boolean,+ credentials?: boolean,};export type BrowserContextStorageStateResult = {cookies: NetworkCookie[],origins: OriginStorage[],+ credentials?: VirtualCredential[],};export type BrowserContextSetStorageStateParams = {storageState?: {cookies?: SetNetworkCookie[],origins?: SetOriginStorage[],+ credentials?: VirtualCredential[],},};export type BrowserContextSetStorageStateOptions = {storageState?: {cookies?: SetNetworkCookie[],origins?: SetOriginStorage[],+ credentials?: VirtualCredential[],},};export type BrowserContextSetStorageStateResult = void;diff --git a/packages/playwright-core/src/client/types.ts b/packages/playwright-core/src/client/types.tsindex ee0ae314ce..7dadd12574 100644--- a/packages/playwright-core/src/client/types.ts+++ b/packages/playwright-core/src/client/types.ts@@ -45,7 +45,8 @@ export type StorageState = {};export type SetStorageState = {cookies?: channels.SetNetworkCookie[],- origins?: (Omit<channels.SetOriginStorage, 'indexedDB'> & { indexedDB?: unknown[] })[]+ origins?: (Omit<channels.SetOriginStorage, 'indexedDB'> & { indexedDB?: unknown[] })[],+ credentials?: unknown[],};export type LifecycleEvent = channels.LifecycleEvent;diff --git a/packages/playwright-core/src/protocol/validator.ts b/packages/playwright-core/src/protocol/validator.tsindex 4a9b428e56..e001312d87 100644--- a/packages/playwright-core/src/protocol/validator.ts+++ b/packages/playwright-core/src/protocol/validator.ts@@ -508,6 +508,7 @@ scheme.BrowserNewContextParams = tObject({storageState: tOptional(tObject({cookies: tOptional(tArray(tType('SetNetworkCookie'))),origins: tOptional(tArray(tType('SetOriginStorage'))),+ credentials: tOptional(tArray(tType('VirtualCredential'))),})),});scheme.BrowserNewContextResult = tObject({@@ -585,6 +586,7 @@ scheme.BrowserNewContextForReuseParams = tObject({storageState: tOptional(tObject({cookies: tOptional(tArray(tType('SetNetworkCookie'))),origins: tOptional(tArray(tType('SetOriginStorage'))),+ credentials: tOptional(tArray(tType('VirtualCredential'))),})),});scheme.BrowserNewContextForReuseResult = tObject({@@ -845,15 +847,18 @@ scheme.BrowserContextSetOfflineParams = tObject({scheme.BrowserContextSetOfflineResult = tOptional(tObject({}));scheme.BrowserContextStorageStateParams = tObject({indexedDB: tOptional(tBoolean),+ credentials: tOptional(tBoolean),});scheme.BrowserContextStorageStateResult = tObject({cookies: tArray(tType('NetworkCookie')),origins: tArray(tType('OriginStorage')),+ credentials: tOptional(tArray(tType('VirtualCredential'))),});scheme.BrowserContextSetStorageStateParams = tObject({storageState: tOptional(tObject({cookies: tOptional(tArray(tType('SetNetworkCookie'))),origins: tOptional(tArray(tType('SetOriginStorage'))),+ credentials: tOptional(tArray(tType('VirtualCredential'))),})),});scheme.BrowserContextSetStorageStateResult = tOptional(tObject({}));diff --git a/packages/playwright-core/src/server/browserContext.ts b/packages/playwright-core/src/server/browserContext.tsindex 2e1ea62038..d41805cd47 100644--- a/packages/playwright-core/src/server/browserContext.ts+++ b/packages/playwright-core/src/server/browserContext.ts@@ -245,7 +245,6 @@ export abstract class BrowserContext<EM extends EventMap = EventMap> extends Sdk// Note: we only need to reset properties from the "paramsThatAllowContextReuse" list.// All other properties force a new context.await this.clock.uninstall(progress);- await this.credentials.dispose(progress);await progress.race(this.setUserAgent(this._options.userAgent));await progress.race(this.doUpdateDefaultEmulatedMedia());await progress.race(this.doUpdateDefaultViewport());@@ -610,11 +609,13 @@ export abstract class BrowserContext<EM extends EventMap = EventMap> extends Sdkthis._origins.add(origin);}- async storageState(progress: Progress, indexedDB = false): Promise<channels.BrowserContextStorageStateResult> {+ async storageState(progress: Progress, indexedDB = false, credentials = false): Promise<channels.BrowserContextStorageStateResult> {const result: channels.BrowserContextStorageStateResult = {cookies: await this.cookies(progress),origins: []};+ if (credentials)+ result.credentials = await progress.race(this.credentials.get());const originsToSave = new Set(this._origins);const collectScript = `(() => {@@ -671,11 +672,21 @@ export abstract class BrowserContext<EM extends EventMap = EventMap> extends Sdkif (mode !== 'initial') {await progress.race(this.clearCache());await progress.race(this.doClearCookies());+ if (state?.credentials?.length)+ this.credentials.clear();+ else+ await this.credentials.dispose(progress);}if (state?.cookies)await progress.race(this.addCookies(state.cookies));+ if (state?.credentials?.length) {+ for (const credential of state.credentials)+ await progress.race(this.credentials.create(credential));+ await this.credentials.install(progress);+ }+const newOrigins = new Map(state?.origins?.map(p => [p.origin, p]) || []);const allOrigins = new Set([...this._origins, ...newOrigins.keys()]);if (allOrigins.size) {diff --git a/packages/playwright-core/src/server/channels.d.ts b/packages/playwright-core/src/server/channels.d.tsindex 01047a43f6..e70d98db23 100644--- a/packages/playwright-core/src/server/channels.d.ts+++ b/packages/playwright-core/src/server/channels.d.ts@@ -976,6 +976,7 @@ export type BrowserNewContextParams = {storageState?: {cookies?: SetNetworkCookie[],origins?: SetOriginStorage[],+ credentials?: VirtualCredential[],},};export type BrowserNewContextOptions = {@@ -1050,6 +1051,7 @@ export type BrowserNewContextOptions = {storageState?: {cookies?: SetNetworkCookie[],origins?: SetOriginStorage[],+ credentials?: VirtualCredential[],},};export type BrowserNewContextResult = {@@ -1127,6 +1129,7 @@ export type BrowserNewContextForReuseParams = {storageState?: {cookies?: SetNetworkCookie[],origins?: SetOriginStorage[],+ credentials?: VirtualCredential[],},};export type BrowserNewContextForReuseOptions = {@@ -1201,6 +1204,7 @@ export type BrowserNewContextForReuseOptions = {storageState?: {cookies?: SetNetworkCookie[],origins?: SetOriginStorage[],+ credentials?: VirtualCredential[],},};export type BrowserNewContextForReuseResult = {@@ -1597,24 +1601,29 @@ export type BrowserContextSetOfflineOptions = {export type BrowserContextSetOfflineResult = void;export type BrowserContextStorageStateParams = {indexedDB?: boolean,+ credentials?: boolean,};export type BrowserContextStorageStateOptions = {indexedDB?: boolean,+ credentials?: boolean,};export type BrowserContextStorageStateResult = {cookies: NetworkCookie[],origins: OriginStorage[],+ credentials?: VirtualCredential[],};export type BrowserContextSetStorageStateParams = {storageState?: {cookies?: SetNetworkCookie[],origins?: SetOriginStorage[],+ credentials?: VirtualCredential[],},};export type BrowserContextSetStorageStateOptions = {storageState?: {cookies?: SetNetworkCookie[],origins?: SetOriginStorage[],+ credentials?: VirtualCredential[],},};export type BrowserContextSetStorageStateResult = void;diff --git a/packages/playwright-core/src/server/credentials.ts b/packages/playwright-core/src/server/credentials.tsindex 5424f9bf06..b41bf29e37 100644--- a/packages/playwright-core/src/server/credentials.ts+++ b/packages/playwright-core/src/server/credentials.ts@@ -20,7 +20,7 @@ import * as rawWebAuthnSource from '../generated/webAuthnSource';import { nullProgress } from './progress';import type { BrowserContext } from './browserContext';-import type { InitScript } from './page';+import type { InitScript, PageBinding } from './page';import type { Progress } from './progress';const kBindingName = '__pwWebAuthnBinding';@@ -41,8 +41,8 @@ type CredentialRecord = VirtualCredential & {export class Credentials {private _browserContext: BrowserContext;- private _initScripts: InitScript[] = [];- private _installed = false;+ private _initScript: InitScript | undefined;+ private _binding: PageBinding | undefined;private _registry = new Map<string, CredentialRecord>();constructor(browserContext: BrowserContext) {@@ -90,18 +90,26 @@ export class Credentials {this._registry.delete(id);}+ clear() {+ this._registry.clear();+ }+async dispose(progress: Progress) {- await progress.race(Promise.all(this._initScripts.map(s => s.dispose())));- this._initScripts = [];- this._installed = false;+ if (this._initScript) {+ await progress.race(this._initScript.dispose());+ this._initScript = undefined;+ }+ if (this._binding) {+ await progress.race(this._binding.dispose());+ this._binding = undefined;+ }this._registry.clear();}async install(progress: Progress) {- if (this._installed)+ if (this._binding)return;- this._installed = true;- await this._browserContext.exposeBinding(progress, kBindingName, async (_source, payload: any) => {+ this._binding = await this._browserContext.exposeBinding(progress, kBindingName, async (_source, payload: any) => {try {if (payload?.type === 'create')return await this._handleCreate(payload);@@ -117,8 +125,7 @@ export class Credentials {${rawWebAuthnSource.source}module.exports.inject()(globalThis);})();`;- const initScript = await this._browserContext.addInitScript(nullProgress, script);- this._initScripts.push(initScript);+ this._initScript = await this._browserContext.addInitScript(nullProgress, script);await progress.race(this._browserContext.safeNonStallingEvaluateInAllFrames(script, 'main', { throwOnJSErrors: false }));}diff --git a/packages/playwright-core/src/server/dispatchers/browserContextDispatcher.ts b/packages/playwright-core/src/server/dispatchers/browserContextDispatcher.tsindex 5c33d784d0..fb57858e71 100644--- a/packages/playwright-core/src/server/dispatchers/browserContextDispatcher.ts+++ b/packages/playwright-core/src/server/dispatchers/browserContextDispatcher.ts@@ -336,7 +336,7 @@ export class BrowserContextDispatcher extends Dispatcher<BrowserContext, channel}async storageState(params: channels.BrowserContextStorageStateParams, progress: Progress): Promise<channels.BrowserContextStorageStateResult> {- return await this._context.storageState(progress, params.indexedDB);+ return await this._context.storageState(progress, params.indexedDB, params.credentials);}async setStorageState(params: channels.BrowserContextSetStorageStateParams, progress: Progress): Promise<void> {diff --git a/packages/playwright-core/types/types.d.ts b/packages/playwright-core/types/types.d.tsindex bfdaf7a204..8d99c632fe 100644--- a/packages/playwright-core/types/types.d.ts+++ b/packages/playwright-core/types/types.d.ts@@ -9635,7 +9635,10 @@ export interface BrowserContext {setOffline(offline: boolean): Promise<void>;/**- * Clears the existing cookies, local storage and IndexedDB entries for all origins and sets the new storage state.+ * Clears the existing cookies, local storage, IndexedDB entries and virtual WebAuthn credentials, and sets the new+ * storage state. When the storage state contains credentials, the virtual WebAuthn authenticator is installed+ * (equivalent to [credentials.install()](https://playwright.dev/docs/api/class-credentials#credentials-install)),+ * preventing all real authenticators from working in this context.** **Usage***@@ -9700,11 +9703,24 @@ export interface BrowserContext {}): Promise<void>;/**- * Returns storage state for this browser context, contains current cookies, local storage snapshot and IndexedDB- * snapshot.+ * Returns storage state for this browser context, contains current cookies, local storage snapshot, IndexedDB+ * snapshot and virtual WebAuthn credentials.* @param options*/storageState(options?: {+ /**+ * Set to `true` to include the context's virtual WebAuthn+ * [browserContext.credentials](https://playwright.dev/docs/api/class-browsercontext#browser-context-credentials)+ * (passkeys) in the storage state snapshot. The captured credentials carry their private keys, so they can be+ * re-seeded into a later context via the+ * [`storageState`](https://playwright.dev/docs/api/class-browser#browser-new-context-option-storage-state) option or+ * [browserContext.setStorageState(storageState)](https://playwright.dev/docs/api/class-browsercontext#browser-context-set-storage-state).+ * Note that restoring the storage state that contains credentials will automatically install the virtual WebAuthn+ * authenticator (see [credentials.install()](https://playwright.dev/docs/api/class-credentials#credentials-install)),+ * and prevent all real authenticators from working in this context.+ */+ credentials?: boolean;+/*** Set to `true` to include [IndexedDB](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API) in the storage* state snapshot. If your application uses IndexedDB to store authentication tokens, like Firebase Authentication,@@ -18888,7 +18904,7 @@ export interface Coverage {* `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:+ * There are three common ways to use it:** **Usage: seed a known credential***@@ -18909,10 +18925,10 @@ export interface Coverage {* // The page's navigator.credentials.get() is answered with the seeded passkey.* ```*- * **Usage: capture a passkey, then reuse it**+ * **Usage: capture a credential, then reuse it**** ```js- * // setup test: let the app register a passkey, then save it.+ * // setup test: let the app register a passkey, then save the storage state with it.* const context = await browser.newContext();* await context.credentials.install();*@@ -18937,6 +18953,10 @@ export interface Coverage {* // navigator.credentials.get() resolves the captured passkey — already signed in.* ```*+ * **Usage: save credentials in the storage state, restore later**+ *+ * See [authentication guide](https://playwright.dev/docs/auth) for examples of using saving and resotring the storage state.+ ** **Defaults***/export interface Credentials {diff --git a/packages/protocol/spec/browser.yml b/packages/protocol/spec/browser.ymlindex bc0b862165..2e7a4e5ecb 100644--- a/packages/protocol/spec/browser.yml+++ b/packages/protocol/spec/browser.yml@@ -76,6 +76,9 @@ Browser:origins:type: array?items: SetOriginStorage+ credentials:+ type: array?+ items: VirtualCredentialreturns:context: BrowserContext@@ -99,6 +102,9 @@ Browser:origins:type: array?items: SetOriginStorage+ credentials:+ type: array?+ items: VirtualCredentialreturns:context: BrowserContextdiff --git a/packages/protocol/spec/browserContext.yml b/packages/protocol/spec/browserContext.ymlindex 27ccc577d6..10c582f970 100644--- a/packages/protocol/spec/browserContext.yml+++ b/packages/protocol/spec/browserContext.yml@@ -179,6 +179,7 @@ BrowserContext:group: configurationparameters:indexedDB: boolean?+ credentials: boolean?returns:cookies:type: array@@ -186,6 +187,9 @@ BrowserContext:origins:type: arrayitems: OriginStorage+ credentials:+ type: array?+ items: VirtualCredentialsetStorageState:title: Set storage state@@ -200,6 +204,9 @@ BrowserContext:origins:type: array?items: SetOriginStorage+ credentials:+ type: array?+ items: VirtualCredentialpause:title: Pausediff --git a/tests/library/browsercontext-storage-state.spec.ts b/tests/library/browsercontext-storage-state.spec.tsindex b8b03daece..488e9b959a 100644--- a/tests/library/browsercontext-storage-state.spec.ts+++ b/tests/library/browsercontext-storage-state.spec.ts@@ -540,6 +540,47 @@ it('should support empty indexedDB', { annotation: { type: 'issue', description:expect(await context.storageState({ indexedDB: true })).toEqual(storageState);});+it('should round-trip WebAuthn credentials with storageState', async ({ contextFactory, server }) => {+ const context = await contextFactory();+ const credential = await context.credentials.create(server.HOSTNAME);++ // Credentials are opt-in, omitted by default.+ expect(await context.storageState()).toEqual({ cookies: [], origins: [] });++ const storageState = await context.storageState({ credentials: true });+ expect(storageState).toEqual({ cookies: [], origins: [], credentials: [credential] });++ // A fresh context seeded from the storage state holds the same credential and round-trips equal.+ const context2 = await contextFactory({ storageState });+ expect(await context2.credentials.get()).toEqual([credential]);+ expect(await context2.storageState({ credentials: true })).toEqual(storageState);+});++it('setStorageState should replace credentials', async ({ contextFactory }) => {+ const ctxA = await contextFactory();+ const credA = await ctxA.credentials.create('a.example.com');+ const stateA = await ctxA.storageState({ credentials: true });++ const ctxB = await contextFactory();+ const credB = await ctxB.credentials.create('b.example.com');+ const stateB = await ctxB.storageState({ credentials: true });++ const context = await contextFactory({ storageState: stateA });+ expect(await context.credentials.get()).toEqual([credA]);++ // Replacing the storage state swaps in the new credentials.+ await context.setStorageState(stateB);+ expect(await context.credentials.get()).toEqual([credB]);++ // A storage state without credentials clears them.+ await context.setStorageState({ cookies: [], origins: [] });+ expect(await context.credentials.get()).toEqual([]);++ // Credentials can be installed again afterwards.+ await context.setStorageState(stateA);+ expect(await context.credentials.get()).toEqual([credA]);+});+it('setStorageState should handle missing file', async ({ contextFactory }, testInfo) => {const context = await contextFactory();const file = testInfo.outputPath('does-not-exist.json');diff --git a/tests/library/browsercontext-webauthn.spec.ts b/tests/library/browsercontext-webauthn.spec.tsindex 9365936d9c..40ae4498c1 100644--- a/tests/library/browsercontext-webauthn.spec.ts+++ b/tests/library/browsercontext-webauthn.spec.ts@@ -155,3 +155,45 @@ it('should capture a page-created credential and reuse it in another context', aexpect(gotId).toBe(createdId);});++it('should reuse a page-created credential via the storageState option', async ({ contextFactory, server }) => {+ // Setup context: the app registers a passkey via navigator.credentials.create().+ const setupContext = await contextFactory();+ await setupContext.credentials.install();+ const setupPage = await setupContext.newPage();+ await setupPage.goto(server.EMPTY_PAGE);++ const createdId = await setupPage.evaluate(async ({ rpId }) => {+ const challenge = crypto.getRandomValues(new Uint8Array(32));+ const created = await navigator.credentials.create({+ publicKey: {+ challenge,+ rp: { id: rpId, name: 'Test RP' },+ user: { id: new Uint8Array([1, 2, 3, 4]), name: 'u', displayName: 'User' },+ pubKeyCredParams: [{ type: 'public-key', alg: -7 }],+ authenticatorSelection: { residentKey: 'required', userVerification: 'preferred' },+ },+ }) as PublicKeyCredential;+ return created.id;+ }, { rpId: server.HOSTNAME });++ // Capture the passkey as part of the storage state.+ const storageState = await setupContext.storageState({ credentials: true });++ // A context created from the storage state has the authenticator installed and signs in with+ // the captured passkey — without calling install() again.+ const context = await contextFactory({ storageState });+ const page = await context.newPage();+ await page.goto(server.EMPTY_PAGE);++ const gotId = await page.evaluate(async ({ rpId }) => {+ const challenge = crypto.getRandomValues(new Uint8Array(32));+ // No allowCredentials — relies on the re-seeded credential being discoverable.+ const cred = await navigator.credentials.get({+ publicKey: { challenge, rpId, userVerification: 'preferred' },+ }) as PublicKeyCredential;+ return cred.id;+ }, { rpId: server.HOSTNAME });++ expect(gotId).toBe(createdId);+});