Implementation:Nightwatchjs Nightwatch Browser Commands API

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

Overview

Concrete browser automation API for navigating pages, interacting with DOM elements, and asserting test conditions in Nightwatch.js E2E tests.

Description

The browser object provides chainable commands for end-to-end testing. Core commands include navigateTo for URL navigation, waitForElementVisible for synchronization, click and setValue for interaction, and assert.textContains/assert.titleContains for verification. The browser instance is injected into test callbacks by the Nightwatch test runner.

Usage

Use these commands within describe/it test blocks to automate browser interactions. The browser object is available as a callback parameter in test functions or as a global when enable_global_apis is configured.

Code Reference

Source Location

Repository: nightwatch
File: examples/tests/ecosia.js (lines 1-20)
File: examples/tests/google.js (lines 1-43)
File: api/index.js (lines 1-32)

Signature

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

// Element synchronization
browser.waitForElementVisible(selector: string, timeout?: number) -> this

// Interaction
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, expectedText: string) -> this
browser.assert.titleContains(expectedTitle: string) -> this
browser.assert.visible(selector: string) -> this

Import

// No import required - browser is injected by the test runner
describe('Test Suite', function() {
  it('test case', function(browser) {
    // browser is available here
  });
});

I/O Contract

Inputs

Name	Type	Required	Description
selector	string	Yes	CSS or XPath selector to locate DOM elements
url	string	Yes (for navigateTo)	Target URL for navigation
value	string or string[]	Yes (for setValue)	Input values to set on form elements
timeout	number	No	Timeout in ms for waitFor commands (uses global default)
browser.Keys.ENTER	Key constant	No	Special key constants for sendKeys

Outputs

Name	Type	Description
this (browser)	NightwatchAPI	Returns browser instance for method chaining
Assertion results	Pass/Fail	Logged to console and reporter; fails halt test if abortOnAssertionFailure is true

Usage Examples

Basic Search Test

describe('Ecosia.org Demo', function() {

  before(browser => {
    browser.navigateTo('https://www.ecosia.org/');
  });

  it('Demo test ecosia.org', function(browser) {
    browser
      .waitForElementVisible('body')
      .assert.titleContains('Ecosia')
      .assert.visible('input[type=search]')
      .setValue('input[type=search]', 'nightwatch')
      .assert.visible('button[type=submit]')
      .click('button[type=submit]')
      .assert.textContains('.layout__content', 'Nightwatch.js');
  });

  after(browser => browser.end());
});

Multi-Step Form Test

describe('BrowserStack Demo Auth', function() {
  it('should login successfully', function(browser) {
    browser
      .navigateTo('https://bstackdemo.com/')
      .click('#signin')
      .setValue('#username', 'demouser')
      .setValue('#password', 'testingisfun99')
      .click('#login-btn')
      .assert.textContains('.username', 'demouser');
  });
});

Related Pages

Page Connections

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

Principle

Implementation

Heuristic

Environment