Environment:Nightwatchjs Nightwatch Selenium WebDriver 4

Knowledge Sources	Nightwatch.js Selenium WebDriver
Domains	Infrastructure, Browser_Automation
Last Updated	2026-02-12 01:00 GMT

Overview

Selenium WebDriver 4.27.0 environment with browser-specific driver binaries for Chrome, Firefox, Safari, and Edge automation.

Description

Nightwatch.js uses `selenium-webdriver` 4.27.0 as its core browser automation transport layer. This environment encompasses the Selenium WebDriver client library and the browser-specific driver binaries (ChromeDriver, GeckoDriver, SafariDriver, EdgeDriver) needed to control browsers. Nightwatch supports both local driver execution (where it manages the driver process lifecycle) and remote WebDriver server connections (Selenium Grid, BrowserStack, SauceLabs). The transport layer handles W3C WebDriver protocol with legacy JSONWire protocol compatibility for older commands.

Usage

This environment is required for all browser-based testing in Nightwatch, including E2E tests, component tests, and page object tests. It provides the bridge between Nightwatch test commands and actual browser instances. Use local drivers for development and CI, or remote servers for cross-browser/cloud testing.

System Requirements

Category	Requirement	Notes
Runtime	Node.js >= 18.20.5	Required by both Nightwatch and selenium-webdriver
Browser (Chrome)	Chrome + matching ChromeDriver	Driver version must match browser major version
Browser (Firefox)	Firefox + GeckoDriver	GeckoDriver translates W3C commands to Marionette
Browser (Safari)	Safari + SafariDriver	Built into macOS; enable via `safaridriver --enable`
Browser (Edge)	Edge + EdgeDriver	Chromium-based; uses same protocol as Chrome
Network	HTTP/HTTPS access to WebDriver endpoint	Port 4444 (Selenium), 9515 (Chrome), or cloud URL

Dependencies

System Packages

Browser binary (at least one of: Chrome, Firefox, Safari, Edge)
Matching browser driver binary (ChromeDriver, GeckoDriver, etc.)

Node.js Packages

`selenium-webdriver` = 4.27.0 (direct dependency)
`chromedriver` (optional peer dependency)
`geckodriver` (optional peer dependency)
`devtools-protocol` >= 0.0.1140464 (for CDP commands)

Credentials

For local testing, no credentials are required.

For remote/cloud testing, the following WebDriver config fields must be set:

`webdriver.username`: API authentication username (for cloud services).
`webdriver.access_key`: API authentication key (for cloud services).
`webdriver.host`: WebDriver server hostname.
`webdriver.port`: WebDriver server port (default varies by driver).

Quick Install

# Install Nightwatch with ChromeDriver
npm install nightwatch chromedriver --save-dev

# Or with GeckoDriver for Firefox
npm install nightwatch geckodriver --save-dev

# Or install without a specific driver (for remote/cloud testing)
npm install nightwatch --save-dev

Code Evidence

Selenium WebDriver import from `lib/index.js:1`:

const {By, Key, Capabilities} = require('selenium-webdriver');

Supported browser mapping from `lib/transport/factory.js:3-12`:

const BrowsersLowerCase = {
  chrome: Browser.CHROME,
  firefox: Browser.FIREFOX,
  safari: Browser.SAFARI,
  microsoftedge: Browser.EDGE,
  msedge: Browser.EDGE,
  edge: Browser.EDGE,
  ie: Browser.INTERNET_EXPLORER,
  'internet explorer': Browser.INTERNET_EXPLORER
};

WebDriver connection defaults from `lib/settings/defaults.js:221-254`:

webdriver: {
  start_process: false,
  cli_args: {},
  server_path: null,
  log_path: './logs',
  check_process_delay: 100,
  max_status_poll_tries: 10,
  status_poll_interval: 200,
  process_create_timeout: 120000,
  timeout_options: {
    timeout: 90000,
    retry_attempts: 2
  },
  username: undefined,
  access_key: undefined
}

Unknown browser error with "did you mean" suggestion from `lib/transport/factory.js:102-108`:

const didYouMean = require('didyoumean');
const browsersList = Object.values(Browser);
const resultMeant = didYouMean(browserName, browsersList);

throw new Error(`Unknown browser: "${browserName}"${resultMeant ? ('; did you mean "' + resultMeant + '"?') : ''}`);

Common Errors

Error Message	Cause	Solution
`Unknown browser: "X"; did you mean "Y"?`	Misspelled browser name in config	Fix `browserName` in `desiredCapabilities` to a supported value
`ECONNREFUSED` on WebDriver port	Driver process not running	Set `webdriver.start_process: true` or start driver manually
`session not created: This version of ChromeDriver only supports Chrome version X`	ChromeDriver/Chrome version mismatch	Update ChromeDriver to match installed Chrome version
`DEPRECATED: Setting browserName=null for running Appium tests`	Legacy Appium config pattern	Set `selenium.use_appium: true` instead of `browserName: null`

Compatibility Notes

Chrome: Most commonly used. ChromeDriver is an optional peer dependency (`npm i chromedriver`). Supports Chrome DevTools Protocol (CDP) commands.
Firefox: Uses GeckoDriver with Marionette protocol. Optional peer dependency (`npm i geckodriver`).
Safari: Built-in SafariDriver on macOS. Cannot run tests in parallel due to single-instance limitation.
Edge: Chromium-based. Uses same underlying protocol as Chrome. Accepts `msedge`, `edge`, or `microsoftedge` as browser name.
Internet Explorer: Legacy support. Uses JSONWire protocol commands marked as `w3c_deprecated`.
W3C vs Legacy: Nightwatch supports both W3C WebDriver and legacy JSONWire protocol. Some commands are deprecated and only work with JSONWire.

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment