0
# Browser Control & Navigation
1

2
Core browser session management, navigation, and window control operations for test setup and teardown.
3

4
## Capabilities
5

6
### Session Management
7

8
Control WebDriver browser sessions including initialization, termination, and debugging.
9

10
```javascript { .api }
11
/**
12
 * Initialize WebDriver session with configured capabilities
13
 * @returns Promise resolving when session is ready
14
 */
15
browser.init();
16

17
/**
18
 * End the current WebDriver session gracefully
19
 * @param endSession - Whether to close browser (default: true)
20
 * @returns Promise resolving when session ended
21
 */
22
browser.end(endSession?: boolean);
23

24
/**
25
 * Quit the WebDriver session immediately
26
 * @returns Promise resolving when session terminated
27
 */
28
browser.quit();
29

30
/**
31
 * Pause test execution for specified duration
32
 * @param ms - Milliseconds to pause
33
 * @returns Promise resolving after pause
34
 */
35
browser.pause(ms: number);
36

37
/**
38
 * Enter interactive debug mode
39
 * @returns Promise resolving when debug session ends
40
 */
41
browser.debug();
42

43
/**
44
 * Perform sequence of WebDriver actions
45
 * @param actions - Array of actions to perform
46
 * @returns Promise resolving when actions complete
47
 */
48
browser.perform(actions: Action[]);
49
```
50

51
**Usage Examples:**
52

53
```javascript
54
// Initialize session at test start
55
browser.init();
56

57
// Pause execution
58
browser.pause(2000); // Wait 2 seconds
59

60
// End session at test completion
61
browser.end();
62
```
63

64
### Page Navigation
65

66
Navigate between pages and manage browser history.
67

68
```javascript { .api }
69
/**
70
 * Navigate to specified URL
71
 * @param url - URL to navigate to
72
 * @returns Promise resolving when navigation completes
73
 */
74
browser.url(url: string);
75

76
/**
77
 * Navigate back in browser history
78
 * @returns Promise resolving when navigation completes
79
 */
80
browser.back();
81

82
/**
83
 * Navigate forward in browser history
84
 * @returns Promise resolving when navigation completes
85
 */
86
browser.forward();
87

88
/**
89
 * Refresh the current page
90
 * @returns Promise resolving when page reloads
91
 */
92
browser.refresh();
93

94
/**
95
 * Get current page URL
96
 * @returns Promise resolving with current URL
97
 */
98
browser.getCurrentUrl(): Promise<string>;
99

100
/**
101
 * Get page title
102
 * @returns Promise resolving with page title
103
 */
104
browser.getTitle(): Promise<string>;
105

106
/**
107
 * Get or set URL hash fragment
108
 * @param hash - Hash to set (optional)
109
 * @returns Promise resolving with current hash
110
 */
111
browser.urlHash(hash?: string): Promise<string>;
112
```
113

114
**Usage Examples:**
115

116
```javascript
117
// Navigate to page
118
browser.url("https://example.com");
119

120
// Navigate back and forward
121
browser.back();
122
browser.forward();
123

124
// Get current location
125
browser.getCurrentUrl().then(url => {
126
  console.log("Current URL:", url);
127
});
128
```
129

130
### Window Management
131

132
Control browser window size, position, and state.
133

134
```javascript { .api }
135
/**
136
 * Maximize browser window
137
 * @returns Promise resolving when window maximized
138
 */
139
browser.maximizeWindow();
140

141
/**
142
 * Resize window to specific dimensions
143
 * @param width - Window width in pixels
144
 * @param height - Window height in pixels
145
 * @returns Promise resolving when window resized
146
 */
147
browser.resizeWindow(width: number, height: number);
148

149
/**
150
 * Get current window dimensions
151
 * @returns Promise resolving with window size object
152
 */
153
browser.getWindowSize(): Promise<{width: number, height: number}>;
154

155
/**
156
 * Set window dimensions
157
 * @param width - Window width in pixels
158
 * @param height - Window height in pixels
159
 * @returns Promise resolving when size set
160
 */
161
browser.setWindowSize(width: number, height: number);
162

163
/**
164
 * Get current window position
165
 * @returns Promise resolving with position object
166
 */
167
browser.getWindowPosition(): Promise<{x: number, y: number}>;
168

169
/**
170
 * Set window position
171
 * @param x - X coordinate in pixels
172
 * @param y - Y coordinate in pixels
173
 * @returns Promise resolving when position set
174
 */
175
browser.setWindowPosition(x: number, y: number);
176

177
/**
178
 * Get window rectangle (position and size)
179
 * @returns Promise resolving with rectangle object
180
 */
181
browser.getWindowRect(): Promise<{x: number, y: number, width: number, height: number}>;
182

183
/**
184
 * Set window rectangle
185
 * @param options - Rectangle properties
186
 * @returns Promise resolving when rectangle set
187
 */
188
browser.setWindowRect(options: {x?: number, y?: number, width?: number, height?: number});
189
```
190

191
**Usage Examples:**
192

193
```javascript
194
// Maximize window for consistent testing
195
browser.maximizeWindow();
196

197
// Set specific window size
198
browser.setWindowSize(1024, 768);
199

200
// Position window
201
browser.setWindowPosition(100, 100);
202
```
203

204
### Page Content Operations
205

206
Capture page content, screenshots, and inject scripts.
207

208
```javascript { .api }
209
/**
210
 * Get complete page HTML source
211
 * @returns Promise resolving with HTML source string
212
 */
213
browser.pageSource(): Promise<string>;
214

215
/**
216
 * Capture and save screenshot
217
 * @param filename - Path to save screenshot
218
 * @returns Promise resolving when screenshot saved
219
 */
220
browser.saveScreenshot(filename: string);
221

222
/**
223
 * Save DOM snapshot to file
224
 * @param filename - Path to save snapshot
225
 * @returns Promise resolving when snapshot saved
226
 */
227
browser.saveSnapshot(filename: string);
228

229
/**
230
 * Inject JavaScript into page
231
 * @param script - JavaScript code to inject
232
 * @returns Promise resolving when script injected
233
 */
234
browser.injectScript(script: string);
235

236
/**
237
 * Execute synchronous JavaScript
238
 * @param script - JavaScript code to execute
239
 * @param args - Arguments to pass to script
240
 * @returns Promise resolving with script result
241
 */
242
browser.executeScript(script: string | Function, ...args: any[]): Promise<any>;
243

244
/**
245
 * Execute asynchronous JavaScript
246
 * @param script - JavaScript code to execute
247
 * @param args - Arguments to pass to script
248
 * @returns Promise resolving with script result
249
 */
250
browser.executeAsyncScript(script: string | Function, ...args: any[]): Promise<any>;
251
```
252

253
**Usage Examples:**
254

255
```javascript
256
// Capture screenshot
257
browser.saveScreenshot("./screenshots/test-result.png");
258

259
// Execute JavaScript
260
browser.executeScript("return document.title;").then(title => {
261
  console.log("Page title:", title);
262
});
263

264
// Get page source
265
browser.pageSource().then(html => {
266
  console.log("Page HTML length:", html.length);
267
});
268
```
269

270
### Cookie Management
271

272
Manage browser cookies for authentication and state management.
273

274
```javascript { .api }
275
/**
276
 * Get specific cookie by name
277
 * @param name - Cookie name
278
 * @returns Promise resolving with cookie object
279
 */
280
browser.getCookie(name: string): Promise<Cookie>;
281

282
/**
283
 * Get all cookies for current domain
284
 * @returns Promise resolving with array of cookies
285
 */
286
browser.getCookies(): Promise<Cookie[]>;
287

288
/**
289
 * Set cookie with properties
290
 * @param cookie - Cookie object to set
291
 * @returns Promise resolving when cookie set
292
 */
293
browser.setCookie(cookie: Cookie);
294

295
/**
296
 * Delete specific cookie by name
297
 * @param name - Cookie name to delete
298
 * @returns Promise resolving when cookie deleted
299
 */
300
browser.deleteCookie(name: string);
301

302
/**
303
 * Delete all cookies for current domain
304
 * @returns Promise resolving when cookies deleted
305
 */
306
browser.deleteCookies();
307

308
interface Cookie {
309
  name: string;
310
  value: string;
311
  domain?: string;
312
  path?: string;
313
  expires?: Date;
314
  httpOnly?: boolean;
315
  secure?: boolean;
316
}
317
```
318

319
**Usage Examples:**
320

321
```javascript
322
// Set authentication cookie
323
browser.setCookie({
324
  name: "auth_token",
325
  value: "abc123",
326
  domain: "example.com",
327
  path: "/",
328
  httpOnly: true
329
});
330

331
// Get specific cookie
332
browser.getCookie("auth_token").then(cookie => {
333
  console.log("Auth token:", cookie.value);
334
});
335

336
// Clear all cookies
337
browser.deleteCookies();
338
```
339

340
### Selector Strategy
341

342
Configure element location strategies for finding elements.
343

344
```javascript { .api }
345
/**
346
 * Use CSS selector strategy for element finding
347
 * @returns Promise resolving when strategy set
348
 */
349
browser.useCss();
350

351
/**
352
 * Use XPath selector strategy for element finding
353
 * @returns Promise resolving when strategy set
354
 */
355
browser.useXpath();
356
```
357

358
**Usage Examples:**
359

360
```javascript
361
// Switch to XPath strategy
362
browser.useXpath();
363
browser.click("//button[@type='submit']");
364

365
// Switch back to CSS strategy
366
browser.useCss();
367
browser.click("button[type='submit']");
368
```
369

370
### Context Operations
371

372
Execute commands within specific element contexts.
373

374
```javascript { .api }
375
/**
376
 * Execute commands within element context
377
 * @param selector - Element selector for context
378
 * @param callback - Function to execute in context
379
 * @returns Promise resolving when context operations complete
380
 */
381
browser.within(selector: string, callback: (api: NightwatchAPI) => void);
382
```
383

384
**Usage Examples:**
385

386
```javascript
387
// Execute commands within a form context
388
browser.within("#login-form", (form) => {
389
  form.setValue("input[name='username']", "testuser");
390
  form.setValue("input[name='password']", "password123");
391
  form.click("button[type='submit']");
392
});
393
```