UNPKG

86.4 kBTypeScriptView Raw
1// Type definitions for puppeteer 5.4
2// Project: https://github.com/GoogleChrome/puppeteer#readme
3// Definitions by: Marvin Hagemeister <https://github.com/marvinhagemeister>
4// Christopher Deutsch <https://github.com/cdeutsch>
5// Konstantin Simon Maria Möllers <https://github.com/ksm2>
6// Simon Schick <https://github.com/SimonSchick>
7// Serban Ghita <https://github.com/SerbanGhita>
8// Jason Kaczmarsky <https://github.com/JasonKaz>
9// Dave Cardwell <https://github.com/davecardwell>
10// Andrés Ortiz <https://github.com/angrykoala>
11// Piotr Błażejewicz <https://github.com/peterblazejewicz>
12// Cameron Hunter <https://github.com/cameronhunter>
13// Pirasis Leelatanon <https://github.com/1pete>
14// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
15// TypeScript Version: 3.0
16
17/// <reference types="node" />
18
19import { ChildProcess } from 'child_process';
20
21export namespace devices {
22 interface Device {
23 name: string;
24 userAgent: string;
25 viewport: {
26 width: number;
27 height: number;
28 deviceScaleFactor: number;
29 isMobile: boolean;
30 hasTouch: boolean;
31 isLandscape: boolean;
32 };
33 }
34}
35
36export const devices: { [name: string]: devices.Device };
37
38declare class CustomError extends Error {
39 constructor(message: string);
40}
41
42/**
43 * TimeoutError is emitted whenever certain operations are terminated due to timeout.
44 *
45 * Example operations are {@link Page.waitForSelector | page.waitForSelector}
46 * or {@link PuppeteerNode.launch | puppeteer.launch}.
47 */
48declare class TimeoutError extends CustomError {}
49
50export namespace errors {
51 class TimeoutError extends CustomError {}
52}
53
54/** Wraps a DOM element into an ElementHandle instance */
55export type WrapElementHandle<X> = X extends Element ? ElementHandle<X> : X;
56
57/** Unwraps a DOM element out of an ElementHandle instance */
58export type UnwrapElementHandle<X> = X extends ElementHandle<infer E> ? E : X;
59
60export type Serializable = number | string | boolean | null | JSONArray | JSONObject;
61export interface JSONArray extends Array<Serializable> {}
62export interface JSONObject {
63 [key: string]: Serializable;
64}
65export type SerializableOrJSHandle = Serializable | JSHandle;
66
67/**
68 * We want to maintain intellisense for known values but remain open to unknown values. This type is a workaround for
69 * [Microsoft/TypeScript#29729](https://github.com/Microsoft/TypeScript/issues/29729). It will be removed as soon as
70 * it's not needed anymore.
71 */
72type LiteralUnion<LiteralType> = LiteralType | (string & { _?: never | undefined });
73
74export type Platform = LiteralUnion<'mac' | 'win32' | 'win64' | 'linux'>;
75export type Product = LiteralUnion<'chrome' | 'firefox'>;
76
77/** Defines `$eval` and `$$eval` for Page, Frame and ElementHandle. */
78export interface Evalable {
79 /**
80 * This method runs `document.querySelector` within the context and passes it as the first argument to `pageFunction`.
81 * If there's no element matching `selector`, the method throws an error.
82 *
83 * If `pageFunction` returns a Promise, then `$eval` would wait for the promise to resolve and return its value.
84 *
85 * @param selector A selector to query for
86 * @param pageFunction Function to be evaluated in browser context
87 * @returns Promise which resolves to the return value of pageFunction
88 */
89 $eval<R>(selector: string, pageFunction: (element: Element) => R | Promise<R>): Promise<WrapElementHandle<R>>;
90
91 /**
92 * This method runs `document.querySelector` within the context and passes it as the first argument to `pageFunction`.
93 * If there's no element matching `selector`, the method throws an error.
94 *
95 * If `pageFunction` returns a Promise, then `$eval` would wait for the promise to resolve and return its value.
96 *
97 * @param selector A selector to query for
98 * @param pageFunction Function to be evaluated in browser context
99 * @param x1 First argument to pass to pageFunction
100 * @returns Promise which resolves to the return value of pageFunction
101 */
102 $eval<R, X1>(
103 selector: string,
104 pageFunction: (element: Element, x1: UnwrapElementHandle<X1>) => R | Promise<R>,
105 x1: X1,
106 ): Promise<WrapElementHandle<R>>;
107
108 /**
109 * This method runs `document.querySelector` within the context and passes it as the first argument to `pageFunction`.
110 * If there's no element matching `selector`, the method throws an error.
111 *
112 * If `pageFunction` returns a Promise, then `$eval` would wait for the promise to resolve and return its value.
113 *
114 * @param selector A selector to query for
115 * @param pageFunction Function to be evaluated in browser context
116 * @param x1 First argument to pass to pageFunction
117 * @param x2 Second argument to pass to pageFunction
118 * @returns Promise which resolves to the return value of pageFunction
119 */
120 $eval<R, X1, X2>(
121 selector: string,
122 pageFunction: (element: Element, x1: UnwrapElementHandle<X1>, x2: UnwrapElementHandle<X2>) => R | Promise<R>,
123 x1: X1,
124 x2: X2,
125 ): Promise<WrapElementHandle<R>>;
126
127 /**
128 * This method runs `document.querySelector` within the context and passes it as the first argument to `pageFunction`.
129 * If there's no element matching `selector`, the method throws an error.
130 *
131 * If `pageFunction` returns a Promise, then `$eval` would wait for the promise to resolve and return its value.
132 *
133 * @param selector A selector to query for
134 * @param pageFunction Function to be evaluated in browser context
135 * @param x1 First argument to pass to pageFunction
136 * @param x2 Second argument to pass to pageFunction
137 * @param x3 Third argument to pass to pageFunction
138 * @returns Promise which resolves to the return value of pageFunction
139 */
140 $eval<R, X1, X2, X3>(
141 selector: string,
142 pageFunction: (
143 element: Element,
144 x1: UnwrapElementHandle<X1>,
145 x2: UnwrapElementHandle<X2>,
146 x3: UnwrapElementHandle<X3>,
147 ) => R | Promise<R>,
148 x1: X1,
149 x2: X2,
150 x3: X3,
151 ): Promise<WrapElementHandle<R>>;
152
153 /**
154 * This method runs `document.querySelector` within the context and passes it as the first argument to `pageFunction`.
155 * If there's no element matching `selector`, the method throws an error.
156 *
157 * If `pageFunction` returns a Promise, then `$eval` would wait for the promise to resolve and return its value.
158 *
159 * @param selector A selector to query for
160 * @param pageFunction Function to be evaluated in browser context
161 * @param args Arguments to pass to pageFunction
162 * @returns Promise which resolves to the return value of pageFunction
163 */
164 $eval<R>(
165 selector: string,
166 pageFunction: (element: Element, ...args: any[]) => R | Promise<R>,
167 ...args: SerializableOrJSHandle[]
168 ): Promise<WrapElementHandle<R>>;
169
170 /**
171 * This method runs `Array.from(document.querySelectorAll(selector))` within the context and passes it as the
172 * first argument to `pageFunction`.
173 *
174 * If `pageFunction` returns a Promise, then `$$eval` would wait for the promise to resolve and return its value.
175 *
176 * @param selector A selector to query for
177 * @param pageFunction Function to be evaluated in browser context
178 * @returns Promise which resolves to the return value of pageFunction
179 */
180 $$eval<R>(selector: string, pageFunction: (elements: Element[]) => R | Promise<R>): Promise<WrapElementHandle<R>>;
181
182 /**
183 * This method runs `Array.from(document.querySelectorAll(selector))` within the context and passes it as the
184 * first argument to `pageFunction`.
185 *
186 * If `pageFunction` returns a Promise, then `$$eval` would wait for the promise to resolve and return its value.
187 *
188 * @param selector A selector to query for
189 * @param pageFunction Function to be evaluated in browser context
190 * @param x1 First argument to pass to pageFunction
191 * @returns Promise which resolves to the return value of pageFunction
192 */
193 $$eval<R, X1>(
194 selector: string,
195 pageFunction: (elements: Element[], x1: UnwrapElementHandle<X1>) => R | Promise<R>,
196 x1: X1,
197 ): Promise<WrapElementHandle<R>>;
198
199 /**
200 * This method runs `Array.from(document.querySelectorAll(selector))` within the context and passes it as the
201 * first argument to `pageFunction`.
202 *
203 * If `pageFunction` returns a Promise, then `$$eval` would wait for the promise to resolve and return its value.
204 *
205 * @param selector A selector to query for
206 * @param pageFunction Function to be evaluated in browser context
207 * @param x1 First argument to pass to pageFunction
208 * @param x2 Second argument to pass to pageFunction
209 * @returns Promise which resolves to the return value of pageFunction
210 */
211 $$eval<R, X1, X2>(
212 selector: string,
213 pageFunction: (elements: Element[], x1: UnwrapElementHandle<X1>, x2: UnwrapElementHandle<X2>) => R | Promise<R>,
214 x1: X1,
215 x2: X2,
216 ): Promise<WrapElementHandle<R>>;
217
218 /**
219 * This method runs `Array.from(document.querySelectorAll(selector))` within the context and passes it as the
220 * first argument to `pageFunction`.
221 *
222 * If `pageFunction` returns a Promise, then `$$eval` would wait for the promise to resolve and return its value.
223 *
224 * @param selector A selector to query for
225 * @param pageFunction Function to be evaluated in browser context
226 * @param x1 First argument to pass to pageFunction
227 * @param x2 Second argument to pass to pageFunction
228 * @param x3 Third argument to pass to pageFunction
229 * @returns Promise which resolves to the return value of pageFunction
230 */
231 $$eval<R, X1, X2, X3>(
232 selector: string,
233 pageFunction: (
234 elements: Element[],
235 x1: UnwrapElementHandle<X1>,
236 x2: UnwrapElementHandle<X2>,
237 x3: UnwrapElementHandle<X3>,
238 ) => R | Promise<R>,
239 x1: X1,
240 x2: X2,
241 x3: X3,
242 ): Promise<WrapElementHandle<R>>;
243
244 /**
245 * This method runs `Array.from(document.querySelectorAll(selector))` within the context and passes it as the
246 * first argument to `pageFunction`.
247 *
248 * If `pageFunction` returns a Promise, then `$$eval` would wait for the promise to resolve and return its value.
249 *
250 * @param selector A selector to query for
251 * @param pageFunction Function to be evaluated in browser context
252 * @param args Arguments to pass to pageFunction
253 * @returns Promise which resolves to the return value of pageFunction
254 */
255 $$eval<R>(
256 selector: string,
257 pageFunction: (elements: Element[], ...args: any[]) => R | Promise<R>,
258 ...args: SerializableOrJSHandle[]
259 ): Promise<WrapElementHandle<R>>;
260}
261
262export interface JSEvalable<A = any> {
263 /**
264 * Evaluates a function in the browser context.
265 * If the function, passed to the frame.evaluate, returns a Promise, then frame.evaluate would wait for the promise to resolve and return its value.
266 * If the function passed into frame.evaluate returns a non-Serializable value, then frame.evaluate resolves to undefined.
267 * @param fn Function to be evaluated in browser context
268 * @param args Arguments to pass to `fn`
269 */
270 evaluate<T extends EvaluateFn<A>>(
271 pageFunction: T,
272 ...args: SerializableOrJSHandle[]
273 ): Promise<EvaluateFnReturnType<T> extends PromiseLike<infer U> ? U : EvaluateFnReturnType<T>>;
274 /**
275 * The only difference between `evaluate` and `evaluateHandle` is that `evaluateHandle` returns in-page object (`JSHandle`).
276 * If the function, passed to the `evaluateHandle`, returns a `Promise`, then `evaluateHandle` would wait for the
277 * promise to resolve and return its value.
278 * The TypeScript definitions assume that `evaluateHandle` returns a `JSHandle`, but if you know it's going to return an
279 * `ElementHandle`, pass it as the generic argument:
280 * @param pageFunction - a function that is run within the page
281 * @param args - arguments to be passed to the pageFunction
282 */
283 // tslint:disable-next-line no-unnecessary-generics (This generic is meant to be passed explicitly.) # https://github.com/Microsoft/dtslint/issues/76
284 evaluateHandle<HandlerType extends JSHandle = JSHandle>(
285 pageFunction: string | ((arg1: A, ...args: any[]) => any),
286 ...args: SerializableOrJSHandle[]
287 // tslint:disable-next-line no-unnecessary-generics (This generic is meant to be passed explicitly.) # https://github.com/Microsoft/dtslint/issues/76
288 ): Promise<HandlerType>;
289}
290
291export interface KeyboardDownOptions {
292 text?: string | undefined;
293}
294
295export interface KeyboardTypeOptions {
296 delay?: number | undefined;
297}
298
299export interface KeyboardPressOptions extends KeyboardDownOptions, KeyboardTypeOptions {}
300
301/** Keyboard provides an api for managing a virtual keyboard. */
302export interface Keyboard {
303 /**
304 * Dispatches a keydown event.
305 * @param key Name of key to press, such as ArrowLeft.
306 * @param options Specifies a input text event.
307 */
308 down(key: string, options?: KeyboardDownOptions): Promise<void>;
309
310 /** Shortcut for `keyboard.down` and `keyboard.up`. */
311 press(key: string, options?: KeyboardPressOptions): Promise<void>;
312
313 /** Dispatches a `keypress` and `input` event. This does not send a `keydown` or keyup `event`. */
314 sendCharacter(char: string): Promise<void>;
315
316 /**
317 * Sends a keydown, keypress/input, and keyup event for each character in the text.
318 * @param text A text to type into a focused element.
319 * @param options Specifies the typing options.
320 */
321 type(text: string, options?: KeyboardTypeOptions): Promise<void>;
322
323 /**
324 * Dispatches a keyup event.
325 * @param key Name of key to release, such as ArrowLeft.
326 */
327 up(key: string): Promise<void>;
328}
329
330export interface MousePressOptions {
331 /**
332 * left, right, or middle.
333 * @default left
334 */
335 button?: MouseButtons | undefined;
336 /**
337 * The number of clicks.
338 * @default 1
339 */
340 clickCount?: number | undefined;
341}
342
343export interface MouseWheelOptions {
344 deltaX?: number | undefined;
345 deltaY?: number | undefined;
346}
347
348export interface MouseWheelOptions {
349 /**
350 * X delta in CSS pixels for mouse wheel event. Positive values emulate a scroll up and negative values a scroll down event.
351 * @default 0
352 */
353 deltaX?: number | undefined;
354 /**
355 * Y delta in CSS pixels for mouse wheel event. Positive values emulate a scroll right and negative values a scroll left event.
356 * @default 0
357 */
358 deltaY?: number | undefined;
359}
360
361export interface Mouse {
362 /**
363 * Shortcut for `mouse.move`, `mouse.down` and `mouse.up`.
364 * @param x The x position.
365 * @param y The y position.
366 * @param options The click options.
367 */
368 click(x: number, y: number, options?: ClickOptions): Promise<void>;
369 /**
370 * Dispatches a `mousedown` event.
371 * @param options The mouse press options.
372 */
373 down(options?: MousePressOptions): Promise<void>;
374
375 /**
376 * Dispatches a `mousemove` event.
377 * @param x The x position.
378 * @param y The y position.
379 * @param options The mouse move options.
380 */
381 move(x: number, y: number, options?: { steps: number }): Promise<void>;
382 /**
383 * Dispatches a `mouseup` event.
384 * @param options The mouse press options.
385 */
386 up(options?: MousePressOptions): Promise<void>;
387
388 /**
389 * Dispatches a `mousewheel` event.
390 * @param options - Optional: `MouseWheelOptions`.
391 *
392 * @example
393 * An example of zooming into an element:
394 * ```js
395 * await page.goto('https://mdn.mozillademos.org/en-US/docs/Web/API/Element/wheel_event$samples/Scaling_an_element_via_the_wheel?revision=1587366');
396 *
397 * const elem = await page.$('div');
398 * const boundingBox = await elem.boundingBox();
399 * await page.mouse.move(
400 * boundingBox.x + boundingBox.width / 2,
401 * boundingBox.y + boundingBox.height / 2
402 * );
403 *
404 * await page.mouse.wheel({ deltaY: -100 })
405 * ```
406 */
407 wheel(options?: MouseWheelOptions): Promise<void>;
408}
409
410export interface Touchscreen {
411 /**
412 * Dispatches a touchstart and touchend event.
413 * @param x The x position.
414 * @param y The y position.
415 */
416 tap(x: number, y: number): Promise<void>;
417}
418/**
419 * You can use `tracing.start` and `tracing.stop` to create a trace file which can be opened in Chrome DevTools or timeline viewer.
420 */
421export interface Tracing {
422 start(options: TracingStartOptions): Promise<void>;
423 stop(): Promise<Buffer>;
424}
425
426export interface TracingStartOptions {
427 path?: string | undefined;
428 screenshots?: boolean | undefined;
429 categories?: string[] | undefined;
430}
431
432export type DialogType = 'alert' | 'beforeunload' | 'confirm' | 'prompt';
433
434/** Dialog objects are dispatched by page via the 'dialog' event. */
435export interface Dialog {
436 /**
437 * Accepts the dialog.
438 * @param promptText A text to enter in prompt. Does not cause any effects if the dialog's type is not prompt.
439 */
440 accept(promptText?: string): Promise<void>;
441
442 /** If dialog is prompt, returns default prompt value. Otherwise, returns empty string. */
443 defaultValue(): string;
444
445 /** Dismiss the dialog */
446 dismiss(): Promise<void>;
447
448 /** Returns the message displayed in the dialog. */
449 message(): string;
450
451 /** The dialog type. Dialog's type, can be one of `alert`, `beforeunload`, `confirm` or `prompt`. */
452 type(): DialogType;
453}
454
455export type ConsoleMessageType =
456 | 'log'
457 | 'debug'
458 | 'info'
459 | 'error'
460 | 'warning'
461 | 'dir'
462 | 'dirxml'
463 | 'table'
464 | 'trace'
465 | 'clear'
466 | 'startGroup'
467 | 'startGroupCollapsed'
468 | 'endGroup'
469 | 'assert'
470 | 'profile'
471 | 'profileEnd'
472 | 'count'
473 | 'timeEnd';
474
475export interface ConsoleMessageLocation {
476 /**
477 * URL of the resource if known.
478 */
479 url?: string | undefined;
480 /**
481 * Line number in the resource if known
482 */
483 lineNumber?: number | undefined;
484 /**
485 * Column number in the resource if known.
486 */
487 columnNumber?: number | undefined;
488}
489
490/** ConsoleMessage objects are dispatched by page via the 'console' event. */
491export interface ConsoleMessage {
492 /** The message arguments. */
493 args(): JSHandle[];
494 /** The location the message originated from */
495 location(): ConsoleMessageLocation;
496 /** The message text. */
497 text(): string;
498 type(): ConsoleMessageType;
499}
500
501export interface AuthOptions {
502 username: string;
503 password: string;
504}
505
506export type MouseButtons = 'left' | 'right' | 'middle';
507
508export interface ClickOptions {
509 /** @default MouseButtons.Left */
510 button?: MouseButtons | undefined;
511 /** @default 1 */
512 clickCount?: number | undefined;
513 /**
514 * Time to wait between mousedown and mouseup in milliseconds.
515 * @default 0
516 */
517 delay?: number | undefined;
518}
519
520export type SameSiteSetting = 'Strict' | 'Lax';
521
522/** Represents a browser cookie. */
523export interface Cookie {
524 /** The cookie name. */
525 name: string;
526 /** The cookie value. */
527 value: string;
528 /** The cookie domain. */
529 domain: string;
530 /** The cookie path. */
531 path: string;
532 /** The cookie Unix expiration time in seconds. */
533 expires: number;
534 /** The cookie size */
535 size: number;
536 /** The cookie http only flag. */
537 httpOnly: boolean;
538 /** The session cookie flag. */
539 session: boolean;
540 /** The cookie secure flag. */
541 secure: boolean;
542 /** The cookie same site definition. */
543 sameSite: SameSiteSetting;
544}
545
546export interface DeleteCookie {
547 /** The cookie name. */
548 name: string;
549 url?: string | undefined;
550 domain?: string | undefined;
551 path?: string | undefined;
552}
553
554export interface SetCookie {
555 /** The cookie name. */
556 name: string;
557 /** The cookie value. */
558 value: string;
559 /** The request-URI to associate with the setting of the cookie. This value can affect the default domain and path values of the created cookie. */
560 url?: string | undefined;
561 /** The cookie domain. */
562 domain?: string | undefined;
563 /** The cookie path. */
564 path?: string | undefined;
565 /** The cookie Unix expiration time in seconds. */
566 expires?: number | undefined;
567 /** The cookie http only flag. */
568 httpOnly?: boolean | undefined;
569 /** The session cookie flag. */
570 session?: boolean | undefined;
571 /** The cookie secure flag. */
572 secure?: boolean | undefined;
573 /** The cookie same site definition. */
574 sameSite?: SameSiteSetting | undefined;
575}
576
577export interface Viewport {
578 /** The page width in pixels. */
579 width: number;
580 /** The page height in pixels. */
581 height: number;
582 /**
583 * Specify device scale factor (can be thought of as dpr).
584 * @default 1
585 */
586 deviceScaleFactor?: number | undefined;
587 /**
588 * Whether the `meta viewport` tag is taken into account.
589 * @default false
590 */
591 isMobile?: boolean | undefined;
592 /**
593 * Specifies if viewport supports touch events.
594 * @default false
595 */
596 hasTouch?: boolean | undefined;
597 /**
598 * Specifies if viewport is in landscape mode.
599 * @default false
600 */
601 isLandscape?: boolean | undefined;
602}
603
604/** Page emulation options. */
605export interface EmulateOptions {
606 /** The viewport emulation options. */
607 viewport: Viewport;
608 /** The emulated user-agent. */
609 userAgent: string;
610}
611
612export type EvaluateFn<T = any> = string | ((arg1: T, ...args: any[]) => any);
613export type EvaluateFnReturnType<T extends EvaluateFn> = T extends (...args: any[]) => infer R ? R : unknown;
614
615export type LoadEvent = 'load' | 'domcontentloaded' | 'networkidle0' | 'networkidle2';
616
617export interface Timeoutable {
618 /**
619 * Maximum navigation time in milliseconds, pass 0 to disable timeout.
620 * @default 30000
621 */
622 timeout?: number | undefined;
623}
624
625/** The navigation options. */
626export interface NavigationOptions extends Timeoutable {
627 /**
628 * When to consider navigation succeeded.
629 * @default load Navigation is consider when the `load` event is fired.
630 */
631 waitUntil?: LoadEvent | LoadEvent[] | undefined;
632}
633
634/**
635 * Navigation options for `page.goto`.
636 */
637export interface DirectNavigationOptions extends NavigationOptions {
638 /**
639 * Referer header value.
640 * If provided it will take preference over the referer header value set by
641 * [page.setExtraHTTPHeaders()](#pagesetextrahttpheadersheaders).
642 */
643 referer?: string | undefined;
644}
645
646/** Accepts values labeled with units. If number, treat as pixels. */
647export type LayoutDimension = string | number;
648
649export type PDFFormat = 'Letter' | 'Legal' | 'Tabloid' | 'Ledger' | 'A0' | 'A1' | 'A2' | 'A3' | 'A4' | 'A5' | 'A6';
650
651export interface PDFOptions {
652 /**
653 * The file path to save the PDF to.
654 * If `path` is a relative path, then it is resolved relative to current working directory.
655 * If no path is provided, the PDF won't be saved to the disk.
656 */
657 path?: string | undefined;
658 /**
659 * Scale of the webpage rendering.
660 * @default 1
661 */
662 scale?: number | undefined;
663 /**
664 * Display header and footer.
665 * @default false
666 */
667 displayHeaderFooter?: boolean | undefined;
668 /**
669 * HTML template for the print header. Should be valid HTML markup with following classes used to inject printing values into them:
670 * - `date` formatted print date
671 * - `title` document title
672 * - `url` document location
673 * - `pageNumber` current page number
674 * - `totalPages` total pages in the document
675 */
676 headerTemplate?: string | undefined;
677 /**
678 * HTML template for the print footer. Should be valid HTML markup with following classes used to inject printing values into them:
679 * - `date` formatted print date
680 * - `title` document title
681 * - `url` document location
682 * - `pageNumber` current page number
683 * - `totalPages` total pages in the document
684 */
685 footerTemplate?: string | undefined;
686 /**
687 * Print background graphics.
688 * @default false
689 */
690 printBackground?: boolean | undefined;
691 /**
692 * Paper orientation.
693 * @default false
694 */
695 landscape?: boolean | undefined;
696 /**
697 * Paper ranges to print, e.g., '1-5, 8, 11-13'.
698 * @default '' which means print all pages.
699 */
700 pageRanges?: string | undefined;
701 /**
702 * Paper format. If set, takes priority over width or height options.
703 * @default 'Letter'
704 */
705 format?: PDFFormat | undefined;
706 /** Paper width. */
707 width?: LayoutDimension | undefined;
708 /** Paper height. */
709 height?: LayoutDimension | undefined;
710 /** Paper margins, defaults to none. */
711 margin?: {
712 /** Top margin. */
713 top?: LayoutDimension | undefined;
714 /** Right margin. */
715 right?: LayoutDimension | undefined;
716 /** Bottom margin. */
717 bottom?: LayoutDimension | undefined;
718 /** Left margin. */
719 left?: LayoutDimension | undefined;
720 } | undefined;
721 /**
722 * Give any CSS @page size declared in the page priority over what is declared in width and
723 * height or format options.
724 * @default false which will scale the content to fit the paper size.
725 */
726 preferCSSPageSize?: boolean | undefined;
727}
728
729/** Defines the screenshot options. */
730export interface ScreenshotOptions {
731 /**
732 * The file path to save the image to. The screenshot type will be inferred from file extension.
733 * If `path` is a relative path, then it is resolved relative to current working directory.
734 * If no path is provided, the image won't be saved to the disk.
735 */
736 path?: string | undefined;
737 /**
738 * The screenshot type.
739 * @default png
740 */
741 type?: 'jpeg' | 'png' | undefined;
742 /** The quality of the image, between 0-100. Not applicable to png images. */
743 quality?: number | undefined;
744 /**
745 * When true, takes a screenshot of the full scrollable page.
746 * @default false
747 */
748 fullPage?: boolean | undefined;
749 /**
750 * An object which specifies clipping region of the page.
751 */
752 clip?: BoundingBox | undefined;
753 /**
754 * Hides default white background and allows capturing screenshots with transparency.
755 * @default false
756 */
757 omitBackground?: boolean | undefined;
758 /**
759 * The encoding of the image, can be either base64 or binary.
760 * @default binary
761 */
762 encoding?: 'base64' | 'binary' | undefined;
763}
764
765export interface BinaryScreenShotOptions extends ScreenshotOptions {
766 encoding?: 'binary' | undefined;
767}
768
769export interface Base64ScreenShotOptions extends ScreenshotOptions {
770 encoding: 'base64';
771}
772
773/** Options for `addStyleTag` */
774export interface StyleTagOptions {
775 /** Url of the <link> tag. */
776 url?: string | undefined;
777 /** Path to the CSS file to be injected into frame. If `path` is a relative path, then it is resolved relative to current working directory. */
778 path?: string | undefined;
779 /** Raw CSS content to be injected into frame. */
780 content?: string | undefined;
781}
782/** Options for `addScriptTag` */
783export interface ScriptTagOptions {
784 /** Url of a script to be added. */
785 url?: string | undefined;
786 /** Path to the JavaScript file to be injected into frame. If `path` is a relative path, then it is resolved relative to current working directory. */
787 path?: string | undefined;
788 /** Raw JavaScript content to be injected into frame. */
789 content?: string | undefined;
790 /** Script type. Use 'module' in order to load a Javascript ES6 module. */
791 type?: string | undefined;
792}
793
794export interface PageFnOptions extends Timeoutable {
795 polling?: 'raf' | 'mutation' | number | undefined;
796}
797
798export interface BoundingBox {
799 /** The x-coordinate of top-left corner. */
800 x: number;
801 /** The y-coordinate of top-left corner. */
802 y: number;
803 /** The width. */
804 width: number;
805 /** The height. */
806 height: number;
807}
808
809export interface BoxModel {
810 /** Content box, represented as an array of {x, y} points. */
811 content: Box[];
812 /** Padding box, represented as an array of {x, y} points. */
813 padding: Box[];
814 /** Border box, represented as an array of {x, y} points. */
815 border: Box[];
816 /** Margin box, represented as an array of {x, y} points. */
817 margin: Box[];
818 width: number;
819 height: number;
820}
821
822export interface Box {
823 x: number;
824 y: number;
825}
826
827/**
828 * The Worker class represents a WebWorker.
829 * The events workercreated and workerdestroyed are emitted on the page object to signal the worker lifecycle.
830 */
831export interface Worker extends JSEvalable {
832 executionContext(): Promise<ExecutionContext>;
833
834 url(): string;
835}
836
837/**
838 * Represents an in-page DOM element. ElementHandles can be created with the page.$ method.
839 */
840export interface ElementHandle<E extends Element = Element> extends JSHandle<E>, Evalable {
841 /**
842 * The method runs element.querySelector within the page.
843 * If no element matches the selector, the return value resolve to null.
844 * @param selector A selector to query element for
845 * @since 0.13.0
846 */
847 $(selector: string): Promise<ElementHandle | null>;
848
849 /**
850 * The method runs element.querySelectorAll within the page.
851 * If no elements match the selector, the return value resolve to [].
852 * @param selector A selector to query element for
853 * @since 0.13.0
854 */
855 $$(selector: string): Promise<ElementHandle[]>;
856
857 /**
858 * @param selector XPath expression to evaluate.
859 */
860 $x(expression: string): Promise<ElementHandle[]>;
861 /**
862 * This method returns the value resolve to the bounding box of the element (relative to the main frame), or null if the element is not visible.
863 */
864 boundingBox(): Promise<BoundingBox | null>;
865 /**
866 * This method returns boxes of the element, or null if the element is not visible.
867 * Boxes are represented as an array of points; each Point is an object {x, y}. Box points are sorted clock-wise.
868 */
869 boxModel(): Promise<BoxModel | null>;
870 /**
871 * This method scrolls element into view if needed, and then uses page.mouse to click in the center of the element.
872 * If the element is detached from DOM, the method throws an error.
873 * @param options Specifies the options.
874 * @since 0.9.0
875 */
876 click(options?: ClickOptions): Promise<void>;
877 /**
878 * @returns Resolves to the content frame for element handles referencing iframe nodes, or null otherwise.
879 * @since 1.2.0
880 */
881 contentFrame(): Promise<Frame | null>;
882 /**
883 * Calls focus on the element.
884 */
885 focus(): Promise<void>;
886 /**
887 * This method scrolls element into view if needed, and then uses page.mouse to hover over the center of the element.
888 * If the element is detached from DOM, the method throws an error.
889 */
890 hover(): Promise<void>;
891 /**
892 * Resolves to true if the element is visible in the current viewport.
893 */
894 isIntersectingViewport(): Promise<boolean>;
895 /**
896 * Focuses the element, and then uses keyboard.down and keyboard.up.
897 * @param key Name of key to press, such as ArrowLeft. See USKeyboardLayout for a list of all key names.
898 * @param options The text and delay options.
899 */
900 press(key: string, options?: { text?: string | undefined; delay?: number | undefined }): Promise<void>;
901 /**
902 * This method scrolls element into view if needed, and then uses page.screenshot to take a screenshot of the element.
903 * If the element is detached from DOM, the method throws an error.
904 * @param options Same options as in page.screenshot.
905 */
906 screenshot(options?: Base64ScreenShotOptions): Promise<string>;
907 screenshot(options?: BinaryScreenShotOptions): Promise<Buffer>;
908 screenshot(options?: ScreenshotOptions): Promise<string | Buffer>;
909 /**
910 * Triggers a change and input event once all the provided options have been selected. If there's no <select> element
911 * matching selector, the method throws an error.
912 * @param values Values of options to select. If the <select> has the multiple attribute, all values are considered, otherwise only the first one is taken into account.
913 * @returns An array of option values that have been successfully selected.
914 * @since 1.12.0
915 */
916 select(...values: string[]): Promise<string[]>;
917 /**
918 * This method scrolls element into view if needed, and then uses touchscreen.tap to tap in the center of the element.
919 * If the element is detached from DOM, the method throws an error.
920 */
921 tap(): Promise<void>;
922 toString(): string;
923 /**
924 * Focuses the element, and then sends a keydown, keypress/input, and keyup event for each character in the text.
925 * @param text A text to type into a focused element.
926 * @param options The typing options.
927 */
928 type(text: string, options?: { delay: number }): Promise<void>;
929 /**
930 * This method expects elementHandle to point to an input element.
931 * @param filePaths Sets the value of the file input these paths. If some of the filePaths are relative paths, then they are resolved relative to current working directory.
932 */
933 uploadFile(...filePaths: string[]): Promise<void>;
934}
935
936/** The class represents a context for JavaScript execution. */
937export interface ExecutionContext extends JSEvalable {
938 queryObjects(prototypeHandle: JSHandle): Promise<JSHandle>;
939}
940
941/** JSHandle represents an in-page JavaScript object. */
942export interface JSHandle<T = any> extends JSEvalable<T> {
943 /**
944 * Returns a ElementHandle
945 */
946 asElement(): ElementHandle | null;
947 /**
948 * Stops referencing the element handle.
949 */
950 dispose(): Promise<void>;
951 /**
952 * Gets the execution context.
953 */
954 executionContext(): ExecutionContext;
955 /**
956 * Returns a map with property names as keys and JSHandle instances for the property values.
957 */
958 getProperties(): Promise<Map<string, JSHandle>>;
959 /**
960 * Fetches a single property from the objectHandle.
961 * @param propertyName The property to get.
962 */
963 getProperty(propertyName: string): Promise<JSHandle>;
964
965 /**
966 * Returns a JSON representation of the object.
967 * The JSON is generated by running JSON.stringify on the object in page and consequent JSON.parse in puppeteer.
968 * @throws The method will throw if the referenced object is not stringifiable.
969 */
970 jsonValue(): Promise<unknown>;
971}
972
973export interface Metrics {
974 /** The timestamp when the metrics sample was taken. */
975 Timestamp: number;
976 /** Number of documents in the page. */
977 Documents: number;
978 /** Number of frames in the page. */
979 Frames: number;
980 /** Number of events in the page. */
981 JSEventListeners: number;
982 /** Number of DOM nodes in the page. */
983 Nodes: number;
984 /** Total number of full or partial page layout. */
985 LayoutCount: number;
986 /** Total number of page style recalculations. */
987 RecalcStyleCount: number;
988 /** Combined durations of all page layouts. */
989 LayoutDuration: number;
990 /** Combined duration of all page style recalculations. */
991 RecalcStyleDuration: number;
992 /** Combined duration of JavaScript execution. */
993 ScriptDuration: number;
994 /** Combined duration of all tasks performed by the browser. */
995 TaskDuration: number;
996 /** Used JavaScript heap size. */
997 JSHeapUsedSize: number;
998 /** Total JavaScript heap size. */
999 JSHeapTotalSize: number;
1000}
1001
1002export type Headers = Record<string, string>;
1003export type HttpMethod = 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE' | 'OPTIONS';
1004
1005export type ResourceType =
1006 | 'document'
1007 | 'stylesheet'
1008 | 'image'
1009 | 'media'
1010 | 'font'
1011 | 'script'
1012 | 'texttrack'
1013 | 'xhr'
1014 | 'fetch'
1015 | 'eventsource'
1016 | 'websocket'
1017 | 'manifest'
1018 | 'other';
1019
1020export type ErrorCode =
1021 | 'aborted'
1022 | 'accessdenied'
1023 | 'addressunreachable'
1024 | 'blockedbyclient'
1025 | 'blockedbyresponse'
1026 | 'connectionaborted'
1027 | 'connectionclosed'
1028 | 'connectionfailed'
1029 | 'connectionrefused'
1030 | 'connectionreset'
1031 | 'internetdisconnected'
1032 | 'namenotresolved'
1033 | 'timedout'
1034 | 'failed';
1035
1036export interface Overrides {
1037 url?: string | undefined;
1038 method?: HttpMethod | undefined;
1039 postData?: string | undefined;
1040 headers?: Headers | undefined;
1041}
1042
1043/** Represents a page request. */
1044export interface Request {
1045 /**
1046 * Aborts request.
1047 * To use this, request interception should be enabled with `page.setRequestInterception`.
1048 * @throws An exception is immediately thrown if the request interception is not enabled.
1049 */
1050 abort(errorCode?: ErrorCode): Promise<void>;
1051
1052 /**
1053 * Continues request with optional request overrides.
1054 * To use this, request interception should be enabled with `page.setRequestInterception`.
1055 * @throws An exception is immediately thrown if the request interception is not enabled.
1056 */
1057 continue(overrides?: Overrides): Promise<void>;
1058
1059 /**
1060 * @returns An object if the request failed, null otherwise.
1061 */
1062 failure(): { errorText: string } | null;
1063
1064 /**
1065 * @returns The `Frame` object that initiated the request, or `null` if navigating to error pages
1066 */
1067 frame(): Frame | null;
1068
1069 /**
1070 * An object with HTTP headers associated with the request.
1071 * All header names are lower-case.
1072 */
1073 headers(): Headers;
1074
1075 /** Whether this request is driving frame's navigation. */
1076 isNavigationRequest(): boolean;
1077
1078 /** Returns the request's method (GET, POST, etc.) */
1079
1080 method(): HttpMethod;
1081
1082 /** Contains the request's post body, if any. */
1083 postData(): string | undefined;
1084
1085 /**
1086 * A `redirectChain` is a chain of requests initiated to fetch a resource.
1087 *
1088 * - If there are no redirects and the request was successful, the chain will be empty.
1089 * - If a server responds with at least a single redirect, then the chain will contain all the requests that were redirected.
1090 *
1091 * `redirectChain` is shared between all the requests of the same chain.
1092 *
1093 * @since 1.2.0
1094 */
1095 redirectChain(): Request[];
1096
1097 /** Contains the request's resource type as it was perceived by the rendering engine. */
1098 resourceType(): ResourceType;
1099
1100 /**
1101 * Fulfills request with given response.
1102 * To use this, request interception should be enabled with `page.setRequestInterception`.
1103 * @throws An exception is immediately thrown if the request interception is not enabled.
1104 * @param response The response options that will fulfill this request.
1105 */
1106 respond(response: RespondOptions): Promise<void>;
1107
1108 /** A matching `Response` object, or `null` if the response has not been received yet. */
1109 response(): Response | null;
1110
1111 /** Contains the URL of the request. */
1112 url(): string;
1113}
1114/** Options for `Request.respond` method */
1115export interface RespondOptions {
1116 /**
1117 * Specifies the response status code.
1118 * @default 200
1119 */
1120 status?: number | undefined;
1121 /** Specifies the response headers. */
1122 headers?: Headers | undefined;
1123 /** Specifies the Content-Type response header. */
1124 contentType?: string | undefined;
1125 /** Specifies the response body. */
1126 body?: Buffer | string | undefined;
1127}
1128
1129export interface RemoteInfo {
1130 /** the IP address of the remote server */
1131 ip: string;
1132 /** the port used to connect to the remote server */
1133 port: number;
1134}
1135
1136export interface SecurityDetails {
1137 /** A string with the name of issuer of the certificate. (e.g. "Let's Encrypt Authority X3"). */
1138 issuer(): string;
1139 /** String with the security protocol (e.g. TLS 1.2). */
1140 protocol(): string;
1141 /** Name of the subject to which the certificate was issued to (e.g. "www.example.com"). */
1142 subjectName(): string;
1143 /** Timestamp stating the start of validity of the certificate. */
1144 validFrom(): number;
1145 /** Timestamp stating the end of validity of the certificate. */
1146 validTo(): number;
1147}
1148
1149/** Response class represents responses which are received by page. */
1150export interface Response {
1151 /** Promise which resolves to a buffer with response body. */
1152 buffer(): Promise<Buffer>;
1153 /** A Frame that initiated this response, or null if navigating to error pages. */
1154 frame(): Frame | null;
1155 /** True if the response was served from either the browser's disk cache or memory cache. */
1156 fromCache(): boolean;
1157 /** True if the response was served by a service worker. */
1158 fromServiceWorker(): boolean;
1159 /** An object with HTTP headers associated with the response. All header names are lower-case. */
1160 headers(): Headers;
1161 /**
1162 * Promise which resolves to a JSON representation of response body.
1163 * @throws This method will throw if the response body is not parsable via `JSON.parse`.
1164 */
1165 json(): Promise<unknown>;
1166 /** Contains a boolean stating whether the response was successful (status in the range 200-299) or not. */
1167 ok(): boolean;
1168 /** Returns remote connection info */
1169 remoteAddress(): RemoteInfo;
1170 /** Returns an object with security details associated with the response. */
1171 securityDetails(): SecurityDetails | null;
1172 /** A matching Request object. */
1173 request(): Request;
1174 /** Contains the status code of the response (e.g., 200 for a success). */
1175 status(): number;
1176 /** Contains the status text of the response (e.g. usually an "OK" for a success). */
1177 statusText(): string;
1178 /** Promise which resolves to a text representation of response body. */
1179 text(): Promise<string>;
1180 /** Contains the URL of the response. */
1181 url(): string;
1182}
1183
1184export interface WaitForSelectorOptions extends Timeoutable {
1185 /**
1186 * Wait for element to be present in DOM and to be visible,
1187 * i.e. to not have display: none or visibility: hidden CSS properties.
1188 * @default false
1189 */
1190 visible?: boolean | undefined;
1191 /**
1192 * Wait for element to not be found in the DOM or to be hidden,
1193 * i.e. have display: none or visibility: hidden CSS properties.
1194 * @default false
1195 */
1196 hidden?: boolean | undefined;
1197}
1198
1199export interface WaitForSelectorOptionsHidden extends WaitForSelectorOptions {
1200 hidden: true;
1201}
1202
1203export interface FrameBase extends Evalable, JSEvalable {
1204 /**
1205 * The method queries frame for the selector.
1206 * If there's no such element within the frame, the method will resolve to null.
1207 */
1208 $(selector: string): Promise<ElementHandle | null>;
1209
1210 /**
1211 * The method runs document.querySelectorAll within the frame.
1212 * If no elements match the selector, the return value resolve to [].
1213 */
1214 $$(selector: string): Promise<ElementHandle[]>;
1215
1216 /**
1217 * The method evaluates the XPath expression.
1218 * @param expression XPath expression to evaluate.
1219 */
1220 $x(expression: string): Promise<ElementHandle[]>;
1221
1222 /** Adds a `<script>` tag into the page with the desired url or content. */
1223 addScriptTag(options: ScriptTagOptions): Promise<void>;
1224
1225 /** Adds a `<link rel="stylesheet">` tag into the page with the desired url or a `<style type="text/css">` tag with the content. */
1226 addStyleTag(options: StyleTagOptions): Promise<void>;
1227
1228 /**
1229 * This method fetches an element with selector, scrolls it into view if needed, and
1230 * then uses `page.mouse` to click in the center of the element. If there's no element
1231 * matching selector, the method throws an error.
1232 * @param selector A selector to search for element to click. If there are multiple elements satisfying the selector, the first will be clicked.
1233 * @param options Specifies the click options.
1234 */
1235 click(selector: string, options?: ClickOptions): Promise<void>;
1236
1237 /** Gets the full HTML contents of the page, including the doctype. */
1238 content(): Promise<string>;
1239
1240 /**
1241 * Navigates to a URL.
1242 * @param url URL to navigate page to. The url should include scheme, e.g. `https://`
1243 * @param options The navigation parameters.
1244 */
1245 goto(url: string, options?: DirectNavigationOptions): Promise<Response | null>;
1246
1247 /** This method fetches an element with selector and focuses it. */
1248 focus(selector: string): Promise<void>;
1249
1250 /**
1251 * This method fetches an element with `selector`, scrolls it into view if needed,
1252 * and then uses page.mouse to hover over the center of the element. If there's no
1253 * element matching `selector`, the method throws an error.
1254 * @param selector A selector to search for element to hover. If there are multiple elements satisfying the selector, the first will be hovered.
1255 */
1256 hover(selector: string): Promise<void>;
1257
1258 /**
1259 * Triggers a `change` and `input` event once all the provided options have been selected.
1260 * If there's no `<select>` element matching selector, the method throws an error.
1261 * @param selector A selector to query page for.
1262 * @param values Values of options to select. If the `<select>` has the `multiple` attribute,
1263 * all values are considered, otherwise only the first one is taken into account.
1264 */
1265 select(selector: string, ...values: string[]): Promise<string[]>;
1266
1267 /**
1268 * Sets the page content.
1269 * @param html HTML markup to assign to the page.
1270 * @param options The navigation parameters.
1271 */
1272 setContent(html: string, options?: NavigationOptions): Promise<void>;
1273
1274 /**
1275 * This method fetches an element with `selector`, scrolls it into view if needed,
1276 * and then uses page.touchscreen to tap in the center of the element.
1277 * @param selector A `selector` to search for element to tap. If there are multiple elements
1278 * satisfying the selector, the first will be tapped.
1279 */
1280 tap(selector: string): Promise<void>;
1281
1282 /** Returns page's title. */
1283 title(): Promise<string>;
1284
1285 /**
1286 * Sends a `keydown`, `keypress/input`, and `keyup` event for each character in the text.
1287 * @param selector A selector of an element to type into. If there are multiple elements satisfying the selector, the first will be used.
1288 * @param text: A text to type into a focused element.
1289 * @param options: The typing parameters.
1290 */
1291 type(selector: string, text: string, options?: { delay: number }): Promise<void>;
1292
1293 /** Returns frame's url. */
1294 url(): string;
1295
1296 /**
1297 * @remarks
1298 *
1299 * This method behaves differently depending on the first parameter. If it's a
1300 * `string`, it will be treated as a `selector` or `xpath` (if the string
1301 * starts with `//`). This method then is a shortcut for
1302 * {@link Frame.waitForSelector} or {@link Frame.waitForXPath}.
1303 *
1304 * If the first argument is a function this method is a shortcut for
1305 * {@link Frame.waitForFunction}.
1306 *
1307 * If the first argument is a `number`, it's treated as a timeout in
1308 * milliseconds and the method returns a promise which resolves after the
1309 * timeout.
1310 *
1311 * @param selectorOrFunctionOrTimeout - a selector, predicate or timeout to
1312 * wait for.
1313 * @param options - optional waiting parameters.
1314 * @param args - arguments to pass to `pageFunction`.
1315 *
1316 * @deprecated Don't use this method directly. Instead use the more explicit
1317 * methods available: {@link Frame.waitForSelector},
1318 * {@link Frame.waitForXPath}, {@link Frame.waitForFunction} or
1319 * {@link Frame.waitForTimeout}.
1320 */
1321 waitFor(duration: number): Promise<void>;
1322 waitFor(selector: string, options: WaitForSelectorOptionsHidden): Promise<ElementHandle | null>;
1323 waitFor(selector: string, options?: WaitForSelectorOptions): Promise<ElementHandle>;
1324 waitFor(
1325 selector: EvaluateFn,
1326 options?: WaitForSelectorOptions,
1327 ...args: SerializableOrJSHandle[]
1328 ): Promise<JSHandle>;
1329
1330 /**
1331 * Allows waiting for various conditions.
1332 */
1333 waitForFunction(fn: EvaluateFn, options?: PageFnOptions, ...args: SerializableOrJSHandle[]): Promise<JSHandle>;
1334
1335 /**
1336 * Wait for the page navigation occur.
1337 * @param options The navigation parameters.
1338 */
1339 waitForNavigation(options?: NavigationOptions): Promise<Response>;
1340
1341 waitForSelector(selector: string, options?: WaitForSelectorOptions): Promise<ElementHandle>;
1342 waitForSelector(selector: string, options?: WaitForSelectorOptionsHidden): Promise<ElementHandle | null>;
1343
1344 /**
1345 * Causes your script to wait for the given number of milliseconds.
1346 *
1347 * @remarks
1348 * It's generally recommended to not wait for a number of seconds, but instead
1349 * use {@link Frame.waitForSelector}, {@link Frame.waitForXPath} or
1350 * {@link Frame.waitForFunction} to wait for exactly the conditions you want.
1351 *
1352 * @example
1353 *
1354 * Wait for 1 second:
1355 *
1356 * ```
1357 * await frame.waitForTimeout(1000);
1358 * ```
1359 *
1360 * @param milliseconds - the number of milliseconds to wait.
1361 */
1362 waitForTimeout(milliseconds: number): Promise<void>;
1363
1364 waitForXPath(xpath: string, options?: WaitForSelectorOptions): Promise<ElementHandle>;
1365}
1366
1367export interface Frame extends FrameBase {
1368 childFrames(): Frame[];
1369 /** Execution context associated with this frame. */
1370 executionContext(): Promise<ExecutionContext>;
1371 /** Returns `true` if the frame has been detached, or `false` otherwise. */
1372 isDetached(): boolean;
1373 /** Returns frame's name attribute as specified in the tag. */
1374 name(): string;
1375 /** Returns parent frame, if any. Detached frames and main frames return null. */
1376 parentFrame(): Frame | null;
1377}
1378
1379export interface PageEventObj {
1380 /** Emitted when the page closes. */
1381 close: undefined;
1382 /**
1383 * Emitted when JavaScript within the page calls one of console API methods, e.g. console.log or console.dir.
1384 * Also emitted if the page throws an error or a warning.
1385 */
1386 console: ConsoleMessage;
1387 /**
1388 * Emitted when a JavaScript dialog appears, such as alert, prompt, confirm or beforeunload.
1389 * Puppeteer can respond to the dialog via Dialog's accept or dismiss methods.
1390 */
1391 dialog: Dialog;
1392 /**
1393 * Emitted when the initial HTML document has been completely loaded and parsed,
1394 * without waiting for stylesheets, images, and subframes to finish loading.
1395 */
1396 domcontentloaded: never;
1397 /** Emitted when the page crashes. */
1398 error: Error;
1399 /** Emitted when a frame is attached. */
1400 frameattached: Frame;
1401 /** Emitted when a frame is detached. */
1402 framedetached: Frame;
1403 /** Emitted when a frame is navigated to a new url. */
1404 framenavigated: Frame;
1405 /** Emitted when the JavaScript load event is dispatched. */
1406 load: undefined;
1407 /**
1408 * Emitted when the JavaScript code makes a call to `console.timeStamp`.
1409 * For the list of metrics see `page.metrics`.
1410 */
1411 metrics: { title: string; metrics: Metrics };
1412 /** Emitted when an uncaught exception happens within the page. */
1413 pageerror: Error;
1414 /** Emitted when the page opens a new tab or window. */
1415 popup: Page;
1416 /**
1417 * Emitted when a page issues a request. The request object is read-only.
1418 * In order to intercept and mutate requests, see page.setRequestInterceptionEnabled.
1419 */
1420 request: Request;
1421 /** Emitted when a request fails, for example by timing out. */
1422 requestfailed: Request;
1423 /** Emitted when a request finishes successfully. */
1424 requestfinished: Request;
1425 /** Emitted when a response is received. */
1426 response: Response;
1427 /** Emitted when a dedicated WebWorker is spawned by the page. */
1428 workercreated: Worker;
1429 /** Emitted when a dedicated WebWorker is terminated. */
1430 workerdestroyed: Worker;
1431}
1432
1433export interface PageCloseOptions {
1434 /**
1435 * Whether to run the before unload page handlers.
1436 * @default false
1437 */
1438 runBeforeUnload?: boolean | undefined;
1439}
1440
1441export interface GeoOptions {
1442 /**
1443 * Latitude between -90 and 90.
1444 */
1445 latitude: number;
1446 /**
1447 * Longitude between -180 and 180.
1448 */
1449 longitude: number;
1450 /**
1451 * Non-negative accuracy value.
1452 */
1453 accuracy?: number | undefined;
1454}
1455
1456export type MediaType = 'screen' | 'print';
1457
1458export interface AXNode {
1459 /**
1460 * The role.
1461 */
1462 role: string;
1463 /**
1464 * A human readable name for the node.
1465 */
1466 name: string;
1467 /**
1468 * The current value of the node.
1469 */
1470 value: string | number;
1471 /**
1472 * An additional human readable description of the node.
1473 */
1474 description: string;
1475 /**
1476 * Keyboard shortcuts associated with this node.
1477 */
1478 keyshortcuts: string;
1479 /**
1480 * A human readable alternative to the role.
1481 */
1482 roledescription: string;
1483 /**
1484 * A description of the current value.
1485 */
1486 valuetext: string;
1487 /**
1488 * Whether the node is disabled.
1489 */
1490 disabled: boolean;
1491 /**
1492 * Whether the node is expanded or collapsed.
1493 */
1494 expanded: boolean;
1495 /**
1496 * Whether the node is focused.
1497 */
1498 focused: boolean;
1499 /**
1500 * Whether the node is modal.
1501 */
1502 modal: boolean;
1503 /**
1504 * Whether the node text input supports multiline.
1505 */
1506 multiline: boolean;
1507 /**
1508 * Whether more than one child can be selected.
1509 */
1510 multiselectable: boolean;
1511 /**
1512 * Whether the node is read only.
1513 */
1514 readonly: boolean;
1515 /**
1516 * Whether the node is required.
1517 */
1518 required: boolean;
1519 /**
1520 * Whether the node is selected in its parent node.
1521 */
1522 selected: boolean;
1523 /**
1524 * Whether the checkbox is checked, or "mixed".
1525 */
1526 checked: boolean | 'mixed';
1527 /**
1528 * Whether the toggle button is checked, or "mixed".
1529 */
1530 pressed: boolean | 'mixed';
1531 /**
1532 * The level of a heading.
1533 */
1534 level: number;
1535 /**
1536 * The minimum value in a node.
1537 */
1538 valuemin: number;
1539 /**
1540 * The maximum value in a node.
1541 */
1542 valuemax: number;
1543 /**
1544 * What kind of autocomplete is supported by a control.
1545 */
1546 autocomplete: string;
1547 /**
1548 * What kind of popup is currently being shown for a node.
1549 */
1550 haspopup: string;
1551 /**
1552 * Whether and in what way this node's value is invalid.
1553 */
1554 invalid: string;
1555 /**
1556 * Whether the node is oriented horizontally or vertically.
1557 */
1558 orientation: string;
1559 /**
1560 * Child nodes of this node, if any.
1561 */
1562 children: AXNode[];
1563}
1564
1565export interface SnapshopOptions {
1566 /**
1567 * Prune uninteresting nodes from the tree.
1568 * @default true
1569 */
1570 interestingOnly?: boolean | undefined;
1571 /**
1572 * The root DOM element for the snapshot.
1573 * @default document.body
1574 */
1575 root?: ElementHandle | undefined;
1576}
1577
1578/**
1579 * The Accessibility class provides methods for inspecting Chromium's accessibility tree.
1580 * The accessibility tree is used by assistive technology such as screen readers.
1581 * Accessibility is a very platform-specific thing. On different platforms,
1582 * there are different screen readers that might have wildly different output.
1583 * Blink - Chrome's rendering engine - has a concept of "accessibility tree",
1584 * which is than translated into different platform-specific APIs.
1585 * Accessibility namespace gives users access to the Blink Accessibility Tree.
1586 * Most of the accessibility tree gets filtered out when converting from Blink AX Tree to Platform-specific AX-Tree or
1587 * by screen readers themselves. By default, Puppeteer tries to approximate this filtering,
1588 * exposing only the "interesting" nodes of the tree.
1589 */
1590export interface Accessibility {
1591 snapshot(options?: SnapshopOptions): Promise<AXNode>;
1592}
1593
1594export interface MediaFeature {
1595 name: string;
1596 value: string;
1597}
1598
1599export interface FileChooser {
1600 /**
1601 * Accept the file chooser request with given paths.
1602 * If some of the filePaths are relative paths, then they are resolved relative to the current working directory.
1603 */
1604 accept(filePaths: string[]): Promise<void>;
1605 /** Closes the file chooser without selecting any files. */
1606 cancel(): Promise<void>;
1607 /** Whether file chooser allow for multiple file selection. */
1608 isMultiple(): boolean;
1609}
1610
1611/** Page provides methods to interact with a single tab in Chromium. One Browser instance might have multiple Page instances. */
1612export interface Page extends EventEmitter, FrameBase {
1613 /**
1614 * Adds the listener function to the end of the listeners array for the event named `eventName`.
1615 * No checks are made to see if the listener has already been added. Multiple calls passing the same combination of
1616 * `eventName` and listener will result in the listener being added, and called, multiple times.
1617 * @param event The name of the event.
1618 * @param handler The callback function.
1619 */
1620 on<K extends keyof PageEventObj>(eventName: K, handler: (e: PageEventObj[K], ...args: any[]) => void): this;
1621
1622 /**
1623 * Adds a one time listener function for the event named `eventName`.
1624 * The next time `eventName` is triggered, this listener is removed and then invoked.
1625 * @param event The name of the event.
1626 * @param handler The callback function.
1627 */
1628 once<K extends keyof PageEventObj>(eventName: K, handler: (e: PageEventObj[K], ...args: any[]) => void): this;
1629
1630 accessibility: Accessibility;
1631
1632 /**
1633 * Provide credentials for http authentication.
1634 * To disable authentication, pass `null`.
1635 */
1636 authenticate(credentials: AuthOptions | null): Promise<void>;
1637
1638 /** Brings page to front (activates tab). */
1639 bringToFront(): Promise<void>;
1640
1641 /** Get the browser the page belongs to. */
1642 browser(): Browser;
1643
1644 /** Get the browser context that the page belongs to. */
1645 browserContext(): BrowserContext;
1646
1647 /** Closes the current page. */
1648 close(options?: PageCloseOptions): Promise<void>;
1649
1650 /**
1651 * Gets the cookies.
1652 * If no URLs are specified, this method returns cookies for the current page URL.
1653 * If URLs are specified, only cookies for those URLs are returned.
1654 */
1655 cookies(...urls: string[]): Promise<Cookie[]>;
1656
1657 coverage: Coverage;
1658
1659 /**
1660 * Deletes the specified cookies.
1661 */
1662 deleteCookie(...cookies: DeleteCookie[]): Promise<void>;
1663
1664 /** Emulates given device metrics and user agent. This method is a shortcut for `setUserAgent` and `setViewport`. */
1665 emulate(options: EmulateOptions): Promise<void>;
1666
1667 /**
1668 * Emulates the idle state.
1669 * If no arguments set, clears idle state emulation.
1670 *
1671 * @example
1672 * ```js
1673 * // set idle emulation
1674 * await page.emulateIdleState({isUserActive: true, isScreenUnlocked: false});
1675 *
1676 * // do some checks here
1677 * ...
1678 *
1679 * // clear idle emulation
1680 * await page.emulateIdleState();
1681 * ```
1682 *
1683 * @param overrides Mock idle state. If not set, clears idle overrides
1684 * @param isUserActive Mock isUserActive
1685 * @param isScreenUnlocked Mock isScreenUnlocked
1686 */
1687 emulateIdleState(overrides?: { isUserActive: boolean; isScreenUnlocked: boolean }): Promise<void>;
1688
1689 /** Emulates the media. */
1690 emulateMediaType(mediaType: MediaType | null): Promise<void>;
1691
1692 /**
1693 * Given an array of media feature objects, emulates CSS media features on the page.
1694 * Passing null resets all.
1695 */
1696 emulateMediaFeatures(features: MediaFeature[] | null): Promise<void>;
1697
1698 /**
1699 * Changes the timezone of the page.
1700 * See ICU’s [metaZones.txt](https://cs.chromium.org/chromium/src/third_party/icu/source/data/misc/metaZones.txt?rcl=faee8bc70570192d82d2978a71e2a615788597d1) for a list of supported timezone IDs.
1701 * Passing null disables timezone emulation.
1702 */
1703 emulateTimezone(tz: string | null): Promise<void>;
1704
1705 /**
1706 * Adds a function which would be invoked in one of the following scenarios: whenever the page is navigated; whenever the child frame is attached or navigated.
1707 * The function is invoked after the document was created but before any of its scripts were run. This is useful to amend JavaScript environment, e.g. to seed Math.random.
1708 * @param fn The function to be evaluated in browser context.
1709 * @param args The arguments to pass to the `fn`.
1710 */
1711 evaluateOnNewDocument(fn: EvaluateFn, ...args: SerializableOrJSHandle[]): Promise<void>;
1712
1713 /**
1714 * The method adds a function called name on the page's `window` object.
1715 * When called, the function executes `puppeteerFunction` in node.js and returns a
1716 * Promise which resolves to the return value of `puppeteerFunction`.
1717 * @param name The name of the function on the window object.
1718 * @param fn Callback function which will be called in Puppeteer's context.
1719 */
1720 exposeFunction(name: string, puppeteerFunction: (...args: any[]) => any): Promise<void>;
1721
1722 /** An array of all frames attached to the page. */
1723 frames(): Frame[];
1724
1725 /**
1726 * Navigate to the previous page in history.
1727 * @param options The navigation parameters.
1728 */
1729 goBack(options?: NavigationOptions): Promise<Response | null>;
1730
1731 /**
1732 * Navigate to the next page in history.
1733 * @param options The navigation parameters.
1734 */
1735 goForward(options?: NavigationOptions): Promise<Response | null>;
1736
1737 /** Returns the virtual keyboard. */
1738 keyboard: Keyboard;
1739
1740 /** Indicates that the page has been closed. */
1741 isClosed(): boolean;
1742
1743 /**
1744 * @returns `true` if the page has JavaScript enabled, `false` otherwise.
1745 */
1746 isJavaScriptEnabled(): boolean;
1747
1748 /** Page is guaranteed to have a main frame which persists during navigation's. */
1749 mainFrame(): Frame;
1750
1751 /** Gets the page metrics. */
1752 metrics(): Promise<Metrics>;
1753
1754 /** Gets the virtual mouse. */
1755 mouse: Mouse;
1756
1757 /**
1758 * Generates a PDF of the page with `print` css media.
1759 * To generate a pdf with `screen` media, call `page.emulateMedia('screen')` before calling `page.pdf()`:
1760 * @param options The PDF parameters.
1761 */
1762 pdf(options?: PDFOptions): Promise<Buffer>;
1763
1764 /**
1765 * The method iterates JavaScript heap and finds all the objects with the given prototype.
1766 * @param prototypeHandle A handle to the object prototype.
1767 */
1768 queryObjects(prototypeHandle: JSHandle): Promise<JSHandle>;
1769
1770 /**
1771 * Reloads the current page.
1772 * @param options The navigation parameters.
1773 */
1774 reload(options?: NavigationOptions): Promise<Response>;
1775
1776 /**
1777 * Captures a screenshot of the page.
1778 * @param options The screenshot options.
1779 */
1780 screenshot(options?: Base64ScreenShotOptions): Promise<string>;
1781 screenshot(options?: BinaryScreenShotOptions): Promise<Buffer>;
1782 screenshot(options?: ScreenshotOptions): Promise<string | Buffer>;
1783
1784 /**
1785 * Toggles bypassing page's Content-Security-Policy.
1786 * NOTE CSP bypassing happens at the moment of CSP initialization rather then evaluation.
1787 * Usually this means that page.setBypassCSP should be called before navigating to the domain.
1788 * @param enabled sets bypassing of page's Content-Security-Policy.
1789 */
1790 setBypassCSP(enabled: boolean): Promise<void>;
1791
1792 /**
1793 * Determines whether cache is enabled on the page.
1794 * @param [enabled=true] Whether or not to enable cache on the page.
1795 */
1796 setCacheEnabled(enabled?: boolean): Promise<void>;
1797
1798 /**
1799 * Sets the cookies on the page.
1800 * @param cookies The cookies to set.
1801 */
1802 setCookie(...cookies: SetCookie[]): Promise<void>;
1803
1804 /**
1805 * This setting will change the default maximum navigation time of 30 seconds for the following methods:
1806 * - `page.goto`
1807 * - `page.goBack`
1808 * - `page.goForward`
1809 * - `page.reload`
1810 * - `page.waitForNavigation`
1811 */
1812 setDefaultNavigationTimeout(timeout: number): void;
1813
1814 /**
1815 * This setting will change the default maximum time for the following methods and related shortcuts:
1816 * - `page.goBack`
1817 * - `page.goForward`
1818 * - `page.goto`
1819 * - `page.reload`
1820 * - `page.setContent`
1821 * - `page.waitFor`
1822 * - `page.waitForFunction`
1823 * - `page.waitForNavigation`
1824 * - `page.waitForRequest`
1825 * - `page.waitForResponse`
1826 * - `page.waitForSelector`
1827 * - `page.waitForXPath`
1828 *
1829 * NOTE page.setDefaultNavigationTimeout takes priority over page.setDefaultTimeout
1830 */
1831 setDefaultTimeout(timeout: number): void;
1832
1833 /**
1834 * The extra HTTP headers will be sent with every request the page initiates.
1835 * @param headers An object containing additional http headers to be sent with every request. All header values must be strings.
1836 */
1837 setExtraHTTPHeaders(headers: Headers): Promise<void>;
1838
1839 /**
1840 * Sets the page's geolocation.
1841 */
1842 setGeolocation(options: GeoOptions): Promise<void>;
1843
1844 /**
1845 * Determines whether JavaScript is enabled on the page.
1846 * @param enable Whether or not to enable JavaScript on the page.
1847 */
1848 setJavaScriptEnabled(enabled: boolean): Promise<void>;
1849
1850 /**
1851 * Determines whether the offline mode is enabled.
1852 * @param enabled When `true`, enables the offline mode for the page.
1853 */
1854 setOfflineMode(enabled: boolean): Promise<void>;
1855
1856 /**
1857 * Determines whether the request interception is enabled.
1858 * @param enabled When `true` the methods `request.abort`, `request.continue` and `request.respond` must be used.
1859 */
1860 setRequestInterception(enabled: boolean): Promise<void>;
1861
1862 /**
1863 * Specifies the User-Agent used in this page.
1864 * @param userAgent The user-agent to be used in the page.
1865 */
1866 setUserAgent(userAgent: string): Promise<void>;
1867 /**
1868 * Sets the viewport of the page.
1869 * @param viewport The viewport parameters.
1870 */
1871 setViewport(viewport: Viewport): Promise<void>;
1872
1873 /** @returns The target this page was created from */
1874 target(): Target;
1875
1876 /** Returns the page's title. */
1877 title(): Promise<string>;
1878
1879 /** Returns the virtual touchscreen object. */
1880 touchscreen: Touchscreen;
1881
1882 /** Returns the tracing object. */
1883 tracing: Tracing;
1884
1885 /**
1886 * The page's URL. This is a shortcut for `page.mainFrame().url()`
1887 */
1888 url(): string;
1889
1890 /** Gets the page viewport. */
1891 viewport(): Viewport;
1892
1893 waitForRequest(urlOrPredicate: string | ((req: Request) => boolean), options?: Timeoutable): Promise<Request>;
1894
1895 waitForResponse(urlOrPredicate: string | ((res: Response) => boolean), options?: Timeoutable): Promise<Response>;
1896
1897 /**
1898 * In non-headless Chromium, this method results in the native file picker dialog not showing up for the user.
1899 * This method is typically coupled with an action that triggers file choosing.
1900 * This must be called before the file chooser is launched. It will not return a currently active file chooser.
1901 */
1902 waitForFileChooser(options?: Timeoutable): Promise<FileChooser>;
1903
1904 /** This method returns all of the dedicated WebWorkers associated with the page. */
1905 workers(): Worker[];
1906}
1907
1908export interface TargetAwaiter {
1909 waitForTarget(predicate: (target: Target) => boolean, options?: Timeoutable): Promise<Target>;
1910}
1911
1912/** A Browser is created when Puppeteer connects to a Chromium instance, either through puppeteer.launch or puppeteer.connect. */
1913export interface Browser extends EventEmitter, TargetAwaiter {
1914 /**
1915 * Adds the listener function to the end of the listeners array for the event named `eventName`.
1916 * No checks are made to see if the listener has already been added. Multiple calls passing the same combination of
1917 * `eventName` and listener will result in the listener being added, and called, multiple times.
1918 * @param event The name of the event.
1919 * @param handler The callback function.
1920 */
1921 on<K extends keyof BrowserEventObj>(eventName: K, handler: (e: BrowserEventObj[K], ...args: any[]) => void): this;
1922
1923 /**
1924 * Adds a one time listener function for the event named `eventName`.
1925 * The next time `eventName` is triggered, this listener is removed and then invoked.
1926 * @param event The name of the event.
1927 * @param handler The callback function.
1928 */
1929 once<K extends keyof BrowserEventObj>(eventName: K, handler: (e: BrowserEventObj[K], ...args: any[]) => void): this;
1930
1931 /**
1932 * Returns an array of all open browser contexts.
1933 * In a newly created browser, this will return a single instance of BrowserContext.
1934 */
1935 browserContexts(): BrowserContext[];
1936
1937 /**
1938 * Closes browser with all the pages (if any were opened).
1939 * The browser object itself is considered to be disposed and can not be used anymore.
1940 */
1941 close(): Promise<void>;
1942
1943 /**
1944 * Creates a new incognito browser context.
1945 * This won't share cookies/cache with other browser contexts.
1946 */
1947 createIncognitoBrowserContext(): Promise<BrowserContext>;
1948
1949 /**
1950 * Disconnects Puppeteer from the browser, but leaves the Chromium process running.
1951 * After calling `disconnect`, the browser object is considered disposed and cannot be used anymore.
1952 */
1953 disconnect(): void;
1954
1955 /** Indicates that the browser is connected. */
1956 isConnected(): boolean;
1957
1958 /**
1959 * Returns the default browser context.
1960 * The default browser context can not be closed.
1961 */
1962 defaultBrowserContext(): BrowserContext;
1963
1964 /** Promise which resolves to a new Page object. */
1965 newPage(): Promise<Page>;
1966
1967 /** Promise which resolves to an array of all open pages. */
1968 pages(): Promise<Page[]>;
1969
1970 /** Spawned browser process. Returns `null` if the browser instance was created with `puppeteer.connect` method */
1971 process(): ChildProcess;
1972
1973 /** A target associated with the browser. */
1974 target(): Target;
1975
1976 /** Promise which resolves to an array of all active targets. */
1977 targets(): Promise<Target[]>;
1978
1979 /**
1980 * Promise which resolves to the browser's original user agent.
1981 * **NOTE** Pages can override browser user agent with `page.setUserAgent`.
1982 */
1983 userAgent(): Promise<string>;
1984
1985 /** For headless Chromium, this is similar to HeadlessChrome/61.0.3153.0. For non-headless, this is similar to Chrome/61.0.3153.0. */
1986 version(): Promise<string>;
1987
1988 /** Browser websocket endpoint which can be used as an argument to puppeteer.connect. The format is ws://${host}:${port}/devtools/browser/<id> */
1989 wsEndpoint(): string;
1990}
1991
1992export interface BrowserEventObj {
1993 /** Emitted when puppeteer gets disconnected from the browser instance. */
1994 disconnected: undefined;
1995
1996 /** Emitted when the url of a target changes. */
1997 targetchanged: Target;
1998
1999 /** Emitted when a target is created, for example when a new page is opened by `window.open` or `browser.newPage`. */
2000 targetcreated: Target;
2001
2002 /** Emitted when a target is destroyed, for example when a page is closed. */
2003 targetdestroyed: Target;
2004}
2005
2006export type Permission =
2007 | 'geolocation'
2008 | 'midi'
2009 | 'midi-sysex'
2010 | 'notifications'
2011 | 'push'
2012 | 'camera'
2013 | 'microphone'
2014 | 'background-sync'
2015 | 'ambient-light-sensor'
2016 | 'accelerometer'
2017 | 'gyroscope'
2018 | 'magnetometer'
2019 | 'accessibility-events'
2020 | 'clipboard-read'
2021 | 'clipboard-write'
2022 | 'payment-handler';
2023
2024/**
2025 * BrowserContexts provide a way to operate multiple independent browser sessions.
2026 * When a browser is launched, it has a single BrowserContext used by default.
2027 * The method `browser.newPage()` creates a page in the default browser context.
2028 */
2029export interface BrowserContext extends EventEmitter, TargetAwaiter {
2030 /**
2031 * Adds the listener function to the end of the listeners array for the event named `eventName`.
2032 * No checks are made to see if the listener has already been added. Multiple calls passing the same combination of
2033 * `eventName` and listener will result in the listener being added, and called, multiple times.
2034 * @param event The name of the event.
2035 * @param handler The callback function.
2036 */
2037 on<K extends keyof BrowserContextEventObj>(
2038 eventName: K,
2039 handler: (e: BrowserContextEventObj[K], ...args: any[]) => void,
2040 ): this;
2041
2042 /**
2043 * Adds a one time listener function for the event named `eventName`.
2044 * The next time `eventName` is triggered, this listener is removed and then invoked.
2045 * @param event The name of the event.
2046 * @param handler The callback function.
2047 */
2048 once<K extends keyof BrowserContextEventObj>(
2049 eventName: K,
2050 handler: (e: BrowserContextEventObj[K], ...args: any[]) => void,
2051 ): this;
2052
2053 /** The browser this browser context belongs to. */
2054 browser(): Browser;
2055
2056 /**
2057 * Clears all permission overrides for the browser context.
2058 */
2059 clearPermissionOverrides(): Promise<void>;
2060
2061 /** Closes the browser context. All the targets that belong to the browser context will be closed. */
2062 close(): Promise<void>;
2063
2064 /**
2065 * Returns whether BrowserContext is incognito.
2066 * The default browser context is the only non-incognito browser context.
2067 */
2068 isIncognito(): boolean;
2069
2070 /** Creates a new page in the browser context. */
2071 newPage(): Promise<Page>;
2072
2073 /**
2074 *
2075 * @param origin The origin to grant permissions to, e.g. "https://example.com".
2076 * @param permissions An array of permissions to grant.
2077 * All permissions that are not listed here will be automatically denied.
2078 */
2079 overridePermissions(origin: string, permissions: Permission[]): Promise<void>;
2080
2081 /** Promise which resolves to an array of all open pages. */
2082 pages(): Promise<Page[]>;
2083
2084 /** An array of all active targets inside the browser context. */
2085 targets(): Target[];
2086}
2087
2088export interface BrowserContextEventObj {
2089 /** Emitted when the url of a target inside the browser context changes. */
2090 targetchanged: Target;
2091
2092 /** Emitted when a target is created, for example when a new page is opened by `window.open` or `browserContext.newPage`. */
2093 targetcreated: Target;
2094
2095 /** Emitted when a target is destroyed, for example when a page is closed. */
2096 targetdestroyed: Target;
2097}
2098
2099export type TargetType = 'page' | 'background_page' | 'shared_worker' | 'service_worker' | 'browser' | 'other';
2100
2101export interface Target {
2102 /** Get the browser the target belongs to. */
2103 browser(): Browser;
2104
2105 /** The browser context the target belongs to. */
2106 browserContext(): BrowserContext;
2107
2108 /** Creates a Chrome Devtools Protocol session attached to the target. */
2109 createCDPSession(): Promise<CDPSession>;
2110
2111 /** Get the target that opened this target. Top-level targets return `null`. */
2112 opener(): Target | null;
2113
2114 /** Returns the target `Page` or a `null` if the type of the page is not "page". */
2115 page(): Promise<Page>;
2116
2117 /** Identifies what kind of target this is. */
2118 type(): TargetType;
2119
2120 /** Returns the target URL. */
2121 url(): string;
2122
2123 /** If the target is not of type `service_worker` or `shared_worker`, resolves `null`. */
2124 worker(): Promise<Worker | null>;
2125}
2126
2127export interface LaunchOptions extends ChromeArgOptions, BrowserOptions, Timeoutable {
2128 /**
2129 * Which browser to launch.
2130 * At this time, this is either `chrome` or `firefox`. See also `PUPPETEER_PRODUCT`.
2131 * @default 'chrome'
2132 */
2133 product?: Product | undefined;
2134 /**
2135 * Path to a Chromium executable to run instead of bundled Chromium. If
2136 * executablePath is a relative path, then it is resolved relative to current
2137 * working directory.
2138 */
2139 executablePath?: string | undefined;
2140 /**
2141 * Do not use `puppeteer.defaultArgs()` for launching Chromium.
2142 * @default false
2143 */
2144 ignoreDefaultArgs?: boolean | string[] | undefined;
2145 /**
2146 * Close chrome process on Ctrl-C.
2147 * @default true
2148 */
2149 handleSIGINT?: boolean | undefined;
2150 /**
2151 * Close chrome process on SIGTERM.
2152 * @default true
2153 */
2154 handleSIGTERM?: boolean | undefined;
2155 /**
2156 * Close chrome process on SIGHUP.
2157 * @default true
2158 */
2159 handleSIGHUP?: boolean | undefined;
2160 /**
2161 * Whether to pipe browser process stdout and stderr into process.stdout and
2162 * process.stderr.
2163 * @default false
2164 */
2165 dumpio?: boolean | undefined;
2166 /**
2167 * Specify environment variables that will be visible to Chromium.
2168 * @default `process.env`.
2169 */
2170 env?: {
2171 [key: string]: string | boolean | number;
2172 } | undefined;
2173 /**
2174 * Connects to the browser over a pipe instead of a WebSocket.
2175 * @default false
2176 */
2177 pipe?: boolean | undefined;
2178}
2179
2180export interface ChromeArgOptions {
2181 /**
2182 * Whether to run browser in headless mode.
2183 * @default true unless the devtools option is true.
2184 */
2185 headless?: boolean | undefined;
2186 /**
2187 * Additional arguments to pass to the browser instance.
2188 * The list of Chromium flags can be found here: https://peter.sh/experiments/chromium-command-line-switches
2189 */
2190 args?: string[] | undefined;
2191 /**
2192 * Path to a User Data Directory.
2193 */
2194 userDataDir?: string | undefined;
2195 /**
2196 * Whether to auto-open a DevTools panel for each tab.
2197 * If this option is true, the headless option will be set false.
2198 */
2199 devtools?: boolean | undefined;
2200}
2201
2202export interface BrowserOptions {
2203 /**
2204 * Whether to ignore HTTPS errors during navigation.
2205 * @default false
2206 */
2207 ignoreHTTPSErrors?: boolean | undefined;
2208 /**
2209 * Sets a consistent viewport for each page. Defaults to an 800x600 viewport. null disables the default viewport.
2210 */
2211 defaultViewport?: {
2212 /**
2213 * page width in pixels.
2214 */
2215 width?: number | undefined;
2216 /**
2217 * page height in pixels.
2218 */
2219 height?: number | undefined;
2220 /**
2221 * Specify device scale factor (can be thought of as dpr).
2222 * @default 1
2223 */
2224 deviceScaleFactor?: number | undefined;
2225 /**
2226 * Whether the meta viewport tag is taken into account.
2227 * @default false
2228 */
2229 isMobile?: boolean | undefined;
2230 /**
2231 * Specifies if viewport supports touch events.
2232 * @default false
2233 */
2234 hasTouch?: boolean | undefined;
2235 /**
2236 * Specifies if viewport is in landscape mode.
2237 * @default false
2238 */
2239 isLandscape?: boolean | undefined;
2240 } | null | undefined;
2241 /**
2242 * Slows down Puppeteer operations by the specified amount of milliseconds.
2243 * Useful so that you can see what is going on.
2244 */
2245 slowMo?: number | undefined;
2246}
2247
2248export interface ConnectOptions extends BrowserOptions {
2249 /**
2250 * A browser url to connect to, in format `http://${host}:${port}`.
2251 * Use interchangeably with browserWSEndpoint to let Puppeteer fetch it from metadata endpoint.
2252 */
2253 browserURL?: string | undefined;
2254
2255 /** A browser websocket endpoint to connect to. */
2256 browserWSEndpoint?: string | undefined;
2257
2258 /**
2259 * **Experimental** Specify a custom transport object for Puppeteer to use.
2260 */
2261 transport?: ConnectionTransport | undefined;
2262}
2263
2264export interface ConnectionTransport {
2265 send(message: string): void;
2266 close(): void;
2267 onmessage?(message: string): void;
2268 onclose?(): void;
2269}
2270
2271export interface CDPSession extends EventEmitter {
2272 /**
2273 * Detaches session from target. Once detached, session won't emit any events and can't be used
2274 * to send messages.
2275 */
2276 detach(): Promise<void>;
2277
2278 /**
2279 * @param method Protocol method name
2280 */
2281 send(method: string, params?: object): Promise<object>;
2282}
2283
2284export interface Coverage {
2285 startCSSCoverage(options?: StartCoverageOptions): Promise<void>;
2286 startJSCoverage(options?: StartCoverageOptions): Promise<void>;
2287 stopCSSCoverage(): Promise<CoverageEntry[]>;
2288 stopJSCoverage(): Promise<CoverageEntry[]>;
2289}
2290
2291export interface StartCoverageOptions {
2292 /**
2293 * Whether to reset coverage on every navigation.
2294 * @default true
2295 */
2296 resetOnNavigation?: boolean | undefined;
2297 /**
2298 * Whether anonymous scripts generated by the page should be reported.
2299 * @default false
2300 */
2301 reportAnonymousScripts?: boolean | undefined;
2302}
2303
2304export interface CoverageEntry {
2305 url: string;
2306 text: string;
2307 ranges: Array<{ start: number; end: number }>;
2308}
2309
2310/** BrowserFetcher can download and manage different versions of Chromium. */
2311export interface BrowserFetcher {
2312 /** The method initiates a HEAD request to check if the revision is available. */
2313 canDownload(revision: string): Promise<boolean>;
2314 /** The method initiates a GET request to download the revision from the host. */
2315 download(
2316 revision: string,
2317 progressCallback?: (downloadBytes: number, totalBytes: number) => void,
2318 ): Promise<RevisionInfo>;
2319 localRevisions(): Promise<string[]>;
2320 platform(): Platform;
2321 product(): Product;
2322 remove(revision: string): Promise<void>;
2323 revisionInfo(revision: string): RevisionInfo;
2324}
2325
2326export interface RevisionInfo {
2327 /** The revision the info was created from */
2328 revision: string;
2329 /** Path to the extracted revision folder */
2330 folderPath: string;
2331 /** Path to the revision executable */
2332 executablePath: string;
2333 /** URL this revision can be downloaded from */
2334 url: string;
2335 /** whether the revision is locally available on disk */
2336 local: boolean;
2337 product: Product;
2338}
2339
2340export interface FetcherOptions {
2341 /** A download host to be used. Defaults to `https://storage.googleapis.com`. */
2342 host?: string | undefined;
2343 /** A path for the downloads folder. Defaults to `<root>/.local-chromium`, where `<root>` is puppeteer's package root. */
2344 path?: string | undefined;
2345 /** Possible values are: `mac`, `win32`, `win64`, `linux`. Defaults to the current platform. */
2346 platform?: Platform | undefined;
2347 /**
2348 * @default 'chrome'
2349 */
2350 product?: Product | undefined;
2351}
2352
2353type EventType = string | symbol;
2354type Handler<T = any> = (event?: T) => void;
2355
2356export interface EventEmitter {
2357 on(event: EventType, handler: Handler): EventEmitter;
2358 off(event: EventType, handler: Handler): EventEmitter;
2359 addListener(event: EventType, handler: Handler): EventEmitter;
2360 removeListener(event: EventType, handler: Handler): EventEmitter;
2361 emit(event: EventType, eventData?: any): boolean;
2362 once(event: EventType, handler: Handler): EventEmitter;
2363 listenerCount(event: string): number;
2364 removeAllListeners(event?: EventType): EventEmitter;
2365}
2366
2367/**
2368 * Contains two functions `queryOne` and `queryAll` that can
2369 * be {@link Puppeteer.registerCustomQueryHandler | registered}
2370 * as alternative querying strategies. The functions `queryOne` and `queryAll`
2371 * are executed in the page context. `queryOne` should take an `Element` and a
2372 * selector string as argument and return a single `Element` or `null` if no
2373 * element is found. `queryAll` takes the same arguments but should instead
2374 * return a `NodeListOf<Element>` or `Array<Element>` with all the elements
2375 * that match the given query selector.
2376 */
2377export interface CustomQueryHandler {
2378 queryOne?: ((element: Element | Document, selector: string) => Element | null) | undefined;
2379 queryAll?: ((element: Element | Document, selector: string) => Element[] | NodeListOf<Element>) | undefined;
2380}
2381
2382/** Attaches Puppeteer to an existing Chromium instance */
2383export function connect(options?: ConnectOptions): Promise<Browser>;
2384/** The default flags that Chromium will be launched with */
2385export function defaultArgs(options?: ChromeArgOptions): string[];
2386/** Path where Puppeteer expects to find bundled Chromium */
2387export function executablePath(): string;
2388/** The method launches a browser instance with given arguments. The browser will be closed when the parent node.js process is closed. */
2389export function launch(options?: LaunchOptions): Promise<Browser>;
2390/** This methods attaches Puppeteer to an existing Chromium instance. */
2391export function createBrowserFetcher(options?: FetcherOptions): BrowserFetcher;
2392
2393/**
2394 * The name of the browser that is under automation (`"chrome"` or `"firefox"`)
2395 *
2396 * The product is set by the `PUPPETEER_PRODUCT` environment variable or the `product`
2397 * option in `puppeteer.launch([options])` and defaults to `chrome`.
2398 * Firefox support is experimental.
2399 */
2400export const product: Product;
2401
2402/**
2403 * Registers a {@link CustomQueryHandler | custom query handler}. After
2404 * registration, the handler can be used everywhere where a selector is
2405 * expected by prepending the selection string with `<name>/`. The name is
2406 * only allowed to consist of lower- and upper case latin letters.
2407 * @example
2408 * ```
2409 * puppeteer.registerCustomQueryHandler('text', { … });
2410 * const aHandle = await page.$('text/…');
2411 * ```
2412 * @param name - The name that the custom query handler will be registered under.
2413 * @param queryHandler - The {@link CustomQueryHandler | custom query handler} to
2414 * register.
2415 */
2416export function registerCustomQueryHandler(name: string, queryHandler: CustomQueryHandler): void;
2417/**
2418 * @param name - The name of the query handler to unregistered.
2419 */
2420export function unregisterCustomQueryHandler(name: string): void;
2421