Principle:Nightwatchjs Nightwatch Programmatic Test Execution
| Knowledge Sources | |
|---|---|
| Domains | Testing, API, Test_Orchestration |
| Last Updated | 2026-02-12 00:00 GMT |
Overview
A programmatic test suite execution pattern that runs test files through the full test runner lifecycle from Node.js code.
Description
Programmatic Test Execution provides an API for running complete test suites from code rather than the CLI. The runTests() method accepts test file paths and optional settings, then executes the full test runner lifecycle: configuration loading, WebDriver session creation, test execution, and result collection. The CliRunner class provides lower-level control over the same pipeline.
This enables custom orchestration scenarios like: running specific tests based on code changes, implementing retry logic, aggregating results across multiple runs, or integrating with deployment pipelines.
Usage
Use runTests() for simple programmatic execution, CliRunner for advanced control over the test lifecycle.
Theoretical Basis
Programmatic execution abstracts the CLI pipeline into API calls:
- runTests(source, settings): High-level — runs tests and returns result
- CliRunner(argv): Low-level — provides setupAsync() and runTests() steps
- Both manage the same pipeline: config → session → execute → report