Document public methods

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 "./";

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();
 

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<Page, { page: Page; playId: string }> {
   return async ({ page, playId }, use) => {
     await addInitScriptForPlayId(page, playId);
@@ -7,6 +8,7 @@ export function pageExtension(): TestFixture<Page, { page: Page; playId: string
   };
 }
 
+/** Adds an init script to the given page that monkey-patches fetch requests to include an `x-play-id` header */
 export function addInitScriptForPlayId(page: Page, playId: string): Promise<void> {
   return page.addInitScript(
     ({ p }) => {

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<T>(page: Page, userId: UserId, keyDefinition: UserKeyDefinition<T>): Promise<T | null> {
     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<T>(
     page: Page,
     userId: UserId,

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;

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<TUp, TReturns> {
   abstract template: string;
 

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> = T extends SceneTemplate<infer U, any> ? 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<TUp, TReturns = void> {
   abstract template: string;
   private seedId?: string;