Writing E2E Tests

Framework: Playwright + custom fixtures/POMs. All tests in e2e-pw/.

Workflow (MANDATORY)

The user is a QA tester who describes tests in human language. You translate intent into code. You decide ALL technical details (fixtures, POMs, locators).

1. Explore

Before anything else:

• Check similar tests in e2e-pw/platforms/
• Read relevant POMs for available methods
• Read app UI components to understand elements, roles, text content

2. Clarify ambiguities

If the request has gaps, present a numbered questionnaire in a single message. The user answers by number. Only ask about behavior/expectations, never about implementation.

Must ask when: platform unclear, scope ambiguous, expected result vague, multiple UI paths exist, locale matters.

Example questionnaire:

Before I write the test, I need to clarify a few things:

1. Platform: web or docportal?
2. You said "create catalog" — verify it appears in the list only, or also that it opens?
3. Should the test check the modal content, or just that the action completes?

Skip questions only if the request is unambiguous with explicit steps and expected results.

3. Plan in Plan Mode

Use EnterPlanMode to create the test plan. The plan must translate user's words into technical steps:

Test: <name>
Platform: web / docportal
Fixture: editorTest / homeTest / catalogTest / baseTest
Test data: <files/catalogs to create>

Steps:
1. <action>
2. <action>

Assertions:
- <assertion 1>
- <assertion 2>

Wait for user approval, then exit plan mode and write the test.

Fixture Selection

Editor content/formatting     → editorTest
Home page / catalog list      → homeTest
Navigation inside a catalog   → catalogTest
Custom setup (web)            → baseTest
Docportal                     → baseTest (docportal)

Hierarchy (web)

baseTest            — web context, files, localStorage
  ├─ homeTest       — + homePage (HomePage)
  ├─ catalogTest    — + catalogPage (CatalogPage)
  │    └─ editorTest — + editor (ArticleEditorPom)
  └─ (direct use for custom setups)

Hierarchy (docportal)

baseTest — web context, API login/source setup

Running Tests

cd e2e-pw
# Build & start: web (6001) / docportal (6003)
bun run web:build && bun run web:start
bun run docportal:build && bun run docportal:start

# Run
bunx playwright test --project=web                    # all web
bunx playwright test --project=web basic.spec.ts      # single file
bunx playwright test --project=web -g "test name"     # by name
bun run ui                                            # interactive UI
bunx playwright test --project=docportal-prepare --project=docportal

Projects: web, web-enterprise, static (port 6002), docportal-prepare, docportal, docportal-enterprise.

Platforms

Platform	Port	State	Setup
web	6001	Reset each test (isolated)	files fixture via DOM
docportal	6003	Persistent	API setup, docportal-prepare
static	6002	Static build	Pre-built

Locators

Only getByRole and getByText. getByPlaceholder and getByLabel are fine where they read naturally — they resolve through accessible names too. getByTestId is a last resort. CSS and XPath selectors — locator(".foo"), locator("[data-qa=…]"), class names, tag chains, :nth-child — are not allowed, and neither is reaching for a data-* attribute as a hook.

When an element has no usable role or accessible name, the answer is to fix the component, not to work around it in the test. Give the button a real <button>, an aria-label, a visible text — whatever the element is actually missing. A test that reaches into markup is a test that breaks on the next restyle, and it hides an accessibility gap in the product.

Editing app code to make an element addressable is expected and welcome. It is not scope creep.

// GOOD — the element says what it is
page.getByRole("button", { name: "Save" }).click();
page.getByRole("menuitemradio", { name: "master" }).click();
page.getByText("Article Title").click();

// LAST RESORT — only when the element genuinely cannot carry a role or a name
page.getByTestId("add-catalog").click();

// NOT ALLOWED — fix the component instead
page.locator(".btn-primary > span").click();
page.locator(".right-extensions i").first().click();
page.locator("[data-qa='qa-publish-tab']").click();

If you find yourself writing a comment that explains which CSS class the app happens to render, stop: that is the moment to add the role or the label to the component.

Fixing the component: use the real element, not an ARIA patch

Making an element addressable means giving it the right tag, not decorating the wrong one.

// GOOD
<button type="button" aria-label={t("git.branch.actions")} onClick={…}>

// BAD — a div wearing a button costume
<div role="button" tabIndex={0} aria-label={…} onClick={…}>

role="button" plus tabIndex={0} on a <div> or <span> reproduces by hand what <button> gives for free — keyboard activation, focus order, Enter/Space handling — and it always reproduces some of it wrong. Use <button type="button">; type is required, or the button submits any form it lands in.

Never silence an a11y lint. biome-ignore lint/a11y/* is not an accepted way out: that rule firing is the review telling you the element is wrong. If a semantic element genuinely does not fit — an existing click target would nest, a styled wrapper would break — change the surrounding markup so it does, or say plainly in the MR why it cannot be done. Do not commit the suppression.

Suppressions in general are a smell here. The only one currently accepted in e2e-pw is lint/correctness/noEmptyPattern on fixture signatures, because Playwright requires the async ({}, use) form to detect fixture dependencies and biome has no way to know that.

Test Examples

Editor:

import { editorTest } from "@web/fixtures/editor.fixture";
editorTest("does something", async ({ editor }) => {
  await editor.setMarkdown("Hello(*)");
  await editor.press("ControlOrMeta+B");
  await editor.type("bold");
  await editor.assertMarkdownContains("**bold**");
});

Home/catalog:

import { homeTest } from "@web/fixtures/home.fixture";
homeTest.use({ files: { "my-catalog": { "article.md": "# Hello", "doc-root.yml": "title: My Catalog\n" } } });
homeTest("shows catalog", async ({ homePage }) => {
  await homePage.workspace.assertHasCatalogs(["my-catalog"]);
});

Docportal:

import { baseTest as test } from "@docportal/fixtures/base.fixture";
test.use({ source: "env", user: "env" });
test("navigates", async ({ basePage }) => {
  const page = basePage.raw;
  await page.getByRole("button", { name: "Catalog" }).click();
  await basePage.waitForLoad();
});

Fixtures

Test data setup

files — inline file tree (primary method):

homeTest.use({ files: { "catalog": { "art.md": "# Title", "doc-root.yml": "title: Cat\n" } } });

Keys = dirs/files, strings = content, objects = subdirs, number[] = binary.

dir — load from filesystem: catalogTest.use({ dir: new URL("./test-catalog", import.meta.url) });

zip — upload and extract ZIP file.

Options (web)

files, zip, dir, source ("env" | SourceData), isolated (true), isReadOnly (false), experimentalFeatures (string[]), startUrl ("/").

Editor extras: initMd (string), firstEnter (true).

Options (docportal)

source, user ("env" | AuthCredentials), isolated (true), startUrl ("/").

Serial mode

test.describe.configure({ mode: "serial" }) — when tests depend on each other.

Step grouping

await test.step("label", async () => { ... }) — for better reporting.

POMs

BaseSharedPage (shared-pom/page.ts): goto(path), waitForLoad(), waitForUrl(url), assertUrl(url), assertNoModal(), navigate(path) (pushState), copyFileToClipboard(path), raw (Page), modal (Locator).

HomePage (web/pom/home.page.ts): topBar (TopMenu: getAddCatalog(), getSwitchWorkspace(), getSwitchUiLanguage(), getSwitchTheme()), workspace (WorkspacePom).

CatalogPage (web/pom/catalog.page.ts): currentArticleContent(markdownOnly?), getCatalogActions(), getCatalogProperties(), getNavTreeState(catalogName).

ArticleEditorPom (web/pom/editor.pom.ts): setMarkdown(md, opts?), markdown(), type(text), press(keys), focus(), pasteHtml(html), pasteText(text), forceSave(), clickToolbar(button), hoverToolbar(button), assertMarkdown(expected, opts?), assertMarkdownContains(expected), assertMarkdownValid(), bottom().

WorkspacePom: assertHasCatalogs(names[]), assertCurrentWorkspace(config), assertWorkspaces(configs[]).

CatalogPom (web/pom/catalog.pom.ts): props().

Theme (shared-pom/theme.ts): assertHasTheme(theme), assertThemeChanged(), switch(locator?).

Atoms (shared-pom/atoms/)

Dropdown: open(), close(), isOpen(), getItems(), findItemByTitle(title), assertHasItem(item), assertHasItems(items[]), assertTriggerVisible(), assertContentVisible(), assertContentHidden().

DropdownItem: click(), hover(), assertVisible(), assertHidden(). Props: title, description, hasSubContent.

Button: click(), hover(), text(), assertVisible(), assertHasText(text).

Select (extends Dropdown): uses select-content/select-item test IDs.

Editor Specifics

(*) in setMarkdown = cursor position. Keys: space-separated, modifiers with + (ControlOrMeta+B).

Toolbar buttons: bold, italic, strikethrough, heading-2/3/4, bullet-list, ordered-list, task-list, code, table, note, diagrams, pencil-ruler.

md template tag (@utils/utils) removes indentation from template literals.

Conventions

1. One behavior per test
2. Use POMs, not raw locators
3. getByRole/getByText only — no CSS, no XPath, no data-* hooks. Missing role or name means the component gets fixed; getByTestId is the last resort, not the default
4. waitForLoad() after navigation
5. serial only when order matters
6. files fixture for test data, not manual setup
7. Files: <feature>.spec.ts, group in describe blocks
8. Do not modify test infrastructure (fixtures, POMs, utils, config) without asking. Only *.spec.ts files can be created/edited freely.
9. For examining playwright's trace files use playwright skill