How to Run Nightwatch in CI Without WebDriver Errors

Nightwatch drives browsers over WebDriver, so CI needs both the browser and a version-matched driver - the usual failure is a chromedriver/Chrome version mismatch.

Nightwatch is a Node end-to-end framework built on the W3C WebDriver protocol. It launches a system browser through a driver (chromedriver/geckodriver). In CI you must install the browser and a matching driver, run headless, and disable the sandbox in containers.

Why it fails in CI

Nightwatch needs a driver whose version matches the installed browser. A chromedriver that is a different major version than Chrome refuses to start the session. On a slim runner the browser may be missing or unable to run headless/sandboxed.

This version of ChromeDriver only supports Chrome version N - driver/browser mismatch.
No usable sandbox! - containerized Chrome needs --no-sandbox.
cannot find Chrome binary / missing geckodriver on the PATH.

Install & run it reliably

Install the browser and a matching driver. Nightwatch can manage drivers via its config, or you can install them as npm packages pinned to the browser version. Run headless with the sandbox disabled in containers.

.github/workflows/e2e.yml

npm ci
# driver matched to the installed browser (pin versions together)
npm install --save-dev chromedriver

# nightwatch.conf.js (chrome):
#   desiredCapabilities: { browserName: 'chrome',
#     'goog:chromeOptions': { args: ['--headless=new','--no-sandbox'] } }
npx nightwatch --env chrome

Cache & speed

Cache ~/.npm for Node deps. The browser is a system install - bake it and the matching driver into a custom image so versions stay aligned and apt does not run each job.

.github/workflows/ci.yml

- uses: actions/cache@v4
  with:
    path: ~/.npm
    key: npm-${{ runner.os }}-${{ hashFiles('**/package-lock.json') }}

Common errors

only supports Chrome version N → align chromedriver with the installed Chrome major version.
No usable sandbox! → add --no-sandbox to the chrome args in containers.
cannot find Chrome binary → install Chrome/Chromium and point Nightwatch at it.
Session never starts → driver not on PATH or version mismatch.

Key takeaways

Nightwatch needs a browser plus a version-matched WebDriver.
Pin chromedriver to the installed Chrome major version.
Run headless with --no-sandbox in containers; bake browser+driver into the image.