write-e2e-tests · diff
git:20260814.9a8c19b to git:20260814.94a28da
53 added, 39 removed. Audit A to A.
---
name: write-e2e-tests
description: >-
- Use when converting a completed webwright browser-exploration run into a
- durable, checked-in Playwright Test e2e spec — mapping its plan.md
- Critical Points to assertions and validating the result is stable and
- CI-discoverable. Browser-driven UI flows only; not for API-level
- end-to-end tests.
+ Use when the user wants browser UI e2e as a Playwright Test spec —
+ converting a completed webwright run, or unblocking a missing
+ Playwright toolchain or webwright run first. Not for API-level end-to-end
+ tests.
---
# Write E2E Tests
- Converts a finished [webwright](https://github.com/microsoft/Webwright) run
- into a standalone Playwright Test spec. Webwright is Microsoft Research's
- browser-automation Claude Code skill; install it from that repo if it isn't
- already available. Its own Plan → Explore → Author → Execute → Self-verify →
- Done workflow is the exploration engine, unchanged — this skill starts only
- after that run has completed, and adds exactly one capability: turning it
- into a test that lives in the project's e2e suite and runs again on its own.
+ Turns a browser UI flow into a checked-in Playwright Test spec.
+ [Webwright](https://github.com/microsoft/Webwright) is the exploration engine:
+ it produces `plan.md` and `final_script.py`. This skill unblocks a missing
+ toolchain or run after confirmation, then converts.
## Scope
- **Browser-driven UI flows only** — not API-level end-to-end tests. The
- output is always a Playwright Test spec — no per-project detection of
- another framework, no cross-framework translation.
+ The output is always a Playwright Test spec — no per-project detection of
+ another framework, no cross-framework translation. An existing Cypress or
+ Selenium suite stays; confirm before adding Playwright beside it.
## Workflow
- 1. **Check webwright is installed.** If not, guide the user through
- installing it and wait for their explicit confirmation before proceeding.
+ 1. **Inventory.** In the target project, mark each of these present or
+ absent: a JS package manifest and its package manager; `@playwright/test`
+ and `playwright.config`; the webwright skill; a qualifying run; another
+ e2e stack (Cypress, Selenium); existing CI files; webwright artifact
+ paths git still tracks. Leave this step when every item is marked. No
+ package manifest — stop and report.
- 2. **Check Playwright Test is set up** in the target project. No
- `@playwright/test` dependency or `playwright.config` at all — stop and
- report this. Don't install or scaffold it yourself; that's the user's
- call.
+ 2. **Toolchain.** If Playwright, browsers, or webwright are missing, confirm
+ once for those items and follow
+ [references/setup.md](references/setup.md). Another e2e stack without
+ Playwright — confirm adding Playwright beside it.
- 3. **Convert.** Take a webwright run that has already finished — its
- `plan.md` and `final_script.py` — and produce a standalone Playwright
- Test spec file. How to handle a scan hit is in
- [references/security.md](references/security.md).
+ 3. **Find a qualifying run.** Search `outputs/`, `final_runs/`, and any
+ path the user named for `plan.md` plus `final_script.py` whose
+ Critical Points are all checked. Found — show the path and reuse it
+ unless the user asks to re-run. Otherwise go to *explore*.
+
+ 4. **Explore.** Confirm on its own before driving the real site. If the
+ user has not named the flow, ask. Load webwright's `SKILL.md` and run
+ it to Done. Convert is the next step. Exploration stays in webwright.
+
+ 5. **Repo — gitignore.** Propose `.gitignore` rules when unignored
+ webwright artifacts exist (`outputs/`, `final_runs/`, screenshots/logs)
+ or this run just scaffolded Playwright (`test-results/`,
+ `playwright-report/`). Write only after confirmation. Add rules only;
+ do not `git rm --cached` already-tracked files.
+
+ 6. **Convert.** Take the qualifying run's `plan.md` and `final_script.py`
+ and produce a standalone Playwright Test spec file. How to handle a
+ scan hit is in [references/security.md](references/security.md).
- **Scan input.** Run `scripts/scan-secrets.sh` on `final_script.py`.
Non-zero exit: follow that doc. A visual read of the script is not
a scan.
- **Map and draft.** Map each Critical Point in `plan.md` one-to-one to an
- `expect()` assertion; that mapping is the whole of the conversion,
- don't re-derive what to assert from scratch. Put credential values
- in `process.env`; leave selectors and non-credential fixtures as
- literals.
+ `expect()` assertion; that mapping is the whole of the conversion.
+ Put credential values in `process.env`; leave selectors and
+ non-credential fixtures as literals.
- **Scan output.** Run `scripts/scan-secrets.sh` on the drafted spec
- before writing it. Non-zero exit: follow that doc. Do not write a
- spec the script rejects.
+ before writing it. Non-zero exit: follow that doc. Write only a spec
+ the script accepts.
Place the spec in the project's existing e2e test directory (its
Playwright config's `testDir`, or the project's established
convention), named after the flow being converted.
- 4. **Validate.** Run all three gates, in order:
+ 7. **Validate.** Run all three gates, in order:
- **Run** — execute the generated spec once; it passes.
- - **Stable** — re-run it 3 consecutive times; all 3 pass. Confirms the
- flow isn't flaky.
- - **Discoverable** — the project's test-run/CI configuration finds the
- new spec file.
+ - **Stable** — re-run it 3 consecutive times; all 3 pass.
+ - **Discoverable** — the project's test-run command finds the new spec
+ file. A remote pipeline is not required.
+ On failure, attempt an automatic fix and re-validate, up to 2 attempts.
+ Still failing after that — stop and report. Hand back only a spec that
+ has passed all three gates.
- 5. **On failure**, attempt an automatic fix and re-validate, up to 2 attempts.
- Still failing after that — stop and report the failure and its likely
- cause. Don't hand back a spec that hasn't passed all three gates.
+ 8. **Repo — CI.** After Validate, follow
+ [references/ci.md](references/ci.md). Write only after confirmation.