0
# Nightwatch.js
1

2
Nightwatch.js is a comprehensive Node.js-based end-to-end testing framework that provides APIs for browser automation, element interaction, assertions, and mobile testing. It offers an integrated testing solution supporting multiple types of testing including end-to-end web application testing, component testing, unit testing, visual regression testing, accessibility testing, API testing, and native mobile app testing.
3

4
## Package Information
5

6
- **Package Name**: nightwatch
7
- **Package Type**: npm
8
- **Language**: JavaScript/TypeScript
9
- **Installation**: `npm install nightwatch`
10

11
## Core Imports
12

13
Main module import:
14
```javascript
15
// ES6 Modules
16
import Nightwatch from "nightwatch";
17

18
// CommonJS
19
const Nightwatch = require("nightwatch");
20
```
21

22
Named exports (available in Nightwatch v2+):
23
```javascript
24
// ES6 named imports
25
import { browser, app, element, expect, assert, verify } from "nightwatch";
26

27
// CommonJS destructuring
28
const { browser, app, element, expect, assert, verify } = require("nightwatch");
29
```
30

31
Selenium WebDriver utilities:
32
```javascript
33
// ES6 named imports
34
import { By, Key, Capabilities } from "nightwatch";
35

36
// CommonJS destructuring
37
const { By, Key, Capabilities } = require("nightwatch");
38
```
39

40
Global APIs (available in test files):
41
```javascript
42
// Available globally in test files without imports
43
browser.url("https://example.com");
44
browser.assert.titleContains("Example");
45
expect(element("#selector")).to.be.visible;
46
```
47

48
## Basic Usage
49

50
```javascript
51
// Basic test example
52
module.exports = {
53
  "Demo test": function(browser) {
54
    browser
55
      .url("https://example.com")
56
      .waitForElementVisible("body", 1000)
57
      .assert.titleContains("Example")
58
      .assert.visible("input[type=text]")
59
      .setValue("input[type=text]", "nightwatch")
60
      .waitForElementVisible("button[type=submit]", 1000)
61
      .click("button[type=submit]")
62
      .pause(1000)
63
      .assert.containsText("#results", "success")
64
      .end();
65
  }
66
};
67
```
68

69
## Architecture
70

71
Nightwatch.js is built around several key components:
72

73
- **NightwatchClient**: Core client managing WebDriver sessions and command execution
74
- **TestSuite**: Test suite orchestration with lifecycle hooks and reporting
75
- **Element API**: Modern element wrapper providing fluent interactions and queries
76
- **Command Queue**: Asynchronous command queue ensuring proper execution order
77
- **Transport Layer**: WebDriver protocol implementation supporting multiple browsers
78
- **Assertion Engine**: Comprehensive assertion library with expect-style and assert-style APIs
79
- **Page Object Model**: Structured approach for organizing test elements and actions
80

81
## Capabilities
82

83
### Browser Control & Navigation
84

85
Core browser session management, navigation, and window control operations for test setup and teardown.
86

87
```javascript { .api }
88
// Session Management
89
browser.init();
90
browser.end();
91
browser.quit();
92

93
// Navigation
94
browser.url(url);
95
browser.back();
96
browser.forward();
97
browser.refresh();
98

99
// Window Management
100
browser.maximizeWindow();
101
browser.resizeWindow(width, height);
102
browser.getWindowSize();
103
browser.setWindowSize(width, height);
104
```
105

106
[Browser Control](./browser-control.md)
107

108
### Element Interaction
109

110
Comprehensive element finding, interaction, and property access APIs for web element automation.
111

112
```javascript { .api }
113
// Element Finding
114
browser.findElement(selector);
115
browser.findElements(selector);
116
browser.element(selector);
117

118
// Element Interaction
119
browser.click(selector);
120
browser.setValue(selector, value);
121
browser.clearValue(selector);
122
browser.sendKeys(selector, keys);
123

124
// Element State
125
browser.isVisible(selector);
126
browser.isPresent(selector);
127
browser.isEnabled(selector);
128
browser.getText(selector);
129
browser.getValue(selector);
130
```
131

132
[Element Interaction](./element-interaction.md)
133

134
### Modern Element API
135

136
Modern fluent element API providing chainable operations and built-in waiting mechanisms.
137

138
```javascript { .api }
139
// Element Creation
140
const element = browser.element(selector);
141

142
// Element Queries
143
element.findByText(text);
144
element.findByRole(role);
145
element.findByPlaceholderText(text);
146

147
// Element Actions
148
element.click();
149
element.sendKeys(...keys);
150
element.clear();
151
element.check();
152
element.uncheck();
153

154
// Element Properties
155
element.getText();
156
element.getValue();
157
element.getAttribute(name);
158
element.isVisible();
159
element.isEnabled();
160
```
161

162
[Modern Element API](./modern-element-api.md)
163

164
### Assertions & Expectations
165

166
Comprehensive assertion library supporting both assert-style and expect-style validation patterns.
167

168
```javascript { .api }
169
// Assert-style Assertions
170
browser.assert.titleContains(expected);
171
browser.assert.visible(selector);
172
browser.assert.textContains(selector, text);
173
browser.assert.urlContains(expected);
174

175
// Expect-style Assertions
176
browser.expect.element(selector).to.be.visible;
177
browser.expect.element(selector).text.to.contain(expected);
178
browser.expect.title().to.equal(expected);
179
browser.expect.url().to.match(regex);
180
```
181

182
[Assertions & Expectations](./assertions-expectations.md)
183

184
### Page Object Model
185

186
Structured page object pattern for organizing elements, sections, and custom commands.
187

188
```javascript { .api }
189
// Page Object Definition
190
interface PageObject {
191
  url: string | (() => string);
192
  elements: Record<string, ElementProperties>;
193
  sections: Record<string, SectionProperties>;
194
  commands: Record<string, Function>;
195
}
196

197
// Page Object Usage
198
const loginPage = browser.page.loginPage();
199
loginPage.navigate();
200
loginPage.fillForm(username, password);
201
loginPage.submit();
202
```
203

204
[Page Object Model](./page-object-model.md)
205

206
### Advanced Features
207

208
Advanced testing capabilities including performance monitoring, accessibility testing, and mobile support.
209

210
```javascript { .api }
211
// Performance & Monitoring
212
browser.takeHeapSnapshot();
213
browser.enablePerformanceMetrics();
214
browser.getPerformanceMetrics();
215

216
// Accessibility Testing
217
browser.axeInject();
218
browser.axeRun(options);
219

220
// Mobile Testing
221
browser.isIOS();
222
browser.isAndroid();
223
browser.isMobile();
224
browser.setGeolocation(latitude, longitude);
225
```
226

227
[Advanced Features](./advanced-features.md)
228

229
### Programmatic API
230

231
Programmatic client creation and test runner for integrating Nightwatch into custom applications and workflows.
232

233
```javascript { .api }
234
// Create programmatic client
235
Nightwatch.createClient(options);
236

237
// Run tests programmatically
238
Nightwatch.runTests(testSource, settings);
239

240
// CLI runner
241
Nightwatch.CliRunner(argv);
242

243
// Initialize client
244
Nightwatch.initClient(opts);
245
```
246

247
[Programmatic API](./programmatic-api.md)
248

249
### Protocol Commands
250

251
Low-level WebDriver protocol commands for fine-grained browser control and automation.
252

253
```javascript { .api }
254
// WebDriver Protocol
255
browser.session();
256
browser.status();
257
browser.navigateTo(url);
258
browser.getCurrentUrl();
259

260
// Element Protocol
261
browser.elementIdClick(id);
262
browser.elementIdText(id);
263
browser.elementIdAttribute(id, name);
264

265
// Mouse & Keyboard
266
browser.moveTo(element, xOffset, yOffset);
267
browser.mouseButtonClick(button);
268
browser.keys(keys);
269
```
270

271
[Protocol Commands](./protocol-commands.md)
272

273
### CLI Usage
274

275
Command-line interface for running tests, setup, and maintenance operations.
276

277
```javascript { .api }
278
// CLI commands
279
nightwatch [test-source] [options]
280
nightwatch --help
281
nightwatch --version
282
nightwatch --info
283
nightwatch --list-files
284
```
285

286
### Utilities
287

288
Utility APIs for HTTP requests and Chrome DevTools Protocol access.
289

290
```javascript { .api }
291
// HTTP utilities
292
Nightwatch.utils.HttpRequest;
293

294
// Chrome DevTools Protocol
295
Nightwatch.utils.cdp;
296

297
// Logger utilities
298
Nightwatch.Logger.log(message);
299
Nightwatch.Logger.info(message);
300
Nightwatch.Logger.warn(message);
301
Nightwatch.Logger.error(message);
302
```
303

304
## Global Objects
305

306
```javascript { .api }
307
// Available globally in test files
308
declare const browser: NightwatchAPI;
309
declare const app: NightwatchAPI; // Alias for browser
310
declare const element: (selector: string) => Element;
311
declare const expect: ExpectAPI;
312

313
// Selenium WebDriver imports
314
declare const By: typeof import('selenium-webdriver').By;
315
declare const Key: typeof import('selenium-webdriver').Key;
316
declare const locateWith: typeof import('selenium-webdriver').locateWith;
317
```
318

319
## Core Types
320

321
```javascript { .api }
322
interface NightwatchAPI {
323
  // Session Management
324
  sessionId: string;
325
  capabilities: Capabilities;
326
  desiredCapabilities: Capabilities;
327
  
328
  // Browser Detection
329
  isChrome(): boolean;
330
  isFirefox(): boolean;
331
  isSafari(): boolean;
332
  isIOS(): boolean;
333
  isAndroid(): boolean;
334
  isMobile(): boolean;
335
  
336
  // Test Information
337
  currentTest: {
338
    name: string;
339
    module: string;
340
    results: TestResults;
341
  };
342
  
343
  // Globals
344
  globals: NightwatchGlobals;
345
  options: NightwatchOptions;
346
}
347

348
interface NightwatchClient {
349
  api: NightwatchAPI;
350
  queue: CommandQueue;
351
  transport: Transport;
352
  sessionId: string;
353
  
354
  initialize(): Promise<void>;
355
  createSession(): Promise<SessionData>;
356
  createTransport(): void;
357
}
358

359
interface TestSuite {
360
  client: NightwatchClient;
361
  api: NightwatchAPI;
362
  context: Context;
363
  reporter: Reporter;
364
  
365
  run(): Promise<boolean>;
366
  createSession(): Promise<void>;
367
  runTestSuite(): Promise<boolean>;
368
}
369
```