0
# Page Interaction
1

2
Comprehensive page automation including navigation, element interaction, JavaScript execution, and content manipulation. The Page interface provides high-level methods for common browser automation tasks.
3

4
## Capabilities
5

6
### Page Navigation
7

8
Navigate to URLs, handle page loading states, and manage page history.
9

10
```typescript { .api }
11
/**
12
 * Navigate to a URL
13
 * @param url - URL to navigate to
14
 * @param options - Navigation options
15
 * @returns Response object or null
16
 */
17
goto(url: string, options?: PageGotoOptions): Promise<Response | null>;
18

19
/**
20
 * Reload the current page
21
 * @param options - Reload options
22
 * @returns Response object or null
23
 */
24
reload(options?: PageReloadOptions): Promise<Response | null>;
25

26
/**
27
 * Navigate back in browser history
28
 * @param options - Navigation options
29
 * @returns Response object or null
30
 */
31
goBack(options?: PageGoBackOptions): Promise<Response | null>;
32

33
/**
34
 * Navigate forward in browser history
35
 * @param options - Navigation options
36
 * @returns Response object or null
37
 */
38
goForward(options?: PageGoForwardOptions): Promise<Response | null>;
39
```
40

41
**Usage Examples:**
42

43
```typescript
44
// Basic navigation
45
await page.goto('https://example.com');
46

47
// Navigation with options
48
await page.goto('https://example.com', {
49
  waitUntil: 'networkidle',
50
  timeout: 30000
51
});
52

53
// Handle navigation responses
54
const response = await page.goto('https://api.example.com/data');
55
if (response && response.status() === 200) {
56
  console.log('Navigation successful');
57
}
58

59
// Page history navigation
60
await page.goBack();
61
await page.goForward();
62
await page.reload();
63
```
64

65
### Element Interaction
66

67
High-level element interaction methods with built-in waiting and error handling.
68

69
```typescript { .api }
70
/**
71
 * Click an element matching the selector
72
 * @param selector - Element selector
73
 * @param options - Click options
74
 */
75
click(selector: string, options?: PageClickOptions): Promise<void>;
76

77
/**
78
 * Double-click an element matching the selector
79
 * @param selector - Element selector
80
 * @param options - Click options
81
 */
82
dblclick(selector: string, options?: PageDblclickOptions): Promise<void>;
83

84
/**
85
 * Fill an input element with text
86
 * @param selector - Input element selector
87
 * @param value - Text to fill
88
 * @param options - Fill options
89
 */
90
fill(selector: string, value: string, options?: PageFillOptions): Promise<void>;
91

92
/**
93
 * Type text into an element
94
 * @param selector - Element selector
95
 * @param text - Text to type
96
 * @param options - Type options
97
 */
98
type(selector: string, text: string, options?: PageTypeOptions): Promise<void>;
99

100
/**
101
 * Press a key on an element
102
 * @param selector - Element selector
103
 * @param key - Key to press
104
 * @param options - Press options
105
 */
106
press(selector: string, key: string, options?: PagePressOptions): Promise<void>;
107

108
/**
109
 * Check a checkbox or select a radio button
110
 * @param selector - Element selector
111
 * @param options - Check options
112
 */
113
check(selector: string, options?: PageCheckOptions): Promise<void>;
114

115
/**
116
 * Uncheck a checkbox
117
 * @param selector - Element selector
118
 * @param options - Uncheck options
119
 */
120
uncheck(selector: string, options?: PageUncheckOptions): Promise<void>;
121

122
/**
123
 * Select options from a dropdown
124
 * @param selector - Select element selector
125
 * @param values - Values to select
126
 * @param options - Select options
127
 */
128
selectOption(selector: string, values: string | ElementHandle | SelectOption | string[] | ElementHandle[] | SelectOption[], options?: PageSelectOptionOptions): Promise<string[]>;
129
```
130

131
**Usage Examples:**
132

133
```typescript
134
// Form interaction
135
await page.fill('input[name="email"]', 'user@example.com');
136
await page.fill('input[name="password"]', 'secretpassword');
137
await page.check('input[name="rememberMe"]');
138
await page.click('button[type="submit"]');
139

140
// Dropdown selection
141
await page.selectOption('select[name="country"]', 'us');
142
await page.selectOption('select[name="options"]', ['option1', 'option2']);
143

144
// Keyboard interaction
145
await page.press('input[name="search"]', 'Enter');
146
await page.type('textarea', 'This is some text', { delay: 100 });
147

148
// Advanced clicking
149
await page.click('button', {
150
  position: { x: 10, y: 10 },
151
  modifiers: ['Shift'],
152
  clickCount: 2
153
});
154
```
155

156
### Content Access
157

158
Access and manipulate page content including HTML, text, and metadata.
159

160
```typescript { .api }
161
/**
162
 * Get the full HTML content of the page
163
 * @returns HTML content as string
164
 */
165
content(): Promise<string>;
166

167
/**
168
 * Set the HTML content of the page
169
 * @param html - HTML content to set
170
 * @param options - Content options
171
 */
172
setContent(html: string, options?: PageSetContentOptions): Promise<void>;
173

174
/**
175
 * Get the page title
176
 * @returns Page title
177
 */
178
title(): Promise<string>;
179

180
/**
181
 * Get the current page URL
182
 * @returns Current URL
183
 */
184
url(): string;
185

186
/**
187
 * Get inner text of an element
188
 * @param selector - Element selector
189
 * @param options - Text options
190
 * @returns Inner text or null
191
 */
192
innerText(selector: string, options?: PageInnerTextOptions): Promise<string>;
193

194
/**
195
 * Get text content of an element
196
 * @param selector - Element selector
197
 * @param options - Text options
198
 * @returns Text content or null
199
 */
200
textContent(selector: string, options?: PageTextContentOptions): Promise<string | null>;
201

202
/**
203
 * Get innerHTML of an element
204
 * @param selector - Element selector
205
 * @param options - HTML options
206
 * @returns Inner HTML
207
 */
208
innerHTML(selector: string, options?: PageInnerHTMLOptions): Promise<string>;
209

210
/**
211
 * Get attribute value of an element
212
 * @param selector - Element selector
213
 * @param name - Attribute name
214
 * @param options - Attribute options
215
 * @returns Attribute value or null
216
 */
217
getAttribute(selector: string, name: string, options?: PageGetAttributeOptions): Promise<string | null>;
218
```
219

220
**Usage Examples:**
221

222
```typescript
223
// Get page information
224
const title = await page.title();
225
const url = page.url();
226
const content = await page.content();
227

228
// Extract element content
229
const headerText = await page.textContent('h1');
230
const emailValue = await page.getAttribute('input[name="email"]', 'value');
231
const divHtml = await page.innerHTML('div.content');
232

233
// Set page content
234
await page.setContent('<html><body><h1>Test Page</h1></body></html>');
235
```
236

237
### JavaScript Execution
238

239
Execute JavaScript code in the page context and return results.
240

241
```typescript { .api }
242
/**
243
 * Execute JavaScript in the page context
244
 * @param pageFunction - Function to execute
245
 * @param arg - Optional argument to pass
246
 * @returns Serializable result
247
 */
248
evaluate<R, Arg>(pageFunction: PageFunction<Arg, R>, arg?: Arg): Promise<R>;
249

250
/**
251
 * Execute JavaScript and return a JSHandle
252
 * @param pageFunction - Function to execute
253
 * @param arg - Optional argument to pass
254
 * @returns JSHandle to the result
255
 */
256
evaluateHandle<R, Arg>(pageFunction: PageFunction<Arg, R>, arg?: Arg): Promise<JSHandle<R>>;
257

258
/**
259
 * Add a script tag to the page
260
 * @param options - Script options
261
 * @returns ElementHandle to the script tag
262
 */
263
addScriptTag(options: PageAddScriptTagOptions): Promise<ElementHandle>;
264

265
/**
266
 * Add a style tag to the page
267
 * @param options - Style options
268
 * @returns ElementHandle to the style tag
269
 */
270
addStyleTag(options: PageAddStyleTagOptions): Promise<ElementHandle>;
271
```
272

273
**Usage Examples:**
274

275
```typescript
276
// Execute JavaScript and get result
277
const result = await page.evaluate(() => {
278
  return document.querySelectorAll('a').length;
279
});
280

281
// Pass arguments to page function
282
const text = await page.evaluate((selector) => {
283
  return document.querySelector(selector)?.textContent;
284
}, 'h1');
285

286
// Get JSHandle for complex objects
287
const windowHandle = await page.evaluateHandle(() => window);
288
const location = await windowHandle.getProperty('location');
289

290
// Add external script
291
await page.addScriptTag({ url: 'https://code.jquery.com/jquery-3.6.0.min.js' });
292

293
// Add inline script
294
await page.addScriptTag({
295
  content: 'window.myVariable = "test";'
296
});
297

298
// Add CSS styles
299
await page.addStyleTag({
300
  content: 'body { background-color: red; }'
301
});
302
```
303

304
### Waiting and Synchronization
305

306
Wait for various conditions and synchronize with page state changes.
307

308
```typescript { .api }
309
/**
310
 * Wait for an element to appear
311
 * @param selector - Element selector
312
 * @param options - Wait options
313
 * @returns ElementHandle or null
314
 */
315
waitForSelector(selector: string, options?: PageWaitForSelectorOptions): Promise<ElementHandle | null>;
316

317
/**
318
 * Wait for a JavaScript function to return truthy
319
 * @param pageFunction - Function to evaluate
320
 * @param arg - Optional argument
321
 * @param options - Wait options
322
 * @returns Result of the function
323
 */
324
waitForFunction<R, Arg>(pageFunction: PageFunction<Arg, R>, arg?: Arg, options?: PageWaitForFunctionOptions): Promise<JSHandle<R>>;
325

326
/**
327
 * Wait for a page event
328
 * @param event - Event name
329
 * @param optionsOrPredicate - Options or predicate function
330
 * @returns Event data
331
 */
332
waitForEvent(event: string, optionsOrPredicate?: PageWaitForEventOptions | Function): Promise<any>;
333

334
/**
335
 * Wait for URL to match pattern
336
 * @param url - URL pattern
337
 * @param options - Wait options
338
 */
339
waitForURL(url: string | RegExp | ((url: URL) => boolean), options?: PageWaitForURLOptions): Promise<void>;
340

341
/**
342
 * Wait for page load state
343
 * @param state - Load state to wait for
344
 * @param options - Wait options
345
 */
346
waitForLoadState(state?: 'load' | 'domcontentloaded' | 'networkidle', options?: PageWaitForLoadStateOptions): Promise<void>;
347

348
/**
349
 * Wait for specified timeout
350
 * @param timeout - Timeout in milliseconds
351
 */
352
waitForTimeout(timeout: number): Promise<void>;
353
```
354

355
**Usage Examples:**
356

357
```typescript
358
// Wait for elements
359
await page.waitForSelector('.loading', { state: 'hidden' });
360
await page.waitForSelector('button.submit', { state: 'visible' });
361

362
// Wait for custom conditions
363
await page.waitForFunction(() => {
364
  return document.querySelectorAll('.item').length > 10;
365
});
366

367
// Wait for events
368
const response = await page.waitForEvent('response', response => {
369
  return response.url().includes('/api/data');
370
});
371

372
// Wait for navigation
373
await Promise.all([
374
  page.waitForNavigation(),
375
  page.click('a.next-page')
376
]);
377

378
// Wait for load states
379
await page.waitForLoadState('networkidle');
380
await page.waitForURL('**/dashboard/**');
381
```
382

383
### Screenshots and Media
384

385
Capture screenshots, generate PDFs, and handle media content.
386

387
```typescript { .api }
388
/**
389
 * Take a screenshot of the page
390
 * @param options - Screenshot options
391
 * @returns Buffer containing image data
392
 */
393
screenshot(options?: PageScreenshotOptions): Promise<Buffer>;
394

395
/**
396
 * Generate a PDF of the page
397
 * @param options - PDF options
398
 * @returns Buffer containing PDF data
399
 */
400
pdf(options?: PagePdfOptions): Promise<Buffer>;
401
```
402

403
**Usage Examples:**
404

405
```typescript
406
// Full page screenshot
407
await page.screenshot({ path: 'page.png' });
408

409
// Element screenshot
410
await page.screenshot({
411
  path: 'element.png',
412
  clip: { x: 0, y: 0, width: 300, height: 200 }
413
});
414

415
// Screenshot options
416
await page.screenshot({
417
  path: 'page.jpg',
418
  type: 'jpeg',
419
  quality: 80,
420
  fullPage: true
421
});
422

423
// Generate PDF
424
await page.pdf({
425
  path: 'page.pdf',
426
  format: 'A4',
427
  printBackground: true
428
});
429
```
430

431
## Configuration Types
432

433
### Navigation Options
434

435
```typescript { .api }
436
interface PageGotoOptions {
437
  /** When to consider navigation complete */
438
  waitUntil?: 'load' | 'domcontentloaded' | 'networkidle' | 'commit';
439
  /** Maximum navigation time in milliseconds */
440
  timeout?: number;
441
  /** Referer header value */
442
  referer?: string;
443
}
444

445
interface PageReloadOptions {
446
  /** When to consider reload complete */
447
  waitUntil?: 'load' | 'domcontentloaded' | 'networkidle' | 'commit';
448
  /** Maximum reload time in milliseconds */
449
  timeout?: number;
450
}
451
```
452

453
### Interaction Options
454

455
```typescript { .api }
456
interface PageClickOptions {
457
  /** Which button to click */
458
  button?: 'left' | 'right' | 'middle';
459
  /** Number of clicks */
460
  clickCount?: number;
461
  /** Time to wait between mousedown and mouseup */
462
  delay?: number;
463
  /** Exact position to click */
464
  position?: { x: number; y: number; };
465
  /** Modifier keys to hold */
466
  modifiers?: Array<'Alt' | 'Control' | 'Meta' | 'Shift'>;
467
  /** Whether to bypass actionability checks */
468
  force?: boolean;
469
  /** Actions that do not have a target element should be performed on this element */
470
  trial?: boolean;
471
  /** Maximum time to wait for element */
472
  timeout?: number;
473
}
474

475
interface PageFillOptions {
476
  /** Whether to bypass actionability checks */
477
  force?: boolean;
478
  /** Actions that do not have a target element should be performed on this element */
479
  trial?: boolean;
480
  /** Maximum time to wait for element */
481
  timeout?: number;
482
}
483

484
interface PageTypeOptions {
485
  /** Time to wait between key presses */
486
  delay?: number;
487
  /** Maximum time to wait for element */
488
  timeout?: number;
489
}
490
```
491

492
### Wait Options
493

494
```typescript { .api }
495
interface PageWaitForSelectorOptions {
496
  /** Element state to wait for */
497
  state?: 'attached' | 'detached' | 'visible' | 'hidden';
498
  /** Maximum time to wait */
499
  timeout?: number;
500
}
501

502
interface PageWaitForFunctionOptions {
503
  /** Maximum time to wait */
504
  timeout?: number;
505
  /** Polling interval */
506
  polling?: number | 'raf';
507
}
508

509
interface PageWaitForEventOptions {
510
  /** Maximum time to wait for event */
511
  timeout?: number;
512
  /** Predicate function to filter events */
513
  predicate?: Function;
514
}
515
```
516

517
### Screenshot Options
518

519
```typescript { .api }
520
interface PageScreenshotOptions {
521
  /** File path to save screenshot */
522
  path?: string;
523
  /** Image type */
524
  type?: 'png' | 'jpeg';
525
  /** JPEG quality (0-100) */
526
  quality?: number;
527
  /** Omits default background */
528
  omitBackground?: boolean;
529
  /** Capture full scrollable page */
530
  fullPage?: boolean;
531
  /** Clip area to screenshot */
532
  clip?: { x: number; y: number; width: number; height: number; };
533
  /** Hides default caret */
534
  caret?: 'hide' | 'initial';
535
  /** Scale factor for high-DPI displays */
536
  scale?: 'css' | 'device';
537
  /** Screenshot animations */
538
  animations?: 'disabled' | 'allow';
539
}
540
```