metabuilder/pastebin/docs/DEBUGGING_GUIDE.md

Playwright Test Debugging Guide

Quick Debug Commands

View test report after running

npx playwright show-report

Run tests with browser visible (headed mode)

npx playwright test --headed

Step through tests interactively

npx playwright test --debug

View test execution with timeline

npx playwright test --headed --workers=1

See trace of test execution

npx playwright test --trace on

Run single test by name pattern

npx playwright test -g "button focus state"

Run specific test file

npx playwright test tests/e2e/visual-regression.spec.ts

Run specific test group

npx playwright test -g "Mobile Touch"

Update snapshots (for visual regression)

npx playwright test --update-snapshots

Debugging Failed Tests

1. Screenshot Inspection

Failed tests automatically capture screenshots in:

test-results/[test-name]/test-failed-1.png

2. Video Playback

Videos of failed tests are saved in:

test-results/[test-name]/video.webm

3. Trace Files

Debug traces are at:

test-results/[test-name]/trace.zip

Open with: npx playwright show-trace test-results/[test-name]/trace.zip

4. Console Output

View full output with:

npx playwright test --reporter=list

Common Issues and Solutions

Issue: Tests timeout on CI but work locally

Solution: Check network speed

# Run with slower network simulation
npx playwright test --headed --workers=1

Issue: Intermittent test failures

Solution: Add more wait conditions

await page.waitForLoadState('networkidle')
await page.waitForTimeout(500)

Issue: Visual regression snapshot mismatch

Solution: Update baseline if changes are intentional

npx playwright test --update-snapshots

Issue: Touch/mobile tests fail on desktop

Solution: Tests should skip appropriately. Check:

test.skip(!testInfo.project.name.includes("mobile"), "mobile-only")

Issue: Memory leak detection

Solution: Run with memory profiling

npx playwright test --headed --workers=1

Test Modification Tips

Add debug logging to test

test("my test", async ({ page }) => {
  console.log("Current URL:", page.url());
  console.log("Page title:", await page.title());
  
  // Add pause for inspection
  await page.pause(); // Browser will wait for you to continue
  
  // Your test...
});

Inspect element in debug mode

test("inspect element", async ({ page }) => {
  await page.goto("/");
  await page.pause();
  
  // Browser devtools will open, inspect the element
  const element = page.locator("button").first();
  console.log(await element.boundingBox());
});

Check computed styles

const styles = await element.evaluate(el => {
  const computed = window.getComputedStyle(el);
  return {
    color: computed.color,
    background: computed.backgroundColor,
    fontSize: computed.fontSize,
  };
});
console.log("Computed styles:", styles);

Network interception for debugging

// See all network requests
page.on("request", request => {
  console.log("Request:", request.url(), request.method());
});

page.on("response", response => {
  console.log("Response:", response.url(), response.status());
});

Performance Profiling

Check page metrics

const metrics = await page.metrics();
console.log(`Memory: ${metrics.JSHeapUsedSize / 1048576 | 0} MB`);
console.log(`Layout count: ${metrics.LayoutCount}`);
console.log(`Recalc style count: ${metrics.RecalcStyleCount}`);

Measure navigation timing

const timing = await page.evaluate(() => {
  const nav = performance.getEntriesByType("navigation")[0];
  return {
    loadTime: nav.loadEventEnd - nav.loadEventStart,
    domReady: nav.domContentLoadedEventEnd - nav.loadEventStart,
    transfer: nav.responseEnd - nav.requestStart,
  };
});
console.log("Timing:", timing);

Viewport and Device Testing

Test specific resolution

# Run only on desktop
npx playwright test --project=chromium-desktop

# Run only on mobile
npx playwright test --project=chromium-mobile

Test custom viewport

const context = await browser.newContext({
  viewport: { width: 1920, height: 1080 },
});

Accessibility Debugging

Check ARIA attributes

const role = await element.getAttribute("role");
const label = await element.getAttribute("aria-label");
const expanded = await element.getAttribute("aria-expanded");

console.log({ role, label, expanded });

Verify keyboard navigation

// Tab through elements
for (let i = 0; i < 10; i++) {
  await page.keyboard.press("Tab");
  const focused = await page.evaluate(() => document.activeElement?.tagName);
  console.log(`Tab ${i}:`, focused);
}

Test Report Customization

Generate detailed JSON report

npx playwright test --reporter=json > report.json

Generate HTML report

npx playwright test --reporter=html

Custom report format

npx playwright test --reporter=junit

Debugging Tips by Test Type

Visual Regression Tests

1. Save baseline images locally
2. Compare pixel-by-pixel differences
3. Check for animation timing issues
4. Verify screenshot size matches viewport

Functionality Tests

1. Check for console errors with page.on("console")
2. Monitor network requests for failures
3. Verify state changes after interactions
4. Check DOM mutations after actions

Mobile Tests

1. Verify touch events register properly
2. Check viewport dimensions in browser
3. Test safe area and notch handling
4. Verify input type matches mobile keyboard

Performance Tests

1. Check metrics before and after actions
2. Monitor heap size growth
3. Track layout recalculation count
4. Measure script execution time

Useful Playwright Methods for Debugging

// Get element information
await element.boundingBox();          // Position and size
await element.getAttribute("class");  // Class names
await element.isVisible();            // Visibility
await element.isEnabled();            // Enabled state

// Page inspection
await page.content();                 // Full HTML
await page.textContent();             // All text
await page.title();                   // Page title
await page.url();                     // Current URL

// Console/error monitoring
page.on("console", msg => console.log(msg));
page.on("pageerror", err => console.log(err));

// Performance data
await page.metrics();                 // Performance metrics

Test Failure Checklist

When a test fails:

1. ✅ Check screenshot in test-results/
2. ✅ Watch video of test execution
3. ✅ Review trace file in Playwright inspector
4. ✅ Check console logs and errors
5. ✅ Verify element selectors are correct
6. ✅ Check for race conditions (use proper waits)
7. ✅ Verify viewport/device configuration
8. ✅ Check network conditions
9. ✅ Review recent code changes
10. ✅ Run test in isolation to confirm

Getting Help

Run with verbose logging

DEBUG=pw:api npx playwright test

Check Playwright version

npx playwright --version

Update Playwright

npm install @playwright/test@latest

View full documentation

npx playwright test --help

---

Happy Debugging! 🐛🔍