Implementation:Nightwatchjs Nightwatch Browser Command API

Knowledge Sources	Nightwatch Nightwatch API Reference
Domains	Testing, Browser_Automation, API
Last Updated	2026-02-12 00:00 GMT

Overview

Concrete browser command API available on the NightwatchAPI instance for programmatic browser automation and element interaction.

Description

The browser object returned by launchBrowser() exposes the full Nightwatch command set. The public API (api/index.js) lazily loads element commands (findElement, findElements, waitForElementPresent, waitForElementVisible, quit) and the internal command tree provides navigation, interaction, and assertion commands. The element.find() method returns ScopedElement instances for the new chainable element API.

Usage

Call commands on the browser object obtained from launchBrowser(). Use async/await or chaining for sequential execution.

Code Reference

Source Location

Repository: nightwatch
File: api/index.js (lines 1-32)
File: api/README.md (lines 1-60)

Signature

// Navigation
browser.navigateTo(url: string) -> this
browser.back() -> this
browser.forward() -> this
browser.refresh() -> this

// Element interaction
browser.waitForElementVisible(selector: string, timeout?: number) -> this
browser.waitForElementPresent(selector: string, timeout?: number) -> this
browser.click(selector: string) -> this
browser.setValue(selector: string, value: string | string[]) -> this
browser.sendKeys(selector: string, keys: string[]) -> this

// Assertions
browser.assert.textContains(selector: string, text: string) -> this
browser.assert.titleContains(title: string) -> this
browser.assert.visible(selector: string) -> this
browser.assert.urlContains(url: string) -> this

// New Element API
browser.element.find(selector: string) -> ScopedElement
browser.element.findAll(selector: string) -> Elements

Import

// browser is obtained from launchBrowser()
const browser = await client.launchBrowser();

I/O Contract

Inputs

Name	Type	Required	Description
selector	string	Yes	CSS or XPath selector for element commands
url	string	Yes (navigateTo)	Target URL
value	string or string[]	Yes (setValue)	Values to input
timeout	number	No	Timeout in ms for waitFor commands

Outputs

Name	Type	Description
this (browser)	NightwatchAPI	Returns browser for chaining
ScopedElement	Object	From element.find(), supports chainable queries

Usage Examples

Programmatic Browser Commands

const Nightwatch = require('nightwatch');

(async function() {
  const client = Nightwatch.createClient({
    browserName: 'chrome',
    headless: true
  });

  const browser = await client.launchBrowser();

  // Navigation and interaction
  await browser.navigateTo('https://www.ecosia.org/');
  await browser.waitForElementVisible('body');
  await browser.setValue('input[type=search]', 'nightwatch');
  await browser.click('button[type=submit]');

  // Assertions
  await browser.assert.textContains('.layout__content', 'Nightwatch.js');

  // New Element API
  const heading = browser.element.find('h1');
  await heading.assert.present();

  await browser.end();
  await client.cleanup();
})();

Related Pages

Page Connections

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

Principle

Implementation

Heuristic

Environment