Test globals

Overview

Test globals are a useful concept that Nightwatch provides for persisting data between test suites and also to define global test hooks. In its most simple form, it is a dictionary of name-value pairs which is defined in your configuration file.

Globals can be defined either as a "globals" property in your config file or as an external file which is specified as the "globals_path" property.

Example

Here's an example definition using the globals property in the nightwatch.json configuration file:

nightwatch.json 
{
  "src_folders": [],

  "test_settings": {
    "default": {
      "launch_url": "https://nightwatchjs.org",

      "globals": {
        "myGlobalVar" : "some value",
        "otherGlobal" : "some other value"
      }
    }
  }
}

The globals object is loaded directly onto the Nightwatch api object which is passed to the tests and available via browser.globals.

sampleTest.js 
describe('test globals example', function() {

  it('Demo test', function(browser) {
    console.log(browser.globals.myGlobalVar); // myGlobalVar == "some value"
  });

})

External test globals

Test globals can also be defined in an external file, specified by the globals_path settings in your configuration file, like so:

nightwatch.json 
{
  "src_folders": [],
  "globals_path": "lib/globals.js",

  "test_settings": {
    "default": {
    "launch_url": "https://nightwatchjs.org"
  }
}

The external globals file can also contain:

  • global test hooks
  • a custom reporter
  • test specific settings

Pre-defined Globals

The following globals can be used to control the behaviour of the test runner and are defined with the below default values.

You can define these in two ways:

  • in your external globals file, specified by the globals_path config property, e.g. lib/globals.js
  • directly in your nightwatch.conf.js config file
lib/globals.js 
module.exports = {
  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 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,

    // Custom reporter
    reporter: function(results, done) {
      // do something with the results
      done(results);
    },

    // External before hook is ran at the beginning of the tests run, before creating the Selenium session
    before(done) {
      done();
    },

    // External after hook is ran at the very end of the tests run, after closing the Selenium session
    after(done) {
      done();
    },

    // This will be run before each test suite is started
    beforeEach(browser, done) {
      done();
    },

    // This will be run after each test suite is finished
    afterEach(browser, done) {
      done();
    },

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

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

Environment Specific Globals

Like other test settings, globals have the ability to be overwritten per test environment.

Consider this configuration:

nightwatch.json 
{
  "src_folders": [],

  "test_settings": {
    "default": {
      "launch_url": "https://nightwatchjs.org",

      "globals": {
        "myGlobalVar" : "some value",
        "otherGlobal" : "some other value"
      }
    },

    "integration": {
      "globals": {
        "myGlobalVar" : "integrated global"
      }
    }
  }
}

Add a very basic test:

sampleTest.js 
module.exports = {
  'Demo test' : function (browser) {
    console.log('myGlobalVar is: "', browser.globals.myGlobalVar, '"');
  }
};

Pass the --env integration option to the runner:

npx nightwatch --env integration

Then our globals object will look like below:

myGlobalVar is: "integrated global"

Recommended content

Improve this article