Nightwatch v2.0-alpha

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

• New features
  • support for the WebDriver Actions API
  • support for Chrome DevTools protocol
  • support for Firefox specific commands
  • new "ensure" assertions
  • new element() global and support for using WebElements
  • support for using the Selenium "driver" object directly
  • support for using WebDriver BiDi
  • new API commands
    • getAccessibleName()
    • getAriaRole()
    • takeElementScreenshot()
    • uploadFile()
    • waitUntil()
• Improvements
  • Using async/await
  • Defining WebDriver capabilities
  • Using try/catch
• New config settings
  • WebDriver settings
• Breaking changes

New features

Support for the WebDriver Actions API

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.

Support for Chrome DevTools protocol

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:

• browser.chrome
  • .launchApp()
  • .getNetworkConditions()
  • .setNetworkConditions()
  • .sendDevToolsCommand()
  • .sendAndGetDevToolsCommand()
  • .setPermission()
  • .setDownloadPath()
  • .getCastSinks()
  • .setCastSinkToUse()
  • .startCastTabMirroring()
  • .getCastIssueMessage()
  • .stopCasting()

More info:

• selenium-webdriver/chrome
• selenium-webdriver/edge

Support for Firefox specific commands

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.

• browser.firefox
  • .getContext()
  • .setContext()
  • .installAddon()
  • .uninstallAddon()

More info:

• selenium-webdriver/firefox

New .ensure assertions

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')  
  });
});

New element() global and support for using WebElements

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);
  });
});

Using the Selenium WebDriver object directly

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)
  });
});

Using WebDriver BiDi in Nightwatch

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)
  });
});

New API commands

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);

Improvements

Using async/await

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);  
});

Defining WebDriver capabilities

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
        ]
      }
    }
  }
};

Using try/catch

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)
    }
  });
});

New config settings

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
}

New WebDriver config settings

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: ''
  }
}

Breaking changes

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:

  • changes in the result object:
    • contains an error property which is an Error object instance
    • no longer contains httpStatusCode property
    • no longer contains value property

• removed 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.