What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Use headless Playwright for normal automated tests and CI; use headed Playwright when you need to watch the browser, inspect a failure, or debug an interaction. Playwright Test is headless by default. You can switch a test run with --headed, or set headless: false when launching a browser. The right choice depends on whether a human needs a visible window—not on a universal speed claim, because Playwright’s official documentation does not publish a single benchmark that applies to every workload.
What headless and headed mean in Playwright
Headless mode
In headless mode, Playwright drives a browser without opening a visible desktop window. Test results, logs, traces, screenshots and videos are observed through the test runner and its artifacts. This is the default behavior for Playwright Test, so a plain test command runs headlessly unless you change a setting.
Headed mode
Headed mode opens a normal browser window. You can watch each navigation and click, inspect the page while a test is running, and use the browser’s visible state to diagnose problems that are difficult to understand from terminal output alone.
| Consideration | Headless | Headed |
|---|---|---|
| Visible window | No | Yes |
| Best fit | Unattended automation, local test runs and CI | Interactive debugging, demonstrations and visual diagnosis |
| Playwright Test setting | Default; omit the option or use headless: true |
Use --headed |
| Browser API setting | headless: true (the default) |
headless: false |
| Display needed | No visible display in the normal workflow | A desktop display locally; usually Xvfb in CI |
| Chromium implementation | A separate Chromium headless shell by default when no channel is selected | The regular Chromium build |
How to run Playwright headless or headed
Playwright Test commands
From a project that already has Playwright installed, these commands select the mode for the entire run:
#1 Best Overall
# Default: headless
npx playwright test
# Open a visible browser window
npx playwright test --headed
# Open the Playwright Inspector and run headed
npx playwright test --debug--debug is more than a visibility switch. It opens the Playwright Inspector, which lets you step through actions, edit and test locators live, pick locators from the page, and review actionability logs. It also configures a debugging-friendly run. Use --headed when you simply want to watch a normal run; use --debug when you are investigating behavior.
Browser API launch options
When using Playwright’s library API, omit headless or set it to true for headless operation. Set it to false for a visible browser. slowMo adds a delay between operations so a person can follow them; the commonly shown 100 value is an example setting, not a performance measurement.
import { chromium } from 'playwright';
// Headless is the default.
const browser = await chromium.launch();
const page = await browser.newPage();
await page.goto('https://example.com');
console.log(await page.title());
await browser.close();
// Headed launch for local diagnosis.
const debugBrowser = await chromium.launch({
headless: false,
slowMo: 100
});
const debugPage = await debugBrowser.newPage();
await debugPage.goto('https://example.com');
await debugPage.pause();
await debugBrowser.close();page.pause() pauses execution so you can inspect the page with Playwright’s debugging tools. Remove it from unattended runs.
Which mode should you choose?
Choose headless for automation and CI
- Your pipeline should run without a person watching it.
- The build agent has no desktop session or display server.
- You want results in terminal output and saved artifacts.
- You are running many independent jobs and do not need a live window for each one.
Headless is the sensible baseline for regression suites, smoke tests, scheduled checks and production automation. A failure does not require a permanent display: configure traces, screenshots, videos or logs so the failed state can be inspected afterward.
Free tools Windows power users keep installed
One-click scans. No signup required.
Choose headed for diagnosis
- A locator fails and you need to see what was actually rendered.
- A menu, dialog, animation or hover interaction behaves unexpectedly.
- You are developing a new test and want immediate visual feedback.
- You are demonstrating a workflow to another person.
Headed mode is a diagnostic tool, not a requirement for writing reliable tests. Once the problem is understood, switch the normal suite back to headless and retain trace or screenshot capture for future failures.
Use both modes deliberately
A practical workflow is to reproduce a failure with npx playwright test --headed or --debug, correct the locator or synchronization issue, then verify the fix with the ordinary headless command. If a test passes headed but fails headless, treat that difference as a clue to investigate timing, rendering, resource loading or environment assumptions—not as proof that headed is inherently more correct.
Debugging features that make headed mode useful
Inspector and locator picking
The Inspector can pause at an action, show the current page, and help you select a locator from the rendered interface. Its actionability logs explain why Playwright considered an element not ready—for example, not visible, not enabled or covered by another element.
Slow motion
Set slowMo in the browser launch options when a sequence moves too quickly to observe. Keep the value limited to local diagnosis; adding delays to every CI run increases wall-clock time without improving test correctness.
Artifacts without a window
If your only reason for using headed mode is to see what happened after a failure, configure traces, screenshots, videos and console or network logs instead. These artifacts are reproducible in CI and can be attached to a build, whereas a display is ephemeral.
Headed Playwright in CI: displays and Xvfb
Headless runs normally work on a CI worker with no visible display. Headed runs need a display server. On Linux CI, Playwright documents using Xvfb, a virtual framebuffer that supplies a display without physical monitor hardware.
xvfb-run npx playwright test --headedThe CI image must contain Xvfb and the browser’s required display dependencies. If the command reports that it cannot open a display, verify the DISPLAY environment and the Xvfb installation before changing test code. Containers may also need system libraries required by the selected browser.
Chromium headless shell versus regular Chromium
Playwright ships a regular Chromium build for headed operations and, by default, a separate Chromium headless shell for headless mode when you do not specify a browser channel. That implementation difference can matter when testing browser-specific rendering or APIs.
Do these 3 things before closing this tab:
1Scan for outdated or missing drivers - takes under a minute2Clear out junk files and repair common Windows errors3Fix the driver behind crashes, sound loss and screen glitchesSelecting the chromium channel opts into the newer headless mode. Playwright describes it as closer to regular Chrome and more feature-complete for high-accuracy testing. Choose it when parity with a regular Chrome environment is more important than keeping the default headless-shell arrangement. Validate the choice against your supported browser matrix rather than assuming either implementation is universally superior.
Performance, reliability and cost considerations
Do not rely on a universal speed number
There is no official Playwright statistic that quantifies one universal headless-versus-headed speed or memory difference. Browser version, page complexity, videos, traces, CPU limits, network conditions, worker count and the CI image all affect results. If performance matters, measure the same test set in both modes on the environment you actually operate.
Control variables when measuring
- Pin the Playwright and browser versions.
- Run the same projects, retries, workers and artifact settings.
- Use representative pages and repeat the run enough to smooth transient network effects.
- Record duration, failure rate and resource usage separately; do not treat a single fast run as a benchmark.
Reliability practices
- Use resilient, user-facing locators rather than coordinates tied to a particular window size.
- Wait for meaningful conditions such as a selector or network state instead of inserting arbitrary sleeps.
- Keep headed debugging changes, such as
slowMoandpage.pause(), out of the production test path. - Capture a trace or screenshot on failure so headless CI failures remain diagnosable.
Common problems and fixes
“The headed browser cannot start in CI”
Cause: no display server is available. Fix: install and invoke Xvfb, for example xvfb-run npx playwright test --headed, and confirm the image has the required browser display libraries.
“The test passes headed but fails headless”
Cause: a timing race, a rendering-sensitive locator, resource differences or an assumption about viewport or browser implementation. Fix: inspect a trace, verify locator actionability, remove arbitrary sleeps, and compare the selected Chromium channel and viewport.
Recommended Free Tools
“I cannot see what failed in headless CI”
Cause: the job is not retaining diagnostics. Fix: enable traces, screenshots, videos or logs on failure and publish them as CI artifacts.
“The browser is too fast to follow locally”
Cause: normal automation completes actions immediately. Fix: run with --debug or launch with headless: false, slowMo: 100. Treat 100 milliseconds as a viewing aid, not a recommended production delay.
“A headed command opens a window but the page still looks wrong”
Cause: headed visibility does not change application state, viewport, permissions, authentication or network behavior. Fix: inspect those context settings and the page’s console and network logs; changing mode alone cannot repair an application defect.
Or skip the browser setup
If your goal is a clean website screenshot rather than interactive browser testing, ScreenshotNeo provides a single HTTP request. It accepts cookie and consent banners as a visitor and removes more than 60 known consent platforms, newsletter popups and chat widgets before capture; each cleanup step can be disabled. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads and cache hits are not billed, and response headers identify the page verdict and billing status.
ScreenshotNeo also offers an MCP server with take_screenshot, get_page_info and capture_pdf for Claude, Cursor and other MCP clients. Every plan includes its features. Pricing is Free for 1,000 shots per month with no card, Starter $5 for 3,000, Growth $15 for 15,000, Pro $39 for 60,000, Scale $99 for 250,000 and Business $249 for 1,000,000; yearly billing gives two months free.
cURL
See the ScreenshotNeo documentation for all options.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpPython
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)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}`);Create a free ScreenshotNeo account for 1,000 screenshots a month with no card.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.FAQ
Does headed mode produce more accurate tests?
Not automatically. It uses the regular headed browser build, while default Chromium headless uses a separate headless shell. Accuracy depends on your target browser and test environment; select the Chromium channel when closer-to-Chrome headless behavior is required.
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Can I use Playwright Inspector without writing headed launch code?
Yes. Run npx playwright test --debug; Playwright opens the Inspector and launches the test in headed mode.
Is Xvfb required for every Playwright test?
No. It is needed when a CI job must run a headed browser without a physical display. Ordinary headless CI runs do not need a visible display.
Should production monitoring use headed mode?
Usually no. Monitoring is unattended, so headless execution with retained diagnostics is simpler. Use headed mode only when reproducing or investigating a visual or interaction-specific issue.
Frequently Asked Questions
Does headed mode produce more accurate tests?
Not automatically. It uses the regular headed browser build, while default Chromium headless uses a separate headless shell. Accuracy depends on your target browser and test environment; select the Chromium channel when closer-to-Chrome headless behavior is required.
Can I use Playwright Inspector without writing headed launch code?
Yes. Run npx playwright test --debug; Playwright opens the Inspector and launches the test in headed mode.
Is Xvfb required for every Playwright test?
No. It is needed when a CI job must run a headed browser without a physical display. Ordinary headless CI runs do not need a visible display.
Should production monitoring use headed mode?
Usually no. Monitoring is unattended, so headless execution with retained diagnostics is simpler. Use headed mode only when reproducing or investigating a visual or interaction-specific issue.
The Bottom Line
Run Playwright headless by default for unattended tests and CI. Switch to headed or --debug when a person needs to observe and diagnose the browser, and use Xvfb when headed execution is required on a display-less CI worker.
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.
