.expect API Suggest edits

Overview

Nightwatch provides a fluent BDD-style interface for performing assertions on elements, defined on the expect namespace on the main Nightwatch instance. It is based on the Chai Expect assertion library and provides a greater level of flexibility, also adding new capabilities over the classic assert interface.

It uses a chain-able language to construct assertions given an element specified by a css/xpath selector. A simple example looks like the following:

describe('expect example', function() {
  it('sample test', function (browser) {
    // start with identifying the element
    // and then assert the element is present
    browser.expect.element('#main').to.be.present;

    // or assert the element is visible
    browser.expect.element('#main').to.be.visible;
  });
}

Language Chains

The following are provided as chainable getters to improve the readability of your assertions. They do not provide testing capabilities and the order is not important.

  • to
  • be
  • been
  • is
  • that
  • which
  • and
  • has
  • have
  • with
  • at
  • does
  • of

.equal(value)/.contain(value)/.match(regex)

These methods will perform assertions on the specified target on the current element. The targets can be an attribute value, the element's inner text and a css property.

this.demoTest = function (browser) {
  browser.expect.element('#main').text.to.equal('The Night Watch');

  browser.expect.element('#main').text.to.contain('The Night Watch');

  browser.expect.element('#main').to.have.css('display').which.equals('block');
};

.startWith(value)/.endWith(value)

Same as equal / contain / match.

this.demoTest = function (browser) {
  browser.expect.element('#main').text.to.endWith('Watch');

  browser.expect.element('#main').text.to.startWith('The');
};

.not

Negates any of assertions following in the chain.

this.demoTest = function (browser) {
  browser.expect.element('#main').text.to.not.equal('The Night Watch');

  browser.expect.element('#main').text.to.not.contain('The Night Watch');

  browser.expect.element('#main').to.have.css('display').which.does.not.equal('block');
};

.before(ms)/.after(ms)

These methods perform the same thing which is essentially retrying the assertion for the given amount of time (in milliseconds). before or after can be chained to any assertion and thus adding retry capability.

You can change the polling interval by defining a waitForConditionPollInterval property (in milliseconds) as a global property in your nightwatch.json or in your external globals file. Similarly, a default timeout can be specified as a global waitForConditionTimeout property (in milliseconds).

this.demoTest = function (browser) {
  browser.expect.element('#main').text.to.contain('The Night Watch').before(1000);

  browser.expect.element('#main').text.to.not.contain('The Night Watch').after(500);
};

expect.cookie()

Expect assertions operating on a single cookie after retrieving the entire cookie string, using .getCookies().
Syntax:
browser.expect.cookie('cookie-name', ['cookie-domain'])
this.demoTest = function (browser) {
  browser.expect.cookie('cookie-name').to.contain('cookie-value');
  browser.expect.cookie('cookie-name').to.match(/regex/);
  browser.expect.cookie('loginCookie', 'example.org').to.contain('cookie-value');
};

Parameters:

Name Type description
name String The name of the cookie to be inspected.
domain
Optional		 String The domain name on which the cookie is set to.

expect.element() Suggest edits

Expect assertions operating on a single element, specified by its CSS/Xpath selector.

Syntax:
browser.element('#selector')
Parameters:
Name Type description
selector String The CSS/XPath selector of the element to be inspected.

.a(type)Suggest edits

Checks if the type (i.e. tag name) of a specified element is of an expected value.

Parameters:
Name Type description
type string

The expected type
message
Optional		 string

Optional log message to display in the output. If missing, one is displayed by default.
Usage:
this.demoTest = function (browser) {
  browser.expect.element('#q').to.be.an('input');
  browser.expect.element('#q').to.be.an('input', 'Testing if #q is an input');
  browser.expect.element('#w').to.be.a('span');
}

.activeSuggest edits

Property that checks if an element is active in the DOM.

Usage:
this.demoTest = function (browser) {
  browser.expect.element('#main').to.be.active;
  browser.expect.element('#main').to.not.be.active;
  browser.expect.element('#main').to.be.active.before(100);
};

.attribute(name)Suggest edits

Checks if a given attribute of an element exists and optionally if it has the expected value.

Parameters:
Name Type description
attribute string

The attribute name
message
Optional		 string

Optional log message to display in the output. If missing, one is displayed by default.
Usage:
this.demoTest = function (browser) {
  browser.expect.element('body').to.have.attribute('data-attr');
  browser.expect.element('body').to.not.have.attribute('data-attr');
  browser.expect.element('body').to.not.have.attribute('data-attr', 'Testing if body does not have data-attr');
  browser.expect.element('body').to.have.attribute('data-attr').before(100);
  browser.expect.element('body').to.have.attribute('data-attr')
    .equals('some attribute');
  browser.expect.element('body').to.have.attribute('data-attr')
    .not.equals('other attribute');
  browser.expect.element('body').to.have.attribute('data-attr')
    .which.contains('something');
  browser.expect.element('body').to.have.attribute('data-attr')
    .which.matches(/^something\ else/);
};

.css(property)Suggest edits

Checks a given css property of an element exists and optionally if it has the expected value.

Parameters:
Name Type description
property string

The css property name
message
Optional		 string

Optional log message to display in the output. If missing, one is displayed by default.
Usage:
this.demoTest = function (browser) {
  browser.expect.element('#main').to.have.css('display');
  browser.expect.element('#main').to.have.css('display', 'Testing for display');
  browser.expect.element('#main').to.not.have.css('display');
  browser.expect.element('#main').to.have.css('display').before(100);
  browser.expect.element('#main').to.have.css('display').which.equals('block');
  browser.expect.element('#main').to.have.css('display').which.contains('some value');
  browser.expect.element('#main').to.have.css('display').which.matches(/some\ value/);
};

.enabledSuggest edits

Property that checks if an element is currently enabled.

Usage:
this.demoTest = function (browser) {
  browser.expect.element('#weblogin').to.be.enabled;
  browser.expect.element('#main').to.not.be.enabled;
  browser.expect.element('#main').to.be.enabled.before(100);
};

.presentSuggest edits

Property that checks if an element is present in the DOM.

Usage:
this.demoTest = function (browser) {
  browser.expect.element('#main').to.be.present;
  browser.expect.element('#main').to.not.be.present;
  browser.expect.element('#main').to.be.present.before(100);
};

.property(name)Suggest edits

Checks if a given DOM property of an element has the expected value. For all the available DOM element properties, consult the Element doc at MDN.

Parameters:
Name Type description
property string

The property name
message
Optional		 string

Optional log message to display in the output. If missing, one is displayed by default.
Usage:
this.demoTest = function (browser) {
  browser.expect.element('body').to.have.property('className').equals('test-class');
  browser.expect.element('body').to.have.property('className').matches(/^something\ else/);
  browser.expect.element('body').to.not.have.property('classList').equals('test-class');
  browser.expect.element('body').to.have.property('classList').deep.equal(['class-one', 'class-two']);
  browser.expect.element('body').to.have.property('classList').contain('class-two');
  browser.expect.element('body').to.have.domProperty('classList').contain('class-two');
};

.selectedSuggest edits

Property that checks if an OPTION element, or an INPUT element of type checkbox or radio button is currently selected.

Usage:
this.demoTest = function (browser) {
  browser.expect.element('#main').to.be.selected;
  browser.expect.element('#main').to.not.be.selected;
  browser.expect.element('#main').to.be.selected.before(100);
};

.textSuggest edits

Property that retrieves the text contained by an element. Can be chained to check if contains/equals/matches the specified text or regex.

Usage:
this.demoTest = function (browser) {
  browser.expect.element('#main').text.to.equal('The Night Watch');
  browser.expect.element('#main').text.to.not.equal('The Night Watch');
  browser.expect.element('#main').text.to.equal('The Night Watch').before(100);
  browser.expect.element('#main').text.to.contain('The Night Watch');
  browser.expect.element('#main').text.to.match(/The\ Night\ Watch/);
};

.valueSuggest edits

Property that retrieves the value (i.e. the value attributed) of an element. Can be chained to check if contains/equals/matches the specified text or regex.

Usage:
this.demoTest = function (browser) {
  browser.expect.element('#q').to.have.value.that.equals('search');
  browser.expect.element('#q').to.have.value.not.equals('search');
  browser.expect.element('#q').to.have.value.which.contains('search');
  browser.expect.element('#q').to.have.value.which.matches(/search/);
};

.visibleSuggest edits

Property that asserts the visibility of a specified element.

Usage:
this.demoTest = function (browser) {
  browser.expect.element('#main').to.be.visible;
  browser.expect.element('#main').to.not.be.visible;
  browser.expect.element('#main').to.be.visible.before(100);
};

expect.elements() Suggest edits

Expect assertions operating on a collection of elements, specified by a CSS/Xpath selector. So far only .count is available.

Syntax:
browser.elements('#selector')
Parameters:
Name Type description
selector String The CSS/XPath selector of the collection of elements to be inspected.

.elements().count

Checks if the number of elements specified by a selector is equal or not to a given value.

Usage:
this.demoTest = function (browser) {
  browser.expect.elements('div').count.to.equal(10);
  browser.expect.elements('p').count.to.not.equal(1);
}

expect.title() Suggest edits

Retrieves the page title value in order to be used for performing equal, match or contains assertions on it.
Usage:
this.demoTest = function (browser) {
  browser.expect.title().to.contain('value');
  browser.expect.title().to.match(/value/);
};

expect.url()

Retrieves the page url value in order to be used for performing equal, match or contains assertions on it.
Usage:
this.demoTest = function (browser) {
  browser.expect.url().to.contain('https://');
  browser.expect.url().to.endWith('.org');
};