Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
To run Playwright tests without opening a browser window, use npx playwright test: Playwright Test runs headlessly by default. For a Node.js script that launches a browser directly, set headless: true in chromium.launch()—that is also the launch default. Install the browser binaries that match your Playwright package first, and choose a different Chromium headless path only if your CI behavior or browser-fidelity needs call for it.
Run Playwright Test headlessly
In a project that already has Playwright Test configured, run:
npx playwright testThis runs the configured test suite without opening a visible browser window. Install the matching browser binaries before the first run or after changing the Playwright package version:
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →npx playwright installIf the project only uses Chromium, install that browser alone:
#1 Best Overall
npx playwright install chromiumTo run one test file, add its path:
npx playwright test tests/example.spec.tsTo run one configured browser project, use the project name from your Playwright configuration:
npx playwright test --project=chromiumThe value chromium is an example project name, not a universal name: use whichever name your configuration defines. These commands change which tests or project run; they do not change the default headless behavior. Add --headed when you intentionally want a visible browser window.
Make headless mode explicit in the test configuration
Although headless execution is the default for Playwright Test, an explicit setting can make the intended behavior clear to teammates and prevent confusion when comparing configurations:
import { defineConfig } from '@playwright/test';
export default defineConfig({
use: {
headless: true,
},
});Save this in playwright.config.ts. The use block configures the test browser context and accepts browser launch options, including headless. Set it to false when you need to watch a test run in a browser window; otherwise, leaving it at true keeps test execution headless.
Launch a browser directly from Node.js
For a script that uses the Playwright library rather than the test runner, specify the launch option on the browser:
import { chromium } from 'playwright';
const browser = await chromium.launch({ headless: true });
try {
const page = await browser.newPage();
await page.goto('https://example.com');
// Perform automation here.
} finally {
await browser.close();
}This example assumes an environment that supports JavaScript modules and top-level await. Adapt the module format to your project if needed. The finally block closes the browser even if navigation or later automation throws an error. The launch option defaults to headless, but specifying it makes the intent unambiguous. Install the browser build matching the installed Playwright version before launching it.
Choose the Chromium headless implementation
“Headless Chromium” can refer to two distinct execution paths in Playwright. With no browser channel specified, Playwright uses a separate Chromium headless shell. You can instead opt into Chromium’s newer headless mode by setting channel: 'chromium' in a test project or launch options. The newer mode is described as closer to regular Chrome, and the two paths can behave differently. Do not assume a result from one path proves identical behavior in the other; check the path your target CI environment actually uses.
| Need | Choice | Install command |
|---|---|---|
| Standard headless CI, where the default behaves as expected | Default Chromium headless shell; omit the channel | npx playwright install --with-deps --only-shell |
| Closer alignment with regular Chrome or browser-extension testing | Newer Chromium headless mode; set channel: 'chromium' |
npx playwright install --with-deps --no-shell |
The install commands shown include Linux system-dependency installation as well as the browser selection. They are useful CI choices when you want only the corresponding headless browser files rather than the default set. If your test needs another browser or mode, select installation options to match that requirement instead of copying a shell-only command blindly.
Set the newer Chromium channel in a test project
For a Playwright Test project, add the channel to that project’s use options. For example, merge these settings into the project object in your existing configuration:
use: {
browserName: 'chromium',
channel: 'chromium',
headless: true,
}For a direct launch, pass the channel when launching:
const browser = await chromium.launch({
channel: 'chromium',
headless: true,
});Do not use the newer channel just because it sounds newer. Prefer the default shell if it behaves correctly and the smaller headless-only installation is useful; try the channel when Chrome-like fidelity or a feature requirement matters, then validate the behavior in the same environment where the tests will run.
Set up headless Playwright in CI
A minimal CI setup has three parts: install the project dependencies, install the Playwright browser binaries for the installed package version, and run the test command. On Linux CI, if required operating-system libraries are missing, install them together with Chromium:
npx playwright install --with-deps chromiumThen run the suite:
npx playwright testPlaywright browser binaries are versioned alongside the Playwright package. When that package changes, install the browser versions expected by the new package rather than relying on binaries left behind by a previous build. This is particularly important in CI images or caches that persist across runs: a package/browser mismatch can surface as a browser launch failure even though the test code itself has not changed.
When a visible CI run is necessary
Headless is usually the straightforward choice for CI when no one needs to watch the browser. For visual debugging, use --headed or Playwright’s debug command:
npx playwright test --headed
npx playwright test --debugA Linux agent needs a display server for headed execution. The CI documentation’s pattern is to run the headed test command under Xvfb:
Recommended Free Tools
xvfb-run npx playwright test --headedThat display requirement applies to the visible run, not the ordinary headless command. If the CI job is failing only after switching to headed mode, check the display setup before changing test logic.
Troubleshoot common headless failures
| Symptom | Likely cause | What to try |
|---|---|---|
| Browser executable is missing or fails to launch after an upgrade | Installed browser binaries do not match the Playwright package version | Run npx playwright install, or install the specific browser your project uses. |
| Chromium starts locally but not on Linux CI | Required operating-system dependencies may be absent | Try npx playwright install --with-deps chromium in the Linux environment. |
| Tests pass with one headless path but behave differently with another | The default headless shell and newer channel: 'chromium' mode can differ |
Confirm which path the project config selects and reproduce the target CI mode locally or in the same environment. |
| A headed debug run fails on a Linux agent with no display | Headed browsers need a display server | Use xvfb-run npx playwright test --headed, or return to headless mode when visibility is not needed. |
| The reason for a browser startup failure is unclear | Browser-level details are not visible in the normal test output | Enable Playwright browser logs with DEBUG=pw:browser. |
| The browser starts, but an API operation or automation step fails | More detail about Playwright API calls may be needed | Enable API logs with DEBUG=pw:api. |
Run a diagnostic command with the environment variable set for that invocation:
DEBUG=pw:browser npx playwright test
DEBUG=pw:api npx playwright testUse browser logs when the process fails to start or initialize a browser, and API logs when you need more detail about Playwright operations. Once you can reproduce a problem visibly, --debug can help inspect the test interactively; on Linux, make sure a display server is available for that headed session.
Or skip the browser setup
If your goal is simply to capture a webpage image or PDF, rather than to automate interactions or run a Playwright test suite, a screenshot API may be a better fit. ScreenshotNeo is a website screenshot API and MCP server: a single GET request can return a PNG, JPEG, WebP, or PDF. It is not a Playwright replacement for tests, assertions, or general browser automation.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Scan for outdated or missing drivers - takes under a minute3Repair Windows errors before they cause bigger problemsHere is a one-request image example; see the ScreenshotNeo API documentation for options:
curl -G "https://api.screenshotneo.com/v1/shot"
-d access_key=YOUR_API_KEY
--data-urlencode url=https://stripe.com
-o shot.webpScreenshotNeo accepts cookie or consent banners as a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each step can be turned off. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and the response includes X-Page-Verdict and X-Billed headers. Its MCP server provides take_screenshot, get_page_info, and capture_pdf tools for AI agents and MCP clients. The free plan includes 1,000 shots per month with no card; paid plans start at $5 for 3,000 shots. Every feature is available on every plan.
Sign up for ScreenshotNeo’s free plan to get 1,000 screenshots a month with no card.
Understand the practical trade-offs
Headless is about visibility, not a different test command
For Playwright Test, the normal command already runs headlessly; a special “headless” command is not required. Use configuration when you want the choice written down, and use a direct launch option when you are writing a standalone browser script. Switch to headed execution for observation and debugging, not as a general remedy for an unexplained failure.
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 →Performance and reliability depend on the environment
The material distinction established here is which browser build and dependencies the environment uses, not a guaranteed speed advantage for one headless path. The default shell supports a smaller headless-only installation; choosing the newer Chromium mode can change browser behavior and should be validated against the target. Matching the browser build to the package and provisioning Linux dependencies are practical reliability steps. There is no single runtime or performance figure that applies to every project, CI runner, and page.
Keep CI installs aligned with what tests exercise
Install only the browser set appropriate for the projects you run. Chromium-only installation is suitable for a Chromium-only project; a shell-only or no-shell installation narrows the Chromium headless path further. If tests use other configured browsers or require the alternate Chromium implementation, make sure the CI installation includes those needs. A narrowly scoped install can reduce unnecessary browser setup, but an install command that excludes a required browser will leave tests unable to launch it.
FAQ
Can I use Playwright headless mode to take a webpage screenshot?
Yes. A Playwright page can be automated in headless mode, including screenshot capture; choose Playwright when you also need browser interaction or test assertions. For a simple screenshot or PDF request without a test suite, the API option above avoids managing a local browser installation.
Does changing to headless: false change which tests run?
No. It changes whether the browser is visible. Select tests or projects separately with a file path or --project.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Is channel: 'chromium' required for headless tests?
No. The default is the separate Chromium headless shell. Specify the channel only when you deliberately want the newer Chromium headless path.
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.
