Implementation:Nightwatchjs Nightwatch Nightwatch Options Type Definitions

Knowledge Sources	Nightwatchjs_Nightwatch Nightwatch Configuration
Domains	Configuration, Type_System
Last Updated	2026-02-12 00:00 GMT

Overview

TypeScript type definitions for the complete Nightwatch configuration object, including test settings, WebDriver options, Selenium options, and test environment configuration.

Description

The nightwatch-options.d.ts file defines all TypeScript interfaces for configuring Nightwatch. The key interfaces are:

NightwatchOptions — Top-level configuration with `custom_commands_path`, `plugins`, `test_settings`, `globals_path`, `trace`, and more.
NightwatchTestSettingGeneric — Per-environment settings like `baseUrl`, `desiredCapabilities`, `webdriver`, `selenium`, `test_runner`, `test_workers`, `screenshots`, output options, and window size.
WebdriverOptions — WebDriver server settings including `start_process`, `server_path`, `host`, `port`, `timeout_options`, `keep_alive`, and browser-specific paths.
NightwatchSeleniumOptions — Selenium Grid settings.
NightwatchTestRunner — Test runner configuration (Mocha, Cucumber, default).
NightwatchTestWorker — Parallel execution settings.
NightwatchScreenshotOptions — Screenshot capture configuration.
NightwatchTestSettings — Map of named test environments.

⚠️ Deprecation Warning: This file contains 4 deprecated configuration options (`selenium_host`, `selenium_port`, `use_ssl`, `unit_tests_mode`) that have been replaced by modern equivalents. See Heuristic:Nightwatchjs_Nightwatch_Warning_Deprecated_API_Members for migration guidance.

Usage

These types are used when writing `nightwatch.conf.ts` or when programmatically constructing a configuration object. They provide autocompletion for all valid configuration keys and their expected value types.

Code Reference

Source Location

Repository: Nightwatchjs_Nightwatch
File: types/nightwatch-options.d.ts
Lines: 1-826

Signature

export interface NightwatchOptions extends NightwatchTestSettingGeneric {
  custom_commands_path?: string | string[] | null;
  custom_assertions_path?: string | string[] | null;
  page_objects_path?: string | string[] | null;
  plugins?: string[];
  globals_path?: string | null;
  test_settings: NightwatchTestSettings;
  backwards_compatibility_mode?: boolean;
  disable_global_apis?: boolean;
  element_command_retries?: number;
  trace?: { enabled: boolean; path?: string; };
  // ... additional options
}

export interface NightwatchTestSettingGeneric {
  baseUrl?: string;
  desiredCapabilities?: NightwatchDesiredCapabilities;
  selenium?: NightwatchSeleniumOptions;
  webdriver?: WebdriverOptions;
  test_runner?: string | NightwatchTestRunner;
  test_workers?: boolean | NightwatchTestWorker;
  globals?: NightwatchGlobals;
  screenshots?: NightwatchScreenshotOptions;
  // ... additional settings
}

export interface WebdriverOptions {
  start_process?: boolean;
  server_path?: string | null;
  host?: string;
  port?: number;
  timeout_options?: TimeoutOptions;
  keep_alive?: boolean | { enabled: boolean; keepAliveMsecs: number };
  // ... additional options
}

Import

import { NightwatchOptions, NightwatchTestSettingGeneric, WebdriverOptions } from 'nightwatch';

I/O Contract

Inputs

Name	Type	Required	Description
test_settings	NightwatchTestSettings	Yes	Map of named environments (e.g., "default", "chrome", "firefox")
src_folders	string / string[]	No	Directories containing test files
custom_commands_path	string / string[]	No	Directories for custom command modules
webdriver	WebdriverOptions	No	WebDriver server configuration

Outputs

Name	Type	Description
Typed config object	NightwatchOptions	Fully typed configuration consumed by Nightwatch CLI and programmatic API

Usage Examples

TypeScript Configuration File

import { NightwatchOptions } from 'nightwatch';

const config: NightwatchOptions = {
  src_folders: ['tests'],
  custom_commands_path: ['commands'],
  page_objects_path: ['pages'],
  plugins: ['@nightwatch/react'],

  webdriver: {
    start_process: true,
    server_path: '',
  },

  test_settings: {
    default: {
      desiredCapabilities: {
        browserName: 'chrome',
      },
      baseUrl: 'http://localhost:3000',
    },
    firefox: {
      desiredCapabilities: {
        browserName: 'firefox',
      },
    },
  },
};

export default config;

Related Pages

Page Connections

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

Principle

Implementation

Heuristic

Environment