0 Fork 0

mirror of https://github.com/kevinveenbirkenbach/computer-playbook.git synced 2026-11-08 19:56:53 +00:00

Files

T

kevinveenbirkenbach da140094a1 docs(agents): split iteration loops and refactor Playwright SPOT

Split docs/agents/action/iteration.md into role.md, playwright.md,
workflow.md, and a scope-focused README. Move Certificate Authority
and Inspect rules into role.md. Rewrite playwright.md as a machine-
oriented state machine with explicit preconditions, procedure, exit
gates, and escape path.

Extract Playwright spec content MUSTs into the new contrib SPOT
docs/contributing/artefact/files/role/playwright.specs.js.md. Reduce
the agent-side spec and env.j2 pages to procedure only. Align the
framework SPOT and the test-e2e-playwright role README with the
central templates/package.json.j2 + files/playwright.config.js model
and images.playwright.version as single source of truth.

Sweep em dashes and sentence-case role headings across all touched
docs per documentation.md and readme_md.md rules.

2026-04-19 22:04:24 +02:00

5.5 KiB

Raw Blame History

Playwright Tests 🎭

This page is the SPOT for Playwright end-to-end test requirements, runner integration, and file contracts. For implementation guidance when writing or updating role-local files, see Agent playwright.spec.js and Agent playwright.env.j2. For what the files/playwright.spec.js of a role MUST contain, see playwright.spec.js (role file rules).

Framework 🧰

Playwright runs inside Docker via the shared test-e2e-playwright role.
There is no standalone make target for Playwright. Tests run as part of local deploy flows (e.g. make deploy-fresh-purged-apps APPS=web-app-matomo FULL_CYCLE=true). For spec-only iteration after the first successful deploy, see Playwright Spec Loop.

When to Write ✍️

You MUST provide Playwright tests for every web-* role.
For when a spec MUST be added or updated (including the javascript.js / style.css trigger), see the Scenarios section of playwright.spec.js.

Role-Local Files 📁

Every Playwright-enabled role MUST provide exactly these two files:

File	Purpose
`files/playwright.spec.js`	Test scenarios executed by the Playwright runner
`templates/playwright.env.j2`	Rendered `.env` passed to the Playwright container

playwright.config.js MUST remain centralized in roles/test-e2e-playwright/files/ and package.json in roles/test-e2e-playwright/templates/package.json.j2 (rendered per-deploy into the staging dir). You MUST NOT duplicate or override either per role.

The @playwright/test version pinned into the rendered package.json comes from images.playwright.version in roles/test-e2e-playwright/defaults/main.yml via the image_version filter. That YAML value is the single source of truth for the Playwright version.

CI Image Source 🪞

The Playwright container image is declared in roles/test-e2e-playwright/defaults/main.yml under images.playwright (image: + version:). CI mirrors that image into GHCR through the standard mirror pipeline before deploy tests run, so Playwright jobs do not depend on direct pulls from MCR during the test phase.

The version: MUST stay pinned to an exact Playwright version and distro pair such as v1.59.1-noble. You MUST NOT switch this to a mutable tag such as latest, because mutable upstream tags are more vulnerable to CDN propagation delays and make flaky CI failures much harder to reason about.

Runner 🚀

The test-e2e-playwright role discovers Playwright-enabled roles through the presence of templates/playwright.env.j2. For each discovered role it:

stages the test project
renders .env from playwright.env.j2
copies files/playwright.spec.js into the project as tests/playwright.spec.js
renders the central templates/package.json.j2 and copies the central files/playwright.config.js into the staging dir
waits until the app is reachable
runs Playwright in Docker

File Requirements 📄

See the dedicated SPOT pages for authoring rules:

playwright.spec.js: what the role-local spec MUST contain (entry point, scenarios, selectors, final state)
playwright.env.j2: rendered test input surface, variable naming, and entry-point selection

Recording Tests 🎬

Playwright Codegen (built-in) 🔧

Playwright ships a built-in code recorder:

npx playwright codegen https://<app-url>

This opens the Playwright Inspector alongside a browser. Every interaction is recorded and emitted as a runnable spec. Use the output as a starting draft and clean it up according to the authoring rules in playwright.spec.js.

playwright-recorder (Docker-based) 🐳

For infrastructure-heavy setups where Playwright should not live in the main repository, use playwright-recorder. It wraps Playwright codegen in Docker with X11/XWayland forwarding and an ephemeral workspace so no state leaks between recordings.

Requirements: Docker, X11 or XWayland, xhost

# Install
make install

# Record a flow starting at a specific URL
make codegen
# or directly:
./scripts/codegen.sh https://<app-url>/login

# Replay a recorded spec headlessly
make replay
# or directly:
./scripts/replay.sh recordings/login.spec.ts

Generated files are persisted in the local workspace (git-ignored). Copy the relevant parts into files/playwright.spec.js and adapt them.

Development Procedure 📋

This page owns framework and runner mechanics only. The procedure for writing, deploying, and reviewing a role-local spec lives in the dedicated SPOTs:

Agent playwright.spec.js: authoring procedure and live review.
Role Loop: baseline deploy, redeploy rules, Certificate Authority trust, Inspect-before-redeploy.
Playwright Spec Loop: spec-only inner loop against the already-running stack.
playwright.spec.js (role file rules): what the spec MUST contain, including logged-out final state and console cleanliness.

5.5 KiB Raw Blame History