pw-review

# Review Playwright Tests

Systematically review Playwright test files for anti-patterns, missed best practices, and coverage gaps.

## Input

`$ARGUMENTS` can be:
- A file path: review that specific test file
- A directory: review all test files in the directory
- Empty: review all tests in the project's `testDir`

## Steps

### 1. Gather Context

- Read `playwright.config.ts` for project settings
- List all `*.spec.ts` / `*.spec.js` files in scope
- If reviewing a single file, also check related page objects and fixtures

### 2. Check Each File Against Anti-Patterns

Load `anti-patterns.md` from this skill directory. Check for all 20 anti-patterns.

**Critical (must fix):**
1. `waitForTimeout()` usage
2. Non-web-first assertions (`expect(await ...)`)
3. Hardcoded URLs instead of `baseURL`
4. CSS/XPath selectors when role-based exists
5. Missing `await` on Playwright calls
6. Shared mutable state between tests
7. Test execution order dependencies

**Warning (should fix):**
8. Tests longer than 50 lines (consider splitting)
9. Magic strings without named constants
10. Missing error/edge case tests
11. `page.evaluate()` for things locators can do
12. Nested `test.describe()` more than 2 levels deep
13. Generic test names ("should work", "test 1")

**Info (consider):**
14. No page objects for pages with 5+ locators
15. Inline test data instead of factory/fixture
16. Missing accessibility assertions
17. No visual regression tests for UI-heavy pages
18. Console error assertions not checked
19. Network idle waits instead of specific assertions
20. Missing `test.describe()` grouping

### 3. Score Each File

Rate 1-10 based on:
- **9-10**: Production-ready, follows all golden rules
- **7-8**: Good, minor improvements possible
- **5-6**: Functional but has anti-patterns
- **3-4**: Significant issues, likely flaky
- **1-2**: Needs rewrite

### 4. Generate Review Report

For each file:
```
## <filename> — Score: X/10

### Critical
- Line 15: `waitForTimeout(2000)` → use `expect(locator).toBeVisible()`
- Line 28: CSS selector `.btn-submit` → `getByRole('button', { name: "submit" })`

### Warning
- Line 42: Test name "test login" → "should redirect to dashboard after login"

### Suggestions
- Consider adding error case: what happens with invalid credentials?
```

### 5. For Project-Wide Review

If reviewing an entire test suite:
- Spawn sub-agents per file for parallel review (up to 5 concurrent)
- Or use `/batch` for very large suites
- Aggregate results into a summary table

### 6. Offer Fixes

For each critical issue, provide the corrected code. Ask user: "Apply these fixes? [Yes/No]"

If yes, apply all fixes using `Edit` tool.

## Output

- File-by-file review with scores
- Summary: total files, average score, critical issue count
- Actionable fix list
- Coverage gaps identified (pages/features with no tests)

{
  "format": "aiskill/v1",
  "skill": {
    "name": "pw-review",
    "slug": "playwright-pw-review",
    "version": "1.0.0",
    "description": "Review Playwright tests for quality. Use when user says \"review tests\", \"check test quality\", \"audit tests\", \"improve tests\", \"test code review\", or \"playwright best practices check\".",
    "category": "Development",
    "tags": [
      "testing",
      "code-review"
    ],
    "platforms": [
      "chatgpt",
      "claude-code",
      "cursor"
    ],
    "tested_environment": "Agent Skills convention (SKILL.md) — works with Claude Code, Cursor, ChatGPT/Codex and compatible agents",
    "license": "MIT"
  },
  "prompts": {
    "system": "# Review Playwright Tests\r\n\r\nSystematically review Playwright test files for anti-patterns, missed best practices, and coverage gaps.\r\n\r\n## Input\r\n\r\n`$ARGUMENTS` can be:\r\n- A file path: review that specific test file\r\n- A directory: review all test files in the directory\r\n- Empty: review all tests in the project's `testDir`\r\n\r\n## Steps\r\n\r\n### 1. Gather Context\r\n\r\n- Read `playwright.config.ts` for project settings\r\n- List all `*.spec.ts` / `*.spec.js` files in scope\r\n- If reviewing a single file, also check related page objects and fixtures\r\n\r\n### 2. Check Each File Against Anti-Patterns\r\n\r\nLoad `anti-patterns.md` from this skill directory. Check for all 20 anti-patterns.\r\n\r\n**Critical (must fix):**\r\n1. `waitForTimeout()` usage\r\n2. Non-web-first assertions (`expect(await ...)`)\r\n3. Hardcoded URLs instead of `baseURL`\r\n4. CSS/XPath selectors when role-based exists\r\n5. Missing `await` on Playwright calls\r\n6. Shared mutable state between tests\r\n7. Test execution order dependencies\r\n\r\n**Warning (should fix):**\r\n8. Tests longer than 50 lines (consider splitting)\r\n9. Magic strings without named constants\r\n10. Missing error/edge case tests\r\n11. `page.evaluate()` for things locators can do\r\n12. Nested `test.describe()` more than 2 levels deep\r\n13. Generic test names (\"should work\", \"test 1\")\r\n\r\n**Info (consider):**\r\n14. No page objects for pages with 5+ locators\r\n15. Inline test data instead of factory/fixture\r\n16. Missing accessibility assertions\r\n17. No visual regression tests for UI-heavy pages\r\n18. Console error assertions not checked\r\n19. Network idle waits instead of specific assertions\r\n20. Missing `test.describe()` grouping\r\n\r\n### 3. Score Each File\r\n\r\nRate 1-10 based on:\r\n- **9-10**: Production-ready, follows all golden rules\r\n- **7-8**: Good, minor improvements possible\r\n- **5-6**: Functional but has anti-patterns\r\n- **3-4**: Significant issues, likely flaky\r\n- **1-2**: Needs rewrite\r\n\r\n### 4. Generate Review Report\r\n\r\nFor each file:\r\n```\r\n## <filename> — Score: X/10\r\n\r\n### Critical\r\n- Line 15: `waitForTimeout(2000)` → use `expect(locator).toBeVisible()`\r\n- Line 28: CSS selector `.btn-submit` → `getByRole('button', { name: \"submit\" })`\r\n\r\n### Warning\r\n- Line 42: Test name \"test login\" → \"should redirect to dashboard after login\"\r\n\r\n### Suggestions\r\n- Consider adding error case: what happens with invalid credentials?\r\n```\r\n\r\n### 5. For Project-Wide Review\r\n\r\nIf reviewing an entire test suite:\r\n- Spawn sub-agents per file for parallel review (up to 5 concurrent)\r\n- Or use `/batch` for very large suites\r\n- Aggregate results into a summary table\r\n\r\n### 6. Offer Fixes\r\n\r\nFor each critical issue, provide the corrected code. Ask user: \"Apply these fixes? [Yes/No]\"\r\n\r\nIf yes, apply all fixes using `Edit` tool.\r\n\r\n## Output\r\n\r\n- File-by-file review with scores\r\n- Summary: total files, average score, critical issue count\r\n- Actionable fix list\r\n- Coverage gaps identified (pages/features with no tests)",
    "user_template": ""
  },
  "variables": [],
  "install": {
    "steps": [
      {
        "title": "Download & unzip",
        "detail": "Download the .zip package from SkillVault and unzip it. The playwright-pw-review/ folder contains SKILL.md plus any companion scripts, references and assets."
      },
      {
        "title": "Copy into your agent skills directory",
        "detail": "Move the folder into your agent's skills directory — e.g. ~/.claude/skills/ (Claude Code), .codex/skills/, .cursor/skills/ or your project's .claude/skills/ folder — then restart or reload the session."
      },
      {
        "title": "Use it",
        "detail": "Describe the task in natural language; the agent loads the skill automatically when the request matches the skill description."
      }
    ]
  },
  "usage": {
    "steps": []
  },
  "metadata": {
    "author": "SkillVault",
    "source": "https://skillvault.top/skills/playwright-pw-review",
    "exported_at": "2026-11-03T07:45:18.403Z"
  }
}

format: aiskill/v1
skill:
  name: pw-review
  slug: playwright-pw-review
  version: 1.0.0
  description: >-
    Review Playwright tests for quality. Use when user says "review tests", "check test quality",
    "audit tests", "improve tests", "test code review", or "playwright best practices check".
  category: Development
  tags:
    - testing
    - code-review
  platforms:
    - chatgpt
    - claude-code
    - cursor
  tested_environment: >-
    Agent Skills convention (SKILL.md) — works with Claude Code, Cursor, ChatGPT/Codex and
    compatible agents
  license: MIT
prompts:
  system: "# Review Playwright Tests\r\n\r\nSystematically review Playwright test files for anti-patterns, missed best practices, and coverage gaps.\r\n\r\n## Input\r\n\r\n`$ARGUMENTS` can be:\r\n- A file path: review that specific test file\r\n- A directory: review all test files in the directory\r\n- Empty: review all tests in the project's `testDir`\r\n\r\n## Steps\r\n\r\n### 1. Gather Context\r\n\r\n- Read `playwright.config.ts` for project settings\r\n- List all `*.spec.ts` / `*.spec.js` files in scope\r\n- If reviewing a single file, also check related page objects and fixtures\r\n\r\n### 2. Check Each File Against Anti-Patterns\r\n\r\nLoad `anti-patterns.md` from this skill directory. Check for all 20 anti-patterns.\r\n\r\n**Critical (must fix):**\r\n1. `waitForTimeout()` usage\r\n2. Non-web-first assertions (`expect(await ...)`)\r\n3. Hardcoded URLs instead of `baseURL`\r\n4. CSS/XPath selectors when role-based exists\r\n5. Missing `await` on Playwright calls\r\n6. Shared mutable state between tests\r\n7. Test execution order dependencies\r\n\r\n**Warning (should fix):**\r\n8. Tests longer than 50 lines (consider splitting)\r\n9. Magic strings without named constants\r\n10. Missing error/edge case tests\r\n11. `page.evaluate()` for things locators can do\r\n12. Nested `test.describe()` more than 2 levels deep\r\n13. Generic test names (\"should work\", \"test 1\")\r\n\r\n**Info (consider):**\r\n14. No page objects for pages with 5+ locators\r\n15. Inline test data instead of factory/fixture\r\n16. Missing accessibility assertions\r\n17. No visual regression tests for UI-heavy pages\r\n18. Console error assertions not checked\r\n19. Network idle waits instead of specific assertions\r\n20. Missing `test.describe()` grouping\r\n\r\n### 3. Score Each File\r\n\r\nRate 1-10 based on:\r\n- **9-10**: Production-ready, follows all golden rules\r\n- **7-8**: Good, minor improvements possible\r\n- **5-6**: Functional but has anti-patterns\r\n- **3-4**: Significant issues, likely flaky\r\n- **1-2**: Needs rewrite\r\n\r\n### 4. Generate Review Report\r\n\r\nFor each file:\r\n```\r\n## <filename> — Score: X/10\r\n\r\n### Critical\r\n- Line 15: `waitForTimeout(2000)` → use `expect(locator).toBeVisible()`\r\n- Line 28: CSS selector `.btn-submit` → `getByRole('button', { name: \"submit\" })`\r\n\r\n### Warning\r\n- Line 42: Test name \"test login\" → \"should redirect to dashboard after login\"\r\n\r\n### Suggestions\r\n- Consider adding error case: what happens with invalid credentials?\r\n```\r\n\r\n### 5. For Project-Wide Review\r\n\r\nIf reviewing an entire test suite:\r\n- Spawn sub-agents per file for parallel review (up to 5 concurrent)\r\n- Or use `/batch` for very large suites\r\n- Aggregate results into a summary table\r\n\r\n### 6. Offer Fixes\r\n\r\nFor each critical issue, provide the corrected code. Ask user: \"Apply these fixes? [Yes/No]\"\r\n\r\nIf yes, apply all fixes using `Edit` tool.\r\n\r\n## Output\r\n\r\n- File-by-file review with scores\r\n- Summary: total files, average score, critical issue count\r\n- Actionable fix list\r\n- Coverage gaps identified (pages/features with no tests)"
  user_template: ""
variables: []
install:
  steps:
    - title: Download & unzip
      detail: >-
        Download the .zip package from SkillVault and unzip it. The playwright-pw-review/ folder
        contains SKILL.md plus any companion scripts, references and assets.
    - title: Copy into your agent skills directory
      detail: >-
        Move the folder into your agent's skills directory — e.g. ~/.claude/skills/ (Claude Code),
        .codex/skills/, .cursor/skills/ or your project's .claude/skills/ folder — then restart or
        reload the session.
    - title: Use it
      detail: >-
        Describe the task in natural language; the agent loads the skill automatically when the
        request matches the skill description.
usage:
  steps: []
metadata:
  author: SkillVault
  source: https://skillvault.top/skills/playwright-pw-review
  exported_at: "2026-11-03T07:45:18.403Z"