# nightwatchjs/nightwatch architecture

> Architecture diagram of the GitHub repository nightwatchjs/nightwatch, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nightwatchjs/nightwatch
- Repository: https://github.com/nightwatchjs/nightwatch

## Overview

Nightwatch is a Node.js test-automation framework: a test author runs suites through its CLI or programmatic API, test-runner integrations execute cases and hooks, and the Nightwatch client sends browser or mobile commands through WebDriver/Appium transports. Results, assertions, screenshots and reports support the feedback loop. The README also documents component, visual-regression, accessibility and API testing capabilities; corresponding visible API, screenshot and axe modules are included, while API-test wiring is not inferred from the sampled HTTP transport. Source excerpts are partial, so some subsystem links are omitted.

Main entry points: [`lib/transport/factory.js`](https://github.com/nightwatchjs/nightwatch/blob/main/lib/transport/factory.js) (Transport factory), [`lib/api/index.js`](https://github.com/nightwatchjs/nightwatch/blob/main/lib/api/index.js) (API loading), [`lib/testsuite/index.js`](https://github.com/nightwatchjs/nightwatch/blob/main/lib/testsuite/index.js) (Suite lifecycle), [`lib/runner/runner.js`](https://github.com/nightwatchjs/nightwatch/blob/main/lib/runner/runner.js) (Suite runner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_execution["Test execution"]
  node_cli["CLI entry<br/>[cli.js]"]
  node_runner["Suite runner<br/>[runner.js]"]
  node_frameworks["Test integrations"]
  node_suite["Suite lifecycle<br/>[index.js]"]
  node_settings["Configuration<br/>[settings.js]"]
end

subgraph group_automation["Automation API"]
  node_client["Nightwatch client<br/>[client.js]"]
  node_api["API loading<br/>[index.js]"]
  node_commands["Browser commands"]
  node_elements["Element commands"]
  node_webelement["Web elements"]
  node_assertions["Assertions"]
  node_expect["Expect API"]
  node_pageobjects["Page objects<br/>[index.js]"]
end

subgraph group_connectivity["Device connectivity"]
  node_transport["Transport factory<br/>[factory.js]"]
  node_webdriver["WebDriver transport<br/>[index.js]"]
  node_http["HTTP requests<br/>[request.js]"]
  node_appium["Appium support<br/>[appium.js]"]
end

subgraph group_feedback["Results and feedback"]
  node_reporter["Reporter<br/>[index.js]"]
  node_results["Test results<br/>[results.js]"]
  node_screenshots["Visual capture<br/>[screenshots.js]"]
  node_axe["Accessibility checks<br/>[axeRun.js]"]
end

node_author(("Test author"))
node_browser(("Browser or device"))
node_external(("WebDriver endpoint"))

node_author -->|"starts tests"| node_cli
node_author -->|"defines cases"| node_suite
node_cli -->|"starts runner"| node_runner
node_runner -->|"loads settings"| node_settings
node_runner -->|"selects runner"| node_frameworks
node_runner -->|"runs suites"| node_suite
node_frameworks -->|"executes cases"| node_suite
node_suite -->|"creates client"| node_client
node_client -->|"uses settings"| node_settings
node_client -->|"loads APIs"| node_api
node_api -->|"registers commands"| node_commands
node_api -->|"registers commands"| node_elements
node_api -->|"registers assertions"| node_assertions
node_api -->|"registers expect"| node_expect
node_api -->|"loads objects"| node_pageobjects
node_elements -->|"builds element API"| node_webelement
node_suite -->|"records outcomes"| node_reporter
node_client -->|"creates transport"| node_transport
node_transport -->|"selects driver"| node_webdriver
node_transport -.->|"selects mobile"| node_appium
node_commands -->|"dispatches commands"| node_transport
node_elements -->|"dispatches commands"| node_transport
node_assertions -->|"checks browser state"| node_transport
node_expect -->|"checks browser state"| node_transport
node_webdriver -->|"sends requests"| node_http
node_http -->|"WebDriver protocol"| node_external
node_external -->|"controls session"| node_browser
node_appium -.->|"controls device"| node_external
node_reporter -->|"updates results"| node_results
node_suite -->|"captures on error"| node_screenshots
node_commands -->|"runs accessibility"| node_axe
node_reporter -->|"reports outcomes"| node_author

click node_cli "https://github.com/nightwatchjs/nightwatch/blob/main/lib/runner/cli/cli.js"
click node_runner "https://github.com/nightwatchjs/nightwatch/blob/main/lib/runner/runner.js"
click node_frameworks "https://github.com/nightwatchjs/nightwatch/tree/main/lib/runner/test-runners"
click node_suite "https://github.com/nightwatchjs/nightwatch/blob/main/lib/testsuite/index.js"
click node_settings "https://github.com/nightwatchjs/nightwatch/blob/main/lib/settings/settings.js"
click node_client "https://github.com/nightwatchjs/nightwatch/blob/main/lib/core/client.js"
click node_api "https://github.com/nightwatchjs/nightwatch/blob/main/lib/api/index.js"
click node_commands "https://github.com/nightwatchjs/nightwatch/tree/main/lib/api/client-commands"
click node_elements "https://github.com/nightwatchjs/nightwatch/tree/main/lib/api/element-commands"
click node_webelement "https://github.com/nightwatchjs/nightwatch/tree/main/lib/api/web-element"
click node_assertions "https://github.com/nightwatchjs/nightwatch/tree/main/lib/api/assertions"
click node_expect "https://github.com/nightwatchjs/nightwatch/tree/main/lib/api/expect"
click node_pageobjects "https://github.com/nightwatchjs/nightwatch/blob/main/lib/page-object/index.js"
click node_transport "https://github.com/nightwatchjs/nightwatch/blob/main/lib/transport/factory.js"
click node_webdriver "https://github.com/nightwatchjs/nightwatch/blob/main/lib/transport/selenium-webdriver/index.js"
click node_http "https://github.com/nightwatchjs/nightwatch/blob/main/lib/http/request.js"
click node_appium "https://github.com/nightwatchjs/nightwatch/blob/main/lib/transport/selenium-webdriver/appium.js"
click node_reporter "https://github.com/nightwatchjs/nightwatch/blob/main/lib/reporter/index.js"
click node_results "https://github.com/nightwatchjs/nightwatch/blob/main/lib/reporter/results.js"
click node_screenshots "https://github.com/nightwatchjs/nightwatch/blob/main/lib/utils/screenshots.js"
click node_axe "https://github.com/nightwatchjs/nightwatch/blob/main/lib/api/client-commands/axeRun.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_runner,node_frameworks,node_suite,node_settings,node_browser toneBlue
class node_client,node_api,node_commands,node_elements,node_webelement,node_assertions,node_expect,node_pageobjects toneAmber
class node_transport,node_webdriver,node_http,node_appium toneMint
class node_reporter,node_results,node_screenshots,node_axe toneRose
class node_author,node_external toneIndigo
```

## Components

### Test execution

- [CLI entry](https://github.com/nightwatchjs/nightwatch/blob/main/lib/runner/cli/cli.js): `lib/runner/cli/cli.js`
- [Suite runner](https://github.com/nightwatchjs/nightwatch/blob/main/lib/runner/runner.js): `lib/runner/runner.js`
- [Test integrations](https://github.com/nightwatchjs/nightwatch/tree/main/lib/runner/test-runners): `lib/runner/test-runners`
- [Suite lifecycle](https://github.com/nightwatchjs/nightwatch/blob/main/lib/testsuite/index.js): `lib/testsuite/index.js`
- [Configuration](https://github.com/nightwatchjs/nightwatch/blob/main/lib/settings/settings.js): `lib/settings/settings.js`

### Automation API

- [Nightwatch client](https://github.com/nightwatchjs/nightwatch/blob/main/lib/core/client.js): `lib/core/client.js`
- [API loading](https://github.com/nightwatchjs/nightwatch/blob/main/lib/api/index.js): `lib/api/index.js`
- [Browser commands](https://github.com/nightwatchjs/nightwatch/tree/main/lib/api/client-commands): `lib/api/client-commands`
- [Element commands](https://github.com/nightwatchjs/nightwatch/tree/main/lib/api/element-commands): `lib/api/element-commands`
- [Web elements](https://github.com/nightwatchjs/nightwatch/tree/main/lib/api/web-element): `lib/api/web-element`
- [Assertions](https://github.com/nightwatchjs/nightwatch/tree/main/lib/api/assertions): `lib/api/assertions`
- [Expect API](https://github.com/nightwatchjs/nightwatch/tree/main/lib/api/expect): `lib/api/expect`
- [Page objects](https://github.com/nightwatchjs/nightwatch/blob/main/lib/page-object/index.js): `lib/page-object/index.js`

### Device connectivity

- [Transport factory](https://github.com/nightwatchjs/nightwatch/blob/main/lib/transport/factory.js): `lib/transport/factory.js`
- [WebDriver transport](https://github.com/nightwatchjs/nightwatch/blob/main/lib/transport/selenium-webdriver/index.js): `lib/transport/selenium-webdriver/index.js`
- [HTTP requests](https://github.com/nightwatchjs/nightwatch/blob/main/lib/http/request.js): `lib/http/request.js`
- [Appium support](https://github.com/nightwatchjs/nightwatch/blob/main/lib/transport/selenium-webdriver/appium.js): `lib/transport/selenium-webdriver/appium.js`

### Results and feedback

- [Reporter](https://github.com/nightwatchjs/nightwatch/blob/main/lib/reporter/index.js): `lib/reporter/index.js`
- [Test results](https://github.com/nightwatchjs/nightwatch/blob/main/lib/reporter/results.js): `lib/reporter/results.js`
- [Visual capture](https://github.com/nightwatchjs/nightwatch/blob/main/lib/utils/screenshots.js): `lib/utils/screenshots.js`
- [Accessibility checks](https://github.com/nightwatchjs/nightwatch/blob/main/lib/api/client-commands/axeRun.js): `lib/api/client-commands/axeRun.js`

### Other components

- **Test author**
- **Browser or device**
- **WebDriver endpoint**

## Connections

- Test author → CLI entry: starts tests
- Test author → Suite lifecycle: defines cases
- CLI entry → Suite runner: starts runner
- Suite runner → Configuration: loads settings
- Suite runner → Test integrations: selects runner
- Suite runner → Suite lifecycle: runs suites
- Test integrations → Suite lifecycle: executes cases
- Suite lifecycle → Nightwatch client: creates client
- Nightwatch client → Configuration: uses settings
- Nightwatch client → API loading: loads APIs
- API loading → Browser commands: registers commands
- API loading → Element commands: registers commands
- API loading → Assertions: registers assertions
- API loading → Expect API: registers expect
- API loading → Page objects: loads objects
- Element commands → Web elements: builds element API
- Suite lifecycle → Reporter: records outcomes
- Nightwatch client → Transport factory: creates transport
- Transport factory → WebDriver transport: selects driver
- Transport factory → Appium support: selects mobile
- Browser commands → Transport factory: dispatches commands
- Element commands → Transport factory: dispatches commands
- Assertions → Transport factory: checks browser state
- Expect API → Transport factory: checks browser state
- WebDriver transport → HTTP requests: sends requests
- HTTP requests → WebDriver endpoint: WebDriver protocol
- WebDriver endpoint → Browser or device: controls session
- Appium support → WebDriver endpoint: controls device
- Reporter → Test results: updates results
- Suite lifecycle → Visual capture: captures on error
- Browser commands → Accessibility checks: runs accessibility
- Reporter → Test author: reports outcomes