Nightwatch.js

Browser automated testing, the easy way.

Browser Automation

Nightwatch.js is an integrated, easy to use End-to-End testing solution for browser based apps and websites, written on Node.js. It uses the W3C WebDriver API to perform commands and assertions on DOM elements.

  • Clean Syntax

    Simple but powerful syntax which enables you to write tests very quickly, using only Javascript (Node.js) and CSS or Xpath selectors.

  • Cloud Testing Support

    Comes with its own cloud testing platform - NightCloud.io (TBA). Works with other cloud testing providers, such as SauceLabs and BrowserStack.

  • Page Objects Support

    Fluent and easy to work with Page Object Model support to better organise elements and sections, with support for both CSS or Xpath selectors.

  • Easy to Extend

    Flexible command and assertion framework which makes it easy to extend to implement your application custom commands and assertions.

  • Built-in Test Runner

    Built-in command-line test runner which can run the tests either sequentially or in parallel, together, by group, tags or single. Also, support for Mocha runner is built-in.

  • WebDriver Service

    Manages automatically Selenium or WebDriver services (ChromeDriver, GeckoDriver, Edge, Safari) in a separate child process.

  • Continuous Integration

    JUnit XML reporting is built-in so you can integrate your tests in your build process with systems such as Teamcity, Jenkins, Hudson etc.

Demo Test

The test below navigates to google.com and searches for "rembrandt van rijn", then verifies if the term first result is the Wikipedia page of Rembrandt.


module.exports = {
  'Demo test Google' : function (client) {
    client
      .url('http://www.google.com')
      .waitForElementVisible('body', 1000)
      .assert.title('Google')
      .assert.visible('input[type=text]')
      .setValue('input[type=text]', 'rembrandt van rijn')
      .waitForElementVisible('button[name=btnG]', 1000)
      .click('button[name=btnG]')
      .pause(1000)
      .assert.containsText('ol#rso li:first-child',
        'Rembrandt - Wikipedia')
      .end();
  }
};

Run and manage your Nightwatch tests
with absolutely no hassle, no config, no nonsense.

Learn More

Getting Started

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.

Theory of Operation

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 Mozilla Firefox Standalone server which implements the W3C WebDriver protocol to communicate with Gecko browsers, such as Firefox.
ChromeDriver Google Chrome 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 Microsoft Edge Windows executable which supports both the W3C WebDriver spec and JSON Wire Protocol for running tests against Microsoft Edge.
SafariDriver Microsoft Edge 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.

Name type default description
webdriver object An object containing WebDriver related configuration options. See the next section for details.
src_folders Optional string|array none An array of folders (excluding subfolders) where the tests are located.

If this is not specified, the test source must be passed inline as the second argument to the test runner.
test_settings object This object contains all the test related options and can contain multiple environments. See below for details.
selenium Optional object An object containing Selenium Server related configuration options. If Selenium is not used, webdriver options should be set instead.
Starting with Nightwatch 1.0, Selenium is only required when testing against a Grid setup or a cloud testing service (such as SauceLabs or BrowserStack).
output_folder
Optional
string tests_output The location where the JUnit XML report files will be saved.
custom_commands_path Optional string|array none Location(s) where custom commands will be loaded from.
custom_assertions_path Optional string|array none Location(s) where custom assertions will be loaded from.
page_objects_path
Optional
string|array none Location(s) where page object files will be loaded from.
globals_path
Optional
string none Location of an external globals module which will be loaded and made available to the test as a property globals on the main client instance.

Globals can also be defined/overwritten inside a test_settings environment.
live_output
Optional
boolean false Whether or not to buffer the output in case of parallel running. See below for details.
disable_colors
Optional
boolean false Controls whether or not to disable coloring of the cli output globally.
parallel_process_delay
Optional
integer 10 Specifies the delay(in milliseconds) between starting the child processes when running in parallel mode.
test_workers
Optional
boolean|object false Whether or not to run individual test files in parallel. If set to true, runs the tests in parallel and determines the number of workers automatically.
If set to an object, can specify specify the number of workers as "auto" or a number.

Example: "test_workers" : {"enabled" : true, "workers" : "auto"}
test_runner
Optional
string|object "default" Specifies which test runner to use when running the tests. Values can be either default (built-in nightwatch runner) or mocha.


Example: "test_runner" : {"type" : "mocha", "options" : {"ui" : "tdd"}}
unit_tests_mode
Optional
boolean false Controls whether to run tests in unit testing mode, which means the session will not automatically be created.

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.

Name type default description
start_process boolean false Whether or not to manage the WebDriver process automatically.
server_path string none The location of the WebDriver binary. This needs to be specified if start_process is enabled.
E.g.: bin/chromedriver
port integer The port number on which the WebDriver service will listen and/or on which Nightwatch will attempt to connect.
host string Only needed when the WebDriver service is running on a different machine.
log_path Optional string|boolean none The location where the WebDriver service log file output.log file will be placed. Defaults to current directory.
To disable WebDriver logging, set this to false
cli_args Optional object none List of cli arguments to be passed to the WebDriver process. This varies for each WebDriver implementation.
request_timeout_options Optional object timeout: 60000
retry_attempts: 0
Requests to the WebDriver service will timeout in timeout ms; A retry will happen retry_attempts number of times.

Example:

{timeout: 15000, retry_attempts: 5}
username Optional string none Usually only needed for cloud testing Selenium services. In case the server requires credentials this username will be used to compute the Authorization header.

The value can be also an environment variable, in which case it will look like this:
"username" : "${SAUCE_USERNAME}"
access_key Optional string none This field will be used together with username to compute the Authorization header.

Like username, the value can be also an environment variable:
"access_key" : "${SAUCE_ACCESS_KEY}"
proxy Optional string none Proxy requests to the WebDriver (or Selenium) service. http, https, socks(v5), socks5, sock4, and pac are accepted. Uses node-proxy-agent.

Example: http://user:pass@host:port
default_path_prefix Optional string Needed sometimes when using a Selenium Server. The prefix to be added to to all requests (e.g. /wd/hub).
use_legacy_jsonwire Optional boolean false Some WebDriver implementations (Safari, Edge) support both the W3C WebDriver API as well as the legacy JSON Wire (Selenium) API.

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.

Name type default description
start_process boolean false Whether or not to manage the Selenium process automatically.
server_path string none The location of the Selenium jar file. This needs to be specified if start_process is enabled.
E.g.: bin/selenium-server-standalone-2.43.0.jar
log_path string|boolean none The location where the Selenium output.log file will be placed. Defaults to current directory.
To disable Selenium logging, set this to false
version2 boolean false Set this to true if you need to use legacy Selenium Server 2.
port integer 4444 The port number Selenium will listen on and/or Nighwatch will attempt to connect to.
cli_args object none List of cli arguments to be passed to the Selenium process. Here you can set various options for browser drivers, such as:

  • webdriver.firefox.profile: Selenium will by default create a new Firefox profile for each session. If you wish to use an existing Firefox profile you can specify its name here.
    Complete list of Firefox Driver arguments available here.
  • webdriver.chrome.driver: Nightwatch can run the tests using Chrome browser also. To enable this you have to download the ChromeDriver binary and specify it's location here. Also don't forget to specify chrome as the browser name in the desiredCapabilities object.
    More information can be found on the ChromeDriver website.
  • webdriver.ie.driver: Nightwatch has support for Internet Explorer also. To enable this you have to download the IE Driver binary and specify it's location here. Also don't forget to specify "internet explorer" as the browser name in the desiredCapabilities object.

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

Name type default description
desiredCapabilities object The WebDriver when a new session will be created. You can specify browser name for instance along with other capabilities.
Example:

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

You can view the complete list of capabilities here.
launch_url string none A url which can be used later in the tests as the main url to load. Can be useful if your tests will run on different environments, each one with a different url.
start_session boolean true Whether or not to automatically start the WebDriver session. This will typically be set to false when running unit/integration tests that don't interact with the Selenium server.
unit_tests_mode boolean false Run Nightwatch in unit testing mode, that is no WebDriver session will be created and the tests will not receive the browser api object. More on writing unit tests in Nightwatch.
screenshots object none Selenium generates screenshots when command errors occur. With on_failure set to true, also generates screenshots for failing or erroring tests. These are saved on the disk.

Since v0.7.5 you can disable screenshots for command errors by setting "on_error" to false.

Example:

"screenshots" : {
  "enabled" : true,
  "on_failure" : true,
  "on_error" : false,
  "path" : ""
}
globals object An object which will be made available within the test and can be overwritten per environment. Example:

"globals" : {
  "myGlobal" : "some_global"
}
Globals can also be defined in an external file. More on External Globals.
persist_globals boolean false Set this to true if you'd like to persist the same globals object between testsuite runs or have a (deep) copy of it per each testsuite.
cli_args object none Same as WebDriver/Selenium settings cli_args. You can override the global cli_args on a per-environment basis.
end_session_on_fail boolean true End the session automatically when the test is being terminated, usually after a failed assertion.
skip_testcases_on_fail boolean true Skip the remaining testcases (or test steps) from the same test suite (i.e. test file), when one testcase fails.
exclude array An array of folders or file patterns to be skipped (relative to the main source folder).
Example:

"exclude" : ["excluded-folder"]
or:
"exclude" : ["test-folder/*-smoke.js"]
filter string Folder or file pattern to be used when loading the tests. Files that don't match this pattern will be ignored.
Example:

"filter" : "tests/*-smoke.js"
log_screenshot_data boolean false Do not show the Base64 image data in the (verbose) log when taking screenshots.
silent boolean true Whether to show extended Selenium command logs.
output boolean true Use to disable terminal output completely.
disable_colors boolean false Use to disable colored output in the terminal.
use_xpath boolean false Use xpath as the default locator strategy
output_folder string|boolean Define the location where the JUnit XML report files will be saved. This will overwrite any value defined in the Basic Settings section. If you'd like to disable the reports completely inside a specific environment, set this to false.
skipgroup
string Skip a group of tests (a subfolder); can be a list of comma-separated values (no space).
skiptags
string Skip tests by tag name; can be a list of comma-separated values (no space)
sync_test_names
boolean true A name property will be added to the desiredCapabilities containing the test suite name when this is enabled. It is useful when using cloud testing services.
detailed_output boolean true By default detailed assertion output is displayed while the test is running. Set this to false if you'd like to only see the test case name displayed and pass/fail status. This is especially useful when running tests in parallel.
selenium_host string localhost The hostname/IP on which the Selenium Server is accepting connections.
selenium_port integer 4444 The port number on which the Selenium Server is accepting connections.

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.

Developer Guide

Writing Tests

Using the preferred CSS selector model to locate elements on a page, Nightwatch makes it very easy to write automated End-to-End tests.

Create a separate folder for tests in your project, e.g.: tests. Each file inside it will be loaded as a test suite by the Nightwatch test runner. Here's a basic test suite example:


module.exports = {
  'Demo test Google' : function (browser) {
    browser
      .url('http://www.google.com')
      .waitForElementVisible('body')
      .setValue('input[type=text]', 'nightwatch')
      .waitForElementVisible('input[name=btnK]')
      .click('input[name=btnK]')
      .pause(1000)
      .assert.containsText('#main', 'Night Watch')
      .end();
  }
};

Remember always to call the .end() method when you want to close your test, in order for the browser session to be properly closed.

A test can have multiple steps, if needed:

module.exports = {
  'step one: navigate to google' : function (browser) {
    browser
      .url('http://www.google.com')
      .waitForElementVisible('body', 1000)
      .setValue('input[type=text]', 'nightwatch')
      .waitForElementVisible('input[name=btnK]', 1000)
  },

  'step two: click input' : function (browser) {
    browser
      .click('input[name=btnK]')
      .pause(1000)
      .assert.containsText('#main', 'Night Watch')
      .end();
  }
};

Tests could also be written in this format:


this.demoTestGoogle = function (browser) {
  browser
    .url('http://www.google.com')
    .waitForElementVisible('body', 1000)
    .setValue('input[type=text]', 'nightwatch')
    .waitForElementVisible('input[name=btnK]', 1000)
    .click('input[name=btnK]')
    .pause(1000)
    .assert.containsText('#main', 'The Night Watch')
    .end();
};

Using XPath selectors

Nightwatch supports xpath selectors also. To switch to xpath instead of css selectors as the locate strategy, in your test call the method useXpath(), as seen in the example below. To switch back to CSS, call useCss().

To always use xpath by default set the property "use_xpath": true in your test settings.


this.demoTestGoogle = function (browser) {
  browser
    .useXpath() // every selector now must be xpath
    .click("//tr[@data-recordid]/span[text()='Search Text']")
    .useCss() // we're back to CSS now
    .setValue('input[type=text]', 'nightwatch')
};

Expect Assertions

The Nightwatch API supports out of the box a BDD-style expect assertion library which greatly improves the flexibility as well as readability of the assertions.

The expect assertions use a subset of the Expect api from the Chai framework and are available for elements only at this point. Here's an example:


module.exports = {
  'Demo test Google' : function (browser) {
    browser
      .url('http://google.no')
      .pause(1000);

    // expect element <body> to be present in 1000ms
    browser.expect.element('body').to.be.present.before(1000);

    // expect element <#lst-ib> to have css property 'display'
    browser.expect.element('#lst-ib').to.have.css('display');

    // expect element <body> to have attribute 'class' which contains text 'vasq'
    browser.expect.element('body').to.have.attribute('class').which.contains('vasq');

    // expect element <#lst-ib> to be an input tag
    browser.expect.element('#lst-ib').to.be.an('input');

    // expect element <#lst-ib> to be visible
    browser.expect.element('#lst-ib').to.be.visible;

    browser.end();
  }
};


The expect interface provides a much more flexible and fluid language for defining assertions, significantly improved over the existing assert interface. The only downside is that it's not possible to chain assertions anymore and at this point custom messages aren't yet supported.


For a complete list of available expect assertions, refer to the API docs.

Using before[Each] and after[Each] hooks

Nightwatch provides the standard before/after and beforeEach/afterEach hooks to be used in the tests.

The before and after will run before and after the execution of the test suite respectively, while beforeEach and afterEach are ran before and after each testcase (test step).

All methods have the Nightwatch instance passed as argument.

Example:


module.exports = {
  before : function(browser) {
    console.log('Setting up...');
  },

  after : function(browser) {
    console.log('Closing down...');
  },

  beforeEach : function(browser) {

  },

  afterEach : function(browser) {

  },

  'step one' : function (browser) {
    browser
     // ...
  },

  'step two' : function (browser) {
    browser
    // ...
      .end();
  }
};

In the example above the sequence of method calls will be as follows: before(), beforeEach(), "step one", afterEach(), beforeEach(), "step two", afterEach(), after().

Asynchronous before[Each] and after[Each]

All the before[Each] and after[Each] methods can also perform asynchronous operations, in which case they will require the callback passed as the second argument.

The done function must be called as the last step when the async operation completes. Not calling it will result in a timeout error.

Example with beforeEach & afterEach:


module.exports = {
  beforeEach: function(browser, done) {
    // performing an async operation
    setTimeout(function() {
      // finished async duties
      done();
    }, 100);
  },

  afterEach: function(browser, done) {
    // performing an async operation
    setTimeout(function() {
      // finished async duties
      done();
    }, 200);
  }
};

Controlling the done invocation timeout

By default the done invocation timeout is set to 10 seconds (2 seconds for unit tests). In some cases this might not be sufficient and to avoid a timeout error, you can increase this timeout by defining an asyncHookTimeout property (in milliseconds) in your external globals file (see below for details on external globals).

For an example, refer to the provided globalsModule example.

Explicitly failing the test

Failing the test intentionally in a test hook can be achieved by calling done with an Error argument:


module.exports = {
  afterEach: function(browser, done) {
    // performing an async operation
    performAsync(function(err) {
      if (err) {
        done(err);
        return;
      }
      // ...
    });
  }
};

External Globals

Most of the time it's more useful to have your globals defined in an external file, specified in the globals_path property, instead of having them defined in nightwatch.json.

You can overwrite globals per environment as needed. Say you have your tests running locally and also against a remote staging server. Most of the times you will need some different setting up.

Global Hooks

The same set of hooks as per test suite is also available globally, outside the scope of the test. See the below example for more details. In the case of global hooks, the beforeEach and afterEach refers to a test suite (i.e. test file), and are ran before and after a test suite.

Global Settings

There are a number of globals which are holding test settings and can control test execution. These are detailed in the provided globalsModule sample.

Example:


module.exports = {
  'default' : {
    isLocal : true,
  },

  'integration' : {
    isLocal : false
  },

  // External before hook is ran at the beginning of the tests run, before creating the Selenium session
  before: function(done) {
    // run this only for the local-env
    if (this.isLocal) {
      // start the local server
      App.startServer(function() {
        // server listening
        done();
      });
    } else {
      done();
    }
  },

  // External after hook is ran at the very end of the tests run, after closing the Selenium session
  after: function(done) {
    // run this only for the local-env
    if (this.isLocal) {
      // start the local server
      App.stopServer(function() {
        // shutting down
        done();
      });
    } else {
      done();
    }
  },

  // This will be run before each test suite is started
  beforeEach: function(browser, done) {
    // getting the session info
    browser.status(function(result) {
      console.log(result.value);
      done();
    });
  },

  // This will be run after each test suite is finished
  afterEach: function(browser, done) {
    console.log(browser.currentTest);
    done();
  }
};

Global Reporter

The global reporter is invoked before calling the built-in junit reporter (or a custom reporter specified using the --reporter CLI option).

Example:


module.exports = {
  reporter : function(results, cb) {
    console.log('results', results);
    cb();
  }
};

Nightwatch Runner

Nightwatch includes a command-line test runner which makes it easy to run tests and generate useful output. Please refer to the Installation section for details on how to get the runner installed. There are a few different options on how to use the test runner, depending on your installation type.

Global

If you have installed Nightwatch globally (with -g option), the binary nightwatch will be available anywhere:

nightwatch [source] [options]

Project specific

If you have Nightwatch installed as a dependency of your project, you can refer the binary from the node_modules/.bin folder:


Linux and MacOSX:
./node_modules/.bin/nightwatch [source] [options]


Windows:

Create a file nightwatch.js and add the following line:

require('nightwatch/bin/runner.js');

Then run as follows:

node nightwatch.js [source] [options]

Tests source

The optional source argument can be either one or more files or an entire folder. This can be located irrespectively of the src_folders setting.


Example - single test:
nightwatch tests/one/firstTest.js


Example - 2 individual tests:
nightwatch tests/one/firstTest.js tests/secondTest.js


Example - 1 individual test and 1 folder:
nightwatch tests/one/test.js tests/utils

Command-line Options

The test runner supports a number of run-time options to be passed to. To view all, run the following:

nightwatch --help
Name Shortname default description
--config -c ./nightwatch.json The location of the nightwatch.json file - the configuration file which the runner uses and which also includes the Selenium WebDriver options.
--output -o tests_output The location where the JUnit XML reports will be saved.
--reporter -r junit Name of a predefined reporter (e.g. junit) or path to a custom reporter file to use.

The custom reporter interface looks like:
module.exports = {
  write(results, options, done) {
    done();
  }
};
--env -e default Which testing environment to use - defined in nightwatch.json
--verbose Shows extended selenium command logging during the session
--version -v Shows the version number
--test -t Runs only the specified test suite/module. By default the runner will attempt to run all tests in the src_folders settings folder(s) and their subfolders.
--testcase Used only together with --test. Runs the specified testcase from the current suite/module.
--group -g Runs only the specified group or several (comma separated) of tests (subfolder). Tests are grouped by being placed in the same subfolder.
--skipgroup -s Skip one or several (comma separated) group of tests.
--filter -f Specify a filter (glob expression) as the file name format to use when loading the test files.
--tag -a Filter test modules by tags. Only tests that have the specified tags will be loaded.
--skiptags Skips tests that have the specified tag or tags (comma separated).
--retries Retries failed or errored testcases up to the specified number of times. Retrying a testcase will also retry the beforeEach and afterEach hooks, if any.
--suiteRetries Retries failed or errored testsuites (test modules) up to the specified number of times. Retrying a testsuite will also retry the before and after hooks (in addition to the global beforeEach and afterEach respectively), if any are defined on the testsuite.

Test Environments

You can define multiple sections (environments) of test settings so you could overwrite specific values per environment.

A "default" environment is required. All the other environments are inheriting from default and can overwrite settings as needed.

An environment inherits all the base settings and all the settings defined under the "default" environment.

{
  ...
  "test_settings" : {
    "default" : {
      "launch_url" : "http://localhost",
      "globals" : {
        "myGlobalVar" : "some value",
        "otherGlobal" : "some other value"
      }
    },

    "integration" : {
      "launch_url" : "http://staging.host",
      "globals" : {
        "myGlobalVar" : "other value"
      }
    }
  }
}

The key of the settings group can be passed then to the runner as the `--env` argument to use the specified settings, like so:
nightwatch --env integration

This can be useful if you need to have different settings for your local machine and the Continuous Integration server.

Test Groups

Nightwatch makes it possible to organize your test scripts into groups and run them as needed. To group tests together just place them in the same sub-folder. The folder name is the name of the group.

Example:

lib/
  ├── selenium-server-standalone.jar
custom-commands/
  ├── loginUser.js
  ├── attachPicture.js
tests/
  ├── logingroup
  |   ├── login_test.js
  |   └── otherlogin_test.js
  ├── addressbook
  |   ├── addressbook_test.js
  |   └── contact_test.js
  ├── chat
  |   ├── chatwindow_test.js
  |   ├── chatmessage_test.js
  |   └── otherchat_test.js
  └── smoketests
      ├── smoke_test.js
      └── othersmoke_test.js

To run only the smoketests group you would do the following:

nightwatch --group smoketests

Also, if you would want to skip running the smoketests group you would do the following:

nightwatch --skipgroup smoketests

To skip multiple groups, just add them as comma-separated:

nightwatch --skipgroup addressbook,chat

Test Tags

You can also selectively target tests to run based on tags, such that a test may be belong to multiple tags. For example, you might have a login test that belongs to a login suite as well as a sanity suite.

The tagging can be accomplished by adding the @tags property to a test module:


module.exports = {
  '@tags': ['login', 'sanity'],
  'demo login test': function (browser) {
     // test code
  }
};

To select which tags to run, use the --tag command line flag:

nightwatch --tag login

Specify multiple tags as:

nightwatch --tag login --tag something_else


To skip running tests with a specific tag, use the --skiptags flag:

nightwatch --skiptags login

Or to skip multiple tags, add each tag you want to skip as comma-separated:

nightwatch --skiptags login,something_else

Disabling Tests

To prevent a test module from running, simply set the disabled attribute in that module to true, like so:


module.exports = {
  '@disabled': true, // This will prevent the test module from running.

  'sample test': function (browser) {
    // test code
  }
};

This can be useful if you don't want to run certain tests that are known to be failing.

Disabling Individual Testcases

Disabling individual testcases isn't currently supported out of the box. However it can be achieved relatively straightforward with a simple work-around. By simply converting the test method to a string, Nightwatch will ignore it.

Here's an example:


module.exports = {
  'sample test': function (browser) {
    // test code
  },

  // disabled
  'other sample test': ''+function (browser) {
    // test code
  }
};

Parallel Running

Nightwatch supports the tests to be run in parallel. This can be achieved either via test workers or by running multiple test environments in parallel.

Via Workers

When this is enabled the test runner will launch a configurable number of child processes and then distribute the loaded tests over to be ran in parallel.

To enable test workers, set the test_workers top-level property, like so:


"test_workers": {
  "enabled": true,
  "workers": "auto"
}

or, simply:


"test_workers": true


The workers option configures how many child processes can run concurrently.

  • "auto" - determined by number of CPUs e.g. 4 CPUs means 4 workers
  • {number} - specifies an exact number of workers

Test concurrency is done at the file level. Each test file will fill a test worker slot. Individual tests/steps in a test file will not run concurrently.

Version 0.9 brings improved support for displaying output when running tests in parallel. We recommend setting detailed_output to false in your test settings for improved output readability.

Multiple Environments

nightwatch -e default,chrome

The above will run two environments named default and chrome in parallel.

Terminal Output

Each environment will be run as a separate child_process and the output will be sent to the main process.

To make the output easier to read, Nightwatch by default buffers the output from each child process and displays everything at the end, grouped by environment.

If you'd like to disable the output buffering and see the output from each child process as it is sent to stdout, simply set the property "live_output" : true on the top level in your nightwatch.json (e.g. after selenium).
You can create a separate environment per browser (by chaining desiredCapabilities) and then run them in parallel. In addition, using the filter and exclude options tests can be split per environment in order to be ran in parallel.

Using Mocha

Starting with version 0.8 Nightwatch is bundled with a custom version of the popular Mocha test runner which allows running tests using Mocha, thus taking advantage of its interfaces and reporters.

Usage

There are two main ways in which you can use Mocha with Nightwatch.

From Nightwatch

Mocha is used as an alternative test runner to the built-in one. This is done by specifying the "test_runner" option in the nightwatch.json configuration file.

Custom options can also be specified for Mocha:


{
  ...
  "test_runner" : {
    "type" : "mocha",
    "options" : {
      "ui" : "bdd",
      "reporter" : "list"
    }
  }
  ...
}

or simply:


{
  ...
  "test_runner" : "mocha"
  ...
}

A complete list of Mocha options that are supported can be found here.

The test_runner option can also be specified at test environment level:


{
  "test_settings" : {
    "mocha_tests" : {
      "test_runner" : {
        "type" : "mocha",
        "options" : {
          "ui" : "tdd",
          "reporter" : "list"
        }
      }
    }
  }
  ...
}

Example

Writing a test in Mocha is the same as writing it in Nightwatch. Each testcase receives the browser object, hooks also receiving a done callback for async operations.


describe('Google demo test for Mocha', function() {

  describe('with Nightwatch', function() {

    before(function(browser, done) {
      done();
    });

    after(function(browser, done) {
      browser.end(function() {
        done();
      });
    });

    afterEach(function(browser, done) {
      done();
    });

    beforeEach(function(browser, done) {
      done();
    });

    it('uses BDD to run the Google simple test', function(browser) {
      browser
        .url('http://google.com')
        .expect.element('body').to.be.present.before(1000);

      browser.setValue('input[type=text]', ['nightwatch', browser.Keys.ENTER])
        .pause(1000)
        .assert.containsText('#main', 'Night Watch');
    });
  });
});

When using the mocha test runner from Nightwatch some cli options are not available, like --retries, --suiteRetries, --reporter.

Using the standard Mocha

Running Nightwatch tests with the standard Mocha it's also possible, though a bit more boilerplate code is involved and you need to manage the selenium server.

Example


var nightwatch = require('nightwatch');

describe('Github', function() {
  var client = nightwatch.initClient({
    silent : true
  });

  var browser = client.api();

  this.timeout(99999999);

  before(function() {

    browser.perform(function() {
      console.log('beforeAll')
    });

  });

  beforeEach(function(done) {
    browser.perform(function() {
      console.log('beforeEach')
    });

    client.start(done);
  });


  it('Demo test GitHub', function (done) {
    browser
      .url('https://github.com/nightwatchjs/nightwatch')
      .waitForElementVisible('body', 5000)
      .assert.title('nightwatchjs/nightwatch · GitHub')
      .waitForElementVisible('body', 1000)
      .assert.visible('.container .breadcrumb a span')
      .assert.containsText('.container .breadcrumb a span', 'nightwatch', 'Checking project title is set to nightwatch');

    client.start(done);
  });

  afterEach(function() {
    browser.perform(function() {
      console.log('afterEach')
    });
  });

  after(function(done) {
    browser.end(function() {
      console.log('afterAll')
    });

    client.start(done);
  });

});

Programmatic API

Since v1.0, Nightwatch exports an API through which it may be used without a configuration file. The runTests() public method which may be used for running the tests inside a custom runner.

The return value is a promise.

Syntax


  Nightwatch.runTests([testSource], [settings]);

Example


  const Nightwatch = require('nightwatch');

  Nightwatch.runTests('/path/to/tests_folder', {
    // various settings
  }).then(function() {
    // Tests finished
  }).catch(function(err) {
    // An error occurred
  });

You can also build your complete custom runner, based on the Nightwatch CLI runner:

Custom Runner Example


  const Nightwatch = require('nightwatch');

  // read the CLI arguments
  Nightwatch.cli(function(argv) {
    argv._source = argv['_'].slice(0);

    // create the Nightwatch CLI runner
    const runner = Nightwatch.CliRunner(argv);

    // setup and run tests
    runner
      .setup()
      .startWebDriver()
      .then(_ => runner.runTests())
      .then(_ => runner.stopWebDriver())
      .catch(err => console.error(err));
  });

Writing Custom Commands

Most of the time you will need to extend the Nightwatch commands to suit your own application needs. Doing that is only a matter of creating a separate folder and defining your own commands inside, each in its own file.

Then specify the path to that folder in the nightwatch.json file, as the custom_commands_path property. The command name is the name of the file itself.

There are two main ways in which you can define a custom command:

1) Function-style commands

This is the simplest form in which commands are defined, however they are also quite limited.

The command module needs to export a command function, which needs to call at least one Nightwatch api method (such as .execute()). This is due to a limitation of how the asynchronous queueing system of commands works. You can also wrap everything in a .perform() call. Client commands like execute and perform are available via this.


exports.command = function(file, callback) {
  var self = this;
  var imageData;
  var fs = require('fs');

  try {
    var originalData = fs.readFileSync(file);
    var base64Image = new Buffer(originalData, 'binary').toString('base64');
    imageData = 'data:image/jpeg;base64,' + base64Image;
  } catch (err) {
    console.log(err);
    throw "Unable to open file: " + file;
  }

  this.execute(
    function(data) { // execute application specific code
      App.resizePicture(data);
      return true;
    },

    [imageData], // arguments array to be passed

    function(result) {
      if (typeof callback === "function") {
        callback.call(self, result);
      }
    }
  );

  return this;
};

The example above defines a command (e.g. resizePicture.js) which loads an image file as data-URI and calls a method named resizePicture (via .execute()), defined inside the application.

With this command, the test will look something like:


module.exports = {
  "testing resize picture" : function (browser) {
    browser
      .url("http://app.host")
      .waitForElementVisible("body")
      .resizePicture("/var/www/pics/moon.jpg")
      .assert.element(".container .picture-large")
      .end();
  }
};

2) Class-style commands

This is how most of the Nightwatch's own commands are written. Your command module needs to export a class constructor with a command instance method representing the command function. Commands written like this should inherit from EventEmitter and manually signal the complete event, to indicate command completion.

Class-based command methods are run in the context (the value of this) of the class instance. The browser object is available as this.api.

The example below is the .pause() command, written as an ES6 class:


const EventEmitter = require('events');

class Pause extends EventEmitter {
  command(ms, cb) {
    // If we don't pass the milliseconds, the client will
    // be suspended indefinitely
    if (!ms) {
      return this;
    }

    setTimeout(() => {
      // if we have a callback, call it right before the complete event
      if (cb) {
        cb.call(this.api);
      }

      this.emit('complete');
    }, ms);

    return this;
  }
} 

module.exports = Pause;


The "complete" event

Signaling the complete event needs to be done inside an asynchronous action (e.g. a setTimeout call). Command classes that do not extend EventEmitter will be treated similar to command functions, requiring that the command method calls at least one Nightwatch api method to be able to complete.

Writing Custom Assertions

Nightwatch allows you to even define your own assertions, extending the available .assert and .verify namespaces.

Assertions implement a simple interface which is shared between built-in assertions and custom ones:


exports.assertion = function() {

  /**
   * The message which will be used in the test output and
   * inside the XML reports
   * @type {string}
   */
  this.message;

  /**
   * A value to perform the assertion on. If a function is
   * defined, its result will be used.
   * @type {function|*}
   */
  this.expected;

  /**
   * The method which performs the actual assertion. It is
   * called with the result of the value method as the argument.
   * @type {function}
   */
  this.pass = function(value) {

  };

  /**
   * The method which returns the value to be used on the
   * assertion. It is called with the result of the command's
   * callback as argument.
   * @type {function}
   */
  this.value = function(result) {

  };

  /**
   * Performs a protocol command/action and its result is
   * passed to the value method via the callback argument.
   * @type {function}
   */
  this.command = function(callback) {

    return this;
  };

};

Custom assertions also inherit from EventEmitter. To see some examples, check the assertions module on Github:
/nightwatch/tree/master/lib/selenium/assertions

Custom Reporter

If you'd like to define your own reporter in addition to the built-in ones (stdout and junit-xml) you can do so in two ways:

The --reporter command-line argument

Interface:

module.exports = {
  write : function(results, options, done) {
    done();
  }
};

The reporter method in your external globals file.

See the provided globalsModule.js for an example.

Example:


module.exports = {
  reporter : function(results, done) {
    console.log(results);
    done();
  }
};

Using Page Objects

The Page Objects methodology is a popular pattern to write end-to-end tests by wrapping the pages or page fragments of a web app into objects. The purpose of a page object is to allow a software client to do anything and see anything that a human can by abstracting away the underlying html actions needed to access and manipulate the page.

A comprehensive introduction to Page Objects can be found in this article.

As of version 1.0 Nightwatch does not support legacy page objects written prior to version 0.7.

Configuring Page Objects

To create a page object simply create an object with properties that describe the page. Each page object should be located in a separate file, located in a designated folder. Nightwatch reads the page objects from the folder (or folders) specified in the page_objects_path configuration property.

The page_objects_path property can also be an array of folders, allowing you thus to logically split the page objects into smaller groups.

The Url property

You can optionally add a url property that designates the page's URL. To navigate to the page, you can call the navigate method on the page object.

The URL will usually be defined as a string:


module.exports = {
  url: 'http://google.com',
  elements: {}
};

It can also be a function in case the URL is dynamic. One use case for this is to support different test environments. You can create a function that gets called in the context of the page, thus allowing you to do:


module.exports = {
  url: function() { 
    return this.api.launchUrl + '/login'; 
  },
  elements: {}
};

Defining Elements

Most of the time, you will want to define elements on your page that your tests will interact with through commands and assertions. This is made simple using the elements property so that all your elements are defined in a single place. Especially in larger integration tests, using elements will go a long way to keep test code DRY.

Switching between css and xpath locate strategies is handled internally so you don't need to call useXpath and useCss in your tests. The default locateStrategy is css but you can also specify xpath:


module.exports = {
  elements: {
    searchBar: {
      selector: 'input[type=text]'
    },
    submit: {
      selector: '//[@name="q"]',
      locateStrategy: 'xpath'
    }
  }
};


Or if you're creating elements with the same locate strategy as is default, you can use the shorthand:


module.exports = {
  elements: {
    searchBar: 'input[type=text]'
  }
};


Using the elements property allows you to refer to the element by its name with an "@" prefix, rather than selector, when calling element commands and assertions (click, etc).

Optionally, you can define an array of objects:


var sharedElements = {
  mailLink: 'a[href*="mail.google.com"]'
};

module.exports = {
  elements: [
    sharedElements,
    { searchBar: 'input[type=text]' }
  ]
};


Putting elements and url together, say you have the following defined above saved as a google.js file:


module.exports = {
  url: 'http://google.com',
  elements: {
    searchBar: {
      selector: 'input[type=text]'
    },
    submit: {
      selector: '//[@name="q"]',
      locateStrategy: 'xpath'
    }
  }
};


In your tests you will use it as follows:


module.exports = {
  'Test': function (browser) {
    var google = browser.page.google();

    google.navigate()
      .assert.title('Google')
      .assert.visible('@searchBar')
      .setValue('@searchBar', 'nightwatch')
      .click('@submit');

    browser.end();
  }
};

Using the Element index Property

The index is used to target a specific element in a query that results in multiple elements returned. Normally, only the first element is used (index = 0) but using the index property, you can specify any element within the result.

Say in the example above, the searchBar element selector returns 3 elements and you are interested in the second element.


module.exports = {
  elements: {
    searchBar: {
      selector: 'input[type=text]',
      index: 2
    }
  }
};

You can also override what the page element defined by specifying the element as an object selectors in commands, which can also receive the index:


module.exports = {
  'Test': function (browser) {
    var google = browser.page.google();

    google
      .navigate()
      .assert.title('Google');

    google.waitForElementVisible('@searchBar') // 2nd input element
    google.waitForElementVisible({selector:'@searchBar', index:1}, function(result){}); // 1st div

    google.click('@submit');

    browser.end();
  }
};

Defining Sections

Sometimes it is useful to define sections of a page. Sections do 2 things:

  • Provide a level of namespacing under the page
  • Provide element-level nesting so that any element defined within a section is a descendant of its parent section in the DOM

You can create sections using the sections property:


module.exports = {
  sections: {
    menu: {
      selector: '#gb',
      elements: {
        mail: {
          selector: 'a[href="mail"]'
        },
        images: {
          selector: 'a[href="imghp"]'
        }
      }
    }
  }
};


Your tests would use it as follows:


module.exports = {
  'Test': function (browser) {
    var google = browser.page.google();
    google.expect.section('@menu').to.be.visible;

    var menuSection = google.section.menu;
    menuSection.expect.element('@mail').to.be.visible;
    menuSection.expect.element('@images').to.be.visible;

    menuSection.click('@mail');

    browser.end();
  }
};


Note that every command and assertion on a section (other than expect assertions) returns that section for chaining. If desired, you can nest sections under other sections for complex DOM structures.

Example of nesting page object sections:


module.exports = {
  sections: {
    menu: {
      selector: '#gb',
      elements: {
        mail: {
          selector: 'a[href="mail"]'
        },
        images: {
          selector: 'a[href="imghp"]'
        }
      },
      sections: {
        apps: {
          selector: 'div.gb_pc',
          elements: {
            myAccount: {
              selector: '#gb192'
            },
            googlePlus: {
              selector: '#gb119'
            }
          }
        }
      }
    }
  }
};


Using a nested section in your test is straightforward:


module.exports = {
  'Test': function (browser) {
    var google = browser.page.google();
    google.expect.section('@menu').to.be.visible;

    var menuSection = google.section.menu;
    var appSection = menuSection.section.apps;
    menuSection.click('@appSection');

    appSection.expect.element('@myAccount').to.be.visible;
    appSection.expect.element('@googlePlus').to.be.visible;

    browser.end();
  }
};

Writing Commands

You can add commands to your page object using the commands property. This is a useful way to encapsulate logic about the page that would otherwise live in a test, or multiple tests.

Nightwatch will call the command on the context of the page or section. Client commands like pause are available via this.api. For chaining, each function should return the page object or section.

In this case, a command is used to encapsulate logic for clicking the submit button:


var googleCommands = {
  submit: function() {
    this.api.pause(1000);
    return this.waitForElementVisible('@submitButton', 1000)
      .click('@submitButton')
      .waitForElementNotPresent('@submitButton');
  }
};

module.exports = {
  commands: [googleCommands],
  elements: {
    searchBar: {
      selector: 'input[type=text]'
    },
    submitButton: {
      selector: 'input[name=btnK]'
    }
  }
};


Then the test is simply:


module.exports = {
  'Test': function (browser) {
    var google = browser.page.google();
    google.setValue('@searchBar', 'nightwatch')
      .submit();

    browser.end();
  }
};

Writing Unit Tests

Unit testing in Nightwatch has been refined in version 0.9. Unit tests now written in Nightwatch are also fully compatible with Mocha's Exports interface, so you can use either test runners.

Unit Tests Mode

Nightwatch automatically attempts to connect to the WebDriver server and create a session. When running unit tests this needs to be disabled and the runner needs to be made aware that it is operating in unit testing mode.

This can be done in two ways:

Setting unit_tests_mode=true

This is a global option. Set the unit_tests_mode option to true in the nightwatch.json:

{
  "src_folders" : ["tests"],

  "unit_tests_mode": true
}

Adding @unitTest property per test

You can set the @unitTest property to true if you'd like to have individual test suites as unit tests.


const assert = require('assert');

module.exports = {
  '@unitTest' : true,

  'demo UnitTest' : function (done) {
    assert.equal('TEST', 'TEST');
    setTimeout(function() {
      done();
    }, 10);
  }
};

Assertion framework

Starting with 0.9, in the improved support for unit tests, the browser object is no longer passed as an argument to the test. The only argument passed now is the done callback to be used for asynchronous tests.

You can use whatever assertion framework you like. Chai.js is quite a good one and very flexible.

Example

Here's a subset of the unit test for the utils.js Nightwatch module:


var assert = require('assert');
var common = require('../../common.js');
var Utils = common.require('util/utils.js');

module.exports = {
  'test Utils' : {
    testFormatElapsedTime : function() {

      var resultMs = Utils.formatElapsedTime(999);
      assert.equal(resultMs, '999ms');

      var resultSec = Utils.formatElapsedTime(1999);
      assert.equal(resultSec, '1.999s');

      var resultMin = Utils.formatElapsedTime(122299, true);
      assert.equal(resultMin, '2m 2s / 122299ms');
    },

    testMakeFnAsync : function() {
      function asyncFn(cb) {
        cb();
      }

      function syncFn() {}

      var convertedFn = Utils.makeFnAsync(1, syncFn);
      var called = false;
      convertedFn(function() {
        called = true;
      });

      assert.equal(Utils.makeFnAsync(1, asyncFn), asyncFn);
      assert.ok(called);
    }
  }
};

Asynchronous Unit Tests

The argument to the test function is the optional done callback which signals the test is complete. If present, the callback must be called when the async operation finishes.

Example

Here's unit test which checks if Nightwatch throws an error if you don't invoke the done callback within a set time (10 ms).


module.exports = {
  const assert = require('assert');

  module.exports = {
    'demo UnitTest' : function (done) {
      assert.equal('TEST', 'TEST');

      setTimeout(function() {
done(); }, 10); } }; };

Using a Combined Configuration

Below it's an example of how you can combine end-to-end tests and unit tests in the same nightwatch.json configuration file. Notice the usage of exclude and filter properties.

An empty exclude means we want to reset its value and rely only on filter.

{
  "src_folders" : ["./examples/tests", "./examples/unittests"],
  "output_folder" : "./examples/reports",


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

  "test_settings" : {
    "default" : {
      "launch_url" : "http://localhost",
      "desiredCapabilities": {
        "browserName": "chrome"
      },
      "exclude" : "./examples/unittests/*"
    },

    "unittests" : {
      "unit_tests_mode" : true,
      "filter" : "./examples/unittests/*",
      "exclude" : ""
    }
  }
}

Code Coverage

At the moment, Nightwatch doesn't provide a coverage reporter but it is something that's being planned for a future release. In the meantime you can write a custom reporter which will output coverage data. See the custom reporter section for details and the Mocha HTMLCov reporter for how the reporter should look like.

3rd party coverage service

There are some hosted services which provide the reporting and metrics for you in a modern web interface. These services will typically require coverage data in LCOV format. Nightwatch uses coveralls.io.

For details on how an LCOV reporter should look like and how to integrate with your project, you can check out the mocha-lcov-reporter.

API Reference


Nightwatch provides a fluent BDD-style interface for performing assertions on elements, defined on the expect namespace on the main Nightwatch instance. It is based on the Chai Expect assertion library and provides a greater level of flexibility, also adding new capabilities over the classic assert interface.

It uses a chain-able language to construct assertions given an element specified by a css/xpath selector. A simple example looks like the following:


this.demoTest = function (browser) {
  // start with identifying the element
  // and then assert the element is present
  browser.expect.element('#main').to.be.present;

  // or assert the element is visible
  browser.expect.element('#main').to.be.visible;
};

Language Chains

The following are provided as chainable getters to improve the readability of your assertions. They do not provide testing capabilities and the order is not important.

  • to
  • be
  • been
  • is
  • that
  • which
  • and
  • has
  • have
  • with
  • at
  • does
  • of

.equal(value)/.contain(value)/.match(regex)

These methods will perform assertions on the specified target on the current element. The targets can be an attribute value, the element's inner text and a css property.


this.demoTest = function (browser) {
  browser.expect.element('#main').text.to.equal('The Night Watch');

  browser.expect.element('#main').text.to.contain('The Night Watch');

  browser.expect.element('#main').to.have.css('display').which.equals('block');
};

.startsWith(value)/.endsWith(value)

Same as `equal`/`contain`/`match`.


this.demoTest = function (browser) {
  browser.expect.element('#main').text.to.endWith('Watch');

  browser.expect.element('#main').text.to.startWith('The');
};

.not

Negates any of assertions following in the chain.


this.demoTest = function (browser) {
  browser.expect.element('#main').text.to.not.equal('The Night Watch');

  browser.expect.element('#main').text.to.not.contain('The Night Watch');

  browser.expect.element('#main').to.have.css('display').which.does.not.equal('block');
};

.before(ms)/.after(ms)

These methods perform the same thing which is essentially retrying the assertion for the given amount of time (in milliseconds). before or after can be chained to any assertion and thus adding retry capability.

You can change the polling interval by defining a waitForConditionPollInterval property (in milliseconds) as a global property in your nightwatch.json or in your external globals file. Similarly, a default timeout can be specified as a global waitForConditionTimeout property (in milliseconds).


this.demoTest = function (browser) {
  browser.expect.element('#main').text.to.contain('The Night Watch').before(1000);

  browser.expect.element('#main').text.to.not.contain('The Night Watch').after(500);
};

.a(type)

Checks if the type (i.e. tag name) of a specified element is of an expected value.

Parameters:
Name Type description
type string

The expected type

message
Optional
string

Optional log message to display in the output. If missing, one is displayed by default.

Usage:

this.demoTest = function (browser) {
  browser.expect.element('#q').to.be.an('input');
  browser.expect.element('#q').to.be.an('input', 'Testing if #q is an input');
  browser.expect.element('#w').to.be.a('span');
}

.attribute(name)

Checks if a given attribute of an element exists and optionally if it has the expected value.

Parameters:
Name Type description
attribute string

The attribute name

message
Optional
string

Optional log message to display in the output. If missing, one is displayed by default.

Usage:

this.demoTest = function (browser) {
  browser.expect.element('body').to.have.attribute('data-attr');
  browser.expect.element('body').to.not.have.attribute('data-attr');
  browser.expect.element('body').to.not.have.attribute('data-attr', 'Testing if body does not have data-attr');
  browser.expect.element('body').to.have.attribute('data-attr').before(100);
  browser.expect.element('body').to.have.attribute('data-attr')
    .equals('some attribute');
  browser.expect.element('body').to.have.attribute('data-attr')
    .not.equals('other attribute');
  browser.expect.element('body').to.have.attribute('data-attr')
    .which.contains('something');
  browser.expect.element('body').to.have.attribute('data-attr')
    .which.matches(/^something\ else/);
};

.css(property)

Checks a given css property of an element exists and optionally if it has the expected value.

Parameters:
Name Type description
property string

The css property name

message
Optional
string

Optional log message to display in the output. If missing, one is displayed by default.*

Usage:

this.demoTest = function (browser) {
  browser.expect.element('#main').to.have.css('display');
  browser.expect.element('#main').to.have.css('display', 'Testing for display');
  browser.expect.element('#main').to.not.have.css('display');
  browser.expect.element('#main').to.have.css('display').before(100);
  browser.expect.element('#main').to.have.css('display').which.equals('block');
  browser.expect.element('#main').to.have.css('display').which.contains('some value');
  browser.expect.element('#main').to.have.css('display').which.matches(/some\ value/);
};

.enabled

Property that checks if an element is currently enabled.

Usage:

this.demoTest = function (browser) {
  browser.expect.element('#weblogin').to.be.enabled;
  browser.expect.element('#main').to.not.be.enabled;
  browser.expect.element('#main').to.be.enabled.before(100);
};

.present

Property that checks if an element is present in the DOM.

Usage:

this.demoTest = function (browser) {
  browser.expect.element('#main').to.be.present;
  browser.expect.element('#main').to.not.be.present;
  browser.expect.element('#main').to.be.present.before(100);
};

.selected

Property that checks if an OPTION element, or an INPUT element of type checkbox or radio button is currently selected.

Usage:

this.demoTest = function (browser) {
  browser.expect.element('#main').to.be.selected;
  browser.expect.element('#main').to.not.be.selected;
  browser.expect.element('#main').to.be.selected.before(100);
};

.text

Property that retrieves the text contained by an element. Can be chained to check if contains/equals/matches the specified text or regex.

Usage:

this.demoTest = function (browser) {
  browser.expect.element('#main').text.to.equal('The Night Watch');
  browser.expect.element('#main').text.to.not.equal('The Night Watch');
  browser.expect.element('#main').text.to.equal('The Night Watch').before(100);
  browser.expect.element('#main').text.to.contain('The Night Watch');
  browser.expect.element('#main').text.to.match(/The\ Night\ Watch/);
};

.value

Property that retrieves the value (i.e. the value attributed) of an element. Can be chained to check if contains/equals/matches the specified text or regex.

Usage:

this.demoTest = function (browser) {
  browser.expect.element('#q').to.have.value.that.equals('search');
  browser.expect.element('#q').to.have.value.not.equals('search');
  browser.expect.element('#q').to.have.value.which.contains('search');
  browser.expect.element('#q').to.have.value.which.matches(/search/);
};

.visible

Property that asserts the visibility of a specified element.

Usage:

this.demoTest = function (browser) {
  browser.expect.element('#main').to.be.visible;
  browser.expect.element('#main').to.not.be.visible;
  browser.expect.element('#main').to.be.visible.before(100);
};

The classic assert/verify library is still available on the Nightwatch instance as two objects containing the same methods to perform assertions on elements:

  • .assert - when an assertion fails, the test ends, skipping all other assertions.
  • .verify - when an assertion fails, the test logs the failure and continues with other assertions.

This will end the test:

client.assert.visible('.non_existing');

But this will just log the failure and continue:

client.verify.visible(".non_existing");

Node.js Assert Module

Nightwatch.js extends Node.js assert module, so you can also use any of the available methods there in your tests.

Automatically retrying failed assertions

You can tell Nightwatch to automatically retry failed assertions until a given timeout is reached, before the test runner gives up and fails the test. This can be accomplished by setting the property retryAssertionTimeout (in milliseconds) in the globals file.

For example: retryAssertionTimeout = 2000

.attributeContains()

Checks if the given attribute of an element contains the expected value.

Parameters:
Name Type description
selector string The selector (CSS / Xpath) used to locate the element.
attribute string The attribute name
expected string The expected contained value of the attribute to check.
message
Optional
string Optional log message to display in the output. If missing, one is displayed by default.
Usage:

this.demoTest = function (browser) {

  browser.assert.attributeContains('#someElement', 'href', 'google.com');

};

.attributeEquals()

Checks if the given attribute of an element has the expected value.

Parameters:
Name Type description
cssSelector string The CSS selector used to locate the element.
attribute string The attribute name
expected string The expected value of the attribute to check.
msg
Optional
string Optional log message to display in the output. If missing, one is displayed by default.
Usage:

this.demoTest = function (browser) {

  browser.assert.attributeEquals("body", "data-attr", "some value");

};

.containsText()

Checks if the given element contains the specified text.

Parameters:
Name Type description
cssSelector string The CSS selector used to locate the element.
expectedText string The text to look for.
msg
Optional
string Optional log message to display in the output. If missing, one is displayed by default.
Usage:

this.demoTest = function (browser) {

  browser.assert.containsText("#main", "The Night Watch");

};

.cssClassPresent()

Checks if the given element has the specified CSS class.

Parameters:
Name Type description
cssSelector string The CSS selector used to locate the element.
className string The CSS class to look for.
msg
Optional
string Optional log message to display in the output. If missing, one is displayed by default.
Usage:

this.demoTest = function (browser) {

  browser.assert.cssClassPresent("#main", "container");

};

.cssClassNotPresent()

Checks if the given element does not have the specified CSS class.

Parameters:
Name Type description
cssSelector string The CSS selector used to locate the element.
className string The CSS class to look for.
msg
Optional
string Optional log message to display in the output. If missing, one is displayed by default.
Usage:

this.demoTest = function (browser) {

  browser.assert.cssClassNotPresent("#main", "container");

};

.cssProperty()

Checks if the specified css property of a given element has the expected value.

Parameters:
Name Type description
cssSelector string The CSS selector used to locate the element.
cssProperty string The CSS property.
expected string|number The expected value of the css property to check.
msg
Optional
string Optional log message to display in the output. If missing, one is displayed by default.
Usage:

this.demoTest = function (browser) {

  browser.assert.cssProperty("#main", "display", "block");

};

.elementPresent()

Checks if the given element exists in the DOM.

Parameters:
Name Type description
cssSelector string The CSS selector used to locate the element.
msg
Optional
string Optional log message to display in the output. If missing, one is displayed by default.
Usage:

this.demoTest = function (browser) {

  browser.assert.elementPresent("#main");

};

.elementNotPresent()

Checks if the given element does not exist in the DOM.

Parameters:
Name Type description
cssSelector string The CSS selector used to locate the element.
msg
Optional
string Optional log message to display in the output. If missing, one is displayed by default.
Usage:

this.demoTest = function (browser) {

  browser.assert.elementNotPresent(".should_not_exist");

};

.hidden()

Checks if the given element is not visible on the page.

Parameters:
Name Type description
cssSelector string The CSS selector used to locate the element.
msg
Optional
string Optional log message to display in the output. If missing, one is displayed by default.
Usage:

this.demoTest = function (browser) {

  browser.assert.hidden(".should_not_be_visible");

};

.title()

Checks if the page title equals the given value.

Parameters:
Name Type description
expected string The expected page title.
msg
Optional
string Optional log message to display in the output. If missing, one is displayed by default.
Usage:

this.demoTest = function (browser) {

  browser.assert.title("Nightwatch.js");

};

.urlContains()

Checks if the current URL contains the given value.

Parameters:
Name Type description
expectedText string The value expected to exist within the current URL.
msg
Optional
string Optional log message to display in the output. If missing, one is displayed by default.
Usage:

this.demoTest = function (browser) {

  browser.assert.urlContains('google');

};

.urlEquals()

Checks if the current url equals the given value.

Parameters:
Name Type description
expected string The expected url.
msg
Optional
string Optional log message to display in the output. If missing, one is displayed by default.
Usage:

this.demoTest = function (browser) {

  browser.assert.urlEquals('http://www.google.com');

};

.value()

Checks if the given form element's value equals the expected value.

Parameters:
Name Type description
cssSelector string The CSS selector used to locate the element.
expectedText string The expected text.
msg
Optional
string Optional log message to display in the output. If missing, one is displayed by default.
Usage:

this.demoTest = function (browser) {

  browser.assert.value("form.login input[type=text]", "username");

};

.valueContains()

Checks if the given form element's value contains the expected value.

Parameters:
Name Type description
cssSelector string The CSS selector used to locate the element.
expectedText string The expected text.
msg
Optional
string Optional log message to display in the output. If missing, one is displayed by default.
Usage:

this.demoTest = function (browser) {

  browser.assert.valueContains("form.login input[type=text]", "username");

};

.visible()

Checks if the given element is visible on the page.

Parameters:
Name Type description
cssSelector string The CSS selector used to locate the element.
msg
Optional
string Optional log message to display in the output. If missing, one is displayed by default.
Usage:

this.demoTest = function (browser) {

  browser.assert.visible(".should_be_visible");

};

Page objects provide an additional layer of abstraction for test case creation. Page objects are defined in modules and parsed into factory functions that create page object instances. These factories are accessible through the page reference within the command API (accessible through the browser object) using the name of the module that defines them.

Example:

module.exports = {
  // can be string or function
  url: function () {
    return this.api.launchUrl;
  },

  elements: {
    // shorthand, specifies selector
    mySubmitButton: 'input[type=submit]'

    // full
    myTextInput: {
      selector: 'input[type=text]',
      locateStrategy: 'css selector'
    }
  },

  commands: [
    {
      myCustomPause: function () {
        this.api.pause(this.props.myPauseTime);
      }
    }
  ],

  // object version (best considered immutable)
  props: {
    myPauseTime: 1000
  },

  sections: {

    myFooterSection: {

      selector: '#my-footer',
      locateStrategy: 'css selector',

      elements: {
        myLogo: {
          selector: '.my-logo',
          locateStrategy: 'css selector'
        }
      },

      commands: [
        {
          myMoveToLogo: function () {
            this.moveToElement('@myLogo', this.props.myLogoX, this.props.myLogoY);
          }
        }
      ],

      // function version (recommended)
      props: function () {
        return {
          myLogoX: 10,
          myLogoY: 10
        };
      },

      sections: {
        // additional, nested sections
      }
    }
  }
};

Page Object Module

Name Type description
commands Array A list of objects containing functions to represent methods added to the page object instance.
elements Object|Array An object, or array of objects, of named element definitions to be used as element selectors within element commands called from the page object.
props Object|Function An object or a function returning an object representing a container for user variables. Props objects are copied directly into the props property of the page object instance.
sections Object An object of named sections definitions defining the sections within the page object.
url String|Function A url or function returning a url to be used in a url() command when the page's navigate() method is called.

Page Object Instance

Page object module definitions are used to define page object instances when their respective factory functions within the page reference of the standard command API is called.

const myPageObject = browser.page.MyPage(); // defined in MyPage.js module

Every time a factory function like MyPage above is called, a new instance of the page object is created.

Properties

Name Type description
api Object A reference providing access to the full Nightwatch command API, usually known as browser in test cases. This is used to access those commands that are not part of the subset of commands within the page object API.
elements Object A map of Element objects used by element selectors.
name string The name of the page object as defined by its module name (not including the extension). This is the same name used to access the page object factory from the page reference in the command API.
props Object A reference to props object assigned from the module definition.

Note: this will be the same props object for all instances of the page object if defined as an object instance within the page object module. If you wish for each props object to be unique, define props in the module as a function that would return a new props object for each new page object instance.
section Object A map of Sections objects defined for the page object. This will only contain sections within the page object module's root sections definition. Nested sections are accessible through their parent section's own section reference.
url string|Function The url value from the page object module, either a string or a function depending on how it was defined there.

Methods

Navigates to the resolved url defined for the page object using the command API's url() command. This command is generally used in place of the command API's url() when working with page objects because the url member of the page object is the user-defined url string or function and not the call used to navigate to a url.

Element Instances

Element instances encapsulate the definition used to handle element selectors. Generally you won't need to access them directly, instead referring to them using their @-prefixed names for selector arguments, but they are available through a page object or section's elements property.

Section Instances

Page object section instances are accessed from the section property of a page object instance (note that this is the singular version of "section" whereas the plural version, "sections", was used in the module definition). Sections are created automatically through the page object factory and are available directly as properties from the section reference.


const myPageObject = browser.page.MyPage();
const mySection = myPageObject.section.MySection; // from a `sections: {}` block in page object
        

Page Object Commands

All the Nightwatch command and assertions API is inherited by page objects.

Custom Commands

Name Type description
commands Array A list of objects containing functions to represent methods added to the page object instance.

Page object commands considerations:

  • Access: Page object commands are defined within page object modules. They can be in the module root object within the commands list or within section definitions (also in a commands), but only exist for the definition they're within.

    Page object commands in the module root commands are not available in child sections and section commands are not available in parent sections or the root page object.
  • Context: Page object command context (the value of this) is the page object (for sections its the section object).
  • Execution: Page object commands are not called from within the command queue. Code in a page object command is executed immediately when the function is called.
  • Chaining: Page object commands must return a value for chaining. This can be anything, but it's recommended you stick to this to allow your commands to be chained in the context of the page object instance.

Nightwatch provides the basic WebDriver protocol mappings and also various composite commands to ensure a more fluent and convenient syntax for writing tests.

  • composite commands - such as getValue or isVisible, usually incorporate two or more WebDriver protocol commands
  • protocol commands - are most of the times simple mappings to the W3C WebDriver protocol or, in some cases, its predecessor - the Selenium JsonWireProtocol protocol.

Some of them are basic commands (such as url and execute) and others are internal commands being used by Nightwatch commands and assertions.

The callback function

Each method below allows an callback argument to be passed as the last argument. The callback function will then be called after the command is completed with the main API (browser) as the context and the response object as argument.


this.demoTest = function (browser) {

  browser.click("#main ul li a.first", function(response) {
    this.assert.ok(browser === this, "Check if the context is right.");
    this.assert.ok(typeof response == "object", "We got a response object.");
  });

};

Finding Elements

The commands listed below allow lookup of individual elements and collections of elements. Element retrieval searches are performed using a provided selector, in usually a CSS selector or, less often, an Xpath selector.

The convenience commands, such as .waitForElementVisible() can take a default locator strategy. More info on locator strategy can be found on the WebDriver page.

Each element has an associated web element reference (a UUID) that uniquely identifies the element across all browsing contexts.

.waitForElementVisible()

Waits a given time in milliseconds for an element to be visible in the page before performing any other commands or assertions.

If the element fails to be present and visible in the specified amount of time, the test fails. You can change this by setting abortOnFailure to false.

You can change the polling interval by defining a waitForConditionPollInterval property (in milliseconds) in as a global property in your nightwatch.json or in your external globals file.

Similarly, a default timeout can be specified as a global waitForConditionTimeout property (in milliseconds).

Parameters:
Name Type description
selector string

The selector (CSS / Xpath) used to locate the element.

time=waitForConditionTimeout
Optional
number

The total number of milliseconds to wait before failing.

poll=waitForConditionPollInterval
Optional
number

The number of milliseconds to wait between checks. You can use this only if you also specify the time parameter.

abortOnFailure=abortOnAssertionFailure
Optional
boolean

By the default if the element is not found the test will fail. Set this to false if you wish for the test to continue even if the assertion fails. To set this globally you can define a property abortOnAssertionFailure in your globals.

callback
Optional
function

Optional callback function to be called when the command finishes.

message
Optional
string

Optional message to be shown in the output; the message supports two placeholders: %s for current selector and %d for the time (e.g. Element %s was not in the page for %d ms).

Usage:

this.demoTest = function (browser) {
  browser.waitForElementVisible('body', 1000);
  // continue if failed
  browser.waitForElementVisible('body', 1000, false);
  // with callback
  browser.waitForElementVisible('body', 1000, function() {
    // do something while we're here
  });
  // custom Spanish message
  browser.waitForElementVisible('body', 1000, 'elemento %s no era visible en %d ms');
  // many combinations possible - the message is always the last argument
  browser.waitForElementVisible('body', 1000, false, function() {}, 'elemento %s no era visible en %d ms');
};

.waitForElementNotVisible()

Opposite of waitForElementVisible. Waits a given time in milliseconds for an element to be not visible (i.e. hidden but existing) in the page before performing any other commands or assertions.

If the element fails to be hidden in the specified amount of time, the test fails.

You can change the polling interval by defining a waitForConditionPollInterval property (in milliseconds) in as a global property in your nightwatch.json or in your external globals file.

Similarly, a default timeout can be specified as a global waitForConditionTimeout property (in milliseconds).

Parameters:
Name Type description
selector string

The selector (CSS / Xpath) used to locate the element.

time=waitForConditionTimeout
Optional
number

The total number of milliseconds to wait before failing.

poll=waitForConditionPollInterval
Optional
number

The number of milliseconds to wait between checks. You can use this only if you also specify the time parameter.

abortOnFailure=abortOnAssertionFailure
Optional
boolean

By the default if the element is not found the test will fail. Set this to false if you wish for the test to continue even if the assertion fails. To set this globally you can define a property abortOnAssertionFailure in your globals.

callback
Optional
function

Optional callback function to be called when the command finishes.

message
Optional
string

Optional message to be shown in the output; the message supports two placeholders: %s for current selector and %d for the time (e.g. Element %s was not in the page for %d ms).

Usage:

this.demoTest = function (browser) {
  browser.waitForElementNotVisible('#dialog', 1000);
};

.waitForElementPresent()

Waits a given time in milliseconds for an element to be present in the page before performing any other commands or assertions.

If the element fails to be present in the specified amount of time, the test fails. You can change this by setting abortOnFailure to false.

You can change the polling interval by defining a waitForConditionPollInterval property (in milliseconds) in as a global property in your nightwatch.json or in your external globals file.

Similarly, a default timeout can be specified as a global waitForConditionTimeout property (in milliseconds).

Parameters:
Name Type description
selector string

The selector (CSS / Xpath) used to locate the element.

time=waitForConditionTimeout
Optional
number

The total number of milliseconds to wait before failing.

poll=waitForConditionPollInterval
Optional
number

The number of milliseconds to wait between checks. You can use this only if you also specify the time parameter.

abortOnFailure=abortOnAssertionFailure
Optional
boolean

By the default if the element is not found the test will fail. Set this to false if you wish for the test to continue even if the assertion fails. To set this globally you can define a property abortOnAssertionFailure in your globals.

callback
Optional
function

Optional callback function to be called when the command finishes.

message
Optional
string

Optional message to be shown in the output; the message supports two placeholders: %s for current selector and %d for the time (e.g. Element %s was not in the page for %d ms).

Usage:

this.demoTest = function (browser) {
  browser.waitForElementPresent('body', 1000);
  // continue if failed
  browser.waitForElementPresent('body', 1000, false);
  // with callback
  browser.waitForElementPresent('body', 1000, function() {
    // do something while we're here
  });
  // custom Spanish message
  browser.waitForElementPresent('body', 1000, 'elemento %s no era presente en %d ms');
  // many combinations possible - the message is always the last argument
  browser.waitForElementPresent('body', 1000, false, function() {}, 'elemento %s no era presente en %d ms');
};

.waitForElementNotPresent()

Opposite of waitForElementPresent. Waits a given time in milliseconds for an element to be not present (i.e. removed) in the page before performing any other commands or assertions.

If the element is still present after the specified amount of time, the test fails.

You can change the polling interval by defining a waitForConditionPollInterval property (in milliseconds) in as a global property in your nightwatch.json or in your external globals file.

Similarly, a default timeout can be specified as a global waitForConditionTimeout property (in milliseconds).

Parameters:
Name Type description
selector string

The selector (CSS / Xpath) used to locate the element.

time=waitForConditionTimeout
Optional
number

The total number of milliseconds to wait before failing.

poll=waitForConditionPollInterval
Optional
number

The number of milliseconds to wait between checks. You can use this only if you also specify the time parameter.

abortOnFailure=abortOnAssertionFailure
Optional
boolean

By the default if the element is not found the test will fail. Set this to false if you wish for the test to continue even if the assertion fails. To set this globally you can define a property abortOnAssertionFailure in your globals.

callback
Optional
function

Optional callback function to be called when the command finishes.

message
Optional
string

Optional message to be shown in the output; the message supports two placeholders: %s for current selector and %d for the time (e.g. Element %s was not in the page for %d ms).

Usage:

this.demoTest = function (browser) {
  browser.waitForElementNotPresent('#dialog', 1000);
};

.element()

Search for an element on the page, starting from the document root. The located element will be returned as a web element JSON object.
First argument to be passed is the locator strategy, which is detailed on the WebDriver docs.

Parameters:
Name Type description
using string

The locator strategy to use.

value string

The search target.

callback function

Callback function which is called with the result value.

Usage:

module.exports = {
 'demo Test' : function(browser) {
    browser.element('css selector', 'body', function(result) {
      console.log(result.value)
    });
  }
}

.elements()

Search for multiple elements on the page, starting from the document root. The located elements will be returned as web element JSON objects.
First argument to be passed is the locator strategy, which is detailed on the WebDriver docs.

Parameters:
Name Type description
using string

The locator strategy to use.

value string

The search target.

callback function

Callback function to be invoked with the result when the command finishes.

Usage:

module.exports = {
 'demo Test' : function(browser) {
    browser.elements('css selector', 'ul li', function(result) {
      console.log(result.value)
    });
  }
}

.elementIdEquals()

Test if two element IDs refer to the same DOM element.

Parameters:
Name Type description
id string

The web element ID of the element to route the command to.

otherId string

The web element ID of the other element to compare against.

callback function

Callback function which is called with the result value.

Usage:

module.exports = {
 'demo Test' : function(browser) {
    browser.elementIdEquals('<ID-1>', '<ID-2>', function(result) {
      console.log(result.value)
    });
  }
}

.elementIdElement()

Search for an element on the page, starting from the identified element. The located element will be returned as a web element JSON object.

Parameters:
Name Type description
id string

The web element ID of the element to route the command to.

using string

The locator strategy to use.

value string

The search target.

callback function

Callback function which is called with the result value.

Usage:

module.exports = {
 'demo Test' : function(browser) {
    browser.elementIdElement('<ID>', 'css selector', '.new-element', function(result) {
      console.log(result.value)
    });
  }
}

.elementIdElements()

Search for multiple elements on the page, starting from the identified element. The located element will be returned as a web element JSON objects.

Parameters:
Name Type description
id string

The web element ID of the element to route the command to.

using string

The locator strategy to use.

value string

The search target.

callback function

Callback function which is called with the result value.

Usage:

module.exports = {
 'demo Test' : function(browser) {
    browser.elementIdElements('<ID>', 'css selector', 'ul li', function(result) {
      console.log(result.value)
    });
  }
}

Element Interaction

.click()

Simulates a click event on the given DOM element. Uses elementIdClick protocol action internally.

The element is scrolled into view if it is not already pointer-interactable. See the WebDriver specification for element interactability

Parameters:
Name Type description
selector string

The CSS/Xpath selector used to locate the element.

callback
Optional
function

Optional callback function to be called when the command finishes.

Usage:

this.demoTest = function (browser) {
  browser.click("#main ul li a.first");
};

.clearValue()

Clear a textarea or a text input element's value. Uses elementIdValue protocol action internally.

Parameters:
Name Type description
selector string

The CSS/Xpath selector used to locate the element.

callback
Optional
function

Optional callback function to be called when the command finishes.

Usage:

this.demoTest = function (browser) {
  browser.clearValue('input[type=text]');
};

.moveToElement()

Move the mouse by an offset of the specified element. Uses moveTo protocol command.

Parameters:
Name Type description
selector string

The CSS/Xpath selector used to locate the element.

xoffset number

X offset to move to, relative to the top-left corner of the element.

yoffset number

Y offset to move to, relative to the top-left corner of the element.

callback
Optional
function

Optional callback function to be called when the command finishes.

Usage:

this.demoTest = function (browser) {
  browser.moveToElement('#main', 10, 10);
};

.setValue()

Sends some text to an element. Can be used to set the value of a form element or to send a sequence of key strokes to an element. Any UTF-8 character may be specified.

setValue does not clear the existing value of the element. To do so, use the clearValue() command.

An object map with available keys and their respective UTF-8 characters, as defined on W3C WebDriver draft spec, is loaded onto the main Nightwatch instance as browser.Keys.

Parameters:
Name Type description
selector string

The CSS/Xpath selector used to locate the element.

inputValue string|array

The text to send to the element or key strokes.

callback
Optional
function

Optional callback function to be called when the command finishes.

Usage:

// send some simple text to an input
this.demoTest = function (browser) {
  browser.setValue('input[type=text]', 'nightwatch');
};
//
// send some text to an input and hit enter.
this.demoTest = function (browser) {
  browser.setValue('input[type=text]', ['nightwatch', browser.Keys.ENTER]);
};

.submitForm()

Submit a FORM element. The submit command may also be applied to any element that is a descendant of a FORM element. Uses submit protocol command.

Parameters:
Name Type description
selector string

The CSS/Xpath selector used to locate the element.

callback
Optional
function

Optional callback function to be called when the command finishes.

Usage:

this.demoTest = function (browser) {
  browser.submitForm('form.login');
};

.elementIdClear()

Scrolls into view a submittable element excluding buttons or editable element, and then attempts to clear its value, reset the checked state, or text content.

Parameters:
Name Type description
id string

The web element ID of the element to route the command to.

callback
Optional
function

Optional callback function to be called when the command finishes.

.elementIdClick()

Scrolls into view the element and clicks the in-view center point. If the element is not pointer-interactable, an element not interactable error is returned.

Parameters:
Name Type description
id string

The web element ID of the element to route the command to.

callback
Optional
function

Optional callback function to be called when the command finishes.

.elementIdValue()

Scrolls into view the form control element and then sends the provided keys to the element, or returns the current value of the element. In case the element is not keyboard interactable, an element not interactable error is returned.

Parameters:
Name Type description
id string

The web element ID of the element to route the command to.

value
Optional
string|array|none

Value to send to element in case of a POST

callback function

Callback function which is called with the result value.

.keys()

Send a sequence of key strokes to the active element. The sequence is defined in the same format as the sendKeys command.
An object map with available keys and their respective UTF-8 characters, as defined on W3C WebDriver draft spec, is loaded onto the main Nightwatch instance as client.Keys.

Rather than the setValue, the modifiers are not released at the end of the call. The state of the modifier keys is kept between calls, so mouse interactions can be performed while modifier keys are depressed.

Parameters:
Name Type description
keysToSend Array

The keys sequence to be sent.

callback
Optional
function

Optional callback function to be called when the command finishes.

.submit()

Submit a FORM element. The submit command may also be applied to any element that is a descendant of a FORM element.

Parameters:
Name Type description
id string

The web element ID of the element to route the command to.

callback
Optional
function

Optional callback function to be called when the command finishes.

Element State

Details on how WebDriver checks if the element is displayed are available Element Displayedness page.

.getAttribute()

Retrieve the value of an attribute for a given DOM element. Uses elementIdAttribute protocol command.

Parameters:
Name Type description
selector string

The CSS/Xpath selector used to locate the element.

attribute string

The attribute name to inspect.

callback function

Callback function which is called with the result value.

Returns
Type description
* The value of the attribute
Usage:

this.demoTest = function (browser) {
  browser.getAttribute("#main ul li a.first", "href", function(result) {
    this.assert.equal(typeof result, "object");
    this.assert.equal(result.status, 0);
    this.assert.equal(result.value, "#home");
  });
};

.getCssProperty()

Retrieve the value of a css property for a given DOM element. Uses elementIdCssProperty protocol command.

Parameters:
Name Type description
selector string

The CSS/Xpath selector used to locate the element.

cssProperty string

The CSS property to inspect.

callback function

Callback function which is called with the result value.

Returns
Type description
* The value of the css property
Usage:

this.demoTest = function (browser) {
  browser.getCssProperty("#main ul li a.first", "display", function(result) {
    this.assert.equal(typeof result, "object");
    this.assert.equal(result.status, 0);
    this.assert.equal(result.value, 'inline');
  });
};

.getElementSize()

Determine an element's size in pixels. Uses elementIdSize protocol command.

Parameters:
Name Type description
selector string

The CSS/Xpath selector used to locate the element.

callback function

Callback function which is called with the result value.

Returns
Type description
{width: number, height: number} The width and height of the element in pixels
Usage:

this.demoTest = function (browser) {
  browser.getElementSize("#main ul li a.first", function(result) {
    this.assert.equal(typeof result, "object");
    this.assert.equal(result.status, 0);
    this.assert.equal(result.value.width, 500);
    this.assert.equal(result.value.height, 20);
 });
};

.getTagName()

Query for an element's tag name. Uses elementIdName protocol command.

Parameters:
Name Type description
selector string

The CSS/Xpath selector used to locate the element.

callback function

Callback function which is called with the result value.

Returns
Type description
number The element's tag name, as a lowercase string.
Usage:

this.demoTest = function (browser) {
  browser.getTagName("#main ul li .first", function(result) {
    this.assert.equal(typeof result, "object");
    this.assert.equal(result.status, 0);
    this.assert.equal(result.value, "a");
  });
};

.getText()

Returns the visible text for the element. Uses elementIdText protocol command.

Parameters:
Name Type description
selector string

The CSS/Xpath selector used to locate the element.

callback function

Callback function which is called with the result value.

Returns
Type description
string The element's visible text.
Usage:

this.demoTest = function (browser) {
  browser.getText("#main ul li a.first", function(result) {
    this.assert.equal(typeof result, "object");
    this.assert.equal(result.status, 0);
    this.assert.equal(result.value, "nightwatchjs.org");
  });
};

.getValue()

Returns a form element current value. Uses elementIdValue protocol command.

Parameters:
Name Type description
selector string

The CSS/Xpath selector used to locate the element.

callback function

Callback function which is called with the result value.

Returns
Type description
string The element's value.
Usage:

this.demoTest = function (browser) {
  browser.getValue("form.login input[type=text]", function(result) {
    this.assert.equal(typeof result, "object");
    this.assert.equal(result.status, 0);
    this.assert.equal(result.value, "enter username");
  });
};

.isVisible()

Determine if an element is currently displayed. Uses elementIdDisplayed protocol command.

Parameters:
Name Type description
selector string

The CSS/Xpath selector used to locate the element.

callback function

Callback function which is called with the result value.

Usage:

this.demoTest = function (browser) {
  browser.isVisible('#main', function(result) {
    this.assert.equal(typeof result, "object");
    this.assert.equal(result.status, 0);
    this.assert.equal(result.value, true);
  });
};

.elementActive()

Get the element on the page that currently has focus. The element will be returned as a web element JSON object.

Parameters:
Name Type description
callback function

Callback function which is called with the result value.

Usage:

module.exports = {
 'demo Test' : function(browser) {
    browser.elementActive('<ID>', 'css selector', 'ul li', function(result) {
      console.log(result.value)
    });
  }
}

.elementIdAttribute()

Get the value of an element's attribute.

Parameters:
Name Type description
id string

ID of the element to route the command to.

attributeName string

The attribute name

callback function

Callback function which is called with the result value.

.elementIdCssProperty()

Retrieve the computed value of the given CSS property of the given element.

The CSS property to query should be specified using the CSS property name, not the JavaScript property name (e.g. background-color instead of backgroundColor).

Parameters:
Name Type description
id string

The web element ID of the element to route the command to.

cssPropertyName string
callback function

Callback function which is called with the result value.

.elementIdDisplayed()

Determine if an element is currently displayed.

Parameters:
Name Type description
id string

The web element ID of the element to route the command to.

callback function

Callback function which is called with the result value.

.elementIdEnabled()

Determine if an element is currently enabled.

Parameters:
Name Type description
id string

The web element ID of the element to route the command to.

callback function

Callback function which is called with the result value.

.elementIdName()

Retrieve the qualified tag name of the given element.

Parameters:
Name Type description
id string

The web element ID of the element to route the command to.

callback function

Callback function which is called with the result value.

.elementIdSelected()

Determine if an OPTION element, or an INPUT element of type checkbox or radio button is currently selected.

Parameters:
Name Type description
id string

The web element ID of the element to route the command to.

callback function

Callback function which is called with the result value.

.elementIdSize()

Determine an element's size in pixels. The size will be returned as a JSON object with width and height properties.

Parameters:
Name Type description
id string

The web element ID of the element to route the command to.

callback function

Callback function which is called with the result value.

.elementIdText()

Returns the visible text for the element.

Parameters:
Name Type description
id string

The web element ID of the element to route the command to.

callback function

Callback function which is called with the result value.

Element Location

.getLocation()

Determine an element's location on the page. The point (0, 0) refers to the upper-left corner of the page.

The element's coordinates are returned as a JSON object with x and y properties. Uses elementIdLocation protocol command.

Parameters:
Name Type description
selector string

The CSS/Xpath selector used to locate the element.

callback function

Callback function which is called with the result value.

Returns
Type description
{x:number, y:number} The X and Y coordinates for the element on the page.
Usage:

this.demoTest = function (browser) {
  browser.getLocation("#main ul li a.first", function(result) {
    this.assert.equal(typeof result, "object");
    this.assert.equal(result.status, 0);
    this.assert.equal(result.value.x, 200);
    this.assert.equal(result.value.y, 200);
  });
};

.getLocationInView()

Determine an element's location on the screen once it has been scrolled into view. Uses elementIdLocationInView protocol command.

Parameters:
Name Type description
selector string

The CSS/Xpath selector used to locate the element.

callback function

Callback function which is called with the result value.

Returns
Type description
{x: number, y: number} The X and Y coordinates for the element on the page.
Usage:

this.demoTest = function (browser) {
  browser.getLocationInView("#main ul li a.first", function(result) {
    this.assert.equal(typeof result, "object");
    this.assert.equal(result.status, 0);
    this.assert.equal(result.value.x, 200);
    this.assert.equal(result.value.y, 200);
  });
};

.elementIdLocationInView()

Determine an element's location on the screen once it has been scrolled into view.

Parameters:
Name Type description
id string

The web element ID of the element to route the command to.

callback
Optional
function

Optional callback function to be called when the command finishes.

.elementIdLocation()

Determine an element's location on the page. The point (0, 0) refers to the upper-left corner of the page.

The element's coordinates are returned as a JSON object with x and y properties.

Parameters:
Name Type description
id string

The web element ID of the element to route the command to.

callback function

Callback function which is called with the result value.

Returns
Type description
object The X and Y coordinates for the element on the page.

Document Handling

.injectScript()

Utility command to load an external script into the page specified by url.

Parameters:
Name Type description
scriptUrl string

The script file url

id
Optional
string

Dom element id to be set on the script tag.

callback
Optional
function

Optional callback function to be called when the command finishes.

Returns
Type description
HTMLScriptElement The newly created script tag.
Usage:

this.demoTest = function(client) {
  this.injectScript("{script-url}", function() {
    // we're all done here.
  });
};

.source()

Returns a string serialisation of the DOM of the current page.

Parameters:
Name Type description
callback function

Callback function which is called with the result value.

.execute()

Inject a snippet of JavaScript into the page for execution in the context of the currently selected frame. The executed script is assumed to be synchronous.
The script argument defines the script to execute in the form of a function body. The value returned by that function will be returned to the client.

The function will be invoked with the provided args array and the values may be accessed via the arguments object in the order specified.

Under the hood, if the body param is a function it is converted to a string with <function>.toString(). Any references to your current scope are ignored.

To ensure cross-browser compatibility, the specified function should not be in ES6 format (i.e. () => {}). If the execution of the function fails, the first argument of the callback contains error information.

Parameters:
Name Type description
body string|function

The function body to be injected.

args Array

An array of arguments which will be passed to the function.

callback
Optional
function

Optional callback function to be called when the command finishes.

Returns
Type description
* The script result.
Usage:

 this.demoTest = function (browser) {
   browser.execute(function(imageData) {
     // resize operation
     return true;
   }, [imageData], function(result) {
     // result.value === true
   });
}

.executeAsync()

Inject a snippet of JavaScript into the page for execution in the context of the currently selected frame. The executed script is assumed to be asynchronous.

The function to be injected receives the done callback as argument which needs to be called when the asynchronous operation finishes. The value passed to the done callback is returned to the client.
Additional arguments for the injected function may be passed as a non-empty array which will be passed before the done callback.

Asynchronous script commands may not span page loads. If an unload event is fired while waiting for the script result, an error will be returned.

Parameters:
Name Type description
script string|function

The function body to be injected.

args Array

An array of arguments which will be passed to the function.

callback
Optional
function

Optional callback function to be called when the command finishes.

Returns
Type description
* The script result.
Usage:

 this.demoTest = function (browser) {
   browser.executeAsync(function(done) {
     setTimeout(function() {
       done(true);
     }, 500);
   }, function(result) {
     // result.value === true
   });

   browser.executeAsync(function(arg1, arg2, done) {
     setTimeout(function() {
       done(true);
     }, 500);
   }, [arg1, arg2], function(result) {
     // result.value === true
   });
}

Sessions

A WebDriver session represents the connection between a client and a remote WebDriver server. Read more on WebDriver page.

.getLogTypes()

Gets the available log types. More info about log types in WebDriver can be found here: https://github.com/SeleniumHQ/selenium/wiki/Logging

Parameters:
Name Type description
callback function

Callback function which is called with the result value.

Returns
Type description
Array Available log types
Usage:

this.demoTest = function(client) {
  this.getLogTypes(function(typesArray) {
    console.log(typesArray);
  });
};

.getLog()

Gets a log from selenium.

Parameters:
Name Type description
typeString string|function

Log type to request

callback function

Callback function which is called with the result value.

Usage:

this.demoTest = function(client) {
  this.getLog('browser', function(logEntriesArray) {
    console.log('Log length: ' + logEntriesArray.length);
    logEntriesArray.forEach(function(log) {
       console.log('[' + log.level + '] ' + log.timestamp + ' : ' + log.message);
     });
  });
};

.isLogAvailable()

Utility command to test if the log type is available.

Parameters:
Name Type description
typeString string|function

Type of log to test

callback function

Callback function which is called with the result value.

Usage:

this.demoTest = function(browser) {
  browser.isLogAvailable('browser', function(isAvailable) {
    // do something more in here
  });
}

.end()

Ends the session. Uses session protocol command.

Parameters:
Name Type description
callback
Optional
function

Optional callback function to be called when the command finishes.

Usage:

this.demoTest = function (browser) {
  browser.end();
};

.session()

Get info about, delete or create a new session. Defaults to the current session.

Parameters:
Name Type description
action
Optional
string

The http verb to use, can be "get", "post" or "delete". If only the callback is passed, get is assumed by default.

sessionId
Optional
string

The id of the session to get info about or delete.

callback
Optional
function

Optional callback function to be called when the command finishes.

Usage:

this.demoTest = function (browser) {
   browser.session(function(result) {
     console.log(result.value);
   });
   //
   browser.session('delete', function(result) {
     console.log(result.value);
   });
   //
   browser.session('delete', '12345-abc', function(result) {
     console.log(result.value);
   });
}

.sessions()

Returns a list of the currently active sessions.

Parameters:
Name Type description
callback function

Callback function which is called with the result value.

Usage:

 this.demoTest = function (browser) {
   browser.sessions(function(result) {
     console.log(result.value);
   });
}

.timeouts()

Configure the amount of time that a particular type of operation can execute for before they are aborted and a |Timeout| error is returned to the client.

Parameters:
Name Type description
type string

The type of operation to set the timeout for. Valid values are "script" for script timeouts, "implicit" for modifying the implicit wait timeout and "page load" for setting a page load timeout.

ms number

The amount of time, in milliseconds, that time-limited commands are permitted to run.

callback
Optional
function

Optional callback function to be called when the command finishes.

Usage:

 this.demoTest = function (browser) {
   browser.timeouts('script', 10000, function(result) {
     console.log(result);
   });
}

.timeoutsAsyncScript()

Set the amount of time, in milliseconds, that asynchronous scripts executed by .executeAsync are permitted to run before they are aborted and a |Timeout| error is returned to the client.

Parameters:
Name Type description
ms number

The amount of time, in milliseconds, that time-limited commands are permitted to run.

callback
Optional
function

Optional callback function to be called when the command finishes.

Usage:

 this.demoTest = function (browser) {
   browser.timeoutsAsyncScript(10000, function(result) {
     console.log(result);
   });
}

.timeoutsImplicitWait()

Set the amount of time the driver should wait when searching for elements. If this command is never sent, the driver will default to an implicit wait of 0ms.

Parameters:
Name Type description
ms number

The amount of time, in milliseconds, that time-limited commands are permitted to run.

callback
Optional
function

Optional callback function to be called when the command finishes.

Usage:

 this.demoTest = function (browser) {
   browser.timeoutsImplicitWait(10000, function(result) {
     console.log(result);
   });
}

.status()

Query the server's current status.

Parameters:
Name Type description
callback function

Callback function which is called with the result value.

.sessionLog()

Gets the text of the log type specified. To find out the available log types, use .getLogTypes().

Returns a log entry JSON object.

Parameters:
Name Type description
typeString string

Type of log to request. Can be one of: client, driver, browser, server

callback function

Callback function which is called with the result value.

Returns
Type description
Array Array of the text entries of the log.
Usage:

 this.demoTest = function (browser) {
   browser.sessionLog('client', function(result) {
     console.log(result.value);
   });
}

.sessionLogTypes()

Gets an array of strings for which log types are available. This methods returns the entire WebDriver response, if you are only interested in the logs array, use .getLogTypes() instead.

Parameters:
Name Type description
callback function

Callback function which is called with the result value.

Usage:

 this.demoTest = function (browser) {
   browser.sessionLogTypes(function(result) {
     console.log(result.value);
   });
}

The commands in this section allow navigation to new URLs and introspection of the currently loaded url.

.getTitle()

Returns the title of the current page. Uses title protocol command.

Parameters:
Name Type description
callback function

Callback function which is called with the result value.

Returns
Type description
string The page title.
Usage:

 this.demoTest = function (browser) {
   browser.getTitle(function(title) {
     this.assert.equal(typeof title, 'string');
     this.assert.equal(title, 'Nightwatch.js');
   });
 };

.init()

This command is an alias to url and also a convenience method when called without any arguments in the sense that it performs a call to .url() with passing the value of launch_url field from the settings file.
Uses url protocol command.

Parameters:
Name Type description
url
Optional
string

Url to navigate to.

callback
Optional
function

Optional callback function to be called when the command finishes.

Usage:

this.demoTest = function (client) {
  client.init();
};

.urlHash()

Convenience method that adds the specified hash (i.e. url fragment) to the current value of the launch_url as set in nightwatch.json.

Parameters:
Name Type description
hash string

The hash to add/replace to the current url (i.e. the value set in the launch_url property in nightwatch.json).

callback
Optional
function

Optional callback function to be called when the command finishes.

Usage:

this.demoTest = function (client) {
  client.urlHash('#hashvalue');
  // or
  client.urlHash('hashvalue');
};

.url()

Retrieve the URL of the current page or navigate to a new URL.

Parameters:
Name Type description
url
Optional
string|function

If missing, it will return the URL of the current page as an argument to the supplied callback.

callback
Optional
Function
Usage:

module.exports = {
 'demo Test' : function(browser) {
    browser.url(function(result) {
      // return the current url
      console.log(result);
    });
    //
    // navigate to new url:
    browser.url('{URL}');
    //
    //
    // navigate to new url:
    browser.url('{URL}', function(result) {
      console.log(result);
    });
  }
}

.back()

Navigate backwards in the browser history, if possible.

Parameters:
Name Type description
callback
Optional
function

Optional callback function to be called when the command finishes.

.forward()

Navigate forwards in the browser history, if possible.

Parameters:
Name Type description
callback
Optional
function

Optional callback function to be called when the command finishes.

.refresh()

Refresh the current page.

Parameters:
Name Type description
callback
Optional
function

Optional callback function to be called when the command finishes.

.title()

Get the current page title.

Parameters:
Name Type description
callback function

Callback function which is called with the result value.

Usage:

 this.demoTest = function (browser) {
   browser.title(function(result) {
     console.log(result.value);
   });
}

Window Related

.switchWindow()

Change focus to another window. The window to change focus to may be specified by its server assigned window handle, or by the value of its name attribute.

To find out the window handle use windowHandles command

Parameters:
Name Type description
handleOrName string

The server assigned window handle or the name attribute.

callback
Optional
function

Optional callback function to be called when the command finishes.

Usage:

 this.demoTest = function (browser) {
   browser.windowHandles(function(result) {
     var handle = result.value[0];
     browser.switchWindow(handle);
   });
 };

.resizeWindow()

Resizes the current window.

Parameters:
Name Type description
width number

The new window width.

height number

The new window height.

callback
Optional
function

Optional callback function to be called when the command finishes.

Usage:

 this.demoTest = function (browser) {
   browser.resizeWindow(1000, 800);
 };

.setWindowPosition()

Sets the current window position.

Parameters:
Name Type description
offsetX number

The new window offset x-position.

offsetY number

The new window offset y-position.

callback
Optional
function

Optional callback function to be called when the command finishes.

Usage:

 this.demoTest = function (browser) {
   browser.setWindowPosition(0, 0);
 };

.maximizeWindow()

Maximizes the current window.

Parameters:
Name Type description
callback
Optional
function

Optional callback function to be called when the command finishes.

Usage:

 this.demoTest = function (browser) {
   browser.maximizeWindow();
 };

.closeWindow()

Close the current window. This can be useful when you're working with multiple windows open (e.g. an OAuth login).
Uses window protocol command.

Parameters:
Name Type description
callback
Optional
function

Optional callback function to be called when the command finishes.

Usage:

this.demoTest = function (client) {
  client.closeWindow();
};

.window()

Change focus to another window or close the current window. Shouldn't normally be used directly, instead .switchWindow() and .closeWindow() should be used.

Parameters:
Name Type description
method string

The HTTP method to use. Can be either POST (change focus) or DELETE (close window).

handleOrName string

The window to change focus to.

callback
Optional
function

Optional callback function to be called when the command finishes.

.windowHandle()

Retrieve the current window handle.

Parameters:
Name Type description
callback function

Callback function which is called with the result value.

Usage:

 this.demoTest = function (browser) {
   browser.windowHandle(function(result) {
     console.log(result.value);
   });
}

.windowHandles()

Retrieve the list of all window handles available to the session.

Parameters:
Name Type description
callback function

Callback function which is called with the result value.

Usage:

 this.demoTest = function (browser) {
   browser.windowHandles(function(result) {
     // An array of window handles.
     console.log(result.value);
   });
}

.windowMaximize()

Increases the window to the maximum available size without going full-screen.

Parameters:
Name Type description
handleOrName
Optional
string

windowHandle URL parameter; if it is "current", the currently active window will be maximized.

callback
Optional
function

Optional callback function to be called when the command finishes.

Usage:

 this.demoTest = function (browser) {
   browser.windowMaximize('current', function(result) {
     console.log(result);
   });
}

.windowPosition()

Change or get the position of the specified window. If the second argument is a function it will be used as a callback and the call will perform a get request to retrieve the existing window position.

Parameters:
Name Type description
windowHandle string
offsetX number
offsetY number
callback function

Callback function which is called with the result value.

Usage:

 this.demoTest = function (browser) {

   // Change the position of the specified window.
   // If the :windowHandle URL parameter is "current", the currently active window will be moved.
   browser.windowPosition('current', 0, 0, function(result) {
     console.log(result);
   });

   // Get the position of the specified window.
   // If the :windowHandle URL parameter is "current", the position of the currently active window will be returned.
   browser.windowPosition('current', function(result) {
     console.log(result.value);
   });
}

.windowSize()

Change or get the size of the specified window. If the second argument is a function it will be used as a callback and the call will perform a get request to retrieve the existing window size.

Parameters:
Name Type description
windowHandle string
width number
height number
callback
Optional
function

Optional callback function to be called when the command finishes.

Usage:

 this.demoTest = function (browser) {

   // Return the size of the specified window. If the :windowHandle URL parameter is "current", the size of the currently active window will be returned.
   browser.windowSize('current', function(result) {
     console.log(result.value);
   });

   // Change the size of the specified window.
   // If the :windowHandle URL parameter is "current", the currently active window will be resized.
   browser.windowSize('current', 300, 300, function(result) {
     console.log(result.value);
   });
}

.frame()

Change focus to another frame on the page. If the frame id is missing or null, the server should switch to the page's default content.

Parameters:
Name Type description
frameId
Optional
string|number

Identifier for the frame to change focus to.

callback
Optional
function

Optional callback function to be called when the command finishes.

Usage:

 this.demoTest = function (browser) {
   browser.frame('<ID>', function(result) {
     console.log(result);
   });
}

.frameParent()

Change focus to the parent context. If the current context is the top level browsing context, the context remains unchanged.

Parameters:
Name Type description
callback
Optional
function

Optional callback function to be called when the command finishes.

Usage:

 this.demoTest = function (browser) {
   browser.frameParent(function(result) {
     console.log(result);
   });
}

Cookies

.getCookies()

Retrieve all cookies visible to the current page. The cookies are returned as an array of cookie JSON object, as defined here.

Uses cookie protocol command.

Parameters:
Name Type description
callback function

The callback function which will receive the response as an argument.

Returns
Type description
Array.<object> A list of cookies.
Usage:

this.demoTest = function(browser) {
  browser.getCookies(function callback(result) {
    this.assert.equal(result.value.length, 1);
    this.assert.equals(result.value[0].name, 'test_cookie');
  });
}

.getCookie()

Retrieve a single cookie visible to the current page. The cookie is returned as a cookie JSON object, as defined here.

Uses cookie protocol command.

Parameters:
Name Type description
name string

The cookie name.

callback function

Callback function which is called with the result value.

Returns
Type description
object|null The cookie object as a selenium cookie JSON object or null if the cookie wasn't found.
Usage:

this.demoTest = function(browser) {
  browser.getCookie(name, function callback(result) {
    this.assert.equal(result.value, '123456');
    this.assert.equals(result.name, 'test_cookie');
  });
}

.setCookie()

Set a cookie, specified as a cookie JSON object, as defined here.

Uses cookie protocol command.

Parameters:
Name Type description
cookie object

The cookie object.

callback
Optional
function

Optional callback function to be called when the command finishes.

Usage:

this.demoTest = function(browser) {
  browser.setCookie({
    name     : "test_cookie",
    value    : "test_value",
    path     : "/", (Optional)
    domain   : "example.org", (Optional)
    secure   : false, (Optional)
    httpOnly : false, // (Optional)
    expiry   : 1395002765 // (Optional) time in seconds since midnight, January 1, 1970 UTC
  });
}

.deleteCookie()

Delete the cookie with the given name. This command is a no-op if there is no such cookie visible to the current page.

Parameters:
Name Type description
cookieName string

The name of the cookie to delete.

callback
Optional
function

Optional callback function to be called when the command finishes.

Usage:

this.demoTest = function(browser) {
  browser.deleteCookie("test_cookie", function() {
    // do something more in here
  });
}

.deleteCookies()

Delete all cookies visible to the current page.

Parameters:
Name Type description
callback
Optional
function

Optional callback function to be called when the command finishes.

Usage:

this.demoTest = function(browser) {
  browser.deleteCookies(function() {
    // do something more in here
  });
}

Retrieve or delete all cookies visible to the current page or set a cookie. Normally this shouldn't be used directly, instead the cookie convenience methods should be used: getCookie, getCookies, setCookie, deleteCookie, deleteCookies.

Parameters:
Name Type description
method string

Http method

callbackOrCookie
Optional
function|object

Optional callback function to be called when the command finishes.

User Actions

.doubleClick()

Double-clicks at the current mouse coordinates (set by .moveto()).

Parameters:
Name Type description
callback
Optional
function

Optional callback function to be called when the command finishes.

.mouseButtonClick()

Click at the current mouse coordinates (set by moveto).

The button can be (0, 1, 2) or ('left', 'middle', 'right'). It defaults to left mouse button.

Parameters:
Name Type description
button string|number

The mouse button

callback
Optional
function

Optional callback function to be called when the command finishes.

.mouseButtonDown()

Click and hold the left mouse button (at the coordinates set by the last moveto command). Note that the next mouse-related command that should follow is mouseButtonUp . Any other mouse command (such as click or another call to buttondown) will yield undefined behaviour.

Can be used for implementing drag-and-drop. The button can be (0, 1, 2) or ('left', 'middle', 'right'). It defaults to left mouse button, and if you don't pass in a button but do pass in a callback, it will handle it correctly.

Parameters:
Name Type description
button string|number

The mouse button

callback
Optional
function

Optional callback function to be called when the command finishes.

.mouseButtonUp()

Releases the mouse button previously held (where the mouse is currently at). Must be called once for every mouseButtonDown command issued.

Can be used for implementing drag-and-drop. The button can be (0, 1, 2) or ('left', 'middle', 'right'). It defaults to left mouse button, and if you don't pass in a button but do pass in a callback, it will handle it correctly.

Parameters:
Name Type description
button string|number

The mouse button

callback
Optional
function

Optional callback function to be called when the command finishes.

.moveTo()

Move the mouse by an offset of the specified element. If no element is specified, the move is relative to the current mouse cursor. If an element is provided but no offset, the mouse will be moved to the center of the element.

If the element is not visible, it will be scrolled into view.

Parameters:
Name Type description
element string

The web element ID assigned to the element to move to. If not specified or is null, the offset is relative to current position of the mouse.

xoffset number

X offset to move to, relative to the top-left corner of the element. If not specified, the mouse will move to the middle of the element.

yoffset number

Y offset to move to, relative to the top-left corner of the element. If not specified, the mouse will move to the middle of the element.

callback
Optional
function

Optional callback function to be called when the command finishes.

User Prompts

.acceptAlert()

Accepts the currently displayed alert dialog. Usually, this is equivalent to clicking on the 'OK' button in the dialog.

Parameters:
Name Type description
callback
Optional
function

Optional callback function to be called when the command finishes.

.dismissAlert()

Dismisses the currently displayed alert dialog. For confirm() and prompt() dialogs, this is equivalent to clicking the 'Cancel' button.

For alert() dialogs, this is equivalent to clicking the 'OK' button.

Parameters:
Name Type description
callback
Optional
function

Optional callback function to be called when the command finishes.

.getAlertText()

Gets the text of the currently displayed JavaScript alert(), confirm(), or prompt() dialog.

Parameters:
Name Type description
callback function

Callback function which is called with the result value.

Returns
Type description
string The text of the currently displayed alert.

.setAlertText()

Sends keystrokes to a JavaScript prompt() dialog.

Parameters:
Name Type description
value string

Keystrokes to send to the prompt() dialog

callback
Optional
function

Optional callback function to be called when the command finishes.

Screen Capture

.saveScreenshot()

Take a screenshot of the current page and saves it as the given filename.

Parameters:
Name Type description
fileName string

The complete path to the file name where the screenshot should be saved.

callback
Optional
function

Optional callback function to be called when the command finishes.

Usage:

 this.demoTest = function (browser) {
   browser.saveScreenshot('/path/to/fileName.png');
 };

.screenshot()

Take a screenshot of the current page.

Parameters:
Name Type description
log_screenshot_data boolean

Whether or not the screenshot data should appear in the logs when running with --verbose

callback function

Callback function which is called with the result value.

Mobile Related

.getOrientation()

Get the current browser orientation.

Parameters:
Name Type description
callback function

Callback function which is called with the result value.

Returns
Type description
string} The current browser orientation: {LANDSCAPE|PORTRAIT

.setOrientation()

Sets the browser orientation.

Parameters:
Name Type description
orientation string

The new browser orientation: {LANDSCAPE|PORTRAIT}

callback
Optional
function

Optional callback function to be called when the command finishes.

.contexts()

Get a list of the available contexts.

Used by Appium when testing hybrid mobile web apps. More info here: https://github.com/appium/appium/blob/master/docs/en/advanced-concepts/hybrid.md.

Parameters:
Name Type description
callback function

Callback function to be called when the command finishes.

Returns
Type description
Array an array of strings representing available contexts, e.g 'WEBVIEW', or 'NATIVE'

.currentContext()

Get current context.

Parameters:
Name Type description
callback function

Callback function to be called when the command finishes.

Returns
Type description
string|null a string representing the current context or `null`, representing "no context"

.setContext()

Sets the context.

Parameters:
Name Type description
context string

context name to switch to - a string representing an available context.

callback
Optional
function

Optional callback function to be called when the command finishes.

Utilities / Debugging

.pause()

Suspends the test for the given time in milliseconds. If the milliseconds argument is missing it will suspend the test indefinitely

Parameters:
Name Type description
ms number

The number of milliseconds to wait.

callback
Optional
function

Optional callback function to be called when the command finishes.

Usage:

this.demoTest = function (browser) {
  browser.pause(1000);
  // or suspend indefinitely
  browser.pause();
};

.useCss()

Sets the locate strategy for selectors to css selector, therefore every following selector needs to be specified as css.

Parameters:
Name Type description
callback
Optional
function

Optional callback function to be called when the command finishes.

Usage:

this.demoTest = function (browser) {
  browser
    .useCss() // we're back to CSS now
    .setValue('input[type=text]', 'nightwatch');
};

.useXpath()

Sets the locate strategy for selectors to xpath, therefore every following selector needs to be specified as xpath.

Parameters:
Name Type description
callback
Optional
function

Optional callback function to be called when the command finishes.

Usage:

this.demoTest = function (browser) {
  browser
    .useXpath() // every selector now must be xpath
    .click("//tr[@data-recordid]/span[text()='Search Text']");
};

.perform()

A simple perform command which allows access to the Nightwatch API in a callback. Can be useful if you want to read variables set by other commands.

The callback signature can have up to two parameters.

  • no parameters: callback runs and perform completes immediately at the end of the execution of the callback.
  • one parameter: allows for asynchronous execution within the callback providing a done callback function for completion as the first argument.
  • two parameters: allows for asynchronous execution with the Nightwatch api object passed in as the first argument, followed by the done callback.
Parameters:
Name Type description
callback function

The function to run as part of the queue.

Usage:

this.demoTest = function (browser) {
  var elementValue;
  browser
    .getValue('.some-element', function(result) {
      elementValue = result.value;
    })
    // other stuff going on ...
    //
    // self-completing callback
    .perform(function() {
      console.log('elementValue', elementValue);
      // without any defined parameters, perform
      // completes immediately (synchronously)
    })
    //
    // asynchronous completion
    .perform(function(done) {
      console.log('elementValue', elementValue);
      // potentially other async stuff going on
      // on finished, call the done callback
      done();
    })
    //
    // asynchronous completion including api (client)
    .perform(function(client, done) {
      console.log('elementValue', elementValue);
      // similar to before, but now with client
      // potentially other async stuff going on
      // on finished, call the done callback
      done();
    });
};

Contact

Please report any issues or feature requests on GitHub. Please review the Contributing Guidelines before submitting a new issue.

Issues with the documentation, such as inconsistencies, typos or mistakes can be reported on the Docs Github repository.

We also welcome API command examples which are included on the individual API command page. For example, the clearValue page is built out of: github.com/nightwatchjs/nightwatch-docs/blob/master/api/method/clearValue.md.

Questions/Getting Help

You're encouraged to ask any questions you might have regarding the usage of Nightwatch or its API on the Mailing List or on Twitter. In addition, there is a StackOverflow Nightwatch.js tag at your disposal.

Contributing

Contributions to Nightwatch are welcome, but please review the Contributing Guidelines beforehand to avoid your pull request getting delayed or declined.

Nightwatch is being developed by PineView.io - an independent consultancy based in Oslo, Norway with help from its contributors.

Get in Touch

You can hire us if you need expert, enterprise-level advice and assistance for your project. Head over to our website and let us know. We work with companies on large scale projects which require deeper integration and more tailor made solutions.

Becoming a Sponsor

If you're interested in supporting Nightwatch financially, you can become a sponsor on the OpenCollective platform.

Your support can accelerate the development of Nightwatch, allow us to spend more time on issues, new features and documentation.