External Globals

Globals are a useful concept which Nightwatch provides to be used for data operations between or outside of test runs. For a complete overview of what globals are and how they can be used, please refer to the Using test globals page in the Getting Started section.

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

module.exports = {
  globals_path: './nightwatch/globals.js'
};

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.

Example:

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

  'integration' : {
    isLocal : false
  }
};

Global Test Settings

For scenarios where greater flexibility is needed, there are a number of globals which are holding test settings and can control test execution.

Here's the entire global object with the default values, which can be overwritten as needed. You can also view the source code on Github: github.com/nightwatchjs/nightwatch/blob/main/lib/settings/defaults.js.

module.exports = {
  // An object which will be made available on the main test api, throughout the test execution
  globals: {
    // this controls whether to abort the test execution when an assertion failed and skip the rest
    // it's being used in waitFor commands and expect assertions
    abortOnAssertionFailure: true,
    

    // this controls whether to abort the test execution when an element cannot be located; an error
    // is logged in all cases, but this also enables skipping the rest of the testcase;
    // it's being used in element commands such as .click() or .getText()
    abortOnElementLocateError: false,
    

    // this will overwrite the default polling interval (currently 500ms) for waitFor commands
    // and expect assertions that use retry
    waitForConditionPollInterval: 500,
    

    // default timeout value in milliseconds for waitFor commands and implicit waitFor value for
    // expect assertions
    waitForConditionTimeout: 5000,
    

    // since 1.4.0 – this controls whether to abort the test execution when an element cannot be located; an error
    // is logged in all cases, but this also enables skipping the rest of the testcase;
    // it's being used in element commands such as .click() or .getText()
    abortOnElementLocateError: false,
    

    // this will cause waitFor commands on elements to throw an error if multiple
    // elements are found using the given locate strategy and selector
    throwOnMultipleElementsReturned: false,
    

    // By default a warning is printed if multiple elements are found using the given locate strategy
    // and selector; set this to true to suppress those warnings
    suppressWarningsOnMultipleElementsReturned: false,
    

    // controls the timeout value for async hooks. Expects the done() callback to be invoked within this time
    // or an error is thrown
    asyncHookTimeout : 10000,
    

    // controls the timeout value for when running async unit tests. Expects the done() callback to be invoked within this time
    // or an error is thrown
    unitTestsTimeout : 2000,
    

    // controls the timeout value for when executing the global async reporter. Expects the done() callback to be invoked within this time
    // or an error is thrown
    customReporterCallbackTimeout: 20000,
    

    // 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.
    retryAssertionTimeout: 5000,
    

    reporter: function(results, cb) {cb(results);}
  }
};

Global Test Hooks

The same set of hooks as per test suite is also available globally, outside the scope of the test. 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 before[Each] and after[Each]

You can also have global before and after [asynchronous] methods that can perform an operation before starting the test runner and right before exiting, when all the tests have finished executing.

Similarly, global beforeEach and afterEach will be invoked before and after each test suite (i.e. test file). These ones do receive the Nightwatch browser object.

The methods are defined in the external globals file and invoked using the globals object as context. The callback is the only argument passed and must be called when the operation finishes.

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(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(done) {
    // run this only for the local-env
    if (this.isLocal) {
      // stop the local server
      App.stopServer(function() {
        // shutting down
        done();
      });
    } else {
      done();
    }
  },
  

  // This will be run before each test suite is started
  beforeEach(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(browser, done) {
    console.log(browser.currentTest);
    done();
  },
  

  // Called right after the command .navigateTo() is finished
  async onBrowserNavigate(browser) {
    return Promise.resolve();
  },
  

  // Called right before the command .quite() is finished
  async onBrowserQuit(browser) {
    return Promise.resolve();
  }
};

Global Reporter

The global reporter is invoked at the end of the test run, before calling the built-in jUnit reporter (or a custom reporter specified using the --reporter CLI option). An object containing the test results is passed as an argument.

Example:

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

Further Reading: