mygo/.agents/skills/playwright-cli/SKILL.md

name, description

name	description
playwright-cli	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/:

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:

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:

# 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:

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:

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:

mise exec -- npm run playwright:cli -- screenshot --filename=.artifacts/playwright-cli/mygo-debug.png

7. Close every session when finished, including error paths:

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/:

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 before using this workflow.

Load detailed references only when needed

• Read element-attributes.md when snapshots omit a required DOM attribute.
• Read playwright-tests.md when attaching to a paused Playwright Test run.
• Read request-mocking.md when reproducing API failures with browser-level routes.
• Read running-code.md for multi-step page evaluation that individual CLI commands cannot express.
• Read session-management.md for named, persistent, attached, or parallel sessions.
• Read spec-driven-testing.md when planning, generating, or healing E2E scenarios.
• Read storage-state.md when inspecting or preserving cookies, local storage, or session storage.
• Read test-generation.md when translating an interactive session into Playwright test code.
• Read tracing.md for trace capture and diagnosis.
• Read 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.