Implementation:Nightwatchjs Nightwatch Custom Command Interface

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

Overview

Concrete API interface for defining custom commands conforming to the NightwatchCustomCommandsModel in Nightwatch.js.

Description

Custom commands are JavaScript modules placed in the custom_commands_path directory. The object-based style exports { command(args) {} } where this is bound to the Nightwatch command context. The class-based style exports an ES6 class with an async command() method. The this context provides access to this.api (full Nightwatch API), this.client, and all built-in browser commands.

Usage

Create a .js file in the custom_commands_path directory. The filename (without extension) becomes the command name. Use object style for simple commands, class style for async or complex commands.

Code Reference

Source Location

• Repository: nightwatch
• File: examples/custom-commands/strictClick.js (lines 1-6)
• File: types/custom-command.d.ts (lines 1-25)

Signature

// Object-based custom command
module.exports = {
  command(selector: string, ...args): this {
    // this = Nightwatch command context
    // this.api = full Nightwatch API
    return this;
  }
};

// Class-based custom command (ES6)
module.exports = class CustomCommand extends EventEmitter {
  async command(...args): Promise<any> {
    // this.api = full Nightwatch API
    // this.client = NightwatchClient
  }
};

Import

// No import required - auto-loaded from custom_commands_path
// File: custom-commands/strictClick.js
// Usage: browser.strictClick(selector)

I/O Contract

Inputs

Name	Type	Required	Description
this	NightwatchCommandContext	Automatic	Bound context with access to all browser commands
this.api	NightwatchAPI	Automatic	Full Nightwatch API instance
User-defined args	any	Varies	Parameters defined in the command signature

Outputs

Name	Type	Description
this	NightwatchCommandContext	Return this for method chaining (object style)
Promise	any	Resolved result (class style)

Usage Examples

Object-Based Command (strictClick)

// custom-commands/strictClick.js
module.exports = {
  command: function(selector) {
    return this.waitForElementVisible(selector)
      .click(selector);
  }
};

// Usage in tests:
// browser.strictClick('#submit-button');

Class-Based Command

// custom-commands/angular/getElementsInList.js
module.exports = class AngularCommand {
  async command(listName, cb = function(r) { return r; }) {
    return this.api.executeScript(function(listName) {
      var elements = document.querySelectorAll(
        '*[ng-repeat$="' + listName + '"]'
      );
      return elements || null;
    }, [listName], async function(result) {
      const cbResult = await cb(result);
      return cbResult.value ? cbResult.value : cbResult;
    });
  }
};

// Usage in tests:
// browser.angular.getElementsInList('item in items');

Related Pages

Implements Principle

• Principle:Nightwatchjs_Nightwatch_Custom_Command_Creation