Implementation:Nightwatchjs Nightwatch Expect Type Definitions

Knowledge Sources	Nightwatchjs_Nightwatch Nightwatch Expect API
Domains	Testing, Type_System, BDD_Assertions
Last Updated	2026-02-12 00:00 GMT

Overview

TypeScript type definitions for Nightwatch's BDD-style expect assertion API, providing chainable assertions on elements, cookies, titles, URLs, and element collections.

Description

The expect.d.ts file defines the TypeScript interfaces for Nightwatch's Chai-inspired `expect` API. Key types include:

Expect — The top-level function and namespace. Can be called directly with an element to get `ExpectElement`, or used via `.cookie()`, `.element()`, `.component()`, `.section()`, `.elements()`, `.title()`, `.url()`.
ExpectElement — Element-specific assertions: `a`/`an` (tag type), `active`, `attribute`, `css`, `enabled`, `present`, `property`, `selected`, `text`, `value`, `visible`, `domProperty`.
ExpectCookie — Cookie value assertions.
ExpectElements — Element collection assertions with `.count`.
ExpectTitle / ExpectUrl — Page title and URL assertions.
ExpectAssertions — Base chain providing `equal`/`equals`/`eq`, `include`/`contains`, `match`/`matches`, `startWith`/`endWith`, `before`/`after` (timeouts), and `not` negation.
ExpectLanguageChains — Readability chains: `to`, `be`, `been`, `is`, `that`, `which`, `and`, `has`, `have`, `with`, `at`, `does`, `of`, `same`, `not`, `deep`.

Usage

These types are used when writing BDD-style tests using `browser.expect.element()`, `expect.title()`, `expect.url()`, etc. in TypeScript.

Code Reference

Source Location

Repository: Nightwatchjs_Nightwatch
File: types/expect.d.ts
Lines: 1-226

Signature

export interface Expect {
  (val: Element | WebElement | By | {[ELEMENT_KEY]: string}): ExpectElement;
  (val: any): Chai.Assertion;
  cookie(name: string, domain?: string): ExpectCookie;
  element(property: Definition): ExpectElement;
  component(property: Definition): ExpectElement;
  section(property: ScopedSelector): ExpectSection;
  elements(property: ScopedSelector): ExpectElements;
  title(): ExpectTitle;
  url(): ExpectUrl;
}

export interface ExpectElement extends ExpectAssertions<ExpectElement> {
  a(type: string, message?: string): Awaitable<this, NightwatchExpectResult>;
  active: Awaitable<this, NightwatchExpectResult>;
  attribute(attribute: string, message?: string): Awaitable<this, NightwatchExpectResult>;
  css(property: string, message?: string): Awaitable<this, NightwatchExpectResult>;
  enabled: Awaitable<this, NightwatchExpectResult>;
  present: Awaitable<this, NightwatchExpectResult>;
  selected: Awaitable<this, NightwatchExpectResult>;
  text: Awaitable<this, NightwatchExpectResult>;
  value: Awaitable<this, NightwatchExpectResult>;
  visible: Awaitable<this, NightwatchExpectResult>;
}

Import

import { Expect, ExpectElement, ExpectCookie } from 'nightwatch';

I/O Contract

Inputs

Name	Type	Required	Description
selector	Definition / ScopedSelector	Yes (for element/section)	Element or section selector
name	string	Yes (for cookie)	Cookie name
value	any	Yes (for equals/contains)	Expected value for comparison

Outputs

Name	Type	Description
NightwatchExpectResult	Object	Contains `value: null`, `returned: 1`
Chainable expectation	ExpectElement / ExpectTitle / etc.	Fluent chain for further assertions

Usage Examples

Element Expect Assertions

describe('Expect API', function() {
  it('uses BDD-style expect', async function(browser) {
    // Element assertions
    browser.expect.element('#main').to.be.visible;
    browser.expect.element('#main').text.to.contain('Welcome');
    browser.expect.element('#main').to.have.attribute('class').which.contains('active');
    browser.expect.element('input').to.be.enabled;
    browser.expect.element('input').value.to.equal('default');

    // Negation
    browser.expect.element('.hidden').to.not.be.visible;

    // Tag type
    browser.expect.element('#logo').to.be.an('img');

    // With timeout
    browser.expect.element('#dynamic').to.be.present.before(5000);
  });
});

Cookie, Title, and URL

describe('Expect non-element', function() {
  it('asserts cookies, title, URL', async function(browser) {
    browser.expect.cookie('session_id').to.contain('abc');
    browser.expect.title().to.equal('Dashboard');
    browser.expect.url().to.contain('/dashboard');

    // Element count
    browser.expect.elements('.item').count.to.equal(5);
  });
});

Related Pages

Page Connections

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

Principle

Implementation

Heuristic

Environment