---
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.