Mastering Playwright: Run & Debug Tests Like a Pro

Introduction

End-to-end testing is a critical component of modern web development, ensuring your applications work as expected from a user's perspective. Playwright stands out as a powerful, reliable tool for crafting robust E2E tests. But writing tests is just one part of the equation; effectively running, debugging, and analyzing them is where the real efficiency gains happen.

This guide will equip you with the knowledge to master Playwright's command-line interface (CLI) and built-in tools. You'll learn how to execute tests with precision, debug issues swiftly, and interpret results like a seasoned professional, ultimately enhancing your development workflow and the quality of your applications.

Core Concepts

Playwright offers a flexible and powerful way to manage your test execution. Understanding its core concepts for running and debugging tests is key to a smooth development experience.

Running Your Tests

At its heart, Playwright provides a simple command to kick off your tests:

npx playwright test

By default, this command does a few things:

• Parallel Execution: Your tests run in parallel, maximizing efficiency.
• Headless Mode: No browser window opens, and results appear directly in your terminal. This is great for CI/CD environments.
• Multi-Browser: It runs tests across all browsers configured in your playwright.config file (typically Chromium, Firefox, and WebKit).

Running in UI Mode (Highly Recommended)

For an unparalleled developer experience, Playwright's UI Mode is a game-changer. It allows you to visually walk through each step of your test, inspect DOM snapshots, view logs, network requests, and use features like the locator picker and watch mode.

npx playwright test --ui

Running in Headed Mode

Sometimes you want to see the browser in action without the full UI Mode. Use --headed to open a browser window and visually observe Playwright interacting with your application.

npx playwright test --headed`

Targeting Specific Browsers

To run tests on one or more specific browsers, use the --project flag:

npx playwright test --project webkit
npx playwright test --project chromium --project firefox

Running Specific Tests

Playwright provides fine-grained control over which tests to run:

• Single File: npx playwright test landing-page.spec.ts
• Multiple Files/Directories: npx playwright test tests/todo-page/ tests/landing-page/
• By Keyword in Filename: npx playwright test landing login (runs files with 'landing' or 'login' in their name)
• By Test Title: npx playwright test -g "add a todo item" (runs tests whose title matches the given string)
• Last Failed Tests: After a run, re-execute only the tests that previously failed. npx playwright test --last-failed

Debugging Your Tests

Debugging is an inevitable part of test development. Playwright offers several powerful ways to pinpoint issues:

Debugging with UI Mode (Again, Highly Recommended)

As mentioned, UI Mode is fantastic for debugging. You can step through tests, inspect the page, and use the built-in locator picker and playground to refine your selectors.

npx playwright test --ui

Debugging with Playwright Inspector

For stepping through Playwright API calls and seeing detailed debug logs, the Playwright Inspector is invaluable. It opens a separate window that allows you to control test execution step-by-step.

npx playwright test --debug

You can also debug specific files or even a particular test by line number:

npx playwright test example.spec.ts --debug
npx playwright test example.spec.ts:10 --debug

Using console.log and IDE Debuggers

Don't forget the classics! console.log is always useful for quick checks, and Playwright tests run in Node.js, so you can leverage your IDE's built-in debugger (e.g., VS Code) for breakpoints and variable inspection.

Understanding Test Reports

After your tests run, Playwright can generate a comprehensive HTML report. This report is crucial for understanding test failures, filtering results, and exploring the full trace of each test step.

By default, the report opens automatically if tests fail. Otherwise, you can open it manually:

npx playwright show-report

The HTML report allows you to filter by browser, status (passed, failed, skipped), search for specific tests, and dive into detailed traces, complete with video recordings, screenshots, and step-by-step actions.

Practical Code Example

Let's assume you have a simple Playwright test file named `example.spec.ts` in your `tests` directory:

typescript
// tests/example.spec.ts
import { test, expect } from '@playwright/test';

test('has title', async ({ page }) => {
  await page.goto('https://playwright.dev/');
  await expect(page).toHaveTitle(/Playwright/);
});

test('get started link', async ({ page }) => {
  await page.goto('https://playwright.dev/');
  await page.getByRole('link', { name: 'Get started' }).click();
  await expect(page.getByRole('heading', { name: 'Installation' })).toBeVisible();
});

Now, here are some common commands you'll use to run and debug your tests:

bash

1. Run all tests in headless mode (default)

npx playwright test

2. Run all tests in UI Mode (highly recommended for development)

npx playwright test --ui

3. Run all tests in headed mode (browser window opens)

npx playwright test --headed

4. Run tests specifically on the Chromium browser

npx playwright test --project chromium

5. Run a specific test file

npx playwright test tests/example.spec.ts

6. Run tests with a specific title (e.g., 'has title')

npx playwright test -g "has title"

7. Debug a specific test file using Playwright Inspector

npx playwright test tests/example.spec.ts --debug

8. Open the HTML test report manually

npx playwright show-report

Code Breakdown

Let's break down the practical commands we just saw:

• npx playwright test: This is your default command. It executes all tests defined in your project, running them in parallel across all configured browsers (Chromium, Firefox, WebKit) in a headless environment. It's perfect for quick checks or CI/CD pipelines.

• npx playwright test --ui: This command launches Playwright's incredible UI Mode. It opens a browser window alongside a powerful UI where you can step through tests, inspect elements, and get a detailed trace of execution. Essential for an efficient debugging and development workflow.

• npx playwright test --headed: If you need to visually observe your tests running but don't require the full debugging capabilities of UI Mode, this command opens a browser window for each test, allowing you to see Playwright's interactions.

• npx playwright test --project chromium: Use the --project flag to target specific browsers. Here, tests will only run on Chromium, saving time if you're focused on a particular browser's behavior.

• npx playwright test tests/example.spec.ts: To focus on a single test file, simply pass its path as an argument. This is extremely useful when developing or fixing a specific test.

• npx playwright test -g "has title": The -g (grep) flag allows you to run tests based on their title. This is ideal for quickly isolating and running a single test or a small group of tests that share a common title pattern.

• npx playwright test tests/example.spec.ts --debug: Adding the --debug flag to your test command activates the Playwright Inspector. This tool provides a step-by-step debugger for your Playwright API calls, complete with logs, making it easier to understand exactly what your test is doing at each stage.

• npx playwright show-report: After any test run, this command will open the comprehensive HTML report in your browser. This report aggregates all test results, providing filtering, searching, and detailed traces for each test, including videos and screenshots of failures. It's your go-to for post-run analysis.

Best Practices / Common Pitfalls

• Start with UI Mode: When developing new tests or debugging existing ones, always begin with npx playwright test --ui. Its visual feedback, locator picker, and step-through capabilities dramatically speed up development.
• Target Specific Browsers for Speed: During development, use npx playwright test --project chromium (or your primary browser) to get faster feedback cycles instead of running on all configured browsers every time.
• Leverage -g for Focused Debugging: If you're debugging a single failing test, use npx playwright test -g "Your Test Title" to run only that specific test. This avoids unnecessary test runs and keeps your focus tight.
• Re-run Failed Tests Efficiently: After an initial test run, use npx playwright test --last-failed to quickly re-execute only the tests that failed. This is a huge time-saver when iterating on fixes.
• Use Playwright Inspector for Deep Dives: For complex debugging scenarios where you need to understand the exact sequence of Playwright API calls, the --debug flag with the Playwright Inspector is your best friend.
• Integrate with VS Code Extension: For an even more seamless experience, install the Playwright VS Code extension. It allows you to run and debug tests directly from the editor sidebar or next to your test definitions.
• Regularly Review HTML Reports: Don't just look at terminal output. The HTML report provides invaluable context, including videos, screenshots, and detailed step traces, which are crucial for understanding intermittent failures or complex scenarios.
• Avoid Arbitrary waitForTimeout: Instead of await page.waitForTimeout(5000), use Playwright's built-in auto-waiting mechanisms, assertions like expect(locator).toBeVisible(), or specific page.waitFor... methods for more robust and reliable tests.

Conclusion

Mastering the execution and debugging of your Playwright tests is just as important as writing them well. By leveraging the powerful command-line interface, the intuitive UI Mode, the detailed Playwright Inspector, and comprehensive HTML reports, you can significantly enhance your testing workflow.

Embrace these tools and techniques to write more reliable tests, debug issues with greater efficiency, and ultimately deliver higher quality web applications. Happy testing!