ld
52dd56ff06
- feat: add `.agents/skills/playwright-cli/` with complete Skill markdown, agent interface, and 9 reference files covering session management, spec-driven testing, video recording, tracing, storage, request mocking, element attributes, test debugging, and running custom code - feat: add `.playwright/cli.config.json` to configure the Playwright CLI - feat: add `web/package.json` `playwright:cli` script that resolves `playwright cli` from the repo root - build: remove `@playwright/mcp` dependency from `web/package.json` - build: set `XDG_CACHE_HOME` in `mise.toml` - build: delete `.codex/config.toml` (MCP server config) - docs: update `README.md`, `docs/web/roadmap.md`, `docs/web/decisions.md`, and `web/README.md` to reflect the new Playwright CLI approach
108 lines
5.3 KiB
Markdown
108 lines
5.3 KiB
Markdown
---
|
|
name: playwright-cli
|
|
description: Debug and automate the MyGO Web interface with the repository-pinned Playwright CLI. Use for headless browser inspection, login and file-flow debugging, screenshots, DOM snapshots, console or network diagnosis, Playwright test debugging, and browser-driven verification in this repository.
|
|
---
|
|
|
|
# Debug MyGO with Playwright CLI
|
|
|
|
Use the Playwright CLI bundled with the locked `@playwright/test` dependency. Keep every browser action behind the repository npm script so a future CLI entry-point change is isolated to `web/package.json`.
|
|
|
|
## Use the repository command contract
|
|
|
|
Run browser commands from `web/`:
|
|
|
|
```bash
|
|
mise exec -- npm run playwright:cli -- <command> [arguments]
|
|
```
|
|
|
|
The npm script changes to the repository root before starting Playwright. This makes the CLI discover `.playwright/cli.config.json` and keeps generated output under `.artifacts/playwright-cli/`.
|
|
|
|
Never invoke `playwright-cli`, `npx playwright-cli`, `npx playwright`, a global Playwright installation, or `@latest`. Do not install `@playwright/cli`; the locked stable `@playwright/test` package supplies the CLI.
|
|
|
|
## Prepare the local environment
|
|
|
|
Install locked JavaScript dependencies and the matching Chromium revision:
|
|
|
|
```bash
|
|
cd web
|
|
mise exec -- npm ci
|
|
mise exec -- npm run playwright:install:deps
|
|
mise exec -- npm run playwright:install
|
|
```
|
|
|
|
Treat the Debian system-library command as an environment setup step. Do not rerun it during ordinary debugging when the dependencies are already present.
|
|
|
|
For authenticated file workflows, start both services in separate long-running terminals:
|
|
|
|
```bash
|
|
# Repository root: backend API on 127.0.0.1:10086.
|
|
mise exec -- go run . serve
|
|
|
|
# web/: Vite on 127.0.0.1:5173, proxying /api to the backend.
|
|
mise exec -- npm run dev -- --host 127.0.0.1
|
|
```
|
|
|
|
Use existing local test credentials or credentials supplied for the task. Never write credentials into the Skill, source files, screenshots, or reports. Keep upload fixtures below 20 MB for the current milestone.
|
|
|
|
## Follow the debugging loop
|
|
|
|
1. Reproduce the problem with the narrowest existing test first. Confirm the test expresses the intended behavior before changing implementation code.
|
|
2. Confirm the required server is reachable. The login page itself only needs Vite; login, list, upload, and download also need the Go backend and suitable local data.
|
|
3. Open the page and read its accessibility snapshot:
|
|
|
|
```bash
|
|
mise exec -- npm run playwright:cli -- open http://127.0.0.1:5173/login
|
|
mise exec -- npm run playwright:cli -- snapshot
|
|
```
|
|
|
|
4. Use refs from the latest snapshot for interactions. Take another snapshot after navigation, modal changes, or substantial rerenders because refs can become stale.
|
|
5. Inspect browser and API evidence before guessing:
|
|
|
|
```bash
|
|
mise exec -- npm run playwright:cli -- console
|
|
mise exec -- npm run playwright:cli -- requests
|
|
mise exec -- npm run playwright:cli -- request <number>
|
|
```
|
|
|
|
6. Prefer snapshots for structure and screenshots for visual evidence:
|
|
|
|
```bash
|
|
mise exec -- npm run playwright:cli -- screenshot --filename=.artifacts/playwright-cli/mygo-debug.png
|
|
```
|
|
|
|
7. Close every session when finished, including error paths:
|
|
|
|
```bash
|
|
mise exec -- npm run playwright:cli -- close
|
|
mise exec -- npm run playwright:cli -- close-all
|
|
```
|
|
|
|
Use a named session with `-s=<name>` when parallel or persistent investigations would otherwise collide. Keep sessions isolated unless the task explicitly requires saved state.
|
|
|
|
## Debug Playwright tests
|
|
|
|
Run the repository suite from `web/`:
|
|
|
|
```bash
|
|
mise exec -- npm run test:e2e
|
|
```
|
|
|
|
For interactive debugging, start the test with `--debug=cli`, wait for its `tw-*` session name, then attach through the same npm wrapper. Read [playwright-tests.md](references/playwright-tests.md) before using this workflow.
|
|
|
|
## Load detailed references only when needed
|
|
|
|
- Read [element-attributes.md](references/element-attributes.md) when snapshots omit a required DOM attribute.
|
|
- Read [playwright-tests.md](references/playwright-tests.md) when attaching to a paused Playwright Test run.
|
|
- Read [request-mocking.md](references/request-mocking.md) when reproducing API failures with browser-level routes.
|
|
- Read [running-code.md](references/running-code.md) for multi-step page evaluation that individual CLI commands cannot express.
|
|
- Read [session-management.md](references/session-management.md) for named, persistent, attached, or parallel sessions.
|
|
- Read [spec-driven-testing.md](references/spec-driven-testing.md) when planning, generating, or healing E2E scenarios.
|
|
- Read [storage-state.md](references/storage-state.md) when inspecting or preserving cookies, local storage, or session storage.
|
|
- Read [test-generation.md](references/test-generation.md) when translating an interactive session into Playwright test code.
|
|
- Read [tracing.md](references/tracing.md) for trace capture and diagnosis.
|
|
- Read [video-recording.md](references/video-recording.md) only when a video materially improves the debugging result.
|
|
|
|
## Preserve repository boundaries
|
|
|
|
Write screenshots, traces, videos, downloaded responses, and temporary upload fixtures only under ignored `.artifacts/` paths. Do not change application data, create accounts, or call destructive UI actions unless the task authorizes those effects. Report browser launch or sandbox failures instead of silently disabling the configured Chromium sandbox.
|