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.