How to run Playwright tests in headed mode

Visible browser runs help when a Playwright test passes or fails too quickly to understand from terminal output alone. Headed mode keeps the normal Playwright Test runner in control while opening browser windows so animation, focus, navigation, and overlay behavior can be watched on the desktop.

The --headed flag changes browser launch mode from the default headless run. Pairing it with --workers=1 keeps one browser window active at a time, and a file, line, title, or project filter keeps the run tied to the behavior being inspected.

Headed mode needs a graphical session, so it belongs on a developer workstation, a remote desktop, or a CI job with a display server. Use --debug when the browser must pause in Playwright Inspector, and use traces when the evidence needs to be shared after the run.

1. Open a terminal at the Playwright project root.

   $ cd ~/projects/playwright-demo

2. List the test target before opening headed browsers.

   $ npx playwright test tests/home.spec.ts --project=chromium --list
   Listing tests:
     [chromium] › home.spec.ts:3:5 › home page shows ready state
   Total: 1 test in 1 file

   Omit the file path and --project option to run every configured project in headed mode, or use a line number, title grep, or project filter for a smaller visual run.
   Related: How to run specific Playwright tests

3. Run the selected target in headed mode with one worker.

   $ npx playwright test tests/home.spec.ts --project=chromium --headed --workers=1
   Running 1 test using 1 worker
   
     ✓  1 [chromium] › tests/home.spec.ts:3:5 › home page shows ready state (377ms)
   
     1 passed (1.3s)

   The browser window stays visible while the test is running. A large suite can open many windows without --workers=1.

4. Rerun the same target without headed mode after the visual check is finished.

   $ npx playwright test tests/home.spec.ts --project=chromium --workers=1
   Running 1 test using 1 worker
   
     ✓  1 [chromium] › tests/home.spec.ts:3:5 › home page shows ready state (114ms)
   
     1 passed (665ms)

   A passing headless rerun confirms the test still works without the local browser window.
   Related: How to run Playwright tests