Applies to CrossBrowserTesting SaaS, last modified on November 26, 2020

Nightwatch.JS provides a powerful commandline tool that allows you to run end-to-end Selenium tests with JavaScript language bindings, all the while avoiding asynchronous commands and racing conditions. To get started, you will need NPM. It comes with Node, and you can find setup instructions for the whole package here. Once you have NPM, create a directory where you would like your test projects to be stored. Navigate to that directory. From there, we will initialize it as a Node Package by using the following:

user$ npm init

From there, we will need to install Nightwatch as well as cbt_tunnels for initializing a local connection. Run the following command from that directory.

user$ npm install nightwatch
user$ npm install cbt_tunnels

Next, we need to create JSON object that Nightwatch will point to when deciding how to configure the environment we will be testing on. In our case, we will be setting it up to test in CrossBrowserTesting's cloud. Create a file called nightwatch.json, and copy to following environment configuration therein:

  "src_folders" : ["tests"],
  "output_folder" : "reports",
  "custom_commands_path" : "",
  "custom_assertions_path" : "",
  "page_objects_path" : "",
  "globals_path" : "",                 // can leave this blank for now. we will use it later for local connection setup.

  "test_settings" : {
    "default" : {
      "launch_url" : "<launch_url_of_choice",
      "selenium_port" : 80,
      "selenium_host" : "",
      "silent": true,
      "screenshots" : {
        "enabled" : false,
        "path" : ""
      "username": "<your_cbt_username>",
      "access_key": "<your_cbt_authkey>",
      "desiredCapabilities": {
        "acceptSslCerts": "1",
        "browserName": "Chrome",
        "version": "75",
        "build": "1.0",
        "javascriptEnabled": "1",
        "name": "NightwatchJSExample",
        "platform" : "Windows 10",
        "record_network" : "false",
        "record_video" : "true",
        "screen_resolution" : "1366x768"

As you can see, you will need to setup the configuration object to include your CrossBrowserTesting username and authorization key, which can be found in our API as well as on the Selenium dashboard.

Finally, we will create a tests directory where all of our actual test scripts will reside. While in your current directory, create a folder called tests. Within it, create a file called first_test.js and copy to following code:

this.toDos = function(browser) {
      .setValue('//*[@id="todotext"]', 'run your first selenium test')
      .assert.containsText('li:nth-child(4) > span', 'run your first selenium test')

Back up to tests parent directory, and run the following command:

user$ nightwatch

Head over to CrossBrowserTesting's dashboard, and you should see a test starting up on a Windows 7×64 / Internet Explorer 10 configuration. We can start adding more tests to tests to the tests directory, and Nightwatch will take care of the rest. Be sure to have a look at Nightwatch's API to ensure you are making use of their best practices. If at any point, you have trouble getting your tests running with us, do not hesitate to contact Support. We are always happy to help.

Local connection usage

If you are interested in testing behind your firewall, CrossBrowserTesting definitely supports that. We will just need to make a few changes to how Nightwatch starts tests. Before each test, we will start a tunnel, and we will stop it afterward. Alternatively, you can make a few small changes to make cbt_tunnels start before each suite. We will cover that as well.

Within your current directory, create a file called globals.js. In this file, copy the following code:

var cbt = require('cbt_tunnels');
module.exports = {
  beforeEach : function(done) {
    console.log('Starting up tunnel');
      'username': '<your_cbt_username>',
      'authkey': '<your_auth_key>'
    }, function(err, data) {
      if (err) {
      } else {
  afterEach : function(done) {
    console.log('Closing Down Tunnel');

If you installed cbt_tunnels earlier, this beforeEach and afterEach functions should work fine. If you would like to run them before each suite of tests, just change these to general 'before' and 'after' functions. We need to make one more change to our nightwatch.json file. Remember that globals path from before? Now we need to have it point to the path of this globals.js file. Once that is been completed, you are good to go. Cbt_tunnels will start before and after each test, and you can test pages behind your firewall or proxy across all of CrossBrowserTesting's OS/Device/Browser combinations.

If you have any trouble establishing a local connection or would like to know more about how it works, we have a separate repository for cbt_tunnels which can be found here.


My tests keep timing out on iOS devices!

Because of the time it takes to start Appium on iOS devices, you may be coming right up against Nightwatch’s default 60 second timeout. To change this, change your nightwatch.json file to include the following:

"request_timeout_options": {
"timeout": 300000,
"retry_attempts": 2

See Also

Test Frameworks and Tools
About Selenium Testing
Selenium and JavaScript
WebDriverIO and CrossBrowserTesting

Highlight search results