Implementation:Nightwatchjs Nightwatch Nightwatch Configuration

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

Overview

Configuration module pattern for defining Nightwatch.js test execution settings, timeouts, globals, and environment-specific overrides.

Description

The Nightwatch configuration is a module.exports object in nightwatch.conf.js (or nightwatch.json). The globals module defines runtime parameters consumed by CliRunner.setup() and the test runner. Key settings include assertion failure behavior, wait condition timeouts and polling intervals, async hook timeouts, and retry windows.

Usage

Create or modify the configuration file whenever adjusting test execution behavior, adding new browser environments, changing timeouts, or setting up CI/CD-specific overrides.

Code Reference

Source Location

Repository: nightwatch
File: examples/globalsModule.js (lines 1-71)
File: examples/globals.json (lines 1-9)

Signature

module.exports = {
  // Abort test on assertion failure (used in waitFor and expect)
  abortOnAssertionFailure: Boolean,      // default: true

  // Polling interval for waitFor commands (ms)
  waitForConditionPollInterval: Number,   // default: 500

  // Default timeout for waitFor commands (ms)
  waitForConditionTimeout: Number,        // default: 5000

  // Throw error if multiple elements match selector
  throwOnMultipleElementsReturned: Boolean, // default: false

  // Timeout for async hooks (before/after/beforeEach/afterEach)
  asyncHookTimeout: Number,               // default: 10000

  // Timeout for async unit tests
  unitTestsTimeout: Number,               // default: 2000

  // Timeout for custom reporter callback
  customReporterCallbackTimeout: Number,   // default: 20000

  // Auto-retry failed assertions within this window (ms)
  retryAssertionTimeout: Number,           // default: 1000

  // Environment-specific overrides
  'default': { /* global defaults */ },
  'test_env': { /* environment overrides */ }
};

Import

// Configuration is loaded automatically by Nightwatch from:
// nightwatch.conf.js, nightwatch.conf.cjs, or nightwatch.json
// The globals file is referenced via the "globals_path" setting

I/O Contract

Inputs

Name	Type	Required	Description
abortOnAssertionFailure	Boolean	No	Halt test execution on assertion failure (default: true)
waitForConditionPollInterval	Number	No	Polling interval in ms for waitFor commands (default: 500)
waitForConditionTimeout	Number	No	Timeout in ms for waitFor commands (default: 5000)
asyncHookTimeout	Number	No	Timeout in ms for async lifecycle hooks (default: 10000)
retryAssertionTimeout	Number	No	Auto-retry window in ms for failed assertions (default: 1000)

Outputs

Name	Type	Description
Settings object	Object	Configuration consumed by CliRunner.setup() and the test runner

Usage Examples

Basic Globals Module

// globals.js
module.exports = {
  abortOnAssertionFailure: true,
  waitForConditionPollInterval: 500,
  waitForConditionTimeout: 5000,
  asyncHookTimeout: 10000,
  retryAssertionTimeout: 1000,

  'default': {
    myGlobal: function() {
      return 'I am a method';
    }
  },

  'test_env': {
    myGlobal: 'test_global'
  }
};

JSON Globals

{
  "waitForConditionPollInterval": 100,
  "waitForConditionTimeout": 5000,
  "retryAssertionTimeout": 1000,
  "myGlobal": "some value"
}

Related Pages

Implements Principle

Principle:Nightwatchjs_Nightwatch_Configuration_Setup

Requires Environment

Uses Heuristic

Page Connections

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

Principle

Implementation

Heuristic

Environment