playwright（Playwright 浏览器测试）

Playwright

When to Use This Skill

Use this skill when the user:

Mentions / keywords

• Mentions “Playwright”, “@playwright/test”, “playwright.config.ts”, “trace viewer”, or “PWDEBUG”
• References *.spec.ts / *.test.ts files that import @playwright/test

Context

• Is trying to add or maintain E2E/smoke coverage for a web app
• Is trying to debug flaky UI tests (selectors, timing, waits)
• Needs one-off automation (screenshots, console logs, quick flow checks)

Purpose

• Route Playwright work into the right workflow (suite vs. one-off script vs. debugging)
• Standardize patterns that prevent flaky tests (locators, assertions, waits)
• Keep artifacts in ./tmp/ for predictable cleanup

Quick routing

• Writing/maintaining @playwright/test suites → See references/e2e-with-playwright-test.md
• Auth once, reuse state (storageState) → See references/auth-and-storage-state.md
• CI hardening + config knobs → See references/ci-and-config.md
• Locators, assertions, POM, fixtures → See references/patterns.md
• Fixtures (worker-scoped, auto fixtures) → See references/fixtures.md
• Mocking APIs / controlling network → See references/api-mocking.md
• Visual testing (toHaveScreenshot) → See references/visual-testing.md
• Link checking / dead link detection → See references/link-checking.md
• Flaky tests / trace viewer / retries → See references/debugging.md
• One-off automation (screenshots/logs/check flows) → See references/ad-hoc-automation.md

Non-negotiables

• Prefer getByRole / getByLabel over CSS/XPath; add data-testid only when needed.
• Use web-first assertions (await expect(locator).toBeVisible()) instead of boolean checks.
• Never add waitForTimeout() to “fix” flake; if you use it temporarily while debugging, remove it before calling the work “done”.
• Don’t default to networkidle everywhere; use it intentionally (SPAs / known background activity can make it misleading).
• For CLI agent runs, use minimal reporters to avoid log spam; store artifacts under ./tmp/playwright/.
• Keep tests independent; avoid cross-test shared state.

Verification

• E2E suite changes: run npx playwright test --reporter=line (or --reporter=dot) and confirm failures reproduce.
• Flake fixes: run the previously failing test at least 5 times (ex: --repeat-each 5) before calling it fixed.
• CI-sensitive changes: run the suite in “CI-like” settings (ex: CI=1 npx playwright test --reporter=line) and confirm it still behaves.

Provenance

• Consolidated from upstream installed skills: playwright-best-practices, playwright-testing, playwright-expert, playwright-skill, webapp-testing