@element-hq/element-web-playwright-common 3.1.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

@@ -11,52 +11,61 @@ declare class Toasts {
     readonly page: Page;
     constructor(page: Page);
     /**
-     * Assert that no toasts exist
+     * Assert that no toasts exist.
      */
     assertNoToasts(): Promise<void>;
     /**
-     * Assert that a toast with the given title exists, and return it
+     * Return the toast with the supplied title. Fail or return null if it does
+     * not exist.
      *
-     * @param title - Expected title of the toast
-     * @param timeout - Time to retry the assertion for in milliseconds.
-     *                  Defaults to `timeout` in `TestConfig.expect`.
-     * @returns the Locator for the matching toast
-     */
-    getToast(title: string, timeout?: number): Promise<Locator>;
-    /**
-     * Find a toast with the given title, if it exists.
+     * 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 - Title of the toast.
-     * @returns the Locator for the matching toast, or an empty locator if it
-     *          doesn't exist.
+     * @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.)
      */
-    getToastIfExists(title: string): Locator;
+    getToast(title: string, timeout?: number, required?: true): Promise<Locator>;
+    getToast(title: string, timeout: number | undefined, required: false): Promise<Locator | null>;
     /**
-     * Accept a toast with the given title. Only works for the first toast in
-     * the stack.
+     * 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
+     * @param title - Expected title of the toast.
      */
     acceptToast(title: string): Promise<void>;
     /**
-     * Accept a toast with the given title, if it exists. Only works for the
-     * first toast in the stack.
+     * Accept the toast with the supplied title, if it exists, or return after 2
+     * seconds if it is not found.
      *
-     * @param title - Title of the toast
+     * 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 a toast with the given title. Only works for the first toast in
-     * the stack.
+     * 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
+     * @param title - Expected title of the toast.
      */
     rejectToast(title: string): Promise<void>;
     /**
-     * Reject a toast with the given title, if it exists. Only works for the
-     * first toast in the stack.
+     * 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 - Title of the toast
+     * @param title - Expected title of the toast.
      */
     rejectToastIfExists(title: string): Promise<void>;
 }

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

@@ -1 +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;;;;;;;OAOG;IACU,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAMxE;;;;;;OAMG;IACI,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;IAI/C;;;;;OAKG;IACU,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAItD;;;;;OAKG;IACU,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAO9D;;;;;OAKG;IACU,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKtD;;;;;OAKG;IACU,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAMjE"}
+{"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

@@ -22,76 +22,103 @@ class Toasts {
         this.page = page;
     }
     /**
-     * Assert that no toasts exist
+     * Assert that no toasts exist.
      */
     async assertNoToasts() {
         await expect(this.page.locator(".mx_Toast_toast")).not.toBeVisible();
     }
-    /**
-     * Assert that a toast with the given title exists, and return it
-     *
-     * @param title - Expected title of the toast
-     * @param timeout - Time to retry the assertion for in milliseconds.
-     *                  Defaults to `timeout` in `TestConfig.expect`.
-     * @returns the Locator for the matching toast
-     */
-    async getToast(title, timeout) {
-        const toast = this.getToastIfExists(title);
-        await expect(toast).toBeVisible({ timeout });
-        return toast;
+    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;
+            }
+        }
     }
     /**
-     * Find a toast with the given title, if it exists.
+     * Accept the toast with the supplied title, or fail if it does not exist.
      *
-     * @param title - Title of the toast.
-     * @returns the Locator for the matching toast, or an empty locator if it
-     *          doesn't exist.
-     */
-    getToastIfExists(title) {
-        return this.page.locator(".mx_Toast_toast", { hasText: title }).first();
-    }
-    /**
-     * Accept a toast with the given title. Only works for the first toast in
-     * the stack.
+     * Only works if this toast is at the top of the stack of toasts.
      *
-     * @param title - Expected title of the toast
+     * @param title - Expected title of the toast.
      */
     async acceptToast(title) {
-        const toast = await this.getToast(title);
-        await toast.locator('.mx_Toast_buttons button[data-kind="primary"]').click();
+        return await clickToastButton(this, title, "primary");
     }
     /**
-     * Accept a toast with the given title, if it exists. Only works for the
-     * first toast in the stack.
+     * 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 - Title of the toast
+     * @param title - Expected title of the toast.
      */
     async acceptToastIfExists(title) {
-        const toast = this.getToastIfExists(title).locator('.mx_Toast_buttons button[data-kind="primary"]');
-        if ((await toast.count()) > 0) {
-            await toast.click();
-        }
+        return await clickToastButton(this, title, "primary", 2000, false);
     }
     /**
-     * Reject a toast with the given title. Only works for the first toast in
-     * the stack.
+     * 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
+     * @param title - Expected title of the toast.
      */
     async rejectToast(title) {
-        const toast = await this.getToast(title);
-        await toast.locator('.mx_Toast_buttons button[data-kind="secondary"]').click();
+        return await clickToastButton(this, title, "secondary");
     }
     /**
-     * Reject a toast with the given title, if it exists. Only works for the
-     * first toast in the stack.
+     * Reject the toast with the supplied title, if it exists, or return after 2
+     * seconds if it is not found.
      *
-     * @param title - Title of the toast
+     * Only works if this toast is at the top of the stack of toasts.
+     *
+     * @param title - Expected title of the toast.
      */
     async rejectToastIfExists(title) {
-        const toast = this.getToastIfExists(title).locator('.mx_Toast_buttons button[data-kind="secondary"]');
-        if ((await toast.count()) > 0) {
-            await toast.click();
-        }
+        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

@@ -8,8 +8,8 @@ export declare const test: import("playwright/test").TestType<import("playwright
     toasts: {
         readonly page: Page;
         assertNoToasts(): Promise<void>;
-        getToast(title: string, timeout?: number): Promise<import("playwright-core").Locator>;
-        getToastIfExists(title: string): import("playwright-core").Locator;
+        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>;

package/lib/index.d.ts

@@ -44,8 +44,8 @@ export declare const test: import("playwright/test").TestType<import("playwright
     toasts: {
         readonly page: import("playwright-core").Page;
         assertNoToasts(): Promise<void>;
-        getToast(title: string, timeout?: number): Promise<import("playwright-core").Locator>;
-        getToastIfExists(title: string): import("playwright-core").Locator;
+        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>;

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@element-hq/element-web-playwright-common",
     "type": "module",
-    "version": "3.1.0",
+    "version": "4.0.0",
     "license": "SEE LICENSE IN README.md",
     "repository": {
         "type": "git",
@@ -24,8 +24,7 @@
     "devDependencies": {
         "@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/src/fixtures/toasts.ts

@@ -29,81 +29,135 @@ class Toasts {
     public constructor(public readonly page: Page) {}
 
     /**
-     * Assert that no toasts exist
+     * Assert that no toasts exist.
      */
     public async assertNoToasts(): Promise<void> {
         await expect(this.page.locator(".mx_Toast_toast")).not.toBeVisible();
     }
 
     /**
-     * Assert that a toast with the given title exists, and return it
+     * Return the toast with the supplied title. Fail or return null if it does
+     * not exist.
      *
-     * @param title - Expected title of the toast
-     * @param timeout - Time to retry the assertion for in milliseconds.
-     *                  Defaults to `timeout` in `TestConfig.expect`.
-     * @returns the Locator for the matching toast
-     */
-    public async getToast(title: string, timeout?: number): Promise<Locator> {
-        const toast = this.getToastIfExists(title);
-        await expect(toast).toBeVisible({ timeout });
-        return toast;
-    }
-
-    /**
-     * Find a toast with the given title, if it exists.
+     * 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 - Title of the toast.
-     * @returns the Locator for the matching toast, or an empty locator if it
-     *          doesn't exist.
+     * @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 getToastIfExists(title: string): Locator {
-        return this.page.locator(".mx_Toast_toast", { hasText: title }).first();
+    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 a toast with the given title. Only works for the first toast in
-     * the stack.
+     * 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
+     * @param title - Expected title of the toast.
      */
     public async acceptToast(title: string): Promise<void> {
-        const toast = await this.getToast(title);
-        await toast.locator('.mx_Toast_buttons button[data-kind="primary"]').click();
+        return await clickToastButton(this, title, "primary");
     }
+
     /**
-     * Accept a toast with the given title, if it exists. Only works for the
-     * first toast in the stack.
+     * Accept the toast with the supplied title, if it exists, or return after 2
+     * seconds if it is not found.
      *
-     * @param title - Title of the toast
+     * 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> {
-        const toast = this.getToastIfExists(title).locator('.mx_Toast_buttons button[data-kind="primary"]');
-        if ((await toast.count()) > 0) {
-            await toast.click();
-        }
+        return await clickToastButton(this, title, "primary", 2000, false);
     }
 
     /**
-     * Reject a toast with the given title. Only works for the first toast in
-     * the stack.
+     * 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
+     * @param title - Expected title of the toast.
      */
     public async rejectToast(title: string): Promise<void> {
-        const toast = await this.getToast(title);
-        await toast.locator('.mx_Toast_buttons button[data-kind="secondary"]').click();
+        return await clickToastButton(this, title, "secondary");
     }
 
     /**
-     * Reject a toast with the given title, if it exists. Only works for the
-     * first toast in the stack.
+     * Reject the toast with the supplied title, if it exists, or return after 2
+     * seconds if it is not found.
      *
-     * @param title - Title of the toast
+     * 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> {
-        const toast = this.getToastIfExists(title).locator('.mx_Toast_buttons button[data-kind="secondary"]');
-        if ((await toast.count()) > 0) {
-            await toast.click();
-        }
+        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/tsconfig.json

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