Implementation:Nightwatchjs Nightwatch Custom Assertion Type Definitions

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

Overview

TypeScript type definitions for the `NightwatchAssertion<T>` interface that users implement to create custom assertions, and the `NightwatchCustomAssertions` augmentation interface.

Description

The custom-assertion.d.ts file defines:

NightwatchAssertion<T> — The generic interface for building custom assertions. Properties include:
- `expected` — The expected value or function returning it.
- `message` — Test output message.
- `command(callback)` — The async command that retrieves the value to evaluate.
- `value(result)` — Extracts the testable value from the command result.
- `pass(value)` / `evaluate(value)` — Determines if the assertion passed.
- `formatMessage()` — Custom message formatting with `.not` negate support.
- `failure(result)` — Handles command failures.
- `actual(passed)` — Reports actual state on failure.
- `api` (readonly) — Access to the Nightwatch API.
- `client` (readonly) — Access to the Nightwatch client.
- `negate` (readonly) — Whether `.not` was used.
NightwatchCustomAssertions<ReturnType> — Empty augmentation interface that users extend via module declaration to register custom assertions.

Usage

Implement `NightwatchAssertion<T>` when creating custom assertion files placed in the `custom_assertions_path` directory. Augment `NightwatchCustomAssertions` to add TypeScript support for custom assertions on `browser.assert`.

Code Reference

Source Location

Repository: Nightwatchjs_Nightwatch
File: types/custom-assertion.d.ts
Lines: 1-153

Signature

export interface NightwatchAssertion<T> {
  options?: { elementSelector: boolean };
  expected: (() => T) | T;
  message?: string;
  pass?(value: T): unknown;
  value?(result: NightwatchAssertionSuccessfulResult<T>): T;
  command(
    this: Pick<NightwatchAssertion<T>, 'client' | 'api' | 'negate'>,
    callback: (result: NightwatchAssertionSuccessfulResult<T>) => void
  ): unknown;
  formatMessage?(): { message: string; args: unknown[] };
  evaluate?(value: T): boolean;
  failure?(result: NightwatchAssertionFailedResult<T>): boolean;
  actual?(passed: boolean): string;
  readonly api: NightwatchAPI;
  readonly client: NightwatchClientObject;
  readonly negate: boolean;
}

export interface NightwatchCustomAssertions<ReturnType> {}

Import

import { NightwatchAssertion, ScopedSelector } from 'nightwatch';

I/O Contract

Inputs

Name	Type	Required	Description
expected	T or () => T	Yes	The expected value for the assertion
message	string	Yes (or formatMessage)	Display message for test output
command	function	Yes	Async function that retrieves the value to test

Outputs

Name	Type	Description
pass/evaluate result	boolean	Whether the assertion passed
Assertion registered on browser.assert	Method	Custom assertion available as `browser.assert.customName()`

Usage Examples

Custom Assertion Implementation

import { ScopedSelector, NightwatchAssertion } from 'nightwatch';

export const assertion = function ElementHasCount(
  this: NightwatchAssertion<number>,
  selector: ScopedSelector,
  count: number
) {
  this.message = `Testing if element <${selector}> has count: ${count}`;
  this.expected = count;

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

  this.evaluate = (value) => {
    return value === count;
  };

  this.command = async (callback) => {
    const elementsCount = await this.api.element.findAll(selector).count();
    callback({ value: elementsCount });
  };
};

Augmenting TypeScript Types

import { Awaitable, NightwatchAssertionsResult, ScopedSelector } from 'nightwatch';

declare module 'nightwatch' {
  interface NightwatchCustomAssertions<ReturnType> {
    elementHasCount(
      selector: ScopedSelector,
      count: number
    ): Awaitable<ReturnType, NightwatchAssertionsResult<number>>;
  }
}

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment