How do I run Playwright tests in headed mode?

Add the --headed flag: npx playwright test --headed. To make it the default instead, set headless: false under use in playwright.config.js.

This answer is one piece of Chapter 16: The Test Runner.

Test Structure & Lifecycle
playwright.config.ts Complete Reference
Test Organization at Scale
Tags, Grep, and the Suite You Actually Run
What Runs Where, and What Serial Costs
Practice and interview questions: Assertions & Test Runner

Playwright runs headless by default: the browser works normally but no window is shown. That is faster and is what you want on a CI machine, which has no screen. While you are writing or fixing a test, though, it helps to watch the browser click through the steps.

The --headed flag shows the browser window for that run only. Nothing in the config changes, so the next plain npx playwright test is headless again. If you want every local run to be headed, set headless: false in the use block, ideally only when process.env.CI is not set so the pipeline stays headless.

Headed mode only shows the window. The test still runs at full speed, so a short test is over in about a second. To stop and step through it, use --debug instead, which opens the Playwright Inspector.

The example is an ordinary test run with --headed. It passed in the same way it does headless; the only difference is that a Chromium window opened for the length of the run.

headed.spec.js(https://practice.learnplayforge.com)

$ npx playwright test headed.spec.js --headed

// headed.spec.js
import { test, expect } from '@playwright/test';

test('the cart starts empty', async ({ page }) => {
  await page.goto('/catalog.html?mock=static&seed=42&autologin=1');
  await expect(page.getByTestId('cart-empty')).toBeVisible();
  await expect(page.getByTestId('cart-total')).toHaveText('₹0');
});

Output

Running 1 test using 1 worker

  ok 1 [chromium] › headed.spec.js:3:1 › the cart starts empty (981ms)

  1 passed (4.7s)

Test yourself

You run npx playwright test with no flags and no headless setting in the config. What do you see?

AI can write the test now. The job is knowing whether it checks anything. That's what the course teaches, one chapter at a time.

163 lessons · 226 drills · start free

How do I run Playwright tests in headed mode?

Related questions