fix

# Fix Failing or Flaky Tests

Diagnose and fix a Playwright test that fails or passes intermittently using a systematic taxonomy.

## Input

`$ARGUMENTS` contains:
- A test file path: `e2e/login.spec.ts`
- A test name: ""should redirect after login"`
- A description: `"the checkout test fails in CI but passes locally"`

## Steps

### 1. Reproduce the Failure

Run the test to capture the error:

```bash
npx playwright test <file> --reporter=list
```

If the test passes, it's likely flaky. Run burn-in:

```bash
npx playwright test <file> --repeat-each=10 --reporter=list
```

If it still passes, try with parallel workers:

```bash
npx playwright test --fully-parallel --workers=4 --repeat-each=5
```

### 2. Capture Trace

Run with full tracing:

```bash
npx playwright test <file> --trace=on --retries=0
```

Read the trace output. Use `/debug` to analyze trace files if available.

### 3. Categorize the Failure

Load `flaky-taxonomy.md` from this skill directory.

Every failing test falls into one of four categories:

| Category | Symptom | Diagnosis |
|---|---|---|
| **Timing/Async** | Fails intermittently everywhere | `--repeat-each=20` reproduces locally |
| **Test Isolation** | Fails in suite, passes alone | `--workers=1 --grep "test name"` passes |
| **Environment** | Fails in CI, passes locally | Compare CI vs local screenshots/traces |
| **Infrastructure** | Random, no pattern | Error references browser internals |

### 4. Apply Targeted Fix

**Timing/Async:**
- Replace `waitForTimeout()` with web-first assertions
- Add `await` to missing Playwright calls
- Wait for specific network responses before asserting
- Use `toBeVisible()` before interacting with elements

**Test Isolation:**
- Remove shared mutable state between tests
- Create test data per-test via API or fixtures
- Use unique identifiers (timestamps, random strings) for test data
- Check for database state leaks

**Environment:**
- Match viewport sizes between local and CI
- Account for font rendering differences in screenshots
- Use `docker` locally to match CI environment
- Check for timezone-dependent assertions

**Infrastructure:**
- Increase timeout for slow CI runners
- Add retries in CI config (`retries: 2`)
- Check for browser OOM (reduce parallel workers)
- Ensure browser dependencies are installed

### 5. Verify the Fix

Run the test 10 times to confirm stability:

```bash
npx playwright test <file> --repeat-each=10 --reporter=list
```

All 10 must pass. If any fail, go back to step 3.

### 6. Prevent Recurrence

Suggest:
- Add to CI with `retries: 2` if not already
- Enable `trace: 'on-first-retry'` in config
- Add the fix pattern to project's test conventions doc

## Output

- Root cause category and specific issue
- The fix applied (with diff)
- Verification result (10/10 passes)
- Prevention recommendation

{
  "format": "aiskill/v1",
  "skill": {
    "name": "fix",
    "slug": "playwright-fix",
    "version": "1.0.0",
    "description": "Fix failing or flaky Playwright tests. Use when user says \"fix test\", \"flaky test\", \"test failing\", \"debug test\", \"test broken\", \"test passes sometimes\", or \"intermittent failure\".",
    "category": "Development",
    "tags": [
      "testing"
    ],
    "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": "# Fix Failing or Flaky Tests\r\n\r\nDiagnose and fix a Playwright test that fails or passes intermittently using a systematic taxonomy.\r\n\r\n## Input\r\n\r\n`$ARGUMENTS` contains:\r\n- A test file path: `e2e/login.spec.ts`\r\n- A test name: \"\"should redirect after login\"`\r\n- A description: `\"the checkout test fails in CI but passes locally\"`\r\n\r\n## Steps\r\n\r\n### 1. Reproduce the Failure\r\n\r\nRun the test to capture the error:\r\n\r\n```bash\r\nnpx playwright test <file> --reporter=list\r\n```\r\n\r\nIf the test passes, it's likely flaky. Run burn-in:\r\n\r\n```bash\r\nnpx playwright test <file> --repeat-each=10 --reporter=list\r\n```\r\n\r\nIf it still passes, try with parallel workers:\r\n\r\n```bash\r\nnpx playwright test --fully-parallel --workers=4 --repeat-each=5\r\n```\r\n\r\n### 2. Capture Trace\r\n\r\nRun with full tracing:\r\n\r\n```bash\r\nnpx playwright test <file> --trace=on --retries=0\r\n```\r\n\r\nRead the trace output. Use `/debug` to analyze trace files if available.\r\n\r\n### 3. Categorize the Failure\r\n\r\nLoad `flaky-taxonomy.md` from this skill directory.\r\n\r\nEvery failing test falls into one of four categories:\r\n\r\n| Category | Symptom | Diagnosis |\r\n|---|---|---|\r\n| **Timing/Async** | Fails intermittently everywhere | `--repeat-each=20` reproduces locally |\r\n| **Test Isolation** | Fails in suite, passes alone | `--workers=1 --grep \"test name\"` passes |\r\n| **Environment** | Fails in CI, passes locally | Compare CI vs local screenshots/traces |\r\n| **Infrastructure** | Random, no pattern | Error references browser internals |\r\n\r\n### 4. Apply Targeted Fix\r\n\r\n**Timing/Async:**\r\n- Replace `waitForTimeout()` with web-first assertions\r\n- Add `await` to missing Playwright calls\r\n- Wait for specific network responses before asserting\r\n- Use `toBeVisible()` before interacting with elements\r\n\r\n**Test Isolation:**\r\n- Remove shared mutable state between tests\r\n- Create test data per-test via API or fixtures\r\n- Use unique identifiers (timestamps, random strings) for test data\r\n- Check for database state leaks\r\n\r\n**Environment:**\r\n- Match viewport sizes between local and CI\r\n- Account for font rendering differences in screenshots\r\n- Use `docker` locally to match CI environment\r\n- Check for timezone-dependent assertions\r\n\r\n**Infrastructure:**\r\n- Increase timeout for slow CI runners\r\n- Add retries in CI config (`retries: 2`)\r\n- Check for browser OOM (reduce parallel workers)\r\n- Ensure browser dependencies are installed\r\n\r\n### 5. Verify the Fix\r\n\r\nRun the test 10 times to confirm stability:\r\n\r\n```bash\r\nnpx playwright test <file> --repeat-each=10 --reporter=list\r\n```\r\n\r\nAll 10 must pass. If any fail, go back to step 3.\r\n\r\n### 6. Prevent Recurrence\r\n\r\nSuggest:\r\n- Add to CI with `retries: 2` if not already\r\n- Enable `trace: 'on-first-retry'` in config\r\n- Add the fix pattern to project's test conventions doc\r\n\r\n## Output\r\n\r\n- Root cause category and specific issue\r\n- The fix applied (with diff)\r\n- Verification result (10/10 passes)\r\n- Prevention recommendation",
    "user_template": ""
  },
  "variables": [],
  "install": {
    "steps": [
      {
        "title": "Download & unzip",
        "detail": "Download the .zip package from SkillVault and unzip it. The playwright-fix/ 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-fix",
    "exported_at": "2026-11-03T07:41:49.527Z"
  }
}

format: aiskill/v1
skill:
  name: fix
  slug: playwright-fix
  version: 1.0.0
  description: >-
    Fix failing or flaky Playwright tests. Use when user says "fix test", "flaky test", "test
    failing", "debug test", "test broken", "test passes sometimes", or "intermittent failure".
  category: Development
  tags:
    - testing
  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: "# Fix Failing or Flaky Tests\r\n\r\nDiagnose and fix a Playwright test that fails or passes intermittently using a systematic taxonomy.\r\n\r\n## Input\r\n\r\n`$ARGUMENTS` contains:\r\n- A test file path: `e2e/login.spec.ts`\r\n- A test name: \"\"should redirect after login\"`\r\n- A description: `\"the checkout test fails in CI but passes locally\"`\r\n\r\n## Steps\r\n\r\n### 1. Reproduce the Failure\r\n\r\nRun the test to capture the error:\r\n\r\n```bash\r\nnpx playwright test <file> --reporter=list\r\n```\r\n\r\nIf the test passes, it's likely flaky. Run burn-in:\r\n\r\n```bash\r\nnpx playwright test <file> --repeat-each=10 --reporter=list\r\n```\r\n\r\nIf it still passes, try with parallel workers:\r\n\r\n```bash\r\nnpx playwright test --fully-parallel --workers=4 --repeat-each=5\r\n```\r\n\r\n### 2. Capture Trace\r\n\r\nRun with full tracing:\r\n\r\n```bash\r\nnpx playwright test <file> --trace=on --retries=0\r\n```\r\n\r\nRead the trace output. Use `/debug` to analyze trace files if available.\r\n\r\n### 3. Categorize the Failure\r\n\r\nLoad `flaky-taxonomy.md` from this skill directory.\r\n\r\nEvery failing test falls into one of four categories:\r\n\r\n| Category | Symptom | Diagnosis |\r\n|---|---|---|\r\n| **Timing/Async** | Fails intermittently everywhere | `--repeat-each=20` reproduces locally |\r\n| **Test Isolation** | Fails in suite, passes alone | `--workers=1 --grep \"test name\"` passes |\r\n| **Environment** | Fails in CI, passes locally | Compare CI vs local screenshots/traces |\r\n| **Infrastructure** | Random, no pattern | Error references browser internals |\r\n\r\n### 4. Apply Targeted Fix\r\n\r\n**Timing/Async:**\r\n- Replace `waitForTimeout()` with web-first assertions\r\n- Add `await` to missing Playwright calls\r\n- Wait for specific network responses before asserting\r\n- Use `toBeVisible()` before interacting with elements\r\n\r\n**Test Isolation:**\r\n- Remove shared mutable state between tests\r\n- Create test data per-test via API or fixtures\r\n- Use unique identifiers (timestamps, random strings) for test data\r\n- Check for database state leaks\r\n\r\n**Environment:**\r\n- Match viewport sizes between local and CI\r\n- Account for font rendering differences in screenshots\r\n- Use `docker` locally to match CI environment\r\n- Check for timezone-dependent assertions\r\n\r\n**Infrastructure:**\r\n- Increase timeout for slow CI runners\r\n- Add retries in CI config (`retries: 2`)\r\n- Check for browser OOM (reduce parallel workers)\r\n- Ensure browser dependencies are installed\r\n\r\n### 5. Verify the Fix\r\n\r\nRun the test 10 times to confirm stability:\r\n\r\n```bash\r\nnpx playwright test <file> --repeat-each=10 --reporter=list\r\n```\r\n\r\nAll 10 must pass. If any fail, go back to step 3.\r\n\r\n### 6. Prevent Recurrence\r\n\r\nSuggest:\r\n- Add to CI with `retries: 2` if not already\r\n- Enable `trace: 'on-first-retry'` in config\r\n- Add the fix pattern to project's test conventions doc\r\n\r\n## Output\r\n\r\n- Root cause category and specific issue\r\n- The fix applied (with diff)\r\n- Verification result (10/10 passes)\r\n- Prevention recommendation"
  user_template: ""
variables: []
install:
  steps:
    - title: Download & unzip
      detail: >-
        Download the .zip package from SkillVault and unzip it. The playwright-fix/ 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-fix
  exported_at: "2026-11-03T07:41:49.527Z"