Config Settings

Base settings

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

Name type default description
src_folders string | Array | glob pattern 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 An object in which all the test environments are defined, each overwriting test settings as needed. A default environment is always required, from which the other environments inherit settings from.

See Defining Test Environments for details.
webdriver object An object containing WebDriver related configuration options.
selenium object An object containing Selenium Server related configuration options. If Selenium Server 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).
custom_commands_path string | Array | glob pattern none Location(s) where custom commands will be loaded from.
custom_assertions_path string | Array | glob pattern none Location(s) where custom assertions will be loaded from.
page_objects_path string | Array | glob pattern none Location(s) where page object files will be loaded from.
globals_path 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.
backwards_compatibility_mode
since v2.0		 boolean false In Nightwatch v1.x, when used with await operator, API commands will return the full result object as {value: `<VALUE>`} whereas in v2, the value is return directly. If using a callback, the behaviour remains unchanged.
disable_global_apis
since v2.0		 boolean false Disable the global apis like "browser", "element()", "expect()"; this might be needed if using Nightwatch with third-party libraries.

Test Runner settings

The below settings are used to control the way the built-in CLI test runner works.

Name type default description
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.

Example: "test_runner" : {"type" : "mocha", "options" : {"ui" : "tdd"}}
parallel_process_delay integer 10 Specifies the delay(in milliseconds) between starting the child processes when running in parallel mode.
enable_fail_fast
since v2.0		 boolean false Enable aborting the test run execution when the first test failure occurs; the remaining test suites will be skipped.
test_workers boolean|object false Whether or not to run individual test suites in parallel using a test worker for each. 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"}

Since v1.3.7 you can specify node options to be passed to individual test worker processes, using the node_options property.


Example:

- This will pass all of process.execArgv:

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


- This will pass only the specified cli options:

"test_workers": {
  "enabled": true,
  "workers": "auto",
  "node_options": ["--inspect"]
},
unit_tests_mode boolean false Controls whether to run tests in unit testing mode, which means the session will not automatically be created.

Test Session Settings

These settings are used to fine tune the behaviour of a test session and define properties which may be available during the course of it.

Setting the baseUrl property

This baseUrl (or launchUrl) 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 baseUrl 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.baseUrl)
      // ...
      .end();
  }
};
Name type default description
baseUrl 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.

Aliases: base_url, launch_url, launchUrl.
desiredCapabilities
alias: capabilities		 object | function | Selenium Capabilities The WebDriver capabilities for when a new session will be created. You can specify browser name for instance along with other capabilities.
Example:

"desiredCapabilities" : {
  "browserName" : "firefox",
  "acceptInsecureCerts" : true
}
You can view the complete list of capabilities here.

Since v2.0, Selenium Capabilities objects can also be specified. Example:
const firefox = require('selenium-webdriver/firefox');


const options = new firefox.Options()
  .addExtensions('../../../path/to/extension.xpi');


module.exports = {
  src_folders: ['tests'],
  test_settings: {
    default: {
      browserName: 'firefox',
      desiredCapabilities: options
    }
  }
};

Or as a function: 
module.exports = {
  src_folders: ['tests'],
  test_settings: {
    default: {
      browserName: 'firefox',
      desiredCapabilities() {
        const firefox = require('selenium-webdriver/firefox');
        

        const options = new firefox.Options()
          .addExtensions('../../../path/to/extension.xpi');
        

        return options;
      }
    }
  }
};
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.
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 Webdriver server.
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.
use_xpath boolean false Use xpath as the default locator strategy
use_ssl boolean false Set to true if connecting to a remote Grid server via https. Also don't forget to set port to 443.
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.
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.
selenium_host
Deprecated - use selenium.host		 string localhost The hostname/IP on which the Selenium Server is accepting connections.
selenium_port
Deprecated - use selenium.port		 integer 4444 The port number on which the Selenium Server is accepting connections.

Filtering Settings

The below settings can be used to define ways of filtering test files.

Name type default description
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"
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).

Output Settings

The below settings can be used to control the output and logging when running tests.

Name type default description
output_folder string tests_output The location where the JUnit XML report files will be saved.
disable_colors boolean false Controls whether or not to disable coloring of the CLI output globally.
live_output boolean false This option is only useful when running tests in parallel. Controls whether or not to buffer the output.
silent boolean true Whether to show the extended HTTP traffic command logs from the WebDriver or Selenium server.
output boolean true Used to disable CLI output completely.
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. Detailed output is disabled by default when running tests in parallel.
disable_error_log boolean false Set this to true if you'd like to not display errors during the execution of the test (they are shown at the end always).
output_timestamp boolean false Set this to true if you'd like to see timestamps next to the logging output.
log_screenshot_data boolean false Used to enable showing the Base64 image data in the (verbose) log when taking screenshots.

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 When this is enabled, the Webdriver server is run in background in a child process and started/stopped automatically.
Nightwatch includes support for managing Chromedriver, Geckodriver (Firefox), Safaridriver, and Selenium Server.
server_path string none Only useful if start_process is enabled.
host string Only needed when the Webdriver service is running on a different machine.
port integer The port number on which the Webdriver service will listen and/or on which Nightwatch will attempt to connect.
ssl boolean Should be set to true if connecting to a remote (cloud) service via HTTPS. Also don't forget to set port to 443.
log_path 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
log_file_name string|none none By default, the log file name will be the same as the testsuite file name, but a different filename can be specified as well.
cli_args object none List of cli arguments to be passed to the Webdriver process. This varies for each Webdriver implementation.
keep_alive boolean|object false Enable HTTP Keep-Alive. If set to true the keepAlive option is enabled with default settings (keepAliveMsecs = 3000).
If set to an object, can specify specify the keepAliveMsecs value.

Example: "keep_alive" : {"enabled" : true, "keepAliveMsecs" : 2000}
timeout_options object timeout: 60000
retry_attempts: 0 		Requests to the Webdriver service will timeout in timeout miliseconds; a retry will happen retry_attempts number of times.

Example:
{timeout: 15000, retry_attempts: 5}
status_poll_interval
since v1.2.2		 integer 100 Interval (in ms) to use between status ping checks when checking if the Webdriver server is up and running
max_status_poll_tries
since v1.2.2		 integer 5 Maximum number of ping status check attempts when checking if the Webdriver server is up and running before returning a timeout error.
process_create_timeout
since v1.2.2		 integer 120000 The entire time (in ms) to wait for the Node.js process to be created and running (default is 2 min), including spawning the child process and checking the status
username 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 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 string none Proxy requests to the Webdriver (or Selenium) service. http, https, socks(v5), socks5, sock4, and pac are accepted.
Uses proxy-agent which needs to be installed as a separate package from NPM.

Example: http://user:pass@host:port
default_path_prefix string Needed sometimes when using a Selenium Server. The prefix to be added to to all requests (e.g. /wd/hub).

Selenium Server Settings

If Selenium Server is being used, then the connection related settings should be placed under the "selenium"". If both webdriver and selenium dictionaries are present, the selenium options will be merged with the webdriver ones.

The "selenium" settings should also be used when configuring connections to cloud-based testing providers, such as BrowserStack, SauceLabs, CrossBrowserTesting, or LambdaTest.

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 works with Internet Explorer also. To enable this you have to download the IE Driver binary and specify it's location here.

    Alternatively you can install the package iedriver from NPM.

    Also you need to specify "internet explorer" as the browser name in the desiredCapabilities object.

Selenium Example Configuration

Here's an example configuration as part of the nightwatch.conf.js which uses a local Selenium Server with support for Firefox, Chrome, and Internet Explorer.

The following NPM packages are assumed to be installed in the current project:

module.exports = {
  src_folders: [],
  

  test_settings: {
    default: {
    launch_url: 'https://nightwatchjs.org'
  },
  

  selenium: {
    // Selenium Server is running locally and is managed by Nightwatch
    selenium: {
      start_process: true,
      port: 4444,
      server_path: require('selenium-server').path,
      cli_args: {
        'webdriver.gecko.driver': require('geckodriver').path,
        'webdriver.chrome.driver': require('chromedriver').path,
        'webdriver.ie.driver': process.platform === 'win32' ? require('iedriver').path : ''
      }
    },
    webdriver: {
      start_process: false
    }
  },
  

  'selenium.chrome': {
    extends: 'selenium',
    desiredCapabilities: {
      browserName: 'chrome',
      chromeOptions: {
      }
    }
  },
  

  'selenium.firefox': {
    extends: 'selenium',
    desiredCapabilities: {
      browserName: 'firefox'
    }
  },
  

  'selenium.ie': {
    extends: 'selenium',
    desiredCapabilities: {
      browserName: 'internet explorer'
    }
  }
}
}

BrowserStack Example Configuration

Browserstack is one of the most popular cloud testing platforms. Using it with Nightwatch is very straightforward and there is configuration in the auto-generated nightwatch.conf.js file.

Once you have an account, you need to set the following environment variables. Dotenv files are also supported by Nightwatch.

  • BROWSERSTACK_USER
  • BROWSERSTACK_KEY

Remember to also enable HTTP keepalive for improved network performance.

module.exports = {
  src_folders: [],
  

  webdriver: {
    keep_alive: true,
    timeout_options: {
      timeout: 60000,
      retry_attempts: 3
    }
  }
  

  test_settings: {
    default: {
      launch_url: 'https://nightwatchjs.org'
    },
    

    browserstack: {
      selenium: {
        host: 'hub-cloud.browserstack.com',
        port: 443
      },
      

      // More info on configuring capabilities can be found on:
      // https://www.browserstack.com/automate/capabilities?tag=selenium-4
      desiredCapabilities: {
        'bstack:options' : {
          local: 'false',
          userName: '${BROWSERSTACK_USER}',
          accessKey: '${BROWSERSTACK_KEY}',
        }
      }
    },
    

    'browserstack.chrome': {
      extends: 'browserstack',
      desiredCapabilities: {
        browserName: 'chrome',
        chromeOptions : {
        }
      }
    },
    

    'browserstack.firefox': {
      extends: 'browserstack',
      desiredCapabilities: {
        browserName: 'firefox'
      }
    },
    

    'browserstack.ie': {
      extends: 'browserstack',
      desiredCapabilities: {
        browserName: 'IE',
        browserVersion: '11.0',
        'bstack:options' : {
          os: 'Windows',
          osVersion: '10',
          local: 'false',
          seleniumVersion: '3.5.2',
          resolution: '1366x768'
        }
      }
    }
  }
}

Recommended content