@element-hq/element-web-playwright-common 3.0.0 → 4.0.0

package/Dockerfile

@@ -6,10 +6,17 @@ ARG PLAYWRIGHT_VERSION
 WORKDIR /work
 
 # fonts-dejavu is needed for the same RTL rendering as on CI
-RUN apt-get update && apt-get -y install docker.io fonts-dejavu
+RUN apt-get update && \
+    apt-get -y install docker.io fonts-dejavu && \
+    apt-get purge -y --auto-remove && \
+    rm -rf /var/lib/apt/lists/*
+
 # Install the matching playwright runtime, the docker image only includes browsers
 RUN npm i -g playwright@${PLAYWRIGHT_VERSION}
 
+# switch to pwuser
+USER 1001:1001
+
 COPY docker-entrypoint.sh /docker-entrypoint.sh
 
 # We use `docker-init` as PID 1, which means that the container shuts down correctly on SIGTERM.

package/lib/fixtures/toasts.d.ts

@@ -0,0 +1,73 @@
+import { type Locator, type Page } from "@playwright/test";
+export declare const test: import("playwright/test").TestType<import("playwright/test").PlaywrightTestArgs & import("playwright/test").PlaywrightTestOptions & {
+    axe: import("@axe-core/playwright").AxeBuilder;
+} & import("./services.js").TestFixtures & {
+    /**
+     * Convenience functions for handling toasts.
+     */
+    toasts: Toasts;
+}, import("playwright/test").PlaywrightWorkerArgs & import("playwright/test").PlaywrightWorkerOptions & import("./services.js").WorkerOptions & import("./services.js").Services>;
+declare class Toasts {
+    readonly page: Page;
+    constructor(page: Page);
+    /**
+     * Assert that no toasts exist.
+     */
+    assertNoToasts(): Promise<void>;
+    /**
+     * Return the toast with the supplied title. Fail or return null if it does
+     * not exist.
+     *
+     * If `required` is false, you should supply a relatively short `timeout`
+     * (e.g. 2000, meaning 2 seconds) to prevent your test taking too long.
+     *
+     * @param title - Expected title of the toast.
+     * @param timeout - Time in ms before we give up and decide the toast does
+     *                  not exist. If `required` is true, defaults to `timeout`
+     *                  in `TestConfig.expect`. Otherwise, defaults to 2000 (2
+     *                  seconds).
+     * @param required - If true, fail the test (throw an exception) if the
+     *                   toast is not visible. Otherwise, just return null if
+     *                   the toast is not visible.
+     * @returns the Locator for the matching toast, or null if it is not
+     *          visible. (null will only be returned if `required` is false.)
+     */
+    getToast(title: string, timeout?: number, required?: true): Promise<Locator>;
+    getToast(title: string, timeout: number | undefined, required: false): Promise<Locator | null>;
+    /**
+     * Accept the toast with the supplied title, or fail if it does not exist.
+     *
+     * Only works if this toast is at the top of the stack of toasts.
+     *
+     * @param title - Expected title of the toast.
+     */
+    acceptToast(title: string): Promise<void>;
+    /**
+     * Accept the toast with the supplied title, if it exists, or return after 2
+     * seconds if it is not found.
+     *
+     * Only works if this toast is at the top of the stack of toasts.
+     *
+     * @param title - Expected title of the toast.
+     */
+    acceptToastIfExists(title: string): Promise<void>;
+    /**
+     * Reject the toast with the supplied title, or fail if it does not exist.
+     *
+     * Only works if this toast is at the top of the stack of toasts.
+     *
+     * @param title - Expected title of the toast.
+     */
+    rejectToast(title: string): Promise<void>;
+    /**
+     * Reject the toast with the supplied title, if it exists, or return after 2
+     * seconds if it is not found.
+     *
+     * Only works if this toast is at the top of the stack of toasts.
+     *
+     * @param title - Expected title of the toast.
+     */
+    rejectToastIfExists(title: string): Promise<void>;
+}
+export {};
+//# sourceMappingURL=toasts.d.ts.map

package/lib/fixtures/toasts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"toasts.d.ts","sourceRoot":"","sources":["../../src/fixtures/toasts.ts"],"names":[],"mappings":"AAOA,OAAO,EAAU,KAAK,OAAO,EAAE,KAAK,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAQnE,eAAO,MAAM,IAAI;;;IACb;;OAEG;YACK,MAAM;iLAMhB,CAAC;AAEH,cAAM,MAAM;aAC2B,IAAI,EAAE,IAAI;gBAAV,IAAI,EAAE,IAAI;IAE7C;;OAEG;IACU,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5C;;;;;;;;;;;;;;;;;OAiBG;IACU,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC;IAC5E,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,SAAS,EAAE,QAAQ,EAAE,KAAK,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC;IAqB3G;;;;;;OAMG;IACU,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAItD;;;;;;;OAOG;IACU,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI9D;;;;;;OAMG;IACU,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAItD;;;;;;;OAOG;IACU,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAGjE"}

package/lib/fixtures/toasts.js

@@ -0,0 +1,124 @@
+/*
+ * Copyright 2026 Element Creations Ltd.
+ *
+ * SPDX-License-Identifier: AGPL-3.0-only OR GPL-3.0-only OR LicenseRef-Element-Commercial
+ * Please see LICENSE files in the repository root for full details.
+ */
+import { expect } from "@playwright/test";
+// We want to avoid using `mergeTests` in index.ts because it drops useful type
+// information about the fixtures. Instead, we add `services` into our fixture
+// suite by using its `test` as a base, so that there is a linear hierarchy.
+import { test as base } from "./services.js";
+// This fixture provides convenient handling of Element Web's toasts.
+export const test = base.extend({
+    toasts: async ({ page }, use) => {
+        const toasts = new Toasts(page);
+        await use(toasts);
+    },
+});
+class Toasts {
+    page;
+    constructor(page) {
+        this.page = page;
+    }
+    /**
+     * Assert that no toasts exist.
+     */
+    async assertNoToasts() {
+        await expect(this.page.locator(".mx_Toast_toast")).not.toBeVisible();
+    }
+    async getToast(title, timeout, required = true) {
+        const toast = this.page.locator(".mx_Toast_toast", { hasText: title }).first();
+        if (required) {
+            await expect(toast).toBeVisible({ timeout });
+            return toast;
+        }
+        else {
+            // If we don't set a timeout, waitFor will wait forever. Since
+            // required is false, we definitely don't want to wait forever.
+            timeout = timeout ?? 2000;
+            try {
+                await toast.waitFor({ state: "visible", timeout });
+                return toast;
+            }
+            catch {
+                return null;
+            }
+        }
+    }
+    /**
+     * Accept the toast with the supplied title, or fail if it does not exist.
+     *
+     * Only works if this toast is at the top of the stack of toasts.
+     *
+     * @param title - Expected title of the toast.
+     */
+    async acceptToast(title) {
+        return await clickToastButton(this, title, "primary");
+    }
+    /**
+     * Accept the toast with the supplied title, if it exists, or return after 2
+     * seconds if it is not found.
+     *
+     * Only works if this toast is at the top of the stack of toasts.
+     *
+     * @param title - Expected title of the toast.
+     */
+    async acceptToastIfExists(title) {
+        return await clickToastButton(this, title, "primary", 2000, false);
+    }
+    /**
+     * Reject the toast with the supplied title, or fail if it does not exist.
+     *
+     * Only works if this toast is at the top of the stack of toasts.
+     *
+     * @param title - Expected title of the toast.
+     */
+    async rejectToast(title) {
+        return await clickToastButton(this, title, "secondary");
+    }
+    /**
+     * Reject the toast with the supplied title, if it exists, or return after 2
+     * seconds if it is not found.
+     *
+     * Only works if this toast is at the top of the stack of toasts.
+     *
+     * @param title - Expected title of the toast.
+     */
+    async rejectToastIfExists(title) {
+        return await clickToastButton(this, title, "secondary", 2000, false);
+    }
+}
+/**
+ * Find the toast with the supplied title and click a button on it.
+ *
+ * Only works if this toast is at the top of the stack of toasts.
+ *
+ * If `required` is false, you should supply a relatively short `timeout`
+ * (e.g. 2000, meaning 2 seconds) to prevent your test taking too long.
+ *
+ * @param toasts - A Toasts instance.
+ * @param title - Expected title of the toast.
+ * @param button - Which button to click on the toast. Allowed values are
+ *                 "primary", which will accept the toast, or "secondary",
+ *                 which will reject it.
+ * @param timeout - Time in ms before we give up and decide the toast does
+ *                  not exist. If `required` is true, defaults to `timeout`
+ *                  in `TestConfig.expect`. Otherwise, defaults to 2000 (2
+ *                  seconds).
+ * @param required - If true, fail the test (throw an exception) if the
+ *                   toast is not visible. Otherwise, just return after
+ *                   `timeout` if the toast is not visible.
+ */
+async function clickToastButton(toasts, title, button, timeout, required = true) {
+    let toast;
+    if (required) {
+        toast = await toasts.getToast(title, timeout, true);
+    }
+    else {
+        toast = await toasts.getToast(title, timeout, false);
+    }
+    if (toast) {
+        await toast.locator(`.mx_Toast_buttons button[data-kind="${button}"]`).click();
+    }
+}

package/lib/fixtures/user.d.ts

@@ -5,6 +5,17 @@ export declare function populateLocalStorageWithCredentials(page: Page, credenti
 export declare const test: import("playwright/test").TestType<import("playwright/test").PlaywrightTestArgs & import("playwright/test").PlaywrightTestOptions & {
     axe: import("@axe-core/playwright").AxeBuilder;
 } & import("./services.js").TestFixtures & {
+    toasts: {
+        readonly page: Page;
+        assertNoToasts(): Promise<void>;
+        getToast(title: string, timeout?: number, required?: true): Promise<import("playwright-core").Locator>;
+        getToast(title: string, timeout: number | undefined, required: false): Promise<import("playwright-core").Locator | null>;
+        acceptToast(title: string): Promise<void>;
+        acceptToastIfExists(title: string): Promise<void>;
+        rejectToast(title: string): Promise<void>;
+        rejectToastIfExists(title: string): Promise<void>;
+    };
+} & {
     /**
      * The displayname to use for the user registered in {@link #credentials}.
      *

package/lib/fixtures/user.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"user.d.ts","sourceRoot":"","sources":["../../src/fixtures/user.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,KAAK,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAI7C,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAEnD,0IAA0I;AAC1I,wBAAsB,mCAAmC,CAAC,IAAI,EAAE,IAAI,EAAE,WAAW,EAAE,WAAW,iBAuB7F;AAED,eAAO,MAAM,IAAI;;;IACb;;;;;OAKG;kBACW,MAAM;IAEpB;;;OAGG;iBACU,WAAW;IAExB;;;;;;OAMG;yBACkB,IAAI;IAEzB;;;;OAIG;UACG,WAAW;iLA+BnB,CAAC"}
+{"version":3,"file":"user.d.ts","sourceRoot":"","sources":["../../src/fixtures/user.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,KAAK,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAO7C,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAEnD,0IAA0I;AAC1I,wBAAsB,mCAAmC,CAAC,IAAI,EAAE,IAAI,EAAE,WAAW,EAAE,WAAW,iBAuB7F;AAED,eAAO,MAAM,IAAI;;;;;;;;;;;;;;IACb;;;;;OAKG;kBACW,MAAM;IAEpB;;;OAGG;iBACU,WAAW;IAExB;;;;;;OAMG;yBACkB,IAAI;IAEzB;;;;OAIG;UACG,WAAW;iLA+BnB,CAAC"}

package/lib/fixtures/user.js

@@ -6,7 +6,10 @@ SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
 Please see LICENSE files in the repository root for full details.
 */
 import { sample, uniqueId } from "lodash-es";
-import { test as base } from "./services.js";
+// We want to avoid using `mergeTests` in index.ts because it drops useful type
+// information about the fixtures. Instead, we add `toasts` into our fixture
+// suite by using its `test` as a base, so that there is a linear hierarchy.
+import { test as base } from "./toasts.js";
 /** Adds an initScript to the given page which will populate localStorage appropriately so that Element will use the given credentials. */
 export async function populateLocalStorageWithCredentials(page, credentials) {
     await page.addInitScript(({ credentials }) => {

package/lib/index.d.ts

@@ -41,6 +41,17 @@ export interface TestFixtures {
 export declare const test: import("playwright/test").TestType<import("playwright/test").PlaywrightTestArgs & import("playwright/test").PlaywrightTestOptions & {
     axe: import("@axe-core/playwright").AxeBuilder;
 } & import("./fixtures/services.js").TestFixtures & {
+    toasts: {
+        readonly page: import("playwright-core").Page;
+        assertNoToasts(): Promise<void>;
+        getToast(title: string, timeout?: number, required?: true): Promise<import("playwright-core").Locator>;
+        getToast(title: string, timeout: number | undefined, required: false): Promise<import("playwright-core").Locator | null>;
+        acceptToast(title: string): Promise<void>;
+        acceptToastIfExists(title: string): Promise<void>;
+        rejectToast(title: string): Promise<void>;
+        rejectToastIfExists(title: string): Promise<void>;
+    };
+} & {
     displayName?: string;
     credentials: import("./utils/api.js").Credentials;
     pageWithCredentials: import("playwright-core").Page;

package/lib/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,KAAK,MAAM,IAAI,UAAU,EAAE,MAAM,oCAAoC,CAAC;AAK/E,cAAc,wBAAwB,CAAC;AACvC,cAAc,oBAAoB,CAAC;AAEnC,OAAO,EAAE,mCAAmC,EAAE,MAAM,oBAAoB,CAAC;AAQzE,MAAM,WAAW,MAAO,SAAQ,UAAU;IACtC,qBAAqB,EAAE;QACnB,cAAc,CAAC,EAAE;YACb,QAAQ,EAAE,MAAM,CAAC;YACjB,WAAW,CAAC,EAAE,MAAM,CAAC;SACxB,CAAC;QACF,mBAAmB,CAAC,EAAE;YAClB,QAAQ,EAAE,MAAM,CAAC;YACjB,WAAW,CAAC,EAAE,MAAM,CAAC;SACxB,CAAC;KACL,CAAC;IACF,yBAAyB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpD,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC1C,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB;AAGD,eAAO,MAAM,WAAW,EAAE,OAAO,CAAC,MAAM,CAevC,CAAC;AAEF,MAAM,WAAW,YAAY;IACzB;;OAEG;IACH,MAAM,EAAE,OAAO,CAAC,OAAO,WAAW,CAAC,CAAC;IAEpC,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,eAAe,EAAE,OAAO,CAAC;IACzB;;;;;;;;OAQG;IACH,kBAAkB,EAAE,OAAO,CAAC;CAC/B;AAED,eAAO,MAAM,IAAI;;;;;;;kNAmBf,CAAC;AAEH,OAAO,EAAE,MAAM,EAAE,KAAK,wBAAwB,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,KAAK,MAAM,IAAI,UAAU,EAAE,MAAM,oCAAoC,CAAC;AAK/E,cAAc,wBAAwB,CAAC;AACvC,cAAc,oBAAoB,CAAC;AAEnC,OAAO,EAAE,mCAAmC,EAAE,MAAM,oBAAoB,CAAC;AAQzE,MAAM,WAAW,MAAO,SAAQ,UAAU;IACtC,qBAAqB,EAAE;QACnB,cAAc,CAAC,EAAE;YACb,QAAQ,EAAE,MAAM,CAAC;YACjB,WAAW,CAAC,EAAE,MAAM,CAAC;SACxB,CAAC;QACF,mBAAmB,CAAC,EAAE;YAClB,QAAQ,EAAE,MAAM,CAAC;YACjB,WAAW,CAAC,EAAE,MAAM,CAAC;SACxB,CAAC;KACL,CAAC;IACF,yBAAyB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpD,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC1C,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB;AAGD,eAAO,MAAM,WAAW,EAAE,OAAO,CAAC,MAAM,CAevC,CAAC;AAEF,MAAM,WAAW,YAAY;IACzB;;OAEG;IACH,MAAM,EAAE,OAAO,CAAC,OAAO,WAAW,CAAC,CAAC;IAEpC,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,eAAe,EAAE,OAAO,CAAC;IACzB;;;;;;;;OAQG;IACH,kBAAkB,EAAE,OAAO,CAAC;CAC/B;AAED,eAAO,MAAM,IAAI;;;;;;;;;;;;;;;;;;kNAmBf,CAAC;AAEH,OAAO,EAAE,MAAM,EAAE,KAAK,wBAAwB,EAAE,MAAM,mBAAmB,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@element-hq/element-web-playwright-common",
     "type": "module",
-    "version": "3.0.0",
+    "version": "4.0.0",
     "license": "SEE LICENSE IN README.md",
     "repository": {
         "type": "git",
@@ -19,13 +19,12 @@
     },
     "scripts": {
         "prepack": "nx build:playwright",
-        "lint:types": "tsc --noEmit"
+        "lint:types": "nx lint:types"
     },
     "devDependencies": {
-        "@element-hq/element-web-module-api": "*",
+        "@element-hq/element-web-module-api": "workspace:*",
         "@types/lodash-es": "^4.17.12",
-        "typescript": "^5.8.2",
-        "wait-on": "^9.0.4"
+        "typescript": "^6.0.0"
     },
     "dependencies": {
         "@axe-core/playwright": "^4.10.1",
@@ -35,6 +34,7 @@
         "mailpit-api": "^1.2.0",
         "strip-ansi": "^7.1.0",
         "testcontainers": "^11.0.0",
+        "wait-on": "^9.0.4",
         "yaml": "^2.7.0"
     },
     "peerDependencies": {

package/playwright-screenshots.sh

@@ -9,7 +9,7 @@ SCRIPT_DIR=$(dirname "$SCRIPT_PATH")
 function build_image() {
     local IMAGE_NAME="$1"
 
-    echo "Building $IMAGE_NAME image in $SCRIPT_DIR"
+    echo "playwright-screenshots: Building $IMAGE_NAME image in $SCRIPT_DIR"
     docker build -t "$IMAGE_NAME" --build-arg "PLAYWRIGHT_VERSION=${IMAGE_NAME#*:}" "$SCRIPT_DIR"
 }
 
@@ -34,16 +34,19 @@ CONTAINER=$(docker run --network=host -v /tmp:/tmp --rm -d -e PORT="$WS_PORT" "$
 # Set up an exit trap to clean up the docker container
 clean_up() {
     ARG=$?
-    echo "Stopping playwright-server"
+    echo "playwright-screenshots: Stopping playwright-server"
     docker stop "$CONTAINER" > /dev/null
     exit $ARG
 }
 trap clean_up EXIT
 
 # Wait for playwright-server to be ready
-echo "Waiting for playwright-server"
+echo "playwright-screenshots: Waiting for playwright-server"
 pnpm --dir "$SCRIPT_DIR" exec wait-on "tcp:$WS_PORT"
 
+# Playwright seems to overwrite the last line from the console, so add an
+# extra newline to make sure this doesn't get lost.
+echo -e "playwright-screenshots: Running '$@'\n"
+
 # Run the test we were given, setting PW_TEST_CONNECT_WS_ENDPOINT accordingly
-echo "Running '$@'"
 PW_TEST_CONNECT_WS_ENDPOINT="http://localhost:$WS_PORT" "$@"

package/project.json

@@ -8,7 +8,13 @@
             "command": "tsc",
             "inputs": ["src"],
             "outputs": ["{projectRoot}/lib"],
-            "options": { "cwd": "packages/playwright-common" }
+            "options": { "cwd": "packages/playwright-common" },
+            "dependsOn": ["^build"]
+        },
+        "lint:types": {
+            "command": "pnpm exec tsc --noEmit",
+            "options": { "cwd": "packages/playwright-common" },
+            "dependsOn": ["^build"]
         },
         "docker:prebuild": {
             "cache": true,

package/src/fixtures/toasts.ts

@@ -0,0 +1,163 @@
+/*
+ * Copyright 2026 Element Creations Ltd.
+ *
+ * SPDX-License-Identifier: AGPL-3.0-only OR GPL-3.0-only OR LicenseRef-Element-Commercial
+ * Please see LICENSE files in the repository root for full details.
+ */
+
+import { expect, type Locator, type Page } from "@playwright/test";
+
+// We want to avoid using `mergeTests` in index.ts because it drops useful type
+// information about the fixtures. Instead, we add `services` into our fixture
+// suite by using its `test` as a base, so that there is a linear hierarchy.
+import { test as base } from "./services.js";
+
+// This fixture provides convenient handling of Element Web's toasts.
+export const test = base.extend<{
+    /**
+     * Convenience functions for handling toasts.
+     */
+    toasts: Toasts;
+}>({
+    toasts: async ({ page }, use) => {
+        const toasts = new Toasts(page);
+        await use(toasts);
+    },
+});
+
+class Toasts {
+    public constructor(public readonly page: Page) {}
+
+    /**
+     * Assert that no toasts exist.
+     */
+    public async assertNoToasts(): Promise<void> {
+        await expect(this.page.locator(".mx_Toast_toast")).not.toBeVisible();
+    }
+
+    /**
+     * Return the toast with the supplied title. Fail or return null if it does
+     * not exist.
+     *
+     * If `required` is false, you should supply a relatively short `timeout`
+     * (e.g. 2000, meaning 2 seconds) to prevent your test taking too long.
+     *
+     * @param title - Expected title of the toast.
+     * @param timeout - Time in ms before we give up and decide the toast does
+     *                  not exist. If `required` is true, defaults to `timeout`
+     *                  in `TestConfig.expect`. Otherwise, defaults to 2000 (2
+     *                  seconds).
+     * @param required - If true, fail the test (throw an exception) if the
+     *                   toast is not visible. Otherwise, just return null if
+     *                   the toast is not visible.
+     * @returns the Locator for the matching toast, or null if it is not
+     *          visible. (null will only be returned if `required` is false.)
+     */
+    public async getToast(title: string, timeout?: number, required?: true): Promise<Locator>;
+    public async getToast(title: string, timeout: number | undefined, required: false): Promise<Locator | null>;
+    public async getToast(title: string, timeout?: number, required = true): Promise<Locator | null> {
+        const toast = this.page.locator(".mx_Toast_toast", { hasText: title }).first();
+
+        if (required) {
+            await expect(toast).toBeVisible({ timeout });
+            return toast;
+        } else {
+            // If we don't set a timeout, waitFor will wait forever. Since
+            // required is false, we definitely don't want to wait forever.
+            timeout = timeout ?? 2000;
+
+            try {
+                await toast.waitFor({ state: "visible", timeout });
+                return toast;
+            } catch {
+                return null;
+            }
+        }
+    }
+
+    /**
+     * Accept the toast with the supplied title, or fail if it does not exist.
+     *
+     * Only works if this toast is at the top of the stack of toasts.
+     *
+     * @param title - Expected title of the toast.
+     */
+    public async acceptToast(title: string): Promise<void> {
+        return await clickToastButton(this, title, "primary");
+    }
+
+    /**
+     * Accept the toast with the supplied title, if it exists, or return after 2
+     * seconds if it is not found.
+     *
+     * Only works if this toast is at the top of the stack of toasts.
+     *
+     * @param title - Expected title of the toast.
+     */
+    public async acceptToastIfExists(title: string): Promise<void> {
+        return await clickToastButton(this, title, "primary", 2000, false);
+    }
+
+    /**
+     * Reject the toast with the supplied title, or fail if it does not exist.
+     *
+     * Only works if this toast is at the top of the stack of toasts.
+     *
+     * @param title - Expected title of the toast.
+     */
+    public async rejectToast(title: string): Promise<void> {
+        return await clickToastButton(this, title, "secondary");
+    }
+
+    /**
+     * Reject the toast with the supplied title, if it exists, or return after 2
+     * seconds if it is not found.
+     *
+     * Only works if this toast is at the top of the stack of toasts.
+     *
+     * @param title - Expected title of the toast.
+     */
+    public async rejectToastIfExists(title: string): Promise<void> {
+        return await clickToastButton(this, title, "secondary", 2000, false);
+    }
+}
+
+/**
+ * Find the toast with the supplied title and click a button on it.
+ *
+ * Only works if this toast is at the top of the stack of toasts.
+ *
+ * If `required` is false, you should supply a relatively short `timeout`
+ * (e.g. 2000, meaning 2 seconds) to prevent your test taking too long.
+ *
+ * @param toasts - A Toasts instance.
+ * @param title - Expected title of the toast.
+ * @param button - Which button to click on the toast. Allowed values are
+ *                 "primary", which will accept the toast, or "secondary",
+ *                 which will reject it.
+ * @param timeout - Time in ms before we give up and decide the toast does
+ *                  not exist. If `required` is true, defaults to `timeout`
+ *                  in `TestConfig.expect`. Otherwise, defaults to 2000 (2
+ *                  seconds).
+ * @param required - If true, fail the test (throw an exception) if the
+ *                   toast is not visible. Otherwise, just return after
+ *                   `timeout` if the toast is not visible.
+ */
+async function clickToastButton(
+    toasts: Toasts,
+    title: string,
+    button: "primary" | "secondary",
+    timeout?: number,
+    required = true,
+): Promise<void> {
+    let toast: Locator | null;
+    if (required) {
+        toast = await toasts.getToast(title, timeout, true);
+    } else {
+        toast = await toasts.getToast(title, timeout, false);
+    }
+
+    if (toast) {
+        await toast.locator(`.mx_Toast_buttons button[data-kind="${button}"]`).click();
+    }
+}

package/src/fixtures/user.ts

@@ -9,7 +9,10 @@ Please see LICENSE files in the repository root for full details.
 import { type Page } from "@playwright/test";
 import { sample, uniqueId } from "lodash-es";
 
-import { test as base } from "./services.js";
+// We want to avoid using `mergeTests` in index.ts because it drops useful type
+// information about the fixtures. Instead, we add `toasts` into our fixture
+// suite by using its `test` as a base, so that there is a linear hierarchy.
+import { test as base } from "./toasts.js";
 import { type Credentials } from "../utils/api.js";
 
 /** Adds an initScript to the given page which will populate localStorage appropriately so that Element will use the given credentials. */

package/tsconfig.json

@@ -1,6 +1,7 @@
 {
     "$schema": "http://json.schemastore.org/tsconfig",
     "compilerOptions": {
+        "rootDir": "./src",
         "target": "esnext",
         "lib": ["dom", "es2022", "esnext"],
         "esModuleInterop": true,