test_playwright_element

End-to-end test suite for the Element web client (Matrix protocol), built with Playwright.

---

Table of Contents

• Overview
• Project Structure
• Architecture
• Page Objects
• Configuration
• Environment Variables
• How to Run
• CI / GitHub Actions

---

Overview

The suite performs a full smoke test of the Element web client:

1. Register a temporary Matrix account via the homeserver API (or use pre-existing credentials).
2. Navigate to https://app.element.io and sign in.
3. Create a private room.
4. Send a chat message.
5. Assert the message is visible in the room timeline.

---

Project Structure

test_playwright_element/
├── tests/
│   └── element.spec.js      # All test cases (single spec file)
├── playwright.config.js     # Playwright configuration
├── package.json             # npm scripts and dependencies
└── .github/
    └── workflows/
        └── playwright.yml   # GitHub Actions CI workflow

---

Architecture

The project follows a single-file, flat test approach — all test logic lives inside tests/element.spec.js.

Key building blocks

Piece	Purpose
registerMatrixUser(homeserverUrl)	Async helper that creates a throw-away Matrix account via the homeserver's Client-Server API (/_matrix/client/v3/register). Used in beforeAll when no credentials are supplied through environment variables.
test.describe block	Groups the smoke-test scenarios and resolves credentials once in beforeAll so every test in the suite shares the same account.
Inline locators	UI interactions use page.getByRole, page.getByLabel, page.locator, and page.getByPlaceholder directly inside the test — no separate abstraction layer.

Registration flow

Matrix registration is a two-step process:

1. Initiate – POST /_matrix/client/v3/register returns a session ID and available auth flows.
2. Complete – repeat the same endpoint with auth.type = "m.login.dummy" and the session ID. This bypasses CAPTCHA and works on open-registration homeservers.

---

Page Objects

This project does not use the Page Object Model (POM). Locators are written inline inside each test step. This is an intentional choice for a small, single-spec suite where the overhead of a POM layer would outweigh its benefits.

If the suite grows, the recommended next step is to extract the following into dedicated page object classes:

• WelcomePage – cookie banner, "Sign in" link
• LoginPage – homeserver picker, username/password fields, submit button
• RoomListPage – "Add room" button, post-login dialogs
• RoomPage – message composer, timeline event tiles

---

Configuration

playwright.config.js controls global test behaviour:

Setting	Value	Notes
testDir	./tests	Directory scanned for spec files
timeout	120 s	Per-test timeout
retries	1	One automatic retry on failure
baseURL	https://app.element.io	Default origin for page.goto
headless	true	Runs without a visible browser window
screenshot	only-on-failure	Screenshot saved when a test fails
video	retain-on-failure	Video saved when a test fails
trace	retain-on-failure	Trace saved when a test fails
projects	chromium (Desktop Chrome)	Single browser project
reporter	list + html	Console list output + HTML report (never auto-opens)

---

Environment Variables

Variable	Required	Default	Description
HOMESERVER_URL	No	https://matrix.envs.net	Base URL of the Matrix homeserver used for account registration
MATRIX_USER	No	—	Username of a pre-existing Matrix account (skips API registration)
MATRIX_PASSWORD	No	—	Password of the pre-existing account

When both MATRIX_USER and MATRIX_PASSWORD are set the registration step is skipped entirely and the provided account is used instead.

Known public homeservers that support open registration without CAPTCHA:

• https://matrix.envs.net
• https://converser.eu
• https://matrix.tchncs.de

---

How to Run

Prerequisites

• Node.js 18 or later
• npm (bundled with Node.js)

1. Install dependencies

npm ci

2. Install Playwright browsers

npx playwright install --with-deps chromium

3. Run the tests

# Headless (default)
npm test

# Headed – watch the browser while tests run
npm run test:headed

# Interactive UI mode – time-travel debugger
npm run test:ui

4. Run against a custom homeserver or with existing credentials

HOMESERVER_URL=https://matrix.tchncs.de npm test

# Skip API registration by providing an existing account
MATRIX_USER=myuser MATRIX_PASSWORD=mypassword npm test

5. View the HTML report

After a run, open the generated report with:

npx playwright show-report

---

CI / GitHub Actions

The workflow at .github/workflows/playwright.yml runs automatically on every push or pull request to main/master, and can also be triggered manually via workflow_dispatch.

Steps:

1. Check out the repository.
2. Set up Node.js 20 with npm caching.
3. npm ci – install dependencies.
4. Install Chromium with system dependencies.
5. npm test – execute the Playwright suite.
6. Upload the HTML report as an artifact (retained 30 days).
7. Upload screenshots and traces as an artifact on failure (retained 7 days).

Secrets (optional – add in Settings → Secrets and variables → Actions):

Secret	Purpose
HOMESERVER_URL	Override the default homeserver
MATRIX_USER	Use a stable test account instead of registering a new one each run
MATRIX_PASSWORD	Password for MATRIX_USER