菜单
Unblock a failing or hard-to-author Playwright test — UI mode, codegen, trace viewer, Inspector, page.pause(), failure artifacts. Use whenever a test fails mysteriously, when you need to discover a locator, or when stepping through a flow.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
Decide WHEN to drive the browser MCP, WHEN to invoke a Playwright Test Agent (planner/generator/healer), and WHEN to just edit files. The orchestrator skill — read this first when a Playwright task comes in.
Mix API calls into Playwright suites — pure API tests via the request fixture and hybrid tests that seed state via API then assert through the UI. Use when login/setup is slow, when verifying side-effects, or for API regression coverage alongside UI.
Use Playwright as an investigation tool, not just a regression suite — broken-image audits, console-error capture, failed-request capture, negative-path tests, accessibility scans. Use during exploratory testing or whenever a real bug is suspected but not reliably reproducible.
Build custom Playwright fixtures, skip repeated login with storage state, and keep tests isolated so they run in any order in parallel. Use when tests need auth, share setup, or are slow because every test re-logs-in.
Pick locators that survive UI changes and lean on Playwright's auto-waiting to kill flakes. Use when authoring or refactoring a spec, replacing brittle CSS/XPath, or chasing flaky failures.
Make tests deterministic and fast by controlling the network — page.route for stubs, HAR record/replay, request/response modification, WebSocket mocking. Use when tests are flaky due to a slow/unreliable backend, when testing edge-case responses, or when running CI without external services.
| name | playwright-debugging |
| description | Unblock a failing or hard-to-author Playwright test — UI mode, codegen, trace viewer, Inspector, page.pause(), failure artifacts. Use whenever a test fails mysteriously, when you need to discover a locator, or when stepping through a flow. |
Five tools, in the order to reach for them.
--ui — primary workflownpx playwright test --ui
Time-travel DOM snapshots per step, file watcher, locator picker. Replaces 90% of console.log.
codegen — discover a locatornpx playwright codegen http://localhost:5173/login
Click in the browser → it writes the test. Treat output as a starting point, not a commit. It often picks brittle text or nth(n).
This repo's config sets trace: 'on-first-retry'. View a saved trace:
npx playwright show-trace test-results/.../trace.zip
Look at: failed step's DOM snapshot, network tab (5xx? slow?), console tab (JS errors).
--debug — Inspector + step throughnpx playwright test path/to.spec.ts:9 --debug
Hover any locator → highlight. Edit locator inline → see what matches.
await page.pause() — drop-in breakpointawait page.pause();
Runs normally until hit, then opens Inspector.
use: {
trace: 'retain-on-failure',
screenshot: 'only-on-failure',
video: 'retain-on-failure',
},
Most "what happened?" tickets answer themselves once these are on.
| Situation | Reach for |
|---|---|
| Test failed, don't know why | HTML report → trace |
| Need to write a new locator | codegen or --ui locator picker |
| Step through line by line | --debug or page.pause() |
| Passes locally, fails in CI | trace: 'retain-on-failure', download artifact |
| Flakes 1 in 10 | Usually a missing expect(...) before the action — check trace's last passing step |