Debugging Playwright Tests Like a Pro

Table of Contents

• Introduction
• 1. Using Playwright's Built-in Debugging Tools
• 2. Enhanced Logging
• 3. Screenshots and Videos
• 4. Debugging with Breakpoints
• 5. Analyzing Network and Console Logs
• 6. Handling Flaky Tests
• 7. Best Practices for Debugging
• Conclusion

Introduction

Debugging is an essential skill for any developer, especially when working with automated tests. Playwright, with its powerful debugging features, makes it easier to identify and fix issues in your tests. In this post, we’ll explore various techniques and tools to debug Playwright tests effectively and ensure your test suite runs smoothly.

1. Using Playwright's Built-in Debugging Tools

Playwright provides several built-in features to help debug tests:

a. --debug Mode

Run your tests in debug mode to pause on errors and interact with the browser manually.

npx playwright test --debug

This mode launches the browser in a non-headless state and opens Playwright Inspector, allowing you to step through your test code.

b. Playwright Inspector
Playwright Inspector is an interactive tool that lets you:

• Step through test execution.
• Highlight elements on the page.
• View the current state of the DOM.

Enable the inspector in your code:

const { test } = require('@playwright/test');

test('example test', async ({ page }) => {
  await page.pause(); // Launches Playwright Inspector
  await page.goto('https://example.com');
  await page.click('#button');
});

c. Slow-Motion Mode

Run tests in slow motion to observe every step.

const { chromium } = require('playwright');

(async () => {
  const browser = await chromium.launch({ headless: false, slowMo: 100 });
  const page = await browser.newPage();
  await page.goto('https://example.com');
  await page.click('#button');
  await browser.close();
})();

2. Enhanced Logging

a. Debug Logs

Enable debug logs to get detailed information about test execution.

DEBUG=pw:api npx playwright test

This logs all Playwright API calls, helping you understand what’s happening during the test.

b. Custom Logging

Add custom logs in your tests to track variable values and execution flow:

console.log('Navigating to example.com');
await page.goto('https://example.com');
console.log('Clicked the button');
await page.click('#button');

3. Screenshots and Videos

Capture screenshots and videos to review what happened during test execution.

a. Capture on Failure

Configure Playwright to take screenshots or record videos on test failure:

import { defineConfig } from '@playwright/test';

export default defineConfig({
  use: {
    screenshot: 'only-on-failure',
    video: 'retain-on-failure',
  },
});

b. Manual Screenshots

Take screenshots at specific points in your test:

await page.screenshot({ path: 'screenshot.png' });

4. Debugging with Breakpoints

a. Use Breakpoints in IDEs

If you’re using an IDE like VS Code, set breakpoints in your test code and run Playwright tests in debug mode:

1. Add a debugger statement in your test:

debugger;

1. Launch the debugger in VS Code. b. Attach to Node.js

Use Node.js debugging tools to attach to the test process:

node --inspect-brk node_modules/.bin/playwright test

5. Analyzing Network and Console Logs

a. Capture Network Traffic

Intercept and analyze network requests to debug API interactions:

page.on('request', request => console.log('Request:', request.url()));
page.on('response', response => console.log('Response:', response.url()));

b. Listen to Console Logs

Capture and print console logs from the browser:

page.on('console', msg => console.log('Console log:', msg.text()));

6. Handling Flaky Tests

Flaky tests can be challenging to debug. Here’s how to tackle them:

a. Retry Failed Tests

Enable retries to catch intermittent failures:

import { defineConfig } from '@playwright/test';

export default defineConfig({
  retries: 2,
});

b. Debug Specific Tests

Run a single test with debugging enabled:

npx playwright test --project=chromium --grep "test name"

c. Use Test Hooks

Add hooks to log additional information during flaky tests:

test.beforeEach(async ({ page }) => {
  console.log('Starting test');
});

test.afterEach(async ({ page }) => {
  await page.screenshot({ path: `test-failure.png` });
});

7. Best Practices for Debugging

1. Reproduce Issues Locally: Run tests locally with the same configuration as your CI environment.
2. Check Dependencies: Ensure all browser versions and Playwright dependencies are up to date.
3. Isolate Tests: Run tests individually to isolate issues.
4. Analyze Reports: Use HTML test reports to trace failures.

Conclusion

Debugging Playwright tests doesn’t have to be a daunting task. With features like Playwright Inspector, detailed logging, and network analysis, you can quickly identify and resolve issues. By adopting these debugging techniques, you’ll not only save time but also improve the reliability of your test suite.

What’s your favorite Playwright debugging tip? Share it in the comments below!