0
# Page Interaction
1

2
Page navigation, element interaction, and content manipulation with automatic waiting, cross-frame support, and reliable element selection.
3

4
## Capabilities
5

6
### Page Navigation
7

8
Navigate pages, handle navigation events, and manage page lifecycle.
9

10
```typescript { .api }
11
interface Page {
12
  /** Navigate to URL */
13
  goto(url: string, options?: PageGotoOptions): Promise<Response | null>;
14
  /** Reload the page */  
15
  reload(options?: PageReloadOptions): Promise<Response | null>;
16
  /** Go back in navigation history */
17
  goBack(options?: PageGoBackOptions): Promise<Response | null>;
18
  /** Go forward in navigation history */
19
  goForward(options?: PageGoForwardOptions): Promise<Response | null>;
20
  /** Get current URL */
21
  url(): string;
22
  /** Get page title */
23
  title(): Promise<string>;
24
  /** Close the page */
25
  close(options?: PageCloseOptions): Promise<void>;
26
  /** Check if page is closed */
27
  isClosed(): boolean;
28
}
29

30
interface PageGotoOptions {
31
  /** Navigation timeout in milliseconds */
32
  timeout?: number;
33
  /** Wait until condition */
34
  waitUntil?: 'load' | 'domcontentloaded' | 'networkidle' | 'commit';
35
  /** Referer header value */
36
  referer?: string;
37
}
38
```
39

40
**Usage Examples:**
41

42
```typescript
43
// Basic navigation
44
await page.goto('https://example.com');
45
await page.goto('https://example.com', { 
46
  waitUntil: 'networkidle' 
47
});
48

49
// Navigation with timeout
50
await page.goto('https://slow-site.com', { 
51
  timeout: 60000 
52
});
53

54
// Get page info
55
const title = await page.title();
56
const url = page.url();
57

58
// Navigation history
59
await page.goBack();
60
await page.goForward();
61
await page.reload();
62
```
63

64
### Element Interaction
65

66
Interact with page elements using selectors, automatic waiting, and reliable actions.
67

68
```typescript { .api }
69
interface Page {
70
  /** Click element */
71
  click(selector: string, options?: PageClickOptions): Promise<void>;
72
  /** Double-click element */
73
  dblclick(selector: string, options?: PageDblclickOptions): Promise<void>;
74
  /** Fill input element */
75
  fill(selector: string, value: string, options?: PageFillOptions): Promise<void>;
76
  /** Type text into element */
77
  type(selector: string, text: string, options?: PageTypeOptions): Promise<void>;
78
  /** Press key */
79
  press(selector: string, key: string, options?: PagePressOptions): Promise<void>;
80
  /** Check checkbox or radio */
81
  check(selector: string, options?: PageCheckOptions): Promise<void>;
82
  /** Uncheck checkbox */
83
  uncheck(selector: string, options?: PageUncheckOptions): Promise<void>;
84
  /** Select option(s) */
85
  selectOption(selector: string, values: string | string[] | SelectOption | SelectOption[], options?: PageSelectOptionOptions): Promise<string[]>;
86
  /** Set input files */
87
  setInputFiles(selector: string, files: string | string[] | FilePayload | FilePayload[], options?: PageSetInputFilesOptions): Promise<void>;
88
  /** Hover over element */
89
  hover(selector: string, options?: PageHoverOptions): Promise<void>;
90
  /** Focus element */
91
  focus(selector: string, options?: PageFocusOptions): Promise<void>;
92
  /** Blur element */
93
  blur(selector: string, options?: PageBlurOptions): Promise<void>;
94
}
95

96
interface PageClickOptions {
97
  /** Button to click */
98
  button?: 'left' | 'right' | 'middle';
99
  /** Number of clicks */
100
  clickCount?: number;
101
  /** Modifier keys */  
102
  modifiers?: ('Alt' | 'Control' | 'Meta' | 'Shift')[];
103
  /** Click position */
104
  position?: { x: number; y: number };
105
  /** Timeout in milliseconds */
106
  timeout?: number;
107
  /** Force click even if element is not actionable */
108
  force?: boolean;
109
  /** Skip actionability checks */
110
  noWaitAfter?: boolean;
111
  /** Trial run mode */
112
  trial?: boolean;
113
}
114
```
115

116
**Usage Examples:**
117

118
```typescript
119
// Basic interactions
120
await page.click('#submit-button');
121
await page.fill('#email', 'user@example.com');
122
await page.type('#password', 'secret123');
123
await page.press('#search', 'Enter');
124

125
// Advanced interactions  
126
await page.click('.menu-item', { 
127
  button: 'right',
128
  modifiers: ['Control'] 
129
});
130

131
await page.hover('.tooltip-trigger');
132
await page.focus('#first-input');
133

134
// Form interactions
135
await page.check('#agree-terms');
136
await page.selectOption('#country', 'USA');
137
await page.setInputFiles('#file-upload', './document.pdf');
138
```
139

140
### Locators
141

142
Modern element selectors with auto-waiting and retry logic.
143

144
```typescript { .api }
145
interface Page {
146
  /** Create locator for selector */
147
  locator(selector: string, options?: PageLocatorOptions): Locator;
148
  /** Get element handle (deprecated - use locator) */
149
  $(selector: string): Promise<ElementHandle | null>;
150
  /** Get multiple element handles (deprecated - use locator) */
151
  $$(selector: string): Promise<ElementHandle[]>;
152
}
153

154
interface Locator {
155
  /** Click the element */  
156
  click(options?: LocatorClickOptions): Promise<void>;
157
  /** Double-click the element */
158
  dblclick(options?: LocatorDblclickOptions): Promise<void>;
159
  /** Fill input element */
160
  fill(value: string, options?: LocatorFillOptions): Promise<void>;
161
  /** Type text */
162
  type(text: string, options?: LocatorTypeOptions): Promise<void>;
163
  /** Press key */
164
  press(key: string, options?: LocatorPressOptions): Promise<void>;
165
  /** Check checkbox/radio */
166
  check(options?: LocatorCheckOptions): Promise<void>;
167
  /** Uncheck checkbox */
168
  uncheck(options?: LocatorUncheckOptions): Promise<void>;
169
  /** Select options */
170
  selectOption(values: string | string[] | SelectOption | SelectOption[], options?: LocatorSelectOptionOptions): Promise<string[]>;
171
  /** Set input files */
172
  setInputFiles(files: string | string[] | FilePayload | FilePayload[], options?: LocatorSetInputFilesOptions): Promise<void>;
173
  /** Hover over element */
174
  hover(options?: LocatorHoverOptions): Promise<void>;
175
  /** Focus element */
176
  focus(options?: LocatorFocusOptions): Promise<void>;
177
  /** Blur element */
178
  blur(options?: LocatorBlurOptions): Promise<void>;
179

180
  /** Get text content */
181
  textContent(options?: LocatorTextContentOptions): Promise<string | null>;
182
  /** Get inner text */
183
  innerText(options?: LocatorInnerTextOptions): Promise<string>;
184
  /** Get inner HTML */
185
  innerHTML(options?: LocatorInnerHTMLOptions): Promise<string>;
186
  /** Get attribute */
187
  getAttribute(name: string, options?: LocatorGetAttributeOptions): Promise<string | null>;
188
  /** Get input value */
189
  inputValue(options?: LocatorInputValueOptions): Promise<string>;
190
  
191
  /** Check if element is visible */
192
  isVisible(options?: LocatorIsVisibleOptions): Promise<boolean>;
193
  /** Check if element is hidden */
194
  isHidden(options?: LocatorIsHiddenOptions): Promise<boolean>;  
195
  /** Check if element is enabled */
196
  isEnabled(options?: LocatorIsEnabledOptions): Promise<boolean>;
197
  /** Check if element is disabled */
198
  isDisabled(options?: LocatorIsDisabledOptions): Promise<boolean>;
199
  /** Check if element is editable */
200
  isEditable(options?: LocatorIsEditableOptions): Promise<boolean>;
201
  /** Check if checkbox is checked */
202
  isChecked(options?: LocatorIsCheckedOptions): Promise<boolean>;
203

204
  /** Get element count */
205
  count(): Promise<number>;
206
  /** Get nth element */
207
  nth(index: number): Locator;
208
  /** Get first element */
209
  first(): Locator;
210
  /** Get last element */
211
  last(): Locator;
212
  /** Filter by text */
213
  filter(options?: LocatorFilterOptions): Locator;
214
}
215

216
interface PageLocatorOptions {
217
  /** Has text content */
218
  hasText?: string | RegExp;
219
  /** Has attribute */
220
  has?: Locator;
221
}
222

223
interface LocatorFilterOptions {
224
  /** Filter by text content */
225
  hasText?: string | RegExp;
226
  /** Filter by contained locator */
227
  has?: Locator;
228
}
229
```
230

231
**Usage Examples:**
232

233
```typescript
234
// Basic locators
235
const submitButton = page.locator('#submit');
236
const menuItems = page.locator('.menu-item');
237

238
// Locator actions  
239
await submitButton.click();
240
await page.locator('#email').fill('user@example.com');
241
await page.locator('#search').press('Enter');
242

243
// Locator queries
244
const text = await page.locator('h1').textContent();
245
const count = await page.locator('.item').count();
246
const isVisible = await page.locator('#banner').isVisible();
247

248
// Locator filtering
249
const activeItems = page.locator('.item').filter({ hasText: 'active' });
250
const firstItem = page.locator('.item').first();
251
const lastItem = page.locator('.item').last();
252
const thirdItem = page.locator('.item').nth(2);
253

254
// Complex locators
255
const buttonInCard = page.locator('.card').filter({ 
256
  has: page.locator('h2', { hasText: 'Premium' }) 
257
}).locator('button');
258
```
259

260
### Frame Interaction
261

262
Work with iframes and nested browsing contexts.
263

264
```typescript { .api }
265
interface Page {
266
  /** Get main frame */
267
  mainFrame(): Frame;
268
  /** Get all frames */
269
  frames(): Frame[];
270
  /** Get frame by name or URL */
271
  frame(options: { name?: string; url?: string | RegExp }): Frame | null;
272
  /** Create frame locator */
273
  frameLocator(selector: string): FrameLocator;
274
}
275

276
interface Frame {
277
  /** Navigate frame to URL */
278
  goto(url: string, options?: FrameGotoOptions): Promise<Response | null>;
279
  /** Get frame URL */
280
  url(): string;
281
  /** Get frame name */
282
  name(): string;
283
  /** Get parent frame */
284
  parentFrame(): Frame | null;
285
  /** Get child frames */
286
  childFrames(): Frame[];
287
  /** Check if frame is detached */
288
  isDetached(): boolean;
289

290
  /** Click element in frame */
291
  click(selector: string, options?: FrameClickOptions): Promise<void>;
292
  /** Fill element in frame */
293
  fill(selector: string, value: string, options?: FrameFillOptions): Promise<void>;
294
  /** Create locator in frame */
295
  locator(selector: string, options?: FrameLocatorOptions): Locator;
296
}
297

298
interface FrameLocator {
299
  /** Create locator within frame */
300
  locator(selector: string): Locator;
301
  /** Create nested frame locator */
302
  frameLocator(selector: string): FrameLocator;
303
  /** Get first matching frame */
304
  first(): FrameLocator;
305
  /** Get last matching frame */
306
  last(): FrameLocator;
307
  /** Get nth matching frame */
308
  nth(index: number): FrameLocator;
309
}
310
```
311

312
**Usage Examples:**
313

314
```typescript
315
// Work with frames
316
const frame = page.frame({ name: 'content-frame' });
317
if (frame) {
318
  await frame.click('#frame-button');
319
  await frame.fill('#frame-input', 'value');
320
}
321

322
// Frame locators (recommended)
323
const frameButton = page.frameLocator('#content-frame').locator('#button');
324
await frameButton.click();
325

326
// Nested frames
327
const nestedButton = page
328
  .frameLocator('#outer-frame')
329
  .frameLocator('#inner-frame')  
330
  .locator('#button');
331
await nestedButton.click();
332
```
333

334
### Content Evaluation
335

336
Execute JavaScript in page context and extract data.
337

338
```typescript { .api }
339
interface Page {
340
  /** Evaluate JavaScript expression */
341
  evaluate<R, Arg>(pageFunction: PageFunction<Arg, R>, arg: Arg): Promise<R>;
342
  evaluate<R>(pageFunction: PageFunction<void, R>, arg?: any): Promise<R>;
343
  /** Evaluate and return JSHandle */
344
  evaluateHandle<R, Arg>(pageFunction: PageFunction<Arg, R>, arg: Arg): Promise<JSHandle<R>>;
345
  evaluateHandle<R>(pageFunction: PageFunction<void, R>, arg?: any): Promise<JSHandle<R>>;
346
  /** Add script tag */
347
  addScriptTag(options: PageAddScriptTagOptions): Promise<ElementHandle>;
348
  /** Add style tag */
349
  addStyleTag(options: PageAddStyleTagOptions): Promise<ElementHandle>;
350
  /** Expose function to page */
351
  exposeFunction(name: string, callback: Function): Promise<void>;
352
  /** Expose binding to page */
353
  exposeBinding(name: string, callback: PageBinding, options?: PageExposeBindingOptions): Promise<void>;
354
}
355

356
type PageFunction<Arg, R> = string | ((arg: Arg) => R | Promise<R>);
357
type PageBinding = (source: BindingSource, ...args: any[]) => any;
358

359
interface PageAddScriptTagOptions {
360
  /** Script URL */
361
  url?: string;
362
  /** Script path */
363
  path?: string;
364
  /** Script content */
365
  content?: string;
366
  /** Script type */
367
  type?: string;
368
}
369

370
interface PageAddStyleTagOptions {
371
  /** Stylesheet URL */
372
  url?: string;
373
  /** Stylesheet path */
374
  path?: string;
375
  /** Stylesheet content */  
376
  content?: string;
377
}
378
```
379

380
**Usage Examples:**
381

382
```typescript
383
// Evaluate JavaScript
384
const title = await page.evaluate(() => document.title);
385
const windowSize = await page.evaluate(() => ({
386
  width: window.innerWidth,
387
  height: window.innerHeight
388
}));
389

390
// Pass arguments to evaluation
391
const result = await page.evaluate((text) => {
392
  return document.querySelector('h1').textContent === text;
393
}, 'Welcome');
394

395
// Add external scripts
396
await page.addScriptTag({ url: 'https://code.jquery.com/jquery.min.js' });
397
await page.addScriptTag({ path: './my-script.js' });
398

399
// Expose function to page
400
await page.exposeFunction('generateId', () => Math.random().toString(36));
401
// Now page can call: const id = await generateId();
402
```
403

404
## Types
405

406
### Element Selection Types
407

408
```typescript { .api }
409
interface SelectOption {
410
  value?: string;
411
  label?: string;
412
  index?: number;
413
}
414

415
interface FilePayload {
416
  name: string;
417
  mimeType: string;
418
  buffer: Buffer;
419
}
420

421
interface BindingSource {
422
  context: BrowserContext;
423
  page: Page;
424
  frame: Frame;
425
}
426
```
427

428
### Wait Options
429

430
```typescript { .api }
431
interface PageWaitForSelectorOptions {
432
  /** Wait for element state */
433
  state?: 'attached' | 'detached' | 'visible' | 'hidden';
434
  /** Wait timeout */
435
  timeout?: number;
436
  /** Wait for strict mode (single element) */
437
  strict?: boolean;
438
}
439

440
interface PageWaitForFunctionOptions {
441
  /** Function to wait for */
442
  timeout?: number;
443
  /** Polling interval */
444
  polling?: number | 'raf';
445
}
446

447
interface PageWaitForEventOptions {
448
  /** Event timeout */
449
  timeout?: number;
450
  /** Predicate function */
451
  predicate?: Function;
452
}
453

454
interface PageWaitForURLOptions {
455
  /** Navigation timeout */
456
  timeout?: number;
457
  /** Wait until condition */
458
  waitUntil?: 'load' | 'domcontentloaded' | 'networkidle' | 'commit';
459
}
460
```