Assertions Suggest edits

The built-in extendable assert/verify library is available on the Nightwatch instance as two namespaces containing the same methods which perform assertions on elements:

  • .assert - when an assertion fails, the test ends, skipping all other assertions.
  • .verify - when an assertion fails, the test logs the failure and continues with other assertions.



The following will end the test:

browser.assert.visible('.non_existing');

However this will just log the failure and continue:

browser.verify.visible('.non_existing');

Basic Assertions

The methods from the Node.js assert module are also available on the .assert/.verify namespaces and can be used.

Negate (".not") Assertions

Since version 1.3, all the assertions (including custom defined ones) have a ".not" counterpart, which can be used to assert the opposite.

And thus, assertions like elementNotPresent, cssClassNotPresent, hidden are obsolete and have been deprecated.

Example:
describe('Demo .not assertion', function() {
  it('demo test', function(browser) {
    browser.init();

    browser
      .assert.not.elementPresent('.not_present') // previously .assert.elementNotPresent()
      .assert.not.visible('.non_visible') // previously .assert.hidden()
      .assert.not.urlContains('http://');

    // ...
  })
})

Automatic Retries

By default, Nightwatch will automatically retry failed assertions for up to 5000ms. This can be configured by setting the property retryAssertionTimeout (in milliseconds) in your globals (see also working with test globals.

If the given timeout is reached test runner will give up retrying and will mark the assertion as failed.

Example config:

{
  src_folders: ['tests'],

  test_settings: {
    default: {
      launch_url: 'https://nightwatchjs.org',

      globals: {
        myGlobalVar: 'some value',
        retryAssertionTimeout: 5000
      }
    }
  }
}

assert[.not].attributeContains(element, attribute, expected, [msg])

Checks if the given attribute of an element contains the expected value.

Parameters:
Name Type description
element string|object The selector (CSS/Xpath) used to locate the element. Can either be a string or an object which specifies element properties.
attribute string The attribute name
expected string The expected contained value of the attribute to check.
message
Optional		 string Optional log message to display in the output. If missing, one is displayed by default.
Usage:
describe('attributeContains demo', function () {
  it('demo test', function(browser) {
    browser.assert.attributeContains('#someElement', 'href', 'google.com');
  });
};

assert[.not].attributeEquals(element, attribute, expected, [msg])

Checks if the given attribute of an element has the expected value.

Parameters:
Name Type description
element string|object The selector (CSS/Xpath) used to locate the element. Can either be a string or an object which specifies element properties
attribute string The attribute name
expected string The expected value of the attribute to check.
msg
Optional		 string Optional log message to display in the output. If missing, one is displayed by default.
Usage:
describe('attributeEquals demo', function () {
  it('demo test', function(browser) {
    browser.assert.attributeEquals("body", "data-attr", "some value");
  });
};

assert[.not].attributeMatches(element, attribute, regex, [msg])

Checks if the given attribute of an element matches a regular expression.

Parameters:
Name Type description
element string|object The selector (CSS/Xpath) used to locate the element. Can either be a string or an object which specifies element properties
attribute string The attribute name
regex string|RegExp The regular expression to match the value of the attribute against.
msg
Optional		 string Optional log message to display in the output. If missing, one is displayed by default.
Usage:
describe('attributeMatches demo', function () {
  it('demo test', function(browser) {
    browser.assert.attributeMatches("body", "data-attr", /^some-regex$/);
  });
};

assert[.not].cssProperty(element, cssProperty, expected, [msg])

Checks if the specified css property of a given element has the expected value.

Parameters:
Name Type description
element string|object The selector (CSS / Xpath) used to locate the element. Can either be a string or an object which specifies element properties.
cssProperty string The CSS property.
expected string|number The expected value of the css property to check.
msg
Optional		 string Optional log message to display in the output. If missing, one is displayed by default.
Usage:
describe('cssProperty demo', function () {
  it('demo test', function(browser) {
    browser.assert.cssProperty("#main", "display", "block");
  });
};

assert[.not].domPropertyContains(element, domProperty, value, [msg])

Checks if the specified DOM property of a given element has the expected value. For all the available DOM element properties, consult the Element doc at MDN. Several properties can be specified (either as an array or command-separated list). Nightwatch will check each one for presence.

Parameters:
Name Type description
element string|object The selector (CSS / Xpath) used to locate the element. Can either be a string or an object which specifies element properties.
domProperty string The DOM property name.
value string|number The value which for which to check the DOM property.
msg
Optional		 string Optional log message to display in the output. If missing, one is displayed by default.
Usage:
describe('domPropertyContains demo', function () {
  it('demo test', function(browser) {
    browser.assert.domPropertyContains('#main', 'classList', 'visible');

  // in case the resulting property is an array, several elements could be specified
  browser.assert.domPropertyEquals('#main', 'classList', ['class-one', 'class-two']);
  browser.assert.domPropertyEquals('#main', 'classList', 'class-one,class-two');
  });
};

assert[.not].domPropertyEquals(element, domProperty, value, [msg])

Checks if the specified DOM property of a given element has the expected value. For all the available DOM element properties, consult the [Element doc at MDN](https://developer.mozilla.org/en-US/docs/Web/API/element). If the result value is JSON object or array, a deep equality comparison will be performed.

Parameters:
Name Type description
element string|object The selector (CSS / Xpath) used to locate the element. Can either be a string or an object which specifies element properties.
domProperty string The DOM property name.
value string|number The value of the DOM property to check.
msg
Optional		 string Optional log message to display in the output. If missing, one is displayed by default.
Usage:
describe('domPropertyEquals demo', function () {
  it('demo test', function(browser) {
    browser.assert.domPropertyEquals('#main', 'className', 'visible');

  // deep equal will be performed
  browser.assert.domPropertyEquals('#main', 'classList', ['class-one', 'class-two']);

  // split on ',' and deep equal will be performed
  browser.assert.domPropertyEquals('#main', 'classList', 'class-one,class-two']);
  });
};

assert[.not].domPropertyMatches(element, domProperty, regex, [msg])

Check if specified DOM property value of a given element matches a regex. For all the available DOM element properties, consult the [Element doc at MDN](https://developer.mozilla.org/en-US/docs/Web/API/element).

Parameters:
Name Type description
element string|object The selector (CSS / Xpath) used to locate the element. Can either be a string or an object which specifies element properties.
domProperty string The DOM property name.
regex string|RegExp Regex to match against
msg
Optional		 string Optional log message to display in the output. If missing, one is displayed by default.
Usage:
describe('domPropertyMatches demo', function () {
  it('demo test', function(browser) {
    browser.assert.domPropertyMatches('#main', 'tagName', /^frame/);
  });
};

assert[.not].elementsCount(definition, [msg])

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

Parameters:
Name Type description
definition string|object The selector (CSS / Xpath) used to locate the elements. Can either be a string or an object which specifies element properties.
msg
Optional		 string Optional log message to display in the output. If missing, one is displayed by default.
Usage:
describe('elementsCount demo', function () {
  it('demo test', function(browser) {
    browser.assert.elementsCount('div', 10);
  });
};

assert[.not].elementPresent(element, [msg])

Checks if the given element exists in the DOM.

Parameters:
Name Type description
definition string|object The selector (CSS / Xpath) used to locate the element. Can either be a string or an object which specifies element properties.
msg
Optional		 string Optional log message to display in the output. If missing, one is displayed by default.
Usage:
describe('elementPresent demo', function () {
  it('demo test', function(browser) {
    browser.assert.elementPresent("#main");
  });
};

assert[.not].hasClass(element, className, [msg])

Checks if the given element has the specified CSS class. Multiple css classes can be specified either as an array or a space-delimited string. In case the expected value is a space delimited string, the order is not taken into account - each value will individually be checked against.

Parameters:
Name Type description
definition string|object The selector (CSS / Xpath) used to locate the element. Can either be a string or an object which specifies element properties.
className string The CSS class to look for.
msg
Optional		 string Optional log message to display in the output. If missing, one is displayed by default.
Usage:
describe('hasClass demo', function () {
  it('demo test', function(browser) {
    browser.assert.hasClass("#main", "container");
  browser.assert.hasClass('#main', ['visible', 'container']);
  browser.assert.hasClass('#main', 'visible container');
  });
};

assert[.not].hasAttribute(element, expectedAttribute, [msg])

Checks if the given element contains the specified DOM attribute. Multiple attributes can be specified either as an array or a space-delimited string. In case the expected value is a space delimited string, the order is not taken into account - each value will individually be checked against.

Parameters:
Name Type description
element string|object The selector (CSS / Xpath) used to locate the element. Can either be a string or an object which specifies element properties.
expectedAttribute string The DOM attribute to look for.
msg
Optional		 string Optional log message to display in the output. If missing, one is displayed by default.
Usage:
describe('hasAttribute demo', function () {
  it('demo test', function(browser) {
    browser.assert.hasAttribute("#main", "data-track");
  browser.assert.hasAttribute('#main', ['data-track', 'selected']);
  browser.assert.hasAttribute('#main', 'selected enabled');
  });
};

assert[.not].enabled(element, [msg])

Checks if the given element is enabled (as indicated by the 'disabled' attribute).

Parameters:
Name Type description
definition string|object The selector (CSS / Xpath) used to locate the element. Can either be a string or an object which specifies element properties.
msg
Optional		 string Optional log message to display in the output. If missing, one is displayed by default.
Usage:
describe('enabled demo', function () {
  it('demo test', function(browser) {
    browser.assert.enabled('.should_be_enabled');
    browser.assert.enabled({selector: '.should_be_enabled'});
    browser.assert.enabled({selector: '.should_be_enabled', supressNotFoundErrors: true});
  });
};

assert[.not].selected(element, [msg])

Checks if the given element is selected.

Parameters:
Name Type description
element string|object The selector (CSS / Xpath) used to locate the element. Can either be a string or an object which specifies element properties.
msg
Optional		 string Optional log message to display in the output. If missing, one is displayed by default.
Usage:
describe('selected demo', function () {
  it('demo test', function(browser) {
    browser.assert.selected('#main select option.first');
  });
};

assert[.not].textContains(value, [msg])

Checks if the given element contains the specified text.

Parameters:
Name Type description
element string|object The selector (CSS / Xpath) used to locate the element. Can either be a string or an object which specifies element properties.
value string The value to look for.
msg
Optional		 string Optional log message to display in the output. If missing, one is displayed by default.
Usage:
describe('textContains demo', function () {
  it('demo test', function(browser) {
    browser.assert.textContains('#main', 'The Night Watch');
  });
};

assert[.not].textEquals(element, value, [msg])

Check if an element's inner text equals the expected text.

Parameters:
Name Type description
element string|object The selector (CSS / Xpath) used to locate the element. Can either be a string or an object which specifies element properties.
value string The value to look for.
msg
Optional		 string Optional log message to display in the output. If missing, one is displayed by default.
Usage:
describe('textEquals demo', function () {
  it('demo test', function(browser) {
    browser.assert.textEquals('#main', 'The Night Watch');
  });
};

assert[.not].textMatches(element, regex, [msg])

Checks if the page title contains the given value.

Parameters:
Name Type description
element string|object The selector (CSS / Xpath) used to locate the element. Can either be a string or an object which specifies element properties.
regex string|RegExp The regex to match against.
msg
Optional		 string Optional log message to display in the output. If missing, one is displayed by default.
Usage:
describe('textMatches demo', function () {
  it('demo test', function(browser) {
    browser.assert.textMatches('#main', '^Nightwatch');
  });
};

assert[.not].titleContains(value, [msg])

Checks if the page title contains the given value.

Parameters:
Name Type description
value string The value to look for.
msg
Optional		 string Optional log message to display in the output. If missing, one is displayed by default.
Usage:
describe('titleContains demo', function () {
  it('demo test', function(browser) {
    browser.assert.titleContains('Nightwatch.js');
  });
};

assert[.not].titleEquals(value, [msg])

Checks if the page title equals the given value.

Parameters:
Name Type description
value string The expected page title.
msg
Optional		 string Optional log message to display in the output. If missing, one is displayed by default.
Usage:
describe('titleEquals demo', function () {
  it('demo test', function(browser) {
    browser.assert.titleEquals("Nightwatch.js");
  });
};

assert[.not].titleMatches(regex, [msg])

Checks if the current title matches a regular expression.

Parameters:
Name Type description
regex string|RegExp Regex to match the page title against.
msg
Optional		 string Optional log message to display in the output. If missing, one is displayed by default.
Usage:
describe('titleMatches demo', function () {
  it('demo test', function(browser) {
    browser.assert.titleMatches('^Nightwatch');
  });
};

assert[.not].urlContains(value, [msg])

Checks if the current URL contains the given value.

Parameters:
Name Type description
value string The value expected to exist within the current URL.
msg
Optional		 string Optional log message to display in the output. If missing, one is displayed by default.
Usage:
describe('urlContains demo', function () {
  it('demo test', function(browser) {
    browser.assert.urlContains('nightwatchjs.org');
  });
};

assert[.not].urlEquals(expected, [msg])

Checks if the current url equals the given value.

Parameters:
Name Type description
expected string The expected url.
msg
Optional		 string Optional log message to display in the output. If missing, one is displayed by default.
Usage:
describe('urlEquals demo', function () {
  it('demo test', function(browser) {
    browser.assert.urlEquals('https://nightwatchjs.org');
  });
};

assert[.not].urlMatches(regex, [msg])

Checks if the current url matches the given regular expression.

Parameters:
Name Type description
regex string|RegExp Regex to match the URL against.
msg
Optional		 string Optional log message to display in the output. If missing, one is displayed by default.
Usage:
describe('urlMatches demo', function () {
  it('demo test', function(browser) {
    browser.assert.urlMatches('^https');
  });
};

assert[.not].valueContains(element, expectedText, [msg])

Checks if the given form element's value contains the expected value.

Parameters:
Name Type description
element string|object The selector (CSS / Xpath) used to locate the element. Can either be a string or an object which specifies element properties.
expectedText string The expected text.
msg
Optional		 string Optional log message to display in the output. If missing, one is displayed by default.
Usage:
describe('valueContains demo', function () {
  it('demo test', function(browser) {
    browser.assert.valueContains("form.login input[type=text]", "username");
  });
};

assert[.not].valueEquals(element, expectedText, [msg])

Checks if the given form element's value equals the expected value.

Parameters:
Name Type description
element string|object The selector (CSS / Xpath) used to locate the element. Can either be a string or an object which specifies element properties.
expectedText string The expected text.
msg
Optional		 string Optional log message to display in the output. If missing, one is displayed by default.
Usage:
describe('valueEquals demo', function () {
  it('demo test', function(browser) {
    browser.assert.valueEquals("form.login input[type=text]", "username");
  });
};

assert[.not].visible(element, [msg])

Checks if the given element is visible on the page.

Parameters:
Name Type description
element string|object The selector (CSS / Xpath) used to locate the element. Can either be a string or an object which specifies element properties.
msg
Optional		 string Optional log message to display in the output. If missing, one is displayed by default.
Usage:
describe('visible demo', function () {
  it('demo test', function(browser) {
    browser.assert.visible('.should_be_visible');
    browser.assert.visible({selector: '.should_be_visible'});
    browser.assert.visible({selector: '.should_be_visible', supressNotFoundErrors: true});
  });
};