or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

advanced-features.mdassertions-expectations.mdbrowser-control.mdelement-interaction.mdindex.mdmodern-element-api.mdpage-object-model.mdprogrammatic-api.mdprotocol-commands.md
tile.json

tessl/npm-nightwatch

Easy to use Node.js based end-to-end testing solution for web applications using the W3C WebDriver API.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/nightwatch@3.12.x

To install, run

npx @tessl/cli install tessl/npm-nightwatch@3.12.0

index.mddocs/

Nightwatch.js

Nightwatch.js is a comprehensive Node.js-based end-to-end testing framework that provides APIs for browser automation, element interaction, assertions, and mobile testing. It offers an integrated testing solution supporting multiple types of testing including end-to-end web application testing, component testing, unit testing, visual regression testing, accessibility testing, API testing, and native mobile app testing.

Package Information

  • Package Name: nightwatch
  • Package Type: npm
  • Language: JavaScript/TypeScript
  • Installation: npm install nightwatch

Core Imports

Main module import:

// ES6 Modules
import Nightwatch from "nightwatch";

// CommonJS
const Nightwatch = require("nightwatch");

Named exports (available in Nightwatch v2+):

// ES6 named imports
import { browser, app, element, expect, assert, verify } from "nightwatch";

// CommonJS destructuring
const { browser, app, element, expect, assert, verify } = require("nightwatch");

Selenium WebDriver utilities:

// ES6 named imports
import { By, Key, Capabilities } from "nightwatch";

// CommonJS destructuring
const { By, Key, Capabilities } = require("nightwatch");

Global APIs (available in test files):

// Available globally in test files without imports
browser.url("https://example.com");
browser.assert.titleContains("Example");
expect(element("#selector")).to.be.visible;

Basic Usage

// Basic test example
module.exports = {
  "Demo test": function(browser) {
    browser
      .url("https://example.com")
      .waitForElementVisible("body", 1000)
      .assert.titleContains("Example")
      .assert.visible("input[type=text]")
      .setValue("input[type=text]", "nightwatch")
      .waitForElementVisible("button[type=submit]", 1000)
      .click("button[type=submit]")
      .pause(1000)
      .assert.containsText("#results", "success")
      .end();
  }
};

Architecture

Nightwatch.js is built around several key components:

  • NightwatchClient: Core client managing WebDriver sessions and command execution
  • TestSuite: Test suite orchestration with lifecycle hooks and reporting
  • Element API: Modern element wrapper providing fluent interactions and queries
  • Command Queue: Asynchronous command queue ensuring proper execution order
  • Transport Layer: WebDriver protocol implementation supporting multiple browsers
  • Assertion Engine: Comprehensive assertion library with expect-style and assert-style APIs
  • Page Object Model: Structured approach for organizing test elements and actions

Capabilities

Browser Control & Navigation

Core browser session management, navigation, and window control operations for test setup and teardown.

// Session Management
browser.init();
browser.end();
browser.quit();

// Navigation
browser.url(url);
browser.back();
browser.forward();
browser.refresh();

// Window Management
browser.maximizeWindow();
browser.resizeWindow(width, height);
browser.getWindowSize();
browser.setWindowSize(width, height);

Browser Control

Element Interaction

Comprehensive element finding, interaction, and property access APIs for web element automation.

// Element Finding
browser.findElement(selector);
browser.findElements(selector);
browser.element(selector);

// Element Interaction
browser.click(selector);
browser.setValue(selector, value);
browser.clearValue(selector);
browser.sendKeys(selector, keys);

// Element State
browser.isVisible(selector);
browser.isPresent(selector);
browser.isEnabled(selector);
browser.getText(selector);
browser.getValue(selector);

Element Interaction

Modern Element API

Modern fluent element API providing chainable operations and built-in waiting mechanisms.

// Element Creation
const element = browser.element(selector);

// Element Queries
element.findByText(text);
element.findByRole(role);
element.findByPlaceholderText(text);

// Element Actions
element.click();
element.sendKeys(...keys);
element.clear();
element.check();
element.uncheck();

// Element Properties
element.getText();
element.getValue();
element.getAttribute(name);
element.isVisible();
element.isEnabled();

Modern Element API

Assertions & Expectations

Comprehensive assertion library supporting both assert-style and expect-style validation patterns.

// Assert-style Assertions
browser.assert.titleContains(expected);
browser.assert.visible(selector);
browser.assert.textContains(selector, text);
browser.assert.urlContains(expected);

// Expect-style Assertions
browser.expect.element(selector).to.be.visible;
browser.expect.element(selector).text.to.contain(expected);
browser.expect.title().to.equal(expected);
browser.expect.url().to.match(regex);

Assertions & Expectations

Page Object Model

Structured page object pattern for organizing elements, sections, and custom commands.

// Page Object Definition
interface PageObject {
  url: string | (() => string);
  elements: Record<string, ElementProperties>;
  sections: Record<string, SectionProperties>;
  commands: Record<string, Function>;
}

// Page Object Usage
const loginPage = browser.page.loginPage();
loginPage.navigate();
loginPage.fillForm(username, password);
loginPage.submit();

Page Object Model

Advanced Features

Advanced testing capabilities including performance monitoring, accessibility testing, and mobile support.

// Performance & Monitoring
browser.takeHeapSnapshot();
browser.enablePerformanceMetrics();
browser.getPerformanceMetrics();

// Accessibility Testing
browser.axeInject();
browser.axeRun(options);

// Mobile Testing
browser.isIOS();
browser.isAndroid();
browser.isMobile();
browser.setGeolocation(latitude, longitude);

Advanced Features

Programmatic API

Programmatic client creation and test runner for integrating Nightwatch into custom applications and workflows.

// Create programmatic client
Nightwatch.createClient(options);

// Run tests programmatically
Nightwatch.runTests(testSource, settings);

// CLI runner
Nightwatch.CliRunner(argv);

// Initialize client
Nightwatch.initClient(opts);

Programmatic API

Protocol Commands

Low-level WebDriver protocol commands for fine-grained browser control and automation.

// WebDriver Protocol
browser.session();
browser.status();
browser.navigateTo(url);
browser.getCurrentUrl();

// Element Protocol
browser.elementIdClick(id);
browser.elementIdText(id);
browser.elementIdAttribute(id, name);

// Mouse & Keyboard
browser.moveTo(element, xOffset, yOffset);
browser.mouseButtonClick(button);
browser.keys(keys);

Protocol Commands

CLI Usage

Command-line interface for running tests, setup, and maintenance operations.

// CLI commands
nightwatch [test-source] [options]
nightwatch --help
nightwatch --version
nightwatch --info
nightwatch --list-files

Utilities

Utility APIs for HTTP requests and Chrome DevTools Protocol access.

// HTTP utilities
Nightwatch.utils.HttpRequest;

// Chrome DevTools Protocol
Nightwatch.utils.cdp;

// Logger utilities
Nightwatch.Logger.log(message);
Nightwatch.Logger.info(message);
Nightwatch.Logger.warn(message);
Nightwatch.Logger.error(message);

Global Objects

// Available globally in test files
declare const browser: NightwatchAPI;
declare const app: NightwatchAPI; // Alias for browser
declare const element: (selector: string) => Element;
declare const expect: ExpectAPI;

// Selenium WebDriver imports
declare const By: typeof import('selenium-webdriver').By;
declare const Key: typeof import('selenium-webdriver').Key;
declare const locateWith: typeof import('selenium-webdriver').locateWith;

Core Types

interface NightwatchAPI {
  // Session Management
  sessionId: string;
  capabilities: Capabilities;
  desiredCapabilities: Capabilities;
  
  // Browser Detection
  isChrome(): boolean;
  isFirefox(): boolean;
  isSafari(): boolean;
  isIOS(): boolean;
  isAndroid(): boolean;
  isMobile(): boolean;
  
  // Test Information
  currentTest: {
    name: string;
    module: string;
    results: TestResults;
  };
  
  // Globals
  globals: NightwatchGlobals;
  options: NightwatchOptions;
}

interface NightwatchClient {
  api: NightwatchAPI;
  queue: CommandQueue;
  transport: Transport;
  sessionId: string;
  
  initialize(): Promise<void>;
  createSession(): Promise<SessionData>;
  createTransport(): void;
}

interface TestSuite {
  client: NightwatchClient;
  api: NightwatchAPI;
  context: Context;
  reporter: Reporter;
  
  run(): Promise<boolean>;
  createSession(): Promise<void>;
  runTestSuite(): Promise<boolean>;
}