@element-hq/element-web-playwright-common 1.0.0

package/lib/utils/rand.js

@@ -0,0 +1,15 @@
+/*
+Copyright 2024-2025 New Vector Ltd.
+Copyright 2023 The Matrix.org Foundation C.I.C.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE files in the repository root for full details.
+*/
+import crypto from "node:crypto";
+/**
+ * Generate a random base64 string of the given number of bytes.
+ * @param numBytes - The number of bytes to generate.
+ */
+export function randB64Bytes(numBytes) {
+    return crypto.randomBytes(numBytes).toString("base64").replace(/=*$/, "");
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+    "name": "@element-hq/element-web-playwright-common",
+    "type": "module",
+    "version": "1.0.0",
+    "license": "SEE LICENSE IN README.md",
+    "main": "lib/index.js",
+    "bin": {
+        "playwright-screenshots": "./playwright-screenshots.sh"
+    },
+    "devDependencies": {
+        "@types/lodash-es": "^4.17.12",
+        "typescript": "^5.8.2"
+    },
+    "dependencies": {
+        "@axe-core/playwright": "^4.10.1",
+        "@testcontainers/postgresql": "^10.18.0",
+        "lodash-es": "^4.17.21",
+        "mailpit-api": "^1.2.0",
+        "strip-ansi": "^7.1.0",
+        "testcontainers": "^10.18.0",
+        "yaml": "^2.7.0"
+    },
+    "peerDependencies": {
+        "@playwright/test": "^1.51.0",
+        "playwright-core": "^1.51.0"
+    },
+    "scripts": {
+        "prepare": "tsc"
+    }
+}

package/playwright-screenshots.sh

@@ -0,0 +1,53 @@
+#!/bin/bash
+
+# Handle symlinks here as we tend to be executed as an npm binary
+SCRIPT_PATH=$(readlink -f "$0")
+SCRIPT_DIR=$(dirname "$SCRIPT_PATH")
+
+IMAGE_NAME="element-web-playwright-common"
+echo "Building $IMAGE_NAME image in $SCRIPT_DIR"
+
+# Build image
+PW_VERSION=$(
+  yarn list \
+    --pattern @playwright/test \
+    --depth=0 \
+    --json \
+    --non-interactive \
+    --no-progress | \
+    jq -r '.data.trees[].name | split("@")[2]' \
+  )
+echo "with Playwright version $PW_VERSION"
+
+docker build -t "$IMAGE_NAME" --build-arg "PLAYWRIGHT_VERSION=$PW_VERSION" "$SCRIPT_DIR"
+
+RUN_ARGS=(
+  --rm
+  --network host
+  # Pass BASE_URL and CI environment variables to the container
+  -e BASE_URL
+  -e CI
+  # Bind mount the working directory into the container
+  -v $(pwd):/work/
+  # Bind mount the docker socket so we can run docker commands from the container
+  -v /var/run/docker.sock:/var/run/docker.sock
+  # Bind mount /tmp so we can store temporary files
+  -v /tmp/:/tmp/
+  -it
+)
+
+# Ensure we pass all symlinked node_modules to the container
+pushd node_modules || exit > /dev/null
+SYMLINKS=$(find . -maxdepth 2 -type l -not -path "./.bin/*")
+popd || exit > /dev/null
+for LINK in $SYMLINKS; do
+  TARGET=$(readlink -f "node_modules/$LINK")
+  if [ -d "$TARGET" ]; then
+    echo "mounting linked package ${LINK:2} in container"
+    RUN_ARGS+=( "-v" "$TARGET:/work/node_modules/${LINK:2}" )
+  fi
+done
+
+DEFAULT_ARGS=(--grep @screenshot)
+
+docker run "${RUN_ARGS[@]}" "$IMAGE_NAME" "${DEFAULT_ARGS[@]}" "$@"

package/src/@types/playwright-core.d.ts

@@ -0,0 +1,12 @@
+/*
+Copyright 2024-2025 New Vector Ltd.
+Copyright 2024 The Matrix.org Foundation C.I.C.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE files in the repository root for full details.
+*/
+
+declare module "playwright-core/lib/utils" {
+    // This type is not public in playwright-core utils
+    export function sanitizeForFilePath(filePath: string): string;
+}

package/src/expect/axe.ts

@@ -0,0 +1,37 @@
+/*
+Copyright 2024-2025 New Vector Ltd.
+Copyright 2023 The Matrix.org Foundation C.I.C.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE files in the repository root for full details.
+*/
+
+import { test, expect as baseExpect, type ExpectMatcherState, type MatcherReturnType } from "@playwright/test";
+
+import type AxeBuilder from "@axe-core/playwright";
+
+export type Expectations = {
+    /**
+     * Assert that the given AxeBuilder instance has no violations.
+     * @param receiver - The AxeBuilder instance to check.
+     */
+    toHaveNoViolations: (this: ExpectMatcherState, receiver: AxeBuilder) => Promise<MatcherReturnType>;
+};
+
+export const expect = baseExpect.extend<Expectations>({
+    async toHaveNoViolations(this: ExpectMatcherState, receiver: AxeBuilder) {
+        const testInfo = test.info();
+        if (!testInfo) throw new Error(`toHaveNoViolations() must be called during the test`);
+
+        const results = await receiver.analyze();
+
+        await testInfo.attach("accessibility-scan-results", {
+            body: JSON.stringify(results, null, 2),
+            contentType: "application/json",
+        });
+
+        baseExpect(results.violations).toEqual([]);
+
+        return { pass: true, message: (): string => "", name: "toHaveNoViolations" };
+    },
+});

package/src/expect/index.ts

@@ -0,0 +1,21 @@
+/*
+Copyright 2025 New Vector Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE files in the repository root for full details.
+*/
+
+import { mergeExpects, type Expect } from "@playwright/test";
+
+import {
+    expect as screenshotExpectations,
+    Expectations as ScreenshotExpectations,
+    ToMatchScreenshotOptions,
+} from "./screenshot.js";
+import { expect as axeExpectations, Expectations as AxeExpectations } from "./axe.js";
+
+export const expect = mergeExpects(screenshotExpectations, axeExpectations) as Expect<
+    ScreenshotExpectations & AxeExpectations
+>;
+
+export type { ToMatchScreenshotOptions };

package/src/expect/screenshot.ts

@@ -0,0 +1,79 @@
+/*
+Copyright 2024-2025 New Vector Ltd.
+Copyright 2023 The Matrix.org Foundation C.I.C.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE files in the repository root for full details.
+*/
+
+import {
+    test,
+    expect as baseExpect,
+    ElementHandle,
+    type ExpectMatcherState,
+    type Locator,
+    type Page,
+    type PageAssertionsToHaveScreenshotOptions,
+} from "@playwright/test";
+import { type MatcherReturnType } from "playwright/types/test";
+import { sanitizeForFilePath } from "playwright-core/lib/utils";
+import { extname } from "node:path";
+
+// Based on https://github.com/microsoft/playwright/blob/2b77ed4d7aafa85a600caa0b0d101b72c8437eeb/packages/playwright/src/util.ts#L206C8-L210C2
+function sanitizeFilePathBeforeExtension(filePath: string): string {
+    const ext = extname(filePath);
+    const base = filePath.substring(0, filePath.length - ext.length);
+    return sanitizeForFilePath(base) + ext;
+}
+
+export interface ToMatchScreenshotOptions extends PageAssertionsToHaveScreenshotOptions {
+    css?: string;
+}
+
+export type Expectations = {
+    toMatchScreenshot: (
+        this: ExpectMatcherState,
+        receiver: Page | Locator,
+        name: `${string}.png`,
+        options?: ToMatchScreenshotOptions,
+    ) => Promise<MatcherReturnType>;
+};
+
+/**
+ * Provides an upgrade to the `toHaveScreenshot` expectation.
+ * Unfortunately, we can't just extend the existing `toHaveScreenshot` expectation
+ */
+export const expect = baseExpect.extend<Expectations>({
+    async toMatchScreenshot(receiver, name, options) {
+        const testInfo = test.info();
+        if (!testInfo) throw new Error(`toMatchScreenshot() must be called during the test`);
+
+        if (!testInfo.tags.includes("@screenshot")) {
+            throw new Error("toMatchScreenshot() must be used in a test tagged with @screenshot");
+        }
+
+        const page = "page" in receiver ? receiver.page() : receiver;
+
+        let style: ElementHandle<Element> | undefined;
+        if (options?.css) {
+            // We add a custom style tag before taking screenshots
+            style = (await page.addStyleTag({
+                content: options.css,
+            })) as ElementHandle<Element>;
+        }
+
+        const screenshotName = sanitizeFilePathBeforeExtension(name);
+        await baseExpect(receiver).toHaveScreenshot(screenshotName, options);
+
+        await style?.evaluate((tag) => tag.remove());
+
+        testInfo.annotations.push({
+            // `_` prefix hides it from the HTML reporter
+            type: "_screenshot",
+            // include a path relative to `playwright/snapshots/`
+            description: testInfo.snapshotPath(screenshotName).split("/playwright/snapshots/", 2)[1],
+        });
+
+        return { pass: true, message: (): string => "", name: "toMatchScreenshot" };
+    },
+});

package/src/fixtures/axe.ts

@@ -0,0 +1,22 @@
+/*
+Copyright 2024-2025 New Vector Ltd.
+Copyright 2023 The Matrix.org Foundation C.I.C.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE files in the repository root for full details.
+*/
+
+import { test as base } from "@playwright/test";
+import AxeBuilder from "@axe-core/playwright";
+
+export const test = base.extend<{
+    /**
+     * AxeBuilder instance for the current page
+     */
+    axe: AxeBuilder;
+}>({
+    axe: async ({ page }, use) => {
+        const builder = new AxeBuilder({ page });
+        await use(builder);
+    },
+});

package/src/fixtures/index.ts

@@ -0,0 +1,15 @@
+/*
+Copyright 2025 New Vector Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE files in the repository root for full details.
+*/
+
+import { mergeTests } from "@playwright/test";
+
+import { test as axe } from "./axe.js";
+import { test as user } from "./user.js";
+
+export { type Services, type WorkerOptions } from "./services.js";
+
+export const test = mergeTests(axe, user);

package/src/fixtures/services.ts

@@ -0,0 +1,188 @@
+/*
+Copyright 2024-2025 New Vector Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE files in the repository root for full details.
+*/
+
+import { test as base } from "@playwright/test";
+import { type MailpitClient } from "mailpit-api";
+import { Network, type StartedNetwork } from "testcontainers";
+import { PostgreSqlContainer, type StartedPostgreSqlContainer } from "@testcontainers/postgresql";
+
+import {
+    type SynapseConfig,
+    SynapseContainer,
+    type StartedMatrixAuthenticationServiceContainer,
+    type HomeserverContainer,
+    type StartedHomeserverContainer,
+    MailpitContainer,
+    type StartedMailpitContainer,
+} from "../testcontainers/index.js";
+import { Logger } from "../utils/logger.js";
+
+/**
+ * Test-scoped fixtures available in the test
+ */
+export interface TestFixtures {
+    /**
+     * The mailpit client instance for the test.
+     * This is a fresh client instance with no messages from prior tests.
+     */
+    mailpitClient: MailpitClient;
+}
+
+export interface WorkerOptions {
+    /**
+     * The synapse configuration to use for the homeserver.
+     */
+    synapseConfig: Partial<SynapseConfig>;
+}
+
+/**
+ * Worker-scoped "service" fixtures available in the test
+ */
+export interface Services {
+    /**
+     * The logger instance for the worker.
+     */
+    logger: Logger;
+
+    /**
+     * The started testcontainers network instance for the worker.
+     */
+    network: StartedNetwork;
+
+    /**
+     * The started postgres container instance for the worker.
+     */
+    postgres: StartedPostgreSqlContainer;
+
+    /**
+     * The started mailpit container instance for the worker.
+     */
+    mailpit: StartedMailpitContainer;
+
+    /**
+     * The homeserver instance container to use for the worker.
+     */
+    _homeserver: HomeserverContainer<unknown>;
+    /**
+     * The started homeserver instance container for the worker.
+     */
+    homeserver: StartedHomeserverContainer;
+
+    /**
+     * The Matrix Authentication Service container instance for the worker.
+     * May be undefined if no delegated auth is in use.
+     */
+    mas?: StartedMatrixAuthenticationServiceContainer;
+}
+
+export const test = base.extend<TestFixtures, WorkerOptions & Services>({
+    logger: [
+        // eslint-disable-next-line no-empty-pattern
+        async ({}, use) => {
+            const logger = new Logger();
+            await use(logger);
+        },
+        { scope: "worker" },
+    ],
+    network: [
+        // eslint-disable-next-line no-empty-pattern
+        async ({}, use) => {
+            const network = await new Network().start();
+            await use(network);
+            await network.stop();
+        },
+        { scope: "worker" },
+    ],
+    postgres: [
+        async ({ logger, network }, use) => {
+            const container = await new PostgreSqlContainer()
+                .withNetwork(network)
+                .withNetworkAliases("postgres")
+                .withLogConsumer(logger.getConsumer("postgres"))
+                .withTmpFs({
+                    "/dev/shm/pgdata/data": "",
+                })
+                .withEnvironment({
+                    PG_DATA: "/dev/shm/pgdata/data",
+                })
+                .withCommand([
+                    "-c",
+                    "shared_buffers=128MB",
+                    "-c",
+                    `fsync=off`,
+                    "-c",
+                    `synchronous_commit=off`,
+                    "-c",
+                    "full_page_writes=off",
+                ])
+                .start();
+            await use(container);
+            await container.stop();
+        },
+        { scope: "worker" },
+    ],
+
+    mailpit: [
+        async ({ logger, network }, use) => {
+            const container = await new MailpitContainer()
+                .withNetwork(network)
+                .withNetworkAliases("mailpit")
+                .withLogConsumer(logger.getConsumer("mailpit"))
+                .start();
+            await use(container);
+            await container.stop();
+        },
+        { scope: "worker" },
+    ],
+    mailpitClient: async ({ mailpit: container }, use) => {
+        await container.client.deleteMessages();
+        await use(container.client);
+    },
+
+    synapseConfig: [{}, { scope: "worker" }],
+    _homeserver: [
+        async ({ logger }, use) => {
+            const container = new SynapseContainer().withLogConsumer(logger.getConsumer("synapse"));
+            await use(container);
+        },
+        { scope: "worker" },
+    ],
+    homeserver: [
+        async ({ logger, network, _homeserver: homeserver, synapseConfig, mas }, use) => {
+            if (homeserver instanceof SynapseContainer) {
+                homeserver.withConfig(synapseConfig);
+            }
+            const container = await homeserver
+                .withNetwork(network)
+                .withNetworkAliases("homeserver")
+                .withLogConsumer(logger.getConsumer("homeserver"))
+                .withMatrixAuthenticationService(mas)
+                .start();
+
+            await use(container);
+            await container.stop();
+        },
+        { scope: "worker" },
+    ],
+    mas: [
+        // eslint-disable-next-line no-empty-pattern
+        async ({}, use) => {
+            // we stub the mas fixture to allow `homeserver` to depend on it to ensure
+            // when it is specified by `masHomeserver` it is started before the homeserver
+            await use(undefined);
+        },
+        { scope: "worker" },
+    ],
+
+    context: async ({ logger, context, request, homeserver }, use, testInfo) => {
+        homeserver.setRequest(request);
+        await logger.onTestStarted(context);
+        await use(context);
+        await logger.onTestFinished(testInfo);
+        await homeserver.onTestFinished(testInfo);
+    },
+});

package/src/fixtures/user.ts

@@ -0,0 +1,93 @@
+/*
+Copyright 2024-2025 New Vector Ltd.
+Copyright 2023 The Matrix.org Foundation C.I.C.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+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";
+import { Credentials } from "../utils/api.js";
+
+export const test = base.extend<{
+    /**
+     * 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: Credentials;
+
+    /**
+     * The same as {@link https://playwright.dev/docs/api/class-fixtures#fixtures-page|`page`},
+     * but adds an initScript which will populate localStorage with the user's details from
+     * {@link #credentials} and {@link #homeserver}.
+     *
+     * Similar to {@link #user}, but doesn't load the app.
+     */
+    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: Credentials;
+}>({
+    displayName: undefined,
+    credentials: async ({ homeserver, displayName: testDisplayName }, use, testInfo) => {
+        const names = ["Alice", "Bob", "Charlie", "Daniel", "Eve", "Frank", "Grace", "Hannah", "Isaac", "Judy"];
+        const password = uniqueId("password_");
+        const displayName = testDisplayName ?? sample(names)!;
+
+        const credentials = await homeserver.registerUser(`user_${testInfo.testId}`, password, displayName);
+        console.log(`Registered test user ${credentials.userId} with displayname ${displayName}`);
+
+        await use({
+            ...credentials,
+            displayName,
+        });
+    },
+
+    pageWithCredentials: async ({ page, homeserver, credentials }, use) => {
+        await page.addInitScript(
+            ({ baseUrl, credentials }) => {
+                // Seed the localStorage with the required credentials
+                window.localStorage.setItem("mx_hs_url", baseUrl);
+                window.localStorage.setItem("mx_user_id", credentials.userId);
+                window.localStorage.setItem("mx_access_token", credentials.accessToken);
+                window.localStorage.setItem("mx_device_id", credentials.deviceId);
+                window.localStorage.setItem("mx_is_guest", "false");
+                window.localStorage.setItem("mx_has_pickle_key", "false");
+                window.localStorage.setItem("mx_has_access_token", "true");
+
+                window.localStorage.setItem(
+                    "mx_local_settings",
+                    JSON.stringify({
+                        // Retain any other settings which may have already been set
+                        ...JSON.parse(window.localStorage.getItem("mx_local_settings") || "{}"),
+                        // Ensure the language is set to a consistent value
+                        language: "en",
+                    }),
+                );
+            },
+            { baseUrl: homeserver.baseUrl, credentials },
+        );
+        await use(page);
+    },
+
+    user: async ({ pageWithCredentials: page, credentials }, use) => {
+        await page.goto("/");
+        await page.waitForSelector(".mx_MatrixChat", { timeout: 30000 });
+        await use(credentials);
+    },
+});

package/src/index.ts

@@ -0,0 +1,92 @@
+/*
+Copyright 2024-2025 New Vector Ltd.
+Copyright 2023 The Matrix.org Foundation C.I.C.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE files in the repository root for full details.
+*/
+
+import { type Config as BaseConfig } from "@element-hq/element-web-module-api";
+
+import { test as base } from "./fixtures/index.js";
+
+// Enable experimental service worker support
+// See https://playwright.dev/docs/service-workers-experimental#how-to-enable
+process.env["PW_EXPERIMENTAL_SERVICE_WORKER_NETWORK_EVENTS"] = "1";
+
+// We extend the Module API Config interface so that all modules
+// which use declaration merging will have their config types correctly applied.
+export interface Config extends BaseConfig {
+    default_server_config: {
+        "m.homeserver"?: {
+            base_url: string;
+            server_name?: string;
+        };
+        "m.identity_server"?: {
+            base_url: string;
+            server_name?: string;
+        };
+    };
+    setting_defaults: Record<string, unknown>;
+    map_style_url?: string;
+    features: Record<string, boolean>;
+    modules?: string[];
+}
+
+// This is deliberately quite a minimal config.json, so that we can test that the default settings actually work.
+export const CONFIG_JSON: Partial<Config> = {
+    default_server_config: {},
+
+    // The default language is set here for test consistency
+    setting_defaults: {
+        language: "en-GB",
+    },
+
+    // the location tests want a map style url.
+    map_style_url: "https://api.maptiler.com/maps/streets/style.json?key=fU3vlMsMn4Jb6dnEIFsx",
+
+    features: {
+        // We don't want to go through the feature announcement during the e2e test
+        feature_release_announcement: false,
+    },
+};
+
+export interface TestFixtures {
+    /**
+     * The contents of the config.json to send when the client requests it.
+     */
+    config: Partial<typeof CONFIG_JSON>;
+
+    labsFlags: string[];
+}
+
+export const test = base.extend<TestFixtures>({
+    config: {}, // We merge this atop the default CONFIG_JSON in the page fixture to make extending it easier
+    labsFlags: [],
+    page: async ({ homeserver, context, page, config, labsFlags }, use) => {
+        await context.route(`http://localhost:8080/config.json*`, async (route) => {
+            const json = {
+                ...CONFIG_JSON,
+                ...config,
+                default_server_config: {
+                    "m.homeserver": {
+                        base_url: homeserver.baseUrl,
+                    },
+                    ...config.default_server_config,
+                },
+            };
+            json["features"] = {
+                ...json["features"],
+                // Enable the lab features
+                ...labsFlags.reduce<NonNullable<(typeof CONFIG_JSON)["features"]>>((obj, flag) => {
+                    obj[flag] = true;
+                    return obj;
+                }, {}),
+            };
+            await route.fulfill({ json });
+        });
+        await use(page);
+    },
+});
+
+export { expect, type ToMatchScreenshotOptions } from "./expect/index.js";