Browser Automation with Nightwatch and Selenium

Nightwatch.js is an end‑to‑end Node.js powered testing framework. It is provided as a Node.js module and relies on a Selenium WebDriver which has now become a part of W3C specification.

The overview is focused on configuring Nightwatch on a Windows 10 machine.

Environment Setup

Nightwatch is Node.js‑based tool. Since that it requires Node.js platform to be installed the latest version which can be obtained on the official web site. When installing ensure that npm package manager (stands for node package manager) is marked for installation among other features. Also, for your convenience, mark Node.js and npm to be added to PATH environment variable.

Node.js setup. npm package managerThe npm tool is used for actual Nightwatch framework installation. To ensure npm is properly installed check its version by executing

Other npm CLI commands description can be found here.

The next step is to install Nightwatch itself. Run the following install command:

npm install –global nightwatch

The –global option here allows to use Nightwatch as a command line tool (by simply entering nightwatch keyword). The next tool we need is the Selenium Server. It acts as a bridge between Nightwatch and a browser(s). Selenium Server is a Java application contained in a JAR file the latest version of which can be downloaded from this page. In order to launch Selenium the Java Runtime Environment (JRE) needs to be installed on a running machine. The minimum required version is the 6th for older Selenium versions (2.22.0 up to 2.47.0). 3.0.0+ versions require Java 8. To check Java version (and its presence by the way =) ) execute the following command:


Selenium Server version used in this article is 3.4.0 . selenium-server-standalone-{$version}.jar may be launched manually by running:

java -jar selenium-server-standalone-{your_version_here}.jar [-additional-arguments]

This is especially useful when running Selenium Server on a remote machine. Since we have Nightwatch on the same machine where Selenium is, we’re going to manipulate selenium-server-standalone directly from Nightwatch configuration.

Configuration Settings

Our project is going to have next structure:

Note. There is no need of creating reports folder explicitly since it will be created automatically after the test has run.

To run tests JSON configuration file needs to be passed to nightwatch app. By default configuration file name is nightwatch.json. This means when simply running nightwatch without –config option passed in a directory with tests, it searches for nightwatch.json configuration file. Nightwatch also accepts JS configuration file searching nightwatch.conf.js by default. Note that nightwatch.conf.js takes precedence over nightwatch.json configuration if both are found. nightwatch.conf.js may be used for settings overriding or additional environment configuration.

Here is nightwatch.json configuration file example we are going to use in our test.

  "src_folders" : "tests",
  "output_folder" : "reports",

  "selenium" : {
    "start_process" : true,
    "server_path" : "bin/selenium-server-standalone-3.4.0.jar",
    "log_path" : "reports",
    "port" : 4444,
    "cli_args" : {
      "" : "bin/chromedriver.exe",
      "webdriver.gecko.driver" : "bin/geckodriver.exe"

  "test_settings" : {
    "default" : {
      "selenium_port"  : 4444,
      "screenshots" : {
        "enabled" : true,
        "on_failure" : true,
        "on_error" : false,
        "path" : "reports/screenshots/"
      "desiredCapabilities": {
        "browserName": "chrome",
        "javascriptEnabled" : true,
        "assertSslCerts" : true,
        "chromeOptions" : {
          "args" : ["--start-maximized"]

    "firefox" : {
      "desiredCapabilities" : {
        "browserName" : "firefox",
        "javascriptEnabled" : true,
        "assertSslCerts" : true

Here is a similar configuration implemented as JS file:

var selenium_config = {
    start_process: true,
    server_path: "bin/selenium-server-standalone-3.4.0.jar",
    log_path: "reports",
    port: 4444,
    cli_args : {
        "" : "bin/chromedriver.exe",
        "webdriver.gecko.driver" : "bin/geckodriver.exe"

var chrome_config = {
    browserName: "chrome",
    javascriptEnabled: true,
    assertSslCerts: true,
    chromeOptions: {
        args: ["--start-maximized"]
var default_config = {
    selenium_port: 4444,
    screenshots: {
        enabled: true,
        on_failure: true,
        on_error: false,
        path: "reports/screenshots/"
    desiredCapabilities: chrome_config
var firefox_config = Object.assign({}, default_config, {
    desiredCapabilities: {
        browserName: "firefox",
        javascriptEnabled: true,
        assertSslCerts: true
var environments = {
    default: default_config,
    firefox: firefox_config

module.exports = {
    src_folders: "tests",
    output_folder: "reports",
    selenium: selenium_config,
    test_settings: environments

Let’s walk around some important and useful configuration settings according to the documentation.

Basic settings

Configuration root settings

Name Type Default Description
src_folders string|array none An array of folders (excluding subfolders) where the tests are located.
output_folder (optional) string ‘tests_output’ folder The location where the JUnit XML report files will be saved.
page_objects_path (optional) string|array None Location(s) where page object files will be loaded from.
selenium (optional) object An object containing Selenium Server related configuration options. See Selenium configuration settings section.
test_settings object This object contains all the test related options. See Test configuration settings section.
test_workers boolean|object False Whether or not to run individual test files in parallel. If set to `true`, it runs the tests in parallel and determines the number of workers automatically.

If set to an object, it can specify the number of workers as “auto” or a “number”.


“test_workers” : {

“enabled” : true,

“workers” : “auto”


test_runner string|object “default” Specifies which test runner to use when running the tests. Values can be either “default” (built in nightwatch runner) or “mocha”.


“test_runner” : {

“type” : “mocha”,

“options” : {“ui” : “tdd”}


Selenium configuration settings

“selenium” object’s settings

Name Type Default Description
start_process boolean False Whether or not to manage the selenium process automatically. If this option set to true server_path option must be set.
start_session boolean true Whether or not to automatically start the Selenium session. This will typically be set to false when running unit/integration tests that don’t interact with the Selenium server.
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-3.4.0.jar

log_path string|boolean none The location where the selenium output.log file will be placed. Defaults to the current directory.

To disable Selenium logging, set this to false

port integer 4444 The port number Selenium will listen on. Note. If set to other than default value selenium_port setting must be set in accordance with this setting.
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 be 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.

· Nightwatch can run the tests using Chrome browser too. To enable this, you need to download the CromeDriver binary and specify its location here. Also, don’t forget to specify chrome as the browser name in the desiredCapabilities object.

· Nightwatch has also support for Internet Explorer . To enable this, you have to download the IE Driver binary and specify its location here. Also, don’t forget to specify “internet explorer” as the browser name in the desiredCapabilities object.

Test configuration settings

“test_settings” object’s configuration

Name Type Default Description
launch_url string none The URL which can be used in the tests as the main URL to load. Can be useful if your tests will be run on different environments, each one with a different URL.
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.
silent boolean true Whether to show extended Selenium command logs.
output boolean true Use to disable terminal output completely.
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.




“screenshots” : {

“enabled” : true,

“on_failure” : true,

“on_error” : false,  “path” : “”


desiredCapabilities Object An object which will be passed to the Selenium WebDriver when a new session will be created. You can specify browser name for instance along with other capabilities.
use_xpath boolean false Use xpath as the default locator strategy.

Let’s now create a simple test and name the file google_test.js:

module.exports = {
    'Search test' : function(browser) {
            .waitForElementVisible('body', 1000)
            .setValue('input[type=text]', 'testmatick')
            .waitForElementVisible('button[name=btnG]', 1000)
            .assert.containsText('#main', '')

For successful test execution, on both Chrome and Firefox browsers, chromedriver and geckodriver must be downloaded. In our test we use chromedriver_win32_v.2.29 and geckodriver-v0.16.1-win64.

Running tests

Before running the code ensure port 4444, which is going to be used by our test execution, is not occupied by other processes. To check busy ports, you may run the following command:

netstat -aon | more

and check in Local Address column whether a port you desire to use is currently busy.

Now just cd to the project and execute:


Chrome browser is launched by Nightwatch. You should see similar console output

In case of busy port, you may see infinite Starting selenium server… message

Busy port

In this case simply press Ctrl+C, type y and press Enter.

Busy port interrupt

Set other free port then in both port and selenium_port.

To run the test in Firefox browser, execute:

nightwatch –env firefox

Note. firefox option is related to declared environment name not to the browser itself:

"firefox" : {
      "desiredCapabilities" : {
        "browserName" : "firefox",
        "javascriptEnabled" : true,
        "assertSslCerts" : true

Let’s run the test in both browsers simultaneously. To perform this execute:

nightwatch –env default,firefox

Note. There should be no spaces between comma‑separated –env values. You should see similar console output

Run test in both browsers simultaneously

You may also use nightwatch.conf.js for the same test with same options launching. Just put mentioned JS configuration file in the project root directory (where the nightwatch.json is):

Now run same commands additionally passing –config option:

nightwatch –config nightwatch.conf.js
nightwatch –config nightwatch.conf.js –env firefox
nightwatch –config nightwatch.conf.js –env default,firefox

Mentioned option denotes nightwatch.conf.js as the only configuration file, in which case nightwatch.json is simply ignored. The results are the same as they would be when using nightwatch.json as a configuration file.

Testmatick is a leading provider of software test automation services with help of Nightwatch and Selenium. We utilize a wide range of well-known tools and custom-developed test automation solutions.

One comment

  • This is very nice article, you are a professional blogger. I am looking ahеad to searching for extra of your wonderful post. The explanation given on “BROWSER AUTOMATION WITH NIGHT-WATCH AND SELENIUM” was very nice. Thanks for sharing this post. exceptionally useful and helpful article. continue sharing more article!!!

Leave a Reply

Your email address will not be published. Required fields are marked *