playwright-test-debugger

What this skill does

## When to Use This Skill

Use this skill when you need to:

- Fix failing or flaky Playwright tests
- Understand why a test is timing out
- Debug element selector issues
- Analyze test traces and screenshots
- Resolve race conditions
- Investigate unexpected test behavior
- Use Playwright MCP to inspect live browser state

Do NOT use this skill when:

- Creating new tests (use test-generator skill)
- Building Page Objects (use page-object-builder skill)
- Refactoring test code (use test-maintainer skill)

## Prerequisites

Before using this skill:

1. Failing test file or error message
2. Test execution output or logs
3. Optional: Screenshots from test failure
4. Optional: Playwright trace file
5. Optional: Playwright MCP access for live debugging

## Instructions

### Step 1: Gather Failure Information

Ask the user for:

- **Error message** and stack trace
- **Test file** location and test name
- **Expected vs actual** behavior
- **Screenshots** (if available)
- **Trace file** path (if available)
- **Frequency**: Does it fail always or intermittently (flaky)?
- **Environment**: Local, CI, specific browser?

### Step 2: Analyze the Error

Identify the error type:

**Timeout Errors:**

- `Timeout 30000ms exceeded`
- `waiting for selector`
- `waiting for navigation`

**Selector Errors:**

- `Element not found`
- `strict mode violation`
- `No node found`

**Assertion Errors:**

- `Expected ... but received ...`
- `toBe`, `toContain`, `toBeVisible` failures

**Navigation Errors:**

- `Target closed`
- `Navigation failed`
- `ERR_CONNECTION_REFUSED`

**Race Conditions:**

- Intermittent failures
- Works locally but fails in CI
- Different results on different runs

### Step 3: Use Playwright MCP (Optional)

If Playwright MCP is available and needed:

- Use MCP tools to inspect browser state
- Navigate to the problematic page
- Check element visibility and attributes
- Verify data-testid values exist
- Test locator strategies
- Capture screenshots

### Step 4: Identify Root Cause

Common root causes:

**1. Missing or Wrong data-testid:**

- Element has different testid than expected
- testid doesn't exist in HTML
- Multiple elements with same testid

**2. Timing Issues:**

- Element not yet loaded when accessed
- No explicit wait before interaction
- Network requests still pending
- Animations or transitions in progress

**3. Element State:**

- Element exists but not visible
- Element disabled or not clickable
- Element covered by another element
- Element in different frame/iframe

**4. Test Isolation:**

- Tests depend on each other
- Shared state between tests
- Cleanup not performed
- Browser context pollution

**5. Environment Differences:**

- Different viewport sizes
- Different network speeds
- CI vs local differences
- Browser-specific issues

### Step 5: Provide Solution

For each root cause, provide:

1. **Explanation**: What's wrong
2. **Fix**: Code changes needed
3. **Prevention**: How to avoid in future
4. **Verification**: How to confirm it's fixed

### Step 6: Apply the Fix

**For Selector Issues:**

```typescript
// ❌ Before
await page.locator('[data-testid="wrong-id"]').click();

// ✅ After
await page.locator('[data-testid="correct-id"]').click();
```

**For Timeout Issues:**

```typescript
// ❌ Before
await page.locator('[data-testid="submit"]').click();

// ✅ After
await page.locator('[data-testid="submit"]').waitFor({ state: "visible" });
await page.locator('[data-testid="submit"]').click();
```

**For Race Conditions:**

```typescript
// ❌ Before
await page.locator('[data-testid="submit"]').click();
await expect(page.locator('[data-testid="result"]')).toBeVisible();

// ✅ After
await page.locator('[data-testid="submit"]').click();
await page.waitForLoadState("networkidle");
await expect(page.locator('[data-testid="result"]')).toBeVisible();
```

### Step 7: Verify the Fix

Guide the user to:

1. Run the test locally multiple times (3-5 times)
2. Check if error is resolved
3. Verify test passes consistently
4. Run related tests to ensure no regression
5. Consider running in CI if flakiness was CI-specific

## Examples

### Example 1: Timeout Error

**Input:**

```
Test failed with error:
TimeoutError: Timeout 30000ms exceeded.
=========================== logs ===========================
waiting for locator('[data-testid="submit-button"]')
```

**Analysis:**

- Timeout error waiting for element
- Element may not be loading
- Selector may be incorrect

**Solution:**

```typescript
// Check if the data-testid is correct in the HTML
// Add explicit wait with better error message
await page.locator('[data-testid="submit-button"]').waitFor({
  state: "visible",
  timeout: 30000,
});

// If still failing, verify element exists in DOM
const exists = await page.locator('[data-testid="submit-button"]').count();
console.log(`Submit button count: ${exists}`); // Should be 1

// Check if page has loaded
await page.waitForLoadState("domcontentloaded");

// Final solution
await page.waitForLoadState("domcontentloaded");
await page
  .locator('[data-testid="submit-button"]')
  .waitFor({ state: "visible" });
await page.locator('[data-testid="submit-button"]').click();
```

**Prevention:**

- Always add explicit waits before interactions
- Verify data-testid values in HTML
- Use `waitForLoadState` after navigation

### Example 2: Element Not Found

**Input:**

```
Error: Element not found
locator.click: Target closed
  locator('[data-testid="user-menu"]')
```

**Analysis:**

- Element may not exist in current page state
- Possible strict mode violation (multiple elements)
- Element may be in a different frame

**Solution:**

```typescript
// Step 1: Verify element exists
const count = await page.locator('[data-testid="user-menu"]').count();
console.log(`Found ${count} elements`);

// If count = 0: Element doesn't exist, check data-testid in HTML
// If count > 1: Multiple elements, need to be more specific

// Step 2: If multiple elements, use .first() or filter
await page.locator('[data-testid="user-menu"]').first().click();

// Step 3: If in iframe, switch to frame first
const frame = page.frameLocator('[data-testid="app-frame"]');
await frame.locator('[data-testid="user-menu"]').click();

// Step 4: Add proper wait
await page.locator('[data-testid="user-menu"]').waitFor({ state: "attached" });
await page.locator('[data-testid="user-menu"]').click();
```

**Prevention:**

- Ensure data-testid values are unique on the page
- Check for elements in frames/iframes
- Add waits before interaction

### Example 3: Flaky Test (Passes Sometimes)

**Input:**

```
Test fails intermittently:
- Passes 70% of the time locally
- Fails 90% of the time in CI
Error: expect(received).toContainText(expected)
Expected substring: "Success"
Received string: ""
```

**Analysis:**

- Classic race condition
- Element loads but content not yet populated
- Likely caused by async data fetching
- CI is slower so more likely to fail

**Solution:**

```typescript
// ❌ Before: No wait for content
await page.locator('[data-testid="submit"]').click();
await expect(page.locator('[data-testid="message"]')).toContainText("Success");

// ✅ After: Wait for specific condition
await page.locator('[data-testid="submit"]').click();

// Option 1: Wait for network to settle
await page.waitForLoadState("networkidle");
await expect(page.locator('[data-testid="message"]')).toContainText("Success");

// Option 2: Wait for specific API call
await Promise.all([
  page.waitForResponse("**/api/submit"),
  page.locator('[data-testid="submit"]').click(),
]);
await expect(page.locator('[data-testid="message"]')).toContainText("Success");

// Option 3: Use Playwright's auto-waiting in assertion
await page.locator('[data-testid="submit"]').click();
await expect(page.locator('[data-testid="message"]')).toContainText("Success", {
  timeout: 10000, // Explicit timeout for slow operations
});
```

**Prevention:**

- Wait for network requests to complete
- Use explicit timeouts for slow operations
- Run tests