Implementation:Nightwatchjs Nightwatch Element Global API

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

Overview

Global element() utility function for initializing and interacting with DOM elements in Nightwatch.js component and E2E tests.

Description

The element() global creates ScopedElement instances that can be initialized before tests and reused. It accepts a CSS selector string or an object with selector and index properties. The returned element supports chaining with findElement, sendKeys, click, and the expect API. Combined with expect.elements() for collection assertions, it provides a complete element interaction layer.

Usage

Use element() to pre-initialize element references at the describe block level, or inline within tests. Useful for component tests where elements are known ahead of time.

Code Reference

Source Location

Repository: nightwatch
File: examples/tests/vueTodoList.js (lines 1-46)
File: types/web-element.d.ts (lines 11-223)

Signature

// Global element utility
element(selector: string) -> ScopedElement
element({ selector: string, index: number }) -> ScopedElement

// ScopedElement methods
scopedElement.findElement(selector: string) -> WebElement
scopedElement.click() -> Promise<void>
scopedElement.getText() -> Promise<string>

// Global expect for element collections
expect.elements(selector: string).count.toEqual(n: number) -> Promise<void>
expect(scopedElement).text.toContain(text: string) -> Promise<void>

Import

// element() is available as a global when Nightwatch is running
// Can also be imported:
const { element } = require('nightwatch');

I/O Contract

Inputs

Name	Type	Required	Description
selector	string or Object	Yes	CSS selector string or { selector, index } object
index	number	No	Which element to select when multiple match (in object form)

Outputs

Name	Type	Description
ScopedElement	Object	Chainable element wrapper with findElement, click, getText, assert
expect(element)	ExpectChain	Expect assertion chain for the element

Usage Examples

Vue Component Test

describe('To-Do List End-to-End Test', function() {
  // Initialize elements before tests
  const todoElement = element('#new-todo-input');
  const addButtonEl = element('form button[type="submit"]');

  it('should add a todo using global element()', async function() {
    // Navigate to the app
    await browser
      .navigateTo('https://todo-vue3-vite.netlify.app/')
      .sendKeys(todoElement, 'what is nightwatch?')
      .click(addButtonEl);

    // Assert element count
    await expect.elements('#todo-list ul li').count.toEqual(5);

    // Assert specific element text
    const lastElement = element({
      selector: '#todo-list ul li',
      index: 4
    });
    await expect(lastElement).text.toContain('what is nightwatch?');

    // Find child element and interact
    const checkbox = await lastElement.findElement('input[type="checkbox"]');
    await browser.click(checkbox);

    // Verify checked count
    await expect.elements('#todo-list ul li input:checked').count.toEqual(3);
  });
});

Related Pages

Implements Principle

Principle:Nightwatchjs_Nightwatch_Component_Test_Authoring

Requires Environment

Page Connections

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

Principle

Implementation

Heuristic

Environment