Workflow:Nightwatchjs Nightwatch Programmatic API Usage
| Knowledge Sources | |
|---|---|
| Domains | CI_CD, Test_Automation, Node_js |
| Last Updated | 2026-02-12 00:00 GMT |
Overview
End-to-end process for using Nightwatch's programmatic API to run tests from Node.js code without the CLI, enabling integration with custom build pipelines, task runners, and CI/CD systems.
Description
This workflow covers using Nightwatch as a library rather than a CLI tool. The programmatic API provides functions to create browser clients, run test suites, and process results entirely from JavaScript code. This is valuable for embedding Nightwatch in custom tooling, integrating with existing build systems, or creating dynamic test execution workflows that require runtime configuration. The API exposes createClient(), runTests(), and CliRunner for full control over the test lifecycle.
Usage
Execute this workflow when you need to run Nightwatch tests from within another Node.js application, a custom CI script, or a build tool that requires programmatic control over test execution. This includes scenarios where test configuration must be computed at runtime, results need custom processing, or tests must be orchestrated as part of a larger automated pipeline.
Execution Steps
Step 1: Import Nightwatch Module
Import the Nightwatch module in your Node.js script. The module exports several key functions including createClient for single browser sessions, runTests for suite execution, and CliRunner for full CLI-equivalent functionality.
Key considerations:
- Import via require('nightwatch') or ES module import
- The module provides createClient(), runTests(), cli(), and CliRunner
- Each function serves a different level of control over test execution
Step 2: Configure Client Options
Prepare the configuration object specifying browser name, headless mode, environment, and other settings. The programmatic API accepts the same options as nightwatch.conf.js but as a JavaScript object passed at runtime.
What happens:
- Specify browserName (chrome, firefox, edge, safari)
- Set headless mode and other capability flags
- Define the environment name to load environment-specific settings
- Optionally pass a custom configuration file path
Step 3: Create and Initialize Client
Call createClient() with the configuration options to instantiate a Nightwatch browser client. The client creates a WebDriver session and returns a browser object with the full Nightwatch command API.
Key considerations:
- createClient() returns an object with a launchBrowser() method
- launchBrowser() establishes the WebDriver session and returns the browser object
- The browser object has all standard Nightwatch commands available
- Multiple clients can be created for parallel browser sessions
Step 4: Execute Browser Commands
Use the browser object returned by launchBrowser() to execute Nightwatch commands programmatically. All standard commands (navigateTo, click, setValue, assert) are available with the same API as test files.
What happens:
- Call browser.navigateTo(), browser.click(), etc. as in regular tests
- Commands return promises for async/await usage
- Assert and expect APIs are available on the browser object
- The findElement and element APIs work identically to test-file usage
Step 5: Run Test Suites Programmatically
Alternatively, use runTests() or CliRunner to execute entire test suites from code. This provides the same functionality as the CLI runner but with programmatic control over configuration, filtering, and result handling.
Key considerations:
- runTests() accepts settings and source paths
- CliRunner provides the most complete API matching CLI behavior
- Results can be captured and processed in custom reporters
- Exit codes indicate pass/fail status for CI integration
Step 6: Cleanup and Process Results
End the browser session and process test results. The client provides cleanup methods to close the WebDriver session, and results can be examined programmatically for custom reporting or conditional logic.
What happens:
- Call browser.quit() or browser.end() to close the session
- Capture test results from the returned data structures
- Process results for custom dashboards, notifications, or retry logic
- Handle errors and timeouts gracefully for CI stability