Implementation:Nightwatchjs Nightwatch RunTests API

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

Overview

Concrete API for executing Nightwatch.js test suites programmatically via runTests() and CliRunner.

Description

Nightwatch.runTests() accepts test source paths (string, array, or argv-like object) and optional settings, then runs the complete test pipeline. It returns a Promise resolving to a boolean (true = failures occurred, false = all passed). Nightwatch.CliRunner(argv) provides lower-level control, returning a CliRunner instance with setupAsync() and runTests() methods.

Usage

Call runTests() for simple execution scenarios. Use CliRunner when you need to control setup and execution phases independently.

Code Reference

Source Location

• Repository: nightwatch
• File: lib/index.js (lines 279-321)

Signature

// High-level API
Nightwatch.runTests(
  testSource?: string | string[] | Object,
  settings?: Object
) -> Promise<boolean>
// Returns: true = failures, false = all passed

// Low-level API
Nightwatch.CliRunner(argv?: Object) -> CliRunner

// CliRunner interface:
runner.setupAsync(settings?: Object) -> Promise<CliRunner>
runner.runTests() -> Promise<boolean>
runner.getTestsFiles() -> Promise<string[]>
runner.processListener.setExitCode(code: number) -> ProcessListener

Import

const Nightwatch = require('nightwatch');

I/O Contract

Inputs

Name	Type	Required	Description
testSource	string, string[], or Object	No	Test file path(s) or argv-like object with _source
settings	Object	No	Nightwatch settings to merge with configuration
argv.reporter	string or string[]	No	Reporter type(s) (default: 'junit')
argv.env	string	No	Browser environment name
argv.parallel	boolean	No	Enable parallel execution

Outputs

Name	Type	Description
Promise<boolean>	boolean	true = failures occurred, false = all tests passed

Usage Examples

Simple Test Execution

const Nightwatch = require('nightwatch');

// Run a single test file
Nightwatch.runTests('tests/login.js')
  .then(hasFailures => {
    console.log(hasFailures ? 'Tests failed' : 'All tests passed');
    process.exit(hasFailures ? 1 : 0);
  });

Advanced with CliRunner

const Nightwatch = require('nightwatch');

async function runCustom() {
  const runner = Nightwatch.CliRunner({
    _source: ['tests/smoke/*.js'],
    env: 'chrome',
    reporter: ['junit', 'html']
  });

  await runner.setupAsync({ silent: false });
  const hasFailures = await runner.runTests();

  if (hasFailures) {
    runner.processListener.setExitCode(10);
  }
}

runCustom();

Run Multiple Test Sources

const Nightwatch = require('nightwatch');

// Run multiple test files
Nightwatch.runTests(['tests/auth.js', 'tests/checkout.js'], {
  globals: { baseUrl: 'https://staging.example.com' }
}).then(hasFailures => {
  process.exit(hasFailures ? 1 : 0);
});

Related Pages

Implements Principle

• Principle:Nightwatchjs_Nightwatch_Programmatic_Test_Execution

Requires Environment

• Environment:Nightwatchjs_Nightwatch_Node_18_Runtime