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.

At this point you should have at least one WebDriver package installed in your project. Refer to the WebDriver installation section for details.

Auto-generated Configuration

Since version 1.3, Nightwatch will generate a nightwatch.conf.js config file by default, based on the operation system and existing driver packages. If a nightwatch.json or nightwatch.conf.js file is found in the current folder, nothing happens and the file is not generated.

So far, we have included support for Chrome, Firefox, Safari, and Internet Explorer. The following packages can be used from NPM and, if installed, Nightwatch will automatically detect and configure the test runner:

Manual Configuration

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 a .js configuration files is also possible, with nightwatch.conf.js always taking precedence if both files are found. A .js file is often more desirable as it provides more capabilities which come useful in large projects that need to test on several browsers.

Here's an example config file which uses Firefox as target browser.

module.exports = {
  // An array of folders (excluding subfolders) where your tests are located;
  // if this is not specified, the test source must be passed as the second argument to the test runner.
  src_folders: [],

webdriver: {
start_process: true,
port: 4444,
server_path: require('geckodriver').path,
cli_args: [
// very verbose geckodriver logs
// '-vv'

test_settings: {
default: {
launch_url: '',
desiredCapabilities : {
browserName : 'firefox',
alwaysMatch: {
// Enable this if you encounter unexpected SSL certificate errors in Firefox
// acceptInsecureCerts: true,
'moz:firefoxOptions': {
args: [
// '-headless',
// '-verbose'
Improve this article