Recommended Free Tools
Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
Run a JavaScript or TypeScript Playwright Test suite with npx playwright test --headed to watch the browser while tests execute. For a permanent setting, add use: { headless: false } to playwright.config.ts. Python users run the pytest plugin with pytest --headed. This guide explains the commands, filters, debugging alternatives, Linux CI display requirements, security considerations and practical fixes.
Run a Playwright Test visibly from the command line
From the directory containing your Playwright project, run:
npx playwright test --headedPlaywright Test is headless by default. The --headed flag shows the browser window so you can visually see how Playwright interacts with the website, while the normal test runner still controls navigation, assertions and reporting. The official running-tests guide documents this flag at playwright.dev/docs/running-tests.
Use the equivalent command for your package manager:
#1 Best Overall
yarn playwright test --headedpnpm exec playwright test --headed
The command does not change your test code or permanently alter the project. It applies to that invocation only.
Run one file
npx playwright test tests/example.spec.ts --headedPut the file path before or after the flag; Playwright accepts both forms. Use a path relative to the project root (or the path accepted by your shell).
Run a single test by title
npx playwright test --headed -g "checkout shows confirmation"The -g option filters by test title. Quotes preserve spaces and punctuation in the title.
Quick wins for a faster PC:
Scan for outdated or missing drivers - takes under a minuteDriver Scan →Clear out junk files and repair common Windows errorsFree Scan →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Run one configured browser project
npx playwright test --headed --project=chromiumReplace chromium with a project name declared in your playwright.config. This is useful when a configuration runs Chromium, Firefox and WebKit but you only need to observe one browser.
Make headed mode the default
To show a browser on every Playwright Test run, set headless: false in the use section of your configuration:
import { defineConfig } from '@playwright/test';
export default defineConfig({
use: {
headless: false,
},
});Playwright’s configuration reference documents headless as the setting that controls whether the browser is shown; its default is true. A command-line --headed run is often safer for shared projects because it leaves the team’s normal (headless) behavior unchanged.
Keep CI headless while developing locally
You can leave headless: true (or omit the setting) in source control and use --headed only when investigating locally. Alternatively, use separate projects or environment-based configuration so a visible browser is selected only when a local variable is present. Do not assume a headed setting will work on a server without a display; Linux CI needs an X server such as Xvfb.
Choose between headed, debug and UI Mode
These options all make browser activity visible, but they solve different problems.
| Workflow | Browser window | Controls and selection | Best use | Environment and security |
|---|---|---|---|---|
--headed |
Yes | Normal runner; no extra step controls | Watch a regular run and observe timing, navigation or UI state | Needs a usable display when running on Linux |
--debug |
Yes | Playwright Inspector, step controls and locator exploration | Pause and inspect one test at a time | Playwright sets the default timeout to zero in debug mode, so a paused test does not time out while you inspect it |
--ui |
Interactive UI Mode | Test selection, watch mode, trace and per-action information | Explore a suite repeatedly while editing tests | When used with --ui-host=0.0.0.0, traces, passwords and other secrets may be visible to other machines on the network |
Use Inspector for step-through debugging
npx playwright test --debugDebug mode launches browsers headed and opens the Playwright Inspector. It is more intrusive than --headed: tests run one by one and the Inspector provides pause, resume and locator tools. Narrow it with a file, title or project filter when the full suite is too large.
Use UI Mode for interactive exploration
npx playwright test --uiUI Mode lets you choose tests, watch changes and inspect traces and action details. In a container or remote host, Playwright documents options such as:
npx playwright test --ui --ui-host=0.0.0.0 --ui-port=9323Binding to all interfaces is convenient for remote access but is not a harmless default. Protect the port with network controls and authentication supplied by your environment; otherwise anyone who can reach it may see traces containing credentials, tokens or private page data.
Python users: the pytest command is different
The Playwright Python pytest plugin has its own command-line options. Run:
pytest --headedYou can select a browser at the same time:
pytest --browser webkit --headedThe documented --headed and --browser options configure the plugin’s default browser, context and page fixtures. They do not automatically change browser, context or page objects that your test creates directly through Playwright’s API. If your test calls sync_playwright() or async_playwright() and launches its own browser, pass headless=False in that launch call instead:
from playwright.sync_api import sync_playwright
def test_visible_browser():
with sync_playwright() as p:
browser = p.chromium.launch(headless=False)
page = browser.new_page()
page.goto("https://example.com")
assert page.title() == "Example Domain"
browser.close()Headed execution on Linux CI
A headed browser needs a display. Playwright’s CI guidance says Linux agents require Xvfb for headed execution and shows:
xvfb-run npx playwright testXvfb supplies a virtual X display; it does not make a physical monitor appear. Confirm that your runner image includes Xvfb and the browser dependencies before relying on the command. If Xvfb is missing, install it using the distribution-supported package mechanism or choose a CI image that includes Playwright’s documented dependencies.
The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Typical display symptoms
Missing X server or $DISPLAY: start the run underxvfb-runor provide a correctly configured display.- Browser launches and immediately closes: inspect the CI log for missing shared libraries, sandbox restrictions or an invalid display; installing only Xvfb may not install all browser dependencies.
- Works locally but not in CI: compare the operating system, installed browser version, environment variables and display setup. Headed mode adds an environmental dependency that headless mode does not.
Practical headed-mode workflow
- Install the project dependencies and browsers. Use the installation method already used by the project, then ensure the Playwright-managed browsers are installed.
- Start with a narrow run. Use a single file, title filter or
--projectso the visible session is short and easy to inspect. - Run normally headed. Execute
npx playwright test --headedand watch the browser for unexpected redirects, overlays, loading states and focus changes. - Switch to debug mode when timing matters. Re-run with
--debugto pause between actions and inspect locators in the Inspector. - Use UI Mode for repeated edits. Run
--uiwhen you need test selection, file watching and trace exploration rather than one uninterrupted pass. - Return to headless before committing. A headed run is useful evidence, but verify the final suite in the same headless environment used by automation.
Troubleshooting common failures
The browser window never appears
Check that you actually invoked Playwright Test with --headed (or configured headless: false) and that the selected project does not override the setting. On Linux, check DISPLAY and use Xvfb in CI.
The command says the option is unknown
Make sure you are invoking the Playwright Test runner, not a different test command. JavaScript and TypeScript projects use npx playwright test --headed; Python projects using the pytest plugin use pytest --headed. Confirm the installed package and consult the documentation matching your installed Playwright release.
A Python test remains headless
If it uses the pytest fixtures, verify that the Playwright pytest plugin is installed and that you ran pytest --headed. If it creates its own objects, the plugin’s CLI flags do not apply; launch that browser with headless=False.
Tests hang while you inspect them
That is expected when using --debug, which sets the default timeout to zero. Resume the Inspector or stop the run when finished. A plain --headed run retains normal timeout behavior.
UI Mode exposes sensitive data
A UI Mode server bound to 0.0.0.0 can be reachable by other machines. Keep it on localhost when possible, restrict network access when remote access is necessary, and treat traces as sensitive artifacts because they may include passwords, tokens and page content.
Headed runs are slow or flaky
Visible rendering adds work and makes resource contention easier to notice. Use headed mode to understand behavior, not as a performance benchmark. Narrow the test selection, avoid running many visible browser projects simultaneously, and reproduce the final result headless in a clean environment.
Or skip the browser setup
If your goal is a clean image or PDF of a page rather than interactive Playwright debugging, ScreenshotNeo makes one HTTP request and returns the capture. Its service accepts consent banners before capture and removes more than 60 known consent platforms, newsletter popups and chat widgets. Bot checks, blank pages, timeouts, failed loads and cache hits are not billed, and response headers identify the page verdict and billing result.
See the full parameter list in the ScreenshotNeo documentation. A minimal cURL request is:
Free tools Windows power users keep installed
One-click scans. No signup required.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpThe same request in Python:
import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)And in Node.js:
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);ScreenshotNeo also provides an MCP server with take_screenshot, get_page_info and capture_pdf tools for Claude, Cursor and other MCP clients. Every feature is included on every plan: 1,000 screenshots per month are free with no card, and paid plans start at $5 for 3,000 screenshots. Sign up free for ScreenshotNeo.
FAQ
Does headed mode change the assertions or locators in my tests?
No. It changes browser visibility; your test steps and assertions remain the same unless timing or display-dependent behavior exposes an existing issue.
Can I combine headed mode with a file or project filter?
Yes. Add the file path, -g title filter or --project selector to the same Playwright Test command.
Should headed mode be enabled in production CI?
Usually only when diagnosing a display-related failure. It requires a Linux display service such as Xvfb and consumes more graphical resources than headless execution.
Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteWindows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallThe Bottom Line
Use npx playwright test --headed for a one-off visible JavaScript or TypeScript run, configure headless: false for a persistent default, and choose --debug or --ui when you need Inspector controls or interactive test selection. Python pytest users run pytest --headed, while Linux CI requires a display such as Xvfb.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
