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?

// 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:

# 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:

# Step through test execution with live browser
npx playwright test --debug

Inspector allows:

• Stepping through actions one at a time
• Picking locators directly from the browser
• Editing selectors live and seeing results
• Viewing actionability logs

Take screenshots at failure point:

// Before failing action
await page.screenshot({ path: 'before-action.png', fullPage: true });

// Try action
try {
  await page.click('.button');
} catch (error) {
  await page.screenshot({ path: 'after-error.png', fullPage: true });
  throw error;
}

Enable verbose logging:

# API-level debugging
DEBUG=pw:api npx playwright test

# Browser DevTools with playwright object
PWDEBUG=console npx playwright test

With PWDEBUG=console, you get DevTools access to:

// In browser console
playwright.$('.selector')      // Query with Playwright engine
playwright.$$('selector')      // Get all matches
playwright.inspect('selector') // Highlight in Elements panel
playwright.locator('selector') // Create locator

Use trace viewer:

// Record trace
await context.tracing.start({ screenshots: true, snapshots: true });
// ... your test code
await context.tracing.stop({ path: 'trace.zip' });

// View trace
npx playwright show-trace trace.zip

Organize traces with test steps:

// Group actions in trace viewer
await test.step('Login', async () => {
  await page.fill('input[name="username"]', 'user');
  await page.click('button[type="submit"]');
});

await test.step('Navigate to dashboard', async () => {
  await page.click('a[href="/dashboard"]');
});

Add descriptions to locators for clarity:

// Descriptions appear in trace viewer and reports
const submitButton = page.locator('#submit').describe('Submit button');
await submitButton.click();

VS Code debugging:

Install the Playwright VS Code extension for:

• Live debugging with breakpoints in VS Code
• Locator highlighting in browser while editing
• "Show Browser" option for real-time feedback
• Right-click "Debug Test" on any test

This integrates debugging directly into your editor workflow.

3. Inspect Element State

Check if element exists:

const element = page.locator('.button');

// Does it exist in DOM?
const count = await element.count();
console.log(`Found ${count} elements`);

// Is it visible?
const isVisible = await element.isVisible();
console.log(`Visible: ${isVisible}`);

// Is it enabled?
const isEnabled = await element.isEnabled();
console.log(`Enabled: ${isEnabled}`);

// Get all attributes
const attrs = await element.evaluate(el => ({
  classes: el.className,
  id: el.id,
  display: window.getComputedStyle(el).display,
  visibility: window.getComputedStyle(el).visibility,
  opacity: window.getComputedStyle(el).opacity
}));
console.log(attrs);

4. Verify Selector

Test selector in browser console:

// Use page.evaluate to test selector
const found = await page.evaluate(() => {
  const el = document.querySelector('.button');
  return el ? {
    text: el.textContent,
    visible: el.offsetParent !== null,
    enabled: !el.disabled
  } : null;
});
console.log('Selector test:', found);

Check for multiple matches:

// Are there multiple elements?
const all = await page.locator('.button').all();
console.log(`Found ${all.length} matching elements`);

// Get text of all matches
const texts = await page.locator('.button').allTextContents();
console.log('All matching texts:', texts);

Common Issues and Fixes

Issue: Element Not Found

Causes:

• Selector is wrong
• Element hasn't loaded yet
• Element is in iframe
• Element is dynamically created

Debug steps:

// 1. Check if selector exists at all
const exists = await page.locator('.button').count() > 0;
console.log('Element exists:', exists);

// 2. Wait for element explicitly (modern approach)
await page.locator('.button').waitFor({ timeout: 10000 });
// Or let auto-waiting handle it:
await page.locator('.button').click();

// 3. Check if in iframe
const frame = page.frameLocator('iframe');
await frame.locator('.button').click();

// 4. Dump all matching elements
const all = await page.evaluate(() => {
  return Array.from(document.querySelectorAll('button')).map(el => ({
    text: el.textContent,
    classes: el.className,
    id: el.id
  }));
});
console.log('All buttons on page:', all);

Issue: Element Not Visible/Clickable

Causes:

• Element is hidden (CSS: display:none, visibility:hidden)
• Element is covered by another element
• Element is outside viewport
• Element hasn't finished animating

Debug steps:

// 1. Check computed styles
const styles = await page.locator('.button').evaluate(el => ({
  display: window.getComputedStyle(el).display,
  visibility: window.getComputedStyle(el).visibility,
  opacity: window.getComputedStyle(el).opacity,
  zIndex: window.getComputedStyle(el).zIndex
}));
console.log('Element styles:', styles);

// 2. Scroll into view
await page.locator('.button').scrollIntoViewIfNeeded();

// 3. Wait for element to be stable (not animating)
await expect(page.locator('.button')).toBeVisible();
await page.waitForTimeout(100); // Brief wait for animation

// 4. Force click if needed (last resort)
await page.locator('.button').click({ force: true });

Issue: Timing/Race Conditions

Causes:

• Network requests not complete
• JavaScript still executing
• Animations in progress
• Dynamic content loading

Debug steps:

// 1. Wait for network to be idle
await page.goto('https://example.com');
await page.waitForLoadState('networkidle');

// 2. Wait for specific network request
await page.waitForResponse(resp =>
  resp.url().includes('/api/data') && resp.status() === 200
);

// 3. Wait for JavaScript condition
await page.waitForFunction(() =>
  window.dataLoaded === true
);

// 4. Wait for element cou