playwright-debugging_skill

Overview

This skill provides a systematic Playwright debugging workflow for diagnosing and fixing browser automation failures quickly. It focuses on reproducible steps, visibility tools (UI, debugger, traces), selector and element-state checks, and race-condition fixes. Use it when tests are flaky, selectors stop working, or timeouts occur to get actionable next steps and concrete checks.

How this skill works

The skill walks you through reproduce-and-isolate steps, adds visibility using Playwright UI/Inspector/trace/screenshot tools, and inspects element state and selectors with small code snippets. It highlights common failure categories (not found, not visible/clickable, timing/race conditions, stale references, form issues) and gives targeted fixes like condition-based waits, re-querying locators, and trace analysis. Practical commands and tiny code patterns are provided so you can apply fixes immediately.

When to use it

• A script that used to work now fails after a site or test change
• Intermittent (flaky) tests that pass sometimes and fail other times
• "Element not found", "not visible", or timeout errors during actions
• Tests that behave differently in CI than locally
• When selectors seem brittle or elements are intermittently covered/disabled

Best practices

• Reproduce the failure in headed mode and isolate a single failing test before debugging
• Prefer condition-based waits (expect().toBeVisible(), waitForResponse) over fixed timeouts
• Use Playwright UI, --debug, and trace viewer to get time-travel logs and screenshots
• Re-query locators after navigation; never hold stale element handles across page changes
• Use role-based or data-testid selectors to reduce brittleness and improve stability

Example use cases

• Replace waitForTimeout calls with expect(locator).toBeVisible() to fix flaky timing issues
• Run npx playwright test --ui to visually step through a failing workflow and edit selectors live
• Record a trace for a failing CI run and analyze network/DOM snapshots in the trace viewer
• Diagnose "element not clickable" by checking computed styles, z-index, overlays, and animations
• Fix a form submission failure by inspecting form.action, triggering blur/input events, or calling form.submit()