Nightwatch APIs Suggest edits

Nightwatch works by loading all the necessary commands, settings, and other properties on a single API object which is made available at runtime to all test scripts as the single argument. This is so that everything is ready to get started with writing the actual test script and not have to instantiate other objects.

The "browser" object

We are referring to the main API object as browser – for consistency with other Selenium related JS test frameworks and also because since v2, it is also available as a global:

module.exports = {
  demoTest: function (browser) {
    browser.init();
  }
};

You might also see examples from previous versions of Nightwatch, using client. It is of course perfectly fine, although it might be confusing to users who are new to JavaScript syntax. 

module.exports = {
  demoTest: function (client) {
    client.init();
  }
};

Using as Global

From Nightwatch 2, browser is available as a global, so this is also valid:

module.exports = {
  demoTest: function () {
    browser.init();
  }
};

As well as this:

describe('Nightwatch APIs', function() {

  it('demoTest', function () {
    browser.init();
  })
};

API Contents

Below is a list of all public properties and methods that are made available on the browser object.

[String] .WEBDRIVER_ELEMENT_ID

The W3C web element identifier, equals to the string constant: "element-6066-11e4-a52e-4f735466cecf"

[String] .browserName

The browserName specified in the capabilities object

[Boolean] .isChrome()

Returns true|false whether or not the browser used is Google Chrome.

[Boolean] .isFirefox()

Returns true|false whether or not the browser used is a Mozilla Firefox.

[Boolean] .isSafari()

Returns true|false whether or not the browser used is Apple Safari.

[Boolean] .isEdge()

Returns true|false whether or not the browser used is Microsoft Edge.

[Boolean] .isInternetExplorer()

Returns true|false whether or not the browser used is Microsoft InternetExplorer.

[Boolean] .isOpera()

Returns true|false whether or not the browser used is Opera.

[String] .baseUrl

The value of baseUrl as defined in the Nightwatch config and which will be used as the default url for the command .init().

Other aliases are: base_url, launch_url, or launchUrl.

[Function] .actions()

Returns a new instance of the Actions class from Selenium. See the User Actions API section for details.

[Object] .capabilities

The WebDriver session capabilities, used by the browser driver to communicate the features supported.

WebDriver capabilities are used to communicate the features supported by a session. A client may also use capabilities to define which features it requires the driver to satisfy when creating a new session.

When a WebDriver session is created it returns a set of capabilities describing the negotiated, effective capabilities of the session. Some of the capabilities included in this set are standard and shared between all browsers, but the set may also contain browser-specific capabilities and these are always prefixed. More on WebDriver Capabilities.

Example:
{
  acceptInsecureCerts: false,
  browserName: 'chrome',
  browserVersion: '96.0.4664.55',
  'goog:chromeOptions': { debuggerAddress: 'localhost:50427' },
  // ... continued
}

[Object] currentTest

An object containing information about the current running testcase.

Available properties:
{
  // name of the current running testcase
  name: ' ... ',

  // name of the current running testsuite, i.e. the test file
  module: ' ... ',

  // name of the current running test group, if any
  group: '', 

  // the results object is shared among all testcases in the current testsuite
  results: {
    time: 0,
    assertions: [Array],
    passed: 0,
    errors: 0,
    failed: 0,
    retries: [Number],
    skipped: 0,
    tests: 0,
    steps: [],
    stackTrace: '',
    // an object accumulating the results of each testcase
    testcases: [Object]
  },

  // the current timestamp, in the format: Wed, 01 Dec 2021 08:34:00 GMT
  timestamp: ''
}

[Object] .desiredCapabilities

An object containing the capabilities sent by Nightwatch to WebDriver, as defined in the Nightwatch config file (see the Configuration section for details).

Example:
{
  browserName: 'chrome',
  'goog:chromeOptions': {},
  name: 'Example Test'
}

[Object] .driver

The Selenium WebDriver instance which Nightwatch uses under the hood. Can be useful in custom commands when it is needed to extend the main functionality offered by Nightwatch.

If uses in regular testcase scripts, this needs to be wrapped in a .perform() command.


Example:
In the below example we will retrieve the WebDriver Session instance. 
describe('Nightwatch APIs', function() {

  it('driver demoTest', async function () {
    const session = await browser
      .init()
      .perform(function() {
        return this.driver.getSession();
      });
  })
};

[String] .sessionId

The WebDriver session ID. WebDriver gives each session a unique session ID that can be used to differentiate one session from another. More info on WebDriver session is available on the W3C WebDriver page and the Selenium WebDriver Docs.

Example:
console.log(browser.sessionId); // e0b40362dcec8ec501ac2b42b62bdce2

[Object] .globals

The processed Nightwatch globals object which contains all the currently global properties and methods. See the Test Globals section for details.

[Object] .options

The processed Nightwatch config object which contains all the currently used properties and settings. See the Configuration section for details.

[Object] .Keys

A link to the Key enumeration from Selenium, which contains all the pressable keys that aren't text. This is usually needed when working with commands that send text to a page, like .sendKeys().

[Object] .page

Contains a dictionary of the current page objects, created for the currently running testcase. See Working with Page Objects section for details.

[Object] .assert

See Assert API section for details.

[Object] .verify

See Assert API section for details.

[Object] .ensure

See Ensure API section for details.

[Object] .expect

See Expect API section for details.

[Object] .chrome

Chromium specific commands. See API Commands section for details.

[Object] .firefox

Firefox specific commands. See API Commands section for details.