Web System Tests

Write, run, and maintain browser-driven system tests for $ARGUMENTS. Apply all rules below strictly.

Composition

• /system-tests owns the contract — black box, running system, coordinates as configuration, isolation, total verdict reporting. This skill is its web realization: layout, configuration, selector policy, test syntax, and the green oracle.
• The stack skill owns the application under test — /web-components (SPA), /web-sprinkles, or /web-static.
• /ears-tests owns spec-derived expectations: one test.describe per requirement group, the literal Rn.m id in the test title.
• /bce owns where things live: one spec file per business component, named after it.

Versus the Chrome DevTools verification loop

/web-static drives the rendered page through Chrome DevTools MCP — console, accessibility snapshot, viewport, Lighthouse, Baseline. That loop inspects the page as it is right now: agent-driven, single-shot, leaving no artifact behind. This skill produces a committed suite re-run by a machine on every change, in three engines, indefinitely.

Neither replaces the other. Rendering, accessibility tree, contrast, and Baseline compliance belong to the DevTools loop; user-visible behavior, and its survival across changes, belongs here. Where a project has both, green means both.

The public surface of a web UI is its accessibility tree

/system-tests permits assertions through the public surface only. For an HTTP service that surface is the endpoint; for a web UI it is everything the user can perceive and operate — which is exactly what the accessibility tree exposes. So the selector policy is a consequence of the contract, not a style preference:

• Locate by role, label, text, or placeholder: getByRole, getByLabel, getByText, getByPlaceholder.
• CSS selectors, ids, class names, nth-child, DOM shape, shadow-root piercing, and store internals are implementation. A test bound to them fails on a refactor that changed nothing a user can see — which is a false alarm, and false alarms are what kill suites.

The payoff shows up when a locator finds nothing: an element with no accessible name is a defect in the application — a missing <label>, a button whose text is an icon, a heading that is a styled <div>. Fix the markup per /web-conventions. Reaching for a CSS selector instead hides a real accessibility bug behind a passing test.

Project layout

project/
├── app/src/                     # the application — stack skill's concern
└── tests/                       # the suite; never shipped with the app
    ├── package.json
    ├── playwright.config.js
    ├── fixtures.js              # only when coverage is enabled
    └── tests/
        └── <business-component>.spec.js

Setup, once:

npm install -D @playwright/test
npx playwright install          # add --with-deps on CI

Tests live outside the served root so the suite is never deployed, and the application keeps its zero-dependency, no-build-system property — the harness is not the artifact.

Configuration

// @ts-check
const { defineConfig, devices } = require('@playwright/test');

module.exports = defineConfig({
  testDir: './tests',
  fullyParallel: true,
  forbidOnly: !!process.env.CI,
  retries: process.env.CI ? 2 : 0,
  workers: process.env.CI ? 1 : undefined,
  reporter: 'html',
  use: {
    baseURL: process.env.BASE_URL ?? 'http://localhost:3000',
    trace: 'on-first-retry',
  },
  webServer: {
    command: 'java zws ../app/src --single',
    url: 'http://localhost:3000',
    reuseExistingServer: !process.env.CI,
  },
  projects: [
    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
    { name: 'firefox', use: { ...devices['Desktop Firefox'] } },
    { name: 'webkit', use: { ...devices['Desktop Safari'] } },
  ],
});

• baseURL, and page.goto('/') in tests. A URL literal repeated in every test is the hardcoded coordinate /system-tests forbids: the suite then runs against one machine only. Port 3000 is the default because that is where the dev server already listens; BASE_URL retargets the whole suite at a deployed preview or a migration target without touching a test.
• webServer with reuseExistingServer. While authoring, your zws is already up on 3000 and Playwright attaches to it — the suite exercises the same server you are clicking through, with live reload intact. On CI nothing is listening, so Playwright starts it. One configuration, no flag to remember, no second port.
• --single serves index.html for extension-less unknown paths, which client-side routing needs for deep links (/bookmarks/edit/3). Drop it for /web-static and /web-sprinkles sites: there a real file backs every URL, and the fallback would turn a broken link into a false 200.
• Three engines. A stack built on web standards claims three engines, so it is tested in three. A test that passes only in Chromium is evidence of a feature below Widely Available; the fix is the /web-conventions Baseline policy, never the removal of a project.
• trace: 'on-first-retry' makes a CI failure debuggable without a reproduction attempt — npx playwright show-trace replays the run.

Writing tests

• One test per user-visible outcome, named for the outcome ('edits a bookmark label'), not for the mechanics.
• Arrange through the UI. Reaching into localStorage, the store, or a backend to plant state is exactly the internal access the black-box contract excludes — and it silently stops testing the path a user takes to create that state. When arranging through the UI is too slow to bear, declare the seed data explicitly rather than assuming it.
• Assert with web-first assertions — await expect(locator).toBeVisible(), .toHaveText(), .toHaveValue(). They retry until they pass or time out, so the wait is bounded by the actual event, not by a guess.
• No sleeps. waitForTimeout is both slower than an auto-waiting assertion on a fast machine and shorter than the truth on a loaded one — it is the standard source of flakiness. If a test needs a wait that assertions cannot express, wait for the observable event (waitForURL, expect(locator).toBeVisible()), never for a duration.
• fill() by default; pressSequentially only when keystrokes matter. fill() sets the value and emits one input event, which is all a plain store-bound handler needs. Per-keystroke entry is required when the behavior under test depends on the intermediate states — typeahead, debounce, as-you-type validation, character counters — and there the delay is part of the test, not decoration.
• Isolation comes from the default fixture. Each test gets a fresh browser context, so cookies, localStorage, and IndexedDB start empty; the /system-tests isolation rule holds as long as tests do not share a page or a context between them. A suite that needs shared state between tests is a suite whose tests are steps of one test.
• Stubbing marks the boundary. page.route may stand in for a backend outside the system under test. It redraws the black-box boundary, so state which service is stubbed in the test name or a comment — an undeclared stub reads as end-to-end coverage that does not exist.
• Never commit test.only — forbidOnly fails the CI run rather than quietly testing one case.

Spec-derived tests

When the expectations come from an /sbce capability spec, /ears-tests owns the transform: one test.describe per requirement group Rn, one test per statement Rn.m, with the literal id leading the test title so it appears in reports and greps against the spec. The concrete shape is in that skill's references/realizations.md (Playwright section). This skill still governs how those tests locate, assert, and run.

Coverage — one spec source, opt-in run

Coverage answers "what did the suite never touch". It informs; it never gates. Green is the suite passing.

page.coverage is Chromium-only, so coverage is a separate, single-engine run over the same spec files — never a forked copy of them. A duplicated suite drifts from its original within a few commits, and the copy that silently stopped matching is the one still reporting green.

Keep the specs importing from a local module that decides what test means:

// tests/fixtures.js
module.exports = process.env.COVERAGE
  ? require('./coverage-fixtures')
  : require('@playwright/test');

// tests/tests/bookmarks.spec.js
const { test, expect } = require('../fixtures');

coverage-fixtures.js extends the page fixture — start JS and CSS coverage with resetOnNavigation: false before handing the page to the test, collect and add it to a module-level Monocart report afterwards, and generate the report in globalTeardown. Consult the monocart-coverage-reports documentation for the current API shape before writing it.

Overriding the fixture rather than the tests is what keeps the single spec source: the test bodies never learn that coverage exists, and the isolation rule survives — no shared page, no serial mode.

Run it with COVERAGE=1 npx playwright test --project=chromium.

Running, and green

• npx playwright test — the suite, all engines.
• npx playwright test --ui — while authoring: time-travel, locator picker, watch mode.
• npx playwright show-report — the last HTML report.

Green = every test passes in every configured project. Report per test, engine included; a skip is a verdict that must be stated with its reason, never an omission. Anything less than all-green is red.

Run the suite after every change to application code and fix before moving on — a suite consulted only before a release stops being an oracle and becomes archaeology. When the stack skill also defines a Chrome DevTools loop, both must be green.

What NOT to do

• Do not locate by CSS selector, id, class, DOM position, or through a shadow root
• Do not read or write the store, localStorage, or a database to arrange or assert
• Do not use waitForTimeout or any sleep
• Do not repeat a URL literal in tests — baseURL plus page.goto('/')
• Do not fork the spec files for a second configuration
• Do not gate green on a coverage number
• Do not drive unit-level concerns through the browser — a pure function's edge cases are not a system test, they are ten seconds of browser startup buying nothing