0
# Navigation & Page Interaction
1

2
Navigation commands for browsing web pages, managing browser history, and retrieving page information.
3

4
## Capabilities
5

6
### Page Navigation
7

8
Navigate to URLs, refresh pages, and control browser history.
9

10
```javascript { .api }
11
/**
12
 * Navigate to a specific URL
13
 * @param url - Target URL to navigate to
14
 * @param cb - Callback receiving (err)
15
 */
16
get(url: string, cb?: callback): void;
17

18
/**
19
 * Refresh the current page
20
 * @param cb - Callback receiving (err)
21
 */
22
refresh(cb?: callback): void;
23

24
/**
25
 * Navigate back in browser history
26
 * @param cb - Callback receiving (err)
27
 */
28
back(cb?: callback): void;
29

30
/**
31
 * Navigate forward in browser history
32
 * @param cb - Callback receiving (err)
33
 */
34
forward(cb?: callback): void;
35
```
36

37
**Usage Examples:**
38

39
```javascript
40
// Navigate to different pages
41
browser.get('https://example.com', function(err) {
42
  if (err) throw err;
43
  console.log('Navigated to example.com');
44
});
45

46
// Use browser history
47
browser.back(function(err) {
48
  if (err) throw err;
49
  browser.forward(); // Go forward again
50
});
51

52
// Promise chain style
53
browser
54
  .get('https://example.com')
55
  .get('https://example.com/login')
56
  .back()                    // Return to homepage
57
  .refresh();                // Reload the page
58
```
59

60
### Page Information
61

62
Retrieve information about the current page.
63

64
```javascript { .api }
65
/**
66
 * Get current page URL
67
 * @param cb - Callback receiving (err, url)
68
 */
69
url(cb?: callback): string;
70

71
/**
72
 * Get current page title
73
 * @param cb - Callback receiving (err, title)
74
 */
75
title(cb?: callback): string;
76

77
/**
78
 * Get page source HTML
79
 * @param cb - Callback receiving (err, source)
80
 */
81
source(cb?: callback): string;
82
```
83

84
**Usage Examples:**
85

86
```javascript
87
// Get page information
88
browser.title(function(err, title) {
89
  console.log('Page title:', title);
90
});
91

92
browser.url(function(err, currentUrl) {
93
  console.log('Current URL:', currentUrl);
94
});
95

96
browser.source(function(err, html) {
97
  console.log('Page source length:', html.length);
98
});
99

100
// Promise chain style
101
browser
102
  .get('https://example.com')
103
  .title()
104
  .then(title => {
105
    console.log('Title:', title);
106
    return browser.url();
107
  })
108
  .then(url => {
109
    console.log('URL:', url);
110
  });
111
```
112

113
### Screenshot Capture
114

115
Capture screenshots of the current page or specific elements.
116

117
```javascript { .api }
118
/**
119
 * Take a screenshot of the current page
120
 * @param cb - Callback receiving (err, base64Image)
121
 */
122
takeScreenshot(cb?: callback): string;
123

124
/**
125
 * Save screenshot to file
126
 * @param filename - Path to save the screenshot
127
 * @param cb - Callback receiving (err)
128
 */
129
saveScreenshot(filename: string, cb?: callback): void;
130
```
131

132
**Usage Examples:**
133

134
```javascript
135
// Take screenshot and get base64 data
136
browser.takeScreenshot(function(err, base64Image) {
137
  if (err) throw err;
138
  console.log('Screenshot captured, size:', base64Image.length);
139
  
140
  // Save to file (you would need to decode base64)
141
  const fs = require('fs');
142
  fs.writeFileSync('screenshot.png', base64Image, 'base64');
143
});
144

145
// Save screenshot directly to file
146
browser.saveScreenshot('test-results/screenshot.png', function(err) {
147
  if (err) throw err;
148
  console.log('Screenshot saved');
149
});
150

151
// Promise chain style
152
browser
153
  .get('https://example.com')
154
  .saveScreenshot('./screenshots/homepage.png')
155
  .then(() => console.log('Screenshot saved'));
156
```
157

158
### Alert Handling
159

160
Handle JavaScript alerts, confirms, and prompts.
161

162
```javascript { .api }
163
/**
164
 * Get text from current alert dialog
165
 * @param cb - Callback receiving (err, text)
166
 */
167
alertText(cb?: callback): string;
168

169
/**
170
 * Send keys to alert prompt dialog
171
 * @param keys - Text to send to the prompt
172
 * @param cb - Callback receiving (err)
173
 */
174
alertKeys(keys: string, cb?: callback): void;
175

176
/**
177
 * Accept alert dialog (click OK)
178
 * @param cb - Callback receiving (err)
179
 */
180
acceptAlert(cb?: callback): void;
181

182
/**
183
 * Dismiss alert dialog (click Cancel)
184
 * @param cb - Callback receiving (err)
185
 */
186
dismissAlert(cb?: callback): void;
187
```
188

189
**Usage Examples:**
190

191
```javascript
192
// Handle a confirmation dialog
193
browser.alertText(function(err, text) {
194
  console.log('Alert text:', text);
195
  
196
  if (text.includes('Are you sure?')) {
197
    browser.acceptAlert(); // Click OK
198
  } else {
199
    browser.dismissAlert(); // Click Cancel
200
  }
201
});
202

203
// Handle a prompt dialog
204
browser.alertKeys('My input text', function(err) {
205
  browser.acceptAlert(); // Submit the prompt
206
});
207

208
// Promise chain style
209
browser
210
  .elementById('delete-button')
211
  .click()
212
  .alertText()
213
  .then(text => {
214
    console.log('Confirmation:', text);
215
    return browser.acceptAlert();
216
  });
217
```
218

219
### Cookie Management
220

221
Manage browser cookies for session handling and testing.
222

223
```javascript { .api }
224
/**
225
 * Get all cookies for current domain
226
 * @param cb - Callback receiving (err, cookies)
227
 */
228
allCookies(cb?: callback): Cookie[];
229

230
/**
231
 * Set a cookie
232
 * @param cookie - Cookie object to set
233
 * @param cb - Callback receiving (err)
234
 */
235
setCookie(cookie: Cookie, cb?: callback): void;
236

237
/**
238
 * Delete all cookies
239
 * @param cb - Callback receiving (err)
240
 */
241
deleteAllCookies(cb?: callback): void;
242

243
/**
244
 * Delete a specific cookie by name
245
 * @param name - Cookie name to delete
246
 * @param cb - Callback receiving (err)
247
 */
248
deleteCookie(name: string, cb?: callback): void;
249

250
interface Cookie {
251
  name: string;
252
  value: string;
253
  domain?: string;
254
  path?: string;
255
  secure?: boolean;
256
  httpOnly?: boolean;
257
  expiry?: number;
258
}
259
```
260

261
**Usage Examples:**
262

263
```javascript
264
// Set a cookie
265
browser.setCookie({
266
  name: 'session_id',
267
  value: 'abc123',
268
  domain: 'example.com',
269
  path: '/',
270
  secure: true
271
}, function(err) {
272
  if (err) throw err;
273
  console.log('Cookie set');
274
});
275

276
// Get all cookies
277
browser.allCookies(function(err, cookies) {
278
  cookies.forEach(cookie => {
279
    console.log(`${cookie.name}=${cookie.value}`);
280
  });
281
});
282

283
// Delete specific cookie
284
browser.deleteCookie('session_id');
285

286
// Clear all cookies
287
browser.deleteAllCookies();
288
```
289

290
### Local Storage
291

292
Access browser local storage for web application testing.
293

294
```javascript { .api }
295
/**
296
 * Set a local storage key-value pair
297
 * @param key - Storage key
298
 * @param value - Storage value
299
 * @param cb - Callback receiving (err)
300
 */
301
setLocalStorageKey(key: string, value: string, cb?: callback): void;
302

303
/**
304
 * Get value from local storage
305
 * @param key - Storage key to retrieve
306
 * @param cb - Callback receiving (err, value)
307
 */
308
getLocalStorageKey(key: string, cb?: callback): string;
309

310
/**
311
 * Remove a key from local storage
312
 * @param key - Storage key to remove
313
 * @param cb - Callback receiving (err)
314
 */
315
removeLocalStorageKey(key: string, cb?: callback): void;
316

317
/**
318
 * Clear all local storage
319
 * @param cb - Callback receiving (err)
320
 */
321
clearLocalStorage(cb?: callback): void;
322
```
323

324
**Usage Examples:**
325

326
```javascript
327
// Set local storage data
328
browser.setLocalStorageKey('user_preferences', JSON.stringify({
329
  theme: 'dark',
330
  language: 'en'
331
}));
332

333
// Get local storage data
334
browser.getLocalStorageKey('user_preferences', function(err, value) {
335
  const prefs = JSON.parse(value);
336
  console.log('User theme:', prefs.theme);
337
});
338

339
// Clear storage
340
browser.clearLocalStorage();
341
```