Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
Use TestCafe’s chrome:headless browser alias, then append Chrome switches to the same quoted browser parameter. On Unix-like shells, run testcafe 'chrome:headless --no-sandbox' tests/sample-fixture.js; in Windows cmd.exe, use testcafe "chrome:headless --no-sandbox" tests/sample-fixture.js. This syntax is for a Chrome executable installed on the machine where TestCafe runs. Remote providers use their own configuration mechanisms.
The correct CLI syntax
TestCafe treats the browser alias and its arguments as one command-line parameter. Keep the entire value quoted so the shell does not split the alias from the switch.
testcafe 'chrome:headless --no-sandbox' tests/sample-fixture.jsThe --no-sandbox switch is only an example of a custom Chrome argument. Do not add it automatically: Chrome’s sandbox is an important security boundary, and whether disabling it is appropriate depends on your execution environment, such as a suitably isolated CI container.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Unix shells
Use single quotes in Bash, Zsh and similar shells:
testcafe 'chrome:headless --disable-gpu --window-size=1440,900' tests/sample-fixture.jsReplace the switches with the arguments your test requires. Arguments are passed to the local Chrome process launched by TestCafe.
#1 Best Overall
- SLIM. LIGHTWEIGHT. READY TO GO: The all-new slim design is perfect for busy lives on the go.
- SKILLFULLY DESIGNED. MILITARY TOUGH: Built with premium craftsmanship to withstand the occasional drop or ding.
- ALL-DAY, ALL-IN-ONE CHARGING: Power through your school day – and beyond – with a long-lasting 12-hour battery.¹
- 3X FASTER THAN THE PREVIOUS GENERATION OF WIFI: Crush your schoolwork in record time with Wi-Fi that’s three times faster than the previous generation of Wi-Fi.
- YOUR PHONE AND CHROMEBOOK WORK BETTER TOGETHER: Easily transfer files between devices, and control your phone right from your Chromebook.
Windows Command Prompt
Windows cmd.exe uses double quotes around the complete browser parameter:
testcafe "chrome:headless --disable-gpu --window-size=1440,900" tests/sample-fixture.jsPowerShell has different quoting and escaping rules. If a value contains spaces, keep the browser expression as one argument and verify how your PowerShell version passes nested quotes to the TestCafe CLI.
Prerequisites and what this command can launch
- Install TestCafe in the project or make its CLI available through your package manager.
- Install Chrome, or place a portable Chrome executable on the same machine.
- Ensure TestCafe can discover that executable. The CLI form with arguments applies to installed and portable browsers on the current machine.
- Provide a real fixture or test path, such as
tests/sample-fixture.js.
A cloud browser is not a local Chrome process. Passing a local CLI postfix does not configure a remote provider. Select the provider’s TestCafe plugin and follow its argument settings instead.
Running headless Chrome through the JavaScript API
With the Runner API, select the headless alias directly:
const createTestCafe = require('testcafe');
(async () => {
const testcafe = await createTestCafe();
try {
const runner = testcafe
.createRunner()
.src('tests/sample-fixture.js')
.browsers('chrome:headless');
await runner.run();
} finally {
await testcafe.close();
}
})();The alias enables headless Chrome but does not, by itself, add arbitrary command-line switches. For a specific local executable and command line, the API also accepts a browser object:
const runner = testcafe
.createRunner()
.src('tests/sample-fixture.js')
.browsers({
path: '/opt/google/chrome/chrome',
cmd: '--headless --disable-gpu --window-size=1440,900'
});The cmd property is optional. Use this object when you need to identify an executable explicitly and provide its command line. Do not treat it as interchangeable with an alias postfix: the API documentation’s path-based configuration has a postfix limitation, so path: forms should not be presented as another spelling of chrome:headless --argument.
Rank #2
- FOR HOME, WORK, & SCHOOL – With an Intel processor, 14-inch display, custom-tuned stereo speakers, and long battery life, this Chromebook laptop lets you knock out any assignment or binge-watch your favorite shows..Voltage:5.0 volts
- HD DISPLAY, PORTABLE DESIGN – See every bit of detail on this micro-edge, anti-glare, 14-inch HD (1366 x 768) display (1); easily take this thin and lightweight laptop PC from room to room, on trips, or in a backpack.
- ALL-DAY PERFORMANCE – Reliably tackle all your assignments at once with the quad-core, Intel Celeron N4120—the perfect processor for performance, power consumption, and value (2).
- 4K READY – Smoothly stream 4K content and play your favorite next-gen games with Intel UHD Graphics 600 (3) (4).
- MEMORY AND STORAGE – Enjoy a boost to your system’s performance with 4 GB of RAM while saving more of your favorite memories with 64 GB of reliable flash-based eMMC storage (5).
Choosing the right launch form
| Where Chrome runs | How TestCafe selects it | Where arguments belong | Typical form |
|---|---|---|---|
| Installed or portable Chrome on the test host | Browser alias | After the alias in one quoted CLI parameter | chrome:headless --switch |
| Explicit local executable | { path, cmd } object in the API |
cmd property |
{ path: '/path/to/chrome', cmd: '--headless ...' } |
| BrowserStack | TestCafe BrowserStack provider alias | BROWSERSTACK_CHROME_ARGS |
Provider environment configuration |
| Another cloud or custom provider | That provider’s TestCafe plugin | Provider-specific launch settings | Consult the plugin documentation |
BrowserStack and other remote providers
For BrowserStack, the TestCafe provider documents the BROWSERSTACK_CHROME_ARGS environment variable for Chrome command-line arguments. BrowserStack Automate must also be enabled with BROWSERSTACK_USE_AUTOMATE=1. These names are BrowserStack-specific; do not assume they work with another cloud service.
Recommended Free Tools
For a different provider, configure the browser through its TestCafe provider plugin. TestCafe’s provider model uses aliases supplied by plugins, and custom headless-browser plugins can expose their own launch options. A local command such as chrome:headless --disable-gpu does not guarantee that the same switch reaches a remotely hosted browser.
Verifying the mode from test code
TestCafe exposes the active browser’s mode and alias through the test controller:
import { Selector } from 'testcafe';
test('reports the browser configuration', async t => {
console.log('alias:', t.browser.alias);
console.log('headless:', t.browser.headless);
await t.expect(t.browser.headless).ok();
});This confirms what TestCafe reports for the running session. It does not prove that every application-specific Chrome switch changed page behavior. If a switch affects rendering, permissions or network handling, verify that behavior separately in the application under test.
Custom-argument patterns that are commonly useful
Window dimensions
testcafe 'chrome:headless --window-size=1440,900' tests/sample-fixture.jsSet a deterministic viewport when screenshots or responsive layouts are part of the test. TestCafe’s own browser and fixture settings may also affect the effective viewport, so check the page dimensions rather than assuming the switch is the only input.
Free tools Windows power users keep installed
One-click scans. No signup required.
Combining several switches
testcafe 'chrome:headless --disable-gpu --window-size=1440,900 --user-agent="QA Chrome"' tests/sample-fixture.jsAll switches remain inside the same outer quote. Nested quoting can vary by shell; if a user-agent value is difficult to pass, simplify it, escape the inner quotes for that shell, or move to the JavaScript API’s cmd field.
Rank #3
- Storage: 16GB Flash Memory
- OS: Chrome OS
- Screen Size: 11.6"
CI containers
Arguments such as --no-sandbox sometimes appear in containerized CI recipes, but they are not universally required. First determine whether the container already provides the permissions and isolation Chrome expects. Disabling the sandbox in an untrusted or shared environment can increase risk.
Troubleshooting
“Browser not found” or Chrome never starts
TestCafe can only launch an installed or portable browser it can discover on the current machine. Confirm Chrome is installed, check the executable path, and use the API’s { path, cmd } object when automatic discovery is unreliable.
The argument is treated as a second browser
The shell probably split the parameter. Quote the alias and every switch together: 'chrome:headless --switch' on Unix-like shells or "chrome:headless --switch" in cmd.exe.
The test opens a headed window
Check that the exact alias is chrome:headless, with the colon and spelling intact. In API code, ensure .browsers('chrome:headless') is the value actually used by the runner and that a later configuration does not replace it.
A switch has no visible effect
Some Chrome flags are version-dependent, restricted in particular environments, or unrelated to the behavior being measured. Confirm the effective browser mode with t.browser.headless and inspect the application symptom independently. A successful launch only shows that Chrome started; it does not validate the semantic effect of every flag.
The path object behaves differently from the CLI
The path-based API configuration has a documented postfix limitation. Keep executable selection and command-line configuration in the object’s path and cmd fields rather than appending alias-style text to the path.
Rank #4
- Intel Celeron N4120: 4 Cores & Threads, 1.1GHz Base Clock, Up to 2.6GHz Boost Clock, 4MB Cache, Intel UHD Graphics 600. The perfect combination of performance, power consumption, and value helps your device handle multitasking smoothly and reliably with four processing cores to divide up the work.
- 14" HD Display: 14.0-inch diagonal, HD (1366 x 768), micro-edge, anti-glare. See your digital world in a whole new way. Enjoy movies and photos with the great image quality and high-definition detail of 1 million pixels.
- Memory & Storage: 4 GB LPDDR4x & 64 GB eMMC Storage. Adequate high-bandwidth RAM to smoothly run multiple applications and browser tabs all at once. An embedded multimedia card provides reliable flash-based storage.
- Ports:2 x USB 3.0 Type-A，1 x USB 3.0 Type-C，1 x HDMI，1 x Headphone Jack
- Chrome OS: Chromebook is a computer for the way the modern world works, with thousands of apps. Enjoy the seamless simplicity that comes with Google Chrome and Android apps, all integrated into one laptop. It’s fast, simple, and secure.
BrowserStack ignores the local switch
Local CLI arguments apply to local Chrome. For BrowserStack, set BROWSERSTACK_CHROME_ARGS and enable Automate with BROWSERSTACK_USE_AUTOMATE=1. For other providers, use their plugin’s documented settings.
Reliability and maintenance guidance
- Pin the Chrome and TestCafe versions used by CI when reproducibility matters; browser flags can change behavior across Chrome releases.
- Keep the browser parameter in a script or package command so quoting is reviewed with the rest of the test configuration.
- Use the smallest set of switches that solves the problem. Extra flags make failures harder to attribute and can alter security or rendering behavior.
- Log the selected alias and headless status when diagnosing CI-only failures.
- Separate local-launch assumptions from provider settings in configuration files, rather than attempting one universal argument string.
Or skip the browser setup
If your actual goal is a clean image or PDF of a web page rather than an interactive TestCafe session, ScreenshotNeo provides a single HTTP request. It accepts consent banners before capture, removes more than 60 known consent platforms plus newsletter popups and chat widgets, and lets you turn those steps off. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads and cache hits are not billed; each response reports the result in X-Page-Verdict and X-Billed headers. Its MCP server also gives Claude, Cursor and other MCP clients take_screenshot, get_page_info and capture_pdf tools.
See the ScreenshotNeo documentation for all request options, including viewport and device presets, full-page lazy-image loading, CSS-selector element capture, dark mode, retina scale, custom CSS and JavaScript, clicks, selector or network-idle waits, blocked resources, headers, cookies, user agents, authorization, timezone, geolocation, transparent backgrounds, resizing, chosen cache TTLs, signed image links, asynchronous webhooks, bulk capture of up to 100 URLs per call, usage reporting and the OpenAPI specification.
One-call examples
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpimport 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)const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);The Free plan includes 1,000 screenshots per month with no card. Paid plans start at $5 for 3,000 shots, and every feature is available on every plan. Create a free ScreenshotNeo account.
Frequently Asked Questions
Can I pass Chrome arguments after a custom executable path in the CLI?
Use the documented alias form for local CLI arguments, or use the JavaScript API’s { path, cmd } object for an explicit executable. Path-based configuration has a postfix limitation, so do not append alias-style arguments to the path itself.
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Does chrome:headless configure a remote Chrome session?
No. It selects headless Chrome that TestCafe launches locally. Remote sessions require the provider’s TestCafe plugin and its own argument configuration.
How can I tell whether TestCafe really started headless?
Read t.browser.headless and t.browser.alias in a test. Those properties report TestCafe’s active browser configuration.
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.
