playwright-debugging

# Playwright Debugging

## Overview

Browser automation failures fall into predictable categories. This skill provides a systematic approach to diagnose and fix issues quickly.

## When to Use

- Scripts that worked before now fail
- Intermittent test failures (flakiness)
- "Element not found" errors
- Timeout errors
- Unexpected behavior in automation
- Elements not interactable

**When NOT to use:**
- Writing new automation (use playwright-patterns skill)
- API or backend debugging

## Quick Reference

| Problem | First Action |
|---------|-------------|
| Timeout on locator | Run with `--ui` mode, check element state with `.count()`, `.isVisible()` |
| Flaky test (passes sometimes) | Replace `waitForTimeout()` with condition-based waits |
| "Element not visible" | Check computed styles, wait for overlays to disappear |
| Works locally, fails CI | Use `waitForLoadState('networkidle')`, increase timeout |
| Element not clickable | Check if covered by overlay, wait for animations to complete |
| Stale element | Re-query after navigation instead of storing locator |

## Diagnostic Framework

### 1. Reproduce and Isolate

**First step: Can you reproduce it?**

```javascript
// Run single test to isolate issue
npx playwright test path/to/test.spec.js

// Run with headed mode to observe
npx playwright test --headed

// Run with slow motion
npx playwright test --headed --slow-mo=1000
```

**Questions to answer:**
- Does it fail consistently or intermittently?
- Does it fail in all browsers or just one?
- Does it fail in headed and headless mode?
- Did something change recently (site update, code change)?

### 2. Add Visibility

**Use UI Mode for interactive debugging:**

```bash
# Best for local development - provides time-travel debugging
npx playwright test --ui
```

UI Mode gives you:
- Visual timeline of all actions
- Watch mode for re-running on file changes
- Network and console tabs
- Time-travel through test execution

**Use Inspector to step through tests:**

``