From b7c75104ebd1abd345e327d93b4c958919315862 Mon Sep 17 00:00:00 2001 From: Matt Gibson Date: Tue, 27 Jan 2026 14:10:54 -0800 Subject: [PATCH] Document public methods --- libs/playwright-helpers/src/example.play.spec.ts | 3 +++ libs/playwright-helpers/src/expect/auth.ts | 3 +++ libs/playwright-helpers/src/fixtures/page-extension.ts | 2 ++ .../playwright-helpers/src/fixtures/user-state.fixture.ts | 3 +++ .../src/queries/emergency-access-invite.query.ts | 1 + libs/playwright-helpers/src/queries/query.ts | 8 ++++++++ .../src/scene-templates/scene-template.ts | 6 ++++++ 7 files changed, 26 insertions(+) diff --git a/libs/playwright-helpers/src/example.play.spec.ts b/libs/playwright-helpers/src/example.play.spec.ts index e0c3c9a9f5b..8608cceb0a8 100644 --- a/libs/playwright-helpers/src/example.play.spec.ts +++ b/libs/playwright-helpers/src/example.play.spec.ts @@ -1,3 +1,6 @@ +// This file contains example tests that demonstrate some of the helpers provided +// by the playwright-helpers library. + import { expectUnlockedAs } from "./expect/auth"; import { test } from "./"; diff --git a/libs/playwright-helpers/src/expect/auth.ts b/libs/playwright-helpers/src/expect/auth.ts index 2f6d37909c8..c809b6814fe 100644 --- a/libs/playwright-helpers/src/expect/auth.ts +++ b/libs/playwright-helpers/src/expect/auth.ts @@ -1,6 +1,9 @@ import { Page } from "playwright"; import { expect } from "playwright/test"; +/** + * Asserts that the application is unlocked as the specified user (by email or name). + */ export async function expectUnlockedAs(emailOrName: string, page: Page) { const currentUri = page.url(); diff --git a/libs/playwright-helpers/src/fixtures/page-extension.ts b/libs/playwright-helpers/src/fixtures/page-extension.ts index d74681bac39..aa4e0dd3f0f 100644 --- a/libs/playwright-helpers/src/fixtures/page-extension.ts +++ b/libs/playwright-helpers/src/fixtures/page-extension.ts @@ -1,5 +1,6 @@ import { Page, TestFixture } from "@playwright/test"; +/** Creates a fixture method which updates the page fixture to monkey-patch fetch requests to include an `x-play-id` header*/ export function pageExtension(): TestFixture { return async ({ page, playId }, use) => { await addInitScriptForPlayId(page, playId); @@ -7,6 +8,7 @@ export function pageExtension(): TestFixture { return page.addInitScript( ({ p }) => { diff --git a/libs/playwright-helpers/src/fixtures/user-state.fixture.ts b/libs/playwright-helpers/src/fixtures/user-state.fixture.ts index c690a287bbd..ff67149b4e0 100644 --- a/libs/playwright-helpers/src/fixtures/user-state.fixture.ts +++ b/libs/playwright-helpers/src/fixtures/user-state.fixture.ts @@ -3,6 +3,7 @@ import { Page, TestFixture } from "@playwright/test"; import { UserKeyDefinition } from "@bitwarden/state"; import { UserId } from "@bitwarden/user-core"; +/** Fixture to provide direct access to User state */ export class UserStateFixture { /** Creates a fixture method for {@link UserStateFixture} to extend playwright tests */ // eslint-disable-next-line @typescript-eslint/no-empty-object-type @@ -14,6 +15,7 @@ export class UserStateFixture { }; } + /** Gets a value from user state */ async get(page: Page, userId: UserId, keyDefinition: UserKeyDefinition): Promise { let json: string | null; switch (keyDefinition.stateDefinition.defaultStorageLocation) { @@ -35,6 +37,7 @@ export class UserStateFixture { return json == null ? null : (JSON.parse(json) as T); } + /** Sets a value to user state */ async set( page: Page, userId: UserId, diff --git a/libs/playwright-helpers/src/queries/emergency-access-invite.query.ts b/libs/playwright-helpers/src/queries/emergency-access-invite.query.ts index a9f6e7b4354..5eef5a70410 100644 --- a/libs/playwright-helpers/src/queries/emergency-access-invite.query.ts +++ b/libs/playwright-helpers/src/queries/emergency-access-invite.query.ts @@ -1,5 +1,6 @@ import { Query } from "./query"; +/** Takes the email of the grantee and returns a list of invite links for the grantee account */ export class EmergencyAccessInviteQuery extends Query< { email: string; diff --git a/libs/playwright-helpers/src/queries/query.ts b/libs/playwright-helpers/src/queries/query.ts index 4357c553d7a..697ea2dc6d3 100644 --- a/libs/playwright-helpers/src/queries/query.ts +++ b/libs/playwright-helpers/src/queries/query.ts @@ -3,6 +3,14 @@ import { webServerBaseUrl } from "@playwright-config"; // First seed points at the seeder API proxy, second is the query path of the QueryController const queryApiUrl = new URL("/seed/query", webServerBaseUrl).toString(); +/** + * A Query represents a request to the server to fetch data without modifying server state. + * It is created by providing a Query Template name and the arguments required by the server to fulfill the query. + * + * Queries are intended to be executed through the {@link Play.query} method. + * + * Queries have a different structure to Scenes, because they do not need to track internal state to manage setup and teardown. + */ export abstract class Query { abstract template: string; diff --git a/libs/playwright-helpers/src/scene-templates/scene-template.ts b/libs/playwright-helpers/src/scene-templates/scene-template.ts index 3beca507f35..d9f92ea78e1 100644 --- a/libs/playwright-helpers/src/scene-templates/scene-template.ts +++ b/libs/playwright-helpers/src/scene-templates/scene-template.ts @@ -5,6 +5,12 @@ const seedApiUrl = new URL("/seed/seed/", webServerBaseUrl).toString(); export type extractTUpType = T extends SceneTemplate ? U : never; +/** + * A SceneTemplate represents a predefined set of data and state to be created on the server for testing purposes. + * It contains the arguments required by the server to create the data. + * + * SceneTemplates are intended to be used to create {@link Scene} instances through the {@link Play.scene} method. + */ export abstract class SceneTemplate { abstract template: string; private seedId?: string;