Implementation:Nightwatchjs Nightwatch Web Element Type Definitions

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

Overview

TypeScript type definitions for Nightwatch's modern ScopedElement API, including element querying, interaction, assertion, and DOM traversal methods.

Description

The web-element.d.ts file defines the TypeScript interfaces for Nightwatch's fluent element API introduced in v3. Key types include:

ScopedElement — The core element type providing chainable methods for finding, interacting with, and asserting on DOM elements. Extends both `Element` and `PromiseLike<WebElement>`.
Elements — A collection type returned by `findAll`/`findElements`, with `.nth()` and `.count()` methods.
ElementAssertions — Assertion methods on elements: `enabled`, `selected`, `visible`, `present`, `hasClass`, `hasAttribute`, `hasDescendants`, with `.not` negation.
ElementValue — A promise-like wrapper with `.assert` (containing `contains`, `equals`, `matches`) and `.map()` for transforming values.
ElementFunction — The `element()` global function type providing `find`, `findByText`, `findByRole`, `findByPlaceholderText`, `findByLabelText`, `findByAltText`, and their `findAll*` counterparts.
ElementLocator — Locator configuration with `index`, `timeout`, `condition`, `retryInterval`, `locateStrategy`, and `abortOnFailure`.

Usage

These types are used when writing Nightwatch tests using the modern element API (`browser.element.find()`, `browser.element.findByRole()`, etc.) in TypeScript. They enable autocompletion for all element interaction and assertion methods.

Code Reference

Source Location

Repository: Nightwatchjs_Nightwatch
File: types/web-element.d.ts
Lines: 1-381

Signature

export interface ScopedElement extends Element, PromiseLike<WebElement> {
  assert: ElementAssertions;
  find(selector: ScopedElementSelector): ScopedElement;
  findByText(text: string, options?: {...}): ScopedElement;
  findByRole(role: string, options?: {...}): ScopedElement;
  findByPlaceholderText(text: string, options?: {...}): ScopedElement;
  findByLabelText(text: string, options?: {...}): ScopedElement;
  findByAltText(text: string, options?: {...}): ScopedElement;
  findAll(selector: ScopedSelector): Elements;
  click(): Promise<WebElement>;
  getText(): ElementValue<string>;
  getAttribute(name: string): ElementValue<string | null>;
  getCssProperty(name: string): ElementValue<string>;
  isVisible(): ElementValue<boolean>;
  waitUntil(signalOrOptions: WaitUntilActions | WaitUntilOptions): Promise<WebElement>;
  // ... 50+ methods
}

export interface ElementFunction extends Pick<ScopedElement, 'find' | 'findByText' | 'findByRole' | ...> {
  (selector: ScopedElementSelector): ScopedElement;
  findActive(): ScopedElement;
}

Import

import { ScopedElement, Elements, ElementFunction, ElementValue } from 'nightwatch';

I/O Contract

Inputs

Name	Type	Required	Description
selector	ScopedElementSelector	Yes	CSS selector, By locator, WebElement, or Promise thereof
text	string	Yes (for findByText, etc.)	Text content to search by
role	string	Yes (for findByRole)	ARIA role name (e.g., 'button', 'heading')

Outputs

Name	Type	Description
ScopedElement	Object	Chainable element with interaction and assertion methods
Elements	PromiseLike<WebElement[]>	Collection with `.nth()` and `.count()`
ElementValue<T>	PromiseLike<T>	Wrapped value with `.assert` (contains, equals, matches)

Usage Examples

Modern Element API

describe('Web element API', function() {
  it('uses scoped element queries', async function(browser) {
    // Find by CSS selector
    const heading = browser.element.find('h1');
    await heading.getText().assert.equals('Welcome');

    // Find by accessible role
    const submitBtn = browser.element.findByRole('button');
    await submitBtn.click();

    // Find by text content
    const link = browser.element.findByText('Learn more');
    await link.assert.visible();

    // Chained queries
    const form = browser.element.find('form');
    const input = form.findByPlaceholderText('Email');
    await input.sendKeys('user@example.com');

    // Collection operations
    const items = browser.element.findAll('.list-item');
    await items.count().assert.equals(5);
    await items.nth(0).getText().assert.contains('First');
  });
});

Element Assertions

describe('Element assertions', function() {
  it('asserts element state', async function(browser) {
    const el = browser.element.find('#myInput');

    await el.assert.enabled();
    await el.assert.visible();
    await el.assert.hasClass('active');
    await el.assert.hasAttribute('data-testid');

    // Negated
    await el.assert.not.selected();
  });
});

Related Pages

Page Connections

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

Principle

Implementation

Heuristic

Environment