Define custom assertions

Overview

Nightwatch allows you to even define your own assertions, extending the available .assert and .verify namespaces. To do so, create a new folder (e.g. nightwatch/assertions) and start defining your own assertions inside, each in its own file.

Then specify the path to that folder in the nightwatch.json file, as the custom_assertions_path property.

nightwatch.json 
{
  "custom_assertions_path" : "nightwatch/assertions"
}

Custom assertions also inherit from EventEmitter. To see some examples, check the assertions module on Github:
/nightwatch/tree/main/lib/selenium/assertions

Define a custom assertion

Assertions implement a simple interface which is shared between built-in assertions and custom ones:

nightwatch/assertions/customAssert.js 
exports.assertion = function(definition, expectedText, msg) {
  

  // If the custom commands operates with DOM elements, this options should be set
  // this.options = {
  //   elementSelector: true
  // };
  

  /**
   * Returns the message format which will be used to output the message in the console and also
   *  the arguments which will be used for replace the place holders, used in the order of appearance
   * 
   * The message format also takes into account whether the .not negate has been used
   *
   * @return undefined
   */
   this.formatMessage = function() {
     // Use this.negate to determine if ".not" is in use
     // Example: 
     const message = `Testing if the page title ${this.negate ? 'doesn't equal %s' : 'equals %s'}`;
     

     return {
       message,
       args: [`'${expected}'`]
     }
   };
  

  /**
    * Returns the expected value of the assertion which is displayed in the case of a failure
    *
    * @return {string}
    */
   this.expected = function() {
     return this.negate ? `is not '${expectedText}'` : `is '${expectedText}'`;
   };
   

   /**
    * Given the value, the condition used to evaluate if the assertion is passed
    * @param {*} value
    * @return {Boolean}
    */
   this.evaluate = function(value) {
     if (typeof value != 'string') {
       return false;
     }
     

     return value.includes(expectedText);
   };
  

  /**
   * Called with the result object of the command to retrieve the value which is to be evaluated
   *
   * @param {Object} result
   * @return {*}
   */
   this.value = function(result) {
     return result.value;
   };
  

  /**
   * When defined, this method is called by the assertion runner with the command result, to determine if the
   *  value can be retrieved successfully from the result object
   *
   * @param result
   * @return {boolean|*}
   */
   this.failure = function(result) {
     return result === false || result && result.status === -1;
   };
  
 
   /**
    * When defined, this method is called by the assertion runner with the command result to determine the actual
    *  state of the assertion in the event of a failure
    *
    * @param {Boolean} passed
    * @return {string}
    */
   this.actual = function(passed) {
     return passed ? `contains '${expectedText}'` : `does not contain '${expectedText}'`;
   };
  

  /**
   * The command which is to be executed by the assertion runner; Nightwatch api is available as this.api
   * @param {function} callback
   */
  this.command = function(callback) {
     // Example: this.api.getText(definition, callback);
     

     setTimeout(function() {
       // The object containing a "value" property will be passed to the .value() method to determine the value w
       // which is to be evaluated (by the .evaluate() method)
       callback({
         value: ''
       });
       

     }, 1000);   
    
 
  };
  

};

Recommended content