/playwright — Browser Runtime Tests
Core Rule
Use Playwright when the acceptance signal depends on a real browser: routing, forms, auth flows, rendering, navigation, API-backed UI state, responsive layouts, downloads/uploads, or regressions that unit tests cannot see.
For Athena v9.8.0, this skill is the frontend/E2E test arm of athena-runtime-verify. It should produce evidence that can be pasted into sprints/{slug}/runtime-verify.md under ## 测试场景 (实跑).
Official references:
Workflow
Detect project setup before adding anything:
- Existing Playwright: inspect
playwright.config.*, tests/, e2e/, package.json scripts.
- No Playwright: prefer adding
@playwright/test and a minimal config/test file that fits the repo.
- If the repo already uses Cypress/Vitest browser mode/etc., avoid wholesale migration; add Playwright only if runtime verification needs real browser coverage.
Start or reuse a deterministic app target:
- Prefer an existing dev/preview script from
package.json.
- Use a fixed port when possible.
- Set
baseURL in config or pass it via PLAYWRIGHT_BASE_URL.
- Do not leave background servers running at the end of the task.
Write tests through user-visible behavior:
- Use role/text/test-id locators instead of brittle CSS/XPath.
- Use Playwright web-first assertions such as
await expect(locator).toBeVisible().
- Keep tests small: one critical flow or acceptance behavior per test.
- Cover at least normal, boundary, and failure/empty states when doing
runtime-verify.
Run and iterate:
- Main path:
npx playwright test.
- Debug path:
npx playwright test --headed, npx playwright test --ui, or npx playwright codegen <url> when exploring selectors.
- Trace path:
npx playwright test --trace on then inspect with npx playwright show-trace <trace.zip>.
- If browser binaries are missing, run
npx playwright install or the narrower browser install requested by the repo.
Record evidence:
- Include exact command, exit code, and the important pass/fail output.
- For
athena-runtime-verify, write a row in runtime-verify.md with scenario, type, command, actual output, and verdict.
- If a test first fails and then passes after a fix, record both the failing symptom and the passing rerun.
Athena Integration
Feature: use when UI/API behavior is risky or user-visible.Refactor/System: use for browser-facing flows before review; this is part of runtime verification.Bugfix: use when the bug is reproducible in the browser, even though full runtime-verify is usually skipped.Hotfix/Quick: run only the smallest smoke path needed.
Resources
Read references/runtime-patterns.md when you need concrete command patterns, config snippets, or evidence table examples.
1---2name: playwright-33description: Playwright browser/E2E testing workflow for runtime verification. Use when Codex needs to add, run, debug, or document frontend/browser tests, smoke-test a dev server, verify UI flows during athena-runtime-verify, capture traces/screenshots, or turn manual browser checks into repeatable tests.4---56# /playwright — Browser Runtime Tests78## Core Rule910Use Playwright when the acceptance signal depends on a real browser: routing, forms, auth flows, rendering, navigation, API-backed UI state, responsive layouts, downloads/uploads, or regressions that unit tests cannot see.1112For Athena v9.8.0, this skill is the frontend/E2E test arm of `athena-runtime-verify`. It should produce evidence that can be pasted into `sprints/{slug}/runtime-verify.md` under `## 测试场景 (实跑)`.1314Official references:15- Playwright intro: https://playwright.dev/docs/intro16- Writing tests: https://playwright.dev/docs/writing-tests17- CLI: https://playwright.dev/docs/test-cli18- Codegen: https://playwright.dev/docs/codegen19- Trace viewer: https://playwright.dev/docs/trace-viewer2021## Workflow22231. Detect project setup before adding anything:24 - Existing Playwright: inspect `playwright.config.*`, `tests/`, `e2e/`, `package.json` scripts.25 - No Playwright: prefer adding `@playwright/test` and a minimal config/test file that fits the repo.26 - If the repo already uses Cypress/Vitest browser mode/etc., avoid wholesale migration; add Playwright only if runtime verification needs real browser coverage.27282. Start or reuse a deterministic app target:29 - Prefer an existing dev/preview script from `package.json`.30 - Use a fixed port when possible.31 - Set `baseURL` in config or pass it via `PLAYWRIGHT_BASE_URL`.32 - Do not leave background servers running at the end of the task.33343. Write tests through user-visible behavior:35 - Use role/text/test-id locators instead of brittle CSS/XPath.36 - Use Playwright web-first assertions such as `await expect(locator).toBeVisible()`.37 - Keep tests small: one critical flow or acceptance behavior per test.38 - Cover at least normal, boundary, and failure/empty states when doing `runtime-verify`.39404. Run and iterate:41 - Main path: `npx playwright test`.42 - Debug path: `npx playwright test --headed`, `npx playwright test --ui`, or `npx playwright codegen <url>` when exploring selectors.43 - Trace path: `npx playwright test --trace on` then inspect with `npx playwright show-trace <trace.zip>`.44 - If browser binaries are missing, run `npx playwright install` or the narrower browser install requested by the repo.45465. Record evidence:47 - Include exact command, exit code, and the important pass/fail output.48 - For `athena-runtime-verify`, write a row in `runtime-verify.md` with scenario, type, command, actual output, and verdict.49 - If a test first fails and then passes after a fix, record both the failing symptom and the passing rerun.5051## Athena Integration5253- `Feature`: use when UI/API behavior is risky or user-visible.54- `Refactor/System`: use for browser-facing flows before review; this is part of runtime verification.55- `Bugfix`: use when the bug is reproducible in the browser, even though full runtime-verify is usually skipped.56- `Hotfix/Quick`: run only the smallest smoke path needed.5758## Resources5960Read `references/runtime-patterns.md` when you need concrete command patterns, config snippets, or evidence table examples.
wenjunduan