0
# Page Navigation and Interaction
1

2
Complete page automation including navigation, element interaction, JavaScript execution, and content extraction.
3

4
## Capabilities
5

6
### Page Interface
7

8
Main interface for interacting with browser pages, providing navigation, content manipulation, and event handling.
9

10
```typescript { .api }
11
interface Page extends EventEmitter {
12
  /** Navigate to URL */
13
  goto(url: string, options?: GoToOptions): Promise<HTTPResponse | null>;
14
  /** Reload current page */
15
  reload(options?: ReloadOptions): Promise<HTTPResponse | null>;
16
  /** Go back in history */
17
  goBack(options?: GoToOptions): Promise<HTTPResponse | null>;
18
  /** Go forward in history */
19
  goForward(options?: GoToOptions): Promise<HTTPResponse | null>;
20
  /** Set viewport size */
21
  setViewport(viewport: Viewport): Promise<void>;
22
  /** Get current viewport */
23
  viewport(): Viewport | null;
24
  /** Take screenshot */
25
  screenshot(options?: ScreenshotOptions): Promise<Buffer>;
26
  /** Generate PDF */
27
  pdf(options?: PDFOptions): Promise<Buffer>;
28
  /** Get page title */
29
  title(): Promise<string>;
30
  /** Get page URL */
31
  url(): string;
32
  /** Get page content as HTML */
33
  content(): Promise<string>;
34
  /** Set page content */
35
  setContent(html: string, options?: GoToOptions): Promise<void>;
36
  /** Evaluate JavaScript in page context */
37
  evaluate<T>(pageFunction: Function, ...args: any[]): Promise<T>;
38
  /** Evaluate JavaScript with handle return */
39
  evaluateHandle<T>(pageFunction: Function, ...args: any[]): Promise<JSHandle<T>>;
40
  /** Add script tag to page */
41
  addScriptTag(options: ScriptTagOptions): Promise<ElementHandle>;
42
  /** Add style tag to page */
43
  addStyleTag(options: StyleTagOptions): Promise<ElementHandle>;
44
  /** Expose function to page context */
45
  exposeFunction(name: string, puppeteerFunction: Function): Promise<void>;
46
  /** Remove exposed function */
47
  removeExposedFunction(name: string): Promise<void>;
48
  /** Set geolocation */
49
  setGeolocation(options: GeolocationOptions): Promise<void>;
50
  /** Set timezone */
51
  emulateTimezone(timezoneId: string): Promise<void>;
52
  /** Emulate media type */
53
  emulateMediaType(type?: "screen" | "print" | null): Promise<void>;
54
  /** Emulate media features */
55
  emulateMediaFeatures(features?: MediaFeature[]): Promise<void>;
56
  /** Emulate vision deficiency */
57
  emulateVisionDeficiency(type?: VisionDeficiency): Promise<void>;
58
  /** Set JavaScript enabled state */
59
  setJavaScriptEnabled(enabled: boolean): Promise<void>;
60
  /** Set offline mode */
61
  setOfflineMode(enabled: boolean): Promise<void>;
62
  /** Set request interception */
63
  setRequestInterception(value: boolean): Promise<void>;
64
  /** Set user agent */
65
  setUserAgent(userAgent: string, userAgentMetadata?: UserAgentMetadata): Promise<void>;
66
  /** Set extra HTTP headers */
67
  setExtraHTTPHeaders(headers: Record<string, string>): Promise<void>;
68
  /** Authenticate with HTTP credentials */
69
  authenticate(credentials: Credentials | null): Promise<void>;
70
  /** Get/set cookies */
71
  cookies(...urls: string[]): Promise<Cookie[]>;
72
  setCookie(...cookies: CookieParam[]): Promise<void>;
73
  deleteCookie(...cookies: DeleteCookiesRequest[]): Promise<void>;
74
  /** Click element */
75
  click(selector: string, options?: ClickOptions): Promise<void>;
76
  /** Focus element */
77
  focus(selector: string): Promise<void>;
78
  /** Hover element */
79
  hover(selector: string): Promise<void>;
80
  /** Select options */
81
  select(selector: string, ...values: string[]): Promise<string[]>;
82
  /** Tap element (mobile) */
83
  tap(selector: string): Promise<void>;
84
  /** Type text */
85
  type(selector: string, text: string, options?: TypeOptions): Promise<void>;
86
  /** Wait for selector */
87
  waitForSelector(selector: string, options?: WaitForSelectorOptions): Promise<ElementHandle | null>;
88
  /** Wait for XPath */
89
  waitForXPath(xpath: string, options?: WaitForSelectorOptions): Promise<ElementHandle | null>;
90
  /** Wait for function result */
91
  waitForFunction(pageFunction: Function, options?: WaitForFunctionOptions, ...args: any[]): Promise<JSHandle>;
92
  /** Wait for request */
93
  waitForRequest(urlOrPredicate: string | Function, options?: WaitForOptions): Promise<HTTPRequest>;
94
  /** Wait for response */
95
  waitForResponse(urlOrPredicate: string | Function, options?: WaitForOptions): Promise<HTTPResponse>;
96
  /** Wait for navigation */
97
  waitForNavigation(options?: WaitForOptions): Promise<HTTPResponse | null>;
98
  /** Wait for timeout */
99
  waitForTimeout(milliseconds: number): Promise<void>;
100
  /** Query selector */
101
  $(selector: string): Promise<ElementHandle | null>;
102
  /** Query selector all */
103
  $$(selector: string): Promise<ElementHandle[]>;
104
  /** Evaluate with selector */
105
  $eval<T>(selector: string, pageFunction: Function, ...args: any[]): Promise<T>;
106
  /** Evaluate with selector all */
107
  $$eval<T>(selector: string, pageFunction: Function, ...args: any[]): Promise<T>;
108
  /** XPath query */
109
  $x(expression: string): Promise<ElementHandle[]>;
110
  /** Get browser instance */
111
  browser(): Browser;
112
  /** Get browser context */
113
  browserContext(): BrowserContext;
114
  /** Get main frame */
115
  mainFrame(): Frame;
116
  /** Get all frames */
117
  frames(): Frame[];
118
  /** Get all workers */
119
  workers(): WebWorker[];
120
  /** Create CDP session */
121
  createCDPSession(): Promise<CDPSession>;
122
  /** Get target */
123
  target(): Target;
124
  /** Get keyboard interface */
125
  keyboard: Keyboard;
126
  /** Get mouse interface */
127
  mouse: Mouse;
128
  /** Get touchscreen interface */
129
  touchscreen: Touchscreen;
130
  /** Get coverage interface */
131
  coverage: Coverage;
132
  /** Get tracing interface */
133
  tracing: Tracing;
134
  /** Get accessibility interface */
135
  accessibility: Accessibility;
136
  /** Check if closed */
137
  isClosed(): boolean;
138
  /** Close page */
139
  close(options?: PageCloseOptions): Promise<void>;
140
  /** Check if JavaScript enabled */
141
  isJavaScriptEnabled(): boolean;
142
  /** Check if drag interception enabled */
143
  isDragInterceptionEnabled(): boolean;
144
  /** Set drag interception */
145
  setDragInterception(enabled: boolean): Promise<void>;
146
}
147

148
interface GoToOptions {
149
  timeout?: number;
150
  waitUntil?: PuppeteerLifeCycleEvent | PuppeteerLifeCycleEvent[];
151
  referer?: string;
152
}
153

154
interface ReloadOptions {
155
  timeout?: number;
156
  waitUntil?: PuppeteerLifeCycleEvent | PuppeteerLifeCycleEvent[];
157
}
158

159
type PuppeteerLifeCycleEvent = "load" | "domcontentloaded" | "networkidle0" | "networkidle2";
160

161
interface ScreenshotOptions {
162
  type?: "png" | "jpeg" | "webp";
163
  path?: string;
164
  fullPage?: boolean;
165
  clip?: BoundingBox;
166
  quality?: number;
167
  omitBackground?: boolean;
168
  encoding?: "base64" | "binary";
169
  captureBeyondViewport?: boolean;
170
  fromSurface?: boolean;
171
}
172

173
interface PDFOptions {
174
  scale?: number;
175
  displayHeaderFooter?: boolean;
176
  headerTemplate?: string;
177
  footerTemplate?: string;
178
  printBackground?: boolean;
179
  landscape?: boolean;
180
  pageRanges?: string;
181
  format?: PaperFormat;
182
  width?: string | number;
183
  height?: string | number;
184
  preferCSSPageSize?: boolean;
185
  margin?: {
186
    top?: string | number;
187
    right?: string | number;
188
    bottom?: string | number;
189
    left?: string | number;
190
  };
191
  path?: string;
192
  timeout?: number;
193
  tagged?: boolean;
194
  waitForFonts?: boolean;
195
}
196

197
type PaperFormat = "Letter" | "Legal" | "Tabloid" | "Ledger" | "A0" | "A1" | "A2" | "A3" | "A4" | "A5" | "A6";
198

199
interface ScriptTagOptions {
200
  url?: string;
201
  path?: string;
202
  content?: string;
203
  type?: string;
204
  id?: string;
205
}
206

207
interface StyleTagOptions {
208
  url?: string;
209
  path?: string;
210
  content?: string;
211
}
212

213
interface GeolocationOptions {
214
  latitude: number;
215
  longitude: number;
216
  accuracy?: number;
217
}
218

219
interface MediaFeature {
220
  name: string;
221
  value: string;
222
}
223

224
type VisionDeficiency = "achromatopsia" | "blurredVision" | "deuteranopia" | "protanopia" | "tritanopia" | null;
225

226
interface UserAgentMetadata {
227
  brands?: Array<{ brand: string; version: string }>;
228
  fullVersionList?: Array<{ brand: string; version: string }>;
229
  fullVersion?: string;
230
  platform?: string;
231
  platformVersion?: string;
232
  architecture?: string;
233
  model?: string;
234
  mobile?: boolean;
235
  bitness?: string;
236
  wow64?: boolean;
237
}
238

239
interface Credentials {
240
  username: string;
241
  password: string;
242
}
243

244
interface CookieParam {
245
  name: string;
246
  value: string;
247
  url?: string;
248
  domain?: string;
249
  path?: string;
250
  secure?: boolean;
251
  httpOnly?: boolean;
252
  sameSite?: "Strict" | "Lax" | "None";
253
  expires?: number;
254
  priority?: "Low" | "Medium" | "High";
255
  sameParty?: boolean;
256
  sourceScheme?: "Unset" | "NonSecure" | "Secure";
257
  partitionKey?: string;
258
}
259

260
interface DeleteCookiesRequest {
261
  name: string;
262
  url?: string;
263
  domain?: string;
264
  path?: string;
265
  partitionKey?: string;
266
}
267

268
interface ClickOptions {
269
  button?: "left" | "right" | "middle";
270
  clickCount?: number;
271
  delay?: number;
272
  offset?: { x: number; y: number };
273
}
274

275
interface TypeOptions {
276
  delay?: number;
277
}
278

279
interface WaitForSelectorOptions {
280
  visible?: boolean;
281
  hidden?: boolean;
282
  timeout?: number;
283
}
284

285
interface WaitForFunctionOptions {
286
  timeout?: number;
287
  polling?: "raf" | "mutation" | number;
288
}
289

290
interface WaitForOptions {
291
  timeout?: number;
292
  waitUntil?: PuppeteerLifeCycleEvent | PuppeteerLifeCycleEvent[];
293
}
294

295
interface PageCloseOptions {
296
  runBeforeUnload?: boolean;
297
}
298
```
299

300
**Usage Examples:**
301

302
```typescript
303
import puppeteer from "puppeteer-core";
304

305
const browser = await puppeteer.launch({ executablePath: "/path/to/chrome" });
306
const page = await browser.newPage();
307

308
// Navigation
309
await page.goto("https://example.com", { 
310
  waitUntil: "networkidle0",
311
  timeout: 30000 
312
});
313

314
await page.setViewport({ width: 1024, height: 768 });
315

316
// Content extraction
317
const title = await page.title();
318
const content = await page.content();
319
const url = page.url();
320

321
// Screenshots and PDFs
322
await page.screenshot({ 
323
  path: "screenshot.png", 
324
  fullPage: true 
325
});
326

327
await page.pdf({ 
328
  path: "page.pdf", 
329
  format: "A4",
330
  printBackground: true 
331
});
332

333
// JavaScript evaluation
334
const result = await page.evaluate(() => {
335
  return document.querySelector("h1")?.textContent;
336
});
337

338
const handle = await page.evaluateHandle(() => document.body);
339

340
// Form interaction
341
await page.type("#username", "user@example.com");
342
await page.type("#password", "password123");
343
await page.click("#login-button");
344

345
// Wait for navigation
346
await page.waitForNavigation({ waitUntil: "networkidle0" });
347

348
// Cookies
349
await page.setCookie({
350
  name: "session",
351
  value: "abc123",
352
  domain: "example.com"
353
});
354

355
const cookies = await page.cookies();
356

357
await browser.close();
358
```
359

360
### Page Events
361

362
The Page class emits various events during its lifecycle:
363

364
```typescript { .api }
365
interface PageEvents {
366
  /** Emitted when page closes */
367
  "close": () => void;
368
  /** Emitted when page crashes */
369
  "error": (error: Error) => void;
370
  /** Emitted when page loads */
371
  "load": () => void;
372
  /** Emitted when DOM content loads */
373
  "domcontentloaded": () => void;
374
  /** Emitted when JavaScript console API called */
375
  "console": (message: ConsoleMessage) => void;
376
  /** Emitted when JavaScript dialog appears */
377
  "dialog": (dialog: Dialog) => void;
378
  /** Emitted when request starts */
379
  "request": (request: HTTPRequest) => void;
380
  /** Emitted when response received */
381
  "response": (response: HTTPResponse) => void;
382
  /** Emitted when request fails */
383
  "requestfailed": (request: HTTPRequest) => void;
384
  /** Emitted when request finishes */
385
  "requestfinished": (request: HTTPRequest) => void;
386
  /** Emitted when frame attaches */
387
  "frameattached": (frame: Frame) => void;
388
  /** Emitted when frame detaches */
389
  "framedetached": (frame: Frame) => void;
390
  /** Emitted when frame navigates */
391
  "framenavigated": (frame: Frame) => void;
392
  /** Emitted when worker created */
393
  "workercreated": (worker: WebWorker) => void;
394
  /** Emitted when worker destroyed */
395
  "workerdestroyed": (worker: WebWorker) => void;
396
  /** Emitted when page metrics updated */
397
  "metrics": (data: { title: string; metrics: Metrics }) => void;
398
  /** Emitted when file chooser appears */
399
  "filechooser": (fileChooser: FileChooser) => void;
400
  /** Emitted on popup */
401
  "popup": (page: Page) => void;
402
}
403

404
interface Metrics {
405
  Timestamp?: number;
406
  AudioHandlers?: number;
407
  Documents?: number;
408
  Frames?: number;
409
  JSEventListeners?: number;
410
  Nodes?: number;
411
  LayoutCount?: number;
412
  RecalcStyleCount?: number;
413
  LayoutDuration?: number;
414
  RecalcStyleDuration?: number;
415
  ScriptDuration?: number;
416
  TaskDuration?: number;
417
  JSHeapUsedSize?: number;
418
  JSHeapTotalSize?: number;
419
}
420
```
421

422
### Console Messages
423

424
Handle browser console output:
425

426
```typescript { .api }
427
interface ConsoleMessage {
428
  type(): "log" | "debug" | "info" | "error" | "warning" | "dir" | "dirxml" | "table" | "trace" | "clear" | "startGroup" | "startGroupCollapsed" | "endGroup" | "assert" | "profile" | "profileEnd" | "count" | "timeEnd";
429
  text(): string;
430
  args(): JSHandle[];
431
  location(): ConsoleMessageLocation;
432
  stackTrace(): ConsoleMessageLocation[];
433
}
434

435
interface ConsoleMessageLocation {
436
  url?: string;
437
  lineNumber?: number;
438
  columnNumber?: number;
439
}
440
```
441

442
### Dialog Handling
443

444
Handle JavaScript dialogs (alert, confirm, prompt):
445

446
```typescript { .api }
447
interface Dialog {
448
  type(): "alert" | "beforeunload" | "confirm" | "prompt";
449
  message(): string;
450
  defaultValue(): string;
451
  accept(promptText?: string): Promise<void>;
452
  dismiss(): Promise<void>;
453
}
454
```
455

456
**Usage Examples:**
457

458
```typescript
459
// Handle dialogs
460
page.on("dialog", async (dialog) => {
461
  console.log("Dialog type:", dialog.type());
462
  console.log("Dialog message:", dialog.message());
463
  
464
  if (dialog.type() === "confirm") {
465
    await dialog.accept();
466
  } else {
467
    await dialog.dismiss();
468
  }
469
});
470

471
// Handle console messages
472
page.on("console", (msg) => {
473
  console.log(`PAGE LOG: ${msg.text()}`);
474
});
475

476
// Handle page events
477
page.on("load", () => console.log("Page loaded"));
478
page.on("requestfailed", (req) => {
479
  console.log("Request failed:", req.url());
480
});
481
```
482

483
### File Handling
484

485
Handle file uploads and downloads:
486

487
```typescript { .api }
488
interface FileChooser {
489
  isMultiple(): boolean;
490
  accept(filePaths: string[]): Promise<void>;
491
  cancel(): Promise<void>;
492
}
493
```
494

495
**Usage Examples:**
496

497
```typescript
498
// Handle file chooser
499
const [fileChooser] = await Promise.all([
500
  page.waitForEvent("filechooser"),
501
  page.click("#upload-button")
502
]);
503

504
await fileChooser.accept(["/path/to/file.txt"]);
505

506
// Set download behavior
507
const client = await page.createCDPSession();
508
await client.send("Page.setDownloadBehavior", {
509
  behavior: "allow",
510
  downloadPath: "/path/to/downloads"
511
});
512
```
513

514
### Advanced Page Features
515

516
Additional page capabilities for complex scenarios:
517

518
```typescript { .api }
519
interface Coverage {
520
  startJSCoverage(options?: JSCoverageOptions): Promise<void>;
521
  stopJSCoverage(): Promise<JSCoverageEntry[]>;
522
  startCSSCoverage(options?: CSSCoverageOptions): Promise<void>;
523
  stopCSSCoverage(): Promise<CSSCoverageEntry[]>;
524
}
525

526
interface Tracing {
527
  start(options?: TracingOptions): Promise<void>;
528
  stop(): Promise<Buffer>;
529
}
530

531
interface Accessibility {
532
  snapshot(options?: SnapshotOptions): Promise<SerializedAXNode | null>;
533
}
534

535
interface JSCoverageOptions {
536
  resetOnNavigation?: boolean;
537
  reportAnonymousScripts?: boolean;
538
  includeRawScriptCoverage?: boolean;
539
  useBlockCoverage?: boolean;
540
}
541

542
interface CSSCoverageOptions {
543
  resetOnNavigation?: boolean;
544
}
545

546
interface TracingOptions {
547
  path?: string;
548
  screenshots?: boolean;
549
  categories?: string[];
550
}
551

552
interface SnapshotOptions {
553
  interestingOnly?: boolean;
554
  root?: ElementHandle;
555
}
556
```
557

558
**Usage Examples:**
559

560
```typescript
561
// Code coverage
562
await page.coverage.startJSCoverage();
563
await page.goto("https://example.com");
564
const jsCoverage = await page.coverage.stopJSCoverage();
565

566
// Performance tracing
567
await page.tracing.start({ path: "trace.json" });
568
await page.goto("https://example.com");
569
await page.tracing.stop();
570

571
// Accessibility tree
572
const snapshot = await page.accessibility.snapshot();
573
console.log(JSON.stringify(snapshot, null, 2));
574
```