Implementation:Nightwatchjs Nightwatch ScopedElement Query API

Knowledge Sources	Nightwatch Nightwatch Element API
Domains	Testing, Component_Testing, Accessibility
Last Updated	2026-02-12 00:00 GMT

Overview

Concrete API for querying DOM elements by role, text, label, and other semantic properties in Nightwatch.js tests.

Description

The ScopedElement class provides Testing Library-inspired query methods: findByRole, findByText, findByPlaceholderText, findByLabelText, findByAltText for single elements, and findAll, findAllByText for collections. The Elements class returned by findAll provides nth(index) for indexed access and count() for counting. Both integrate with assert for presence/attribute checking.

Usage

Chain query methods off an element() or browser.element to locate elements semantically. Use findByRole as the primary query when possible.

Code Reference

Source Location

Repository: nightwatch
File: examples/tests/element/elementapi-tests.js (lines 1-82)
File: types/web-element.d.ts (lines 11-223, 236-253, 291-309)

Signature

// Single element queries
element.find(selector: string) -> ScopedElement
element.findByRole(role: string, options?: { name?: string, exact?: boolean }) -> ScopedElement
element.findByText(text: string, options?: { exact?: boolean }) -> ScopedElement
element.findByPlaceholderText(text: string, options?: { exact?: boolean }) -> ScopedElement
element.findByLabelText(text: string, options?: { exact?: boolean }) -> ScopedElement
element.findByAltText(text: string, options?: { exact?: boolean }) -> ScopedElement

// Collection queries
element.findAll(selector: string) -> Elements
element.findAllByText(text: string, options?: { exact?: boolean }) -> Elements

// Elements methods
elements.nth(index: number) -> ScopedElement
elements.count() -> ElementValue<number>

// Assertions
scopedElement.assert.present() -> void
scopedElement.assert.hasAttribute(name: string) -> void

Import

// Available on element() instances and browser.element
const el = element('body');
el.findByRole('button');

I/O Contract

Inputs

Name	Type	Required	Description
role	string	Yes (for findByRole)	ARIA role name (e.g., 'button', 'heading', 'textbox')
text	string	Yes (for findByText)	Visible text content to match
options.exact	boolean	No	Whether to match exact text (default: true)
index	number	Yes (for nth)	Zero-based index into element collection

Outputs

Name	Type	Description
ScopedElement	Object	Located element for interaction and assertion
Elements	Object	Collection with nth() and count() methods
ElementValue<number>	number	Element count from count() method

Usage Examples

Semantic Element Queries

describe('Element API tests', function() {
  it('demonstrates findByRole and findByText', async function(browser) {
    const body = element('body');

    // Find by ARIA role
    const heading = body.findByRole('heading');
    await heading.assert.present();

    // Find by visible text
    const link = body.findByText('Learn More');
    await link.assert.present();

    // Find by placeholder
    const input = body.findByPlaceholderText('Enter your name');
    await input.assert.present();
    await input.assert.hasAttribute('type');

    // Find all and count
    const allButtons = body.findAll('button');
    await expect(allButtons.count()).toEqual(3);

    // Access specific element in collection
    const secondButton = allButtons.nth(1);
    await secondButton.assert.present();
  });
});

Related Pages

Implements Principle

Principle:Nightwatchjs_Nightwatch_Element_Interaction_And_Assertion

Requires Environment

Page Connections

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

Principle

Implementation

Heuristic

Environment