Integrated end-to-end testing framework written in Node.js and using W3C Webdriver API. Developed at @browserstack
MIT License
Bot releases are visible (Hide)
Published by beatfactor about 3 years ago
const Nightwatch = require('nightwatch');
const client = Nightwatch.createClient({
headless: true,
output: true,
silent: true, // set to false to enable verbose logging
browserName: 'firefox', // can be either: firefox, chrome, safari, or edge
timeout: 10000, // set the global timeout to be used with waitFor commands and when retrying assertions/expects
env: null, // set the current test environment from the nightwatch config
desiredCapabilities: {
// any additional capabilities needed
},
globals: {}, // can define/overwrite test globals here; when using a third-party test runner only the global hooks onBrowserNavigate/onBrowserQuit are supported
parallel: false, // when the test runner used supports running tests in parallel; set to true if you need the webdriver port to be randomly generated
// All other settings can be overwritten here, such as:
disable_colors: false
});
const browser = await client.session();
Updated the bundled Mocha test runner to use Mocha v9 and added other features supported by the default nightwatch test runner (such as using test tags, global hooks etc.); pending Mocha v9.1.3 which contains https://github.com/mochajs/mocha/issues/4760
New API commands:
browser.navigateTo(url, [callback])
- navigates to a new url. Accepts also relative urls if launchUrl
is defined in the config and will execute onBrowserNavigate
global hook after the url is loaded.
browser.getCurrentUrl([callback])
browser.quit([callback])
- ends the session and closes down the test WebDriver server, if one is running. This is similar to calling the .end()
command, but the former doesn't quit the WebDriver session. It also executes the onBrowserQuit
global hook before ending the session.
browser.setAttribute([using], selector, property, [callback])
- set the value of a specified DOM attribute for the given element.
moveToElement
and moveTo
api commandsPublished by beatfactor about 3 years ago
proxy-agent
dependency package to the latest version.Published by beatfactor about 3 years ago
selenium_host
config property wasn't set (#2892 )browserName
to null
in order to accommodate Appium (#2882)Published by beatfactor about 3 years ago
The next major version of Nightwatch is finally available in NPM as an alpha pre-release. It contains a wide range of new features and improvements for writing and running tests as well as full cross-browser testing support for W3C WebDriver compliant browsers.
The underlying architecture was completely reworked to use the official selenium-webdriver library in communicating with the browser drivers. This means better cross-browser integration, more reliable DOM element command handling, and overall more stable and faster tests. It also means that the newest features and capabilities of WebDriver will be directly available in Nightwatch, such as the upcoming Webdriver BiDi protocol, deemed as "the future of cross-browser automation".
To install, run:
npm i nightwatch@alpha
WebDriver provides a comprehensive API for generating complex user gestures called the Actions API. This is available and ready to use in Nightwatch via the existing .perform()
command. The previous functionality of the perform() command is still there and working in the same way as before.
Here's a basic example on how to use the new actions api:
try {
const performResult = await browser.perform(function() {
const actions = this.actions({async: true});
return actions
.keyDown(Key.SHIFT)
.keyUp(Key.SHIFT);
});
console.log('perform', performResult)
} catch (err) {
console.error(err)
}
More examples in the selenium api docs. In the example above, the Actions
class instance is created using this.actions(<options>)
. The .perform()
at the end (which is needed in the selenium docs) should be omitted in Nightwatch, as it will be called automatically.
Both ChromeDriver and EdgeDriver expose some specific commands for working with their respective browsers.
When using ChromeDriver or EdgeDriver it is now possible to execute commands via the Chrome DevTools protocol. Here's the full list of commands available on the chrome
namespace on the Nightwatch browser
object:
More info:
The FirefoxDriver exposes some specific commands, such as for setting context to run "privileged" javascript code or for working with addons. These are now available on in Nightwatch directly, on the firefox
namespace.
More info:
The new .ensure
namespace is based on the until module from selenium-webdriver.
Example:
describe('demo test for .ensure', function() {
test('basic test', function(browser) {
browser
.url('https://nightwatchjs.org')
.ensure.titleMatches(/Nightwatch\.js/)
.ensure.elementIsVisible('#index-container')
});
});
The newly added element()
global can be used to pre-construct element objects outside of test cases. It is also possible to use the newly added by()
global utility which is equivalent to using the By()
class from selenium-webdriver to create element locators.
In addition, the browser
object is also available as global, so it's not necessary to pass it as an argument to tests, as it is the case in Nightwatch v1.x.
It is also possible to disable the global apis by setting disable_global_apis
to true
in your nightwatch config file.
Example:
const assert = require('assert');
const {WebElement} = require('selenium-webdriver');
describe('demo element() global', function() {
const signupEl = element(by.css('#signupSection'));
const loginEl = element('#weblogin');
test('element globals command', async function() {
const tagName = await browser.waitForElementPresent(loginEl, 100).getTagName(loginEl);
assert.strictEqual(tagName, 'div');
// use elements created with element() to regular nightwatch assertions
browser.assert.visible(loginEl);
// use elements created with element() to expect assertions
browser.expect.element(loginEl).to.be.visible;
// retrieve the WebElement instance
const loginWebElement = await loginEl.getWebElement();
assert.ok(loginWebElement instanceof WebElement);
});
});
The WebDriver
instance is available as well on the Nightwatch api object as the driver
property.
If you wish to chain WebDriver specific commands, you'll need to wrap them inside either a perform()
or a waitUntil()
command.
Example:
describe('demo driver object', function() {
it('get browser logs – classic', function() {
browser
.url('https://nightwatchjs.org')
.waitForElementVisible('body')
.perform(function() {
this.driver.manage().logs().get('browser').then(result => {
console.log('Browser logs:', result)
})
});
});
it('get browser logs – with ES6 async/await', async function() {
await browser.url('https://nightwatchjs.org').waitForElementVisible('body');
const logs = await browser.driver.manage().logs().get('browser');
console.log('Browser logs:', logs)
});
});
The WebDriver BiDi is the new protocol for
communicating with browsers, defined as a new W3C spec, currently in progress.
Early support is available in Selenium 4 and it is already available in ChromeDriver via the Chrome Developer Tools.
WebDriver Bidi allows users to capture events from the browser as they happen rather than using the traditional
approach of request/response that WebDriver is using for other APIs.
Internally WebDriver will create a WebSocket connection to the browser for events and commands to be transmitted.
Example:
The below example calls the Page.getLayoutMetrics
method from CDP via a WebDriver Bidirectional connection
over a WebSocket.
describe('demo webdriver bidirectional', function() {
it('samepl test bidi', async function(browser) {
await browser.url('http://nightwatchjs.org/');
const cdpConnection = await browser.driver.createCDPConnection('page');
browser.assert.ok(cdpConnection._wsConnection && cdpConnection._wsConnection._url.startsWith('ws://'),
`CDP connection is successful to: ${cdpConnection._wsConnection._url}`);
const layoutMetrics = await browser.perform(function(callback) {
const id = 99;
cdpConnection._wsConnection.on('message', function getLayoutMetrics(message) {
const params = JSON.parse(message)
if (params.id === 99) {
cdpConnection._wsConnection.off('message', getLayoutMetrics);
callback(params.result);
}
});
cdpConnection.execute('Page.getLayoutMetrics', id, {});
});
console.log('Layout Metrics:', layoutMetrics)
});
});
A few new commands have been added and also compatibility has been improved for several existing commands.
browser.getAccessibleName(<selector> | <WebElement>
)
returns the computed WAI-ARIA label of an element.
const result = await browser.getAccessibleName('input[type=search]');
browser.getAriaRole(<selector> | <WebElement>
)
returns the computed WAI-ARIA role of an element.
const result = await browser.getAriaRole('input[type=search]');
browser.takeElementScreenshot(<selector> | <WebElement>
)
take a screenshot of the visible region encompassed by an element's bounding rectangle.
const data = await browser.takeElementScreenshot('#container');
require('fs').writeFile('out.png', data, 'base64');
browser.uploadFile(<selector> | <WebElement>
)
uploads file to an element using absolute file path.
await browser.uploadFile('#myFile', '/path/to/file.pdf');
browser.waitUntil(<conditionFunction>
, [optionalMaxTimeout]
, [optionalRetryInterval]
, [optionalCallback]
)
a generic command which can make the test runner wait for a condition to evaluate to a "truthy" value. The condition may be specified by any function which returns the value to be evaluated or a Promise to wait for. If the condition is not satisfied, a
TimeoutError
will be thrown and the test will fail.
let conditionValue;
await browser.waitUntil(function() {
return conditionValue === true;
});
await browser.waitUntil(async function() {
const title = await this.execute(function() {
return document.title;
});
return title === 'Nightwatch.js';
}, 1000);
We have changed the result format of Nightwatch commands to return the value directly when using the await
operator.
The value passed to callback remains the same as in v1.x. This behaviour can be disabled by setting the
backwards_compatibility_mode
to true
in your nightwatch config.
Example:
Getting the value when using await
:
const value = await browser.getText('#weblogin');
console.log('Value is:', value);
Getting the value when using a callback:
browser.getText('#weblogin', function(result) {
console.log('Value is:', result.value);
});
It is now possible to define session capabilities by setting an instance of a Selenium Capabilities object in your nightwatch.conf.js file as the capabilities
value.
You can refer to the Selenium documentation for all the available capabilities. Here's an example for defining a capabilities
object in your nightwatch.conf.js
for Chrome in headless mode:
Example:
// nightwatch.conf.js
const chrome = require('selenium-webdriver/chrome');
const capabilities = new chrome.Options();
capabilities.headless();
module.exports = {
test_settings: {
chrome: {
capabilities,
webdriver: {
start_process: true,
server_path: require('chromedriver').path,
cli_args: [
// --verbose
]
}
}
}
};
When writing an async
testcase, it is now possible to catch errors locally and prevent them from bubbling up to
the global error handler.
This can be used in implementing custom error handling or in more advanced scenarios. You can catch locally errors
thrown from generic commands like .perform()
or .waitUntil()
.
In the case of Nightwatch assertions, you can also catch the failed assertion error but the testcase will still fail.
Catching the error is the equivalent of setting abortOnFailure
flag to false
(or abortOnAssertionFailure
if
set globally). The purpose is to continue running the rest of the testcase, even after a failed assertion.
Example:
describe('demo async testcase with try/catch', function() {
test('sample test', async function() {
try {
const result = await browser.perform(function() {
throw new Error('Error from perform');
});
} catch (err) {
// The error throw in the perform() command is caught here
console.error('Error:', err);
}
try {
await browser.assert.visible('.wrong_selector');
} catch (err) {
// The assertion error is caught but the testcase will still fail at the end
console.log('Assertion Error:', err)
}
});
});
Below are new settings introduced in v2.0 and their default values:
{
// Set this to true to use the v1.x response format for commands when using ES6 async/await
backwards_compatibility_mode: false,
// Set this to true to disable the global objects such as element(), browser, by(), expect()
disable_global_apis: false,
// Ignore network errors (e.g. ECONNRESET errors)
report_network_errors: true,
// Interactive element commands such as "click" or "setValue" can be retried if an error occurred (such as an "element not interactable" error)
element_command_retries: 2,
// Sets the initial window size: {height: number, width: number}
window_size: undefined
}
Below are new webdriver
settings introduced in v2.0 for various browser drivers:
{
webdriver: {
// Sets the path to the Chrome binary to use. On Mac OS X, this path should reference the actual Chrome executable, not just the application binary (e.g. "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome").
chrome_binary: '',
// Sets the path to Chrome's log file. This path should exist on the machine that will launch Chrome.
chrome_log_file: '',
// Configures the ChromeDriver to launch Chrome on Android via adb.
android_chrome: false,
// Sets the path to the Edge binary to use.
edge_binary: '',
// Sets the path to the Edge binary to use.
edge_log_file: '',
// Sets the binary to use. The binary may be specified as the path to a Firefox executable or a desired release Channel.
firefox_binary: '',
// Sets the path to an existing profile to use as a template for new browser sessions. This profile will be copied for each new session - changes will not be applied to the profile itself.
firefox_profile: ''
}
}
We have tried to minimize the amount of breaking changes as much as possible but some of them were difficult to avoid. Some already deprecated functionality has also been removed.
Here's a summary. Let us know on Github if something else doesn't work after upgrading from a 1.5 or higher version.
when using ES6 async/await test cases, the result value of Nightwatch commands does not contain the status
and value
properties, but simply the value (this can be reversed by setting backwards_compatibility_mode
to true
in your nightwatch config)
setValue
now clears the value before sending the key strokes
sendKeys
is no longer an alias of setValue
, since it's not clearing the value but instead simply sends the keys
In case of element locate errors:
error
property which is an Error object instancehttpStatusCode
propertyvalue
propertyremoved proxy-agent
as dependency since it was frequently causing dependency issues; the proxy-agent package can be installed separately from NPM and used in the same way.
Published by beatfactor about 3 years ago
.verify
asserts with await
or waitFor
commands with abortOnFailure=false
didn't work in case of test failure (#2802, #2797)findElements
command (#2820)Published by beatfactor over 3 years ago
Published by beatfactor over 3 years ago
Published by beatfactor over 3 years ago
Nightwatch v1.7.0 introduces a few major new features and improvements for the test runner and also regarding the test syntax, such as:
It is now possible to use ES6 async/await syntax and also chain api commands together in the same test case; e.g.:
it('find elements example', async function(browser) {
const resultElements = await browser
.url('https://nightwatchjs.org')
.findElements('.features-container li');
resultElements.forEach(item => console.log('Element Id:', item.getId()))
});
You can now use the newer (Chromium-based) Microsoft Edge browser to run your Nightwatch tests. The auto-generated nightwatch.conf.js
already includes configuration, so you can just run by passing the edge
environment:
$ nightwatch --env edge
You can now run tests in parallel via workers in any browser. Not only that, but now you can also run via test workers across multiple browsers in parallel.
Example:
$ nightwatch --env edge,firefox,chrome --parallel
.getId()
convenience method.Example:
const resultElements = await browser.findElements('.features-container li');
resultElements.forEach(item => console.log('Element Id:', item.getId()))
const resultElement = await browser.findElement('.features-container li:first-child');
console.log('Element Id:', resultElement.getId());
Published by beatfactor over 3 years ago
Minor update to the auto-generated nightwatch config.
Published by beatfactor over 3 years ago
This is a minor update to increase the default timeout option for browserstack in the auto-generated nightwatch config.
Published by beatfactor over 3 years ago
This is a pre-release version for v1.7.3
Published by beatfactor over 3 years ago
Published by beatfactor over 3 years ago
Published by beatfactor over 3 years ago
Published by beatfactor over 3 years ago
element()
and elements()
commands where inconsistent when used on section elementsPublished by beatfactor almost 4 years ago
Published by beatfactor about 4 years ago
Nightwatch v1.5 introduces support for using third-party automation libraries directly into Nightwatch tests, thus providing significantly more flexibility in writing custom commands/assertions and also the test itself. This functionality also aims to eliminate some of the burden in choosing between various frameworks, by providing the possibility to combine the functionality offered by other libraries, such as selenium-webdriver or WebdriverIO, with Nightwatch.