1 | /**
|
2 | * These global declarations exist so puppeteer can work without the need to use `"dom"`
|
3 | * types.
|
4 | *
|
5 | * To get full type information for these interfaces, add `"types": "dom"`in your
|
6 | * `tsconfig.json` file.
|
7 | */
|
8 | declare global {
|
9 | interface Document {
|
10 | }
|
11 | interface Element {
|
12 | }
|
13 | interface NodeListOf<TNode> {
|
14 | }
|
15 | }
|
16 | export {};
|
17 | //# sourceMappingURL=global.d.ts.map
|
18 | /// <reference types="node" />
|
19 | import { ChildProcess } from 'child_process';
|
20 | import { Protocol } from 'devtools-protocol';
|
21 | import { ProtocolMapping } from 'devtools-protocol/types/protocol-mapping.js';
|
22 | import type { Readable } from 'stream';
|
23 |
|
24 | /**
|
25 | * The Accessibility class provides methods for inspecting Chromium's
|
26 | * accessibility tree. The accessibility tree is used by assistive technology
|
27 | * such as {@link https://en.wikipedia.org/wiki/Screen_reader | screen readers} or
|
28 | * {@link https://en.wikipedia.org/wiki/Switch_access | switches}.
|
29 | *
|
30 | * @remarks
|
31 | *
|
32 | * Accessibility is a very platform-specific thing. On different platforms,
|
33 | * there are different screen readers that might have wildly different output.
|
34 | *
|
35 | * Blink - Chrome's rendering engine - has a concept of "accessibility tree",
|
36 | * which is then translated into different platform-specific APIs. Accessibility
|
37 | * namespace gives users access to the Blink Accessibility Tree.
|
38 | *
|
39 | * Most of the accessibility tree gets filtered out when converting from Blink
|
40 | * AX Tree to Platform-specific AX-Tree or by assistive technologies themselves.
|
41 | * By default, Puppeteer tries to approximate this filtering, exposing only
|
42 | * the "interesting" nodes of the tree.
|
43 | *
|
44 | * @public
|
45 | */
|
46 | export declare class Accessibility {
|
47 | private _client;
|
48 | /**
|
49 | * @internal
|
50 | */
|
51 | constructor(client: CDPSession);
|
52 | /**
|
53 | * Captures the current state of the accessibility tree.
|
54 | * The returned object represents the root accessible node of the page.
|
55 | *
|
56 | * @remarks
|
57 | *
|
58 | * **NOTE** The Chromium accessibility tree contains nodes that go unused on
|
59 | * most platforms and by most screen readers. Puppeteer will discard them as
|
60 | * well for an easier to process tree, unless `interestingOnly` is set to
|
61 | * `false`.
|
62 | *
|
63 | * @example
|
64 | * An example of dumping the entire accessibility tree:
|
65 | * ```js
|
66 | * const snapshot = await page.accessibility.snapshot();
|
67 | * console.log(snapshot);
|
68 | * ```
|
69 | *
|
70 | * @example
|
71 | * An example of logging the focused node's name:
|
72 | * ```js
|
73 | * const snapshot = await page.accessibility.snapshot();
|
74 | * const node = findFocusedNode(snapshot);
|
75 | * console.log(node && node.name);
|
76 | *
|
77 | * function findFocusedNode(node) {
|
78 | * if (node.focused)
|
79 | * return node;
|
80 | * for (const child of node.children || []) {
|
81 | * const foundNode = findFocusedNode(child);
|
82 | * return foundNode;
|
83 | * }
|
84 | * return null;
|
85 | * }
|
86 | * ```
|
87 | *
|
88 | * @returns An AXNode object representing the snapshot.
|
89 | *
|
90 | */
|
91 | snapshot(options?: SnapshotOptions): Promise<SerializedAXNode>;
|
92 | private serializeTree;
|
93 | private collectInterestingNodes;
|
94 | }
|
95 |
|
96 | /**
|
97 | * @public
|
98 | */
|
99 | export declare type ActionResult = 'continue' | 'abort' | 'respond';
|
100 |
|
101 | /**
|
102 | * @public
|
103 | */
|
104 | export declare interface BoundingBox {
|
105 | /**
|
106 | * the x coordinate of the element in pixels.
|
107 | */
|
108 | x: number;
|
109 | /**
|
110 | * the y coordinate of the element in pixels.
|
111 | */
|
112 | y: number;
|
113 | /**
|
114 | * the width of the element in pixels.
|
115 | */
|
116 | width: number;
|
117 | /**
|
118 | * the height of the element in pixels.
|
119 | */
|
120 | height: number;
|
121 | }
|
122 |
|
123 | /**
|
124 | * @public
|
125 | */
|
126 | export declare interface BoxModel {
|
127 | content: Array<{
|
128 | x: number;
|
129 | y: number;
|
130 | }>;
|
131 | padding: Array<{
|
132 | x: number;
|
133 | y: number;
|
134 | }>;
|
135 | border: Array<{
|
136 | x: number;
|
137 | y: number;
|
138 | }>;
|
139 | margin: Array<{
|
140 | x: number;
|
141 | y: number;
|
142 | }>;
|
143 | width: number;
|
144 | height: number;
|
145 | }
|
146 |
|
147 | /**
|
148 | * A Browser is created when Puppeteer connects to a Chromium instance, either through
|
149 | * {@link PuppeteerNode.launch} or {@link Puppeteer.connect}.
|
150 | *
|
151 | * @remarks
|
152 | *
|
153 | * The Browser class extends from Puppeteer's {@link EventEmitter} class and will
|
154 | * emit various events which are documented in the {@link BrowserEmittedEvents} enum.
|
155 | *
|
156 | * @example
|
157 | *
|
158 | * An example of using a {@link Browser} to create a {@link Page}:
|
159 | * ```js
|
160 | * const puppeteer = require('puppeteer');
|
161 | *
|
162 | * (async () => {
|
163 | * const browser = await puppeteer.launch();
|
164 | * const page = await browser.newPage();
|
165 | * await page.goto('https://example.com');
|
166 | * await browser.close();
|
167 | * })();
|
168 | * ```
|
169 | *
|
170 | * @example
|
171 | *
|
172 | * An example of disconnecting from and reconnecting to a {@link Browser}:
|
173 | * ```js
|
174 | * const puppeteer = require('puppeteer');
|
175 | *
|
176 | * (async () => {
|
177 | * const browser = await puppeteer.launch();
|
178 | * // Store the endpoint to be able to reconnect to Chromium
|
179 | * const browserWSEndpoint = browser.wsEndpoint();
|
180 | * // Disconnect puppeteer from Chromium
|
181 | * browser.disconnect();
|
182 | *
|
183 | * // Use the endpoint to reestablish a connection
|
184 | * const browser2 = await puppeteer.connect({browserWSEndpoint});
|
185 | * // Close Chromium
|
186 | * await browser2.close();
|
187 | * })();
|
188 | * ```
|
189 | *
|
190 | * @public
|
191 | */
|
192 | export declare class Browser extends EventEmitter {
|
193 | /**
|
194 | * @internal
|
195 | */
|
196 | static create(connection: Connection, contextIds: string[], ignoreHTTPSErrors: boolean, defaultViewport?: Viewport | null, process?: ChildProcess, closeCallback?: BrowserCloseCallback, targetFilterCallback?: TargetFilterCallback): Promise<Browser>;
|
197 | private _ignoreHTTPSErrors;
|
198 | private _defaultViewport?;
|
199 | private _process?;
|
200 | private _connection;
|
201 | private _closeCallback;
|
202 | private _targetFilterCallback;
|
203 | private _defaultContext;
|
204 | private _contexts;
|
205 | /**
|
206 | * @internal
|
207 | * Used in Target.ts directly so cannot be marked private.
|
208 | */
|
209 | _targets: Map<string, Target>;
|
210 | /**
|
211 | * @internal
|
212 | */
|
213 | constructor(connection: Connection, contextIds: string[], ignoreHTTPSErrors: boolean, defaultViewport?: Viewport | null, process?: ChildProcess, closeCallback?: BrowserCloseCallback, targetFilterCallback?: TargetFilterCallback);
|
214 | /**
|
215 | * The spawned browser process. Returns `null` if the browser instance was created with
|
216 | * {@link Puppeteer.connect}.
|
217 | */
|
218 | process(): ChildProcess | null;
|
219 | /**
|
220 | * Creates a new incognito browser context. This won't share cookies/cache with other
|
221 | * browser contexts.
|
222 | *
|
223 | * @example
|
224 | * ```js
|
225 | * (async () => {
|
226 | * const browser = await puppeteer.launch();
|
227 | * // Create a new incognito browser context.
|
228 | * const context = await browser.createIncognitoBrowserContext();
|
229 | * // Create a new page in a pristine context.
|
230 | * const page = await context.newPage();
|
231 | * // Do stuff
|
232 | * await page.goto('https://example.com');
|
233 | * })();
|
234 | * ```
|
235 | */
|
236 | createIncognitoBrowserContext(options?: BrowserContextOptions): Promise<BrowserContext>;
|
237 | /**
|
238 | * Returns an array of all open browser contexts. In a newly created browser, this will
|
239 | * return a single instance of {@link BrowserContext}.
|
240 | */
|
241 | browserContexts(): BrowserContext[];
|
242 | /**
|
243 | * Returns the default browser context. The default browser context cannot be closed.
|
244 | */
|
245 | defaultBrowserContext(): BrowserContext;
|
246 | /**
|
247 | * @internal
|
248 | * Used by BrowserContext directly so cannot be marked private.
|
249 | */
|
250 | _disposeContext(contextId?: string): Promise<void>;
|
251 | private _targetCreated;
|
252 | private _targetDestroyed;
|
253 | private _targetInfoChanged;
|
254 | /**
|
255 | * The browser websocket endpoint which can be used as an argument to
|
256 | * {@link Puppeteer.connect}.
|
257 | *
|
258 | * @returns The Browser websocket url.
|
259 | *
|
260 | * @remarks
|
261 | *
|
262 | * The format is `ws://${host}:${port}/devtools/browser/<id>`.
|
263 | *
|
264 | * You can find the `webSocketDebuggerUrl` from `http://${host}:${port}/json/version`.
|
265 | * Learn more about the
|
266 | * {@link https://chromedevtools.github.io/devtools-protocol | devtools protocol} and
|
267 | * the {@link
|
268 | * https://chromedevtools.github.io/devtools-protocol/#how-do-i-access-the-browser-target
|
269 | * | browser endpoint}.
|
270 | */
|
271 | wsEndpoint(): string;
|
272 | /**
|
273 | * Promise which resolves to a new {@link Page} object. The Page is created in
|
274 | * a default browser context.
|
275 | */
|
276 | newPage(): Promise<Page>;
|
277 | /**
|
278 | * @internal
|
279 | * Used by BrowserContext directly so cannot be marked private.
|
280 | */
|
281 | _createPageInContext(contextId?: string): Promise<Page>;
|
282 | /**
|
283 | * All active targets inside the Browser. In case of multiple browser contexts, returns
|
284 | * an array with all the targets in all browser contexts.
|
285 | */
|
286 | targets(): Target[];
|
287 | /**
|
288 | * The target associated with the browser.
|
289 | */
|
290 | target(): Target;
|
291 | /**
|
292 | * Searches for a target in all browser contexts.
|
293 | *
|
294 | * @param predicate - A function to be run for every target.
|
295 | * @returns The first target found that matches the `predicate` function.
|
296 | *
|
297 | * @example
|
298 | *
|
299 | * An example of finding a target for a page opened via `window.open`:
|
300 | * ```js
|
301 | * await page.evaluate(() => window.open('https://www.example.com/'));
|
302 | * const newWindowTarget = await browser.waitForTarget(target => target.url() === 'https://www.example.com/');
|
303 | * ```
|
304 | */
|
305 | waitForTarget(predicate: (x: Target) => boolean, options?: WaitForTargetOptions): Promise<Target>;
|
306 | /**
|
307 | * An array of all open pages inside the Browser.
|
308 | *
|
309 | * @remarks
|
310 | *
|
311 | * In case of multiple browser contexts, returns an array with all the pages in all
|
312 | * browser contexts. Non-visible pages, such as `"background_page"`, will not be listed
|
313 | * here. You can find them using {@link Target.page}.
|
314 | */
|
315 | pages(): Promise<Page[]>;
|
316 | /**
|
317 | * A string representing the browser name and version.
|
318 | *
|
319 | * @remarks
|
320 | *
|
321 | * For headless Chromium, this is similar to `HeadlessChrome/61.0.3153.0`. For
|
322 | * non-headless, this is similar to `Chrome/61.0.3153.0`.
|
323 | *
|
324 | * The format of browser.version() might change with future releases of Chromium.
|
325 | */
|
326 | version(): Promise<string>;
|
327 | /**
|
328 | * The browser's original user agent. Pages can override the browser user agent with
|
329 | * {@link Page.setUserAgent}.
|
330 | */
|
331 | userAgent(): Promise<string>;
|
332 | /**
|
333 | * Closes Chromium and all of its pages (if any were opened). The {@link Browser} object
|
334 | * itself is considered to be disposed and cannot be used anymore.
|
335 | */
|
336 | close(): Promise<void>;
|
337 | /**
|
338 | * Disconnects Puppeteer from the browser, but leaves the Chromium process running.
|
339 | * After calling `disconnect`, the {@link Browser} object is considered disposed and
|
340 | * cannot be used anymore.
|
341 | */
|
342 | disconnect(): void;
|
343 | /**
|
344 | * Indicates that the browser is connected.
|
345 | */
|
346 | isConnected(): boolean;
|
347 | private _getVersion;
|
348 | }
|
349 |
|
350 | /**
|
351 | * @internal
|
352 | */
|
353 | export declare type BrowserCloseCallback = () => Promise<void> | void;
|
354 |
|
355 | /**
|
356 | * Generic browser options that can be passed when launching any browser or when
|
357 | * connecting to an existing browser instance.
|
358 | * @public
|
359 | */
|
360 | export declare interface BrowserConnectOptions {
|
361 | /**
|
362 | * Whether to ignore HTTPS errors during navigation.
|
363 | * @defaultValue false
|
364 | */
|
365 | ignoreHTTPSErrors?: boolean;
|
366 | /**
|
367 | * Sets the viewport for each page.
|
368 | */
|
369 | defaultViewport?: Viewport | null;
|
370 | /**
|
371 | * Slows down Puppeteer operations by the specified amount of milliseconds to
|
372 | * aid debugging.
|
373 | */
|
374 | slowMo?: number;
|
375 | /**
|
376 | * Callback to decide if Puppeteer should connect to a given target or not.
|
377 | */
|
378 | targetFilter?: TargetFilterCallback;
|
379 | }
|
380 |
|
381 | /**
|
382 | * BrowserContexts provide a way to operate multiple independent browser
|
383 | * sessions. When a browser is launched, it has a single BrowserContext used by
|
384 | * default. The method {@link Browser.newPage | Browser.newPage} creates a page
|
385 | * in the default browser context.
|
386 | *
|
387 | * @remarks
|
388 | *
|
389 | * The Browser class extends from Puppeteer's {@link EventEmitter} class and
|
390 | * will emit various events which are documented in the
|
391 | * {@link BrowserContextEmittedEvents} enum.
|
392 | *
|
393 | * If a page opens another page, e.g. with a `window.open` call, the popup will
|
394 | * belong to the parent page's browser context.
|
395 | *
|
396 | * Puppeteer allows creation of "incognito" browser contexts with
|
397 | * {@link Browser.createIncognitoBrowserContext | Browser.createIncognitoBrowserContext}
|
398 | * method. "Incognito" browser contexts don't write any browsing data to disk.
|
399 | *
|
400 | * @example
|
401 | * ```js
|
402 | * // Create a new incognito browser context
|
403 | * const context = await browser.createIncognitoBrowserContext();
|
404 | * // Create a new page inside context.
|
405 | * const page = await context.newPage();
|
406 | * // ... do stuff with page ...
|
407 | * await page.goto('https://example.com');
|
408 | * // Dispose context once it's no longer needed.
|
409 | * await context.close();
|
410 | * ```
|
411 | * @public
|
412 | */
|
413 | export declare class BrowserContext extends EventEmitter {
|
414 | private _connection;
|
415 | private _browser;
|
416 | private _id?;
|
417 | /**
|
418 | * @internal
|
419 | */
|
420 | constructor(connection: Connection, browser: Browser, contextId?: string);
|
421 | /**
|
422 | * An array of all active targets inside the browser context.
|
423 | */
|
424 | targets(): Target[];
|
425 | /**
|
426 | * This searches for a target in this specific browser context.
|
427 | *
|
428 | * @example
|
429 | * An example of finding a target for a page opened via `window.open`:
|
430 | * ```js
|
431 | * await page.evaluate(() => window.open('https://www.example.com/'));
|
432 | * const newWindowTarget = await browserContext.waitForTarget(target => target.url() === 'https://www.example.com/');
|
433 | * ```
|
434 | *
|
435 | * @param predicate - A function to be run for every target
|
436 | * @param options - An object of options. Accepts a timout,
|
437 | * which is the maximum wait time in milliseconds.
|
438 | * Pass `0` to disable the timeout. Defaults to 30 seconds.
|
439 | * @returns Promise which resolves to the first target found
|
440 | * that matches the `predicate` function.
|
441 | */
|
442 | waitForTarget(predicate: (x: Target) => boolean, options?: {
|
443 | timeout?: number;
|
444 | }): Promise<Target>;
|
445 | /**
|
446 | * An array of all pages inside the browser context.
|
447 | *
|
448 | * @returns Promise which resolves to an array of all open pages.
|
449 | * Non visible pages, such as `"background_page"`, will not be listed here.
|
450 | * You can find them using {@link Target.page | the target page}.
|
451 | */
|
452 | pages(): Promise<Page[]>;
|
453 | /**
|
454 | * Returns whether BrowserContext is incognito.
|
455 | * The default browser context is the only non-incognito browser context.
|
456 | *
|
457 | * @remarks
|
458 | * The default browser context cannot be closed.
|
459 | */
|
460 | isIncognito(): boolean;
|
461 | /**
|
462 | * @example
|
463 | * ```js
|
464 | * const context = browser.defaultBrowserContext();
|
465 | * await context.overridePermissions('https://html5demos.com', ['geolocation']);
|
466 | * ```
|
467 | *
|
468 | * @param origin - The origin to grant permissions to, e.g. "https://example.com".
|
469 | * @param permissions - An array of permissions to grant.
|
470 | * All permissions that are not listed here will be automatically denied.
|
471 | */
|
472 | overridePermissions(origin: string, permissions: Permission[]): Promise<void>;
|
473 | /**
|
474 | * Clears all permission overrides for the browser context.
|
475 | *
|
476 | * @example
|
477 | * ```js
|
478 | * const context = browser.defaultBrowserContext();
|
479 | * context.overridePermissions('https://example.com', ['clipboard-read']);
|
480 | * // do stuff ..
|
481 | * context.clearPermissionOverrides();
|
482 | * ```
|
483 | */
|
484 | clearPermissionOverrides(): Promise<void>;
|
485 | /**
|
486 | * Creates a new page in the browser context.
|
487 | */
|
488 | newPage(): Promise<Page>;
|
489 | /**
|
490 | * The browser this browser context belongs to.
|
491 | */
|
492 | browser(): Browser;
|
493 | /**
|
494 | * Closes the browser context. All the targets that belong to the browser context
|
495 | * will be closed.
|
496 | *
|
497 | * @remarks
|
498 | * Only incognito browser contexts can be closed.
|
499 | */
|
500 | close(): Promise<void>;
|
501 | }
|
502 |
|
503 | /**
|
504 | * @public
|
505 | */
|
506 | export declare const enum BrowserContextEmittedEvents {
|
507 | /**
|
508 | * Emitted when the url of a target inside the browser context changes.
|
509 | * Contains a {@link Target} instance.
|
510 | */
|
511 | TargetChanged = "targetchanged",
|
512 | /**
|
513 | * Emitted when a target is created within the browser context, for example
|
514 | * when a new page is opened by
|
515 | * {@link https://developer.mozilla.org/en-US/docs/Web/API/Window/open | window.open}
|
516 | * or by {@link BrowserContext.newPage | browserContext.newPage}
|
517 | *
|
518 | * Contains a {@link Target} instance.
|
519 | */
|
520 | TargetCreated = "targetcreated",
|
521 | /**
|
522 | * Emitted when a target is destroyed within the browser context, for example
|
523 | * when a page is closed. Contains a {@link Target} instance.
|
524 | */
|
525 | TargetDestroyed = "targetdestroyed"
|
526 | }
|
527 |
|
528 | /**
|
529 | * BrowserContext options.
|
530 | *
|
531 | * @public
|
532 | */
|
533 | export declare interface BrowserContextOptions {
|
534 | /**
|
535 | * Proxy server with optional port to use for all requests.
|
536 | * Username and password can be set in `Page.authenticate`.
|
537 | */
|
538 | proxyServer?: string;
|
539 | /**
|
540 | * Bypass the proxy for the given semi-colon-separated list of hosts.
|
541 | */
|
542 | proxyBypassList?: string[];
|
543 | }
|
544 |
|
545 | /**
|
546 | * All the events a {@link Browser | browser instance} may emit.
|
547 | *
|
548 | * @public
|
549 | */
|
550 | export declare const enum BrowserEmittedEvents {
|
551 | /**
|
552 | * Emitted when Puppeteer gets disconnected from the Chromium instance. This
|
553 | * might happen because of one of the following:
|
554 | *
|
555 | * - Chromium is closed or crashed
|
556 | *
|
557 | * - The {@link Browser.disconnect | browser.disconnect } method was called.
|
558 | */
|
559 | Disconnected = "disconnected",
|
560 | /**
|
561 | * Emitted when the url of a target changes. Contains a {@link Target} instance.
|
562 | *
|
563 | * @remarks
|
564 | *
|
565 | * Note that this includes target changes in incognito browser contexts.
|
566 | */
|
567 | TargetChanged = "targetchanged",
|
568 | /**
|
569 | * Emitted when a target is created, for example when a new page is opened by
|
570 | * {@link https://developer.mozilla.org/en-US/docs/Web/API/Window/open | window.open}
|
571 | * or by {@link Browser.newPage | browser.newPage}
|
572 | *
|
573 | * Contains a {@link Target} instance.
|
574 | *
|
575 | * @remarks
|
576 | *
|
577 | * Note that this includes target creations in incognito browser contexts.
|
578 | */
|
579 | TargetCreated = "targetcreated",
|
580 | /**
|
581 | * Emitted when a target is destroyed, for example when a page is closed.
|
582 | * Contains a {@link Target} instance.
|
583 | *
|
584 | * @remarks
|
585 | *
|
586 | * Note that this includes target destructions in incognito browser contexts.
|
587 | */
|
588 | TargetDestroyed = "targetdestroyed"
|
589 | }
|
590 |
|
591 | /**
|
592 | * BrowserFetcher can download and manage different versions of Chromium and Firefox.
|
593 | *
|
594 | * @remarks
|
595 | * BrowserFetcher operates on revision strings that specify a precise version of Chromium, e.g. `"533271"`. Revision strings can be obtained from {@link http://omahaproxy.appspot.com/ | omahaproxy.appspot.com}.
|
596 | * In the Firefox case, BrowserFetcher downloads Firefox Nightly and
|
597 | * operates on version numbers such as `"75"`.
|
598 | *
|
599 | * @example
|
600 | * An example of using BrowserFetcher to download a specific version of Chromium
|
601 | * and running Puppeteer against it:
|
602 | *
|
603 | * ```js
|
604 | * const browserFetcher = puppeteer.createBrowserFetcher();
|
605 | * const revisionInfo = await browserFetcher.download('533271');
|
606 | * const browser = await puppeteer.launch({executablePath: revisionInfo.executablePath})
|
607 | * ```
|
608 | *
|
609 | * **NOTE** BrowserFetcher is not designed to work concurrently with other
|
610 | * instances of BrowserFetcher that share the same downloads directory.
|
611 | *
|
612 | * @public
|
613 | */
|
614 | export declare class BrowserFetcher {
|
615 | private _product;
|
616 | private _downloadsFolder;
|
617 | private _downloadHost;
|
618 | private _platform;
|
619 | /**
|
620 | * @internal
|
621 | */
|
622 | constructor(projectRoot: string, options?: BrowserFetcherOptions);
|
623 | private setPlatform;
|
624 | /**
|
625 | * @returns Returns the current `Platform`, which is one of `mac`, `linux`,
|
626 | * `win32` or `win64`.
|
627 | */
|
628 | platform(): Platform;
|
629 | /**
|
630 | * @returns Returns the current `Product`, which is one of `chrome` or
|
631 | * `firefox`.
|
632 | */
|
633 | product(): Product;
|
634 | /**
|
635 | * @returns The download host being used.
|
636 | */
|
637 | host(): string;
|
638 | /**
|
639 | * Initiates a HEAD request to check if the revision is available.
|
640 | * @remarks
|
641 | * This method is affected by the current `product`.
|
642 | * @param revision - The revision to check availability for.
|
643 | * @returns A promise that resolves to `true` if the revision could be downloaded
|
644 | * from the host.
|
645 | */
|
646 | canDownload(revision: string): Promise<boolean>;
|
647 | /**
|
648 | * Initiates a GET request to download the revision from the host.
|
649 | * @remarks
|
650 | * This method is affected by the current `product`.
|
651 | * @param revision - The revision to download.
|
652 | * @param progressCallback - A function that will be called with two arguments:
|
653 | * How many bytes have been downloaded and the total number of bytes of the download.
|
654 | * @returns A promise with revision information when the revision is downloaded
|
655 | * and extracted.
|
656 | */
|
657 | download(revision: string, progressCallback?: (x: number, y: number) => void): Promise<BrowserFetcherRevisionInfo>;
|
658 | /**
|
659 | * @remarks
|
660 | * This method is affected by the current `product`.
|
661 | * @returns A promise with a list of all revision strings (for the current `product`)
|
662 | * available locally on disk.
|
663 | */
|
664 | localRevisions(): Promise<string[]>;
|
665 | /**
|
666 | * @remarks
|
667 | * This method is affected by the current `product`.
|
668 | * @param revision - A revision to remove for the current `product`.
|
669 | * @returns A promise that resolves when the revision has been removes or
|
670 | * throws if the revision has not been downloaded.
|
671 | */
|
672 | remove(revision: string): Promise<void>;
|
673 | /**
|
674 | * @param revision - The revision to get info for.
|
675 | * @returns The revision info for the given revision.
|
676 | */
|
677 | revisionInfo(revision: string): BrowserFetcherRevisionInfo;
|
678 | /**
|
679 | * @internal
|
680 | */
|
681 | _getFolderPath(revision: string): string;
|
682 | }
|
683 |
|
684 | /**
|
685 | * @public
|
686 | */
|
687 | export declare interface BrowserFetcherOptions {
|
688 | platform?: Platform;
|
689 | product?: string;
|
690 | path?: string;
|
691 | host?: string;
|
692 | }
|
693 |
|
694 | /**
|
695 | * @public
|
696 | */
|
697 | export declare interface BrowserFetcherRevisionInfo {
|
698 | folderPath: string;
|
699 | executablePath: string;
|
700 | url: string;
|
701 | local: boolean;
|
702 | revision: string;
|
703 | product: string;
|
704 | }
|
705 |
|
706 | /**
|
707 | * Launcher options that only apply to Chrome.
|
708 | *
|
709 | * @public
|
710 | */
|
711 | export declare interface BrowserLaunchArgumentOptions {
|
712 | /**
|
713 | * Whether to run the browser in headless mode.
|
714 | * @defaultValue true
|
715 | */
|
716 | headless?: boolean;
|
717 | /**
|
718 | * Path to a user data directory.
|
719 | * {@link https://chromium.googlesource.com/chromium/src/+/refs/heads/main/docs/user_data_dir.md | see the Chromium docs}
|
720 | * for more info.
|
721 | */
|
722 | userDataDir?: string;
|
723 | /**
|
724 | * Whether to auto-open a DevTools panel for each tab. If this is set to
|
725 | * `true`, then `headless` will be set to `false` automatically.
|
726 | * @defaultValue `false`
|
727 | */
|
728 | devtools?: boolean;
|
729 | /**
|
730 | * Additional command line arguments to pass to the browser instance.
|
731 | */
|
732 | args?: string[];
|
733 | }
|
734 |
|
735 | /**
|
736 | * The `CDPSession` instances are used to talk raw Chrome Devtools Protocol.
|
737 | *
|
738 | * @remarks
|
739 | *
|
740 | * Protocol methods can be called with {@link CDPSession.send} method and protocol
|
741 | * events can be subscribed to with `CDPSession.on` method.
|
742 | *
|
743 | * Useful links: {@link https://chromedevtools.github.io/devtools-protocol/ | DevTools Protocol Viewer}
|
744 | * and {@link https://github.com/aslushnikov/getting-started-with-cdp/blob/HEAD/README.md | Getting Started with DevTools Protocol}.
|
745 | *
|
746 | * @example
|
747 | * ```js
|
748 | * const client = await page.target().createCDPSession();
|
749 | * await client.send('Animation.enable');
|
750 | * client.on('Animation.animationCreated', () => console.log('Animation created!'));
|
751 | * const response = await client.send('Animation.getPlaybackRate');
|
752 | * console.log('playback rate is ' + response.playbackRate);
|
753 | * await client.send('Animation.setPlaybackRate', {
|
754 | * playbackRate: response.playbackRate / 2
|
755 | * });
|
756 | * ```
|
757 | *
|
758 | * @public
|
759 | */
|
760 | export declare class CDPSession extends EventEmitter {
|
761 | /**
|
762 | * @internal
|
763 | */
|
764 | _connection: Connection;
|
765 | private _sessionId;
|
766 | private _targetType;
|
767 | private _callbacks;
|
768 | /**
|
769 | * @internal
|
770 | */
|
771 | constructor(connection: Connection, targetType: string, sessionId: string);
|
772 | connection(): Connection;
|
773 | send<T extends keyof ProtocolMapping.Commands>(method: T, ...paramArgs: ProtocolMapping.Commands[T]['paramsType']): Promise<ProtocolMapping.Commands[T]['returnType']>;
|
774 | /**
|
775 | * @internal
|
776 | */
|
777 | _onMessage(object: CDPSessionOnMessageObject): void;
|
778 | /**
|
779 | * Detaches the cdpSession from the target. Once detached, the cdpSession object
|
780 | * won't emit any events and can't be used to send messages.
|
781 | */
|
782 | detach(): Promise<void>;
|
783 | /**
|
784 | * @internal
|
785 | */
|
786 | _onClosed(): void;
|
787 | }
|
788 |
|
789 | /**
|
790 | * Internal events that the CDPSession class emits.
|
791 | *
|
792 | * @internal
|
793 | */
|
794 | export declare const CDPSessionEmittedEvents: {
|
795 | readonly Disconnected: symbol;
|
796 | };
|
797 |
|
798 | /**
|
799 | * @public
|
800 | */
|
801 | export declare interface CDPSessionOnMessageObject {
|
802 | id?: number;
|
803 | method: string;
|
804 | params: Record<string, unknown>;
|
805 | error: {
|
806 | message: string;
|
807 | data: any;
|
808 | };
|
809 | result?: any;
|
810 | }
|
811 |
|
812 | /**
|
813 | * @public
|
814 | */
|
815 | export declare type ChromeReleaseChannel = 'chrome' | 'chrome-beta' | 'chrome-canary' | 'chrome-dev';
|
816 |
|
817 | /**
|
818 | * @public
|
819 | * {@inheritDoc Puppeteer.clearCustomQueryHandlers}
|
820 | */
|
821 | export declare function clearCustomQueryHandlers(): void;
|
822 |
|
823 | /**
|
824 | * @public
|
825 | */
|
826 | export declare interface ClickOptions {
|
827 | /**
|
828 | * Time to wait between `mousedown` and `mouseup` in milliseconds.
|
829 | *
|
830 | * @defaultValue 0
|
831 | */
|
832 | delay?: number;
|
833 | /**
|
834 | * @defaultValue 'left'
|
835 | */
|
836 | button?: 'left' | 'right' | 'middle';
|
837 | /**
|
838 | * @defaultValue 1
|
839 | */
|
840 | clickCount?: number;
|
841 | /**
|
842 | * Offset for the clickable point relative to the top-left corder of the border box.
|
843 | */
|
844 | offset?: Offset;
|
845 | }
|
846 |
|
847 | /**
|
848 | * @public
|
849 | */
|
850 | export declare interface CommonEventEmitter {
|
851 | on(event: EventType, handler: Handler): CommonEventEmitter;
|
852 | off(event: EventType, handler: Handler): CommonEventEmitter;
|
853 | addListener(event: EventType, handler: Handler): CommonEventEmitter;
|
854 | removeListener(event: EventType, handler: Handler): CommonEventEmitter;
|
855 | emit(event: EventType, eventData?: unknown): boolean;
|
856 | once(event: EventType, handler: Handler): CommonEventEmitter;
|
857 | listenerCount(event: string): number;
|
858 | removeAllListeners(event?: EventType): CommonEventEmitter;
|
859 | }
|
860 |
|
861 | /**
|
862 | * Settings that are common to the Puppeteer class, regardless of enviroment.
|
863 | * @internal
|
864 | */
|
865 | export declare interface CommonPuppeteerSettings {
|
866 | isPuppeteerCore: boolean;
|
867 | }
|
868 |
|
869 | /**
|
870 | * @public
|
871 | * {@inheritDoc PuppeteerNode.connect}
|
872 | */
|
873 | export declare function connect(options: ConnectOptions): Promise<Browser>;
|
874 |
|
875 | /**
|
876 | * @public
|
877 | */
|
878 | export declare class Connection extends EventEmitter {
|
879 | _url: string;
|
880 | _transport: ConnectionTransport;
|
881 | _delay: number;
|
882 | _lastId: number;
|
883 | _sessions: Map<string, CDPSession>;
|
884 | _closed: boolean;
|
885 | _callbacks: Map<number, ConnectionCallback>;
|
886 | constructor(url: string, transport: ConnectionTransport, delay?: number);
|
887 | static fromSession(session: CDPSession): Connection;
|
888 | /**
|
889 | * @param sessionId - The session id
|
890 | * @returns The current CDP session if it exists
|
891 | */
|
892 | session(sessionId: string): CDPSession | null;
|
893 | url(): string;
|
894 | send<T extends keyof ProtocolMapping.Commands>(method: T, ...paramArgs: ProtocolMapping.Commands[T]['paramsType']): Promise<ProtocolMapping.Commands[T]['returnType']>;
|
895 | _rawSend(message: Record<string, unknown>): number;
|
896 | _onMessage(message: string): Promise<void>;
|
897 | _onClose(): void;
|
898 | dispose(): void;
|
899 | /**
|
900 | * @param targetInfo - The target info
|
901 | * @returns The CDP session that is created
|
902 | */
|
903 | createSession(targetInfo: Protocol.Target.TargetInfo): Promise<CDPSession>;
|
904 | }
|
905 |
|
906 | /**
|
907 | * @public
|
908 | */
|
909 | export declare interface ConnectionCallback {
|
910 | resolve: Function;
|
911 | reject: Function;
|
912 | error: Error;
|
913 | method: string;
|
914 | }
|
915 |
|
916 | /**
|
917 | * Internal events that the Connection class emits.
|
918 | *
|
919 | * @internal
|
920 | */
|
921 | export declare const ConnectionEmittedEvents: {
|
922 | readonly Disconnected: symbol;
|
923 | };
|
924 |
|
925 | /**
|
926 | * Copyright 2020 Google Inc. All rights reserved.
|
927 | *
|
928 | * Licensed under the Apache License, Version 2.0 (the "License");
|
929 | * you may not use this file except in compliance with the License.
|
930 | * You may obtain a copy of the License at
|
931 | *
|
932 | * http://www.apache.org/licenses/LICENSE-2.0
|
933 | *
|
934 | * Unless required by applicable law or agreed to in writing, software
|
935 | * distributed under the License is distributed on an "AS IS" BASIS,
|
936 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
937 | * See the License for the specific language governing permissions and
|
938 | * limitations under the License.
|
939 | */
|
940 | /**
|
941 | * @public
|
942 | */
|
943 | export declare interface ConnectionTransport {
|
944 | send(string: any): any;
|
945 | close(): any;
|
946 | onmessage?: (message: string) => void;
|
947 | onclose?: () => void;
|
948 | }
|
949 |
|
950 | /**
|
951 | * @public
|
952 | */
|
953 | export declare interface ConnectOptions extends BrowserConnectOptions {
|
954 | browserWSEndpoint?: string;
|
955 | browserURL?: string;
|
956 | transport?: ConnectionTransport;
|
957 | product?: Product;
|
958 | }
|
959 |
|
960 | /**
|
961 | * Users should never call this directly; it's called when calling
|
962 | * `puppeteer.connect`.
|
963 | * @internal
|
964 | */
|
965 | export declare const connectToBrowser: (options: BrowserConnectOptions & {
|
966 | browserWSEndpoint?: string;
|
967 | browserURL?: string;
|
968 | transport?: ConnectionTransport;
|
969 | }) => Promise<Browser>;
|
970 |
|
971 | /**
|
972 | * @internal
|
973 | */
|
974 | export declare type ConsoleAPICalledCallback = (eventType: string, handles: JSHandle[], trace: Protocol.Runtime.StackTrace) => void;
|
975 |
|
976 | /**
|
977 | * ConsoleMessage objects are dispatched by page via the 'console' event.
|
978 | * @public
|
979 | */
|
980 | export declare class ConsoleMessage {
|
981 | private _type;
|
982 | private _text;
|
983 | private _args;
|
984 | private _stackTraceLocations;
|
985 | /**
|
986 | * @public
|
987 | */
|
988 | constructor(type: ConsoleMessageType, text: string, args: JSHandle[], stackTraceLocations: ConsoleMessageLocation[]);
|
989 | /**
|
990 | * @returns The type of the console message.
|
991 | */
|
992 | type(): ConsoleMessageType;
|
993 | /**
|
994 | * @returns The text of the console message.
|
995 | */
|
996 | text(): string;
|
997 | /**
|
998 | * @returns An array of arguments passed to the console.
|
999 | */
|
1000 | args(): JSHandle[];
|
1001 | /**
|
1002 | * @returns The location of the console message.
|
1003 | */
|
1004 | location(): ConsoleMessageLocation;
|
1005 | /**
|
1006 | * @returns The array of locations on the stack of the console message.
|
1007 | */
|
1008 | stackTrace(): ConsoleMessageLocation[];
|
1009 | }
|
1010 |
|
1011 | /**
|
1012 | * @public
|
1013 | */
|
1014 | export declare interface ConsoleMessageLocation {
|
1015 | /**
|
1016 | * URL of the resource if known or `undefined` otherwise.
|
1017 | */
|
1018 | url?: string;
|
1019 | /**
|
1020 | * 0-based line number in the resource if known or `undefined` otherwise.
|
1021 | */
|
1022 | lineNumber?: number;
|
1023 | /**
|
1024 | * 0-based column number in the resource if known or `undefined` otherwise.
|
1025 | */
|
1026 | columnNumber?: number;
|
1027 | }
|
1028 |
|
1029 | /**
|
1030 | * The supported types for console messages.
|
1031 | * @public
|
1032 | */
|
1033 | export declare type ConsoleMessageType = 'log' | 'debug' | 'info' | 'error' | 'warning' | 'dir' | 'dirxml' | 'table' | 'trace' | 'clear' | 'startGroup' | 'startGroupCollapsed' | 'endGroup' | 'assert' | 'profile' | 'profileEnd' | 'count' | 'timeEnd' | 'verbose';
|
1034 |
|
1035 | /**
|
1036 | * @public
|
1037 | */
|
1038 | export declare interface ContinueRequestOverrides {
|
1039 | /**
|
1040 | * If set, the request URL will change. This is not a redirect.
|
1041 | */
|
1042 | url?: string;
|
1043 | method?: string;
|
1044 | postData?: string;
|
1045 | headers?: Record<string, string>;
|
1046 | }
|
1047 |
|
1048 | /**
|
1049 | * The Coverage class provides methods to gathers information about parts of
|
1050 | * JavaScript and CSS that were used by the page.
|
1051 | *
|
1052 | * @remarks
|
1053 | * To output coverage in a form consumable by {@link https://github.com/istanbuljs | Istanbul},
|
1054 | * see {@link https://github.com/istanbuljs/puppeteer-to-istanbul | puppeteer-to-istanbul}.
|
1055 | *
|
1056 | * @example
|
1057 | * An example of using JavaScript and CSS coverage to get percentage of initially
|
1058 | * executed code:
|
1059 | * ```js
|
1060 | * // Enable both JavaScript and CSS coverage
|
1061 | * await Promise.all([
|
1062 | * page.coverage.startJSCoverage(),
|
1063 | * page.coverage.startCSSCoverage()
|
1064 | * ]);
|
1065 | * // Navigate to page
|
1066 | * await page.goto('https://example.com');
|
1067 | * // Disable both JavaScript and CSS coverage
|
1068 | * const [jsCoverage, cssCoverage] = await Promise.all([
|
1069 | * page.coverage.stopJSCoverage(),
|
1070 | * page.coverage.stopCSSCoverage(),
|
1071 | * ]);
|
1072 | * let totalBytes = 0;
|
1073 | * let usedBytes = 0;
|
1074 | * const coverage = [...jsCoverage, ...cssCoverage];
|
1075 | * for (const entry of coverage) {
|
1076 | * totalBytes += entry.text.length;
|
1077 | * for (const range of entry.ranges)
|
1078 | * usedBytes += range.end - range.start - 1;
|
1079 | * }
|
1080 | * console.log(`Bytes used: ${usedBytes / totalBytes * 100}%`);
|
1081 | * ```
|
1082 | * @public
|
1083 | */
|
1084 | export declare class Coverage {
|
1085 | /**
|
1086 | * @internal
|
1087 | */
|
1088 | _jsCoverage: JSCoverage;
|
1089 | /**
|
1090 | * @internal
|
1091 | */
|
1092 | _cssCoverage: CSSCoverage;
|
1093 | constructor(client: CDPSession);
|
1094 | /**
|
1095 | * @param options - Set of configurable options for coverage defaults to
|
1096 | * `resetOnNavigation : true, reportAnonymousScripts : false`
|
1097 | * @returns Promise that resolves when coverage is started.
|
1098 | *
|
1099 | * @remarks
|
1100 | * Anonymous scripts are ones that don't have an associated url. These are
|
1101 | * scripts that are dynamically created on the page using `eval` or
|
1102 | * `new Function`. If `reportAnonymousScripts` is set to `true`, anonymous
|
1103 | * scripts will have `__puppeteer_evaluation_script__` as their URL.
|
1104 | */
|
1105 | startJSCoverage(options?: JSCoverageOptions): Promise<void>;
|
1106 | /**
|
1107 | * @returns Promise that resolves to the array of coverage reports for
|
1108 | * all scripts.
|
1109 | *
|
1110 | * @remarks
|
1111 | * JavaScript Coverage doesn't include anonymous scripts by default.
|
1112 | * However, scripts with sourceURLs are reported.
|
1113 | */
|
1114 | stopJSCoverage(): Promise<JSCoverageEntry[]>;
|
1115 | /**
|
1116 | * @param options - Set of configurable options for coverage, defaults to
|
1117 | * `resetOnNavigation : true`
|
1118 | * @returns Promise that resolves when coverage is started.
|
1119 | */
|
1120 | startCSSCoverage(options?: CSSCoverageOptions): Promise<void>;
|
1121 | /**
|
1122 | * @returns Promise that resolves to the array of coverage reports
|
1123 | * for all stylesheets.
|
1124 | * @remarks
|
1125 | * CSS Coverage doesn't include dynamically injected style tags
|
1126 | * without sourceURLs.
|
1127 | */
|
1128 | stopCSSCoverage(): Promise<CoverageEntry[]>;
|
1129 | }
|
1130 |
|
1131 | /**
|
1132 | * The CoverageEntry class represents one entry of the coverage report.
|
1133 | * @public
|
1134 | */
|
1135 | export declare interface CoverageEntry {
|
1136 | /**
|
1137 | * The URL of the style sheet or script.
|
1138 | */
|
1139 | url: string;
|
1140 | /**
|
1141 | * The content of the style sheet or script.
|
1142 | */
|
1143 | text: string;
|
1144 | /**
|
1145 | * The covered range as start and end positions.
|
1146 | */
|
1147 | ranges: Array<{
|
1148 | start: number;
|
1149 | end: number;
|
1150 | }>;
|
1151 | }
|
1152 |
|
1153 | /**
|
1154 | * @internal
|
1155 | */
|
1156 | export declare function createJSHandle(context: ExecutionContext, remoteObject: Protocol.Runtime.RemoteObject): JSHandle;
|
1157 |
|
1158 | /**
|
1159 | * @public
|
1160 | */
|
1161 | export declare interface Credentials {
|
1162 | username: string;
|
1163 | password: string;
|
1164 | }
|
1165 |
|
1166 | /**
|
1167 | * @public
|
1168 | */
|
1169 | export declare class CSSCoverage {
|
1170 | _client: CDPSession;
|
1171 | _enabled: boolean;
|
1172 | _stylesheetURLs: Map<string, string>;
|
1173 | _stylesheetSources: Map<string, string>;
|
1174 | _eventListeners: PuppeteerEventListener[];
|
1175 | _resetOnNavigation: boolean;
|
1176 | _reportAnonymousScripts: boolean;
|
1177 | constructor(client: CDPSession);
|
1178 | start(options?: {
|
1179 | resetOnNavigation?: boolean;
|
1180 | }): Promise<void>;
|
1181 | _onExecutionContextsCleared(): void;
|
1182 | _onStyleSheet(event: Protocol.CSS.StyleSheetAddedEvent): Promise<void>;
|
1183 | stop(): Promise<CoverageEntry[]>;
|
1184 | }
|
1185 |
|
1186 | /**
|
1187 | * Set of configurable options for CSS coverage.
|
1188 | * @public
|
1189 | */
|
1190 | export declare interface CSSCoverageOptions {
|
1191 | /**
|
1192 | * Whether to reset coverage on every navigation.
|
1193 | */
|
1194 | resetOnNavigation?: boolean;
|
1195 | }
|
1196 |
|
1197 | /**
|
1198 | * Copyright 2018 Google Inc. All rights reserved.
|
1199 | *
|
1200 | * Licensed under the Apache License, Version 2.0 (the "License");
|
1201 | * you may not use this file except in compliance with the License.
|
1202 | * You may obtain a copy of the License at
|
1203 | *
|
1204 | * http://www.apache.org/licenses/LICENSE-2.0
|
1205 | *
|
1206 | * Unless required by applicable law or agreed to in writing, software
|
1207 | * distributed under the License is distributed on an "AS IS" BASIS,
|
1208 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
1209 | * See the License for the specific language governing permissions and
|
1210 | * limitations under the License.
|
1211 | */
|
1212 | /**
|
1213 | * @public
|
1214 | */
|
1215 | export declare class CustomError extends Error {
|
1216 | constructor(message: string);
|
1217 | }
|
1218 |
|
1219 | /**
|
1220 | * Contains two functions `queryOne` and `queryAll` that can
|
1221 | * be {@link Puppeteer.registerCustomQueryHandler | registered}
|
1222 | * as alternative querying strategies. The functions `queryOne` and `queryAll`
|
1223 | * are executed in the page context. `queryOne` should take an `Element` and a
|
1224 | * selector string as argument and return a single `Element` or `null` if no
|
1225 | * element is found. `queryAll` takes the same arguments but should instead
|
1226 | * return a `NodeListOf<Element>` or `Array<Element>` with all the elements
|
1227 | * that match the given query selector.
|
1228 | * @public
|
1229 | */
|
1230 | export declare interface CustomQueryHandler {
|
1231 | queryOne?: (element: Element | Document, selector: string) => Element | null;
|
1232 | queryAll?: (element: Element | Document, selector: string) => Element[] | NodeListOf<Element>;
|
1233 | }
|
1234 |
|
1235 | /**
|
1236 | * @public
|
1237 | * {@inheritDoc Puppeteer.customQueryHandlerNames}
|
1238 | */
|
1239 | export declare function customQueryHandlerNames(): string[];
|
1240 |
|
1241 | /**
|
1242 | * Copyright 2017 Google Inc. All rights reserved.
|
1243 | *
|
1244 | * Licensed under the Apache License, Version 2.0 (the "License");
|
1245 | * you may not use this file except in compliance with the License.
|
1246 | * You may obtain a copy of the License at
|
1247 | *
|
1248 | * http://www.apache.org/licenses/LICENSE-2.0
|
1249 | *
|
1250 | * Unless required by applicable law or agreed to in writing, software
|
1251 | * distributed under the License is distributed on an "AS IS" BASIS,
|
1252 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
1253 | * See the License for the specific language governing permissions and
|
1254 | * limitations under the License.
|
1255 | */
|
1256 | /**
|
1257 | * @public
|
1258 | */
|
1259 | export declare interface Device {
|
1260 | name: string;
|
1261 | userAgent: string;
|
1262 | viewport: {
|
1263 | width: number;
|
1264 | height: number;
|
1265 | deviceScaleFactor: number;
|
1266 | isMobile: boolean;
|
1267 | hasTouch: boolean;
|
1268 | isLandscape: boolean;
|
1269 | };
|
1270 | }
|
1271 |
|
1272 | /**
|
1273 | * @public
|
1274 | * {@inheritDoc Puppeteer.devices}
|
1275 | */
|
1276 | export declare let devices: DevicesMap;
|
1277 |
|
1278 | /**
|
1279 | * @public
|
1280 | */
|
1281 | export declare type DevicesMap = {
|
1282 | [name: string]: Device;
|
1283 | };
|
1284 |
|
1285 | /**
|
1286 | * @internal
|
1287 | */
|
1288 | export declare const devicesMap: DevicesMap;
|
1289 |
|
1290 | /**
|
1291 | * Dialog instances are dispatched by the {@link Page} via the `dialog` event.
|
1292 | *
|
1293 | * @remarks
|
1294 | *
|
1295 | * @example
|
1296 | * ```js
|
1297 | * const puppeteer = require('puppeteer');
|
1298 | *
|
1299 | * (async () => {
|
1300 | * const browser = await puppeteer.launch();
|
1301 | * const page = await browser.newPage();
|
1302 | * page.on('dialog', async dialog => {
|
1303 | * console.log(dialog.message());
|
1304 | * await dialog.dismiss();
|
1305 | * await browser.close();
|
1306 | * });
|
1307 | * page.evaluate(() => alert('1'));
|
1308 | * })();
|
1309 | * ```
|
1310 | * @public
|
1311 | */
|
1312 | export declare class Dialog {
|
1313 | private _client;
|
1314 | private _type;
|
1315 | private _message;
|
1316 | private _defaultValue;
|
1317 | private _handled;
|
1318 | /**
|
1319 | * @internal
|
1320 | */
|
1321 | constructor(client: CDPSession, type: Protocol.Page.DialogType, message: string, defaultValue?: string);
|
1322 | /**
|
1323 | * @returns The type of the dialog.
|
1324 | */
|
1325 | type(): Protocol.Page.DialogType;
|
1326 | /**
|
1327 | * @returns The message displayed in the dialog.
|
1328 | */
|
1329 | message(): string;
|
1330 | /**
|
1331 | * @returns The default value of the prompt, or an empty string if the dialog
|
1332 | * is not a `prompt`.
|
1333 | */
|
1334 | defaultValue(): string;
|
1335 | /**
|
1336 | * @param promptText - optional text that will be entered in the dialog
|
1337 | * prompt. Has no effect if the dialog's type is not `prompt`.
|
1338 | *
|
1339 | * @returns A promise that resolves when the dialog has been accepted.
|
1340 | */
|
1341 | accept(promptText?: string): Promise<void>;
|
1342 | /**
|
1343 | * @returns A promise which will resolve once the dialog has been dismissed
|
1344 | */
|
1345 | dismiss(): Promise<void>;
|
1346 | }
|
1347 |
|
1348 | /**
|
1349 | * @internal
|
1350 | */
|
1351 | export declare class DOMWorld {
|
1352 | private _frameManager;
|
1353 | private _frame;
|
1354 | private _timeoutSettings;
|
1355 | private _documentPromise?;
|
1356 | private _contextPromise?;
|
1357 | private _contextResolveCallback?;
|
1358 | private _detached;
|
1359 | /**
|
1360 | * @internal
|
1361 | */
|
1362 | _waitTasks: Set<WaitTask>;
|
1363 | /**
|
1364 | * @internal
|
1365 | * Contains mapping from functions that should be bound to Puppeteer functions.
|
1366 | */
|
1367 | _boundFunctions: Map<string, Function>;
|
1368 | private _ctxBindings;
|
1369 | private static bindingIdentifier;
|
1370 | constructor(frameManager: FrameManager, frame: Frame, timeoutSettings: TimeoutSettings);
|
1371 | frame(): Frame;
|
1372 | _setContext(context?: ExecutionContext): Promise<void>;
|
1373 | _hasContext(): boolean;
|
1374 | _detach(): void;
|
1375 | executionContext(): Promise<ExecutionContext>;
|
1376 | evaluateHandle<HandlerType extends JSHandle = JSHandle>(pageFunction: EvaluateHandleFn, ...args: SerializableOrJSHandle[]): Promise<HandlerType>;
|
1377 | evaluate<T extends EvaluateFn>(pageFunction: T, ...args: SerializableOrJSHandle[]): Promise<UnwrapPromiseLike<EvaluateFnReturnType<T>>>;
|
1378 | $<T extends Element = Element>(selector: string): Promise<ElementHandle<T> | null>;
|
1379 | _document(): Promise<ElementHandle>;
|
1380 | $x(expression: string): Promise<ElementHandle[]>;
|
1381 | $eval<ReturnType>(selector: string, pageFunction: (element: Element, ...args: unknown[]) => ReturnType | Promise<ReturnType>, ...args: SerializableOrJSHandle[]): Promise<WrapElementHandle<ReturnType>>;
|
1382 | $$eval<ReturnType>(selector: string, pageFunction: (elements: Element[], ...args: unknown[]) => ReturnType | Promise<ReturnType>, ...args: SerializableOrJSHandle[]): Promise<WrapElementHandle<ReturnType>>;
|
1383 | $$<T extends Element = Element>(selector: string): Promise<Array<ElementHandle<T>>>;
|
1384 | content(): Promise<string>;
|
1385 | setContent(html: string, options?: {
|
1386 | timeout?: number;
|
1387 | waitUntil?: PuppeteerLifeCycleEvent | PuppeteerLifeCycleEvent[];
|
1388 | }): Promise<void>;
|
1389 | /**
|
1390 | * Adds a script tag into the current context.
|
1391 | *
|
1392 | * @remarks
|
1393 | *
|
1394 | * You can pass a URL, filepath or string of contents. Note that when running Puppeteer
|
1395 | * in a browser environment you cannot pass a filepath and should use either
|
1396 | * `url` or `content`.
|
1397 | */
|
1398 | addScriptTag(options: {
|
1399 | url?: string;
|
1400 | path?: string;
|
1401 | content?: string;
|
1402 | id?: string;
|
1403 | type?: string;
|
1404 | }): Promise<ElementHandle>;
|
1405 | /**
|
1406 | * Adds a style tag into the current context.
|
1407 | *
|
1408 | * @remarks
|
1409 | *
|
1410 | * You can pass a URL, filepath or string of contents. Note that when running Puppeteer
|
1411 | * in a browser environment you cannot pass a filepath and should use either
|
1412 | * `url` or `content`.
|
1413 | *
|
1414 | */
|
1415 | addStyleTag(options: {
|
1416 | url?: string;
|
1417 | path?: string;
|
1418 | content?: string;
|
1419 | }): Promise<ElementHandle>;
|
1420 | click(selector: string, options: {
|
1421 | delay?: number;
|
1422 | button?: MouseButton;
|
1423 | clickCount?: number;
|
1424 | }): Promise<void>;
|
1425 | focus(selector: string): Promise<void>;
|
1426 | hover(selector: string): Promise<void>;
|
1427 | select(selector: string, ...values: string[]): Promise<string[]>;
|
1428 | tap(selector: string): Promise<void>;
|
1429 | type(selector: string, text: string, options?: {
|
1430 | delay: number;
|
1431 | }): Promise<void>;
|
1432 | waitForSelector(selector: string, options: WaitForSelectorOptions): Promise<ElementHandle | null>;
|
1433 | private _settingUpBinding;
|
1434 | /**
|
1435 | * @internal
|
1436 | */
|
1437 | addBindingToContext(context: ExecutionContext, name: string): Promise<void>;
|
1438 | private _onBindingCalled;
|
1439 | /**
|
1440 | * @internal
|
1441 | */
|
1442 | waitForSelectorInPage(queryOne: Function, selector: string, options: WaitForSelectorOptions, binding?: PageBinding): Promise<ElementHandle | null>;
|
1443 | waitForXPath(xpath: string, options: WaitForSelectorOptions): Promise<ElementHandle | null>;
|
1444 | waitForFunction(pageFunction: Function | string, options?: {
|
1445 | polling?: string | number;
|
1446 | timeout?: number;
|
1447 | }, ...args: SerializableOrJSHandle[]): Promise<JSHandle>;
|
1448 | title(): Promise<string>;
|
1449 | }
|
1450 |
|
1451 | /**
|
1452 | * ElementHandle represents an in-page DOM element.
|
1453 | *
|
1454 | * @remarks
|
1455 | *
|
1456 | * ElementHandles can be created with the {@link Page.$} method.
|
1457 | *
|
1458 | * ```js
|
1459 | * const puppeteer = require('puppeteer');
|
1460 | *
|
1461 | * (async () => {
|
1462 | * const browser = await puppeteer.launch();
|
1463 | * const page = await browser.newPage();
|
1464 | * await page.goto('https://example.com');
|
1465 | * const hrefElement = await page.$('a');
|
1466 | * await hrefElement.click();
|
1467 | * // ...
|
1468 | * })();
|
1469 | * ```
|
1470 | *
|
1471 | * ElementHandle prevents the DOM element from being garbage-collected unless the
|
1472 | * handle is {@link JSHandle.dispose | disposed}. ElementHandles are auto-disposed
|
1473 | * when their origin frame gets navigated.
|
1474 | *
|
1475 | * ElementHandle instances can be used as arguments in {@link Page.$eval} and
|
1476 | * {@link Page.evaluate} methods.
|
1477 | *
|
1478 | * If you're using TypeScript, ElementHandle takes a generic argument that
|
1479 | * denotes the type of element the handle is holding within. For example, if you
|
1480 | * have a handle to a `<select>` element, you can type it as
|
1481 | * `ElementHandle<HTMLSelectElement>` and you get some nicer type checks.
|
1482 | *
|
1483 | * @public
|
1484 | */
|
1485 | export declare class ElementHandle<ElementType extends Element = Element> extends JSHandle<ElementType> {
|
1486 | private _page;
|
1487 | private _frameManager;
|
1488 | /**
|
1489 | * @internal
|
1490 | */
|
1491 | constructor(context: ExecutionContext, client: CDPSession, remoteObject: Protocol.Runtime.RemoteObject, page: Page, frameManager: FrameManager);
|
1492 | asElement(): ElementHandle<ElementType> | null;
|
1493 | /**
|
1494 | * Resolves to the content frame for element handles referencing
|
1495 | * iframe nodes, or null otherwise
|
1496 | */
|
1497 | contentFrame(): Promise<Frame | null>;
|
1498 | private _scrollIntoViewIfNeeded;
|
1499 | /**
|
1500 | * Returns the middle point within an element unless a specific offset is provided.
|
1501 | */
|
1502 | clickablePoint(offset?: Offset): Promise<Point>;
|
1503 | private _getBoxModel;
|
1504 | private _fromProtocolQuad;
|
1505 | private _intersectQuadWithViewport;
|
1506 | /**
|
1507 | * This method scrolls element into view if needed, and then
|
1508 | * uses {@link Page.mouse} to hover over the center of the element.
|
1509 | * If the element is detached from DOM, the method throws an error.
|
1510 | */
|
1511 | hover(): Promise<void>;
|
1512 | /**
|
1513 | * This method scrolls element into view if needed, and then
|
1514 | * uses {@link Page.mouse} to click in the center of the element.
|
1515 | * If the element is detached from DOM, the method throws an error.
|
1516 | */
|
1517 | click(options?: ClickOptions): Promise<void>;
|
1518 | /**
|
1519 | * This method creates and captures a dragevent from the element.
|
1520 | */
|
1521 | drag(target: Point): Promise<Protocol.Input.DragData>;
|
1522 | /**
|
1523 | * This method creates a `dragenter` event on the element.
|
1524 | */
|
1525 | dragEnter(data?: Protocol.Input.DragData): Promise<void>;
|
1526 | /**
|
1527 | * This method creates a `dragover` event on the element.
|
1528 | */
|
1529 | dragOver(data?: Protocol.Input.DragData): Promise<void>;
|
1530 | /**
|
1531 | * This method triggers a drop on the element.
|
1532 | */
|
1533 | drop(data?: Protocol.Input.DragData): Promise<void>;
|
1534 | /**
|
1535 | * This method triggers a dragenter, dragover, and drop on the element.
|
1536 | */
|
1537 | dragAndDrop(target: ElementHandle, options?: {
|
1538 | delay: number;
|
1539 | }): Promise<void>;
|
1540 | /**
|
1541 | * Triggers a `change` and `input` event once all the provided options have been
|
1542 | * selected. If there's no `<select>` element matching `selector`, the method
|
1543 | * throws an error.
|
1544 | *
|
1545 | * @example
|
1546 | * ```js
|
1547 | * handle.select('blue'); // single selection
|
1548 | * handle.select('red', 'green', 'blue'); // multiple selections
|
1549 | * ```
|
1550 | * @param values - Values of options to select. If the `<select>` has the
|
1551 | * `multiple` attribute, all values are considered, otherwise only the first
|
1552 | * one is taken into account.
|
1553 | */
|
1554 | select(...values: string[]): Promise<string[]>;
|
1555 | /**
|
1556 | * This method expects `elementHandle` to point to an
|
1557 | * {@link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input | input element}.
|
1558 | * @param filePaths - Sets the value of the file input to these paths.
|
1559 | * If some of the `filePaths` are relative paths, then they are resolved
|
1560 | * relative to the {@link https://nodejs.org/api/process.html#process_process_cwd | current working directory}
|
1561 | */
|
1562 | uploadFile(...filePaths: string[]): Promise<void>;
|
1563 | /**
|
1564 | * This method scrolls element into view if needed, and then uses
|
1565 | * {@link Touchscreen.tap} to tap in the center of the element.
|
1566 | * If the element is detached from DOM, the method throws an error.
|
1567 | */
|
1568 | tap(): Promise<void>;
|
1569 | /**
|
1570 | * Calls {@link https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/focus | focus} on the element.
|
1571 | */
|
1572 | focus(): Promise<void>;
|
1573 | /**
|
1574 | * Focuses the element, and then sends a `keydown`, `keypress`/`input`, and
|
1575 | * `keyup` event for each character in the text.
|
1576 | *
|
1577 | * To press a special key, like `Control` or `ArrowDown`,
|
1578 | * use {@link ElementHandle.press}.
|
1579 | *
|
1580 | * @example
|
1581 | * ```js
|
1582 | * await elementHandle.type('Hello'); // Types instantly
|
1583 | * await elementHandle.type('World', {delay: 100}); // Types slower, like a user
|
1584 | * ```
|
1585 | *
|
1586 | * @example
|
1587 | * An example of typing into a text field and then submitting the form:
|
1588 | *
|
1589 | * ```js
|
1590 | * const elementHandle = await page.$('input');
|
1591 | * await elementHandle.type('some text');
|
1592 | * await elementHandle.press('Enter');
|
1593 | * ```
|
1594 | */
|
1595 | type(text: string, options?: {
|
1596 | delay: number;
|
1597 | }): Promise<void>;
|
1598 | /**
|
1599 | * Focuses the element, and then uses {@link Keyboard.down} and {@link Keyboard.up}.
|
1600 | *
|
1601 | * @remarks
|
1602 | * If `key` is a single character and no modifier keys besides `Shift`
|
1603 | * are being held down, a `keypress`/`input` event will also be generated.
|
1604 | * The `text` option can be specified to force an input event to be generated.
|
1605 | *
|
1606 | * **NOTE** Modifier keys DO affect `elementHandle.press`. Holding down `Shift`
|
1607 | * will type the text in upper case.
|
1608 | *
|
1609 | * @param key - Name of key to press, such as `ArrowLeft`.
|
1610 | * See {@link KeyInput} for a list of all key names.
|
1611 | */
|
1612 | press(key: KeyInput, options?: PressOptions): Promise<void>;
|
1613 | /**
|
1614 | * This method returns the bounding box of the element (relative to the main frame),
|
1615 | * or `null` if the element is not visible.
|
1616 | */
|
1617 | boundingBox(): Promise<BoundingBox | null>;
|
1618 | /**
|
1619 | * This method returns boxes of the element, or `null` if the element is not visible.
|
1620 | *
|
1621 | * @remarks
|
1622 | *
|
1623 | * Boxes are represented as an array of points;
|
1624 | * Each Point is an object `{x, y}`. Box points are sorted clock-wise.
|
1625 | */
|
1626 | boxModel(): Promise<BoxModel | null>;
|
1627 | /**
|
1628 | * This method scrolls element into view if needed, and then uses
|
1629 | * {@link Page.screenshot} to take a screenshot of the element.
|
1630 | * If the element is detached from DOM, the method throws an error.
|
1631 | */
|
1632 | screenshot(options?: {}): Promise<string | Buffer | void>;
|
1633 | /**
|
1634 | * Runs `element.querySelector` within the page. If no element matches the selector,
|
1635 | * the return value resolves to `null`.
|
1636 | */
|
1637 | $<T extends Element = Element>(selector: string): Promise<ElementHandle<T> | null>;
|
1638 | /**
|
1639 | * Runs `element.querySelectorAll` within the page. If no elements match the selector,
|
1640 | * the return value resolves to `[]`.
|
1641 | */
|
1642 | $$<T extends Element = Element>(selector: string): Promise<Array<ElementHandle<T>>>;
|
1643 | /**
|
1644 | * This method runs `document.querySelector` within the element and passes it as
|
1645 | * the first argument to `pageFunction`. If there's no element matching `selector`,
|
1646 | * the method throws an error.
|
1647 | *
|
1648 | * If `pageFunction` returns a Promise, then `frame.$eval` would wait for the promise
|
1649 | * to resolve and return its value.
|
1650 | *
|
1651 | * @example
|
1652 | * ```js
|
1653 | * const tweetHandle = await page.$('.tweet');
|
1654 | * expect(await tweetHandle.$eval('.like', node => node.innerText)).toBe('100');
|
1655 | * expect(await tweetHandle.$eval('.retweets', node => node.innerText)).toBe('10');
|
1656 | * ```
|
1657 | */
|
1658 | $eval<ReturnType>(selector: string, pageFunction: (element: Element, ...args: unknown[]) => ReturnType | Promise<ReturnType>, ...args: SerializableOrJSHandle[]): Promise<WrapElementHandle<ReturnType>>;
|
1659 | /**
|
1660 | * This method runs `document.querySelectorAll` within the element and passes it as
|
1661 | * the first argument to `pageFunction`. If there's no element matching `selector`,
|
1662 | * the method throws an error.
|
1663 | *
|
1664 | * If `pageFunction` returns a Promise, then `frame.$$eval` would wait for the
|
1665 | * promise to resolve and return its value.
|
1666 | *
|
1667 | * @example
|
1668 | * ```html
|
1669 | * <div class="feed">
|
1670 | * <div class="tweet">Hello!</div>
|
1671 | * <div class="tweet">Hi!</div>
|
1672 | * </div>
|
1673 | * ```
|
1674 | *
|
1675 | * @example
|
1676 | * ```js
|
1677 | * const feedHandle = await page.$('.feed');
|
1678 | * expect(await feedHandle.$$eval('.tweet', nodes => nodes.map(n => n.innerText)))
|
1679 | * .toEqual(['Hello!', 'Hi!']);
|
1680 | * ```
|
1681 | */
|
1682 | $$eval<ReturnType>(selector: string, pageFunction: (elements: Element[], ...args: unknown[]) => ReturnType | Promise<ReturnType>, ...args: SerializableOrJSHandle[]): Promise<WrapElementHandle<ReturnType>>;
|
1683 | /**
|
1684 | * The method evaluates the XPath expression relative to the elementHandle.
|
1685 | * If there are no such elements, the method will resolve to an empty array.
|
1686 | * @param expression - Expression to {@link https://developer.mozilla.org/en-US/docs/Web/API/Document/evaluate | evaluate}
|
1687 | */
|
1688 | $x(expression: string): Promise<ElementHandle[]>;
|
1689 | /**
|
1690 | * Resolves to true if the element is visible in the current viewport.
|
1691 | */
|
1692 | isIntersectingViewport(options?: {
|
1693 | threshold?: number;
|
1694 | }): Promise<boolean>;
|
1695 | }
|
1696 |
|
1697 | /**
|
1698 | * @public
|
1699 | */
|
1700 | export declare type ErrorCode = 'aborted' | 'accessdenied' | 'addressunreachable' | 'blockedbyclient' | 'blockedbyresponse' | 'connectionaborted' | 'connectionclosed' | 'connectionfailed' | 'connectionrefused' | 'connectionreset' | 'internetdisconnected' | 'namenotresolved' | 'timedout' | 'failed';
|
1701 |
|
1702 | /**
|
1703 | * @public
|
1704 | */
|
1705 | export declare let errors: PuppeteerErrors;
|
1706 |
|
1707 | /**
|
1708 | * @public
|
1709 | */
|
1710 | export declare type EvaluateFn<T = any> = string | ((arg1: T, ...args: any[]) => any);
|
1711 |
|
1712 | /**
|
1713 | * @public
|
1714 | */
|
1715 | export declare type EvaluateFnReturnType<T extends EvaluateFn> = T extends (...args: any[]) => infer R ? R : any;
|
1716 |
|
1717 | /**
|
1718 | * @public
|
1719 | */
|
1720 | export declare type EvaluateHandleFn = string | ((...args: any[]) => any);
|
1721 |
|
1722 | /**
|
1723 | * @public
|
1724 | */
|
1725 | export declare const EVALUATION_SCRIPT_URL = "__puppeteer_evaluation_script__";
|
1726 |
|
1727 | /**
|
1728 | * The EventEmitter class that many Puppeteer classes extend.
|
1729 | *
|
1730 | * @remarks
|
1731 | *
|
1732 | * This allows you to listen to events that Puppeteer classes fire and act
|
1733 | * accordingly. Therefore you'll mostly use {@link EventEmitter.on | on} and
|
1734 | * {@link EventEmitter.off | off} to bind
|
1735 | * and unbind to event listeners.
|
1736 | *
|
1737 | * @public
|
1738 | */
|
1739 | export declare class EventEmitter implements CommonEventEmitter {
|
1740 | private emitter;
|
1741 | private eventsMap;
|
1742 | /**
|
1743 | * @internal
|
1744 | */
|
1745 | constructor();
|
1746 | /**
|
1747 | * Bind an event listener to fire when an event occurs.
|
1748 | * @param event - the event type you'd like to listen to. Can be a string or symbol.
|
1749 | * @param handler - the function to be called when the event occurs.
|
1750 | * @returns `this` to enable you to chain method calls.
|
1751 | */
|
1752 | on(event: EventType, handler: Handler): EventEmitter;
|
1753 | /**
|
1754 | * Remove an event listener from firing.
|
1755 | * @param event - the event type you'd like to stop listening to.
|
1756 | * @param handler - the function that should be removed.
|
1757 | * @returns `this` to enable you to chain method calls.
|
1758 | */
|
1759 | off(event: EventType, handler: Handler): EventEmitter;
|
1760 | /**
|
1761 | * Remove an event listener.
|
1762 | * @deprecated please use {@link EventEmitter.off} instead.
|
1763 | */
|
1764 | removeListener(event: EventType, handler: Handler): EventEmitter;
|
1765 | /**
|
1766 | * Add an event listener.
|
1767 | * @deprecated please use {@link EventEmitter.on} instead.
|
1768 | */
|
1769 | addListener(event: EventType, handler: Handler): EventEmitter;
|
1770 | /**
|
1771 | * Emit an event and call any associated listeners.
|
1772 | *
|
1773 | * @param event - the event you'd like to emit
|
1774 | * @param eventData - any data you'd like to emit with the event
|
1775 | * @returns `true` if there are any listeners, `false` if there are not.
|
1776 | */
|
1777 | emit(event: EventType, eventData?: unknown): boolean;
|
1778 | /**
|
1779 | * Like `on` but the listener will only be fired once and then it will be removed.
|
1780 | * @param event - the event you'd like to listen to
|
1781 | * @param handler - the handler function to run when the event occurs
|
1782 | * @returns `this` to enable you to chain method calls.
|
1783 | */
|
1784 | once(event: EventType, handler: Handler): EventEmitter;
|
1785 | /**
|
1786 | * Gets the number of listeners for a given event.
|
1787 | *
|
1788 | * @param event - the event to get the listener count for
|
1789 | * @returns the number of listeners bound to the given event
|
1790 | */
|
1791 | listenerCount(event: EventType): number;
|
1792 | /**
|
1793 | * Removes all listeners. If given an event argument, it will remove only
|
1794 | * listeners for that event.
|
1795 | * @param event - the event to remove listeners for.
|
1796 | * @returns `this` to enable you to chain method calls.
|
1797 | */
|
1798 | removeAllListeners(event?: EventType): EventEmitter;
|
1799 | private eventListenersCount;
|
1800 | }
|
1801 |
|
1802 | /**
|
1803 | * @public
|
1804 | */
|
1805 | export declare type EventType = string | symbol;
|
1806 |
|
1807 | /**
|
1808 | * @internal
|
1809 | */
|
1810 | export declare type ExceptionThrownCallback = (details: Protocol.Runtime.ExceptionDetails) => void;
|
1811 |
|
1812 | /**
|
1813 | * This class represents a context for JavaScript execution. A [Page] might have
|
1814 | * many execution contexts:
|
1815 | * - each
|
1816 | * {@link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe |
|
1817 | * frame } has "default" execution context that is always created after frame is
|
1818 | * attached to DOM. This context is returned by the
|
1819 | * {@link Frame.executionContext} method.
|
1820 | * - {@link https://developer.chrome.com/extensions | Extension}'s content scripts
|
1821 | * create additional execution contexts.
|
1822 | *
|
1823 | * Besides pages, execution contexts can be found in
|
1824 | * {@link https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API |
|
1825 | * workers }.
|
1826 | *
|
1827 | * @public
|
1828 | */
|
1829 | export declare class ExecutionContext {
|
1830 | /**
|
1831 | * @internal
|
1832 | */
|
1833 | _client: CDPSession;
|
1834 | /**
|
1835 | * @internal
|
1836 | */
|
1837 | _world: DOMWorld;
|
1838 | /**
|
1839 | * @internal
|
1840 | */
|
1841 | _contextId: number;
|
1842 | /**
|
1843 | * @internal
|
1844 | */
|
1845 | _contextName: string;
|
1846 | /**
|
1847 | * @internal
|
1848 | */
|
1849 | constructor(client: CDPSession, contextPayload: Protocol.Runtime.ExecutionContextDescription, world: DOMWorld);
|
1850 | /**
|
1851 | * @remarks
|
1852 | *
|
1853 | * Not every execution context is associated with a frame. For
|
1854 | * example, workers and extensions have execution contexts that are not
|
1855 | * associated with frames.
|
1856 | *
|
1857 | * @returns The frame associated with this execution context.
|
1858 | */
|
1859 | frame(): Frame | null;
|
1860 | /**
|
1861 | * @remarks
|
1862 | * If the function passed to the `executionContext.evaluate` returns a
|
1863 | * Promise, then `executionContext.evaluate` would wait for the promise to
|
1864 | * resolve and return its value. If the function passed to the
|
1865 | * `executionContext.evaluate` returns a non-serializable value, then
|
1866 | * `executionContext.evaluate` resolves to `undefined`. DevTools Protocol also
|
1867 | * supports transferring some additional values that are not serializable by
|
1868 | * `JSON`: `-0`, `NaN`, `Infinity`, `-Infinity`, and bigint literals.
|
1869 | *
|
1870 | *
|
1871 | * @example
|
1872 | * ```js
|
1873 | * const executionContext = await page.mainFrame().executionContext();
|
1874 | * const result = await executionContext.evaluate(() => Promise.resolve(8 * 7))* ;
|
1875 | * console.log(result); // prints "56"
|
1876 | * ```
|
1877 | *
|
1878 | * @example
|
1879 | * A string can also be passed in instead of a function.
|
1880 | *
|
1881 | * ```js
|
1882 | * console.log(await executionContext.evaluate('1 + 2')); // prints "3"
|
1883 | * ```
|
1884 | *
|
1885 | * @example
|
1886 | * {@link JSHandle} instances can be passed as arguments to the
|
1887 | * `executionContext.* evaluate`:
|
1888 | * ```js
|
1889 | * const oneHandle = await executionContext.evaluateHandle(() => 1);
|
1890 | * const twoHandle = await executionContext.evaluateHandle(() => 2);
|
1891 | * const result = await executionContext.evaluate(
|
1892 | * (a, b) => a + b, oneHandle, * twoHandle
|
1893 | * );
|
1894 | * await oneHandle.dispose();
|
1895 | * await twoHandle.dispose();
|
1896 | * console.log(result); // prints '3'.
|
1897 | * ```
|
1898 | * @param pageFunction - a function to be evaluated in the `executionContext`
|
1899 | * @param args - argument to pass to the page function
|
1900 | *
|
1901 | * @returns A promise that resolves to the return value of the given function.
|
1902 | */
|
1903 | evaluate<ReturnType extends any>(pageFunction: Function | string, ...args: unknown[]): Promise<ReturnType>;
|
1904 | /**
|
1905 | * @remarks
|
1906 | * The only difference between `executionContext.evaluate` and
|
1907 | * `executionContext.evaluateHandle` is that `executionContext.evaluateHandle`
|
1908 | * returns an in-page object (a {@link JSHandle}).
|
1909 | * If the function passed to the `executionContext.evaluateHandle` returns a
|
1910 | * Promise, then `executionContext.evaluateHandle` would wait for the
|
1911 | * promise to resolve and return its value.
|
1912 | *
|
1913 | * @example
|
1914 | * ```js
|
1915 | * const context = await page.mainFrame().executionContext();
|
1916 | * const aHandle = await context.evaluateHandle(() => Promise.resolve(self));
|
1917 | * aHandle; // Handle for the global object.
|
1918 | * ```
|
1919 | *
|
1920 | * @example
|
1921 | * A string can also be passed in instead of a function.
|
1922 | *
|
1923 | * ```js
|
1924 | * // Handle for the '3' * object.
|
1925 | * const aHandle = await context.evaluateHandle('1 + 2');
|
1926 | * ```
|
1927 | *
|
1928 | * @example
|
1929 | * JSHandle instances can be passed as arguments
|
1930 | * to the `executionContext.* evaluateHandle`:
|
1931 | *
|
1932 | * ```js
|
1933 | * const aHandle = await context.evaluateHandle(() => document.body);
|
1934 | * const resultHandle = await context.evaluateHandle(body => body.innerHTML, * aHandle);
|
1935 | * console.log(await resultHandle.jsonValue()); // prints body's innerHTML
|
1936 | * await aHandle.dispose();
|
1937 | * await resultHandle.dispose();
|
1938 | * ```
|
1939 | *
|
1940 | * @param pageFunction - a function to be evaluated in the `executionContext`
|
1941 | * @param args - argument to pass to the page function
|
1942 | *
|
1943 | * @returns A promise that resolves to the return value of the given function
|
1944 | * as an in-page object (a {@link JSHandle}).
|
1945 | */
|
1946 | evaluateHandle<HandleType extends JSHandle | ElementHandle = JSHandle>(pageFunction: EvaluateHandleFn, ...args: SerializableOrJSHandle[]): Promise<HandleType>;
|
1947 | private _evaluateInternal;
|
1948 | /**
|
1949 | * This method iterates the JavaScript heap and finds all the objects with the
|
1950 | * given prototype.
|
1951 | * @remarks
|
1952 | * @example
|
1953 | * ```js
|
1954 | * // Create a Map object
|
1955 | * await page.evaluate(() => window.map = new Map());
|
1956 | * // Get a handle to the Map object prototype
|
1957 | * const mapPrototype = await page.evaluateHandle(() => Map.prototype);
|
1958 | * // Query all map instances into an array
|
1959 | * const mapInstances = await page.queryObjects(mapPrototype);
|
1960 | * // Count amount of map objects in heap
|
1961 | * const count = await page.evaluate(maps => maps.length, mapInstances);
|
1962 | * await mapInstances.dispose();
|
1963 | * await mapPrototype.dispose();
|
1964 | * ```
|
1965 | *
|
1966 | * @param prototypeHandle - a handle to the object prototype
|
1967 | *
|
1968 | * @returns A handle to an array of objects with the given prototype.
|
1969 | */
|
1970 | queryObjects(prototypeHandle: JSHandle): Promise<JSHandle>;
|
1971 | /**
|
1972 | * @internal
|
1973 | */
|
1974 | _adoptBackendNodeId(backendNodeId: Protocol.DOM.BackendNodeId): Promise<ElementHandle>;
|
1975 | /**
|
1976 | * @internal
|
1977 | */
|
1978 | _adoptElementHandle(elementHandle: ElementHandle): Promise<ElementHandle>;
|
1979 | }
|
1980 |
|
1981 | /**
|
1982 | * File choosers let you react to the page requesting for a file.
|
1983 | * @remarks
|
1984 | * `FileChooser` objects are returned via the `page.waitForFileChooser` method.
|
1985 | * @example
|
1986 | * An example of using `FileChooser`:
|
1987 | * ```js
|
1988 | * const [fileChooser] = await Promise.all([
|
1989 | * page.waitForFileChooser(),
|
1990 | * page.click('#upload-file-button'), // some button that triggers file selection
|
1991 | * ]);
|
1992 | * await fileChooser.accept(['/tmp/myfile.pdf']);
|
1993 | * ```
|
1994 | * **NOTE** In browsers, only one file chooser can be opened at a time.
|
1995 | * All file choosers must be accepted or canceled. Not doing so will prevent
|
1996 | * subsequent file choosers from appearing.
|
1997 | * @public
|
1998 | */
|
1999 | export declare class FileChooser {
|
2000 | private _element;
|
2001 | private _multiple;
|
2002 | private _handled;
|
2003 | /**
|
2004 | * @internal
|
2005 | */
|
2006 | constructor(element: ElementHandle, event: Protocol.Page.FileChooserOpenedEvent);
|
2007 | /**
|
2008 | * Whether file chooser allow for {@link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/file#attr-multiple | multiple} file selection.
|
2009 | */
|
2010 | isMultiple(): boolean;
|
2011 | /**
|
2012 | * Accept the file chooser request with given paths.
|
2013 | * @param filePaths - If some of the `filePaths` are relative paths,
|
2014 | * then they are resolved relative to the {@link https://nodejs.org/api/process.html#process_process_cwd | current working directory}.
|
2015 | */
|
2016 | accept(filePaths: string[]): Promise<void>;
|
2017 | /**
|
2018 | * Closes the file chooser without selecting any files.
|
2019 | */
|
2020 | cancel(): void;
|
2021 | }
|
2022 |
|
2023 | /**
|
2024 | * At every point of time, page exposes its current frame tree via the
|
2025 | * {@link Page.mainFrame | page.mainFrame} and
|
2026 | * {@link Frame.childFrames | frame.childFrames} methods.
|
2027 | *
|
2028 | * @remarks
|
2029 | *
|
2030 | * `Frame` object lifecycles are controlled by three events that are all
|
2031 | * dispatched on the page object:
|
2032 | *
|
2033 | * - {@link PageEmittedEvents.FrameAttached}
|
2034 | *
|
2035 | * - {@link PageEmittedEvents.FrameNavigated}
|
2036 | *
|
2037 | * - {@link PageEmittedEvents.FrameDetached}
|
2038 | *
|
2039 | * @Example
|
2040 | * An example of dumping frame tree:
|
2041 | *
|
2042 | * ```js
|
2043 | * const puppeteer = require('puppeteer');
|
2044 | *
|
2045 | * (async () => {
|
2046 | * const browser = await puppeteer.launch();
|
2047 | * const page = await browser.newPage();
|
2048 | * await page.goto('https://www.google.com/chrome/browser/canary.html');
|
2049 | * dumpFrameTree(page.mainFrame(), '');
|
2050 | * await browser.close();
|
2051 | *
|
2052 | * function dumpFrameTree(frame, indent) {
|
2053 | * console.log(indent + frame.url());
|
2054 | * for (const child of frame.childFrames()) {
|
2055 | * dumpFrameTree(child, indent + ' ');
|
2056 | * }
|
2057 | * }
|
2058 | * })();
|
2059 | * ```
|
2060 | *
|
2061 | * @Example
|
2062 | * An example of getting text from an iframe element:
|
2063 | *
|
2064 | * ```js
|
2065 | * const frame = page.frames().find(frame => frame.name() === 'myframe');
|
2066 | * const text = await frame.$eval('.selector', element => element.textContent);
|
2067 | * console.log(text);
|
2068 | * ```
|
2069 | *
|
2070 | * @public
|
2071 | */
|
2072 | export declare class Frame {
|
2073 | /**
|
2074 | * @internal
|
2075 | */
|
2076 | _frameManager: FrameManager;
|
2077 | private _parentFrame?;
|
2078 | /**
|
2079 | * @internal
|
2080 | */
|
2081 | _id: string;
|
2082 | private _url;
|
2083 | private _detached;
|
2084 | /**
|
2085 | * @internal
|
2086 | */
|
2087 | _loaderId: string;
|
2088 | /**
|
2089 | * @internal
|
2090 | */
|
2091 | _name?: string;
|
2092 | /**
|
2093 | * @internal
|
2094 | */
|
2095 | _lifecycleEvents: Set<string>;
|
2096 | /**
|
2097 | * @internal
|
2098 | */
|
2099 | _mainWorld: DOMWorld;
|
2100 | /**
|
2101 | * @internal
|
2102 | */
|
2103 | _secondaryWorld: DOMWorld;
|
2104 | /**
|
2105 | * @internal
|
2106 | */
|
2107 | _childFrames: Set<Frame>;
|
2108 | /**
|
2109 | * @internal
|
2110 | */
|
2111 | constructor(frameManager: FrameManager, parentFrame: Frame | null, frameId: string);
|
2112 | /**
|
2113 | * @remarks
|
2114 | *
|
2115 | * `frame.goto` will throw an error if:
|
2116 | * - there's an SSL error (e.g. in case of self-signed certificates).
|
2117 | *
|
2118 | * - target URL is invalid.
|
2119 | *
|
2120 | * - the `timeout` is exceeded during navigation.
|
2121 | *
|
2122 | * - the remote server does not respond or is unreachable.
|
2123 | *
|
2124 | * - the main resource failed to load.
|
2125 | *
|
2126 | * `frame.goto` will not throw an error when any valid HTTP status code is
|
2127 | * returned by the remote server, including 404 "Not Found" and 500 "Internal
|
2128 | * Server Error". The status code for such responses can be retrieved by
|
2129 | * calling {@link HTTPResponse.status}.
|
2130 | *
|
2131 | * NOTE: `frame.goto` either throws an error or returns a main resource
|
2132 | * response. The only exceptions are navigation to `about:blank` or
|
2133 | * navigation to the same URL with a different hash, which would succeed and
|
2134 | * return `null`.
|
2135 | *
|
2136 | * NOTE: Headless mode doesn't support navigation to a PDF document. See
|
2137 | * the {@link https://bugs.chromium.org/p/chromium/issues/detail?id=761295 | upstream
|
2138 | * issue}.
|
2139 | *
|
2140 | * @param url - the URL to navigate the frame to. This should include the
|
2141 | * scheme, e.g. `https://`.
|
2142 | * @param options - navigation options. `waitUntil` is useful to define when
|
2143 | * the navigation should be considered successful - see the docs for
|
2144 | * {@link PuppeteerLifeCycleEvent} for more details.
|
2145 | *
|
2146 | * @returns A promise which resolves to the main resource response. In case of
|
2147 | * multiple redirects, the navigation will resolve with the response of the
|
2148 | * last redirect.
|
2149 | */
|
2150 | goto(url: string, options?: {
|
2151 | referer?: string;
|
2152 | timeout?: number;
|
2153 | waitUntil?: PuppeteerLifeCycleEvent | PuppeteerLifeCycleEvent[];
|
2154 | }): Promise<HTTPResponse | null>;
|
2155 | /**
|
2156 | * @remarks
|
2157 | *
|
2158 | * This resolves when the frame navigates to a new URL. It is useful for when
|
2159 | * you run code which will indirectly cause the frame to navigate. Consider
|
2160 | * this example:
|
2161 | *
|
2162 | * ```js
|
2163 | * const [response] = await Promise.all([
|
2164 | * // The navigation promise resolves after navigation has finished
|
2165 | * frame.waitForNavigation(),
|
2166 | * // Clicking the link will indirectly cause a navigation
|
2167 | * frame.click('a.my-link'),
|
2168 | * ]);
|
2169 | * ```
|
2170 | *
|
2171 | * Usage of the {@link https://developer.mozilla.org/en-US/docs/Web/API/History_API | History API} to change the URL is considered a navigation.
|
2172 | *
|
2173 | * @param options - options to configure when the navigation is consided finished.
|
2174 | * @returns a promise that resolves when the frame navigates to a new URL.
|
2175 | */
|
2176 | waitForNavigation(options?: {
|
2177 | timeout?: number;
|
2178 | waitUntil?: PuppeteerLifeCycleEvent | PuppeteerLifeCycleEvent[];
|
2179 | }): Promise<HTTPResponse | null>;
|
2180 | /**
|
2181 | * @returns a promise that resolves to the frame's default execution context.
|
2182 | */
|
2183 | executionContext(): Promise<ExecutionContext>;
|
2184 | /**
|
2185 | * @remarks
|
2186 | *
|
2187 | * The only difference between {@link Frame.evaluate} and
|
2188 | * `frame.evaluateHandle` is that `evaluateHandle` will return the value
|
2189 | * wrapped in an in-page object.
|
2190 | *
|
2191 | * This method behaves identically to {@link Page.evaluateHandle} except it's
|
2192 | * run within the context of the `frame`, rather than the entire page.
|
2193 | *
|
2194 | * @param pageFunction - a function that is run within the frame
|
2195 | * @param args - arguments to be passed to the pageFunction
|
2196 | */
|
2197 | evaluateHandle<HandlerType extends JSHandle = JSHandle>(pageFunction: EvaluateHandleFn, ...args: SerializableOrJSHandle[]): Promise<HandlerType>;
|
2198 | /**
|
2199 | * @remarks
|
2200 | *
|
2201 | * This method behaves identically to {@link Page.evaluate} except it's run
|
2202 | * within the context of the `frame`, rather than the entire page.
|
2203 | *
|
2204 | * @param pageFunction - a function that is run within the frame
|
2205 | * @param args - arguments to be passed to the pageFunction
|
2206 | */
|
2207 | evaluate<T extends EvaluateFn>(pageFunction: T, ...args: SerializableOrJSHandle[]): Promise<UnwrapPromiseLike<EvaluateFnReturnType<T>>>;
|
2208 | /**
|
2209 | * This method queries the frame for the given selector.
|
2210 | *
|
2211 | * @param selector - a selector to query for.
|
2212 | * @returns A promise which resolves to an `ElementHandle` pointing at the
|
2213 | * element, or `null` if it was not found.
|
2214 | */
|
2215 | $<T extends Element = Element>(selector: string): Promise<ElementHandle<T> | null>;
|
2216 | /**
|
2217 | * This method evaluates the given XPath expression and returns the results.
|
2218 | *
|
2219 | * @param expression - the XPath expression to evaluate.
|
2220 | */
|
2221 | $x(expression: string): Promise<ElementHandle[]>;
|
2222 | /**
|
2223 | * @remarks
|
2224 | *
|
2225 | * This method runs `document.querySelector` within
|
2226 | * the frame and passes it as the first argument to `pageFunction`.
|
2227 | *
|
2228 | * If `pageFunction` returns a Promise, then `frame.$eval` would wait for
|
2229 | * the promise to resolve and return its value.
|
2230 | *
|
2231 | * @example
|
2232 | *
|
2233 | * ```js
|
2234 | * const searchValue = await frame.$eval('#search', el => el.value);
|
2235 | * ```
|
2236 | *
|
2237 | * @param selector - the selector to query for
|
2238 | * @param pageFunction - the function to be evaluated in the frame's context
|
2239 | * @param args - additional arguments to pass to `pageFuncton`
|
2240 | */
|
2241 | $eval<ReturnType>(selector: string, pageFunction: (element: Element, ...args: unknown[]) => ReturnType | Promise<ReturnType>, ...args: SerializableOrJSHandle[]): Promise<WrapElementHandle<ReturnType>>;
|
2242 | /**
|
2243 | * @remarks
|
2244 | *
|
2245 | * This method runs `Array.from(document.querySelectorAll(selector))` within
|
2246 | * the frame and passes it as the first argument to `pageFunction`.
|
2247 | *
|
2248 | * If `pageFunction` returns a Promise, then `frame.$$eval` would wait for
|
2249 | * the promise to resolve and return its value.
|
2250 | *
|
2251 | * @example
|
2252 | *
|
2253 | * ```js
|
2254 | * const divsCounts = await frame.$$eval('div', divs => divs.length);
|
2255 | * ```
|
2256 | *
|
2257 | * @param selector - the selector to query for
|
2258 | * @param pageFunction - the function to be evaluated in the frame's context
|
2259 | * @param args - additional arguments to pass to `pageFuncton`
|
2260 | */
|
2261 | $$eval<ReturnType>(selector: string, pageFunction: (elements: Element[], ...args: unknown[]) => ReturnType | Promise<ReturnType>, ...args: SerializableOrJSHandle[]): Promise<WrapElementHandle<ReturnType>>;
|
2262 | /**
|
2263 | * This runs `document.querySelectorAll` in the frame and returns the result.
|
2264 | *
|
2265 | * @param selector - a selector to search for
|
2266 | * @returns An array of element handles pointing to the found frame elements.
|
2267 | */
|
2268 | $$<T extends Element = Element>(selector: string): Promise<Array<ElementHandle<T>>>;
|
2269 | /**
|
2270 | * @returns the full HTML contents of the frame, including the doctype.
|
2271 | */
|
2272 | content(): Promise<string>;
|
2273 | /**
|
2274 | * Set the content of the frame.
|
2275 | *
|
2276 | * @param html - HTML markup to assign to the page.
|
2277 | * @param options - options to configure how long before timing out and at
|
2278 | * what point to consider the content setting successful.
|
2279 | */
|
2280 | setContent(html: string, options?: {
|
2281 | timeout?: number;
|
2282 | waitUntil?: PuppeteerLifeCycleEvent | PuppeteerLifeCycleEvent[];
|
2283 | }): Promise<void>;
|
2284 | /**
|
2285 | * @remarks
|
2286 | *
|
2287 | * If the name is empty, it returns the `id` attribute instead.
|
2288 | *
|
2289 | * Note: This value is calculated once when the frame is created, and will not
|
2290 | * update if the attribute is changed later.
|
2291 | *
|
2292 | * @returns the frame's `name` attribute as specified in the tag.
|
2293 | */
|
2294 | name(): string;
|
2295 | /**
|
2296 | * @returns the frame's URL.
|
2297 | */
|
2298 | url(): string;
|
2299 | /**
|
2300 | * @returns the parent `Frame`, if any. Detached and main frames return `null`.
|
2301 | */
|
2302 | parentFrame(): Frame | null;
|
2303 | /**
|
2304 | * @returns an array of child frames.
|
2305 | */
|
2306 | childFrames(): Frame[];
|
2307 | /**
|
2308 | * @returns `true` if the frame has been detached, or `false` otherwise.
|
2309 | */
|
2310 | isDetached(): boolean;
|
2311 | /**
|
2312 | * Adds a `<script>` tag into the page with the desired url or content.
|
2313 | *
|
2314 | * @param options - configure the script to add to the page.
|
2315 | *
|
2316 | * @returns a promise that resolves to the added tag when the script's
|
2317 | * `onload` event fires or when the script content was injected into the
|
2318 | * frame.
|
2319 | */
|
2320 | addScriptTag(options: FrameAddScriptTagOptions): Promise<ElementHandle>;
|
2321 | /**
|
2322 | * Adds a `<link rel="stylesheet">` tag into the page with the desired url or
|
2323 | * a `<style type="text/css">` tag with the content.
|
2324 | *
|
2325 | * @param options - configure the CSS to add to the page.
|
2326 | *
|
2327 | * @returns a promise that resolves to the added tag when the stylesheets's
|
2328 | * `onload` event fires or when the CSS content was injected into the
|
2329 | * frame.
|
2330 | */
|
2331 | addStyleTag(options: FrameAddStyleTagOptions): Promise<ElementHandle>;
|
2332 | /**
|
2333 | *
|
2334 | * This method clicks the first element found that matches `selector`.
|
2335 | *
|
2336 | * @remarks
|
2337 | *
|
2338 | * This method scrolls the element into view if needed, and then uses
|
2339 | * {@link Page.mouse} to click in the center of the element. If there's no
|
2340 | * element matching `selector`, the method throws an error.
|
2341 | *
|
2342 | * Bear in mind that if `click()` triggers a navigation event and there's a
|
2343 | * separate `page.waitForNavigation()` promise to be resolved, you may end up
|
2344 | * with a race condition that yields unexpected results. The correct pattern
|
2345 | * for click and wait for navigation is the following:
|
2346 | *
|
2347 | * ```javascript
|
2348 | * const [response] = await Promise.all([
|
2349 | * page.waitForNavigation(waitOptions),
|
2350 | * frame.click(selector, clickOptions),
|
2351 | * ]);
|
2352 | * ```
|
2353 | * @param selector - the selector to search for to click. If there are
|
2354 | * multiple elements, the first will be clicked.
|
2355 | */
|
2356 | click(selector: string, options?: {
|
2357 | delay?: number;
|
2358 | button?: MouseButton;
|
2359 | clickCount?: number;
|
2360 | }): Promise<void>;
|
2361 | /**
|
2362 | * This method fetches an element with `selector` and focuses it.
|
2363 | *
|
2364 | * @remarks
|
2365 | * If there's no element matching `selector`, the method throws an error.
|
2366 | *
|
2367 | * @param selector - the selector for the element to focus. If there are
|
2368 | * multiple elements, the first will be focused.
|
2369 | */
|
2370 | focus(selector: string): Promise<void>;
|
2371 | /**
|
2372 | * This method fetches an element with `selector`, scrolls it into view if
|
2373 | * needed, and then uses {@link Page.mouse} to hover over the center of the
|
2374 | * element.
|
2375 | *
|
2376 | * @remarks
|
2377 | * If there's no element matching `selector`, the method throws an
|
2378 | *
|
2379 | * @param selector - the selector for the element to hover. If there are
|
2380 | * multiple elements, the first will be hovered.
|
2381 | */
|
2382 | hover(selector: string): Promise<void>;
|
2383 | /**
|
2384 | * Triggers a `change` and `input` event once all the provided options have
|
2385 | * been selected.
|
2386 | *
|
2387 | * @remarks
|
2388 | *
|
2389 | * If there's no `<select>` element matching `selector`, the
|
2390 | * method throws an error.
|
2391 | *
|
2392 | * @example
|
2393 | * ```js
|
2394 | * frame.select('select#colors', 'blue'); // single selection
|
2395 | * frame.select('select#colors', 'red', 'green', 'blue'); // multiple selections
|
2396 | * ```
|
2397 | *
|
2398 | * @param selector - a selector to query the frame for
|
2399 | * @param values - an array of values to select. If the `<select>` has the
|
2400 | * `multiple` attribute, all values are considered, otherwise only the first
|
2401 | * one is taken into account.
|
2402 | * @returns the list of values that were successfully selected.
|
2403 | */
|
2404 | select(selector: string, ...values: string[]): Promise<string[]>;
|
2405 | /**
|
2406 | * This method fetches an element with `selector`, scrolls it into view if
|
2407 | * needed, and then uses {@link Page.touchscreen} to tap in the center of the
|
2408 | * element.
|
2409 | *
|
2410 | * @remarks
|
2411 | *
|
2412 | * If there's no element matching `selector`, the method throws an error.
|
2413 | *
|
2414 | * @param selector - the selector to tap.
|
2415 | * @returns a promise that resolves when the element has been tapped.
|
2416 | */
|
2417 | tap(selector: string): Promise<void>;
|
2418 | /**
|
2419 | * Sends a `keydown`, `keypress`/`input`, and `keyup` event for each character
|
2420 | * in the text.
|
2421 | *
|
2422 | * @remarks
|
2423 | * To press a special key, like `Control` or `ArrowDown`, use
|
2424 | * {@link Keyboard.press}.
|
2425 | *
|
2426 | * @example
|
2427 | * ```js
|
2428 | * await frame.type('#mytextarea', 'Hello'); // Types instantly
|
2429 | * await frame.type('#mytextarea', 'World', {delay: 100}); // Types slower, like a user
|
2430 | * ```
|
2431 | *
|
2432 | * @param selector - the selector for the element to type into. If there are
|
2433 | * multiple the first will be used.
|
2434 | * @param text - text to type into the element
|
2435 | * @param options - takes one option, `delay`, which sets the time to wait
|
2436 | * between key presses in milliseconds. Defaults to `0`.
|
2437 | *
|
2438 | * @returns a promise that resolves when the typing is complete.
|
2439 | */
|
2440 | type(selector: string, text: string, options?: {
|
2441 | delay: number;
|
2442 | }): Promise<void>;
|
2443 | /**
|
2444 | * @remarks
|
2445 | *
|
2446 | * This method behaves differently depending on the first parameter. If it's a
|
2447 | * `string`, it will be treated as a `selector` or `xpath` (if the string
|
2448 | * starts with `//`). This method then is a shortcut for
|
2449 | * {@link Frame.waitForSelector} or {@link Frame.waitForXPath}.
|
2450 | *
|
2451 | * If the first argument is a function this method is a shortcut for
|
2452 | * {@link Frame.waitForFunction}.
|
2453 | *
|
2454 | * If the first argument is a `number`, it's treated as a timeout in
|
2455 | * milliseconds and the method returns a promise which resolves after the
|
2456 | * timeout.
|
2457 | *
|
2458 | * @param selectorOrFunctionOrTimeout - a selector, predicate or timeout to
|
2459 | * wait for.
|
2460 | * @param options - optional waiting parameters.
|
2461 | * @param args - arguments to pass to `pageFunction`.
|
2462 | *
|
2463 | * @deprecated Don't use this method directly. Instead use the more explicit
|
2464 | * methods available: {@link Frame.waitForSelector},
|
2465 | * {@link Frame.waitForXPath}, {@link Frame.waitForFunction} or
|
2466 | * {@link Frame.waitForTimeout}.
|
2467 | */
|
2468 | waitFor(selectorOrFunctionOrTimeout: string | number | Function, options?: Record<string, unknown>, ...args: SerializableOrJSHandle[]): Promise<JSHandle | null>;
|
2469 | /**
|
2470 | * Causes your script to wait for the given number of milliseconds.
|
2471 | *
|
2472 | * @remarks
|
2473 | * It's generally recommended to not wait for a number of seconds, but instead
|
2474 | * use {@link Frame.waitForSelector}, {@link Frame.waitForXPath} or
|
2475 | * {@link Frame.waitForFunction} to wait for exactly the conditions you want.
|
2476 | *
|
2477 | * @example
|
2478 | *
|
2479 | * Wait for 1 second:
|
2480 | *
|
2481 | * ```
|
2482 | * await frame.waitForTimeout(1000);
|
2483 | * ```
|
2484 | *
|
2485 | * @param milliseconds - the number of milliseconds to wait.
|
2486 | */
|
2487 | waitForTimeout(milliseconds: number): Promise<void>;
|
2488 | /**
|
2489 | * @remarks
|
2490 | *
|
2491 | *
|
2492 | * Wait for the `selector` to appear in page. If at the moment of calling the
|
2493 | * method the `selector` already exists, the method will return immediately.
|
2494 | * If the selector doesn't appear after the `timeout` milliseconds of waiting,
|
2495 | * the function will throw.
|
2496 | *
|
2497 | * This method works across navigations.
|
2498 | *
|
2499 | * @example
|
2500 | * ```js
|
2501 | * const puppeteer = require('puppeteer');
|
2502 | *
|
2503 | * (async () => {
|
2504 | * const browser = await puppeteer.launch();
|
2505 | * const page = await browser.newPage();
|
2506 | * let currentURL;
|
2507 | * page.mainFrame()
|
2508 | * .waitForSelector('img')
|
2509 | * .then(() => console.log('First URL with image: ' + currentURL));
|
2510 | *
|
2511 | * for (currentURL of ['https://example.com', 'https://google.com', 'https://bbc.com']) {
|
2512 | * await page.goto(currentURL);
|
2513 | * }
|
2514 | * await browser.close();
|
2515 | * })();
|
2516 | * ```
|
2517 | * @param selector - the selector to wait for.
|
2518 | * @param options - options to define if the element should be visible and how
|
2519 | * long to wait before timing out.
|
2520 | * @returns a promise which resolves when an element matching the selector
|
2521 | * string is added to the DOM.
|
2522 | */
|
2523 | waitForSelector(selector: string, options?: WaitForSelectorOptions): Promise<ElementHandle | null>;
|
2524 | /**
|
2525 | * @remarks
|
2526 | * Wait for the `xpath` to appear in page. If at the moment of calling the
|
2527 | * method the `xpath` already exists, the method will return immediately. If
|
2528 | * the xpath doesn't appear after the `timeout` milliseconds of waiting, the
|
2529 | * function will throw.
|
2530 | *
|
2531 | * For a code example, see the example for {@link Frame.waitForSelector}. That
|
2532 | * function behaves identically other than taking a CSS selector rather than
|
2533 | * an XPath.
|
2534 | *
|
2535 | * @param xpath - the XPath expression to wait for.
|
2536 | * @param options - options to configure the visiblity of the element and how
|
2537 | * long to wait before timing out.
|
2538 | */
|
2539 | waitForXPath(xpath: string, options?: WaitForSelectorOptions): Promise<ElementHandle | null>;
|
2540 | /**
|
2541 | * @remarks
|
2542 | *
|
2543 | * @example
|
2544 | *
|
2545 | * The `waitForFunction` can be used to observe viewport size change:
|
2546 | * ```js
|
2547 | * const puppeteer = require('puppeteer');
|
2548 | *
|
2549 | * (async () => {
|
2550 | * . const browser = await puppeteer.launch();
|
2551 | * . const page = await browser.newPage();
|
2552 | * . const watchDog = page.mainFrame().waitForFunction('window.innerWidth < 100');
|
2553 | * . page.setViewport({width: 50, height: 50});
|
2554 | * . await watchDog;
|
2555 | * . await browser.close();
|
2556 | * })();
|
2557 | * ```
|
2558 | *
|
2559 | * To pass arguments from Node.js to the predicate of `page.waitForFunction` function:
|
2560 | *
|
2561 | * ```js
|
2562 | * const selector = '.foo';
|
2563 | * await frame.waitForFunction(
|
2564 | * selector => !!document.querySelector(selector),
|
2565 | * {}, // empty options object
|
2566 | * selector
|
2567 | *);
|
2568 | * ```
|
2569 | *
|
2570 | * @param pageFunction - the function to evaluate in the frame context.
|
2571 | * @param options - options to configure the polling method and timeout.
|
2572 | * @param args - arguments to pass to the `pageFunction`.
|
2573 | * @returns the promise which resolve when the `pageFunction` returns a truthy value.
|
2574 | */
|
2575 | waitForFunction(pageFunction: Function | string, options?: FrameWaitForFunctionOptions, ...args: SerializableOrJSHandle[]): Promise<JSHandle>;
|
2576 | /**
|
2577 | * @returns the frame's title.
|
2578 | */
|
2579 | title(): Promise<string>;
|
2580 | /**
|
2581 | * @internal
|
2582 | */
|
2583 | _navigated(framePayload: Protocol.Page.Frame): void;
|
2584 | /**
|
2585 | * @internal
|
2586 | */
|
2587 | _navigatedWithinDocument(url: string): void;
|
2588 | /**
|
2589 | * @internal
|
2590 | */
|
2591 | _onLifecycleEvent(loaderId: string, name: string): void;
|
2592 | /**
|
2593 | * @internal
|
2594 | */
|
2595 | _onLoadingStopped(): void;
|
2596 | /**
|
2597 | * @internal
|
2598 | */
|
2599 | _detach(): void;
|
2600 | }
|
2601 |
|
2602 | /**
|
2603 | * @public
|
2604 | */
|
2605 | export declare interface FrameAddScriptTagOptions {
|
2606 | /**
|
2607 | * the URL of the script to be added.
|
2608 | */
|
2609 | url?: string;
|
2610 | /**
|
2611 | * The path to a JavaScript file to be injected into the frame.
|
2612 | * @remarks
|
2613 | * If `path` is a relative path, it is resolved relative to the current
|
2614 | * working directory (`process.cwd()` in Node.js).
|
2615 | */
|
2616 | path?: string;
|
2617 | /**
|
2618 | * Raw JavaScript content to be injected into the frame.
|
2619 | */
|
2620 | content?: string;
|
2621 | /**
|
2622 | * Set the script's `type`. Use `module` in order to load an ES2015 module.
|
2623 | */
|
2624 | type?: string;
|
2625 | }
|
2626 |
|
2627 | /**
|
2628 | * @public
|
2629 | */
|
2630 | export declare interface FrameAddStyleTagOptions {
|
2631 | /**
|
2632 | * the URL of the CSS file to be added.
|
2633 | */
|
2634 | url?: string;
|
2635 | /**
|
2636 | * The path to a CSS file to be injected into the frame.
|
2637 | * @remarks
|
2638 | * If `path` is a relative path, it is resolved relative to the current
|
2639 | * working directory (`process.cwd()` in Node.js).
|
2640 | */
|
2641 | path?: string;
|
2642 | /**
|
2643 | * Raw CSS content to be injected into the frame.
|
2644 | */
|
2645 | content?: string;
|
2646 | }
|
2647 |
|
2648 | /**
|
2649 | * @internal
|
2650 | */
|
2651 | export declare class FrameManager extends EventEmitter {
|
2652 | _client: CDPSession;
|
2653 | private _page;
|
2654 | private _networkManager;
|
2655 | _timeoutSettings: TimeoutSettings;
|
2656 | private _frames;
|
2657 | private _contextIdToContext;
|
2658 | private _isolatedWorlds;
|
2659 | private _mainFrame;
|
2660 | constructor(client: CDPSession, page: Page, ignoreHTTPSErrors: boolean, timeoutSettings: TimeoutSettings);
|
2661 | initialize(): Promise<void>;
|
2662 | networkManager(): NetworkManager;
|
2663 | navigateFrame(frame: Frame, url: string, options?: {
|
2664 | referer?: string;
|
2665 | timeout?: number;
|
2666 | waitUntil?: PuppeteerLifeCycleEvent | PuppeteerLifeCycleEvent[];
|
2667 | }): Promise<HTTPResponse | null>;
|
2668 | waitForFrameNavigation(frame: Frame, options?: {
|
2669 | timeout?: number;
|
2670 | waitUntil?: PuppeteerLifeCycleEvent | PuppeteerLifeCycleEvent[];
|
2671 | }): Promise<HTTPResponse | null>;
|
2672 | private _onFrameMoved;
|
2673 | _onLifecycleEvent(event: Protocol.Page.LifecycleEventEvent): void;
|
2674 | _onFrameStoppedLoading(frameId: string): void;
|
2675 | _handleFrameTree(frameTree: Protocol.Page.FrameTree): void;
|
2676 | page(): Page;
|
2677 | mainFrame(): Frame;
|
2678 | frames(): Frame[];
|
2679 | frame(frameId: string): Frame | null;
|
2680 | _onFrameAttached(frameId: string, parentFrameId?: string): void;
|
2681 | _onFrameNavigated(framePayload: Protocol.Page.Frame): void;
|
2682 | _ensureIsolatedWorld(name: string): Promise<void>;
|
2683 | _onFrameNavigatedWithinDocument(frameId: string, url: string): void;
|
2684 | _onFrameDetached(frameId: string): void;
|
2685 | _onExecutionContextCreated(contextPayload: Protocol.Runtime.ExecutionContextDescription): void;
|
2686 | private _onExecutionContextDestroyed;
|
2687 | private _onExecutionContextsCleared;
|
2688 | executionContextById(contextId: number): ExecutionContext;
|
2689 | private _removeFramesRecursively;
|
2690 | }
|
2691 |
|
2692 | /**
|
2693 | * We use symbols to prevent external parties listening to these events.
|
2694 | * They are internal to Puppeteer.
|
2695 | *
|
2696 | * @internal
|
2697 | */
|
2698 | export declare const FrameManagerEmittedEvents: {
|
2699 | FrameAttached: symbol;
|
2700 | FrameNavigated: symbol;
|
2701 | FrameDetached: symbol;
|
2702 | LifecycleEvent: symbol;
|
2703 | FrameNavigatedWithinDocument: symbol;
|
2704 | ExecutionContextCreated: symbol;
|
2705 | ExecutionContextDestroyed: symbol;
|
2706 | };
|
2707 |
|
2708 | /**
|
2709 | * @public
|
2710 | */
|
2711 | export declare interface FrameWaitForFunctionOptions {
|
2712 | /**
|
2713 | * An interval at which the `pageFunction` is executed, defaults to `raf`. If
|
2714 | * `polling` is a number, then it is treated as an interval in milliseconds at
|
2715 | * which the function would be executed. If `polling` is a string, then it can
|
2716 | * be one of the following values:
|
2717 | *
|
2718 | * - `raf` - to constantly execute `pageFunction` in `requestAnimationFrame`
|
2719 | * callback. This is the tightest polling mode which is suitable to observe
|
2720 | * styling changes.
|
2721 | *
|
2722 | * - `mutation` - to execute `pageFunction` on every DOM mutation.
|
2723 | */
|
2724 | polling?: string | number;
|
2725 | /**
|
2726 | * Maximum time to wait in milliseconds. Defaults to `30000` (30 seconds).
|
2727 | * Pass `0` to disable the timeout. Puppeteer's default timeout can be changed
|
2728 | * using {@link Page.setDefaultTimeout}.
|
2729 | */
|
2730 | timeout?: number;
|
2731 | }
|
2732 |
|
2733 | /**
|
2734 | * @public
|
2735 | */
|
2736 | export declare interface GeolocationOptions {
|
2737 | /**
|
2738 | * Latitude between -90 and 90.
|
2739 | */
|
2740 | longitude: number;
|
2741 | /**
|
2742 | * Longitude between -180 and 180.
|
2743 | */
|
2744 | latitude: number;
|
2745 | /**
|
2746 | * Optional non-negative accuracy value.
|
2747 | */
|
2748 | accuracy?: number;
|
2749 | }
|
2750 |
|
2751 | /**
|
2752 | * @internal
|
2753 | */
|
2754 | export declare function getQueryHandlerAndSelector(selector: string): {
|
2755 | updatedSelector: string;
|
2756 | queryHandler: InternalQueryHandler;
|
2757 | };
|
2758 |
|
2759 | /**
|
2760 | * @public
|
2761 | */
|
2762 | export declare type Handler<T = any> = (event?: T) => void;
|
2763 |
|
2764 | /**
|
2765 | *
|
2766 | * Represents an HTTP request sent by a page.
|
2767 | * @remarks
|
2768 | *
|
2769 | * Whenever the page sends a request, such as for a network resource, the
|
2770 | * following events are emitted by Puppeteer's `page`:
|
2771 | *
|
2772 | * - `request`: emitted when the request is issued by the page.
|
2773 | * - `requestfinished` - emitted when the response body is downloaded and the
|
2774 | * request is complete.
|
2775 | *
|
2776 | * If request fails at some point, then instead of `requestfinished` event the
|
2777 | * `requestfailed` event is emitted.
|
2778 | *
|
2779 | * All of these events provide an instance of `HTTPRequest` representing the
|
2780 | * request that occurred:
|
2781 | *
|
2782 | * ```
|
2783 | * page.on('request', request => ...)
|
2784 | * ```
|
2785 | *
|
2786 | * NOTE: HTTP Error responses, such as 404 or 503, are still successful
|
2787 | * responses from HTTP standpoint, so request will complete with
|
2788 | * `requestfinished` event.
|
2789 | *
|
2790 | * If request gets a 'redirect' response, the request is successfully finished
|
2791 | * with the `requestfinished` event, and a new request is issued to a
|
2792 | * redirected url.
|
2793 | *
|
2794 | * @public
|
2795 | */
|
2796 | export declare class HTTPRequest {
|
2797 | /**
|
2798 | * @internal
|
2799 | */
|
2800 | _requestId: string;
|
2801 | /**
|
2802 | * @internal
|
2803 | */
|
2804 | _interceptionId: string;
|
2805 | /**
|
2806 | * @internal
|
2807 | */
|
2808 | _failureText: any;
|
2809 | /**
|
2810 | * @internal
|
2811 | */
|
2812 | _response: HTTPResponse | null;
|
2813 | /**
|
2814 | * @internal
|
2815 | */
|
2816 | _fromMemoryCache: boolean;
|
2817 | /**
|
2818 | * @internal
|
2819 | */
|
2820 | _redirectChain: HTTPRequest[];
|
2821 | private _client;
|
2822 | private _isNavigationRequest;
|
2823 | private _allowInterception;
|
2824 | private _interceptionHandled;
|
2825 | private _url;
|
2826 | private _resourceType;
|
2827 | private _method;
|
2828 | private _postData?;
|
2829 | private _headers;
|
2830 | private _frame;
|
2831 | private _continueRequestOverrides;
|
2832 | private _responseForRequest;
|
2833 | private _abortErrorReason;
|
2834 | private _currentStrategy;
|
2835 | private _currentPriority;
|
2836 | private _interceptActions;
|
2837 | /**
|
2838 | * @internal
|
2839 | */
|
2840 | constructor(client: CDPSession, frame: Frame, interceptionId: string, allowInterception: boolean, event: Protocol.Network.RequestWillBeSentEvent, redirectChain: HTTPRequest[]);
|
2841 | /**
|
2842 | * @returns the URL of the request
|
2843 | */
|
2844 | url(): string;
|
2845 | /**
|
2846 | * @returns the `ContinueRequestOverrides` that will be used
|
2847 | * if the interception is allowed to continue (ie, `abort()` and
|
2848 | * `respond()` aren't called).
|
2849 | */
|
2850 | continueRequestOverrides(): ContinueRequestOverrides;
|
2851 | /**
|
2852 | * @returns The `ResponseForRequest` that gets used if the
|
2853 | * interception is allowed to respond (ie, `abort()` is not called).
|
2854 | */
|
2855 | responseForRequest(): Partial<ResponseForRequest>;
|
2856 | /**
|
2857 | * @returns the most recent reason for aborting the request
|
2858 | */
|
2859 | abortErrorReason(): Protocol.Network.ErrorReason;
|
2860 | /**
|
2861 | * @returns An array of the current intercept resolution strategy and priority
|
2862 | * `[strategy,priority]`. Strategy is one of: `abort`, `respond`, `continue`,
|
2863 | * `disabled`, `none`, or `already-handled`.
|
2864 | */
|
2865 | private interceptResolution;
|
2866 | /**
|
2867 | * Adds an async request handler to the processing queue.
|
2868 | * Deferred handlers are not guaranteed to execute in any particular order,
|
2869 | * but they are guarnateed to resolve before the request interception
|
2870 | * is finalized.
|
2871 | */
|
2872 | enqueueInterceptAction(pendingHandler: () => void | PromiseLike<unknown>): void;
|
2873 | /**
|
2874 | * Awaits pending interception handlers and then decides how to fulfill
|
2875 | * the request interception.
|
2876 | */
|
2877 | finalizeInterceptions(): Promise<void>;
|
2878 | /**
|
2879 | * Contains the request's resource type as it was perceived by the rendering
|
2880 | * engine.
|
2881 | */
|
2882 | resourceType(): ResourceType;
|
2883 | /**
|
2884 | * @returns the method used (`GET`, `POST`, etc.)
|
2885 | */
|
2886 | method(): string;
|
2887 | /**
|
2888 | * @returns the request's post body, if any.
|
2889 | */
|
2890 | postData(): string | undefined;
|
2891 | /**
|
2892 | * @returns an object with HTTP headers associated with the request. All
|
2893 | * header names are lower-case.
|
2894 | */
|
2895 | headers(): Record<string, string>;
|
2896 | /**
|
2897 | * @returns A matching `HTTPResponse` object, or null if the response has not
|
2898 | * been received yet.
|
2899 | */
|
2900 | response(): HTTPResponse | null;
|
2901 | /**
|
2902 | * @returns the frame that initiated the request, or null if navigating to
|
2903 | * error pages.
|
2904 | */
|
2905 | frame(): Frame | null;
|
2906 | /**
|
2907 | * @returns true if the request is the driver of the current frame's navigation.
|
2908 | */
|
2909 | isNavigationRequest(): boolean;
|
2910 | /**
|
2911 | * A `redirectChain` is a chain of requests initiated to fetch a resource.
|
2912 | * @remarks
|
2913 | *
|
2914 | * `redirectChain` is shared between all the requests of the same chain.
|
2915 | *
|
2916 | * For example, if the website `http://example.com` has a single redirect to
|
2917 | * `https://example.com`, then the chain will contain one request:
|
2918 | *
|
2919 | * ```js
|
2920 | * const response = await page.goto('http://example.com');
|
2921 | * const chain = response.request().redirectChain();
|
2922 | * console.log(chain.length); // 1
|
2923 | * console.log(chain[0].url()); // 'http://example.com'
|
2924 | * ```
|
2925 | *
|
2926 | * If the website `https://google.com` has no redirects, then the chain will be empty:
|
2927 | *
|
2928 | * ```js
|
2929 | * const response = await page.goto('https://google.com');
|
2930 | * const chain = response.request().redirectChain();
|
2931 | * console.log(chain.length); // 0
|
2932 | * ```
|
2933 | *
|
2934 | * @returns the chain of requests - if a server responds with at least a
|
2935 | * single redirect, this chain will contain all requests that were redirected.
|
2936 | */
|
2937 | redirectChain(): HTTPRequest[];
|
2938 | /**
|
2939 | * Access information about the request's failure.
|
2940 | *
|
2941 | * @remarks
|
2942 | *
|
2943 | * @example
|
2944 | *
|
2945 | * Example of logging all failed requests:
|
2946 | *
|
2947 | * ```js
|
2948 | * page.on('requestfailed', request => {
|
2949 | * console.log(request.url() + ' ' + request.failure().errorText);
|
2950 | * });
|
2951 | * ```
|
2952 | *
|
2953 | * @returns `null` unless the request failed. If the request fails this can
|
2954 | * return an object with `errorText` containing a human-readable error
|
2955 | * message, e.g. `net::ERR_FAILED`. It is not guaranteeded that there will be
|
2956 | * failure text if the request fails.
|
2957 | */
|
2958 | failure(): {
|
2959 | errorText: string;
|
2960 | } | null;
|
2961 | /**
|
2962 | * Continues request with optional request overrides.
|
2963 | *
|
2964 | * @remarks
|
2965 | *
|
2966 | * To use this, request
|
2967 | * interception should be enabled with {@link Page.setRequestInterception}.
|
2968 | *
|
2969 | * Exception is immediately thrown if the request interception is not enabled.
|
2970 | *
|
2971 | * @example
|
2972 | * ```js
|
2973 | * await page.setRequestInterception(true);
|
2974 | * page.on('request', request => {
|
2975 | * // Override headers
|
2976 | * const headers = Object.assign({}, request.headers(), {
|
2977 | * foo: 'bar', // set "foo" header
|
2978 | * origin: undefined, // remove "origin" header
|
2979 | * });
|
2980 | * request.continue({headers});
|
2981 | * });
|
2982 | * ```
|
2983 | *
|
2984 | * @param overrides - optional overrides to apply to the request.
|
2985 | * @param priority - If provided, intercept is resolved using
|
2986 | * cooperative handling rules. Otherwise, intercept is resolved
|
2987 | * immediately.
|
2988 | */
|
2989 | continue(overrides?: ContinueRequestOverrides, priority?: number): Promise<void>;
|
2990 | private _continue;
|
2991 | /**
|
2992 | * Fulfills a request with the given response.
|
2993 | *
|
2994 | * @remarks
|
2995 | *
|
2996 | * To use this, request
|
2997 | * interception should be enabled with {@link Page.setRequestInterception}.
|
2998 | *
|
2999 | * Exception is immediately thrown if the request interception is not enabled.
|
3000 | *
|
3001 | * @example
|
3002 | * An example of fulfilling all requests with 404 responses:
|
3003 | * ```js
|
3004 | * await page.setRequestInterception(true);
|
3005 | * page.on('request', request => {
|
3006 | * request.respond({
|
3007 | * status: 404,
|
3008 | * contentType: 'text/plain',
|
3009 | * body: 'Not Found!'
|
3010 | * });
|
3011 | * });
|
3012 | * ```
|
3013 | *
|
3014 | * NOTE: Mocking responses for dataURL requests is not supported.
|
3015 | * Calling `request.respond` for a dataURL request is a noop.
|
3016 | *
|
3017 | * @param response - the response to fulfill the request with.
|
3018 | * @param priority - If provided, intercept is resolved using
|
3019 | * cooperative handling rules. Otherwise, intercept is resolved
|
3020 | * immediately.
|
3021 | */
|
3022 | respond(response: Partial<ResponseForRequest>, priority?: number): Promise<void>;
|
3023 | private _respond;
|
3024 | /**
|
3025 | * Aborts a request.
|
3026 | *
|
3027 | * @remarks
|
3028 | * To use this, request interception should be enabled with
|
3029 | * {@link Page.setRequestInterception}. If it is not enabled, this method will
|
3030 | * throw an exception immediately.
|
3031 | *
|
3032 | * @param errorCode - optional error code to provide.
|
3033 | * @param priority - If provided, intercept is resolved using
|
3034 | * cooperative handling rules. Otherwise, intercept is resolved
|
3035 | * immediately.
|
3036 | */
|
3037 | abort(errorCode?: ErrorCode, priority?: number): Promise<void>;
|
3038 | private _abort;
|
3039 | }
|
3040 |
|
3041 | /**
|
3042 | * The HTTPResponse class represents responses which are received by the
|
3043 | * {@link Page} class.
|
3044 | *
|
3045 | * @public
|
3046 | */
|
3047 | export declare class HTTPResponse {
|
3048 | private _client;
|
3049 | private _request;
|
3050 | private _contentPromise;
|
3051 | private _bodyLoadedPromise;
|
3052 | private _bodyLoadedPromiseFulfill;
|
3053 | private _remoteAddress;
|
3054 | private _status;
|
3055 | private _statusText;
|
3056 | private _url;
|
3057 | private _fromDiskCache;
|
3058 | private _fromServiceWorker;
|
3059 | private _headers;
|
3060 | private _securityDetails;
|
3061 | /**
|
3062 | * @internal
|
3063 | */
|
3064 | constructor(client: CDPSession, request: HTTPRequest, responsePayload: Protocol.Network.Response);
|
3065 | /**
|
3066 | * @internal
|
3067 | */
|
3068 | _resolveBody(err: Error | null): void;
|
3069 | /**
|
3070 | * @returns The IP address and port number used to connect to the remote
|
3071 | * server.
|
3072 | */
|
3073 | remoteAddress(): RemoteAddress;
|
3074 | /**
|
3075 | * @returns The URL of the response.
|
3076 | */
|
3077 | url(): string;
|
3078 | /**
|
3079 | * @returns True if the response was successful (status in the range 200-299).
|
3080 | */
|
3081 | ok(): boolean;
|
3082 | /**
|
3083 | * @returns The status code of the response (e.g., 200 for a success).
|
3084 | */
|
3085 | status(): number;
|
3086 | /**
|
3087 | * @returns The status text of the response (e.g. usually an "OK" for a
|
3088 | * success).
|
3089 | */
|
3090 | statusText(): string;
|
3091 | /**
|
3092 | * @returns An object with HTTP headers associated with the response. All
|
3093 | * header names are lower-case.
|
3094 | */
|
3095 | headers(): Record<string, string>;
|
3096 | /**
|
3097 | * @returns {@link SecurityDetails} if the response was received over the
|
3098 | * secure connection, or `null` otherwise.
|
3099 | */
|
3100 | securityDetails(): SecurityDetails | null;
|
3101 | /**
|
3102 | * @returns Promise which resolves to a buffer with response body.
|
3103 | */
|
3104 | buffer(): Promise<Buffer>;
|
3105 | /**
|
3106 | * @returns Promise which resolves to a text representation of response body.
|
3107 | */
|
3108 | text(): Promise<string>;
|
3109 | /**
|
3110 | *
|
3111 | * @returns Promise which resolves to a JSON representation of response body.
|
3112 | *
|
3113 | * @remarks
|
3114 | *
|
3115 | * This method will throw if the response body is not parsable via
|
3116 | * `JSON.parse`.
|
3117 | */
|
3118 | json(): Promise<any>;
|
3119 | /**
|
3120 | * @returns A matching {@link HTTPRequest} object.
|
3121 | */
|
3122 | request(): HTTPRequest;
|
3123 | /**
|
3124 | * @returns True if the response was served from either the browser's disk
|
3125 | * cache or memory cache.
|
3126 | */
|
3127 | fromCache(): boolean;
|
3128 | /**
|
3129 | * @returns True if the response was served by a service worker.
|
3130 | */
|
3131 | fromServiceWorker(): boolean;
|
3132 | /**
|
3133 | * @returns A {@link Frame} that initiated this response, or `null` if
|
3134 | * navigating to error pages.
|
3135 | */
|
3136 | frame(): Frame | null;
|
3137 | }
|
3138 |
|
3139 | /**
|
3140 | * @public
|
3141 | */
|
3142 | export declare type InterceptResolutionStrategy = 'abort' | 'respond' | 'continue' | 'disabled' | 'none' | 'alreay-handled';
|
3143 |
|
3144 | /**
|
3145 | * @public
|
3146 | */
|
3147 | export declare interface InternalNetworkConditions extends NetworkConditions {
|
3148 | offline: boolean;
|
3149 | }
|
3150 |
|
3151 | /**
|
3152 | * @internal
|
3153 | */
|
3154 | export declare interface InternalQueryHandler {
|
3155 | queryOne?: (element: ElementHandle, selector: string) => Promise<ElementHandle | null>;
|
3156 | waitFor?: (domWorld: DOMWorld, selector: string, options: WaitForSelectorOptions) => Promise<ElementHandle | null>;
|
3157 | queryAll?: (element: ElementHandle, selector: string) => Promise<ElementHandle[]>;
|
3158 | queryAllArray?: (element: ElementHandle, selector: string) => Promise<JSHandle>;
|
3159 | }
|
3160 |
|
3161 | /**
|
3162 | * @public
|
3163 | */
|
3164 | export declare class JSCoverage {
|
3165 | _client: CDPSession;
|
3166 | _enabled: boolean;
|
3167 | _scriptURLs: Map<string, string>;
|
3168 | _scriptSources: Map<string, string>;
|
3169 | _eventListeners: PuppeteerEventListener[];
|
3170 | _resetOnNavigation: boolean;
|
3171 | _reportAnonymousScripts: boolean;
|
3172 | _includeRawScriptCoverage: boolean;
|
3173 | constructor(client: CDPSession);
|
3174 | start(options?: {
|
3175 | resetOnNavigation?: boolean;
|
3176 | reportAnonymousScripts?: boolean;
|
3177 | includeRawScriptCoverage?: boolean;
|
3178 | }): Promise<void>;
|
3179 | _onExecutionContextsCleared(): void;
|
3180 | _onScriptParsed(event: Protocol.Debugger.ScriptParsedEvent): Promise<void>;
|
3181 | stop(): Promise<JSCoverageEntry[]>;
|
3182 | }
|
3183 |
|
3184 | /**
|
3185 | * The CoverageEntry class for JavaScript
|
3186 | * @public
|
3187 | */
|
3188 | export declare interface JSCoverageEntry extends CoverageEntry {
|
3189 | /**
|
3190 | * Raw V8 script coverage entry.
|
3191 | */
|
3192 | rawScriptCoverage?: Protocol.Profiler.ScriptCoverage;
|
3193 | }
|
3194 |
|
3195 | /**
|
3196 | * Set of configurable options for JS coverage.
|
3197 | * @public
|
3198 | */
|
3199 | export declare interface JSCoverageOptions {
|
3200 | /**
|
3201 | * Whether to reset coverage on every navigation.
|
3202 | */
|
3203 | resetOnNavigation?: boolean;
|
3204 | /**
|
3205 | * Whether anonymous scripts generated by the page should be reported.
|
3206 | */
|
3207 | reportAnonymousScripts?: boolean;
|
3208 | /**
|
3209 | * Whether the result includes raw V8 script coverage entries.
|
3210 | */
|
3211 | includeRawScriptCoverage?: boolean;
|
3212 | }
|
3213 |
|
3214 | /**
|
3215 | * Represents an in-page JavaScript object. JSHandles can be created with the
|
3216 | * {@link Page.evaluateHandle | page.evaluateHandle} method.
|
3217 | *
|
3218 | * @example
|
3219 | * ```js
|
3220 | * const windowHandle = await page.evaluateHandle(() => window);
|
3221 | * ```
|
3222 | *
|
3223 | * JSHandle prevents the referenced JavaScript object from being garbage-collected
|
3224 | * unless the handle is {@link JSHandle.dispose | disposed}. JSHandles are auto-
|
3225 | * disposed when their origin frame gets navigated or the parent context gets destroyed.
|
3226 | *
|
3227 | * JSHandle instances can be used as arguments for {@link Page.$eval},
|
3228 | * {@link Page.evaluate}, and {@link Page.evaluateHandle}.
|
3229 | *
|
3230 | * @public
|
3231 | */
|
3232 | export declare class JSHandle<HandleObjectType = unknown> {
|
3233 | /**
|
3234 | * @internal
|
3235 | */
|
3236 | _context: ExecutionContext;
|
3237 | /**
|
3238 | * @internal
|
3239 | */
|
3240 | _client: CDPSession;
|
3241 | /**
|
3242 | * @internal
|
3243 | */
|
3244 | _remoteObject: Protocol.Runtime.RemoteObject;
|
3245 | /**
|
3246 | * @internal
|
3247 | */
|
3248 | _disposed: boolean;
|
3249 | /**
|
3250 | * @internal
|
3251 | */
|
3252 | constructor(context: ExecutionContext, client: CDPSession, remoteObject: Protocol.Runtime.RemoteObject);
|
3253 | /** Returns the execution context the handle belongs to.
|
3254 | */
|
3255 | executionContext(): ExecutionContext;
|
3256 | /**
|
3257 | * This method passes this handle as the first argument to `pageFunction`.
|
3258 | * If `pageFunction` returns a Promise, then `handle.evaluate` would wait
|
3259 | * for the promise to resolve and return its value.
|
3260 | *
|
3261 | * @example
|
3262 | * ```js
|
3263 | * const tweetHandle = await page.$('.tweet .retweets');
|
3264 | * expect(await tweetHandle.evaluate(node => node.innerText)).toBe('10');
|
3265 | * ```
|
3266 | */
|
3267 | evaluate<T extends EvaluateFn<HandleObjectType>>(pageFunction: T | string, ...args: SerializableOrJSHandle[]): Promise<UnwrapPromiseLike<EvaluateFnReturnType<T>>>;
|
3268 | /**
|
3269 | * This method passes this handle as the first argument to `pageFunction`.
|
3270 | *
|
3271 | * @remarks
|
3272 | *
|
3273 | * The only difference between `jsHandle.evaluate` and
|
3274 | * `jsHandle.evaluateHandle` is that `jsHandle.evaluateHandle`
|
3275 | * returns an in-page object (JSHandle).
|
3276 | *
|
3277 | * If the function passed to `jsHandle.evaluateHandle` returns a Promise,
|
3278 | * then `evaluateHandle.evaluateHandle` waits for the promise to resolve and
|
3279 | * returns its value.
|
3280 | *
|
3281 | * See {@link Page.evaluateHandle} for more details.
|
3282 | */
|
3283 | evaluateHandle<HandleType extends JSHandle = JSHandle>(pageFunction: EvaluateHandleFn, ...args: SerializableOrJSHandle[]): Promise<HandleType>;
|
3284 | /** Fetches a single property from the referenced object.
|
3285 | */
|
3286 | getProperty(propertyName: string): Promise<JSHandle | undefined>;
|
3287 | /**
|
3288 | * The method returns a map with property names as keys and JSHandle
|
3289 | * instances for the property values.
|
3290 | *
|
3291 | * @example
|
3292 | * ```js
|
3293 | * const listHandle = await page.evaluateHandle(() => document.body.children);
|
3294 | * const properties = await listHandle.getProperties();
|
3295 | * const children = [];
|
3296 | * for (const property of properties.values()) {
|
3297 | * const element = property.asElement();
|
3298 | * if (element)
|
3299 | * children.push(element);
|
3300 | * }
|
3301 | * children; // holds elementHandles to all children of document.body
|
3302 | * ```
|
3303 | */
|
3304 | getProperties(): Promise<Map<string, JSHandle>>;
|
3305 | /**
|
3306 | * @returns Returns a JSON representation of the object.If the object has a
|
3307 | * `toJSON` function, it will not be called.
|
3308 | * @remarks
|
3309 | *
|
3310 | * The JSON is generated by running {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify | JSON.stringify}
|
3311 | * on the object in page and consequent {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse | JSON.parse} in puppeteer.
|
3312 | * **NOTE** The method throws if the referenced object is not stringifiable.
|
3313 | */
|
3314 | jsonValue<T = unknown>(): Promise<T>;
|
3315 | /**
|
3316 | * @returns Either `null` or the object handle itself, if the object
|
3317 | * handle is an instance of {@link ElementHandle}.
|
3318 | */
|
3319 | asElement(): ElementHandle | null;
|
3320 | /**
|
3321 | * Stops referencing the element handle, and resolves when the object handle is
|
3322 | * successfully disposed of.
|
3323 | */
|
3324 | dispose(): Promise<void>;
|
3325 | /**
|
3326 | * Returns a string representation of the JSHandle.
|
3327 | *
|
3328 | * @remarks Useful during debugging.
|
3329 | */
|
3330 | toString(): string;
|
3331 | }
|
3332 |
|
3333 | /**
|
3334 | * @public
|
3335 | */
|
3336 | export declare type JSONArray = readonly Serializable[];
|
3337 |
|
3338 | /**
|
3339 | * @public
|
3340 | */
|
3341 | export declare interface JSONObject {
|
3342 | [key: string]: Serializable;
|
3343 | }
|
3344 |
|
3345 | /**
|
3346 | * Keyboard provides an api for managing a virtual keyboard.
|
3347 | * The high level api is {@link Keyboard."type"},
|
3348 | * which takes raw characters and generates proper keydown, keypress/input,
|
3349 | * and keyup events on your page.
|
3350 | *
|
3351 | * @remarks
|
3352 | * For finer control, you can use {@link Keyboard.down},
|
3353 | * {@link Keyboard.up}, and {@link Keyboard.sendCharacter}
|
3354 | * to manually fire events as if they were generated from a real keyboard.
|
3355 | *
|
3356 | * On MacOS, keyboard shortcuts like `⌘ A` -\> Select All do not work.
|
3357 | * See {@link https://github.com/puppeteer/puppeteer/issues/1313 | #1313}.
|
3358 | *
|
3359 | * @example
|
3360 | * An example of holding down `Shift` in order to select and delete some text:
|
3361 | * ```js
|
3362 | * await page.keyboard.type('Hello World!');
|
3363 | * await page.keyboard.press('ArrowLeft');
|
3364 | *
|
3365 | * await page.keyboard.down('Shift');
|
3366 | * for (let i = 0; i < ' World'.length; i++)
|
3367 | * await page.keyboard.press('ArrowLeft');
|
3368 | * await page.keyboard.up('Shift');
|
3369 | *
|
3370 | * await page.keyboard.press('Backspace');
|
3371 | * // Result text will end up saying 'Hello!'
|
3372 | * ```
|
3373 | *
|
3374 | * @example
|
3375 | * An example of pressing `A`
|
3376 | * ```js
|
3377 | * await page.keyboard.down('Shift');
|
3378 | * await page.keyboard.press('KeyA');
|
3379 | * await page.keyboard.up('Shift');
|
3380 | * ```
|
3381 | *
|
3382 | * @public
|
3383 | */
|
3384 | export declare class Keyboard {
|
3385 | private _client;
|
3386 | /** @internal */
|
3387 | _modifiers: number;
|
3388 | private _pressedKeys;
|
3389 | /** @internal */
|
3390 | constructor(client: CDPSession);
|
3391 | /**
|
3392 | * Dispatches a `keydown` event.
|
3393 | *
|
3394 | * @remarks
|
3395 | * If `key` is a single character and no modifier keys besides `Shift`
|
3396 | * are being held down, a `keypress`/`input` event will also generated.
|
3397 | * The `text` option can be specified to force an input event to be generated.
|
3398 | * If `key` is a modifier key, `Shift`, `Meta`, `Control`, or `Alt`,
|
3399 | * subsequent key presses will be sent with that modifier active.
|
3400 | * To release the modifier key, use {@link Keyboard.up}.
|
3401 | *
|
3402 | * After the key is pressed once, subsequent calls to
|
3403 | * {@link Keyboard.down} will have
|
3404 | * {@link https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/repeat | repeat}
|
3405 | * set to true. To release the key, use {@link Keyboard.up}.
|
3406 | *
|
3407 | * Modifier keys DO influence {@link Keyboard.down}.
|
3408 | * Holding down `Shift` will type the text in upper case.
|
3409 | *
|
3410 | * @param key - Name of key to press, such as `ArrowLeft`.
|
3411 | * See {@link KeyInput} for a list of all key names.
|
3412 | *
|
3413 | * @param options - An object of options. Accepts text which, if specified,
|
3414 | * generates an input event with this text.
|
3415 | */
|
3416 | down(key: KeyInput, options?: {
|
3417 | text?: string;
|
3418 | }): Promise<void>;
|
3419 | private _modifierBit;
|
3420 | private _keyDescriptionForString;
|
3421 | /**
|
3422 | * Dispatches a `keyup` event.
|
3423 | *
|
3424 | * @param key - Name of key to release, such as `ArrowLeft`.
|
3425 | * See {@link KeyInput | KeyInput}
|
3426 | * for a list of all key names.
|
3427 | */
|
3428 | up(key: KeyInput): Promise<void>;
|
3429 | /**
|
3430 | * Dispatches a `keypress` and `input` event.
|
3431 | * This does not send a `keydown` or `keyup` event.
|
3432 | *
|
3433 | * @remarks
|
3434 | * Modifier keys DO NOT effect {@link Keyboard.sendCharacter | Keyboard.sendCharacter}.
|
3435 | * Holding down `Shift` will not type the text in upper case.
|
3436 | *
|
3437 | * @example
|
3438 | * ```js
|
3439 | * page.keyboard.sendCharacter('嗨');
|
3440 | * ```
|
3441 | *
|
3442 | * @param char - Character to send into the page.
|
3443 | */
|
3444 | sendCharacter(char: string): Promise<void>;
|
3445 | private charIsKey;
|
3446 | /**
|
3447 | * Sends a `keydown`, `keypress`/`input`,
|
3448 | * and `keyup` event for each character in the text.
|
3449 | *
|
3450 | * @remarks
|
3451 | * To press a special key, like `Control` or `ArrowDown`,
|
3452 | * use {@link Keyboard.press}.
|
3453 | *
|
3454 | * Modifier keys DO NOT effect `keyboard.type`.
|
3455 | * Holding down `Shift` will not type the text in upper case.
|
3456 | *
|
3457 | * @example
|
3458 | * ```js
|
3459 | * await page.keyboard.type('Hello'); // Types instantly
|
3460 | * await page.keyboard.type('World', {delay: 100}); // Types slower, like a user
|
3461 | * ```
|
3462 | *
|
3463 | * @param text - A text to type into a focused element.
|
3464 | * @param options - An object of options. Accepts delay which,
|
3465 | * if specified, is the time to wait between `keydown` and `keyup` in milliseconds.
|
3466 | * Defaults to 0.
|
3467 | */
|
3468 | type(text: string, options?: {
|
3469 | delay?: number;
|
3470 | }): Promise<void>;
|
3471 | /**
|
3472 | * Shortcut for {@link Keyboard.down}
|
3473 | * and {@link Keyboard.up}.
|
3474 | *
|
3475 | * @remarks
|
3476 | * If `key` is a single character and no modifier keys besides `Shift`
|
3477 | * are being held down, a `keypress`/`input` event will also generated.
|
3478 | * The `text` option can be specified to force an input event to be generated.
|
3479 | *
|
3480 | * Modifier keys DO effect {@link Keyboard.press}.
|
3481 | * Holding down `Shift` will type the text in upper case.
|
3482 | *
|
3483 | * @param key - Name of key to press, such as `ArrowLeft`.
|
3484 | * See {@link KeyInput} for a list of all key names.
|
3485 | *
|
3486 | * @param options - An object of options. Accepts text which, if specified,
|
3487 | * generates an input event with this text. Accepts delay which,
|
3488 | * if specified, is the time to wait between `keydown` and `keyup` in milliseconds.
|
3489 | * Defaults to 0.
|
3490 | */
|
3491 | press(key: KeyInput, options?: {
|
3492 | delay?: number;
|
3493 | text?: string;
|
3494 | }): Promise<void>;
|
3495 | }
|
3496 |
|
3497 | /**
|
3498 | * Copyright 2017 Google Inc. All rights reserved.
|
3499 | *
|
3500 | * Licensed under the Apache License, Version 2.0 (the 'License');
|
3501 | * you may not use this file except in compliance with the License.
|
3502 | * You may obtain a copy of the License at
|
3503 | *
|
3504 | * http://www.apache.org/licenses/LICENSE-2.0
|
3505 | *
|
3506 | * Unless required by applicable law or agreed to in writing, software
|
3507 | * distributed under the License is distributed on an 'AS IS' BASIS,
|
3508 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
3509 | * See the License for the specific language governing permissions and
|
3510 | * limitations under the License.
|
3511 | */
|
3512 | /**
|
3513 | * @internal
|
3514 | */
|
3515 | export declare interface KeyDefinition {
|
3516 | keyCode?: number;
|
3517 | shiftKeyCode?: number;
|
3518 | key?: string;
|
3519 | shiftKey?: string;
|
3520 | code?: string;
|
3521 | text?: string;
|
3522 | shiftText?: string;
|
3523 | location?: number;
|
3524 | }
|
3525 |
|
3526 | /**
|
3527 | * @internal
|
3528 | */
|
3529 | export declare const keyDefinitions: Readonly<Record<KeyInput, KeyDefinition>>;
|
3530 |
|
3531 | /**
|
3532 | * All the valid keys that can be passed to functions that take user input, such
|
3533 | * as {@link Keyboard.press | keyboard.press }
|
3534 | *
|
3535 | * @public
|
3536 | */
|
3537 | export declare type KeyInput = '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' | 'Power' | 'Eject' | 'Abort' | 'Help' | 'Backspace' | 'Tab' | 'Numpad5' | 'NumpadEnter' | 'Enter' | '\r' | '\n' | 'ShiftLeft' | 'ShiftRight' | 'ControlLeft' | 'ControlRight' | 'AltLeft' | 'AltRight' | 'Pause' | 'CapsLock' | 'Escape' | 'Convert' | 'NonConvert' | 'Space' | 'Numpad9' | 'PageUp' | 'Numpad3' | 'PageDown' | 'End' | 'Numpad1' | 'Home' | 'Numpad7' | 'ArrowLeft' | 'Numpad4' | 'Numpad8' | 'ArrowUp' | 'ArrowRight' | 'Numpad6' | 'Numpad2' | 'ArrowDown' | 'Select' | 'Open' | 'PrintScreen' | 'Insert' | 'Numpad0' | 'Delete' | 'NumpadDecimal' | 'Digit0' | 'Digit1' | 'Digit2' | 'Digit3' | 'Digit4' | 'Digit5' | 'Digit6' | 'Digit7' | 'Digit8' | 'Digit9' | 'KeyA' | 'KeyB' | 'KeyC' | 'KeyD' | 'KeyE' | 'KeyF' | 'KeyG' | 'KeyH' | 'KeyI' | 'KeyJ' | 'KeyK' | 'KeyL' | 'KeyM' | 'KeyN' | 'KeyO' | 'KeyP' | 'KeyQ' | 'KeyR' | 'KeyS' | 'KeyT' | 'KeyU' | 'KeyV' | 'KeyW' | 'KeyX' | 'KeyY' | 'KeyZ' | 'MetaLeft' | 'MetaRight' | 'ContextMenu' | 'NumpadMultiply' | 'NumpadAdd' | 'NumpadSubtract' | 'NumpadDivide' | 'F1' | 'F2' | 'F3' | 'F4' | 'F5' | 'F6' | 'F7' | 'F8' | 'F9' | 'F10' | 'F11' | 'F12' | 'F13' | 'F14' | 'F15' | 'F16' | 'F17' | 'F18' | 'F19' | 'F20' | 'F21' | 'F22' | 'F23' | 'F24' | 'NumLock' | 'ScrollLock' | 'AudioVolumeMute' | 'AudioVolumeDown' | 'AudioVolumeUp' | 'MediaTrackNext' | 'MediaTrackPrevious' | 'MediaStop' | 'MediaPlayPause' | 'Semicolon' | 'Equal' | 'NumpadEqual' | 'Comma' | 'Minus' | 'Period' | 'Slash' | 'Backquote' | 'BracketLeft' | 'Backslash' | 'BracketRight' | 'Quote' | 'AltGraph' | 'Props' | 'Cancel' | 'Clear' | 'Shift' | 'Control' | 'Alt' | 'Accept' | 'ModeChange' | ' ' | 'Print' | 'Execute' | '\u0000' | 'a' | 'b' | 'c' | 'd' | 'e' | 'f' | 'g' | 'h' | 'i' | 'j' | 'k' | 'l' | 'm' | 'n' | 'o' | 'p' | 'q' | 'r' | 's' | 't' | 'u' | 'v' | 'w' | 'x' | 'y' | 'z' | 'Meta' | '*' | '+' | '-' | '/' | ';' | '=' | ',' | '.' | '`' | '[' | '\\' | ']' | "'" | 'Attn' | 'CrSel' | 'ExSel' | 'EraseEof' | 'Play' | 'ZoomOut' | ')' | '!' | '@' | '#' | '$' | '%' | '^' | '&' | '(' | 'A' | 'B' | 'C' | 'D' | 'E' | 'F' | 'G' | 'H' | 'I' | 'J' | 'K' | 'L' | 'M' | 'N' | 'O' | 'P' | 'Q' | 'R' | 'S' | 'T' | 'U' | 'V' | 'W' | 'X' | 'Y' | 'Z' | ':' | '<' | '_' | '>' | '?' | '~' | '{' | '|' | '}' | '"' | 'SoftLeft' | 'SoftRight' | 'Camera' | 'Call' | 'EndCall' | 'VolumeDown' | 'VolumeUp';
|
3538 |
|
3539 | /**
|
3540 | * @public
|
3541 | * {@inheritDoc PuppeteerNode.launch}
|
3542 | */
|
3543 | export declare function launch(options?: LaunchOptions & BrowserLaunchArgumentOptions & BrowserConnectOptions & {
|
3544 | product?: Product;
|
3545 | extraPrefsFirefox?: Record<string, unknown>;
|
3546 | }): Promise<Browser>;
|
3547 |
|
3548 | /**
|
3549 | * Generic launch options that can be passed when launching any browser.
|
3550 | * @public
|
3551 | */
|
3552 | export declare interface LaunchOptions {
|
3553 | /**
|
3554 | * Chrome Release Channel
|
3555 | */
|
3556 | channel?: ChromeReleaseChannel;
|
3557 | /**
|
3558 | * Path to a browser executable to use instead of the bundled Chromium. Note
|
3559 | * that Puppeteer is only guaranteed to work with the bundled Chromium, so use
|
3560 | * this setting at your own risk.
|
3561 | */
|
3562 | executablePath?: string;
|
3563 | /**
|
3564 | * If `true`, do not use `puppeteer.defaultArgs()` when creating a browser. If
|
3565 | * an array is provided, these args will be filtered out. Use this with care -
|
3566 | * you probably want the default arguments Puppeteer uses.
|
3567 | * @defaultValue false
|
3568 | */
|
3569 | ignoreDefaultArgs?: boolean | string[];
|
3570 | /**
|
3571 | * Close the browser process on `Ctrl+C`.
|
3572 | * @defaultValue `true`
|
3573 | */
|
3574 | handleSIGINT?: boolean;
|
3575 | /**
|
3576 | * Close the browser process on `SIGTERM`.
|
3577 | * @defaultValue `true`
|
3578 | */
|
3579 | handleSIGTERM?: boolean;
|
3580 | /**
|
3581 | * Close the browser process on `SIGHUP`.
|
3582 | * @defaultValue `true`
|
3583 | */
|
3584 | handleSIGHUP?: boolean;
|
3585 | /**
|
3586 | * Maximum time in milliseconds to wait for the browser to start.
|
3587 | * Pass `0` to disable the timeout.
|
3588 | * @defaultValue 30000 (30 seconds).
|
3589 | */
|
3590 | timeout?: number;
|
3591 | /**
|
3592 | * If true, pipes the browser process stdout and stderr to `process.stdout`
|
3593 | * and `process.stderr`.
|
3594 | * @defaultValue false
|
3595 | */
|
3596 | dumpio?: boolean;
|
3597 | /**
|
3598 | * Specify environment variables that will be visible to the browser.
|
3599 | * @defaultValue The contents of `process.env`.
|
3600 | */
|
3601 | env?: Record<string, string | undefined>;
|
3602 | /**
|
3603 | * Connect to a browser over a pipe instead of a WebSocket.
|
3604 | * @defaultValue false
|
3605 | */
|
3606 | pipe?: boolean;
|
3607 | /**
|
3608 | * Which browser to launch.
|
3609 | * @defaultValue `chrome`
|
3610 | */
|
3611 | product?: Product;
|
3612 | /**
|
3613 | * {@link https://searchfox.org/mozilla-release/source/modules/libpref/init/all.js | Additional preferences } that can be passed when launching with Firefox.
|
3614 | */
|
3615 | extraPrefsFirefox?: Record<string, unknown>;
|
3616 | /**
|
3617 | * Whether to wait for the initial page to be ready.
|
3618 | * Useful when a user explicitly disables that (e.g. `--no-startup-window` for Chrome).
|
3619 | * @defaultValue true
|
3620 | */
|
3621 | waitForInitialPage?: boolean;
|
3622 | }
|
3623 |
|
3624 | /**
|
3625 | * @internal
|
3626 | */
|
3627 | export declare class LifecycleWatcher {
|
3628 | _expectedLifecycle: ProtocolLifeCycleEvent[];
|
3629 | _frameManager: FrameManager;
|
3630 | _frame: Frame;
|
3631 | _timeout: number;
|
3632 | _navigationRequest?: HTTPRequest;
|
3633 | _eventListeners: PuppeteerEventListener[];
|
3634 | _initialLoaderId: string;
|
3635 | _sameDocumentNavigationPromise: Promise<Error | null>;
|
3636 | _sameDocumentNavigationCompleteCallback: (x?: Error) => void;
|
3637 | _lifecyclePromise: Promise<void>;
|
3638 | _lifecycleCallback: () => void;
|
3639 | _newDocumentNavigationPromise: Promise<Error | null>;
|
3640 | _newDocumentNavigationCompleteCallback: (x?: Error) => void;
|
3641 | _terminationPromise: Promise<Error | null>;
|
3642 | _terminationCallback: (x?: Error) => void;
|
3643 | _timeoutPromise: Promise<TimeoutError | null>;
|
3644 | _maximumTimer?: NodeJS.Timeout;
|
3645 | _hasSameDocumentNavigation?: boolean;
|
3646 | constructor(frameManager: FrameManager, frame: Frame, waitUntil: PuppeteerLifeCycleEvent | PuppeteerLifeCycleEvent[], timeout: number);
|
3647 | _onRequest(request: HTTPRequest): void;
|
3648 | _onFrameDetached(frame: Frame): void;
|
3649 | navigationResponse(): HTTPResponse | null;
|
3650 | _terminate(error: Error): void;
|
3651 | sameDocumentNavigationPromise(): Promise<Error | null>;
|
3652 | newDocumentNavigationPromise(): Promise<Error | null>;
|
3653 | lifecyclePromise(): Promise<void>;
|
3654 | timeoutOrTerminationPromise(): Promise<Error | TimeoutError | null>;
|
3655 | _createTimeoutPromise(): Promise<TimeoutError | null>;
|
3656 | _navigatedWithinDocument(frame: Frame): void;
|
3657 | _checkLifecycleComplete(): void;
|
3658 | dispose(): void;
|
3659 | }
|
3660 |
|
3661 | /**
|
3662 | * @public
|
3663 | */
|
3664 | export declare interface MediaFeature {
|
3665 | name: string;
|
3666 | value: string;
|
3667 | }
|
3668 |
|
3669 | /**
|
3670 | * @public
|
3671 | */
|
3672 | export declare interface Metrics {
|
3673 | Timestamp?: number;
|
3674 | Documents?: number;
|
3675 | Frames?: number;
|
3676 | JSEventListeners?: number;
|
3677 | Nodes?: number;
|
3678 | LayoutCount?: number;
|
3679 | RecalcStyleCount?: number;
|
3680 | LayoutDuration?: number;
|
3681 | RecalcStyleDuration?: number;
|
3682 | ScriptDuration?: number;
|
3683 | TaskDuration?: number;
|
3684 | JSHeapUsedSize?: number;
|
3685 | JSHeapTotalSize?: number;
|
3686 | }
|
3687 |
|
3688 | /**
|
3689 | * The Mouse class operates in main-frame CSS pixels
|
3690 | * relative to the top-left corner of the viewport.
|
3691 | * @remarks
|
3692 | * Every `page` object has its own Mouse, accessible with [`page.mouse`](#pagemouse).
|
3693 | *
|
3694 | * @example
|
3695 | * ```js
|
3696 | * // Using ‘page.mouse’ to trace a 100x100 square.
|
3697 | * await page.mouse.move(0, 0);
|
3698 | * await page.mouse.down();
|
3699 | * await page.mouse.move(0, 100);
|
3700 | * await page.mouse.move(100, 100);
|
3701 | * await page.mouse.move(100, 0);
|
3702 | * await page.mouse.move(0, 0);
|
3703 | * await page.mouse.up();
|
3704 | * ```
|
3705 | *
|
3706 | * **Note**: The mouse events trigger synthetic `MouseEvent`s.
|
3707 | * This means that it does not fully replicate the functionality of what a normal user
|
3708 | * would be able to do with their mouse.
|
3709 | *
|
3710 | * For example, dragging and selecting text is not possible using `page.mouse`.
|
3711 | * Instead, you can use the {@link https://developer.mozilla.org/en-US/docs/Web/API/DocumentOrShadowRoot/getSelection | `DocumentOrShadowRoot.getSelection()`} functionality implemented in the platform.
|
3712 | *
|
3713 | * @example
|
3714 | * For example, if you want to select all content between nodes:
|
3715 | * ```js
|
3716 | * await page.evaluate((from, to) => {
|
3717 | * const selection = from.getRootNode().getSelection();
|
3718 | * const range = document.createRange();
|
3719 | * range.setStartBefore(from);
|
3720 | * range.setEndAfter(to);
|
3721 | * selection.removeAllRanges();
|
3722 | * selection.addRange(range);
|
3723 | * }, fromJSHandle, toJSHandle);
|
3724 | * ```
|
3725 | * If you then would want to copy-paste your selection, you can use the clipboard api:
|
3726 | * ```js
|
3727 | * // The clipboard api does not allow you to copy, unless the tab is focused.
|
3728 | * await page.bringToFront();
|
3729 | * await page.evaluate(() => {
|
3730 | * // Copy the selected content to the clipboard
|
3731 | * document.execCommand('copy');
|
3732 | * // Obtain the content of the clipboard as a string
|
3733 | * return navigator.clipboard.readText();
|
3734 | * });
|
3735 | * ```
|
3736 | * **Note**: If you want access to the clipboard API,
|
3737 | * you have to give it permission to do so:
|
3738 | * ```js
|
3739 | * await browser.defaultBrowserContext().overridePermissions(
|
3740 | * '<your origin>', ['clipboard-read', 'clipboard-write']
|
3741 | * );
|
3742 | * ```
|
3743 | * @public
|
3744 | */
|
3745 | export declare class Mouse {
|
3746 | private _client;
|
3747 | private _keyboard;
|
3748 | private _x;
|
3749 | private _y;
|
3750 | private _button;
|
3751 | /**
|
3752 | * @internal
|
3753 | */
|
3754 | constructor(client: CDPSession, keyboard: Keyboard);
|
3755 | /**
|
3756 | * Dispatches a `mousemove` event.
|
3757 | * @param x - Horizontal position of the mouse.
|
3758 | * @param y - Vertical position of the mouse.
|
3759 | * @param options - Optional object. If specified, the `steps` property
|
3760 | * sends intermediate `mousemove` events when set to `1` (default).
|
3761 | */
|
3762 | move(x: number, y: number, options?: {
|
3763 | steps?: number;
|
3764 | }): Promise<void>;
|
3765 | /**
|
3766 | * Shortcut for `mouse.move`, `mouse.down` and `mouse.up`.
|
3767 | * @param x - Horizontal position of the mouse.
|
3768 | * @param y - Vertical position of the mouse.
|
3769 | * @param options - Optional `MouseOptions`.
|
3770 | */
|
3771 | click(x: number, y: number, options?: MouseOptions & {
|
3772 | delay?: number;
|
3773 | }): Promise<void>;
|
3774 | /**
|
3775 | * Dispatches a `mousedown` event.
|
3776 | * @param options - Optional `MouseOptions`.
|
3777 | */
|
3778 | down(options?: MouseOptions): Promise<void>;
|
3779 | /**
|
3780 | * Dispatches a `mouseup` event.
|
3781 | * @param options - Optional `MouseOptions`.
|
3782 | */
|
3783 | up(options?: MouseOptions): Promise<void>;
|
3784 | /**
|
3785 | * Dispatches a `mousewheel` event.
|
3786 | * @param options - Optional: `MouseWheelOptions`.
|
3787 | *
|
3788 | * @example
|
3789 | * An example of zooming into an element:
|
3790 | * ```js
|
3791 | * await page.goto('https://mdn.mozillademos.org/en-US/docs/Web/API/Element/wheel_event$samples/Scaling_an_element_via_the_wheel?revision=1587366');
|
3792 | *
|
3793 | * const elem = await page.$('div');
|
3794 | * const boundingBox = await elem.boundingBox();
|
3795 | * await page.mouse.move(
|
3796 | * boundingBox.x + boundingBox.width / 2,
|
3797 | * boundingBox.y + boundingBox.height / 2
|
3798 | * );
|
3799 | *
|
3800 | * await page.mouse.wheel({ deltaY: -100 })
|
3801 | * ```
|
3802 | */
|
3803 | wheel(options?: MouseWheelOptions): Promise<void>;
|
3804 | /**
|
3805 | * Dispatches a `drag` event.
|
3806 | * @param start - starting point for drag
|
3807 | * @param target - point to drag to
|
3808 | */
|
3809 | drag(start: Point, target: Point): Promise<Protocol.Input.DragData>;
|
3810 | /**
|
3811 | * Dispatches a `dragenter` event.
|
3812 | * @param target - point for emitting `dragenter` event
|
3813 | */
|
3814 | dragEnter(target: Point, data: Protocol.Input.DragData): Promise<void>;
|
3815 | /**
|
3816 | * Dispatches a `dragover` event.
|
3817 | * @param target - point for emitting `dragover` event
|
3818 | */
|
3819 | dragOver(target: Point, data: Protocol.Input.DragData): Promise<void>;
|
3820 | /**
|
3821 | * Performs a dragenter, dragover, and drop in sequence.
|
3822 | * @param target - point to drop on
|
3823 | * @param data - drag data containing items and operations mask
|
3824 | * @param options - An object of options. Accepts delay which,
|
3825 | * if specified, is the time to wait between `dragover` and `drop` in milliseconds.
|
3826 | * Defaults to 0.
|
3827 | */
|
3828 | drop(target: Point, data: Protocol.Input.DragData): Promise<void>;
|
3829 | /**
|
3830 | * Performs a drag, dragenter, dragover, and drop in sequence.
|
3831 | * @param target - point to drag from
|
3832 | * @param target - point to drop on
|
3833 | * @param options - An object of options. Accepts delay which,
|
3834 | * if specified, is the time to wait between `dragover` and `drop` in milliseconds.
|
3835 | * Defaults to 0.
|
3836 | */
|
3837 | dragAndDrop(start: Point, target: Point, options?: {
|
3838 | delay?: number;
|
3839 | }): Promise<void>;
|
3840 | }
|
3841 |
|
3842 | /**
|
3843 | * @public
|
3844 | */
|
3845 | export declare type MouseButton = 'left' | 'right' | 'middle';
|
3846 |
|
3847 | /**
|
3848 | * @public
|
3849 | */
|
3850 | export declare interface MouseOptions {
|
3851 | button?: MouseButton;
|
3852 | clickCount?: number;
|
3853 | }
|
3854 |
|
3855 | /**
|
3856 | * @public
|
3857 | */
|
3858 | export declare interface MouseWheelOptions {
|
3859 | deltaX?: number;
|
3860 | deltaY?: number;
|
3861 | }
|
3862 |
|
3863 | /**
|
3864 | * @public
|
3865 | */
|
3866 | export declare interface NetworkConditions {
|
3867 | download: number;
|
3868 | upload: number;
|
3869 | latency: number;
|
3870 | }
|
3871 |
|
3872 | /**
|
3873 | * @public
|
3874 | */
|
3875 | export declare let networkConditions: PredefinedNetworkConditions;
|
3876 |
|
3877 | /**
|
3878 | * @internal
|
3879 | */
|
3880 | export declare class NetworkManager extends EventEmitter {
|
3881 | _client: CDPSession;
|
3882 | _ignoreHTTPSErrors: boolean;
|
3883 | _frameManager: FrameManager;
|
3884 | _requestIdToRequestWillBeSentEvent: Map<string, Protocol.Network.RequestWillBeSentEvent>;
|
3885 | _requestIdToRequestPausedEvent: Map<string, Protocol.Fetch.RequestPausedEvent>;
|
3886 | _requestIdToRequest: Map<string, HTTPRequest>;
|
3887 | _extraHTTPHeaders: Record<string, string>;
|
3888 | _credentials?: Credentials;
|
3889 | _attemptedAuthentications: Set<string>;
|
3890 | _userRequestInterceptionEnabled: boolean;
|
3891 | _protocolRequestInterceptionEnabled: boolean;
|
3892 | _userCacheDisabled: boolean;
|
3893 | _emulatedNetworkConditions: InternalNetworkConditions;
|
3894 | constructor(client: CDPSession, ignoreHTTPSErrors: boolean, frameManager: FrameManager);
|
3895 | initialize(): Promise<void>;
|
3896 | authenticate(credentials?: Credentials): Promise<void>;
|
3897 | setExtraHTTPHeaders(extraHTTPHeaders: Record<string, string>): Promise<void>;
|
3898 | extraHTTPHeaders(): Record<string, string>;
|
3899 | numRequestsInProgress(): number;
|
3900 | setOfflineMode(value: boolean): Promise<void>;
|
3901 | emulateNetworkConditions(networkConditions: NetworkConditions | null): Promise<void>;
|
3902 | _updateNetworkConditions(): Promise<void>;
|
3903 | setUserAgent(userAgent: string, userAgentMetadata?: Protocol.Emulation.UserAgentMetadata): Promise<void>;
|
3904 | setCacheEnabled(enabled: boolean): Promise<void>;
|
3905 | setRequestInterception(value: boolean): Promise<void>;
|
3906 | _updateProtocolRequestInterception(): Promise<void>;
|
3907 | _cacheDisabled(): boolean;
|
3908 | _updateProtocolCacheDisabled(): Promise<void>;
|
3909 | _onRequestWillBeSent(event: Protocol.Network.RequestWillBeSentEvent): void;
|
3910 | _onAuthRequired(event: Protocol.Fetch.AuthRequiredEvent): void;
|
3911 | _onRequestPaused(event: Protocol.Fetch.RequestPausedEvent): void;
|
3912 | _onRequest(event: Protocol.Network.RequestWillBeSentEvent, interceptionId?: string): void;
|
3913 | _onRequestServedFromCache(event: Protocol.Network.RequestServedFromCacheEvent): void;
|
3914 | _handleRequestRedirect(request: HTTPRequest, responsePayload: Protocol.Network.Response): void;
|
3915 | _onResponseReceived(event: Protocol.Network.ResponseReceivedEvent): void;
|
3916 | _forgetRequest(request: HTTPRequest, events: boolean): void;
|
3917 | _onLoadingFinished(event: Protocol.Network.LoadingFinishedEvent): void;
|
3918 | _onLoadingFailed(event: Protocol.Network.LoadingFailedEvent): void;
|
3919 | }
|
3920 |
|
3921 | /**
|
3922 | * We use symbols to prevent any external parties listening to these events.
|
3923 | * They are internal to Puppeteer.
|
3924 | *
|
3925 | * @internal
|
3926 | */
|
3927 | export declare const NetworkManagerEmittedEvents: {
|
3928 | readonly Request: symbol;
|
3929 | readonly RequestServedFromCache: symbol;
|
3930 | readonly Response: symbol;
|
3931 | readonly RequestFailed: symbol;
|
3932 | readonly RequestFinished: symbol;
|
3933 | };
|
3934 |
|
3935 | /**
|
3936 | * @public
|
3937 | */
|
3938 | export declare interface Offset {
|
3939 | /**
|
3940 | * x-offset for the clickable point relative to the top-left corder of the border box.
|
3941 | */
|
3942 | x: number;
|
3943 | /**
|
3944 | * y-offset for the clickable point relative to the top-left corder of the border box.
|
3945 | */
|
3946 | y: number;
|
3947 | }
|
3948 |
|
3949 | /**
|
3950 | * Page provides methods to interact with a single tab or
|
3951 | * {@link https://developer.chrome.com/extensions/background_pages | extension background page} in Chromium.
|
3952 | *
|
3953 | * @remarks
|
3954 | *
|
3955 | * One Browser instance might have multiple Page instances.
|
3956 | *
|
3957 | * @example
|
3958 | * This example creates a page, navigates it to a URL, and then * saves a screenshot:
|
3959 | * ```js
|
3960 | * const puppeteer = require('puppeteer');
|
3961 | *
|
3962 | * (async () => {
|
3963 | * const browser = await puppeteer.launch();
|
3964 | * const page = await browser.newPage();
|
3965 | * await page.goto('https://example.com');
|
3966 | * await page.screenshot({path: 'screenshot.png'});
|
3967 | * await browser.close();
|
3968 | * })();
|
3969 | * ```
|
3970 | *
|
3971 | * The Page class extends from Puppeteer's {@link EventEmitter} class and will
|
3972 | * emit various events which are documented in the {@link PageEmittedEvents} enum.
|
3973 | *
|
3974 | * @example
|
3975 | * This example logs a message for a single page `load` event:
|
3976 | * ```js
|
3977 | * page.once('load', () => console.log('Page loaded!'));
|
3978 | * ```
|
3979 | *
|
3980 | * To unsubscribe from events use the `off` method:
|
3981 | *
|
3982 | * ```js
|
3983 | * function logRequest(interceptedRequest) {
|
3984 | * console.log('A request was made:', interceptedRequest.url());
|
3985 | * }
|
3986 | * page.on('request', logRequest);
|
3987 | * // Sometime later...
|
3988 | * page.off('request', logRequest);
|
3989 | * ```
|
3990 | * @public
|
3991 | */
|
3992 | export declare class Page extends EventEmitter {
|
3993 | /**
|
3994 | * @internal
|
3995 | */
|
3996 | static create(client: CDPSession, target: Target, ignoreHTTPSErrors: boolean, defaultViewport: Viewport | null): Promise<Page>;
|
3997 | private _closed;
|
3998 | private _client;
|
3999 | private _target;
|
4000 | private _keyboard;
|
4001 | private _mouse;
|
4002 | private _timeoutSettings;
|
4003 | private _touchscreen;
|
4004 | private _accessibility;
|
4005 | private _frameManager;
|
4006 | private _emulationManager;
|
4007 | private _tracing;
|
4008 | private _pageBindings;
|
4009 | private _coverage;
|
4010 | private _javascriptEnabled;
|
4011 | private _viewport;
|
4012 | private _screenshotTaskQueue;
|
4013 | private _workers;
|
4014 | private _fileChooserInterceptors;
|
4015 | private _disconnectPromise?;
|
4016 | private _userDragInterceptionEnabled;
|
4017 | /**
|
4018 | * @internal
|
4019 | */
|
4020 | constructor(client: CDPSession, target: Target, ignoreHTTPSErrors: boolean);
|
4021 | private _initialize;
|
4022 | private _onFileChooser;
|
4023 | /**
|
4024 | * @returns `true` if drag events are being intercepted, `false` otherwise.
|
4025 | */
|
4026 | isDragInterceptionEnabled(): boolean;
|
4027 | /**
|
4028 | * @returns `true` if the page has JavaScript enabled, `false` otherwise.
|
4029 | */
|
4030 | isJavaScriptEnabled(): boolean;
|
4031 | /**
|
4032 | * Listen to page events.
|
4033 | */
|
4034 | on<K extends keyof PageEventObject>(eventName: K, handler: (event: PageEventObject[K]) => void): EventEmitter;
|
4035 | once<K extends keyof PageEventObject>(eventName: K, handler: (event: PageEventObject[K]) => void): EventEmitter;
|
4036 | /**
|
4037 | * This method is typically coupled with an action that triggers file
|
4038 | * choosing. The following example clicks a button that issues a file chooser
|
4039 | * and then responds with `/tmp/myfile.pdf` as if a user has selected this file.
|
4040 | *
|
4041 | * ```js
|
4042 | * const [fileChooser] = await Promise.all([
|
4043 | * page.waitForFileChooser(),
|
4044 | * page.click('#upload-file-button'),
|
4045 | * // some button that triggers file selection
|
4046 | * ]);
|
4047 | * await fileChooser.accept(['/tmp/myfile.pdf']);
|
4048 | * ```
|
4049 | *
|
4050 | * NOTE: This must be called before the file chooser is launched. It will not
|
4051 | * return a currently active file chooser.
|
4052 | * @param options - Optional waiting parameters
|
4053 | * @returns Resolves after a page requests a file picker.
|
4054 | * @remarks
|
4055 | * NOTE: In non-headless Chromium, this method results in the native file picker
|
4056 | * dialog `not showing up` for the user.
|
4057 | */
|
4058 | waitForFileChooser(options?: WaitTimeoutOptions): Promise<FileChooser>;
|
4059 | /**
|
4060 | * Sets the page's geolocation.
|
4061 | * @remarks
|
4062 | * NOTE: Consider using {@link BrowserContext.overridePermissions} to grant
|
4063 | * permissions for the page to read its geolocation.
|
4064 | * @example
|
4065 | * ```js
|
4066 | * await page.setGeolocation({latitude: 59.95, longitude: 30.31667});
|
4067 | * ```
|
4068 | */
|
4069 | setGeolocation(options: GeolocationOptions): Promise<void>;
|
4070 | /**
|
4071 | * @returns A target this page was created from.
|
4072 | */
|
4073 | target(): Target;
|
4074 | /**
|
4075 | * Get the CDP session client the page belongs to.
|
4076 | * @internal
|
4077 | */
|
4078 | client(): CDPSession;
|
4079 | /**
|
4080 | * Get the browser the page belongs to.
|
4081 | */
|
4082 | browser(): Browser;
|
4083 | /**
|
4084 | * Get the browser context that the page belongs to.
|
4085 | */
|
4086 | browserContext(): BrowserContext;
|
4087 | private _onTargetCrashed;
|
4088 | private _onLogEntryAdded;
|
4089 | /**
|
4090 | * @returns The page's main frame.
|
4091 | * @remarks
|
4092 | * Page is guaranteed to have a main frame which persists during navigations.
|
4093 | */
|
4094 | mainFrame(): Frame;
|
4095 | get keyboard(): Keyboard;
|
4096 | get touchscreen(): Touchscreen;
|
4097 | get coverage(): Coverage;
|
4098 | get tracing(): Tracing;
|
4099 | get accessibility(): Accessibility;
|
4100 | /**
|
4101 | * @returns An array of all frames attached to the page.
|
4102 | */
|
4103 | frames(): Frame[];
|
4104 | /**
|
4105 | * @returns all of the dedicated
|
4106 | * {@link https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API |
|
4107 | * WebWorkers}
|
4108 | * associated with the page.
|
4109 | * @remarks
|
4110 | * NOTE: This does not contain ServiceWorkers
|
4111 | */
|
4112 | workers(): WebWorker[];
|
4113 | /**
|
4114 | * @param value - Whether to enable request interception.
|
4115 | *
|
4116 | * @remarks
|
4117 | * Activating request interception enables {@link HTTPRequest.abort},
|
4118 | * {@link HTTPRequest.continue} and {@link HTTPRequest.respond} methods. This
|
4119 | * provides the capability to modify network requests that are made by a page.
|
4120 | *
|
4121 | * Once request interception is enabled, every request will stall unless it's
|
4122 | * continued, responded or aborted; or completed using the browser cache.
|
4123 | *
|
4124 | * @example
|
4125 | * An example of a naïve request interceptor that aborts all image requests:
|
4126 | * ```js
|
4127 | * const puppeteer = require('puppeteer');
|
4128 | * (async () => {
|
4129 | * const browser = await puppeteer.launch();
|
4130 | * const page = await browser.newPage();
|
4131 | * await page.setRequestInterception(true);
|
4132 | * page.on('request', interceptedRequest => {
|
4133 | * if (interceptedRequest.url().endsWith('.png') ||
|
4134 | * interceptedRequest.url().endsWith('.jpg'))
|
4135 | * interceptedRequest.abort();
|
4136 | * else
|
4137 | * interceptedRequest.continue();
|
4138 | * });
|
4139 | * await page.goto('https://example.com');
|
4140 | * await browser.close();
|
4141 | * })();
|
4142 | * ```
|
4143 | * NOTE: Enabling request interception disables page caching.
|
4144 | */
|
4145 | setRequestInterception(value: boolean): Promise<void>;
|
4146 | /**
|
4147 | * @param enabled - Whether to enable drag interception.
|
4148 | *
|
4149 | * @remarks
|
4150 | * Activating drag interception enables the `Input.drag`,
|
4151 | * methods This provides the capability to capture drag events emitted
|
4152 | * on the page, which can then be used to simulate drag-and-drop.
|
4153 | */
|
4154 | setDragInterception(enabled: boolean): Promise<void>;
|
4155 | /**
|
4156 | * @param enabled - When `true`, enables offline mode for the page.
|
4157 | * @remarks
|
4158 | * NOTE: while this method sets the network connection to offline, it does
|
4159 | * not change the parameters used in [page.emulateNetworkConditions(networkConditions)]
|
4160 | * (#pageemulatenetworkconditionsnetworkconditions)
|
4161 | */
|
4162 | setOfflineMode(enabled: boolean): Promise<void>;
|
4163 | /**
|
4164 | * @param networkConditions - Passing `null` disables network condition emulation.
|
4165 | * @example
|
4166 | * ```js
|
4167 | * const puppeteer = require('puppeteer');
|
4168 | * const slow3G = puppeteer.networkConditions['Slow 3G'];
|
4169 | *
|
4170 | * (async () => {
|
4171 | * const browser = await puppeteer.launch();
|
4172 | * const page = await browser.newPage();
|
4173 | * await page.emulateNetworkConditions(slow3G);
|
4174 | * await page.goto('https://www.google.com');
|
4175 | * // other actions...
|
4176 | * await browser.close();
|
4177 | * })();
|
4178 | * ```
|
4179 | * @remarks
|
4180 | * NOTE: This does not affect WebSockets and WebRTC PeerConnections (see
|
4181 | * https://crbug.com/563644). To set the page offline, you can use
|
4182 | * [page.setOfflineMode(enabled)](#pagesetofflinemodeenabled).
|
4183 | */
|
4184 | emulateNetworkConditions(networkConditions: NetworkConditions | null): Promise<void>;
|
4185 | /**
|
4186 | * This setting will change the default maximum navigation time for the
|
4187 | * following methods and related shortcuts:
|
4188 | *
|
4189 | * - {@link Page.goBack | page.goBack(options)}
|
4190 | *
|
4191 | * - {@link Page.goForward | page.goForward(options)}
|
4192 | *
|
4193 | * - {@link Page.goto | page.goto(url,options)}
|
4194 | *
|
4195 | * - {@link Page.reload | page.reload(options)}
|
4196 | *
|
4197 | * - {@link Page.setContent | page.setContent(html,options)}
|
4198 | *
|
4199 | * - {@link Page.waitForNavigation | page.waitForNavigation(options)}
|
4200 | * @param timeout - Maximum navigation time in milliseconds.
|
4201 | */
|
4202 | setDefaultNavigationTimeout(timeout: number): void;
|
4203 | /**
|
4204 | * @param timeout - Maximum time in milliseconds.
|
4205 | */
|
4206 | setDefaultTimeout(timeout: number): void;
|
4207 | /**
|
4208 | * Runs `document.querySelector` within the page. If no element matches the
|
4209 | * selector, the return value resolves to `null`.
|
4210 | *
|
4211 | * @remarks
|
4212 | * Shortcut for {@link Frame.$ | Page.mainFrame().$(selector) }.
|
4213 | *
|
4214 | * @param selector - A `selector` to query page for
|
4215 | * {@link https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors | selector}
|
4216 | * to query page for.
|
4217 | */
|
4218 | $<T extends Element = Element>(selector: string): Promise<ElementHandle<T> | null>;
|
4219 | /**
|
4220 | * @remarks
|
4221 | *
|
4222 | * The only difference between {@link Page.evaluate | page.evaluate} and
|
4223 | * `page.evaluateHandle` is that `evaluateHandle` will return the value
|
4224 | * wrapped in an in-page object.
|
4225 | *
|
4226 | * If the function passed to `page.evaluteHandle` returns a Promise, the
|
4227 | * function will wait for the promise to resolve and return its value.
|
4228 | *
|
4229 | * You can pass a string instead of a function (although functions are
|
4230 | * recommended as they are easier to debug and use with TypeScript):
|
4231 | *
|
4232 | * @example
|
4233 | * ```
|
4234 | * const aHandle = await page.evaluateHandle('document')
|
4235 | * ```
|
4236 | *
|
4237 | * @example
|
4238 | * {@link JSHandle} instances can be passed as arguments to the `pageFunction`:
|
4239 | * ```
|
4240 | * const aHandle = await page.evaluateHandle(() => document.body);
|
4241 | * const resultHandle = await page.evaluateHandle(body => body.innerHTML, aHandle);
|
4242 | * console.log(await resultHandle.jsonValue());
|
4243 | * await resultHandle.dispose();
|
4244 | * ```
|
4245 | *
|
4246 | * Most of the time this function returns a {@link JSHandle},
|
4247 | * but if `pageFunction` returns a reference to an element,
|
4248 | * you instead get an {@link ElementHandle} back:
|
4249 | *
|
4250 | * @example
|
4251 | * ```
|
4252 | * const button = await page.evaluateHandle(() => document.querySelector('button'));
|
4253 | * // can call `click` because `button` is an `ElementHandle`
|
4254 | * await button.click();
|
4255 | * ```
|
4256 | *
|
4257 | * The TypeScript definitions assume that `evaluateHandle` returns
|
4258 | * a `JSHandle`, but if you know it's going to return an
|
4259 | * `ElementHandle`, pass it as the generic argument:
|
4260 | *
|
4261 | * ```
|
4262 | * const button = await page.evaluateHandle<ElementHandle>(...);
|
4263 | * ```
|
4264 | *
|
4265 | * @param pageFunction - a function that is run within the page
|
4266 | * @param args - arguments to be passed to the pageFunction
|
4267 | */
|
4268 | evaluateHandle<HandlerType extends JSHandle = JSHandle>(pageFunction: EvaluateHandleFn, ...args: SerializableOrJSHandle[]): Promise<HandlerType>;
|
4269 | /**
|
4270 | * This method iterates the JavaScript heap and finds all objects with the
|
4271 | * given prototype.
|
4272 | *
|
4273 | * @remarks
|
4274 | * Shortcut for
|
4275 | * {@link ExecutionContext.queryObjects |
|
4276 | * page.mainFrame().executionContext().queryObjects(prototypeHandle)}.
|
4277 | *
|
4278 | * @example
|
4279 | *
|
4280 | * ```js
|
4281 | * // Create a Map object
|
4282 | * await page.evaluate(() => window.map = new Map());
|
4283 | * // Get a handle to the Map object prototype
|
4284 | * const mapPrototype = await page.evaluateHandle(() => Map.prototype);
|
4285 | * // Query all map instances into an array
|
4286 | * const mapInstances = await page.queryObjects(mapPrototype);
|
4287 | * // Count amount of map objects in heap
|
4288 | * const count = await page.evaluate(maps => maps.length, mapInstances);
|
4289 | * await mapInstances.dispose();
|
4290 | * await mapPrototype.dispose();
|
4291 | * ```
|
4292 | * @param prototypeHandle - a handle to the object prototype.
|
4293 | * @returns Promise which resolves to a handle to an array of objects with
|
4294 | * this prototype.
|
4295 | */
|
4296 | queryObjects(prototypeHandle: JSHandle): Promise<JSHandle>;
|
4297 | /**
|
4298 | * This method runs `document.querySelector` within the page and passes the
|
4299 | * result as the first argument to the `pageFunction`.
|
4300 | *
|
4301 | * @remarks
|
4302 | *
|
4303 | * If no element is found matching `selector`, the method will throw an error.
|
4304 | *
|
4305 | * If `pageFunction` returns a promise `$eval` will wait for the promise to
|
4306 | * resolve and then return its value.
|
4307 | *
|
4308 | * @example
|
4309 | *
|
4310 | * ```
|
4311 | * const searchValue = await page.$eval('#search', el => el.value);
|
4312 | * const preloadHref = await page.$eval('link[rel=preload]', el => el.href);
|
4313 | * const html = await page.$eval('.main-container', el => el.outerHTML);
|
4314 | * ```
|
4315 | *
|
4316 | * If you are using TypeScript, you may have to provide an explicit type to the
|
4317 | * first argument of the `pageFunction`.
|
4318 | * By default it is typed as `Element`, but you may need to provide a more
|
4319 | * specific sub-type:
|
4320 | *
|
4321 | * @example
|
4322 | *
|
4323 | * ```
|
4324 | * // if you don't provide HTMLInputElement here, TS will error
|
4325 | * // as `value` is not on `Element`
|
4326 | * const searchValue = await page.$eval('#search', (el: HTMLInputElement) => el.value);
|
4327 | * ```
|
4328 | *
|
4329 | * The compiler should be able to infer the return type
|
4330 | * from the `pageFunction` you provide. If it is unable to, you can use the generic
|
4331 | * type to tell the compiler what return type you expect from `$eval`:
|
4332 | *
|
4333 | * @example
|
4334 | *
|
4335 | * ```
|
4336 | * // The compiler can infer the return type in this case, but if it can't
|
4337 | * // or if you want to be more explicit, provide it as the generic type.
|
4338 | * const searchValue = await page.$eval<string>(
|
4339 | * '#search', (el: HTMLInputElement) => el.value
|
4340 | * );
|
4341 | * ```
|
4342 | *
|
4343 | * @param selector - the
|
4344 | * {@link https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors | selector}
|
4345 | * to query for
|
4346 | * @param pageFunction - the function to be evaluated in the page context.
|
4347 | * Will be passed the result of `document.querySelector(selector)` as its
|
4348 | * first argument.
|
4349 | * @param args - any additional arguments to pass through to `pageFunction`.
|
4350 | *
|
4351 | * @returns The result of calling `pageFunction`. If it returns an element it
|
4352 | * is wrapped in an {@link ElementHandle}, else the raw value itself is
|
4353 | * returned.
|
4354 | */
|
4355 | $eval<ReturnType>(selector: string, pageFunction: (element: Element, ...args: unknown[]) => ReturnType | Promise<ReturnType>, ...args: SerializableOrJSHandle[]): Promise<WrapElementHandle<ReturnType>>;
|
4356 | /**
|
4357 | * This method runs `Array.from(document.querySelectorAll(selector))` within
|
4358 | * the page and passes the result as the first argument to the `pageFunction`.
|
4359 | *
|
4360 | * @remarks
|
4361 | *
|
4362 | * If `pageFunction` returns a promise `$$eval` will wait for the promise to
|
4363 | * resolve and then return its value.
|
4364 | *
|
4365 | * @example
|
4366 | *
|
4367 | * ```
|
4368 | * // get the amount of divs on the page
|
4369 | * const divCount = await page.$$eval('div', divs => divs.length);
|
4370 | *
|
4371 | * // get the text content of all the `.options` elements:
|
4372 | * const options = await page.$$eval('div > span.options', options => {
|
4373 | * return options.map(option => option.textContent)
|
4374 | * });
|
4375 | * ```
|
4376 | *
|
4377 | * If you are using TypeScript, you may have to provide an explicit type to the
|
4378 | * first argument of the `pageFunction`.
|
4379 | * By default it is typed as `Element[]`, but you may need to provide a more
|
4380 | * specific sub-type:
|
4381 | *
|
4382 | * @example
|
4383 | *
|
4384 | * ```
|
4385 | * // if you don't provide HTMLInputElement here, TS will error
|
4386 | * // as `value` is not on `Element`
|
4387 | * await page.$$eval('input', (elements: HTMLInputElement[]) => {
|
4388 | * return elements.map(e => e.value);
|
4389 | * });
|
4390 | * ```
|
4391 | *
|
4392 | * The compiler should be able to infer the return type
|
4393 | * from the `pageFunction` you provide. If it is unable to, you can use the generic
|
4394 | * type to tell the compiler what return type you expect from `$$eval`:
|
4395 | *
|
4396 | * @example
|
4397 | *
|
4398 | * ```
|
4399 | * // The compiler can infer the return type in this case, but if it can't
|
4400 | * // or if you want to be more explicit, provide it as the generic type.
|
4401 | * const allInputValues = await page.$$eval<string[]>(
|
4402 | * 'input', (elements: HTMLInputElement[]) => elements.map(e => e.textContent)
|
4403 | * );
|
4404 | * ```
|
4405 | *
|
4406 | * @param selector - the
|
4407 | * {@link https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors | selector}
|
4408 | * to query for
|
4409 | * @param pageFunction - the function to be evaluated in the page context. Will
|
4410 | * be passed the result of `Array.from(document.querySelectorAll(selector))`
|
4411 | * as its first argument.
|
4412 | * @param args - any additional arguments to pass through to `pageFunction`.
|
4413 | *
|
4414 | * @returns The result of calling `pageFunction`. If it returns an element it
|
4415 | * is wrapped in an {@link ElementHandle}, else the raw value itself is
|
4416 | * returned.
|
4417 | */
|
4418 | $$eval<ReturnType>(selector: string, pageFunction: (elements: Element[], ...args: unknown[]) => ReturnType | Promise<ReturnType>, ...args: SerializableOrJSHandle[]): Promise<WrapElementHandle<ReturnType>>;
|
4419 | /**
|
4420 | * The method runs `document.querySelectorAll` within the page. If no elements
|
4421 | * match the selector, the return value resolves to `[]`.
|
4422 | * @remarks
|
4423 | * Shortcut for {@link Frame.$$ | Page.mainFrame().$$(selector) }.
|
4424 | * @param selector - A `selector` to query page for
|
4425 | */
|
4426 | $$<T extends Element = Element>(selector: string): Promise<Array<ElementHandle<T>>>;
|
4427 | /**
|
4428 | * The method evaluates the XPath expression relative to the page document as
|
4429 | * its context node. If there are no such elements, the method resolves to an
|
4430 | * empty array.
|
4431 | * @remarks
|
4432 | * Shortcut for {@link Frame.$x | Page.mainFrame().$x(expression) }.
|
4433 | * @param expression - Expression to evaluate
|
4434 | */
|
4435 | $x(expression: string): Promise<ElementHandle[]>;
|
4436 | /**
|
4437 | * If no URLs are specified, this method returns cookies for the current page
|
4438 | * URL. If URLs are specified, only cookies for those URLs are returned.
|
4439 | */
|
4440 | cookies(...urls: string[]): Promise<Protocol.Network.Cookie[]>;
|
4441 | deleteCookie(...cookies: Protocol.Network.DeleteCookiesRequest[]): Promise<void>;
|
4442 | /**
|
4443 | * @example
|
4444 | * ```js
|
4445 | * await page.setCookie(cookieObject1, cookieObject2);
|
4446 | * ```
|
4447 | */
|
4448 | setCookie(...cookies: Protocol.Network.CookieParam[]): Promise<void>;
|
4449 | /**
|
4450 | * Adds a `<script>` tag into the page with the desired URL or content.
|
4451 | * @remarks
|
4452 | * Shortcut for {@link Frame.addScriptTag | page.mainFrame().addScriptTag(options) }.
|
4453 | * @returns Promise which resolves to the added tag when the script's onload fires or
|
4454 | * when the script content was injected into frame.
|
4455 | */
|
4456 | addScriptTag(options: {
|
4457 | url?: string;
|
4458 | path?: string;
|
4459 | content?: string;
|
4460 | type?: string;
|
4461 | id?: string;
|
4462 | }): Promise<ElementHandle>;
|
4463 | /**
|
4464 | * Adds a `<link rel="stylesheet">` tag into the page with the desired URL or a
|
4465 | * `<style type="text/css">` tag with the content.
|
4466 | * @returns Promise which resolves to the added tag when the stylesheet's
|
4467 | * onload fires or when the CSS content was injected into frame.
|
4468 | */
|
4469 | addStyleTag(options: {
|
4470 | url?: string;
|
4471 | path?: string;
|
4472 | content?: string;
|
4473 | }): Promise<ElementHandle>;
|
4474 | /**
|
4475 | * The method adds a function called `name` on the page's `window` object. When
|
4476 | * called, the function executes `puppeteerFunction` in node.js and returns a
|
4477 | * `Promise` which resolves to the return value of `puppeteerFunction`.
|
4478 | *
|
4479 | * If the puppeteerFunction returns a `Promise`, it will be awaited.
|
4480 | *
|
4481 | * NOTE: Functions installed via `page.exposeFunction` survive navigations.
|
4482 | * @param name - Name of the function on the window object
|
4483 | * @param puppeteerFunction - Callback function which will be called in
|
4484 | * Puppeteer's context.
|
4485 | * @example
|
4486 | * An example of adding an `md5` function into the page:
|
4487 | * ```js
|
4488 | * const puppeteer = require('puppeteer');
|
4489 | * const crypto = require('crypto');
|
4490 | *
|
4491 | * (async () => {
|
4492 | * const browser = await puppeteer.launch();
|
4493 | * const page = await browser.newPage();
|
4494 | * page.on('console', (msg) => console.log(msg.text()));
|
4495 | * await page.exposeFunction('md5', (text) =>
|
4496 | * crypto.createHash('md5').update(text).digest('hex')
|
4497 | * );
|
4498 | * await page.evaluate(async () => {
|
4499 | * // use window.md5 to compute hashes
|
4500 | * const myString = 'PUPPETEER';
|
4501 | * const myHash = await window.md5(myString);
|
4502 | * console.log(`md5 of ${myString} is ${myHash}`);
|
4503 | * });
|
4504 | * await browser.close();
|
4505 | * })();
|
4506 | * ```
|
4507 | * An example of adding a `window.readfile` function into the page:
|
4508 | * ```js
|
4509 | * const puppeteer = require('puppeteer');
|
4510 | * const fs = require('fs');
|
4511 | *
|
4512 | * (async () => {
|
4513 | * const browser = await puppeteer.launch();
|
4514 | * const page = await browser.newPage();
|
4515 | * page.on('console', (msg) => console.log(msg.text()));
|
4516 | * await page.exposeFunction('readfile', async (filePath) => {
|
4517 | * return new Promise((resolve, reject) => {
|
4518 | * fs.readFile(filePath, 'utf8', (err, text) => {
|
4519 | * if (err) reject(err);
|
4520 | * else resolve(text);
|
4521 | * });
|
4522 | * });
|
4523 | * });
|
4524 | * await page.evaluate(async () => {
|
4525 | * // use window.readfile to read contents of a file
|
4526 | * const content = await window.readfile('/etc/hosts');
|
4527 | * console.log(content);
|
4528 | * });
|
4529 | * await browser.close();
|
4530 | * })();
|
4531 | * ```
|
4532 | */
|
4533 | exposeFunction(name: string, puppeteerFunction: Function): Promise<void>;
|
4534 | /**
|
4535 | * Provide credentials for `HTTP authentication`.
|
4536 | * @remarks To disable authentication, pass `null`.
|
4537 | */
|
4538 | authenticate(credentials: Credentials): Promise<void>;
|
4539 | /**
|
4540 | * The extra HTTP headers will be sent with every request the page initiates.
|
4541 | * NOTE: All HTTP header names are lowercased. (HTTP headers are
|
4542 | * case-insensitive, so this shouldn’t impact your server code.)
|
4543 | * NOTE: page.setExtraHTTPHeaders does not guarantee the order of headers in
|
4544 | * the outgoing requests.
|
4545 | * @param headers - An object containing additional HTTP headers to be sent
|
4546 | * with every request. All header values must be strings.
|
4547 | * @returns
|
4548 | */
|
4549 | setExtraHTTPHeaders(headers: Record<string, string>): Promise<void>;
|
4550 | /**
|
4551 | * @param userAgent - Specific user agent to use in this page
|
4552 | * @param userAgentData - Specific user agent client hint data to use in this
|
4553 | * page
|
4554 | * @returns Promise which resolves when the user agent is set.
|
4555 | */
|
4556 | setUserAgent(userAgent: string, userAgentMetadata?: Protocol.Emulation.UserAgentMetadata): Promise<void>;
|
4557 | /**
|
4558 | * @returns Object containing metrics as key/value pairs.
|
4559 | *
|
4560 | * - `Timestamp` : The timestamp when the metrics sample was taken.
|
4561 | *
|
4562 | * - `Documents` : Number of documents in the page.
|
4563 | *
|
4564 | * - `Frames` : Number of frames in the page.
|
4565 | *
|
4566 | * - `JSEventListeners` : Number of events in the page.
|
4567 | *
|
4568 | * - `Nodes` : Number of DOM nodes in the page.
|
4569 | *
|
4570 | * - `LayoutCount` : Total number of full or partial page layout.
|
4571 | *
|
4572 | * - `RecalcStyleCount` : Total number of page style recalculations.
|
4573 | *
|
4574 | * - `LayoutDuration` : Combined durations of all page layouts.
|
4575 | *
|
4576 | * - `RecalcStyleDuration` : Combined duration of all page style
|
4577 | * recalculations.
|
4578 | *
|
4579 | * - `ScriptDuration` : Combined duration of JavaScript execution.
|
4580 | *
|
4581 | * - `TaskDuration` : Combined duration of all tasks performed by the browser.
|
4582 | *
|
4583 | *
|
4584 | * - `JSHeapUsedSize` : Used JavaScript heap size.
|
4585 | *
|
4586 | * - `JSHeapTotalSize` : Total JavaScript heap size.
|
4587 | * @remarks
|
4588 | * NOTE: All timestamps are in monotonic time: monotonically increasing time
|
4589 | * in seconds since an arbitrary point in the past.
|
4590 | */
|
4591 | metrics(): Promise<Metrics>;
|
4592 | private _emitMetrics;
|
4593 | private _buildMetricsObject;
|
4594 | private _handleException;
|
4595 | private _onConsoleAPI;
|
4596 | private _onBindingCalled;
|
4597 | private _addConsoleMessage;
|
4598 | private _onDialog;
|
4599 | /**
|
4600 | * Resets default white background
|
4601 | */
|
4602 | private _resetDefaultBackgroundColor;
|
4603 | /**
|
4604 | * Hides default white background
|
4605 | */
|
4606 | private _setTransparentBackgroundColor;
|
4607 | /**
|
4608 | *
|
4609 | * @returns
|
4610 | * @remarks Shortcut for
|
4611 | * {@link Frame.url | page.mainFrame().url()}.
|
4612 | */
|
4613 | url(): string;
|
4614 | content(): Promise<string>;
|
4615 | /**
|
4616 | * @param html - HTML markup to assign to the page.
|
4617 | * @param options - Parameters that has some properties.
|
4618 | * @remarks
|
4619 | * The parameter `options` might have the following options.
|
4620 | *
|
4621 | * - `timeout` : Maximum time in milliseconds for resources to load, defaults
|
4622 | * to 30 seconds, pass `0` to disable timeout. The default value can be
|
4623 | * changed by using the
|
4624 | * {@link Page.setDefaultNavigationTimeout |
|
4625 | * page.setDefaultNavigationTimeout(timeout)}
|
4626 | * or {@link Page.setDefaultTimeout | page.setDefaultTimeout(timeout)}
|
4627 | * methods.
|
4628 | *
|
4629 | * - `waitUntil`: When to consider setting markup succeeded, defaults to `load`.
|
4630 | * Given an array of event strings, setting content is considered to be
|
4631 | * successful after all events have been fired. Events can be either:<br/>
|
4632 | * - `load` : consider setting content to be finished when the `load` event is
|
4633 | * fired.<br/>
|
4634 | * - `domcontentloaded` : consider setting content to be finished when the
|
4635 | * `DOMContentLoaded` event is fired.<br/>
|
4636 | * - `networkidle0` : consider setting content to be finished when there are no
|
4637 | * more than 0 network connections for at least `500` ms.<br/>
|
4638 | * - `networkidle2` : consider setting content to be finished when there are no
|
4639 | * more than 2 network connections for at least `500` ms.
|
4640 | */
|
4641 | setContent(html: string, options?: WaitForOptions): Promise<void>;
|
4642 | /**
|
4643 | * @param url - URL to navigate page to. The URL should include scheme, e.g.
|
4644 | * `https://`
|
4645 | * @param options - Navigation Parameter
|
4646 | * @returns Promise which resolves to the main resource response. In case of
|
4647 | * multiple redirects, the navigation will resolve with the response of the
|
4648 | * last redirect.
|
4649 | * @remarks
|
4650 | * The argument `options` might have the following properties:
|
4651 | *
|
4652 | * - `timeout` : Maximum navigation time in milliseconds, defaults to 30
|
4653 | * seconds, pass 0 to disable timeout. The default value can be changed by
|
4654 | * using the
|
4655 | * {@link Page.setDefaultNavigationTimeout |
|
4656 | * page.setDefaultNavigationTimeout(timeout)}
|
4657 | * or {@link Page.setDefaultTimeout | page.setDefaultTimeout(timeout)}
|
4658 | * methods.
|
4659 | *
|
4660 | * - `waitUntil`:When to consider navigation succeeded, defaults to `load`.
|
4661 | * Given an array of event strings, navigation is considered to be successful
|
4662 | * after all events have been fired. Events can be either:<br/>
|
4663 | * - `load` : consider navigation to be finished when the load event is
|
4664 | * fired.<br/>
|
4665 | * - `domcontentloaded` : consider navigation to be finished when the
|
4666 | * DOMContentLoaded event is fired.<br/>
|
4667 | * - `networkidle0` : consider navigation to be finished when there are no
|
4668 | * more than 0 network connections for at least `500` ms.<br/>
|
4669 | * - `networkidle2` : consider navigation to be finished when there are no
|
4670 | * more than 2 network connections for at least `500` ms.
|
4671 | *
|
4672 | * - `referer` : Referer header value. If provided it will take preference
|
4673 | * over the referer header value set by
|
4674 | * {@link Page.setExtraHTTPHeaders |page.setExtraHTTPHeaders()}.
|
4675 | *
|
4676 | * `page.goto` will throw an error if:
|
4677 | * - there's an SSL error (e.g. in case of self-signed certificates).
|
4678 | * - target URL is invalid.
|
4679 | * - the timeout is exceeded during navigation.
|
4680 | * - the remote server does not respond or is unreachable.
|
4681 | * - the main resource failed to load.
|
4682 | *
|
4683 | * `page.goto` will not throw an error when any valid HTTP status code is
|
4684 | * returned by the remote server, including 404 "Not Found" and 500
|
4685 | * "Internal Server Error". The status code for such responses can be
|
4686 | * retrieved by calling response.status().
|
4687 | *
|
4688 | * NOTE: `page.goto` either throws an error or returns a main resource
|
4689 | * response. The only exceptions are navigation to about:blank or navigation
|
4690 | * to the same URL with a different hash, which would succeed and return null.
|
4691 | *
|
4692 | * NOTE: Headless mode doesn't support navigation to a PDF document. See the
|
4693 | * {@link https://bugs.chromium.org/p/chromium/issues/detail?id=761295
|
4694 | * | upstream issue}.
|
4695 | *
|
4696 | * Shortcut for {@link Frame.goto | page.mainFrame().goto(url, options)}.
|
4697 | */
|
4698 | goto(url: string, options?: WaitForOptions & {
|
4699 | referer?: string;
|
4700 | }): Promise<HTTPResponse>;
|
4701 | /**
|
4702 | * @param options - Navigation parameters which might have the following
|
4703 | * properties:
|
4704 | * @returns Promise which resolves to the main resource response. In case of
|
4705 | * multiple redirects, the navigation will resolve with the response of the
|
4706 | * last redirect.
|
4707 | * @remarks
|
4708 | * The argument `options` might have the following properties:
|
4709 | *
|
4710 | * - `timeout` : Maximum navigation time in milliseconds, defaults to 30
|
4711 | * seconds, pass 0 to disable timeout. The default value can be changed by
|
4712 | * using the
|
4713 | * {@link Page.setDefaultNavigationTimeout |
|
4714 | * page.setDefaultNavigationTimeout(timeout)}
|
4715 | * or {@link Page.setDefaultTimeout | page.setDefaultTimeout(timeout)}
|
4716 | * methods.
|
4717 | *
|
4718 | * - `waitUntil`: When to consider navigation succeeded, defaults to `load`.
|
4719 | * Given an array of event strings, navigation is considered to be
|
4720 | * successful after all events have been fired. Events can be either:<br/>
|
4721 | * - `load` : consider navigation to be finished when the load event is fired.<br/>
|
4722 | * - `domcontentloaded` : consider navigation to be finished when the
|
4723 | * DOMContentLoaded event is fired.<br/>
|
4724 | * - `networkidle0` : consider navigation to be finished when there are no
|
4725 | * more than 0 network connections for at least `500` ms.<br/>
|
4726 | * - `networkidle2` : consider navigation to be finished when there are no
|
4727 | * more than 2 network connections for at least `500` ms.
|
4728 | */
|
4729 | reload(options?: WaitForOptions): Promise<HTTPResponse | null>;
|
4730 | /**
|
4731 | * This resolves when the page navigates to a new URL or reloads. It is useful
|
4732 | * when you run code that will indirectly cause the page to navigate. Consider
|
4733 | * this example:
|
4734 | * ```js
|
4735 | * const [response] = await Promise.all([
|
4736 | * page.waitForNavigation(), // The promise resolves after navigation has finished
|
4737 | * page.click('a.my-link'), // Clicking the link will indirectly cause a navigation
|
4738 | * ]);
|
4739 | * ```
|
4740 | *
|
4741 | * @param options - Navigation parameters which might have the following properties:
|
4742 | * @returns Promise which resolves to the main resource response. In case of
|
4743 | * multiple redirects, the navigation will resolve with the response of the
|
4744 | * last redirect. In case of navigation to a different anchor or navigation
|
4745 | * due to History API usage, the navigation will resolve with `null`.
|
4746 | * @remarks
|
4747 | * NOTE: Usage of the
|
4748 | * {@link https://developer.mozilla.org/en-US/docs/Web/API/History_API | History API}
|
4749 | * to change the URL is considered a navigation.
|
4750 | *
|
4751 | * Shortcut for
|
4752 | * {@link Frame.waitForNavigation | page.mainFrame().waitForNavigation(options)}.
|
4753 | */
|
4754 | waitForNavigation(options?: WaitForOptions): Promise<HTTPResponse | null>;
|
4755 | private _sessionClosePromise;
|
4756 | /**
|
4757 | * @param urlOrPredicate - A URL or predicate to wait for
|
4758 | * @param options - Optional waiting parameters
|
4759 | * @returns Promise which resolves to the matched response
|
4760 | * @example
|
4761 | * ```js
|
4762 | * const firstResponse = await page.waitForResponse(
|
4763 | * 'https://example.com/resource'
|
4764 | * );
|
4765 | * const finalResponse = await page.waitForResponse(
|
4766 | * (response) =>
|
4767 | * response.url() === 'https://example.com' && response.status() === 200
|
4768 | * );
|
4769 | * const finalResponse = await page.waitForResponse(async (response) => {
|
4770 | * return (await response.text()).includes('<html>');
|
4771 | * });
|
4772 | * return finalResponse.ok();
|
4773 | * ```
|
4774 | * @remarks
|
4775 | * Optional Waiting Parameters have:
|
4776 | *
|
4777 | * - `timeout`: Maximum wait time in milliseconds, defaults to `30` seconds, pass
|
4778 | * `0` to disable the timeout. The default value can be changed by using the
|
4779 | * {@link Page.setDefaultTimeout} method.
|
4780 | */
|
4781 | waitForRequest(urlOrPredicate: string | ((req: HTTPRequest) => boolean | Promise<boolean>), options?: {
|
4782 | timeout?: number;
|
4783 | }): Promise<HTTPRequest>;
|
4784 | /**
|
4785 | * @param urlOrPredicate - A URL or predicate to wait for.
|
4786 | * @param options - Optional waiting parameters
|
4787 | * @returns Promise which resolves to the matched response.
|
4788 | * @example
|
4789 | * ```js
|
4790 | * const firstResponse = await page.waitForResponse(
|
4791 | * 'https://example.com/resource'
|
4792 | * );
|
4793 | * const finalResponse = await page.waitForResponse(
|
4794 | * (response) =>
|
4795 | * response.url() === 'https://example.com' && response.status() === 200
|
4796 | * );
|
4797 | * const finalResponse = await page.waitForResponse(async (response) => {
|
4798 | * return (await response.text()).includes('<html>');
|
4799 | * });
|
4800 | * return finalResponse.ok();
|
4801 | * ```
|
4802 | * @remarks
|
4803 | * Optional Parameter have:
|
4804 | *
|
4805 | * - `timeout`: Maximum wait time in milliseconds, defaults to `30` seconds,
|
4806 | * pass `0` to disable the timeout. The default value can be changed by using
|
4807 | * the {@link Page.setDefaultTimeout} method.
|
4808 | */
|
4809 | waitForResponse(urlOrPredicate: string | ((res: HTTPResponse) => boolean | Promise<boolean>), options?: {
|
4810 | timeout?: number;
|
4811 | }): Promise<HTTPResponse>;
|
4812 | /**
|
4813 | * @param options - Optional waiting parameters
|
4814 | * @returns Promise which resolves when network is idle
|
4815 | */
|
4816 | waitForNetworkIdle(options?: {
|
4817 | idleTime?: number;
|
4818 | timeout?: number;
|
4819 | }): Promise<void>;
|
4820 | /**
|
4821 | * This method navigate to the previous page in history.
|
4822 | * @param options - Navigation parameters
|
4823 | * @returns Promise which resolves to the main resource response. In case of
|
4824 | * multiple redirects, the navigation will resolve with the response of the
|
4825 | * last redirect. If can not go back, resolves to `null`.
|
4826 | * @remarks
|
4827 | * The argument `options` might have the following properties:
|
4828 | *
|
4829 | * - `timeout` : Maximum navigation time in milliseconds, defaults to 30
|
4830 | * seconds, pass 0 to disable timeout. The default value can be changed by
|
4831 | * using the
|
4832 | * {@link Page.setDefaultNavigationTimeout
|
4833 | * | page.setDefaultNavigationTimeout(timeout)}
|
4834 | * or {@link Page.setDefaultTimeout | page.setDefaultTimeout(timeout)}
|
4835 | * methods.
|
4836 | *
|
4837 | * - `waitUntil` : When to consider navigation succeeded, defaults to `load`.
|
4838 | * Given an array of event strings, navigation is considered to be
|
4839 | * successful after all events have been fired. Events can be either:<br/>
|
4840 | * - `load` : consider navigation to be finished when the load event is fired.<br/>
|
4841 | * - `domcontentloaded` : consider navigation to be finished when the
|
4842 | * DOMContentLoaded event is fired.<br/>
|
4843 | * - `networkidle0` : consider navigation to be finished when there are no
|
4844 | * more than 0 network connections for at least `500` ms.<br/>
|
4845 | * - `networkidle2` : consider navigation to be finished when there are no
|
4846 | * more than 2 network connections for at least `500` ms.
|
4847 | */
|
4848 | goBack(options?: WaitForOptions): Promise<HTTPResponse | null>;
|
4849 | /**
|
4850 | * This method navigate to the next page in history.
|
4851 | * @param options - Navigation Parameter
|
4852 | * @returns Promise which resolves to the main resource response. In case of
|
4853 | * multiple redirects, the navigation will resolve with the response of the
|
4854 | * last redirect. If can not go forward, resolves to `null`.
|
4855 | * @remarks
|
4856 | * The argument `options` might have the following properties:
|
4857 | *
|
4858 | * - `timeout` : Maximum navigation time in milliseconds, defaults to 30
|
4859 | * seconds, pass 0 to disable timeout. The default value can be changed by
|
4860 | * using the
|
4861 | * {@link Page.setDefaultNavigationTimeout
|
4862 | * | page.setDefaultNavigationTimeout(timeout)}
|
4863 | * or {@link Page.setDefaultTimeout | page.setDefaultTimeout(timeout)}
|
4864 | * methods.
|
4865 | *
|
4866 | * - `waitUntil`: When to consider navigation succeeded, defaults to `load`.
|
4867 | * Given an array of event strings, navigation is considered to be
|
4868 | * successful after all events have been fired. Events can be either:<br/>
|
4869 | * - `load` : consider navigation to be finished when the load event is fired.<br/>
|
4870 | * - `domcontentloaded` : consider navigation to be finished when the
|
4871 | * DOMContentLoaded event is fired.<br/>
|
4872 | * - `networkidle0` : consider navigation to be finished when there are no
|
4873 | * more than 0 network connections for at least `500` ms.<br/>
|
4874 | * - `networkidle2` : consider navigation to be finished when there are no
|
4875 | * more than 2 network connections for at least `500` ms.
|
4876 | */
|
4877 | goForward(options?: WaitForOptions): Promise<HTTPResponse | null>;
|
4878 | private _go;
|
4879 | /**
|
4880 | * Brings page to front (activates tab).
|
4881 | */
|
4882 | bringToFront(): Promise<void>;
|
4883 | /**
|
4884 | * Emulates given device metrics and user agent. This method is a shortcut for
|
4885 | * calling two methods: {@link Page.setUserAgent} and {@link Page.setViewport}
|
4886 | * To aid emulation, Puppeteer provides a list of device descriptors that can
|
4887 | * be obtained via the {@link Puppeteer.devices} `page.emulate` will resize
|
4888 | * the page. A lot of websites don't expect phones to change size, so you
|
4889 | * should emulate before navigating to the page.
|
4890 | * @example
|
4891 | * ```js
|
4892 | * const puppeteer = require('puppeteer');
|
4893 | * const iPhone = puppeteer.devices['iPhone 6'];
|
4894 | * (async () => {
|
4895 | * const browser = await puppeteer.launch();
|
4896 | * const page = await browser.newPage();
|
4897 | * await page.emulate(iPhone);
|
4898 | * await page.goto('https://www.google.com');
|
4899 | * // other actions...
|
4900 | * await browser.close();
|
4901 | * })();
|
4902 | * ```
|
4903 | * @remarks List of all available devices is available in the source code:
|
4904 | * {@link https://github.com/puppeteer/puppeteer/blob/main/src/common/DeviceDescriptors.ts | src/common/DeviceDescriptors.ts}.
|
4905 | */
|
4906 | emulate(options: {
|
4907 | viewport: Viewport;
|
4908 | userAgent: string;
|
4909 | }): Promise<void>;
|
4910 | /**
|
4911 | * @param enabled - Whether or not to enable JavaScript on the page.
|
4912 | * @returns
|
4913 | * @remarks
|
4914 | * NOTE: changing this value won't affect scripts that have already been run.
|
4915 | * It will take full effect on the next navigation.
|
4916 | */
|
4917 | setJavaScriptEnabled(enabled: boolean): Promise<void>;
|
4918 | /**
|
4919 | * Toggles bypassing page's Content-Security-Policy.
|
4920 | * @param enabled - sets bypassing of page's Content-Security-Policy.
|
4921 | * @remarks
|
4922 | * NOTE: CSP bypassing happens at the moment of CSP initialization rather than
|
4923 | * evaluation. Usually, this means that `page.setBypassCSP` should be called
|
4924 | * before navigating to the domain.
|
4925 | */
|
4926 | setBypassCSP(enabled: boolean): Promise<void>;
|
4927 | /**
|
4928 | * @param type - Changes the CSS media type of the page. The only allowed
|
4929 | * values are `screen`, `print` and `null`. Passing `null` disables CSS media
|
4930 | * emulation.
|
4931 | * @example
|
4932 | * ```
|
4933 | * await page.evaluate(() => matchMedia('screen').matches);
|
4934 | * // → true
|
4935 | * await page.evaluate(() => matchMedia('print').matches);
|
4936 | * // → false
|
4937 | *
|
4938 | * await page.emulateMediaType('print');
|
4939 | * await page.evaluate(() => matchMedia('screen').matches);
|
4940 | * // → false
|
4941 | * await page.evaluate(() => matchMedia('print').matches);
|
4942 | * // → true
|
4943 | *
|
4944 | * await page.emulateMediaType(null);
|
4945 | * await page.evaluate(() => matchMedia('screen').matches);
|
4946 | * // → true
|
4947 | * await page.evaluate(() => matchMedia('print').matches);
|
4948 | * // → false
|
4949 | * ```
|
4950 | */
|
4951 | emulateMediaType(type?: string): Promise<void>;
|
4952 | emulateCPUThrottling(factor: number | null): Promise<void>;
|
4953 | /**
|
4954 | * @param features - `<?Array<Object>>` Given an array of media feature
|
4955 | * objects, emulates CSS media features on the page. Each media feature object
|
4956 | * must have the following properties:
|
4957 | * @example
|
4958 | * ```js
|
4959 | * await page.emulateMediaFeatures([
|
4960 | * { name: 'prefers-color-scheme', value: 'dark' },
|
4961 | * ]);
|
4962 | * await page.evaluate(() => matchMedia('(prefers-color-scheme: dark)').matches);
|
4963 | * // → true
|
4964 | * await page.evaluate(() => matchMedia('(prefers-color-scheme: light)').matches);
|
4965 | * // → false
|
4966 | *
|
4967 | * await page.emulateMediaFeatures([
|
4968 | * { name: 'prefers-reduced-motion', value: 'reduce' },
|
4969 | * ]);
|
4970 | * await page.evaluate(
|
4971 | * () => matchMedia('(prefers-reduced-motion: reduce)').matches
|
4972 | * );
|
4973 | * // → true
|
4974 | * await page.evaluate(
|
4975 | * () => matchMedia('(prefers-reduced-motion: no-preference)').matches
|
4976 | * );
|
4977 | * // → false
|
4978 | *
|
4979 | * await page.emulateMediaFeatures([
|
4980 | * { name: 'prefers-color-scheme', value: 'dark' },
|
4981 | * { name: 'prefers-reduced-motion', value: 'reduce' },
|
4982 | * ]);
|
4983 | * await page.evaluate(() => matchMedia('(prefers-color-scheme: dark)').matches);
|
4984 | * // → true
|
4985 | * await page.evaluate(() => matchMedia('(prefers-color-scheme: light)').matches);
|
4986 | * // → false
|
4987 | * await page.evaluate(
|
4988 | * () => matchMedia('(prefers-reduced-motion: reduce)').matches
|
4989 | * );
|
4990 | * // → true
|
4991 | * await page.evaluate(
|
4992 | * () => matchMedia('(prefers-reduced-motion: no-preference)').matches
|
4993 | * );
|
4994 | * // → false
|
4995 | *
|
4996 | * await page.emulateMediaFeatures([{ name: 'color-gamut', value: 'p3' }]);
|
4997 | * await page.evaluate(() => matchMedia('(color-gamut: srgb)').matches);
|
4998 | * // → true
|
4999 | * await page.evaluate(() => matchMedia('(color-gamut: p3)').matches);
|
5000 | * // → true
|
5001 | * await page.evaluate(() => matchMedia('(color-gamut: rec2020)').matches);
|
5002 | * // → false
|
5003 | * ```
|
5004 | */
|
5005 | emulateMediaFeatures(features?: MediaFeature[]): Promise<void>;
|
5006 | /**
|
5007 | * @param timezoneId - Changes the timezone of the page. See
|
5008 | * {@link https://source.chromium.org/chromium/chromium/deps/icu.git/+/faee8bc70570192d82d2978a71e2a615788597d1:source/data/misc/metaZones.txt | ICU’s metaZones.txt}
|
5009 | * for a list of supported timezone IDs. Passing
|
5010 | * `null` disables timezone emulation.
|
5011 | */
|
5012 | emulateTimezone(timezoneId?: string): Promise<void>;
|
5013 | /**
|
5014 | * Emulates the idle state.
|
5015 | * If no arguments set, clears idle state emulation.
|
5016 | *
|
5017 | * @example
|
5018 | * ```js
|
5019 | * // set idle emulation
|
5020 | * await page.emulateIdleState({isUserActive: true, isScreenUnlocked: false});
|
5021 | *
|
5022 | * // do some checks here
|
5023 | * ...
|
5024 | *
|
5025 | * // clear idle emulation
|
5026 | * await page.emulateIdleState();
|
5027 | * ```
|
5028 | *
|
5029 | * @param overrides - Mock idle state. If not set, clears idle overrides
|
5030 | */
|
5031 | emulateIdleState(overrides?: {
|
5032 | isUserActive: boolean;
|
5033 | isScreenUnlocked: boolean;
|
5034 | }): Promise<void>;
|
5035 | /**
|
5036 | * Simulates the given vision deficiency on the page.
|
5037 | *
|
5038 | * @example
|
5039 | * ```js
|
5040 | * const puppeteer = require('puppeteer');
|
5041 | *
|
5042 | * (async () => {
|
5043 | * const browser = await puppeteer.launch();
|
5044 | * const page = await browser.newPage();
|
5045 | * await page.goto('https://v8.dev/blog/10-years');
|
5046 | *
|
5047 | * await page.emulateVisionDeficiency('achromatopsia');
|
5048 | * await page.screenshot({ path: 'achromatopsia.png' });
|
5049 | *
|
5050 | * await page.emulateVisionDeficiency('deuteranopia');
|
5051 | * await page.screenshot({ path: 'deuteranopia.png' });
|
5052 | *
|
5053 | * await page.emulateVisionDeficiency('blurredVision');
|
5054 | * await page.screenshot({ path: 'blurred-vision.png' });
|
5055 | *
|
5056 | * await browser.close();
|
5057 | * })();
|
5058 | * ```
|
5059 | *
|
5060 | * @param type - the type of deficiency to simulate, or `'none'` to reset.
|
5061 | */
|
5062 | emulateVisionDeficiency(type?: Protocol.Emulation.SetEmulatedVisionDeficiencyRequest['type']): Promise<void>;
|
5063 | /**
|
5064 | * `page.setViewport` will resize the page. A lot of websites don't expect
|
5065 | * phones to change size, so you should set the viewport before navigating to
|
5066 | * the page.
|
5067 | *
|
5068 | * In the case of multiple pages in a single browser, each page can have its
|
5069 | * own viewport size.
|
5070 | * @example
|
5071 | * ```js
|
5072 | * const page = await browser.newPage();
|
5073 | * await page.setViewport({
|
5074 | * width: 640,
|
5075 | * height: 480,
|
5076 | * deviceScaleFactor: 1,
|
5077 | * });
|
5078 | * await page.goto('https://example.com');
|
5079 | * ```
|
5080 | *
|
5081 | * @param viewport -
|
5082 | * @remarks
|
5083 | * Argument viewport have following properties:
|
5084 | *
|
5085 | * - `width`: page width in pixels. required
|
5086 | *
|
5087 | * - `height`: page height in pixels. required
|
5088 | *
|
5089 | * - `deviceScaleFactor`: Specify device scale factor (can be thought of as
|
5090 | * DPR). Defaults to `1`.
|
5091 | *
|
5092 | * - `isMobile`: Whether the meta viewport tag is taken into account. Defaults
|
5093 | * to `false`.
|
5094 | *
|
5095 | * - `hasTouch`: Specifies if viewport supports touch events. Defaults to `false`
|
5096 | *
|
5097 | * - `isLandScape`: Specifies if viewport is in landscape mode. Defaults to false.
|
5098 | *
|
5099 | * NOTE: in certain cases, setting viewport will reload the page in order to
|
5100 | * set the isMobile or hasTouch properties.
|
5101 | */
|
5102 | setViewport(viewport: Viewport): Promise<void>;
|
5103 | /**
|
5104 | * @returns
|
5105 | *
|
5106 | * - `width`: page's width in pixels
|
5107 | *
|
5108 | * - `height`: page's height in pixels
|
5109 | *
|
5110 | * - `deviceScalarFactor`: Specify device scale factor (can be though of as
|
5111 | * dpr). Defaults to `1`.
|
5112 | *
|
5113 | * - `isMobile`: Whether the meta viewport tag is taken into account. Defaults
|
5114 | * to `false`.
|
5115 | *
|
5116 | * - `hasTouch`: Specifies if viewport supports touch events. Defaults to
|
5117 | * `false`.
|
5118 | *
|
5119 | * - `isLandScape`: Specifies if viewport is in landscape mode. Defaults to
|
5120 | * `false`.
|
5121 | */
|
5122 | viewport(): Viewport | null;
|
5123 | /**
|
5124 | * @remarks
|
5125 | *
|
5126 | * Evaluates a function in the page's context and returns the result.
|
5127 | *
|
5128 | * If the function passed to `page.evaluteHandle` returns a Promise, the
|
5129 | * function will wait for the promise to resolve and return its value.
|
5130 | *
|
5131 | * @example
|
5132 | *
|
5133 | * ```js
|
5134 | * const result = await frame.evaluate(() => {
|
5135 | * return Promise.resolve(8 * 7);
|
5136 | * });
|
5137 | * console.log(result); // prints "56"
|
5138 | * ```
|
5139 | *
|
5140 | * You can pass a string instead of a function (although functions are
|
5141 | * recommended as they are easier to debug and use with TypeScript):
|
5142 | *
|
5143 | * @example
|
5144 | * ```
|
5145 | * const aHandle = await page.evaluate('1 + 2');
|
5146 | * ```
|
5147 | *
|
5148 | * To get the best TypeScript experience, you should pass in as the
|
5149 | * generic the type of `pageFunction`:
|
5150 | *
|
5151 | * ```
|
5152 | * const aHandle = await page.evaluate<() => number>(() => 2);
|
5153 | * ```
|
5154 | *
|
5155 | * @example
|
5156 | *
|
5157 | * {@link ElementHandle} instances (including {@link JSHandle}s) can be passed
|
5158 | * as arguments to the `pageFunction`:
|
5159 | *
|
5160 | * ```
|
5161 | * const bodyHandle = await page.$('body');
|
5162 | * const html = await page.evaluate(body => body.innerHTML, bodyHandle);
|
5163 | * await bodyHandle.dispose();
|
5164 | * ```
|
5165 | *
|
5166 | * @param pageFunction - a function that is run within the page
|
5167 | * @param args - arguments to be passed to the pageFunction
|
5168 | *
|
5169 | * @returns the return value of `pageFunction`.
|
5170 | */
|
5171 | evaluate<T extends EvaluateFn>(pageFunction: T, ...args: SerializableOrJSHandle[]): Promise<UnwrapPromiseLike<EvaluateFnReturnType<T>>>;
|
5172 | /**
|
5173 | * Adds a function which would be invoked in one of the following scenarios:
|
5174 | *
|
5175 | * - whenever the page is navigated
|
5176 | *
|
5177 | * - whenever the child frame is attached or navigated. In this case, the
|
5178 | * function is invoked in the context of the newly attached frame.
|
5179 | *
|
5180 | * The function is invoked after the document was created but before any of
|
5181 | * its scripts were run. This is useful to amend the JavaScript environment,
|
5182 | * e.g. to seed `Math.random`.
|
5183 | * @param pageFunction - Function to be evaluated in browser context
|
5184 | * @param args - Arguments to pass to `pageFunction`
|
5185 | * @example
|
5186 | * An example of overriding the navigator.languages property before the page loads:
|
5187 | * ```js
|
5188 | * // preload.js
|
5189 | *
|
5190 | * // overwrite the `languages` property to use a custom getter
|
5191 | * Object.defineProperty(navigator, 'languages', {
|
5192 | * get: function () {
|
5193 | * return ['en-US', 'en', 'bn'];
|
5194 | * },
|
5195 | * });
|
5196 | *
|
5197 | * // In your puppeteer script, assuming the preload.js file is
|
5198 | * in same folder of our script
|
5199 | * const preloadFile = fs.readFileSync('./preload.js', 'utf8');
|
5200 | * await page.evaluateOnNewDocument(preloadFile);
|
5201 | * ```
|
5202 | */
|
5203 | evaluateOnNewDocument(pageFunction: Function | string, ...args: unknown[]): Promise<void>;
|
5204 | /**
|
5205 | * Toggles ignoring cache for each request based on the enabled state. By
|
5206 | * default, caching is enabled.
|
5207 | * @param enabled - sets the `enabled` state of cache
|
5208 | */
|
5209 | setCacheEnabled(enabled?: boolean): Promise<void>;
|
5210 | /**
|
5211 | * @remarks
|
5212 | * Options object which might have the following properties:
|
5213 | *
|
5214 | * - `path` : The file path to save the image to. The screenshot type
|
5215 | * will be inferred from file extension. If `path` is a relative path, then
|
5216 | * it is resolved relative to
|
5217 | * {@link https://nodejs.org/api/process.html#process_process_cwd
|
5218 | * | current working directory}.
|
5219 | * If no path is provided, the image won't be saved to the disk.
|
5220 | *
|
5221 | * - `type` : Specify screenshot type, can be either `jpeg` or `png`.
|
5222 | * Defaults to 'png'.
|
5223 | *
|
5224 | * - `quality` : The quality of the image, between 0-100. Not
|
5225 | * applicable to `png` images.
|
5226 | *
|
5227 | * - `fullPage` : When true, takes a screenshot of the full
|
5228 | * scrollable page. Defaults to `false`
|
5229 | *
|
5230 | * - `clip` : An object which specifies clipping region of the page.
|
5231 | * Should have the following fields:<br/>
|
5232 | * - `x` : x-coordinate of top-left corner of clip area.<br/>
|
5233 | * - `y` : y-coordinate of top-left corner of clip area.<br/>
|
5234 | * - `width` : width of clipping area.<br/>
|
5235 | * - `height` : height of clipping area.
|
5236 | *
|
5237 | * - `omitBackground` : Hides default white background and allows
|
5238 | * capturing screenshots with transparency. Defaults to `false`
|
5239 | *
|
5240 | * - `encoding` : The encoding of the image, can be either base64 or
|
5241 | * binary. Defaults to `binary`.
|
5242 | *
|
5243 | *
|
5244 | * NOTE: Screenshots take at least 1/6 second on OS X. See
|
5245 | * {@link https://crbug.com/741689} for discussion.
|
5246 | * @returns Promise which resolves to buffer or a base64 string (depending on
|
5247 | * the value of `encoding`) with captured screenshot.
|
5248 | */
|
5249 | screenshot(options?: ScreenshotOptions): Promise<Buffer | string | void>;
|
5250 | private _screenshotTask;
|
5251 | /**
|
5252 | * Generatees a PDF of the page with the `print` CSS media type.
|
5253 | * @remarks
|
5254 | *
|
5255 | * NOTE: PDF generation is only supported in Chrome headless mode.
|
5256 | *
|
5257 | * To generate a PDF with the `screen` media type, call
|
5258 | * {@link Page.emulateMediaType | `page.emulateMediaType('screen')`} before
|
5259 | * calling `page.pdf()`.
|
5260 | *
|
5261 | * By default, `page.pdf()` generates a pdf with modified colors for printing.
|
5262 | * Use the
|
5263 | * {@link https://developer.mozilla.org/en-US/docs/Web/CSS/-webkit-print-color-adjust | `-webkit-print-color-adjust`}
|
5264 | * property to force rendering of exact colors.
|
5265 | *
|
5266 | *
|
5267 | * @param options - options for generating the PDF.
|
5268 | */
|
5269 | createPDFStream(options?: PDFOptions): Promise<Readable>;
|
5270 | /**
|
5271 | * @param options -
|
5272 | * @returns
|
5273 | */
|
5274 | pdf(options?: PDFOptions): Promise<Buffer>;
|
5275 | /**
|
5276 | * @returns The page's title
|
5277 | * @remarks
|
5278 | * Shortcut for {@link Frame.title | page.mainFrame().title()}.
|
5279 | */
|
5280 | title(): Promise<string>;
|
5281 | close(options?: {
|
5282 | runBeforeUnload?: boolean;
|
5283 | }): Promise<void>;
|
5284 | /**
|
5285 | * Indicates that the page has been closed.
|
5286 | * @returns
|
5287 | */
|
5288 | isClosed(): boolean;
|
5289 | get mouse(): Mouse;
|
5290 | /**
|
5291 | * This method fetches an element with `selector`, scrolls it into view if
|
5292 | * needed, and then uses {@link Page.mouse} to click in the center of the
|
5293 | * element. If there's no element matching `selector`, the method throws an
|
5294 | * error.
|
5295 | * @remarks Bear in mind that if `click()` triggers a navigation event and
|
5296 | * there's a separate `page.waitForNavigation()` promise to be resolved, you
|
5297 | * may end up with a race condition that yields unexpected results. The
|
5298 | * correct pattern for click and wait for navigation is the following:
|
5299 | * ```js
|
5300 | * const [response] = await Promise.all([
|
5301 | * page.waitForNavigation(waitOptions),
|
5302 | * page.click(selector, clickOptions),
|
5303 | * ]);
|
5304 | * ```
|
5305 | * Shortcut for {@link Frame.click | page.mainFrame().click(selector[, options]) }.
|
5306 | * @param selector - A `selector` to search for element to click. If there are
|
5307 | * multiple elements satisfying the `selector`, the first will be clicked
|
5308 | * @param options - `Object`
|
5309 | * @returns Promise which resolves when the element matching `selector` is
|
5310 | * successfully clicked. The Promise will be rejected if there is no element
|
5311 | * matching `selector`.
|
5312 | */
|
5313 | click(selector: string, options?: {
|
5314 | delay?: number;
|
5315 | button?: MouseButton;
|
5316 | clickCount?: number;
|
5317 | }): Promise<void>;
|
5318 | /**
|
5319 | * This method fetches an element with `selector` and focuses it. If there's no
|
5320 | * element matching `selector`, the method throws an error.
|
5321 | * @param selector - A
|
5322 | * {@link https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors | selector }
|
5323 | * of an element to focus. If there are multiple elements satisfying the
|
5324 | * selector, the first will be focused.
|
5325 | * @returns Promise which resolves when the element matching selector is
|
5326 | * successfully focused. The promise will be rejected if there is no element
|
5327 | * matching selector.
|
5328 | * @remarks
|
5329 | * Shortcut for {@link Frame.focus | page.mainFrame().focus(selector)}.
|
5330 | */
|
5331 | focus(selector: string): Promise<void>;
|
5332 | /**
|
5333 | * This method fetches an element with `selector`, scrolls it into view if
|
5334 | * needed, and then uses {@link Page.mouse} to hover over the center of the element.
|
5335 | * If there's no element matching `selector`, the method throws an error.
|
5336 | * @param selector - A
|
5337 | * {@link https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors | selector}
|
5338 | * to search for element to hover. If there are multiple elements satisfying
|
5339 | * the selector, the first will be hovered.
|
5340 | * @returns Promise which resolves when the element matching `selector` is
|
5341 | * successfully hovered. Promise gets rejected if there's no element matching
|
5342 | * `selector`.
|
5343 | * @remarks
|
5344 | * Shortcut for {@link Page.hover | page.mainFrame().hover(selector)}.
|
5345 | */
|
5346 | hover(selector: string): Promise<void>;
|
5347 | /**
|
5348 | * Triggers a `change` and `input` event once all the provided options have been
|
5349 | * selected. If there's no `<select>` element matching `selector`, the method
|
5350 | * throws an error.
|
5351 | *
|
5352 | * @example
|
5353 | * ```js
|
5354 | * page.select('select#colors', 'blue'); // single selection
|
5355 | * page.select('select#colors', 'red', 'green', 'blue'); // multiple selections
|
5356 | * ```
|
5357 | * @param selector - A
|
5358 | * {@link https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors | Selector}
|
5359 | * to query the page for
|
5360 | * @param values - Values of options to select. If the `<select>` has the
|
5361 | * `multiple` attribute, all values are considered, otherwise only the first one
|
5362 | * is taken into account.
|
5363 | * @returns
|
5364 | *
|
5365 | * @remarks
|
5366 | * Shortcut for {@link Frame.select | page.mainFrame().select()}
|
5367 | */
|
5368 | select(selector: string, ...values: string[]): Promise<string[]>;
|
5369 | /**
|
5370 | * This method fetches an element with `selector`, scrolls it into view if
|
5371 | * needed, and then uses {@link Page.touchscreen} to tap in the center of the element.
|
5372 | * If there's no element matching `selector`, the method throws an error.
|
5373 | * @param selector - A
|
5374 | * {@link https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors | Selector}
|
5375 | * to search for element to tap. If there are multiple elements satisfying the
|
5376 | * selector, the first will be tapped.
|
5377 | * @returns
|
5378 | * @remarks
|
5379 | * Shortcut for {@link Frame.tap | page.mainFrame().tap(selector)}.
|
5380 | */
|
5381 | tap(selector: string): Promise<void>;
|
5382 | /**
|
5383 | * Sends a `keydown`, `keypress/input`, and `keyup` event for each character
|
5384 | * in the text.
|
5385 | *
|
5386 | * To press a special key, like `Control` or `ArrowDown`, use {@link Keyboard.press}.
|
5387 | * @example
|
5388 | * ```
|
5389 | * await page.type('#mytextarea', 'Hello');
|
5390 | * // Types instantly
|
5391 | * await page.type('#mytextarea', 'World', { delay: 100 });
|
5392 | * // Types slower, like a user
|
5393 | * ```
|
5394 | * @param selector - A
|
5395 | * {@link https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors | selector}
|
5396 | * of an element to type into. If there are multiple elements satisfying the
|
5397 | * selector, the first will be used.
|
5398 | * @param text - A text to type into a focused element.
|
5399 | * @param options - have property `delay` which is the Time to wait between
|
5400 | * key presses in milliseconds. Defaults to `0`.
|
5401 | * @returns
|
5402 | * @remarks
|
5403 | */
|
5404 | type(selector: string, text: string, options?: {
|
5405 | delay: number;
|
5406 | }): Promise<void>;
|
5407 | /**
|
5408 | * @remarks
|
5409 | *
|
5410 | * This method behaves differently depending on the first parameter. If it's a
|
5411 | * `string`, it will be treated as a `selector` or `xpath` (if the string
|
5412 | * starts with `//`). This method then is a shortcut for
|
5413 | * {@link Page.waitForSelector} or {@link Page.waitForXPath}.
|
5414 | *
|
5415 | * If the first argument is a function this method is a shortcut for
|
5416 | * {@link Page.waitForFunction}.
|
5417 | *
|
5418 | * If the first argument is a `number`, it's treated as a timeout in
|
5419 | * milliseconds and the method returns a promise which resolves after the
|
5420 | * timeout.
|
5421 | *
|
5422 | * @param selectorOrFunctionOrTimeout - a selector, predicate or timeout to
|
5423 | * wait for.
|
5424 | * @param options - optional waiting parameters.
|
5425 | * @param args - arguments to pass to `pageFunction`.
|
5426 | *
|
5427 | * @deprecated Don't use this method directly. Instead use the more explicit
|
5428 | * methods available: {@link Page.waitForSelector},
|
5429 | * {@link Page.waitForXPath}, {@link Page.waitForFunction} or
|
5430 | * {@link Page.waitForTimeout}.
|
5431 | */
|
5432 | waitFor(selectorOrFunctionOrTimeout: string | number | Function, options?: {
|
5433 | visible?: boolean;
|
5434 | hidden?: boolean;
|
5435 | timeout?: number;
|
5436 | polling?: string | number;
|
5437 | }, ...args: SerializableOrJSHandle[]): Promise<JSHandle>;
|
5438 | /**
|
5439 | * Causes your script to wait for the given number of milliseconds.
|
5440 | *
|
5441 | * @remarks
|
5442 | *
|
5443 | * It's generally recommended to not wait for a number of seconds, but instead
|
5444 | * use {@link Page.waitForSelector}, {@link Page.waitForXPath} or
|
5445 | * {@link Page.waitForFunction} to wait for exactly the conditions you want.
|
5446 | *
|
5447 | * @example
|
5448 | *
|
5449 | * Wait for 1 second:
|
5450 | *
|
5451 | * ```
|
5452 | * await page.waitForTimeout(1000);
|
5453 | * ```
|
5454 | *
|
5455 | * @param milliseconds - the number of milliseconds to wait.
|
5456 | */
|
5457 | waitForTimeout(milliseconds: number): Promise<void>;
|
5458 | /**
|
5459 | * Wait for the `selector` to appear in page. If at the moment of calling the
|
5460 | * method the `selector` already exists, the method will return immediately. If
|
5461 | * the `selector` doesn't appear after the `timeout` milliseconds of waiting, the
|
5462 | * function will throw.
|
5463 | *
|
5464 | * This method works across navigations:
|
5465 | * ```js
|
5466 | * const puppeteer = require('puppeteer');
|
5467 | * (async () => {
|
5468 | * const browser = await puppeteer.launch();
|
5469 | * const page = await browser.newPage();
|
5470 | * let currentURL;
|
5471 | * page
|
5472 | * .waitForSelector('img')
|
5473 | * .then(() => console.log('First URL with image: ' + currentURL));
|
5474 | * for (currentURL of [
|
5475 | * 'https://example.com',
|
5476 | * 'https://google.com',
|
5477 | * 'https://bbc.com',
|
5478 | * ]) {
|
5479 | * await page.goto(currentURL);
|
5480 | * }
|
5481 | * await browser.close();
|
5482 | * })();
|
5483 | * ```
|
5484 | * @param selector - A
|
5485 | * {@link https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors | selector}
|
5486 | * of an element to wait for
|
5487 | * @param options - Optional waiting parameters
|
5488 | * @returns Promise which resolves when element specified by selector string
|
5489 | * is added to DOM. Resolves to `null` if waiting for hidden: `true` and
|
5490 | * selector is not found in DOM.
|
5491 | * @remarks
|
5492 | * The optional Parameter in Arguments `options` are :
|
5493 | *
|
5494 | * - `Visible`: A boolean wait for element to be present in DOM and to be
|
5495 | * visible, i.e. to not have `display: none` or `visibility: hidden` CSS
|
5496 | * properties. Defaults to `false`.
|
5497 | *
|
5498 | * - `hidden`: ait for element to not be found in the DOM or to be hidden,
|
5499 | * i.e. have `display: none` or `visibility: hidden` CSS properties. Defaults to
|
5500 | * `false`.
|
5501 | *
|
5502 | * - `timeout`: maximum time to wait for in milliseconds. Defaults to `30000`
|
5503 | * (30 seconds). Pass `0` to disable timeout. The default value can be changed
|
5504 | * by using the {@link Page.setDefaultTimeout} method.
|
5505 | */
|
5506 | waitForSelector(selector: string, options?: {
|
5507 | visible?: boolean;
|
5508 | hidden?: boolean;
|
5509 | timeout?: number;
|
5510 | }): Promise<ElementHandle | null>;
|
5511 | /**
|
5512 | * Wait for the `xpath` to appear in page. If at the moment of calling the
|
5513 | * method the `xpath` already exists, the method will return immediately. If
|
5514 | * the `xpath` doesn't appear after the `timeout` milliseconds of waiting, the
|
5515 | * function will throw.
|
5516 | *
|
5517 | * This method works across navigation
|
5518 | * ```js
|
5519 | * const puppeteer = require('puppeteer');
|
5520 | * (async () => {
|
5521 | * const browser = await puppeteer.launch();
|
5522 | * const page = await browser.newPage();
|
5523 | * let currentURL;
|
5524 | * page
|
5525 | * .waitForXPath('//img')
|
5526 | * .then(() => console.log('First URL with image: ' + currentURL));
|
5527 | * for (currentURL of [
|
5528 | * 'https://example.com',
|
5529 | * 'https://google.com',
|
5530 | * 'https://bbc.com',
|
5531 | * ]) {
|
5532 | * await page.goto(currentURL);
|
5533 | * }
|
5534 | * await browser.close();
|
5535 | * })();
|
5536 | * ```
|
5537 | * @param xpath - A
|
5538 | * {@link https://developer.mozilla.org/en-US/docs/Web/XPath | xpath} of an
|
5539 | * element to wait for
|
5540 | * @param options - Optional waiting parameters
|
5541 | * @returns Promise which resolves when element specified by xpath string is
|
5542 | * added to DOM. Resolves to `null` if waiting for `hidden: true` and xpath is
|
5543 | * not found in DOM.
|
5544 | * @remarks
|
5545 | * The optional Argument `options` have properties:
|
5546 | *
|
5547 | * - `visible`: A boolean to wait for element to be present in DOM and to be
|
5548 | * visible, i.e. to not have `display: none` or `visibility: hidden` CSS
|
5549 | * properties. Defaults to `false`.
|
5550 | *
|
5551 | * - `hidden`: A boolean wait for element to not be found in the DOM or to be
|
5552 | * hidden, i.e. have `display: none` or `visibility: hidden` CSS properties.
|
5553 | * Defaults to `false`.
|
5554 | *
|
5555 | * - `timeout`: A number which is maximum time to wait for in milliseconds.
|
5556 | * Defaults to `30000` (30 seconds). Pass `0` to disable timeout. The default
|
5557 | * value can be changed by using the {@link Page.setDefaultTimeout} method.
|
5558 | */
|
5559 | waitForXPath(xpath: string, options?: {
|
5560 | visible?: boolean;
|
5561 | hidden?: boolean;
|
5562 | timeout?: number;
|
5563 | }): Promise<ElementHandle | null>;
|
5564 | /**
|
5565 | * The `waitForFunction` can be used to observe viewport size change:
|
5566 | *
|
5567 | * ```
|
5568 | * const puppeteer = require('puppeteer');
|
5569 | * (async () => {
|
5570 | * const browser = await puppeteer.launch();
|
5571 | * const page = await browser.newPage();
|
5572 | * const watchDog = page.waitForFunction('window.innerWidth < 100');
|
5573 | * await page.setViewport({ width: 50, height: 50 });
|
5574 | * await watchDog;
|
5575 | * await browser.close();
|
5576 | * })();
|
5577 | * ```
|
5578 | * To pass arguments from node.js to the predicate of `page.waitForFunction` function:
|
5579 | * ```
|
5580 | * const selector = '.foo';
|
5581 | * await page.waitForFunction(
|
5582 | * (selector) => !!document.querySelector(selector),
|
5583 | * {},
|
5584 | * selector
|
5585 | * );
|
5586 | * ```
|
5587 | * The predicate of `page.waitForFunction` can be asynchronous too:
|
5588 | * ```
|
5589 | * const username = 'github-username';
|
5590 | * await page.waitForFunction(
|
5591 | * async (username) => {
|
5592 | * const githubResponse = await fetch(
|
5593 | * `https://api.github.com/users/${username}`
|
5594 | * );
|
5595 | * const githubUser = await githubResponse.json();
|
5596 | * // show the avatar
|
5597 | * const img = document.createElement('img');
|
5598 | * img.src = githubUser.avatar_url;
|
5599 | * // wait 3 seconds
|
5600 | * await new Promise((resolve, reject) => setTimeout(resolve, 3000));
|
5601 | * img.remove();
|
5602 | * },
|
5603 | * {},
|
5604 | * username
|
5605 | * );
|
5606 | * ```
|
5607 | * @param pageFunction - Function to be evaluated in browser context
|
5608 | * @param options - Optional waiting parameters
|
5609 | * @param args - Arguments to pass to `pageFunction`
|
5610 | * @returns Promise which resolves when the `pageFunction` returns a truthy
|
5611 | * value. It resolves to a JSHandle of the truthy value.
|
5612 | *
|
5613 | * The optional waiting parameter can be:
|
5614 | *
|
5615 | * - `Polling`: An interval at which the `pageFunction` is executed, defaults to
|
5616 | * `raf`. If `polling` is a number, then it is treated as an interval in
|
5617 | * milliseconds at which the function would be executed. If polling is a
|
5618 | * string, then it can be one of the following values:<br/>
|
5619 | * - `raf`: to constantly execute `pageFunction` in `requestAnimationFrame`
|
5620 | * callback. This is the tightest polling mode which is suitable to
|
5621 | * observe styling changes.<br/>
|
5622 | * - `mutation`: to execute pageFunction on every DOM mutation.
|
5623 | *
|
5624 | * - `timeout`: maximum time to wait for in milliseconds. Defaults to `30000`
|
5625 | * (30 seconds). Pass `0` to disable timeout. The default value can be changed
|
5626 | * by using the
|
5627 | * {@link Page.setDefaultTimeout | page.setDefaultTimeout(timeout)} method.
|
5628 | *
|
5629 | */
|
5630 | waitForFunction(pageFunction: Function | string, options?: {
|
5631 | timeout?: number;
|
5632 | polling?: string | number;
|
5633 | }, ...args: SerializableOrJSHandle[]): Promise<JSHandle>;
|
5634 | }
|
5635 |
|
5636 | /**
|
5637 | * @internal
|
5638 | */
|
5639 | export declare interface PageBinding {
|
5640 | name: string;
|
5641 | pptrFunction: Function;
|
5642 | }
|
5643 |
|
5644 | /**
|
5645 | * All the events that a page instance may emit.
|
5646 | *
|
5647 | * @public
|
5648 | */
|
5649 | export declare const enum PageEmittedEvents {
|
5650 | /** Emitted when the page closes.
|
5651 | * @eventProperty
|
5652 | */
|
5653 | Close = "close",
|
5654 | /**
|
5655 | * Emitted when JavaScript within the page calls one of console API methods,
|
5656 | * e.g. `console.log` or `console.dir`. Also emitted if the page throws an
|
5657 | * error or a warning.
|
5658 | *
|
5659 | * @remarks
|
5660 | *
|
5661 | * A `console` event provides a {@link ConsoleMessage} representing the
|
5662 | * console message that was logged.
|
5663 | *
|
5664 | * @example
|
5665 | * An example of handling `console` event:
|
5666 | * ```js
|
5667 | * page.on('console', msg => {
|
5668 | * for (let i = 0; i < msg.args().length; ++i)
|
5669 | * console.log(`${i}: ${msg.args()[i]}`);
|
5670 | * });
|
5671 | * page.evaluate(() => console.log('hello', 5, {foo: 'bar'}));
|
5672 | * ```
|
5673 | */
|
5674 | Console = "console",
|
5675 | /**
|
5676 | * Emitted when a JavaScript dialog appears, such as `alert`, `prompt`,
|
5677 | * `confirm` or `beforeunload`. Puppeteer can respond to the dialog via
|
5678 | * {@link Dialog.accept} or {@link Dialog.dismiss}.
|
5679 | */
|
5680 | Dialog = "dialog",
|
5681 | /**
|
5682 | * Emitted when the JavaScript
|
5683 | * {@link https://developer.mozilla.org/en-US/docs/Web/Events/DOMContentLoaded | DOMContentLoaded } event is dispatched.
|
5684 | */
|
5685 | DOMContentLoaded = "domcontentloaded",
|
5686 | /**
|
5687 | * Emitted when the page crashes. Will contain an `Error`.
|
5688 | */
|
5689 | Error = "error",
|
5690 | /** Emitted when a frame is attached. Will contain a {@link Frame}. */
|
5691 | FrameAttached = "frameattached",
|
5692 | /** Emitted when a frame is detached. Will contain a {@link Frame}. */
|
5693 | FrameDetached = "framedetached",
|
5694 | /** Emitted when a frame is navigated to a new URL. Will contain a {@link Frame}. */
|
5695 | FrameNavigated = "framenavigated",
|
5696 | /**
|
5697 | * Emitted when the JavaScript
|
5698 | * {@link https://developer.mozilla.org/en-US/docs/Web/Events/load | load}
|
5699 | * event is dispatched.
|
5700 | */
|
5701 | Load = "load",
|
5702 | /**
|
5703 | * Emitted when the JavaScript code makes a call to `console.timeStamp`. For
|
5704 | * the list of metrics see {@link Page.metrics | page.metrics}.
|
5705 | *
|
5706 | * @remarks
|
5707 | * Contains an object with two properties:
|
5708 | * - `title`: the title passed to `console.timeStamp`
|
5709 | * - `metrics`: objec containing metrics as key/value pairs. The values will
|
5710 | * be `number`s.
|
5711 | */
|
5712 | Metrics = "metrics",
|
5713 | /**
|
5714 | * Emitted when an uncaught exception happens within the page.
|
5715 | * Contains an `Error`.
|
5716 | */
|
5717 | PageError = "pageerror",
|
5718 | /**
|
5719 | * Emitted when the page opens a new tab or window.
|
5720 | *
|
5721 | * Contains a {@link Page} corresponding to the popup window.
|
5722 | *
|
5723 | * @example
|
5724 | *
|
5725 | * ```js
|
5726 | * const [popup] = await Promise.all([
|
5727 | * new Promise(resolve => page.once('popup', resolve)),
|
5728 | * page.click('a[target=_blank]'),
|
5729 | * ]);
|
5730 | * ```
|
5731 | *
|
5732 | * ```js
|
5733 | * const [popup] = await Promise.all([
|
5734 | * new Promise(resolve => page.once('popup', resolve)),
|
5735 | * page.evaluate(() => window.open('https://example.com')),
|
5736 | * ]);
|
5737 | * ```
|
5738 | */
|
5739 | Popup = "popup",
|
5740 | /**
|
5741 | * Emitted when a page issues a request and contains a {@link HTTPRequest}.
|
5742 | *
|
5743 | * @remarks
|
5744 | * The object is readonly. See {@link Page.setRequestInterception} for intercepting
|
5745 | * and mutating requests.
|
5746 | */
|
5747 | Request = "request",
|
5748 | /**
|
5749 | * Emitted when a request ended up loading from cache. Contains a {@link HTTPRequest}.
|
5750 | *
|
5751 | * @remarks
|
5752 | * For certain requests, might contain undefined.
|
5753 | * {@link https://crbug.com/750469}
|
5754 | */
|
5755 | RequestServedFromCache = "requestservedfromcache",
|
5756 | /**
|
5757 | * Emitted when a request fails, for example by timing out.
|
5758 | *
|
5759 | * Contains a {@link HTTPRequest}.
|
5760 | *
|
5761 | * @remarks
|
5762 | *
|
5763 | * NOTE: HTTP Error responses, such as 404 or 503, are still successful
|
5764 | * responses from HTTP standpoint, so request will complete with
|
5765 | * `requestfinished` event and not with `requestfailed`.
|
5766 | */
|
5767 | RequestFailed = "requestfailed",
|
5768 | /**
|
5769 | * Emitted when a request finishes successfully. Contains a {@link HTTPRequest}.
|
5770 | */
|
5771 | RequestFinished = "requestfinished",
|
5772 | /**
|
5773 | * Emitted when a response is received. Contains a {@link HTTPResponse}.
|
5774 | */
|
5775 | Response = "response",
|
5776 | /**
|
5777 | * Emitted when a dedicated
|
5778 | * {@link https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API | WebWorker}
|
5779 | * is spawned by the page.
|
5780 | */
|
5781 | WorkerCreated = "workercreated",
|
5782 | /**
|
5783 | * Emitted when a dedicated
|
5784 | * {@link https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API | WebWorker}
|
5785 | * is destroyed by the page.
|
5786 | */
|
5787 | WorkerDestroyed = "workerdestroyed"
|
5788 | }
|
5789 |
|
5790 | /**
|
5791 | * Denotes the objects received by callback functions for page events.
|
5792 | *
|
5793 | * See {@link PageEmittedEvents} for more detail on the events and when they are
|
5794 | * emitted.
|
5795 | * @public
|
5796 | */
|
5797 | export declare interface PageEventObject {
|
5798 | close: never;
|
5799 | console: ConsoleMessage;
|
5800 | dialog: Dialog;
|
5801 | domcontentloaded: never;
|
5802 | error: Error;
|
5803 | frameattached: Frame;
|
5804 | framedetached: Frame;
|
5805 | framenavigated: Frame;
|
5806 | load: never;
|
5807 | metrics: {
|
5808 | title: string;
|
5809 | metrics: Metrics;
|
5810 | };
|
5811 | pageerror: Error;
|
5812 | popup: Page;
|
5813 | request: HTTPRequest;
|
5814 | response: HTTPResponse;
|
5815 | requestfailed: HTTPRequest;
|
5816 | requestfinished: HTTPRequest;
|
5817 | requestservedfromcache: HTTPRequest;
|
5818 | workercreated: WebWorker;
|
5819 | workerdestroyed: WebWorker;
|
5820 | }
|
5821 |
|
5822 | /**
|
5823 | * All the valid paper format types when printing a PDF.
|
5824 | *
|
5825 | * @remarks
|
5826 | *
|
5827 | * The sizes of each format are as follows:
|
5828 | * - `Letter`: 8.5in x 11in
|
5829 | *
|
5830 | * - `Legal`: 8.5in x 14in
|
5831 | *
|
5832 | * - `Tabloid`: 11in x 17in
|
5833 | *
|
5834 | * - `Ledger`: 17in x 11in
|
5835 | *
|
5836 | * - `A0`: 33.1in x 46.8in
|
5837 | *
|
5838 | * - `A1`: 23.4in x 33.1in
|
5839 | *
|
5840 | * - `A2`: 16.54in x 23.4in
|
5841 | *
|
5842 | * - `A3`: 11.7in x 16.54in
|
5843 | *
|
5844 | * - `A4`: 8.27in x 11.7in
|
5845 | *
|
5846 | * - `A5`: 5.83in x 8.27in
|
5847 | *
|
5848 | * - `A6`: 4.13in x 5.83in
|
5849 | *
|
5850 | * @public
|
5851 | */
|
5852 | export declare type PaperFormat = 'letter' | 'legal' | 'tabloid' | 'ledger' | 'a0' | 'a1' | 'a2' | 'a3' | 'a4' | 'a5' | 'a6';
|
5853 |
|
5854 | /**
|
5855 | * @internal
|
5856 | */
|
5857 | export declare interface PaperFormatDimensions {
|
5858 | width: number;
|
5859 | height: number;
|
5860 | }
|
5861 |
|
5862 | /**
|
5863 | * @internal
|
5864 | */
|
5865 | export declare const paperFormats: Record<PaperFormat, PaperFormatDimensions>;
|
5866 |
|
5867 | /**
|
5868 | * Copyright 2020 Google Inc. All rights reserved.
|
5869 | *
|
5870 | * Licensed under the Apache License, Version 2.0 (the "License");
|
5871 | * you may not use this file except in compliance with the License.
|
5872 | * You may obtain a copy of the License at
|
5873 | *
|
5874 | * http://www.apache.org/licenses/LICENSE-2.0
|
5875 | *
|
5876 | * Unless required by applicable law or agreed to in writing, software
|
5877 | * distributed under the License is distributed on an "AS IS" BASIS,
|
5878 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
5879 | * See the License for the specific language governing permissions and
|
5880 | * limitations under the License.
|
5881 | */
|
5882 | /**
|
5883 | * @public
|
5884 | */
|
5885 | export declare interface PDFMargin {
|
5886 | top?: string | number;
|
5887 | bottom?: string | number;
|
5888 | left?: string | number;
|
5889 | right?: string | number;
|
5890 | }
|
5891 |
|
5892 | /**
|
5893 | * Valid options to configure PDF generation via {@link Page.pdf}.
|
5894 | * @public
|
5895 | */
|
5896 | export declare interface PDFOptions {
|
5897 | /**
|
5898 | * Scales the rendering of the web page. Amount must be between `0.1` and `2`.
|
5899 | * @defaultValue 1
|
5900 | */
|
5901 | scale?: number;
|
5902 | /**
|
5903 | * Whether to show the header and footer.
|
5904 | * @defaultValue false
|
5905 | */
|
5906 | displayHeaderFooter?: boolean;
|
5907 | /**
|
5908 | * HTML template for the print header. Should be valid HTML with the following
|
5909 | * classes used to inject values into them:
|
5910 | * - `date` formatted print date
|
5911 | *
|
5912 | * - `title` document title
|
5913 | *
|
5914 | * - `url` document location
|
5915 | *
|
5916 | * - `pageNumber` current page number
|
5917 | *
|
5918 | * - `totalPages` total pages in the document
|
5919 | */
|
5920 | headerTemplate?: string;
|
5921 | /**
|
5922 | * HTML template for the print footer. Has the same constraints and support
|
5923 | * for special classes as {@link PDFOptions.headerTemplate}.
|
5924 | */
|
5925 | footerTemplate?: string;
|
5926 | /**
|
5927 | * Set to `true` to print background graphics.
|
5928 | * @defaultValue false
|
5929 | */
|
5930 | printBackground?: boolean;
|
5931 | /**
|
5932 | * Whether to print in landscape orientation.
|
5933 | * @defaultValue = false
|
5934 | */
|
5935 | landscape?: boolean;
|
5936 | /**
|
5937 | * Paper ranges to print, e.g. `1-5, 8, 11-13`.
|
5938 | * @defaultValue The empty string, which means all pages are printed.
|
5939 | */
|
5940 | pageRanges?: string;
|
5941 | /**
|
5942 | * @remarks
|
5943 | * If set, this takes priority over the `width` and `height` options.
|
5944 | * @defaultValue `letter`.
|
5945 | */
|
5946 | format?: PaperFormat;
|
5947 | /**
|
5948 | * Sets the width of paper. You can pass in a number or a string with a unit.
|
5949 | */
|
5950 | width?: string | number;
|
5951 | /**
|
5952 | * Sets the height of paper. You can pass in a number or a string with a unit.
|
5953 | */
|
5954 | height?: string | number;
|
5955 | /**
|
5956 | * Give any CSS `@page` size declared in the page priority over what is
|
5957 | * declared in the `width` or `height` or `format` option.
|
5958 | * @defaultValue `false`, which will scale the content to fit the paper size.
|
5959 | */
|
5960 | preferCSSPageSize?: boolean;
|
5961 | /**
|
5962 | * Set the PDF margins.
|
5963 | * @defaultValue no margins are set.
|
5964 | */
|
5965 | margin?: PDFMargin;
|
5966 | /**
|
5967 | * The path to save the file to.
|
5968 | *
|
5969 | * @remarks
|
5970 | *
|
5971 | * If the path is relative, it's resolved relative to the current working directory.
|
5972 | *
|
5973 | * @defaultValue the empty string, which means the PDF will not be written to disk.
|
5974 | */
|
5975 | path?: string;
|
5976 | /**
|
5977 | * Hides default white background and allows generating pdfs with transparency.
|
5978 | * @defaultValue false
|
5979 | */
|
5980 | omitBackground?: boolean;
|
5981 | /**
|
5982 | * Timeout in milliseconds
|
5983 | * @defaultValue 30000
|
5984 | */
|
5985 | timeout?: number;
|
5986 | }
|
5987 |
|
5988 | /**
|
5989 | * @public
|
5990 | */
|
5991 | export declare type Permission = 'geolocation' | 'midi' | 'notifications' | 'camera' | 'microphone' | 'background-sync' | 'ambient-light-sensor' | 'accelerometer' | 'gyroscope' | 'magnetometer' | 'accessibility-events' | 'clipboard-read' | 'clipboard-write' | 'payment-handler' | 'persistent-storage' | 'idle-detection' | 'midi-sysex';
|
5992 |
|
5993 | /**
|
5994 | * Supported platforms.
|
5995 | * @public
|
5996 | */
|
5997 | export declare type Platform = 'linux' | 'mac' | 'win32' | 'win64';
|
5998 |
|
5999 | /**
|
6000 | * @public
|
6001 | */
|
6002 | export declare interface Point {
|
6003 | x: number;
|
6004 | y: number;
|
6005 | }
|
6006 |
|
6007 | /**
|
6008 | * @public
|
6009 | */
|
6010 | export declare type PredefinedNetworkConditions = {
|
6011 | [name: string]: NetworkConditions;
|
6012 | };
|
6013 |
|
6014 | /**
|
6015 | * @public
|
6016 | */
|
6017 | export declare interface PressOptions {
|
6018 | /**
|
6019 | * Time to wait between `keydown` and `keyup` in milliseconds. Defaults to 0.
|
6020 | */
|
6021 | delay?: number;
|
6022 | /**
|
6023 | * If specified, generates an input event with this text.
|
6024 | */
|
6025 | text?: string;
|
6026 | }
|
6027 |
|
6028 | /**
|
6029 | * Copyright 2020 Google Inc. All rights reserved.
|
6030 | *
|
6031 | * Licensed under the Apache License, Version 2.0 (the "License");
|
6032 | * you may not use this file except in compliance with the License.
|
6033 | * You may obtain a copy of the License at
|
6034 | *
|
6035 | * http://www.apache.org/licenses/LICENSE-2.0
|
6036 | *
|
6037 | * Unless required by applicable law or agreed to in writing, software
|
6038 | * distributed under the License is distributed on an "AS IS" BASIS,
|
6039 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
6040 | * See the License for the specific language governing permissions and
|
6041 | * limitations under the License.
|
6042 | */
|
6043 | /**
|
6044 | * Supported products.
|
6045 | * @public
|
6046 | */
|
6047 | export declare type Product = 'chrome' | 'firefox';
|
6048 |
|
6049 | /**
|
6050 | * Describes a launcher - a class that is able to create and launch a browser instance.
|
6051 | * @public
|
6052 | */
|
6053 | export declare interface ProductLauncher {
|
6054 | launch(object: PuppeteerNodeLaunchOptions): any;
|
6055 | executablePath: (string?: any) => string;
|
6056 | defaultArgs(object: BrowserLaunchArgumentOptions): any;
|
6057 | product: Product;
|
6058 | }
|
6059 |
|
6060 | /**
|
6061 | * @public
|
6062 | */
|
6063 | export declare type ProtocolLifeCycleEvent = 'load' | 'DOMContentLoaded' | 'networkIdle' | 'networkAlmostIdle';
|
6064 | export { ProtocolMapping }
|
6065 |
|
6066 | /**
|
6067 | * The main Puppeteer class.
|
6068 | *
|
6069 | * IMPORTANT: if you are using Puppeteer in a Node environment, you will get an
|
6070 | * instance of {@link PuppeteerNode} when you import or require `puppeteer`.
|
6071 | * That class extends `Puppeteer`, so has all the methods documented below as
|
6072 | * well as all that are defined on {@link PuppeteerNode}.
|
6073 | * @public
|
6074 | */
|
6075 | export declare class Puppeteer {
|
6076 | protected _isPuppeteerCore: boolean;
|
6077 | protected _changedProduct: boolean;
|
6078 | /**
|
6079 | * @internal
|
6080 | */
|
6081 | constructor(settings: CommonPuppeteerSettings);
|
6082 | /**
|
6083 | * This method attaches Puppeteer to an existing browser instance.
|
6084 | *
|
6085 | * @remarks
|
6086 | *
|
6087 | * @param options - Set of configurable options to set on the browser.
|
6088 | * @returns Promise which resolves to browser instance.
|
6089 | */
|
6090 | connect(options: ConnectOptions): Promise<Browser>;
|
6091 | /**
|
6092 | * @remarks
|
6093 | * A list of devices to be used with `page.emulate(options)`. Actual list of devices can be found in {@link https://github.com/puppeteer/puppeteer/blob/main/src/common/DeviceDescriptors.ts | src/common/DeviceDescriptors.ts}.
|
6094 | *
|
6095 | * @example
|
6096 | *
|
6097 | * ```js
|
6098 | * const puppeteer = require('puppeteer');
|
6099 | * const iPhone = puppeteer.devices['iPhone 6'];
|
6100 | *
|
6101 | * (async () => {
|
6102 | * const browser = await puppeteer.launch();
|
6103 | * const page = await browser.newPage();
|
6104 | * await page.emulate(iPhone);
|
6105 | * await page.goto('https://www.google.com');
|
6106 | * // other actions...
|
6107 | * await browser.close();
|
6108 | * })();
|
6109 | * ```
|
6110 | *
|
6111 | */
|
6112 | get devices(): DevicesMap;
|
6113 | /**
|
6114 | * @remarks
|
6115 | *
|
6116 | * Puppeteer methods might throw errors if they are unable to fulfill a request.
|
6117 | * For example, `page.waitForSelector(selector[, options])` might fail if
|
6118 | * the selector doesn't match any nodes during the given timeframe.
|
6119 | *
|
6120 | * For certain types of errors Puppeteer uses specific error classes.
|
6121 | * These classes are available via `puppeteer.errors`.
|
6122 | *
|
6123 | * @example
|
6124 | * An example of handling a timeout error:
|
6125 | * ```js
|
6126 | * try {
|
6127 | * await page.waitForSelector('.foo');
|
6128 | * } catch (e) {
|
6129 | * if (e instanceof puppeteer.errors.TimeoutError) {
|
6130 | * // Do something if this is a timeout.
|
6131 | * }
|
6132 | * }
|
6133 | * ```
|
6134 | */
|
6135 | get errors(): PuppeteerErrors;
|
6136 | /**
|
6137 | * @remarks
|
6138 | * Returns a list of network conditions to be used with `page.emulateNetworkConditions(networkConditions)`. Actual list of predefined conditions can be found in {@link https://github.com/puppeteer/puppeteer/blob/main/src/common/NetworkConditions.ts | src/common/NetworkConditions.ts}.
|
6139 | *
|
6140 | * @example
|
6141 | *
|
6142 | * ```js
|
6143 | * const puppeteer = require('puppeteer');
|
6144 | * const slow3G = puppeteer.networkConditions['Slow 3G'];
|
6145 | *
|
6146 | * (async () => {
|
6147 | * const browser = await puppeteer.launch();
|
6148 | * const page = await browser.newPage();
|
6149 | * await page.emulateNetworkConditions(slow3G);
|
6150 | * await page.goto('https://www.google.com');
|
6151 | * // other actions...
|
6152 | * await browser.close();
|
6153 | * })();
|
6154 | * ```
|
6155 | *
|
6156 | */
|
6157 | get networkConditions(): PredefinedNetworkConditions;
|
6158 | /**
|
6159 | * Registers a {@link CustomQueryHandler | custom query handler}. After
|
6160 | * registration, the handler can be used everywhere where a selector is
|
6161 | * expected by prepending the selection string with `<name>/`. The name is
|
6162 | * only allowed to consist of lower- and upper case latin letters.
|
6163 | * @example
|
6164 | * ```
|
6165 | * puppeteer.registerCustomQueryHandler('text', { … });
|
6166 | * const aHandle = await page.$('text/…');
|
6167 | * ```
|
6168 | * @param name - The name that the custom query handler will be registered under.
|
6169 | * @param queryHandler - The {@link CustomQueryHandler | custom query handler} to
|
6170 | * register.
|
6171 | */
|
6172 | registerCustomQueryHandler(name: string, queryHandler: CustomQueryHandler): void;
|
6173 | /**
|
6174 | * @param name - The name of the query handler to unregistered.
|
6175 | */
|
6176 | unregisterCustomQueryHandler(name: string): void;
|
6177 | /**
|
6178 | * @returns a list with the names of all registered custom query handlers.
|
6179 | */
|
6180 | customQueryHandlerNames(): string[];
|
6181 | /**
|
6182 | * Clears all registered handlers.
|
6183 | */
|
6184 | clearCustomQueryHandlers(): void;
|
6185 | }
|
6186 |
|
6187 | /**
|
6188 | * @public
|
6189 | */
|
6190 | export declare type PuppeteerErrors = Record<string, typeof CustomError>;
|
6191 |
|
6192 | /**
|
6193 | * @public
|
6194 | */
|
6195 | export declare const puppeteerErrors: PuppeteerErrors;
|
6196 |
|
6197 | /**
|
6198 | * @public
|
6199 | */
|
6200 | export declare interface PuppeteerEventListener {
|
6201 | emitter: CommonEventEmitter;
|
6202 | eventName: string | symbol;
|
6203 | handler: (...args: any[]) => void;
|
6204 | }
|
6205 |
|
6206 | /**
|
6207 | * @public
|
6208 | */
|
6209 | export declare type PuppeteerLifeCycleEvent = 'load' | 'domcontentloaded' | 'networkidle0' | 'networkidle2';
|
6210 |
|
6211 | /**
|
6212 | * Extends the main {@link Puppeteer} class with Node specific behaviour for fetching and
|
6213 | * downloading browsers.
|
6214 | *
|
6215 | * If you're using Puppeteer in a Node environment, this is the class you'll get
|
6216 | * when you run `require('puppeteer')` (or the equivalent ES `import`).
|
6217 | *
|
6218 | * @remarks
|
6219 | *
|
6220 | * The most common method to use is {@link PuppeteerNode.launch | launch}, which
|
6221 | * is used to launch and connect to a new browser instance.
|
6222 | *
|
6223 | * See {@link Puppeteer | the main Puppeteer class} for methods common to all
|
6224 | * environments, such as {@link Puppeteer.connect}.
|
6225 | *
|
6226 | * @example
|
6227 | * The following is a typical example of using Puppeteer to drive automation:
|
6228 | * ```js
|
6229 | * const puppeteer = require('puppeteer');
|
6230 | *
|
6231 | * (async () => {
|
6232 | * const browser = await puppeteer.launch();
|
6233 | * const page = await browser.newPage();
|
6234 | * await page.goto('https://www.google.com');
|
6235 | * // other actions...
|
6236 | * await browser.close();
|
6237 | * })();
|
6238 | * ```
|
6239 | *
|
6240 | * Once you have created a `page` you have access to a large API to interact
|
6241 | * with the page, navigate, or find certain elements in that page.
|
6242 | * The {@link Page | `page` documentation} lists all the available methods.
|
6243 | *
|
6244 | * @public
|
6245 | */
|
6246 | export declare class PuppeteerNode extends Puppeteer {
|
6247 | private _lazyLauncher;
|
6248 | private _projectRoot;
|
6249 | private __productName?;
|
6250 | /**
|
6251 | * @internal
|
6252 | */
|
6253 | _preferredRevision: string;
|
6254 | /**
|
6255 | * @internal
|
6256 | */
|
6257 | constructor(settings: {
|
6258 | projectRoot: string;
|
6259 | preferredRevision: string;
|
6260 | productName?: Product;
|
6261 | } & CommonPuppeteerSettings);
|
6262 | /**
|
6263 | * This method attaches Puppeteer to an existing browser instance.
|
6264 | *
|
6265 | * @remarks
|
6266 | *
|
6267 | * @param options - Set of configurable options to set on the browser.
|
6268 | * @returns Promise which resolves to browser instance.
|
6269 | */
|
6270 | connect(options: ConnectOptions): Promise<Browser>;
|
6271 | /**
|
6272 | * @internal
|
6273 | */
|
6274 | get _productName(): Product;
|
6275 | set _productName(name: Product);
|
6276 | /**
|
6277 | * Launches puppeteer and launches a browser instance with given arguments
|
6278 | * and options when specified.
|
6279 | *
|
6280 | * @remarks
|
6281 | *
|
6282 | * @example
|
6283 | * You can use `ignoreDefaultArgs` to filter out `--mute-audio` from default arguments:
|
6284 | * ```js
|
6285 | * const browser = await puppeteer.launch({
|
6286 | * ignoreDefaultArgs: ['--mute-audio']
|
6287 | * });
|
6288 | * ```
|
6289 | *
|
6290 | * **NOTE** Puppeteer can also be used to control the Chrome browser,
|
6291 | * but it works best with the version of Chromium it is bundled with.
|
6292 | * There is no guarantee it will work with any other version.
|
6293 | * Use `executablePath` option with extreme caution.
|
6294 | * If Google Chrome (rather than Chromium) is preferred, a {@link https://www.google.com/chrome/browser/canary.html | Chrome Canary} or {@link https://www.chromium.org/getting-involved/dev-channel | Dev Channel} build is suggested.
|
6295 | * In `puppeteer.launch([options])`, any mention of Chromium also applies to Chrome.
|
6296 | * See {@link https://www.howtogeek.com/202825/what%E2%80%99s-the-difference-between-chromium-and-chrome/ | this article} for a description of the differences between Chromium and Chrome. {@link https://chromium.googlesource.com/chromium/src/+/lkgr/docs/chromium_browser_vs_google_chrome.md | This article} describes some differences for Linux users.
|
6297 | *
|
6298 | * @param options - Set of configurable options to set on the browser.
|
6299 | * @returns Promise which resolves to browser instance.
|
6300 | */
|
6301 | launch(options?: LaunchOptions & BrowserLaunchArgumentOptions & BrowserConnectOptions & {
|
6302 | product?: Product;
|
6303 | extraPrefsFirefox?: Record<string, unknown>;
|
6304 | }): Promise<Browser>;
|
6305 | /**
|
6306 | * @remarks
|
6307 | *
|
6308 | * **NOTE** `puppeteer.executablePath()` is affected by the `PUPPETEER_EXECUTABLE_PATH`
|
6309 | * and `PUPPETEER_CHROMIUM_REVISION` environment variables.
|
6310 | *
|
6311 | * @returns A path where Puppeteer expects to find the bundled browser.
|
6312 | * The browser binary might not be there if the download was skipped with
|
6313 | * the `PUPPETEER_SKIP_DOWNLOAD` environment variable.
|
6314 | */
|
6315 | executablePath(channel?: string): string;
|
6316 | /**
|
6317 | * @internal
|
6318 | */
|
6319 | get _launcher(): ProductLauncher;
|
6320 | /**
|
6321 | * The name of the browser that is under automation (`"chrome"` or `"firefox"`)
|
6322 | *
|
6323 | * @remarks
|
6324 | * The product is set by the `PUPPETEER_PRODUCT` environment variable or the `product`
|
6325 | * option in `puppeteer.launch([options])` and defaults to `chrome`.
|
6326 | * Firefox support is experimental.
|
6327 | */
|
6328 | get product(): string;
|
6329 | /**
|
6330 | *
|
6331 | * @param options - Set of configurable options to set on the browser.
|
6332 | * @returns The default flags that Chromium will be launched with.
|
6333 | */
|
6334 | defaultArgs(options?: BrowserLaunchArgumentOptions): string[];
|
6335 | /**
|
6336 | * @param options - Set of configurable options to specify the settings
|
6337 | * of the BrowserFetcher.
|
6338 | * @returns A new BrowserFetcher instance.
|
6339 | */
|
6340 | createBrowserFetcher(options: BrowserFetcherOptions): BrowserFetcher;
|
6341 | }
|
6342 |
|
6343 | /**
|
6344 | * Utility type exposed to enable users to define options that can be passed to
|
6345 | * `puppeteer.launch` without having to list the set of all types.
|
6346 | * @public
|
6347 | */
|
6348 | export declare type PuppeteerNodeLaunchOptions = BrowserLaunchArgumentOptions & LaunchOptions & BrowserConnectOptions;
|
6349 |
|
6350 | /**
|
6351 | * @public
|
6352 | * {@inheritDoc Puppeteer.registerCustomQueryHandler}
|
6353 | */
|
6354 | export declare function registerCustomQueryHandler(name: string, queryHandler: CustomQueryHandler): void;
|
6355 |
|
6356 | /**
|
6357 | * @public
|
6358 | */
|
6359 | export declare interface RemoteAddress {
|
6360 | ip: string;
|
6361 | port: number;
|
6362 | }
|
6363 |
|
6364 | /**
|
6365 | * Resource types for HTTPRequests as perceived by the rendering engine.
|
6366 | *
|
6367 | * @public
|
6368 | */
|
6369 | export declare type ResourceType = Lowercase<Protocol.Network.ResourceType>;
|
6370 |
|
6371 | /**
|
6372 | * Required response data to fulfill a request with.
|
6373 | *
|
6374 | * @public
|
6375 | */
|
6376 | export declare interface ResponseForRequest {
|
6377 | status: number;
|
6378 | /**
|
6379 | * Optional response headers. All values are converted to strings.
|
6380 | */
|
6381 | headers: Record<string, unknown>;
|
6382 | contentType: string;
|
6383 | body: string | Buffer;
|
6384 | }
|
6385 |
|
6386 | /**
|
6387 | * @public
|
6388 | */
|
6389 | export declare interface ScreenshotClip {
|
6390 | x: number;
|
6391 | y: number;
|
6392 | width: number;
|
6393 | height: number;
|
6394 | }
|
6395 |
|
6396 | /**
|
6397 | * @public
|
6398 | */
|
6399 | export declare interface ScreenshotOptions {
|
6400 | /**
|
6401 | * @defaultValue 'png'
|
6402 | */
|
6403 | type?: 'png' | 'jpeg' | 'webp';
|
6404 | /**
|
6405 | * The file path to save the image to. The screenshot type will be inferred
|
6406 | * from file extension. If path is a relative path, then it is resolved
|
6407 | * relative to current working directory. If no path is provided, the image
|
6408 | * won't be saved to the disk.
|
6409 | */
|
6410 | path?: string;
|
6411 | /**
|
6412 | * When true, takes a screenshot of the full page.
|
6413 | * @defaultValue false
|
6414 | */
|
6415 | fullPage?: boolean;
|
6416 | /**
|
6417 | * An object which specifies the clipping region of the page.
|
6418 | */
|
6419 | clip?: ScreenshotClip;
|
6420 | /**
|
6421 | * Quality of the image, between 0-100. Not applicable to `png` images.
|
6422 | */
|
6423 | quality?: number;
|
6424 | /**
|
6425 | * Hides default white background and allows capturing screenshots with transparency.
|
6426 | * @defaultValue false
|
6427 | */
|
6428 | omitBackground?: boolean;
|
6429 | /**
|
6430 | * Encoding of the image.
|
6431 | * @defaultValue 'binary'
|
6432 | */
|
6433 | encoding?: 'base64' | 'binary';
|
6434 | /**
|
6435 | * If you need a screenshot bigger than the Viewport
|
6436 | * @defaultValue true
|
6437 | */
|
6438 | captureBeyondViewport?: boolean;
|
6439 | }
|
6440 |
|
6441 | /**
|
6442 | * The SecurityDetails class represents the security details of a
|
6443 | * response that was received over a secure connection.
|
6444 | *
|
6445 | * @public
|
6446 | */
|
6447 | export declare class SecurityDetails {
|
6448 | private _subjectName;
|
6449 | private _issuer;
|
6450 | private _validFrom;
|
6451 | private _validTo;
|
6452 | private _protocol;
|
6453 | private _sanList;
|
6454 | /**
|
6455 | * @internal
|
6456 | */
|
6457 | constructor(securityPayload: Protocol.Network.SecurityDetails);
|
6458 | /**
|
6459 | * @returns The name of the issuer of the certificate.
|
6460 | */
|
6461 | issuer(): string;
|
6462 | /**
|
6463 | * @returns {@link https://en.wikipedia.org/wiki/Unix_time | Unix timestamp}
|
6464 | * marking the start of the certificate's validity.
|
6465 | */
|
6466 | validFrom(): number;
|
6467 | /**
|
6468 | * @returns {@link https://en.wikipedia.org/wiki/Unix_time | Unix timestamp}
|
6469 | * marking the end of the certificate's validity.
|
6470 | */
|
6471 | validTo(): number;
|
6472 | /**
|
6473 | * @returns The security protocol being used, e.g. "TLS 1.2".
|
6474 | */
|
6475 | protocol(): string;
|
6476 | /**
|
6477 | * @returns The name of the subject to which the certificate was issued.
|
6478 | */
|
6479 | subjectName(): string;
|
6480 | /**
|
6481 | * @returns The list of {@link https://en.wikipedia.org/wiki/Subject_Alternative_Name | subject alternative names (SANs)} of the certificate.
|
6482 | */
|
6483 | subjectAlternativeNames(): string[];
|
6484 | }
|
6485 |
|
6486 | /**
|
6487 | * @public
|
6488 | */
|
6489 | export declare type Serializable = number | string | boolean | null | BigInt | JSONArray | JSONObject;
|
6490 |
|
6491 | /**
|
6492 | * @public
|
6493 | */
|
6494 | export declare type SerializableOrJSHandle = Serializable | JSHandle;
|
6495 |
|
6496 | /**
|
6497 | * Represents a Node and the properties of it that are relevant to Accessibility.
|
6498 | * @public
|
6499 | */
|
6500 | export declare interface SerializedAXNode {
|
6501 | /**
|
6502 | * The {@link https://www.w3.org/TR/wai-aria/#usage_intro | role} of the node.
|
6503 | */
|
6504 | role: string;
|
6505 | /**
|
6506 | * A human readable name for the node.
|
6507 | */
|
6508 | name?: string;
|
6509 | /**
|
6510 | * The current value of the node.
|
6511 | */
|
6512 | value?: string | number;
|
6513 | /**
|
6514 | * An additional human readable description of the node.
|
6515 | */
|
6516 | description?: string;
|
6517 | /**
|
6518 | * Any keyboard shortcuts associated with this node.
|
6519 | */
|
6520 | keyshortcuts?: string;
|
6521 | /**
|
6522 | * A human readable alternative to the role.
|
6523 | */
|
6524 | roledescription?: string;
|
6525 | /**
|
6526 | * A description of the current value.
|
6527 | */
|
6528 | valuetext?: string;
|
6529 | disabled?: boolean;
|
6530 | expanded?: boolean;
|
6531 | focused?: boolean;
|
6532 | modal?: boolean;
|
6533 | multiline?: boolean;
|
6534 | /**
|
6535 | * Whether more than one child can be selected.
|
6536 | */
|
6537 | multiselectable?: boolean;
|
6538 | readonly?: boolean;
|
6539 | required?: boolean;
|
6540 | selected?: boolean;
|
6541 | /**
|
6542 | * Whether the checkbox is checked, or in a
|
6543 | * {@link https://www.w3.org/TR/wai-aria-practices/examples/checkbox/checkbox-2/checkbox-2.html | mixed state}.
|
6544 | */
|
6545 | checked?: boolean | 'mixed';
|
6546 | /**
|
6547 | * Whether the node is checked or in a mixed state.
|
6548 | */
|
6549 | pressed?: boolean | 'mixed';
|
6550 | /**
|
6551 | * The level of a heading.
|
6552 | */
|
6553 | level?: number;
|
6554 | valuemin?: number;
|
6555 | valuemax?: number;
|
6556 | autocomplete?: string;
|
6557 | haspopup?: string;
|
6558 | /**
|
6559 | * Whether and in what way this node's value is invalid.
|
6560 | */
|
6561 | invalid?: string;
|
6562 | orientation?: string;
|
6563 | /**
|
6564 | * Children of this node, if there are any.
|
6565 | */
|
6566 | children?: SerializedAXNode[];
|
6567 | }
|
6568 |
|
6569 | /**
|
6570 | * @public
|
6571 | */
|
6572 | export declare interface SnapshotOptions {
|
6573 | /**
|
6574 | * Prune uninteresting nodes from the tree.
|
6575 | * @defaultValue true
|
6576 | */
|
6577 | interestingOnly?: boolean;
|
6578 | /**
|
6579 | * Root node to get the accessibility tree for
|
6580 | * @defaultValue The root node of the entire page.
|
6581 | */
|
6582 | root?: ElementHandle;
|
6583 | }
|
6584 |
|
6585 | /**
|
6586 | * @public
|
6587 | */
|
6588 | export declare class Target {
|
6589 | private _targetInfo;
|
6590 | private _browserContext;
|
6591 | private _sessionFactory;
|
6592 | private _ignoreHTTPSErrors;
|
6593 | private _defaultViewport?;
|
6594 | private _pagePromise?;
|
6595 | private _workerPromise?;
|
6596 | /**
|
6597 | * @internal
|
6598 | */
|
6599 | _initializedPromise: Promise<boolean>;
|
6600 | /**
|
6601 | * @internal
|
6602 | */
|
6603 | _initializedCallback: (x: boolean) => void;
|
6604 | /**
|
6605 | * @internal
|
6606 | */
|
6607 | _isClosedPromise: Promise<void>;
|
6608 | /**
|
6609 | * @internal
|
6610 | */
|
6611 | _closedCallback: () => void;
|
6612 | /**
|
6613 | * @internal
|
6614 | */
|
6615 | _isInitialized: boolean;
|
6616 | /**
|
6617 | * @internal
|
6618 | */
|
6619 | _targetId: string;
|
6620 | /**
|
6621 | * @internal
|
6622 | */
|
6623 | constructor(targetInfo: Protocol.Target.TargetInfo, browserContext: BrowserContext, sessionFactory: () => Promise<CDPSession>, ignoreHTTPSErrors: boolean, defaultViewport: Viewport | null);
|
6624 | /**
|
6625 | * Creates a Chrome Devtools Protocol session attached to the target.
|
6626 | */
|
6627 | createCDPSession(): Promise<CDPSession>;
|
6628 | /**
|
6629 | * If the target is not of type `"page"` or `"background_page"`, returns `null`.
|
6630 | */
|
6631 | page(): Promise<Page | null>;
|
6632 | /**
|
6633 | * If the target is not of type `"service_worker"` or `"shared_worker"`, returns `null`.
|
6634 | */
|
6635 | worker(): Promise<WebWorker | null>;
|
6636 | url(): string;
|
6637 | /**
|
6638 | * Identifies what kind of target this is.
|
6639 | *
|
6640 | * @remarks
|
6641 | *
|
6642 | * See {@link https://developer.chrome.com/extensions/background_pages | docs} for more info about background pages.
|
6643 | */
|
6644 | type(): 'page' | 'background_page' | 'service_worker' | 'shared_worker' | 'other' | 'browser' | 'webview';
|
6645 | /**
|
6646 | * Get the browser the target belongs to.
|
6647 | */
|
6648 | browser(): Browser;
|
6649 | /**
|
6650 | * Get the browser context the target belongs to.
|
6651 | */
|
6652 | browserContext(): BrowserContext;
|
6653 | /**
|
6654 | * Get the target that opened this target. Top-level targets return `null`.
|
6655 | */
|
6656 | opener(): Target | null;
|
6657 | /**
|
6658 | * @internal
|
6659 | */
|
6660 | _targetInfoChanged(targetInfo: Protocol.Target.TargetInfo): void;
|
6661 | }
|
6662 |
|
6663 | /**
|
6664 | * @public
|
6665 | */
|
6666 | export declare type TargetFilterCallback = (target: Protocol.Target.TargetInfo) => boolean;
|
6667 |
|
6668 | /**
|
6669 | * TimeoutError is emitted whenever certain operations are terminated due to timeout.
|
6670 | *
|
6671 | * @remarks
|
6672 | *
|
6673 | * Example operations are {@link Page.waitForSelector | page.waitForSelector}
|
6674 | * or {@link PuppeteerNode.launch | puppeteer.launch}.
|
6675 | *
|
6676 | * @public
|
6677 | */
|
6678 | export declare class TimeoutError extends CustomError {
|
6679 | }
|
6680 |
|
6681 | /**
|
6682 | * Copyright 2019 Google Inc. All rights reserved.
|
6683 | *
|
6684 | * Licensed under the Apache License, Version 2.0 (the "License");
|
6685 | * you may not use this file except in compliance with the License.
|
6686 | * You may obtain a copy of the License at
|
6687 | *
|
6688 | * http://www.apache.org/licenses/LICENSE-2.0
|
6689 | *
|
6690 | * Unless required by applicable law or agreed to in writing, software
|
6691 | * distributed under the License is distributed on an "AS IS" BASIS,
|
6692 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
6693 | * See the License for the specific language governing permissions and
|
6694 | * limitations under the License.
|
6695 | */
|
6696 | /**
|
6697 | * @internal
|
6698 | */
|
6699 | export declare class TimeoutSettings {
|
6700 | _defaultTimeout: number | null;
|
6701 | _defaultNavigationTimeout: number | null;
|
6702 | constructor();
|
6703 | setDefaultTimeout(timeout: number): void;
|
6704 | setDefaultNavigationTimeout(timeout: number): void;
|
6705 | navigationTimeout(): number;
|
6706 | timeout(): number;
|
6707 | }
|
6708 |
|
6709 | /**
|
6710 | * The Touchscreen class exposes touchscreen events.
|
6711 | * @public
|
6712 | */
|
6713 | export declare class Touchscreen {
|
6714 | private _client;
|
6715 | private _keyboard;
|
6716 | /**
|
6717 | * @internal
|
6718 | */
|
6719 | constructor(client: CDPSession, keyboard: Keyboard);
|
6720 | /**
|
6721 | * Dispatches a `touchstart` and `touchend` event.
|
6722 | * @param x - Horizontal position of the tap.
|
6723 | * @param y - Vertical position of the tap.
|
6724 | */
|
6725 | tap(x: number, y: number): Promise<void>;
|
6726 | }
|
6727 |
|
6728 | /**
|
6729 | * The Tracing class exposes the tracing audit interface.
|
6730 | * @remarks
|
6731 | * You can use `tracing.start` and `tracing.stop` to create a trace file
|
6732 | * which can be opened in Chrome DevTools or {@link https://chromedevtools.github.io/timeline-viewer/ | timeline viewer}.
|
6733 | *
|
6734 | * @example
|
6735 | * ```js
|
6736 | * await page.tracing.start({path: 'trace.json'});
|
6737 | * await page.goto('https://www.google.com');
|
6738 | * await page.tracing.stop();
|
6739 | * ```
|
6740 | *
|
6741 | * @public
|
6742 | */
|
6743 | export declare class Tracing {
|
6744 | _client: CDPSession;
|
6745 | _recording: boolean;
|
6746 | _path: string;
|
6747 | /**
|
6748 | * @internal
|
6749 | */
|
6750 | constructor(client: CDPSession);
|
6751 | /**
|
6752 | * Starts a trace for the current page.
|
6753 | * @remarks
|
6754 | * Only one trace can be active at a time per browser.
|
6755 | * @param options - Optional `TracingOptions`.
|
6756 | */
|
6757 | start(options?: TracingOptions): Promise<void>;
|
6758 | /**
|
6759 | * Stops a trace started with the `start` method.
|
6760 | * @returns Promise which resolves to buffer with trace data.
|
6761 | */
|
6762 | stop(): Promise<Buffer>;
|
6763 | }
|
6764 |
|
6765 | /**
|
6766 | * @public
|
6767 | */
|
6768 | export declare interface TracingOptions {
|
6769 | path?: string;
|
6770 | screenshots?: boolean;
|
6771 | categories?: string[];
|
6772 | }
|
6773 |
|
6774 | /**
|
6775 | * @public
|
6776 | * {@inheritDoc Puppeteer.unregisterCustomQueryHandler}
|
6777 | */
|
6778 | export declare function unregisterCustomQueryHandler(name: string): void;
|
6779 |
|
6780 | /**
|
6781 | * Unwraps a DOM element out of an ElementHandle instance
|
6782 | * @public
|
6783 | **/
|
6784 | export declare type UnwrapElementHandle<X> = X extends ElementHandle<infer E> ? E : X;
|
6785 |
|
6786 | /**
|
6787 | * @public
|
6788 | */
|
6789 | export declare type UnwrapPromiseLike<T> = T extends PromiseLike<infer U> ? U : T;
|
6790 |
|
6791 | /**
|
6792 | * Copyright 2020 Google Inc. All rights reserved.
|
6793 | *
|
6794 | * Licensed under the Apache License, Version 2.0 (the "License");
|
6795 | * you may not use this file except in compliance with the License.
|
6796 | * You may obtain a copy of the License at
|
6797 | *
|
6798 | * http://www.apache.org/licenses/LICENSE-2.0
|
6799 | *
|
6800 | * Unless required by applicable law or agreed to in writing, software
|
6801 | * distributed under the License is distributed on an "AS IS" BASIS,
|
6802 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
6803 | * See the License for the specific language governing permissions and
|
6804 | * limitations under the License.
|
6805 | */
|
6806 | /**
|
6807 | *
|
6808 | * Sets the viewport of the page.
|
6809 | * @public
|
6810 | */
|
6811 | export declare interface Viewport {
|
6812 | /**
|
6813 | * The page width in pixels.
|
6814 | */
|
6815 | width: number;
|
6816 | /**
|
6817 | * The page height in pixels.
|
6818 | */
|
6819 | height: number;
|
6820 | /**
|
6821 | * Specify device scale factor.
|
6822 | * See {@link https://developer.mozilla.org/en-US/docs/Web/API/Window/devicePixelRatio | devicePixelRatio} for more info.
|
6823 | * @defaultValue 1
|
6824 | */
|
6825 | deviceScaleFactor?: number;
|
6826 | /**
|
6827 | * Whether the `meta viewport` tag is taken into account.
|
6828 | * @defaultValue false
|
6829 | */
|
6830 | isMobile?: boolean;
|
6831 | /**
|
6832 | * Specifies if the viewport is in landscape mode.
|
6833 | * @defaultValue false
|
6834 | */
|
6835 | isLandscape?: boolean;
|
6836 | /**
|
6837 | * Specify if the viewport supports touch events.
|
6838 | * @defaultValue false
|
6839 | */
|
6840 | hasTouch?: boolean;
|
6841 | }
|
6842 |
|
6843 | /**
|
6844 | * @public
|
6845 | */
|
6846 | export declare interface WaitForOptions {
|
6847 | /**
|
6848 | * Maximum wait time in milliseconds, defaults to 30 seconds, pass `0` to
|
6849 | * disable the timeout.
|
6850 | *
|
6851 | * @remarks
|
6852 | * The default value can be changed by using the
|
6853 | * {@link Page.setDefaultTimeout} or {@link Page.setDefaultNavigationTimeout}
|
6854 | * methods.
|
6855 | */
|
6856 | timeout?: number;
|
6857 | waitUntil?: PuppeteerLifeCycleEvent | PuppeteerLifeCycleEvent[];
|
6858 | }
|
6859 |
|
6860 | /**
|
6861 | * @public
|
6862 | */
|
6863 | export declare interface WaitForSelectorOptions {
|
6864 | visible?: boolean;
|
6865 | hidden?: boolean;
|
6866 | timeout?: number;
|
6867 | }
|
6868 |
|
6869 | /**
|
6870 | * @public
|
6871 | */
|
6872 | export declare interface WaitForTargetOptions {
|
6873 | /**
|
6874 | * Maximum wait time in milliseconds. Pass `0` to disable the timeout.
|
6875 | * @defaultValue 30 seconds.
|
6876 | */
|
6877 | timeout?: number;
|
6878 | }
|
6879 |
|
6880 | /**
|
6881 | * @internal
|
6882 | */
|
6883 | export declare class WaitTask {
|
6884 | _domWorld: DOMWorld;
|
6885 | _polling: string | number;
|
6886 | _timeout: number;
|
6887 | _predicateBody: string;
|
6888 | _args: SerializableOrJSHandle[];
|
6889 | _binding: PageBinding;
|
6890 | _runCount: number;
|
6891 | promise: Promise<JSHandle>;
|
6892 | _resolve: (x: JSHandle) => void;
|
6893 | _reject: (x: Error) => void;
|
6894 | _timeoutTimer?: NodeJS.Timeout;
|
6895 | _terminated: boolean;
|
6896 | constructor(options: WaitTaskOptions);
|
6897 | terminate(error: Error): void;
|
6898 | rerun(): Promise<void>;
|
6899 | _cleanup(): void;
|
6900 | }
|
6901 |
|
6902 | /**
|
6903 | * @internal
|
6904 | */
|
6905 | export declare interface WaitTaskOptions {
|
6906 | domWorld: DOMWorld;
|
6907 | predicateBody: Function | string;
|
6908 | title: string;
|
6909 | polling: string | number;
|
6910 | timeout: number;
|
6911 | binding?: PageBinding;
|
6912 | args: SerializableOrJSHandle[];
|
6913 | }
|
6914 |
|
6915 | /**
|
6916 | * @public
|
6917 | */
|
6918 | export declare interface WaitTimeoutOptions {
|
6919 | /**
|
6920 | * Maximum wait time in milliseconds, defaults to 30 seconds, pass `0` to
|
6921 | * disable the timeout.
|
6922 | *
|
6923 | * @remarks
|
6924 | * The default value can be changed by using the
|
6925 | * {@link Page.setDefaultTimeout} method.
|
6926 | */
|
6927 | timeout?: number;
|
6928 | }
|
6929 |
|
6930 | /**
|
6931 | * The WebWorker class represents a
|
6932 | * {@link https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API | WebWorker}.
|
6933 | *
|
6934 | * @remarks
|
6935 | * The events `workercreated` and `workerdestroyed` are emitted on the page
|
6936 | * object to signal the worker lifecycle.
|
6937 | *
|
6938 | * @example
|
6939 | * ```js
|
6940 | * page.on('workercreated', worker => console.log('Worker created: ' + worker.url()));
|
6941 | * page.on('workerdestroyed', worker => console.log('Worker destroyed: ' + worker.url()));
|
6942 | *
|
6943 | * console.log('Current workers:');
|
6944 | * for (const worker of page.workers()) {
|
6945 | * console.log(' ' + worker.url());
|
6946 | * }
|
6947 | * ```
|
6948 | *
|
6949 | * @public
|
6950 | */
|
6951 | export declare class WebWorker extends EventEmitter {
|
6952 | _client: CDPSession;
|
6953 | _url: string;
|
6954 | _executionContextPromise: Promise<ExecutionContext>;
|
6955 | _executionContextCallback: (value: ExecutionContext) => void;
|
6956 | /**
|
6957 | *
|
6958 | * @internal
|
6959 | */
|
6960 | constructor(client: CDPSession, url: string, consoleAPICalled: ConsoleAPICalledCallback, exceptionThrown: ExceptionThrownCallback);
|
6961 | /**
|
6962 | * @returns The URL of this web worker.
|
6963 | */
|
6964 | url(): string;
|
6965 | /**
|
6966 | * Returns the ExecutionContext the WebWorker runs in
|
6967 | * @returns The ExecutionContext the web worker runs in.
|
6968 | */
|
6969 | executionContext(): Promise<ExecutionContext>;
|
6970 | /**
|
6971 | * If the function passed to the `worker.evaluate` returns a Promise, then
|
6972 | * `worker.evaluate` would wait for the promise to resolve and return its
|
6973 | * value. If the function passed to the `worker.evaluate` returns a
|
6974 | * non-serializable value, then `worker.evaluate` resolves to `undefined`.
|
6975 | * DevTools Protocol also supports transferring some additional values that
|
6976 | * are not serializable by `JSON`: `-0`, `NaN`, `Infinity`, `-Infinity`, and
|
6977 | * bigint literals.
|
6978 | * Shortcut for `await worker.executionContext()).evaluate(pageFunction, ...args)`.
|
6979 | *
|
6980 | * @param pageFunction - Function to be evaluated in the worker context.
|
6981 | * @param args - Arguments to pass to `pageFunction`.
|
6982 | * @returns Promise which resolves to the return value of `pageFunction`.
|
6983 | */
|
6984 | evaluate<ReturnType extends any>(pageFunction: Function | string, ...args: any[]): Promise<ReturnType>;
|
6985 | /**
|
6986 | * The only difference between `worker.evaluate` and `worker.evaluateHandle`
|
6987 | * is that `worker.evaluateHandle` returns in-page object (JSHandle). If the
|
6988 | * function passed to the `worker.evaluateHandle` returns a `Promise`, then
|
6989 | * `worker.evaluateHandle` would wait for the promise to resolve and return
|
6990 | * its value. Shortcut for
|
6991 | * `await worker.executionContext()).evaluateHandle(pageFunction, ...args)`
|
6992 | *
|
6993 | * @param pageFunction - Function to be evaluated in the page context.
|
6994 | * @param args - Arguments to pass to `pageFunction`.
|
6995 | * @returns Promise which resolves to the return value of `pageFunction`.
|
6996 | */
|
6997 | evaluateHandle<HandlerType extends JSHandle = JSHandle>(pageFunction: EvaluateHandleFn, ...args: SerializableOrJSHandle[]): Promise<JSHandle>;
|
6998 | }
|
6999 |
|
7000 | /**
|
7001 | * Wraps a DOM element into an ElementHandle instance
|
7002 | * @public
|
7003 | **/
|
7004 | export declare type WrapElementHandle<X> = X extends Element ? ElementHandle<X> : X;
|
7005 |
|
7006 | export * from "devtools-protocol/types/protocol";
|
7007 |
|
7008 | export { }
|
7009 |
|
\ | No newline at end of file |