Nightwatch.js is a Selenium wrapper that provides several out-of-the-box commands and assertions for performing various operations on the page. The commands and assertions are clean and straightforward, enabling you to develop tests very quickly using Javascript (specifically, Node.js). It allows you to create custom helpers to increase your testing capabilities.
In this article, we’ll walk through developing a set of test scripts for front-end applications quickly and effortlessly using Nightwatch.
Getting Started with Nightwatch.js
This blog helps you to set up Nightwatch.js by understanding the required files and folder structure, the ins and outs of configuration files, and how to write and run tests both locally and in a cloud-based environment such as Sauce Labs.
It starts by cloning the nightwatch-skeleton GitHub repo and completing the prerequisites below:
Step | Action | |
1 | Open Terminal | |
2 | Make Directory | $ mkdir ~/work/github |
3 | Clone Nightwatch-Skeleton | $ git clone git@github.com:gsypolt/nighwatch-skeleton.git |
4 | Download Node.js (version 6.5 or later) | Go to https://nodejs.org/en/ |
5 | Change Directory | $ cd ~/work/github/nightwatch-skeleton |
6 | Install Nightwatch-Skeleton Node Package Dependencies | $ npm install |
How Is Nightwatch Skeleton Going to Help?
Before getting into the code and learning how to develop tests using Nightwatch.js, it's worth understanding the nightwatch-skeleton folder structure and configuration. In this post, we’re going to dive into some very specific configurations and custom commands, but most importantly, this post will demonstrate how the nightwatch-skeleton allows testers to come up to speed faster with less worry about the configuration and the standard burden.
The custom-commands folder contains a list of custom helpers to increase your testing capabilities and reusability.
nightwatch.json is a configuration file which tells the Nightwatch tool where to find the stand-alone Selenium binary, browser drivers, location of the test, environment profile, and more.
The package.json contains the metadata and node package dependencies for the project
The ci/functional-test.Jenkinsfile file is a template to help quickly add your functional tests to the Jenkins pipeline.
To reduce copying and pasting the block of code at the end of each test script, the custom helper eliminates the need to duplicate code within all of the test scripts. Code duplication is a terrible coding practice because it’s a maintenance nightmare (and that’s just the start). Reference the custom_command directory inside the Nightwatch skeleton to locate more custom helpers to use. (We use them every day.)
The configuration is the heart and soul of a Nightwatch test project. Setting up any test automation project can be tricky and confusing, with weak documentation. Let's take a closer look at the configuration file and highlight some important lines of code, looking at nightwatch.json below.
LINE 1 Where the tests are located
LINE 3 The location of the custom commands that will be loaded
LINES 10-12 The test_workers set to true allows for the running of individual tests in parallel, and for setting the number of workers to auto or a number. WARNING: If the number of workers is set higher than the number of CPUs where the tests are running in parallel, you will experience random test failures.
LINE 2 set to true, manage the Selenium process for local execution
LINE 3 is the location of the stand-alone Selenium binary. This requires that the start_process = true.
LINES 7-10 - A list of CLI arguments passed to the Selenium process (where to set browser drivers for local execution).
The default test_settings will be passed to the Nightwatch instance, but environment profile settings could overwrite specific default test_settings during runtime.
LINES 16-20 The desiredCapabilities object will be passed to the Selenium WebDriver when a new session is created. I prefer to keep the desired capabilities lean. Our standard is to set the browser name as part of the environment profile. (I will go into more detail in the next code section.) The name tags javascriptEnabled and assertSslCerts are the defaults, and everything else is set inside the environment profile.
LINE 29 Here, we set stand-alone Selenium as false and control this property from the environment profile. We default to executing all tests on Sauce Labs over running them locally.
The mobile sauce-android profile contains the settings that either add or override the settings in the default profile. In this example, the desired capabilities and global variables for the mobile web environment are added. (Please note that Appium is used in a remote environment to launch the virtual machine on Sauce Labs for mobile web testing.)
The local-chrome profile is necessary while developing tests. The developer can leverage the reduced system latency to accelerate testing. The settings allow the Selenium server to run locally and use local resources (browsers, platforms and associated drivers) to perform the test.
To build your own test profiles for Sauce Labs, go to Sauce Labs’ Platform Configurator to find the capabilities needed for Sauce Labs. You can find all the above code snippets at: gist.github.com/gsypolt/nightwatch-code-snippets or https://github.com/gsypolt/nighwatch-skeleton.
Learn How to Write Test Scripts
The nightwatch-skeleton comes with sample tests developed with our standard guidelines. The best place to get started is getting familiar with the Nightwatch API Reference Document. Here are some of our best practices for writing test scripts (not all of them):
Before and After test hooks - LINE 5 and LINE 14.
Tags - Test can have multiple tags to groups the tests (keep them meaningful) - LINE 6.
In general, most of the tests do a user action (which is usually a .click action). At least one .assert statement should be included - LINE 14.
Include GIVEN WHEN THEN comment statements to explain what the test does and its readability - LINES 13, 15, and 17.
The perform blocks are used to synchronize the test steps, as Nightwatch.js is asynchronous in nature. (We use the perform blocks over explicit waits) - LINES 15 and 19.
Running Tests
Now you're ready to run Nightwatch.js tests. The cloned GitHub repo already has a few sample tests ready to execute. The same test files can be executed locally and remotely through Sauce Labs as long as you have credentials. The current configuration automatically starts the Selenium server and launches the desired browser based on the selected environment. Various environment profiles are available by default in the nightwatch.json file. Here are the commands to run the tests for a specific environment defined in the nightwatch.json file:
This command runs a specific test in the test directory:
$ cd ~/work/github/nightwatch-skeleton
$ nightwatch /test_path/test_dir/*.js
This command runs the test in a specific environment profile available:
$ nightwatch --e <env-name>/test_path/test_dir/*.js
This command runs all the tests under the specific tag-name:
$ nightwatch --e <env-name> --tags <tag-name>
There are a few different options for how to use the test runner, depending on your installation type or strategy. (Reference the Nightwatch running tests documentation.)
Conclusion
So far, you have learned how to get started by cloning my nightwatch-skeleton and downloading and installing project dependencies, and you’ve learned additional information about how to configure and tune Nightwatch.js. I only briefly covered how to write tests, but with these steps, you have all the necessary tools to create tests and run them locally or remotely.
For that, you have to consider some aspects, but please note that there are no silver bullets here. Depending on your business needs, you may answer the following questions differently:
Where should I run tests? On staging? On production?
When do I build my test pipeline?
What are the test scenarios I want to test?
When and who should write end-to-end tests?
In closing, a lot of the credit for the nightwatch-skeleton implementation came from my amazing Quality Engineering team at Gannett | USA Today Network, with me spearheading the design.
Greg Sypolt (@gregsypolt) is Director of Quality Engineering at Gannett | USA Today Network, a Fixate IO Contributor, and co-founder of Quality Element. He is responsible for test automation solutions, test coverage (from unit to end-to-end), and continuous integration across all Gannett | USA Today Network products, and has helped change the testing approach from manual to automated testing across several products at Gannett | USA Today Network. To determine improvements and testing gaps, he conducted a face-to-face interview survey process to understand all product development and deployment processes, testing strategies, tooling, and interactive in-house training programs.
