How to Run Headless Browser Tests With Nightwatch.js

To run Nightwatch browser tests without opening a visible browser window, run the project’s Nightwatch CLI with --headless:

npx nightwatch tests --headless

Nightwatch’s CLI documents headless launch for Chrome, Edge, and Firefox. You can also pass a specific test file, choose an environment with --env, or select a configuration file with --config. Headless changes how the browser is displayed; it does not change your test assertions or remove the need for a working browser and driver. See the Nightwatch CLI guide.

1. Install and initialize Nightwatch

For a new project, Nightwatch’s setup utility can create the configuration and guide you through choices such as browser, test folder, base URL, and local or remote execution:

npm init nightwatch

Follow the prompts, then install the generated project dependencies if the setup flow asks you to. For an existing project, install Nightwatch as a development dependency:

npm install --save-dev nightwatch

With Nightwatch installed locally, use npx nightwatch so the project’s version runs. The CLI also accepts a test file or folder as its source argument. The Getting Started guides describe the setup flow.

2. Add a test and configuration

If you do not already have a test, create tests/home.js:

module.exports = {
  'home page has a title': async browser => {
    await browser
      .navigateTo('https://example.com')
      .assert.titleContains('Example Domain')
      .end();
  }
};

For a straightforward local Chrome run, a minimal nightwatch.conf.js can look like this:

module.exports = {
  src_folders: ['tests'],
  test_settings: {
    default: {
      desiredCapabilities: {
        browserName: 'chrome',
        'goog:chromeOptions': {
          args: ['headless']
        }
      }
    }
  }
};

Nightwatch’s CLI --headless flag is the simplest way to request headless execution. The Chrome options shown above are an alternative when you want the browser arguments in configuration. Browser capability formats can vary with the Nightwatch and driver versions in your project; use the current ChromeDriver guide if you need to customize Chrome arguments, binary path, or preferences.

3. Run the tests

Run the whole configured suite or target one file:

# All tests in the configured source folder
npx nightwatch --headless

# A folder
npx nightwatch tests --headless

# One test file
npx nightwatch tests/home.js --headless

Useful CLI options can be combined with the source and headless switch:

# Choose a named test environment
npx nightwatch tests --env chrome --headless

# Select a configuration file
npx nightwatch tests --config nightwatch.ci.conf.js --headless

# Enable extended HTTP command logging while diagnosing a failure
npx nightwatch tests --verbose --headless

# Run tests in parallel workers when appropriate
npx nightwatch tests --parallel --headless

Use the names actually defined in your test_settings for --env; the example environment name chrome is not created automatically. Check the CLI reference for supported options and current syntax.

4. Configure local, CI, and container runs

Local WebDriver

A local headless run does not inherently require Selenium Server. Nightwatch distinguishes local WebDriver settings from Selenium settings; Selenium is used for Grid or cloud testing. Make sure the browser and compatible driver are available to the runner, either through your project’s supported driver setup or explicit configuration. See Nightwatch settings.

Continuous integration

1. Install the same project dependencies from the lockfile in CI.
2. Ensure the CI image has the browser and required driver available.
3. Run the same command used locally, such as npx nightwatch tests --headless.
4. Use a dedicated configuration or named environment for CI-specific paths and infrastructure.
5. Keep remote service credentials in the CI secret store if using a cloud or Selenium Grid environment.

Headless mode helps run without a visible desktop, but does not by itself make local and CI environments identical. Browser versions, operating system libraries, fonts, network access, test data, and timing can still differ.

Chrome inside Docker

Nightwatch’s ChromeDriver documentation specifically recommends adding --no-sandbox to Chrome arguments for its Docker-container scenario:

module.exports = {
  src_folders: ['tests'],
  test_settings: {
    default: {
      desiredCapabilities: {
        browserName: 'chrome',
        'goog:chromeOptions': {
          args: ['headless', '--no-sandbox']
        }
      }
    }
  }
};

Apply this for the documented container case rather than assuming it is required for every local headless run. Refer to the ChromeDriver documentation alongside your container image’s security and browser requirements.

Remote Grid or cloud browser

For a remote Selenium Grid or cloud service, configure a named test environment with the remote host, port, capabilities, and credentials expected by that service. Nightwatch documents services including BrowserStack and Sauce Labs, and lists other cloud providers in its settings reference. Local headless mode does not require a cloud provider; remote execution is a separate infrastructure choice. Start with the Selenium settings guide and cloud provider setup guide.

5. Choose the right options

Need	Option	Use
Run without a visible browser window	--headless	CLI switch documented for Chrome, Edge, and Firefox.
Run a subset of tests	Source path	Pass a file or folder, such as tests/home.js.
Select browser or infrastructure settings	--env	Choose a named environment defined in the config.
Use another project configuration	--config	Point to a configuration file such as nightwatch.ci.conf.js.
Investigate command failures	--verbose	Show extended HTTP command logging.
Use worker processes	--parallel	Enable parallel execution where the suite and environment support it.
Customize Chrome launch	Chrome options in capabilities	Configure arguments, binary, extensions, and preferences as needed.

Parallel workers may change resource demand and test interactions, so confirm your suite is safe to run concurrently before enabling them. For browser coverage across versions or operating systems, configure additional environments or a remote browser service; one headless run only covers the browser environment it launches.

6. Troubleshooting

Symptom	Likely cause	What to check
npx nightwatch is not found	Nightwatch is not installed in the project or dependencies were not installed.	Run npm install --save-dev nightwatch and install the project dependencies.
Browser or driver cannot be started	Browser/driver is missing, not on the expected path, or incompatible.	Check the browser installation, driver setup, and current Nightwatch browser-driver guidance.
The browser window still appears	The headless switch may not have been passed to the test runner, or browser-specific configuration may override expectations.	Confirm the command includes --headless; inspect the selected environment and capability arguments.
Docker Chrome exits during startup	Container launch requirements may not be met.	For the documented Docker scenario, check Chrome arguments and the --no-sandbox setting, plus the image’s browser dependencies.
Tests pass locally but fail in CI	Browser versions, dependencies, environment variables, network access, or test timing differ.	Compare the CI image and local browser/driver versions; make CI configuration explicit and inspect verbose logs.
Remote session cannot connect	Wrong host/port, missing credentials, or remote Selenium settings placed in the wrong environment.	Check the provider’s endpoint and credentials, and configure the remote connection under the relevant Selenium/test environment settings.
Parallel run is flaky	Tests may share state or compete for limited resources.	Try a serial run to isolate the issue, then review shared test data and worker configuration.

7. Performance, reliability, and cost

Headless mode removes the need to display a browser window; it is not a guarantee that tests will be faster. Actual run time depends on browser startup, page behavior, test design, environment resources, network conditions, and parallelism. Measure using your own suite before changing worker counts.

For more repeatable runs, pin project dependencies with a lockfile, make browser and driver versions explicit where your setup allows, isolate test data, and use stable readiness assertions rather than relying on arbitrary delays. Save the CI logs needed to diagnose failures. Remote testing adds a Grid or provider configuration and typically requires credentials; use the service’s own current documentation for operational details and pricing. Nightwatch’s setup and settings documentation establishes the local-versus-remote configuration distinction, but does not establish a universally faster or cheaper choice.

Or skip the browser setup

If your goal is to save a page image rather than interact with it through an end-to-end test, ScreenshotNeo is a website screenshot API and MCP server. A single GET request can return an image or PDF. See the ScreenshotNeo API documentation for request options.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

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)

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 removes cookie banners, popups, and chat widgets before the shot. Bot checks, blank pages, and failed loads are never billed, and response headers report the page verdict and billing status. Its MCP server lets AI agents take screenshots. The Free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 shots.

Create a free ScreenshotNeo account and get 1,000 screenshots a month with no card.

Frequently asked questions

Does headless mode run tests without a browser installed?

No. The browser still needs to launch; headless mode means it runs without a visible browser window.

Can I use headless mode with Firefox or Edge?

Nightwatch’s CLI guide documents headless launching for Chrome, Edge, and Firefox. Check the browser and driver setup for your project version.

Does a headless test replace cross-browser testing?

No. It tests the browser environment you configured. Additional browser or remote environments are a separate coverage choice.

Do I need Selenium Server for a local run?

Not inherently. Nightwatch documents Selenium Server for Grid and cloud testing; local runs can use WebDriver settings.

References: CLI test runner, settings, ChromeDriver, and Getting Started.