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 reinstallPlaywright runs headlessly by default. In a Playwright Test project, install the matching browser binaries and run npx playwright test. For a script that launches a browser directly, pass headless: true to chromium.launch() (it is also the default). Headless mode still performs the browser work; it simply does not open a visible browser window.
This guide shows the command-line, configuration, and direct Node.js approaches, explains Chromium’s two headless implementations, and covers the browser and operating-system setup that commonly determines whether a CI run succeeds.
Run Playwright Test headlessly in three steps
- Install Playwright’s browser binaries. From your project directory, run
npx playwright install. If your configuration only uses Chromium,npx playwright install chromiuminstalls that browser. - Run the test suite. Use
npx playwright test. Playwright Test uses headless mode by default. - Choose a narrower run when needed. Append a test path, such as
npx playwright test tests/example.spec.ts, or select a configured browser project withnpx playwright test --project=chromium.
To temporarily see the browser, add --headed. That is a debugging switch, not a different test command.
Make headless mode explicit in Playwright Test
Set it in playwright.config.ts
The test runner’s headless option defaults to true. Declaring it in the configuration makes the intent visible to anyone reading the project and prevents an accidental change from being hidden in a command-line convention.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
#1 Best Overall
import { defineConfig } from '@playwright/test';
export default defineConfig({
use: {
headless: true,
},
});Run the configured suite normally:
npx playwright testFor local investigation, change the configuration value to false, or use npx playwright test --headed for a one-off visible run. Restore headless execution before committing a configuration change intended for CI.
Use the direct browser API
A script that does not use Playwright Test sets the option on the browser launch call. This complete Node.js example opens a page, performs an operation, and closes the browser even though no window is displayed.
import { chromium } from 'playwright';
const browser = await chromium.launch({ headless: true });
try {
const page = await browser.newPage();
await page.goto('https://example.com');
console.log(await page.title());
} finally {
await browser.close();
}headless: true is explicit here, but omitting the option uses Playwright’s headless launch default. Use headless: false when you need to watch the script during debugging.
Command and configuration choices
| Situation | Use | Result |
|---|---|---|
| Run the whole Playwright Test suite | npx playwright test |
Headless by default |
| Run one test file | npx playwright test tests/example.spec.ts |
Only that file runs headlessly |
| Run one configured browser project | npx playwright test --project=chromium |
Uses the selected project’s settings |
| See a one-off visible run | npx playwright test --headed |
Overrides headless execution for that run |
| Make the setting persistent | use: { headless: true } |
Applies to Playwright Test runs using that config |
| Launch from a script | chromium.launch({ headless: true }) |
Controls the direct browser API |
Choose Chromium’s headless implementation
Playwright’s default Chromium path and its newer Chromium headless path are distinct. When no channel is specified, Playwright uses a separate Chromium headless shell. You can instead set channel: 'chromium' to use Chromium’s newer headless mode, which is closer to the regular Chrome browser. Behavior can differ between the two, so verify the choice in the same environment where your tests will run.
Default headless shell
The shell is the default when you do not specify a channel. It is a practical choice for headless CI when the shell behaves as expected. If CI only needs this implementation, install the smaller headless-only browser set:
Rank #2
- HTML CSS Design and Build Web Sites
- Comes with secure packaging
- It can be a gift option
npx playwright install --with-deps --only-shellThe --only-shell option is specifically for the shell path; do not use it when your project needs the newer Chromium channel.
New Chromium headless mode
Set the channel in a test project or direct launch options:
import { chromium } from 'playwright';
const browser = await chromium.launch({
headless: true,
channel: 'chromium',
});
try {
const page = await browser.newPage();
await page.goto('https://example.com');
} finally {
await browser.close();
}For this path, install Chromium without the shell:
npx playwright install --with-deps --no-shellThe browser documentation describes the newer mode as the real Chrome browser and attributes claims of greater authenticity, reliability, and feature coverage to official Chrome documentation. Treat that as a vendor description, not a guarantee that every site behaves identically in your environment. The newer channel is the better candidate when alignment with regular Chrome matters or when you need browser-extension testing.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →| Choice | Install command | When it fits |
|---|---|---|
| Chromium headless shell | npx playwright install --with-deps --only-shell |
Headless CI that does not require regular-Chrome behavior |
| Chromium channel | npx playwright install --with-deps --no-shell |
Closer alignment with regular Chrome or extension testing |
Prepare Playwright for CI
Keep package and browser versions aligned
Each Playwright package version expects particular browser binaries, and Playwright updates those versions. After upgrading Playwright, run the appropriate npx playwright install command again instead of assuming an older binary is still compatible. A missing or mismatched binary is a setup failure, not a test assertion failure.
Install Linux operating-system dependencies
Linux agents may lack libraries required to start a browser. Install Chromium and the required system dependencies together:
Rank #3
npx playwright install --with-deps chromiumIf you deliberately use the shell-only or no-shell Chromium modes, use the corresponding commands shown above with --with-deps.
Keep the normal CI path headless
Headless execution does not need a display server. If you switch to headed mode on a Linux agent, provide Xvfb; the documented pattern is:
Do these 3 things before closing this tab:
1Scan for outdated or missing drivers - takes under a minute2Repair Windows errors before they cause bigger problems3Fix the driver behind crashes, sound loss and screen glitchesxvfb-run npx playwright testUse headed execution for diagnosis, not as a requirement for ordinary headless runs.
Capture useful logs
Separate browser-startup failures from Playwright API failures by enabling the matching debug channel:
DEBUG=pw:browser npx playwright test
DEBUG=pw:api npx playwright testFor an interactive investigation, Playwright also provides:
Rank #4
- Brand: Wiley
- Set of 2 Volumes
- A handy two-book set that uniquely combines related technologies Highly visual format and accessible language makes these books highly effective learning tools Perfect for beginning web designers and front-end developers
npx playwright test --debugThe debug command and --headed are useful when a selector, navigation, or browser startup issue needs visual inspection. Return to the ordinary headless command after identifying the cause.
Headless reliability and performance decisions
Choose fidelity before minimizing the install
The shell-only install is smaller, which can reduce the browser payload required by a CI image. That benefit is only useful if the shell reproduces the behavior your test needs. If a site, extension, or browser-specific behavior differs, use channel: 'chromium' and install with --no-shell instead.
Install once per environment image when possible
The important invariant is that the binaries available to the job match the Playwright package in that job. Whether your CI system caches the installation or rebuilds it on every run is an environment choice; after a package update, refresh the cached browser set so an old binary is not silently reused.
Use headless as the baseline, headed as a diagnostic
Headless mode avoids a display-server dependency. A headed fallback introduces Xvfb on Linux and can add another failure point. Keep the production path headless, and switch modes only when logs and a visible browser will answer a specific debugging question.
Troubleshooting common failures
| Symptom | Likely cause | Fix |
|---|---|---|
| Browser executable is missing after installing or upgrading Playwright | The package’s expected browser binaries were not installed, or an older set is being used | Run npx playwright install (or the required Chromium command) with the same package version used by the project |
| Chromium will not start on Linux CI | Operating-system dependencies are absent | Run npx playwright install --with-deps chromium and rebuild the job image if necessary |
| The test behaves differently from regular Chrome | The default shell and the newer Chromium headless mode are different implementations | Try channel: 'chromium', install with --no-shell, and verify the result in the target environment |
| You expected a window but none appeared | Headless mode is the default | Use npx playwright test --headed or set headless: false while debugging |
| Headed mode fails with a display error on Linux | No display server is available | Run the headed command under Xvfb, for example xvfb-run npx playwright test |
| Logs do not show whether startup or an API call failed | The wrong debug namespace was enabled | Use DEBUG=pw:browser for browser-level startup logs or DEBUG=pw:api for Playwright API logs |
| A test file or browser project is not the one being run | The command targets the default suite or a different project | Pass the file path or the exact configured project name with --project |
Or skip the browser setup
If your goal is a clean image or PDF of a URL rather than interactive browser testing, ScreenshotNeo provides a one-request website screenshot API and MCP server. It is the practical alternative when you do not want to maintain Playwright browser binaries, Linux dependencies, and headless-mode configuration.
Recommended Free Tools
Use the API documentation at https://screenshotneo.com/docs/ for the full parameter set. A basic cURL request is:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpThe same capture 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,
)
r.raise_for_status()
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}`);
if (!res.ok) throw new Error(`ScreenshotNeo returned ${res.status}`);
const data = Buffer.from(await res.arrayBuffer());
require('node:fs').writeFileSync('shot.webp', data);ScreenshotNeo accepts cookie and consent banners before capture and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each cleanup step can be disabled. Only clean shots are billed: bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing, and the response identifies the result with X-Page-Verdict and X-Billed headers. It can return PNG, JPEG, WebP, or PDF, and its MCP server exposes take_screenshot, get_page_info, and capture_pdf to Claude, Cursor, and other MCP clients.
For automation beyond a basic URL, options include full-page capture with lazy images loaded, CSS-selector element capture, dark mode, device presets or custom viewports, retina scale, PDF paper size and page ranges, custom CSS and JavaScript, pre-capture clicks, hidden selectors, selector/delay/network-idle waits, request and resource blocking, custom headers/cookies/user agents and Authorization, timezone and geolocation, transparent backgrounds, resizing, chosen cache TTLs, signed image links, asynchronous jobs with signed webhooks, bulk capture of up to 100 URLs per call, a usage API, and an OpenAPI specification. Common screenshot-API parameter names are accepted to make migration easier.
| Plan | Allowance and price |
|---|---|
| Free | 1,000 screenshots per month; no card |
| Starter | $5 for 3,000 screenshots |
| Growth | $15 for 15,000 screenshots |
| Pro | $39 for 60,000 screenshots |
| Scale | $99 for 250,000 screenshots |
| Business | $249 for 1,000,000 screenshots |
Every feature is included on every plan, and yearly billing provides two months free. Create a free ScreenshotNeo account to get 1,000 screenshots a month with no card.
Free tools Windows power users keep installed
One-click scans. No signup required.
Frequently Asked Questions
Is the Chromium headless shell the same browser as regular Chrome?
No. The default path uses a separate Chromium headless shell. The newer headless path uses Chromium through channel: 'chromium', so sites can behave differently between the two.
When is the shell-only install appropriate?
Use npx playwright install --with-deps --only-shell when your CI job needs the default shell and does not need regular-Chrome behavior or extension testing.
Why does headed Playwright need extra Linux setup?
A headed browser needs a display server. On a Linux agent without one, run the headed command under Xvfb, such as xvfb-run npx playwright test.
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.
