From 9587cfacfa7a3f79da96890350c4e68b3df6231b Mon Sep 17 00:00:00 2001
From: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
Date: Wed, 3 Apr 2024 11:02:41 +0100
Subject: [PATCH] playwright: Document some of the fixtures (#12388)

---
 playwright/element-web-test.ts     | 37 +++++++++++++++++++++++++++---
 playwright/pages/ElementAppPage.ts |  3 +++
 2 files changed, 37 insertions(+), 3 deletions(-)

diff --git a/playwright/element-web-test.ts b/playwright/element-web-test.ts
index 21407d2585..a524c139f6 100644
--- a/playwright/element-web-test.ts
+++ b/playwright/element-web-test.ts
@@ -66,12 +66,32 @@ export const test = base.extend<
     TestOptions & {
         axe: AxeBuilder;
         checkA11y: () => Promise<void>;
-        // The contents of the config.json to send
+
+        /**
+         * The contents of the config.json to send when the client requests it.
+         */
         config: typeof CONFIG_JSON;
-        // The options with which to run the `homeserver` fixture
+
+        /**
+         * The options with which to run the {@link #homeserver} fixture.
+         */
         startHomeserverOpts: StartHomeserverOpts | string;
+
         homeserver: HomeserverInstance;
         oAuthServer: { port: number };
+
+        /**
+         * The displayname to use for the user registered in {@link #credentials}.
+         *
+         * To set it, call `test.use({ displayName: "myDisplayName" })` in the test file or `describe` block.
+         * See {@link https://playwright.dev/docs/api/class-test#test-use}.
+         */
+        displayName?: string;
+
+        /**
+         * A test fixture which registers a test user on the {@link #homeserver} and supplies the details
+         * of the registered user.
+         */
         credentials: CredentialsWithDisplayName;
 
         /**
@@ -83,9 +103,20 @@ export const test = base.extend<
          */
         pageWithCredentials: Page;
 
+        /**
+         * A (rather poorly-named) test fixture which registers a user per {@link #credentials}, stores
+         * the credentials into localStorage per {@link #homeserver}, and then loads the front page of the
+         * app.
+         */
         user: CredentialsWithDisplayName;
-        displayName?: string;
+
+        /**
+         * The same as {@link https://playwright.dev/docs/api/class-fixtures#fixtures-page|`page`},
+         * but wraps the returned `Page` in a class of utilities for interacting with the Element-Web UI,
+         * {@link ElementAppPage}.
+         */
         app: ElementAppPage;
+
         mailhog: { api: mailhog.API; instance: Instance };
         crypto: Crypto;
         room?: { roomId: string };
diff --git a/playwright/pages/ElementAppPage.ts b/playwright/pages/ElementAppPage.ts
index babb44f881..ac9b4ffef8 100644
--- a/playwright/pages/ElementAppPage.ts
+++ b/playwright/pages/ElementAppPage.ts
@@ -21,6 +21,9 @@ import { Client } from "./client";
 import { Timeline } from "./timeline";
 import { Spotlight } from "./Spotlight";
 
+/**
+ * A set of utility methods for interacting with the Element-Web UI.
+ */
 export class ElementAppPage {
     public constructor(public readonly page: Page) {}