What is Nightwatch?

Nightwatch.js is an automated testing framework for web applications and websites, written in Node.js and using the W3C WebDriver API (formerly Selenium WebDriver).

It is a complete End-to-End testing solution which aims to simplify writing automated tests and setting up Continuous Integration. Nightwatch can also be used for writing Node.js unit and integration tests.

The name Nightwatch was inspired by the famous painting The Night Watch by Dutch artist Rembrandt van Rijn. The masterpiece is prominently displayed in the Rijksmuseum, in Amsterdam - The Netherlands.

Overview of WebDriver

WebDriver is a general purpose library for automating web browsers. It was started as part of the Selenium project, which is a popular and comprehensive set of tools for browser automation, initially written for Java but now with support for most programming languages.

Nightwatch uses the WebDriver API to perform the browser automation related tasks, like opening windows and clicking links for instance.

WebDriver is now a W3C specification aiming to standardize browser automation. WebDriver is a remote control interface that enables introspection and control of user agents. It provides a platform and a restful HTTP api as a way for web browsers to be remotely controlled.

Theory of Operation

Nightwatch works by communicating over a restful HTTP API with a WebDriver server (such as ChromeDriver or Selenium Server). The protocol is defined by the W3C WebDriver spec, which is derived from JSON Wire protocol. See below for an example workflow for browser initialization.

Most of the times, Nightwatch needs to send at least 2 requests to the WebDriver server in order to perform a command or assertion, the first one being the request to locate an element given a CSS selector (or Xpath expression) and the next to perform the actual command/assertion on the given element.

Install Node.js

From nodejs.org:

"Node.js is a platform built on Chrome's JavaScript runtime for easily building fast, scalable network applications. Node.js uses an event-driven, non-blocking I/O model that makes it lightweight and efficient, perfect for data-intensive real-time applications that run across distributed devices."

There are installation packages and instructions for most major Operating systems on its website nodejs.org. Remember to install also the npm tool, which is the node package manager and is distributed with the Node.js installer.

Install Nightwatch

To install the latest version using the npm command line tool, run the following:

npm install nightwatch

• add -g option to make nightwatch runner available globally in your system.
• add --save-dev option to save nightwatch as a devDependency in your package.json.

WebDriver Service

Depending on your target browser, you will need a specific WebDriver server. You will need to download and configure one (or more) of the following services:

WebDriver Binary	Browser	Description
GeckoDriver		Standalone server which implements the W3C WebDriver protocol to communicate with Gecko browsers, such as Firefox.
ChromeDriver		Standalone server which implements the JSON Wire Protocol for Chromium, however it is currently in the process of transitioning to the W3C WebDriver spec. Available for Chrome on Android and Chrome on Desktop (Mac, Linux, Windows and ChromeOS).
Microsoft WebDriver		Windows executable which supports both the W3C WebDriver spec and JSON Wire Protocol for running tests against Microsoft Edge.
SafariDriver		The /usr/bin/safaridriver binary comes pre-installed with recent versions of Mac OS and it's available to use following the instructions on Apple Developer website. More information is available on About WebDriver for Safari page.

Installing WebDriver

Installing the WebDriver services can be done either by downloading the binary directly or by using an NPM package.

GeckoDriver

GeckoDriver can be downloaded from the Releases page on GitHub. Release notes are also available there. Or you can use the geckodriver NPM package as a dependency in your project:

npm install geckodriver --save-dev

ChromeDriver

ChromeDriver can be downloaded from the ChromeDriver Downloads page. Or you can use the chromedriver NPM package as a dependency in your project:

npm install chromedriver --save-dev

Microsoft WebDriver

WebDriver for Microsoft Edge is now a Windows Feature on Demand. To install run the following in an elevated command prompt:

DISM.exe /Online /Add-Capability /CapabilityName:Microsoft.WebDriver~~~~0.0.1.0

More details about installation and usage documentation are available on the official Microsoft WebDriver homepage.

SafariDriver

The safaridriver binary is already installed on recent versions of Mac OS, however some manual configuration is needed before tests can be run against Safari.

You will need to run the following once, before using the safaridriver:

safaridriver --enable

More details are available on the Apple Developer website.

Using Selenium Server

Using Selenium Standalone Server used to be the de-factor standard for managing the various browser drivers and services, but starting with Nightwatch 1.0 is no longer required, nor is it recommended, unless you are testing against legacy browsers, such as Internet Explorer.

It might be required if you have a Selenium Grid environment.

Download Java

Selenium Server is a Java application, which means you will also need to have the Java Development Kit (JDK) installed, minimum required version is 7. You can check this by running java -version from the command line.

Download Selenium

Download the latest version of the selenium-server-standalone-{VERSION}.jar file from the Selenium downloads page and place it on the computer with the browser you want to test. In most cases this will be on your local machine and typically inside your project's source folder.

A good practice is to create a separate subfolder (e.g. bin) and place it there as you might have to download other driver binaries if you want to test multiple browsers.

Running Selenium Automatically

If the server is on the same machine where Nightwatch is running, it can be started/stopped directly by the Nightwatch Test Runner.

Running Selenium Manually

To run the Selenium Server manually, from the directory with the jar run the following:

java -jar selenium-server-standalone-{VERSION}.jar

Using Selenium Standalone Server

For viewing all the run-time options, run the previous command adding the -help:

java -jar selenium-server-standalone-{VERSION}.jar -help

Starting with Selenium 3, FirefoxDriver is no longer included in the package. Also, starting with version 48, Firefox is no longer compatible with FirefoxDriver which is shipped with Selenium 2.x. Firefox users are advised to use GeckoDriver for their testing. For more info, refer to the browser setup section.

More info about running the Selenium Server can be found here: https://github.com/SeleniumHQ/selenium/wiki/RemoteWebDriverServer

The nightwatch test runner binary expects a configuration file, using by default a nightwatch.json file from the current working directory. A nightwatch.conf.js file will also be loaded by default, if found.

nightwatch.json

At this point you should have at least one WebDriver service setup in your project.

Create the nightwatch.json in the project's root folder.

Assuming you have downloaded or installed the ChromeDriver service, the simplest nightwatch.json file will look like this, where node_modules/.bin/chromedriver is the path where ChromeDriver is installed:

{
  "src_folders" : ["tests"],

  "webdriver" : {
    "start_process": true,
    "server_path": "node_modules/.bin/chromedriver",
    "port": 9515
  },

  "test_settings" : {
    "default" : {
      "desiredCapabilities": {
        "browserName": "chrome"
      }
    }
  }
}

Using both configuration files is also possible, with nightwatch.conf.js always taking precedence if both are found.

nightwatch.conf.js

module.exports = (function(settings) {
  settings.test_workers = false;
  return settings;
})(require('./nightwatch.json'));

Base Settings

Below are the default settings that will be passed to the Nightwatch instance.

Environment specific settings

It is likely you will run your tests against multiple environments, and so Nightwatch makes it convenient to define environment specific test settings (under the "test_settings" dictionary). You can overwrite any test setting for each environment as needed. More on test environments under the Nightwatch Runner section.

Nightwatch includes a sample configuration file, which contains multiple environments for various type of requirements. It is located inside the Github repo:

Here's an extract. By default it is using Firefox as the target browser, but it includes configuration for Chrome and Selenium Server as well:

{
  "src_folders" : ["./examples/tests", "./examples/mocha", "./examples/unittests"],
  "custom_commands_path" : "./examples/custom-commands",
  "custom_assertions_path" : "./examples/custom-assertions",
  "page_objects_path" : "./examples/pages",
  "globals_path" : "./examples/globalsModule.js",

  "webdriver" : {
    "start_process": true
  },

  "test_settings" : {
    "default" : {
      "webdriver": {
        "server_path": "./bin/geckodriver-0.23",
        "port": 4444,
        "cli_args": [
          "--log", "debug"
        ]
      },
      "filter": ["./examples/tests"],
      "desiredCapabilities" : {
        "browserName" : "firefox",
        "acceptInsecureCerts" : true
      }
    },

    "chrome" : {
      "webdriver": {
        "port": 9515,
        "server_path": "./bin/chromedriver-2.32",
        "cli_args": [
          "--verbose"
        ]
      },

      "desiredCapabilities" : {
        "browserName" : "chrome",
        "loggingPrefs": {"driver": "INFO", "server": "OFF", "browser": "INFO"}
      }
    },

    "selenium_server" : {
      "selenium" : {
        "start_process": true,
        "host": "localhost",
        "server_path": "./bin/selenium-server-standalone-3.10.0.jar",
        "cli_args": {
          "webdriver.gecko.driver": "./bin/geckodriver-0.23",
          "webdriver.chrome.driver": "./bin/chromedriver-2.32"
        }
      },

      "desiredCapabilities" : {
        "browserName" : "firefox",
        "acceptSslCerts": true
      }
    }
  }
}

WebDriver Settings

Below are a number of options for the WebDriver service. Nightwatch can start and stop the WebDriver process automatically which is very convenient as you don't have to manage this yourself and focus only on the tests.

If you'd like to enable this, set start_process to true and specify the location of the binary file inside server_path.

Selenium Settings

The Selenium Server can still be used as prior to Nightwatch v1. If both webdriver and selenium dictionaries are present, the selenium options will be merged onto the webdriver ones.

Test Settings

The launch_url property

This property will be made available to the main Nightwatch api which is used in the tests. Its value depends on which environment is used. More on test environments under the Nightwatch Runner section.

If you run your tests specifying the integration environment (with --env integration) the launch_url will be set to http://staging.host, as per the configuration. Otherwise it will have the value defined in the default environment (i.e. http://localhost).

module.exports = {
  'Demo test' : function (browser) {
    browser
      .url(browser.launchUrl)
      // ...
      .end();
  }
};

Test Globals

A useful concept that Nightwatch provides is test globals. In its most simple form, this is a dictionary of name-value pairs which is defined in your nightwatch.json configuration file. Like the launch_url property, this is made available directly on the Nightwatch api which is passed to the tests. It is also dependent on the environment used, having the ability to overwrite specific globals per environment.

If we still pass the --env integration option to the runner, then our globals object will look like below:

module.exports = {
  'Demo test' : function (browser) {

    console.log(browser.globals);
    // {
    //   "myGlobalVar" : "some value",
    //   "otherGlobal" : "some other value"
    // }

  }
};

By default, a deep object copy will be created for each test suite run. If you'd like to maintain the same object throughout the entire tests run, set the persist_globals option to true, as detailed below.

External Test Globals

Test globals can also be defined in an external file, specified in the globals_path property.

The external globals file can also contain global test hooks, a custom reporter and other test specific settings. More on External Globals.

Full list of settings

This section contains guides for getting started with most of the major browsers and setup instructions on how to configure the individual webdriver implementations to work with Nightwatch.

The individual drivers described here are usually standalone applications which are used to interact with the browsers via the WebDriver HTTP API. You can run them either directly, or through the Selenium Server.

GeckoDriver

Overview

GeckoDriver is a standalone application used to interact with Gecko-based browsers, such as Firefox. It is written in Rust and maintained by Mozilla.

Starting with Firefox 48, GeckoDriver is the only way to automate Firefox, the legacy FirefoxDriver which used to be part of Selenium is no longer supported. Internally it translates the HTTP calls into Marionette, Mozilla's automation protocol built into Firefox.

Download

GeckoDriver can be downloaded from the Releases page on GitHub. Release notes are also available there. Or you can use the geckodriver NPM package as a dependency in your project:

npm install geckodriver --save-dev

Selenium 2.x users are advised to use version v0.9, whereas Selenium 3 users should use the latest version.

Standalone Usage

Nightwatch can manage the GeckoDriver service automatically, as with other WebDriver services, such as ChromeDriver. To use GeckoDriver directly, add this to your nightwatch.json:

{ 
  "webdriver": {
    "start_process" : true,
    "server_path": "./bin/geckodriver-0.23",
    "cli_args": [
      "--log", "debug"
    ],
    "port": 4444
  },

  "test_settings" : {
    "default" : {
      "desiredCapabilities": {
        "browserName" : "firefox",
        "acceptInsecureCerts": true
      }
    }
  }
}

Usage with Selenium Server

If you're using GeckoDriver through Selenium Server, simply set the cli argument "webdriver.gecko.driver" to point to the location of the binary file. E.g.:

{
  "selenium" : {
    "start_process" : true,
    "server_path" : "./bin/selenium-server-standalone-3.{VERSION}.jar",
    "log_path" : "",
    "port" : 4444,
    "cli_args" : {
      "webdriver.gecko.driver" : "./bin/geckodriver"
    }
  }
}

GeckoDriver can also be used as a standalone application. Usage steps are documented on GitHub: https://github.com/mozilla/geckodriver#usage.

Command line usage

$ ./bin/geckodriver-0.23 -help
geckodriver 0.23.0

USAGE:
    geckodriver-0.23 [FLAGS] [OPTIONS]

FLAGS:
        --connect-existing    Connect to an existing Firefox instance
    -h, --help                Prints help information
        --no-e10s             Start Firefox without multiprocess support (e10s) enabled
    -V, --version             Prints version information
    -v                        Set the level of verbosity. Pass once for debug level logging and twice for trace level logging

OPTIONS:
    -b, --binary            Path to the Firefox binary, if no binary capability provided
        --log                Set Gecko log level [values: fatal, error, warn, info, config, debug, trace]
        --marionette-port     Port to use to connect to gecko (default: random free port)
        --host                Host ip to use for WebDriver server (default: 127.0.0.1)
    -p, --port                Port to use for WebDriver server (default: 4444)

Firefox Capabilities

GeckoDriver supports a capability named firefoxOptions which takes Firefox-specific preference values. Details are available on the GeckoDriver GitHub page: https://github.com/mozilla/geckodriver#firefox-capabilities.

Firefox Profile

Specifying the firefox profile can be done by setting the profile property in the firefoxOptions dictionary, as detailed above. This can be the base64-encoded zip of a profile directory and it may be used to install extensions or custom certificates.

Implementation Status

GeckoDriver is not yet feature complete, which means it does not yet offer full conformance with the WebDriver standard or complete compatibility with Selenium. Implementation status can be tracked on the Marionette MDN page.

ChromeDriver

Overview

ChromeDriver is a standalone server which implements the JSON Wire Protocol for Chromium, however it is currently in the process of transitioning to the W3C WebDriver spec.

It is available for Chrome on Android and Chrome on Desktop (Mac, Linux, Windows and ChromeOS).

Download

ChromeDriver can be downloaded from the ChromeDriver Downloads page. Or you can use the chromedriver NPM package as a dependency in your project:

npm install chromedriver --save-dev

Standalone Usage

Nightwatch can manage the ChromeDriver service automatically, as with other WebDriver services, such as GeckoDriver. To use ChromeDriver directly, configure Nightwatch as below:

{ 
  "webdriver": {
    "server_path": "node_modules/.bin/chromedriver",
    "cli_args": [
      "--verbose"
    ],
    "port": 9515
  },

  "test_settings" : {
    "default" : {
      "desiredCapabilities" : {
        "browserName" : "chrome"
      }
    }
  }
}

Selenium Server Usage

If you're using ChromeDriver through Selenium Server, simply set the cli argument "webdriver.chrome.driver" to point to the location of the binary file. E.g.:

{
  "selenium" : {
    "start_process" : true,
    "server_path" : "./bin/selenium-server-standalone-3.{VERSION}.jar",
    "log_path" : "",
    "port" : 4444,
    "cli_args" : {
      "webdriver.chrome.driver" : "./bin/chromedriver"
    }
  }
}

ChromeOptions

You can specify Chrome options or switches using the chromeOptions dictionary, under the desiredCapabilities. Refer to the ChromeDriver website for a fill list of supported capabilities and options.

Example of detailed config

{ 
  "test_settings" : {
    "default" : {
      "desiredCapabilities" : {
        "browserName" : "chrome",
        "chromeOptions": {
          "args" : ["--no-sandbox"]
        },
        "loggingPrefs": {"driver": "INFO", "server": "OFF", "browser": "INFO"}
      }
    }
  }
}

Command line usage

$ ./bin/chromedriver -h
Usage: ./bin/chromedriver [OPTIONS]

Options
  --port=PORT                     port to listen on
  --adb-port=PORT                 adb server port
  --log-path=FILE                 write server log to file instead of stderr, increases log level to INFO
  --verbose                       log verbosely
  --version                       print the version number and exit
  --silent                        log nothing
  --url-base                      base URL path prefix for commands, e.g. wd/url
  --port-server                   address of server to contact for reserving a port
  --whitelisted-ips               comma-separated whitelist of remote IPv4 addresses which are allowed to connect to ChromeDriver

Microsoft WebDriver

Overview

Microsoft WebDriver is a standalone server which implements the WebDriver protocol for the Edge browser. It is supported by Windows 10 and onwards.

Download

WebDriver for Microsoft Edge is now a Windows Feature on Demand. To install run the following in an elevated command prompt:

DISM.exe /Online /Add-Capability /CapabilityName:Microsoft.WebDriver~~~~0.0.1.0

More details about installation and usage documentation are available on the official Microsoft WebDriver homepage.

Selenium Server Usage

If you're using Microsoft WebDriver through Selenium Server, simply set the cli argument "webdriver.edge.driver" to point to the location of the binary file. E.g.:

{
  "selenium" : {
    "start_process" : true,
    "server_path" : "bin/selenium-server-standalone-3.{VERSION}.jar",
    "log_path" : "",
    "port" : 4444,
    "cli_args" : {
      "webdriver.edge.driver" : "bin/MicrosoftWebDriver.exe"
    }
  },
  "test_settings" : {
    "default" : {
      "selenium_port"  : 4444,
      "selenium_host"  : "localhost",

      "desiredCapabilities": {
        "browserName": "MicrosoftEdge",
        "acceptSslCerts": true
      }
    }
  }
}

Standalone Usage

If you're only running your tests against Edge, running the EdgeDriver standalone can be slightly faster. Also there is no dependency on Java.

This requires a bit more configuration and you will need to start/stop the EdgeDriver:

1) First, disable Selenium Server, if applicable:

{
  "selenium" : {
    "start_process" : false
  }
}

2) Configure the port and default path prefix.

Microsoft WebDriver runs by default on port 9515. We also need to clear the default_path_prefix, as it is set by default to /wd/hub, which is what selenium is using.

{
  "test_settings" : {
    "default" : {
      "selenium_port"  : 17556,
      "selenium_host"  : "localhost",
      "default_path_prefix" : "",

      "desiredCapabilities": {
        "browserName": "MicrosoftEdge",
        "acceptSslCerts": true
      }
    }
  }
}

3) Start the MicrosoftWebDriver server

From the Windows CMD prompt, simply CD to the folder where the MicrosoftWebDriver.exe binary is located and run:

C:\nightwatch\bin>MicrosoftWebDriver.exe
[13:44:49.515] - Listening on http://localhost:17556/

Full command line usage:

C:\nightwatch\bin>MicrosoftWebDriver.exe -h
Usage:
 MicrosoftWebDriver.exe --host= --port= --package= --verbose

Implementation Status

EdgeDriver is not yet feature complete, which means it does not yet offer full conformance with the WebDriver standard or complete compatibility with Selenium. Implementation status can be tracked on the Microsoft WebDriver homepage.