DEV Community: Pratham Rathod

Mastering Playwright: Run & Debug Tests Like a Pro

Pratham Rathod — Wed, 08 Jul 2026 18:11:52 +0000

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!

Playwright Codegen: Generate Tests & Locators Fast

Pratham Rathod — Thu, 02 Jul 2026 16:53:48 +0000

Playwright Codegen: Generate Tests & Locators Fast

Generate Playwright tests and locators with Codegen. Record user actions, add assertions like visibility and text, and fine-tune locators for robust, reliable end-to-end tests.

Playwright Codegen provides an efficient way to generate tests and locators automatically, accelerating the test creation process. It opens a browser for interaction and an Inspector for recording and managing generated code.

Getting Started with Codegen

Running Codegen

To start the test generator, use the codegen command followed by the URL of the website you wish to test. The URL is optional and can be entered directly in the browser window if omitted.

npx playwright codegen https://demo.playwright.dev/todomvc

This command launches:

A browser window for interactions.
The Playwright Inspector, which displays the generated code.

Recording a Test

Codegen automatically generates Playwright code as you interact with the browser. It analyzes the page to recommend robust locators (prioritizing role, text, and test id), refining them to uniquely identify elements and reduce flakiness.

Recording Actions

Perform actions in the browser window, such as:

Clicking: Clicking on buttons, links, etc.
Filling: Typing text into input fields.
Navigating: Visiting different pages.

Adding Assertions

You can add assertions directly during recording:

Click the "Assert" icon in the Playwright Inspector toolbar.
Click a page element in the browser.
Choose the assertion type from the options:

*   **Assert Visibility**: `expect(locator).toBeVisible()`

*   **Assert Text**: `expect(locator).toHaveText()`

*   **Assert Value**: `expect(locator).toHaveValue()`

Managing Recording

Stop Recording: Press the "Record" button in the Inspector to pause code generation.
Copy Code: Use the "Copy" button to transfer the generated code to your editor.
Clear Code: Use the "Clear" button to reset the Inspector and start a new recording.

Once finished, close the Playwright Inspector window or terminate the command in your terminal.

Example Generated Test

Below is an example of a test generated by interacting with the todomvc application (e.g., adding an item and marking it complete).

import { test, expect } from '@playwright/test';

test('should add a todo item and mark it complete', async ({ page }) => {
  await page.goto('https://demo.playwright.dev/todomvc');

  // Add a new todo item
  await page.getByPlaceholder('What needs to be done?').fill('buy some milk');
  await page.getByPlaceholder('What needs to be done?').press('Enter');

  // Assert the new item is visible
  await expect(page.getByLabel('buy some milk')).toBeVisible();

  // Mark the item as complete
  await page.getByLabel('Toggle Todo').check();

  // Assert the item is marked complete (e.g., has a line-through style)
  await expect(page.getByLabel('buy some milk')).toHaveClass('completed');
});

Generating Locators

Codegen can also be used specifically to generate robust locators for existing tests or new elements.

Stop Recording: If recording, press the "Record" button to stop. The "Pick Locator" button will appear.
Activate Locator Picker: Click the "Pick Locator" button.
Hover and Select: Hover over elements in the browser window. Playwright highlights the element and displays its recommended locator.
Copy Locator: Click on the desired element. Its locator code will appear in the "Locator Playground" next to the "Pick Locator" button.
Refine Locator: You can edit the locator in the "Locator Playground" to fine-tune it. As you type, Playwright highlights matching elements in the browser.
Copy to Code: Use the "Copy" button to copy the refined locator for use in your tests.

Example Generated Locator

// Example generated locator for an 'Add' button
page.getByRole('button', { name: 'Add' })

// Example generated locator for an input field by placeholder
page.getByPlaceholder('Enter your email')

Emulation

Codegen supports generating tests under various emulation conditions without additional setup. You can emulate:

Specific viewports and devices.
Color schemes.
Geolocation.
Language.
Timezone.

It can also preserve authenticated states, allowing you to record tests from a logged-in session. For more details on these advanced features, refer to the comprehensive Playwright Test Generator documentation.

Playwright E2E Tests: Actions, Assertions, Hooks

Pratham Rathod — Sun, 28 Jun 2026 15:02:45 +0000

Playwright E2E Tests: Actions, Assertions, Hooks

Learn Playwright E2E testing. Write first test, actions, async assertions, test isolation, leverage hooks for reliable web automation!

This guide provides a practical overview of writing tests with Playwright, focusing on core concepts, actions, assertions, and test organization.

Introduction

Playwright tests are designed for simplicity and reliability. They perform actions on web pages and assert expected states. Playwright automatically handles waiting for elements to become actionable and for assertions to eventually pass, eliminating the need for manual waits and reducing test flakiness.

Getting Started: Your First Test

Playwright tests are typically written in TypeScript or JavaScript. A basic test involves navigating to a URL and performing assertions.

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

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

  // Expect a title "to contain" a substring.
  await expect(page).toHaveTitle(/Playwright/);
});

test('get started link', async ({ page }) => {
  await page.goto('https://playwright.dev/');

  // Click the "Get started" link using its role and name.
  await page.getByRole('link', { name: 'Get started' }).click();

  // Expects the page to have a heading with the name "Installation".
  await expect(page.getByRole('heading', { name: 'Installation' })).toBeVisible();
});

Note: When using JavaScript in VS Code, add // @ts-check at the start of each test file to enable automatic type checking.

Performing Actions

Most tests begin with navigation and then interact with page elements.

Navigation

Use page.goto() to navigate to a URL. Playwright waits for the page to reach the load state before proceeding.

await page.goto('https://playwright.dev/');

Interactions

Interacting with elements starts by locating them using Playwright's Locators API. Locators provide a robust way to find elements on the page. Playwright automatically waits for elements to become actionable (e.g., visible, enabled) before performing an action, so you don't need to add explicit waits.

// Create a locator for the "Get started" link.
const getStartedLink = page.getByRole('link', { name: 'Get started' });

// Click the located element.
await getStartedLink.click();

Often, this can be condensed into a single line:

await page.getByRole('link', { name: 'Get started' }).click();

Basic Actions

Here are some common Playwright actions:

Action	Description
`locator.check()`	Check a checkbox
`locator.click()`	Click an element
`locator.uncheck()`	Uncheck a checkbox
`locator.hover()`	Hover mouse over an element
`locator.fill()`	Fill a form field with text
`locator.focus()`	Focus an element
`locator.press()`	Press a single key
`locator.setInputFiles()`	Pick files for upload
`locator.selectOption()`	Select an option in a dropdown

Using Assertions

Playwright includes test assertions via the expect function. Call expect(value) and use a matcher to define your expectation.

Playwright offers async matchers that wait for a condition to be met, making tests non-flaky.

// This assertion waits until the page title contains "Playwright".
await expect(page).toHaveTitle(/Playwright/);

Popular Async Assertions

Assertion	Description
`expect(locator).toBeChecked()`	Checkbox is checked
`expect(locator).toBeEnabled()`	Control is enabled
`expect(locator).toBeVisible()`	Element is visible
`expect(locator).toContainText()`	Element contains specific text
`expect(locator).toHaveAttribute()`	Element has a specific attribute
`expect(locator).toHaveCount()`	List of elements has a given length
`expect(locator).toHaveText()`	Element matches text (exact or regex)
`expect(locator).toHaveValue()`	Input element has a specific value
`expect(page).toHaveTitle()`	Page has a specific title (exact or regex)
`expect(page).toHaveURL()`	Page has a specific URL (exact or regex)

Playwright also includes generic matchers like toEqual, toContain, and toBeTruthy for immediate synchronous checks. These do not require await.

// Synchronous assertion.
expect(success).toBeTruthy();

Test Isolation

Playwright Test ensures strong isolation between tests. Each test receives a fresh environment, thanks to the page fixture which belongs to an isolated BrowserContext. A BrowserContext is equivalent to a brand new browser profile, preventing test interference.

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

test('example test', async ({ page }) => {
  // "page" here is isolated for this specific test.
});

test('another test', async ({ page }) => {
  // "page" in this second test is completely isolated from the first test.
});

Using Test Hooks

Playwright provides various test hooks to organize and manage test execution.

test.describe(name, callback): Groups related tests.
test.beforeEach(callback): Runs before each test in the current describe block.
test.afterEach(callback): Runs after each test in the current describe block.
test.beforeAll(callback): Runs once before all tests in the current describe block.
test.afterAll(callback): Runs once after all tests in the current describe block.

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

test.describe('navigation', () => {
  // Navigate to the starting URL before each test in this group.
  test.beforeEach(async ({ page }) => {
    await page.goto('https://playwright.dev/');
  });

  test('main navigation', async ({ page }) => {
    // This test starts at 'https://playwright.dev/' due to beforeEach.
    await expect(page).toHaveURL('https://playwright.dev/');
  });

  test('navigate to docs', async ({ page }) => {
    // This test also starts at 'https://playwright.dev/'.
    await page.getByRole('link', { name: 'Docs' }).click();
    await expect(page).toHaveURL(/.*docs/);
  });
});

How to Install Playwright: The Ultimate End-to-End Testing Guide

Pratham Rathod — Sun, 28 Jun 2026 11:36:20 +0000

How to Install Playwright: The Ultimate End-to-End Testing Guide

Learn how to install Playwright and set up your first end-to-end testing environment for modern web applications. This comprehensive guide walks you through the installation process using npm, yarn, or pnpm, ensuring a seamless setup for TypeScript or JavaScript projects. Discover how to configure browser binaries for Chromium, WebKit, and Firefox, and leverage the powerful VS Code extension for efficient test development. We cover everything from initializing your project with the playwright.config.ts file to executing your first example test. Explore advanced features like the HTML Test Reporter for detailed debugging, UI Mode for live time-travel debugging, and GitHub Actions integration for continuous integration pipelines. Whether you are working on Windows, Linux, or macOS, this tutorial provides the essential steps to get your automation suite running quickly. We also detail system requirements, including Node.js compatibility and OS support, to ensure your environment is fully optimized for testing success. By following these steps, you will master parallel execution, headless browser testing, and native mobile emulation. Start your journey into reliable, high-performance web testing with Playwright today and streamline your QA workflow with the industry’s most robust automation framework. Elevate your development standards now with our expert installation guide.

Introduction

Playwright Test is an end-to-end testing framework for modern web applications. It provides a unified solution for testing across Chromium, WebKit, and Firefox with support for parallelization, native mobile emulation, and CI/CD integration.

System Requirements

Node.js: 22.x, 24.x, or 26.x.
OS:
- Windows 11+ or Windows Server 2019+ (or WSL).
- macOS 14 (Sonoma) or later.
- Debian 12/13, Ubuntu 22.04/24.04/26.04 (x86-64 or arm64).

Installation

Run the following command to initialize a new project or add Playwright to an existing project:

npm init playwright@latest

Configuration Prompts

During installation, you will be prompted to configure the following:

Language: TypeScript (default) or JavaScript.
Test Folder: Name of the directory (default: tests or e2e).
GitHub Actions: Recommended for CI integration.
Browser Install: Automatically download required binaries (recommended).

Project Structure

Playwright creates the following scaffold:

File/Folder	Purpose
`playwright.config.ts`	Global configuration (browsers, timeouts, reporters).
`tests/`	Directory containing your test specifications.
`package.json`	Project dependencies and scripts.

Running Tests

Execute tests using the Playwright CLI. By default, tests run in parallel in headless mode across all configured browsers.

Execution Commands

Task	Command
Run all tests	`npx playwright test`
Run specific file	`npx playwright test tests/example.spec.ts`
Run in headed mode	`npx playwright test --headed`
Run specific browser	`npx playwright test --project=chromium`
Open UI Mode	`npx playwright test --ui`

HTML Reports

After execution, generate and view the detailed HTML report:

npx playwright show-report

Maintenance

Updating Playwright

To update the framework and ensure browser binaries are synchronized:

# Update dependency
npm install -D @playwright/test@latest

# Update browser binaries
npx playwright install --with-deps

Version Check

Verify your current installation:

npx playwright --version

Key Features

UI Mode: Use npx playwright test --ui for watch mode, live step-by-step debugging, and time-travel inspection.
Configuration: Edit playwright.config.ts to adjust retries, global timeouts, and environment-specific settings.
Cross-Browser: Supports Chromium, Firefox, and WebKit out of the box.

DEV Community: Pratham Rathod

Mastering Playwright: Run & Debug Tests Like a Pro

Mastering Playwright: Run & Debug Tests Like a Pro

Introduction

Core Concepts

Running Your Tests

Running in UI Mode (Highly Recommended)

Running in Headed Mode

Targeting Specific Browsers

Running Specific Tests

Debugging Your Tests

Debugging with UI Mode (Again, Highly Recommended)

Debugging with Playwright Inspector

Using console.log and IDE Debuggers

Understanding Test Reports

Practical Code Example

1. Run all tests in headless mode (default)

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

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

4. Run tests specifically on the Chromium browser

5. Run a specific test file

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

7. Debug a specific test file using Playwright Inspector

8. Open the HTML test report manually

Code Breakdown

Best Practices / Common Pitfalls

Conclusion

Playwright Codegen: Generate Tests & Locators Fast

Playwright Codegen: Generate Tests & Locators Fast

Getting Started with Codegen

Running Codegen

Recording a Test

Recording Actions

Adding Assertions

Managing Recording

Example Generated Test

Generating Locators

Example Generated Locator

Emulation

Playwright E2E Tests: Actions, Assertions, Hooks

Playwright E2E Tests: Actions, Assertions, Hooks

Introduction

Getting Started: Your First Test

Performing Actions

Navigation

Interactions

Basic Actions

Using Assertions

Popular Async Assertions

Test Isolation

Using Test Hooks

How to Install Playwright: The Ultimate End-to-End Testing Guide

How to Install Playwright: The Ultimate End-to-End Testing Guide

Introduction

System Requirements

Installation

Configuration Prompts

Project Structure

Running Tests

Execution Commands

HTML Reports

Maintenance

Updating Playwright

Version Check

Key Features

Using `console.log` and IDE Debuggers