Introduction to writing tests for web applications | Developer Guide

Overview

Nightwatch provides simple and comprehensive APIs for interacting with web elements and performing various actions and assertions. In Nightwatch v3, brand new element APIs are introduced to make writing tests even simpler and more concise.

The Nightwatch inspector makes it easier to author tests as it provides selector recommendations that are durable in the longer run.

If you know very little or no coding, you can also use our Chrome recorder extension to record tests and run them using Nightwatch.

Finding elements

Before you can interact with elements or perform assertions, you will have to find the elements from the DOM tree using selectors. Nightwatch supports a variety of selectors to make finding elements a breeze. You can do so using .find() & .findAll() related commands:

CSS selectors :

browser.element.find('css selector');
browser.element.findAll('css selector');

xPath selector :

browser.element.find(by.xpath(('xpath string'));
browser.element.findAll(by.xpath(('xpath string'));

By role :

browser.element.findByRole('role');
browser.element.findAllByRole('role');

By text :

browser.element.findByText('text');
browser.element.findAllByText('text');

By placeholder text :

browser.element.findByPlaceholderText('placeholder text');
browser.element.findAllByPlaceholderText('placeholder text');

By label text :

browser.element.findByLabelText('label text');
browser.element.findAllByLabelText('label text');

By alt text :

browser.element.findByAltText('alt text');
browser.element.findAllByAltText('alt text');

Along with the find commands, Nightwatch also provides with convenience methods that help finding methods in more complex scenarios

Finding nth element from an array of elements .nth(index)
Finding count of element array .count()

Finding nested elements

On top of this powerful set of selectors, Nightwatch also supports selector chaining:

browser.element.find('CSS selector').findByText('text').click();
// or
browser.element.findAll('CSS selector').nth(2).findByText('text').click();

For a more detailed guide & examples on selectors, please refer to this guide.

Commands

Once you find elements, you can interact with them using commands

Interaction commands

Click :

browser.element.find('selector').click();

Double Click :

browser.element.find('selector').doubleClick();

Right Click :

browser.element.find('selector').rightClick();

Type into an input :

browser.element.find('selector').sendKeys('text');

Set Value :

browser.element.find('selector').setValue();

Clear :

browser.element.find('selector').clear();

Instead of .find(), you could also have used other find related methods such as .findByText(), .findByRole() followed by the command

Get element details

Get text :

browser.element.find('selector').getText();

Get value :

browser.element.find('selector').getValue();

Get tag name :

browser.element.find('selector').getTagName();

Get attribute :

browser.element.find('selector').getAttribute();

Get CSS property :

browser.element.find('selector').getCssProperty();

Get ID :

browser.element.find('selector').getId();

Get Accessibility name :

browser.element.find('selector').getAccessibilityName();

Get rect :

browser.element.find('selector').getRect();

Update element details

Set text :

browser.element.find('selector').setText('text');

Set attribute :

browser.element.find('selector').setAttributes('attribute', 'attribute value');

Setting browser context

Set Geolocation :

browser.setGeolocation({latitude: , longitude: , accuracy: 100});

Refer to this guide for detailed examples.

You can also write custom commands with Nightwatch.Try now

Assertions

The main point of writing automated tests is setting assertions to pass. There are 2 ways to do assertions with Nightwatch

You can use the built-in assertions

Text equals :

browser.element.find('selector').getText().assert.equals('text');

Text contains :

browser.element.find('selector').getText().assert.contains('text');

Text matches :

browser.element.find('selector').getText().assert.matches('regex');

Value equals :

browser.element.find('selector').getValue().assert.equals('text');

Value contains :

browser.element.find('selector').getValue().assert.contains('text');

Value matches :

browser.element.find('selector').getValue().assert.matches('regex');

URL equals :
```
browser.assert.urlEquals('text');
```
URL contains :
```
browser.assert.urlContains('text');
```
URL matches :
```
browser.assert.urlMatches('regex');
```

Visible :

browser.element.find('selector').assert.visible();

If these assertions don’t suffice, you can write your own custom assertions. Learn how

Chai expects

If you prefer Chai style asserts, you can also use the expect() to perform assertions

Text equals :
```
expect(element).text.to.equal();
```
Text contains :
```
expect(element).text.to.contain();
```
Text equals :
```
expect(element).text.to.match();
```
Value equals :
```
expect(element).value.to.equal();
```
Value contains :
```
expect(element).value.to.contain();
```
Value equals :
```
expect(element).value.to.match();
```
URL equals :
```
expect(brower.url()).to.equal();
```
URL contains :
```
expect(brower.url()).to.contain();
```
URL matches :
```
expect(brower.url()).to.match();
```
Visible :
```
expect(element).to.be.visible();
```

For detailed examples around assertions, refer to this article

Using Nightwatch inspector

Nightwatch inspector is a point-and-click tool designed to save your time while authoring tests and help you write more durable tests. It also allows you to try out Nightwatch commands from devtools itself. Learn more.

Record using Chrome dev tools

Alternatively, Nightwatch provides tools to help you get started by recording your test actions on screen and generate Nightwatch test scripts automatically without having to write any code. Explore Create Nightwatch test using Google Chrome DevTools Recorder for more information.