Implementation:Nightwatchjs Nightwatch Custom Assertion Interface

Knowledge Sources	Nightwatch Nightwatch Custom Assertions
Domains	Testing, Extensibility, Assertions
Last Updated	2026-02-12 00:00 GMT

Overview

Concrete API interface for defining custom assertions conforming to the NightwatchAssertion<T> interface in Nightwatch.js.

Description

Custom assertions are JavaScript modules in the custom_assertions_path directory that export via exports.assertion. The assertion function receives user-defined parameters and sets up the protocol methods on this. The this.api property provides access to all Nightwatch commands for the command() method. The filename becomes the assertion name on browser.assert.fileName() and browser.verify.fileName().

Usage

Create a .js file in the custom_assertions_path directory with exports.assertion = function(args) { ... }. Implement all protocol methods: message, expected(), pass(value), value(result), command(callback), and optionally failure(result).

Code Reference

Source Location

• Repository: nightwatch
• File: examples/custom-assertions/testCustomAssertion.js (lines 1-42)
• File: types/custom-assertion.d.ts (lines 37-148)

Signature

exports.assertion = function(selector, attribute, expected, msg) {
  // this.message: string - Output message for the assertion
  this.message = msg || 'default message';

  // this.expected(): T - Returns expected value
  this.expected = function() { return expected; };

  // this.pass(value: T): boolean - Returns true if assertion passes
  this.pass = function(value) { return value === expected; };

  // this.failure(result): boolean - Returns true if command errored
  this.failure = function(result) {
    return result === false || (result && result.status === -1);
  };

  // this.value(result): T - Extracts actual value from command result
  this.value = function(result) { return result.value; };

  // this.command(callback): NightwatchAPI - Executes browser command
  this.command = function(callback) {
    return this.api.getAttribute(selector, attribute, callback);
  };
};

Import

// No import required - auto-loaded from custom_assertions_path
// File: custom-assertions/testCustomAssertion.js
// Usage: browser.assert.testCustomAssertion(selector, attr, expected)

I/O Contract

Inputs

Name	Type	Required	Description
this.message	string	Yes	Human-readable assertion message
this.expected	Function	Yes	Returns the expected value
this.pass	Function	Yes	Compares actual to expected, returns boolean
this.value	Function	Yes	Extracts value from command result
this.command	Function	Yes	Browser command that retrieves the value
this.failure	Function	No	Detects error conditions
this.api	NightwatchAPI	Automatic	Full Nightwatch API for use in command()

Outputs

Name	Type	Description
Assertion result	Pass/Fail	Logged to console and reporter
browser.assert.*	Fails test	If assertion fails on assert namespace
browser.verify.*	Logs failure	If assertion fails on verify namespace, test continues

Usage Examples

Custom Attribute Assertion

// custom-assertions/testCustomAssertion.js
const util = require('util');

exports.assertion = function(selector, attribute, expected, msg) {
  let DEFAULT_MSG = 'Testing if attribute %s of <%s> contains "%s".';
  let MSG_ELEMENT_NOT_FOUND = DEFAULT_MSG + ' Element could not be located.';
  let MSG_ATTR_NOT_FOUND = DEFAULT_MSG + ' Element does not have a %s attribute.';

  this.message = msg || util.format(DEFAULT_MSG, attribute, selector, expected);

  this.expected = function() {
    return expected;
  };

  this.pass = function(value) {
    return value === expected;
  };

  this.failure = function(result) {
    let failed = (result === false) ||
      result && (result.status === -1 || result.value === null);

    if (failed) {
      this.message = msg || util.format(
        result.value === null ? MSG_ATTR_NOT_FOUND : MSG_ELEMENT_NOT_FOUND,
        attribute, selector, expected
      );
    }

    return failed;
  };

  this.value = function(result) {
    return result.value;
  };

  this.command = function(callback) {
    return this.api.getAttribute(selector, attribute, callback);
  };
};

// Usage in tests:
// browser.assert.testCustomAssertion('#elem', 'data-role', 'admin');

Related Pages

Implements Principle

• Principle:Nightwatchjs_Nightwatch_Custom_Assertion_Creation