Run a Nightwatch test with Chrome hidden by using npx nightwatch --headless. Add the test path and, when your project defines several environments, select the Chrome environment explicitly with --env. A working Chrome installation, a compatible ChromeDriver, and a Nightwatch configuration that defines the selected environment are still required.
Fastest working command
From the project directory, run:
npx nightwatch --headlessNightwatch’s command-line reference describes --headless as launching Chrome or Firefox in headless mode. The flag changes how the browser is displayed; it does not remove the need for a valid browser environment or driver. See the Nightwatch command-line options reference for the current CLI syntax.
To run one file, append its path (using the path layout in your project):
npx nightwatch --headless tests/login.jsIf your configuration has a named Chrome environment, select it:
#1 Best Overall
npx nightwatch --env chrome --headlesschrome is only an example name. The value after --env must exactly match a key under test_settings in your configuration. Nightwatch documents environment selection in its test-environments guide.
Prerequisites Nightwatch still needs
Chrome and ChromeDriver
Install Chrome in the machine, container, or CI runner that executes the tests. Nightwatch drives Chrome through ChromeDriver, so the driver must be installed or downloaded by the project’s chosen setup and must be locatable and compatible with the installed browser. The ChromeDriver guide covers binary paths, capabilities, and driver startup.
Do not add a second driver-management method automatically. First inspect the existing package scripts and nightwatch.conf.js (or the project’s equivalent) to see whether Nightwatch starts a local process, uses a system driver, or connects to a remote endpoint.
A Nightwatch configuration file
Nightwatch recognizes configuration files including nightwatch.conf.js, nightwatch.conf.cjs, nightwatch.conf.ts, and nightwatch.json. If the file is not in the default location, pass it with the CLI’s configuration option, for example:
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →npx nightwatch --config config/nightwatch.conf.js --headlessKeep the test source folders, WebDriver settings, and named environments in that file. The configuration-file reference lists the supported structure.
Choose between the CLI flag and Chrome capabilities
There are two practical ways to express headless Chrome. Use the CLI flag for a one-off or uniform run. Put the argument in Chrome options when different environments need different browser switches or when the browser setup should be visible in version-controlled configuration.
| Approach | Example | Best for | Important detail |
|---|---|---|---|
| CLI | npx nightwatch --env chrome --headless |
Local runs, scripts, and simple CI commands | Nightwatch applies the headless mode requested by the command. |
| Chrome options | 'goog:chromeOptions': { args: ['--headless'] } |
Per-environment browser configuration | Capability names and merging behavior depend on Nightwatch, Selenium, and ChromeDriver versions. |
Avoid configuring both until you know how your runner combines them. A duplicate or conflicting capability can make troubleshooting harder without providing any benefit.
Configure headless Chrome explicitly
The following minimal configuration uses the current W3C capability name, goog:chromeOptions:
Recommended Free Tools
module.exports = {
src_folders: ['tests'],
test_settings: {
default: {
desiredCapabilities: {
browserName: 'chrome',
'goog:chromeOptions': {
args: ['--headless']
}
}
}
}
};Older Nightwatch examples may show chromeOptions instead. Match the capability shape to the versions actually installed in your project; do not copy an older key blindly. The ChromeDriver documentation explains how command-line switches are passed through Chrome options.
If you need a named environment, define it and invoke that exact name:
module.exports = {
src_folders: ['tests'],
test_settings: {
default: {
desiredCapabilities: { browserName: 'chrome' }
},
chrome_headless: {
desiredCapabilities: {
browserName: 'chrome',
'goog:chromeOptions': {
args: ['--headless']
}
}
}
}
};npx nightwatch --env chrome_headlessEnvironment names are project-defined, not guaranteed built-ins. If Nightwatch reports that an environment cannot be found, inspect the keys under test_settings and correct the command.
Run in Docker and continuous integration
Docker containers
Chrome can refuse to start in a container because of its sandbox restrictions. Nightwatch’s ChromeDriver guide documents adding --no-sandbox for that situation:
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Fix the driver behind crashes, sound loss and screen glitches3Repair Windows errors before they cause bigger problemsmodule.exports = {
src_folders: ['tests'],
test_settings: {
default: {
desiredCapabilities: {
browserName: 'chrome',
'goog:chromeOptions': {
args: ['--headless', '--no-sandbox']
}
}
}
}
};Use --no-sandbox only in an environment where the container setup requires it. It changes Chrome’s sandboxing and should not be treated as a universal local-run option.
Shared memory and CI-specific flags
Nightwatch’s GitLab CI example also uses --disable-dev-shm-usage:
Rank #3
'goog:chromeOptions': {
args: ['--headless', '--no-sandbox', '--disable-dev-shm-usage']
}That switch addresses a runtime-specific shared-memory constraint. Add it when your CI or container exhibits that problem, rather than copying every CI flag into every environment. The GitLab CI walkthrough describes installing Chrome and ChromeDriver, running Nightwatch, and (in some setups) using Xvfb. A headless run starts with --headless; Xvfb is an alternative display arrangement, not a requirement for every pipeline.
Typical CI command
npx nightwatch --env chrome_headless --headlessIn a pipeline, capture the Nightwatch, Chrome, and ChromeDriver logs as artifacts. They reveal whether the failure occurred while locating the driver, creating a session, loading a page, or executing a test.
Local driver, Grid, or hosted browsers
A local headless run is the shortest path when the test must execute on the current machine. Nightwatch can also start and stop a local WebDriver process when start_process is enabled and its binary path is configured. The same configuration model supports remote Selenium/Grid or cloud environments when a team needs centralized browsers, multiple operating systems, or parallel infrastructure; those are architecture choices, not prerequisites for --headless. Nightwatch’s configuration and environment guides explain how those settings are represented.
For a reproducible local or CI job, pin the project’s Nightwatch, Selenium-related packages, Chrome, and ChromeDriver versions according to your normal dependency policy. A browser update that outruns the driver is a common source of session-creation failures.
A reliable setup and verification sequence
- Check the Nightwatch CLI. Run
npx nightwatch --versionand confirm that the installed version supports the options you are using. - Locate the configuration. Identify the active
nightwatch.conf.*file, itssrc_folders, and the names undertest_settings. - Verify the browser. Confirm Chrome is installed in the same runtime as the test command, including inside the CI image or container.
- Verify ChromeDriver. Confirm Nightwatch can find a compatible driver or connect to the configured remote endpoint.
- Run the smallest test. Start with
npx nightwatch --env <your-name> --headless path/to/one-test.jsbefore running the full suite. - Add environment-specific switches only when needed. Use
--no-sandboxfor the documented container case and--disable-dev-shm-usagewhen the CI runtime’s shared-memory limits require it. - Review artifacts and logs. Keep screenshots, test output, browser logs, and driver logs so a failed pipeline can be diagnosed without rerunning blindly.
Performance, reliability, and cost considerations
Performance
Headless mode removes the visible desktop window, which is useful on servers and runners without a display. It does not guarantee that every test will run faster: page load time, waits, application startup, video or image processing, and the number of parallel sessions usually dominate runtime. Measure your own suite before changing timeouts or parallelism.
Reliability
Use explicit environment names and keep browser arguments in one place. A test that passes locally but fails in CI often differs in Chrome installation, driver discovery, sandbox permissions, shared memory, network access, or environment variables. Treat the GitLab example as a worked environment, not a universal recipe.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Cost
Running local Chrome and ChromeDriver avoids a hosted-browser service charge, but your team still pays in machine, container, and CI capacity. Remote providers can be useful when you need browsers or operating systems that are not installed locally. Nightwatch identifies BrowserStack and Sauce Labs as examples of hosted testing providers; neither is required for a local headless Chrome run.
Rank #4
Troubleshooting common failures
“Environment” or “test setting” not found
Cause: The value supplied to --env does not match a key in test_settings, or the wrong configuration file is active.
Fix: Check the configuration path, pass it with --config when necessary, and copy the environment name exactly. Remember that chrome is not guaranteed to exist.
Chrome cannot start in a container
Cause: The container’s user or sandbox setup prevents Chrome from launching.
Fix: Add the documented --no-sandbox Chrome argument in that container environment. If the failure concerns shared memory, test --disable-dev-shm-usage as shown in the GitLab example. Do not add unrelated flags until the logs identify the need.
Session creation or “Chrome failed to start” errors
Cause: Chrome is missing, ChromeDriver cannot be found, or the driver and browser are incompatible.
Fix: Check the installed versions and the driver path used by Nightwatch. Confirm the same binaries are present inside the CI image. Review driver startup logs before changing test code.
The command runs a visible browser
Cause: The headless flag was omitted, the wrong script was executed, or a configuration merge replaced the expected Chrome options.
Free tools Windows power users keep installed
One-click scans. No signup required.
Fix: Run npx nightwatch --headless directly, verify the selected environment, and inspect the final desired capabilities. Use either the CLI flag or the explicit goog:chromeOptions argument until you understand how your version merges both.
Tests pass locally but fail only in CI
Cause: Runtime differences such as missing Chrome, restricted sandbox permissions, low shared memory, network policy, or a different configuration file.
Fix: Compare browser and driver versions, print the active Nightwatch configuration, preserve logs, and apply only the CI-specific Chrome arguments demonstrated by the failure. The Nightwatch GitLab guide is a useful reference for a complete CI installation.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Or skip the browser setup
If your goal is a rendered image or PDF rather than an automated browser test, ScreenshotNeo provides a website screenshot API and MCP server. It accepts 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.
One GET request returns PNG, JPEG, WebP, or PDF. The complete API documentation is at https://screenshotneo.com/docs/.
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}`);ScreenshotNeo also offers full-page captures with lazy images loaded, CSS-selector element shots, dark mode, 12 device presets plus custom viewports, retina scale, PDF paper and page-range controls, HTML/CSS rendering, custom JavaScript and CSS, click-before-capture, selector hiding, selector/delay/network-idle waits, request and resource blocking, custom headers, cookies, user agents and authorization, timezone and geolocation, transparent backgrounds, resizing, configurable-TTL caching, signed public image links, asynchronous jobs with signed webhooks, bulk capture of up to 100 URLs per call, a usage API, an OpenAPI specification, and compatibility with parameter names used by other screenshot APIs. Its MCP server exposes take_screenshot, get_page_info, and capture_pdf to Claude, Cursor, and other 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. Create a free ScreenshotNeo account to get started.
Nightwatch headless Chrome checklist
- Use
npx nightwatch --headlessfor the direct command. - Add
--env <name>only with an environment that exists intest_settings. - Ensure Chrome is installed and ChromeDriver is compatible and locatable.
- Use
goog:chromeOptions.argsfor explicit, environment-specific switches. - In Docker, add
--no-sandboxonly when the container needs it. - In CI, investigate shared-memory and display constraints before adding flags such as
--disable-dev-shm-usageor Xvfb. - Preserve Nightwatch, Chrome, and ChromeDriver logs when diagnosing failures.
Frequently Asked Questions
Can I run Nightwatch headless without installing Chrome?
No. A headless session still needs Chrome (or another supported browser) and a compatible ChromeDriver or remote WebDriver endpoint in the runtime that executes the test.
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Repair Windows errors before they cause bigger problemsFix Now →Is Xvfb required for Nightwatch headless mode?
No. Xvfb appears in some CI setups as an alternative display arrangement. Start with Nightwatch’s --headless option and add display tooling only when the CI environment requires it.
Should I use chromeOptions or goog:chromeOptions?
Use the capability shape supported by the Nightwatch, Selenium, and ChromeDriver versions in your project. Current W3C configurations commonly use goog:chromeOptions; older examples may use chromeOptions.
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.
