chrome-devtools-frontend 1.0.1021097 → 1.0.1021582

package/front_end/third_party/puppeteer/package/lib/esm/puppeteer/common/Page.d.ts

@@ -14,30 +14,33 @@
  * limitations under the License.
  */
 /// <reference types="node" />
+/// <reference types="node" />
+import { Protocol } from 'devtools-protocol';
 import type { Readable } from 'stream';
-import { EventEmitter } from './EventEmitter.js';
+import { Accessibility } from './Accessibility.js';
+import { Browser, BrowserContext } from './Browser.js';
 import { CDPSession } from './Connection.js';
+import { ConsoleMessage } from './ConsoleMessage.js';
+import { Coverage } from './Coverage.js';
 import { Dialog } from './Dialog.js';
+import { WaitForSelectorOptions } from './DOMWorld.js';
+import { ElementHandle } from './ElementHandle.js';
+import { EventEmitter } from './EventEmitter.js';
+import { FileChooser } from './FileChooser.js';
 import { Frame } from './FrameManager.js';
-import { Keyboard, Mouse, Touchscreen, MouseButton } from './Input.js';
-import { Tracing } from './Tracing.js';
-import { Coverage } from './Coverage.js';
-import { WebWorker } from './WebWorker.js';
-import { Browser, BrowserContext } from './Browser.js';
-import { Target } from './Target.js';
-import { JSHandle, ElementHandle } from './JSHandle.js';
-import { Viewport } from './PuppeteerViewport.js';
-import { Credentials, NetworkConditions } from './NetworkManager.js';
 import { HTTPRequest } from './HTTPRequest.js';
 import { HTTPResponse } from './HTTPResponse.js';
-import { Accessibility } from './Accessibility.js';
-import { FileChooser } from './FileChooser.js';
-import { ConsoleMessage } from './ConsoleMessage.js';
+import { Keyboard, Mouse, MouseButton, Touchscreen } from './Input.js';
+import { JSHandle } from './JSHandle.js';
 import { PuppeteerLifeCycleEvent } from './LifecycleWatcher.js';
-import { Protocol } from 'devtools-protocol';
-import { SerializableOrJSHandle, EvaluateHandleFn, WrapElementHandle, EvaluateFn, EvaluateFnReturnType, UnwrapPromiseLike } from './EvalTypes.js';
+import { Credentials, NetworkConditions } from './NetworkManager.js';
 import { PDFOptions } from './PDFOptions.js';
+import { Viewport } from './PuppeteerViewport.js';
+import { Target } from './Target.js';
 import { TaskQueue } from './TaskQueue.js';
+import { Tracing } from './Tracing.js';
+import { EvaluateFunc, HandleFor, NodeFor } from './types.js';
+import { WebWorker } from './WebWorker.js';
 /**
  * @public
  */
@@ -158,10 +161,15 @@ export interface ScreenshotOptions {
      */
     encoding?: 'base64' | 'binary';
     /**
-     * If you need a screenshot bigger than the Viewport
+     * Capture the screenshot beyond the viewport.
      * @defaultValue true
      */
     captureBeyondViewport?: boolean;
+    /**
+     * Capture the screenshot from the surface, rather than the view.
+     * @defaultValue true
+     */
+    fromSurface?: boolean;
 }
 /**
  * All the events that a page instance may emit.
@@ -179,13 +187,12 @@ export declare const enum PageEmittedEvents {
      * error or a warning.
      *
      * @remarks
-     *
      * A `console` event provides a {@link ConsoleMessage} representing the
      * console message that was logged.
      *
      * @example
      * An example of handling `console` event:
-     * ```js
+     * ```ts
      * page.on('console', msg => {
      *   for (let i = 0; i < msg.args().length; ++i)
      *    console.log(`${i}: ${msg.args()[i]}`);
@@ -202,7 +209,8 @@ export declare const enum PageEmittedEvents {
     Dialog = "dialog",
     /**
      * Emitted when the JavaScript
-     * {@link https://developer.mozilla.org/en-US/docs/Web/Events/DOMContentLoaded | DOMContentLoaded } event is dispatched.
+     * {@link https://developer.mozilla.org/en-US/docs/Web/Events/DOMContentLoaded | DOMContentLoaded }
+     * event is dispatched.
      */
     DOMContentLoaded = "domcontentloaded",
     /**
@@ -213,7 +221,10 @@ export declare const enum PageEmittedEvents {
     FrameAttached = "frameattached",
     /** Emitted when a frame is detached. Will contain a {@link Frame}. */
     FrameDetached = "framedetached",
-    /** Emitted when a frame is navigated to a new URL. Will contain a {@link Frame}. */
+    /**
+     * Emitted when a frame is navigated to a new URL. Will contain a
+     * {@link Frame}.
+     */
     FrameNavigated = "framenavigated",
     /**
      * Emitted when the JavaScript
@@ -244,14 +255,14 @@ export declare const enum PageEmittedEvents {
      *
      * @example
      *
-     * ```js
+     * ```ts
      * const [popup] = await Promise.all([
      *   new Promise(resolve => page.once('popup', resolve)),
      *   page.click('a[target=_blank]'),
      * ]);
      * ```
      *
-     * ```js
+     * ```ts
      * const [popup] = await Promise.all([
      *   new Promise(resolve => page.once('popup', resolve)),
      *   page.evaluate(() => window.open('https://example.com')),
@@ -281,10 +292,9 @@ export declare const enum PageEmittedEvents {
      * Contains a {@link HTTPRequest}.
      *
      * @remarks
-     *
-     * NOTE: HTTP Error responses, such as 404 or 503, are still successful
-     * responses from HTTP standpoint, so request will complete with
-     * `requestfinished` event and not with `requestfailed`.
+     * HTTP Error responses, such as 404 or 503, are still successful responses
+     * from HTTP standpoint, so request will complete with `requestfinished` event
+     * and not with `requestfailed`.
      */
     RequestFailed = "requestfailed",
     /**
@@ -341,15 +351,18 @@ export interface PageEventObject {
 }
 /**
  * Page provides methods to interact with a single tab or
- * {@link https://developer.chrome.com/extensions/background_pages | extension background page} in Chromium.
+ * {@link https://developer.chrome.com/extensions/background_pages | extension background page}
+ * in Chromium.
  *
- * @remarks
+ * :::note
  *
  * One Browser instance might have multiple Page instances.
  *
+ * :::
+ *
  * @example
- * This example creates a page, navigates it to a URL, and then * saves a screenshot:
- * ```js
+ * This example creates a page, navigates it to a URL, and then saves a screenshot:
+ * ```ts
  * const puppeteer = require('puppeteer');
  *
  * (async () => {
@@ -366,13 +379,13 @@ export interface PageEventObject {
  *
  * @example
  * This example logs a message for a single page `load` event:
- * ```js
+ * ```ts
  * page.once('load', () => console.log('Page loaded!'));
  * ```
  *
- * To unsubscribe from events use the `off` method:
+ * To unsubscribe from events use the {@link Page.off} method:
  *
- * ```js
+ * ```ts
  * function logRequest(interceptedRequest) {
  *   console.log('A request was made:', interceptedRequest.url());
  * }
@@ -380,40 +393,19 @@ export interface PageEventObject {
  * // Sometime later...
  * page.off('request', logRequest);
  * ```
+ *
  * @public
  */
 export declare class Page extends EventEmitter {
+    #private;
     /**
      * @internal
      */
-    static create(client: CDPSession, target: Target, ignoreHTTPSErrors: boolean, defaultViewport: Viewport | null, screenshotTaskQueue: TaskQueue): Promise<Page>;
-    private _closed;
-    private _client;
-    private _target;
-    private _keyboard;
-    private _mouse;
-    private _timeoutSettings;
-    private _touchscreen;
-    private _accessibility;
-    private _frameManager;
-    private _emulationManager;
-    private _tracing;
-    private _pageBindings;
-    private _coverage;
-    private _javascriptEnabled;
-    private _viewport;
-    private _screenshotTaskQueue;
-    private _workers;
-    private _fileChooserInterceptors;
-    private _disconnectPromise?;
-    private _userDragInterceptionEnabled;
-    private _handlerMap;
+    static _create(client: CDPSession, target: Target, ignoreHTTPSErrors: boolean, defaultViewport: Viewport | null, screenshotTaskQueue: TaskQueue): Promise<Page>;
     /**
      * @internal
      */
     constructor(client: CDPSession, target: Target, ignoreHTTPSErrors: boolean, screenshotTaskQueue: TaskQueue);
-    private _initialize;
-    private _onFileChooser;
     /**
      * @returns `true` if drag events are being intercepted, `false` otherwise.
      */
@@ -424,16 +416,38 @@ export declare class Page extends EventEmitter {
     isJavaScriptEnabled(): boolean;
     /**
      * Listen to page events.
+     *
+     * :::note
+     *
+     * This method exists to define event typings and handle proper wireup of
+     * cooperative request interception. Actual event listening and dispatching is
+     * delegated to {@link EventEmitter}.
+     *
+     * :::
      */
     on<K extends keyof PageEventObject>(eventName: K, handler: (event: PageEventObject[K]) => void): EventEmitter;
     once<K extends keyof PageEventObject>(eventName: K, handler: (event: PageEventObject[K]) => void): EventEmitter;
     off<K extends keyof PageEventObject>(eventName: K, handler: (event: PageEventObject[K]) => void): EventEmitter;
     /**
      * This method is typically coupled with an action that triggers file
-     * choosing. The following example clicks a button that issues a file chooser
+     * choosing.
+     *
+     * :::caution
+     *
+     * This must be called before the file chooser is launched. It will not return
+     * a currently active file chooser.
+     *
+     * :::
+     *
+     * @remarks
+     * In non-headless Chromium, this method results in the native file picker
+     * dialog `not showing up` for the user.
+     *
+     * @example
+     * The following example clicks a button that issues a file chooser
      * and then responds with `/tmp/myfile.pdf` as if a user has selected this file.
      *
-     * ```js
+     * ```ts
      * const [fileChooser] = await Promise.all([
      * page.waitForFileChooser(),
      * page.click('#upload-file-button'),
@@ -441,14 +455,6 @@ export declare class Page extends EventEmitter {
      * ]);
      * await fileChooser.accept(['/tmp/myfile.pdf']);
      * ```
-     *
-     * NOTE: This must be called before the file chooser is launched. It will not
-     * return a currently active file chooser.
-     * @param options - Optional waiting parameters
-     * @returns Resolves after a page requests a file picker.
-     * @remarks
-     * NOTE: In non-headless Chromium, this method results in the native file picker
-     * dialog `not showing up` for the user.
      */
     waitForFileChooser(options?: WaitTimeoutOptions): Promise<FileChooser>;
     /**
@@ -457,7 +463,7 @@ export declare class Page extends EventEmitter {
      * NOTE: Consider using {@link BrowserContext.overridePermissions} to grant
      * permissions for the page to read its geolocation.
      * @example
-     * ```js
+     * ```ts
      * await page.setGeolocation({latitude: 59.95, longitude: 30.31667});
      * ```
      */
@@ -467,10 +473,9 @@ export declare class Page extends EventEmitter {
      */
     target(): Target;
     /**
-     * Get the CDP session client the page belongs to.
      * @internal
      */
-    client(): CDPSession;
+    _client(): CDPSession;
     /**
      * Get the browser the page belongs to.
      */
@@ -479,8 +484,6 @@ export declare class Page extends EventEmitter {
      * Get the browser context that the page belongs to.
      */
     browserContext(): BrowserContext;
-    private _onTargetCrashed;
-    private _onLogEntryAdded;
     /**
      * @returns The page's main frame.
      * @remarks
@@ -518,7 +521,7 @@ export declare class Page extends EventEmitter {
      *
      * @example
      * An example of a naïve request interceptor that aborts all image requests:
-     * ```js
+     * ```ts
      * const puppeteer = require('puppeteer');
      * (async () => {
      *   const browser = await puppeteer.launch();
@@ -558,7 +561,7 @@ export declare class Page extends EventEmitter {
     /**
      * @param networkConditions - Passing `null` disables network condition emulation.
      * @example
-     * ```js
+     * ```ts
      * const puppeteer = require('puppeteer');
      * const slow3G = puppeteer.networkConditions['Slow 3G'];
      *
@@ -603,14 +606,19 @@ export declare class Page extends EventEmitter {
      * Runs `document.querySelector` within the page. If no element matches the
      * selector, the return value resolves to `null`.
      *
-     * @remarks
-     * Shortcut for {@link Frame.$ | Page.mainFrame().$(selector) }.
-     *
      * @param selector - A `selector` to query page for
      * {@link https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors | selector}
      * to query page for.
      */
-    $<T extends Element = Element>(selector: string): Promise<ElementHandle<T> | null>;
+    $<Selector extends string>(selector: Selector): Promise<ElementHandle<NodeFor<Selector>> | null>;
+    /**
+     * The method runs `document.querySelectorAll` within the page. If no elements
+     * match the selector, the return value resolves to `[]`.
+     * @remarks
+     * Shortcut for {@link Frame.$$ | Page.mainFrame().$$(selector) }.
+     * @param selector - A `selector` to query page for
+     */
+    $$<Selector extends string>(selector: Selector): Promise<Array<ElementHandle<NodeFor<Selector>>>>;
     /**
      * @remarks
      *
@@ -625,13 +633,13 @@ export declare class Page extends EventEmitter {
      * recommended as they are easier to debug and use with TypeScript):
      *
      * @example
-     * ```
+     * ```ts
      * const aHandle = await page.evaluateHandle('document')
      * ```
      *
      * @example
      * {@link JSHandle} instances can be passed as arguments to the `pageFunction`:
-     * ```
+     * ```ts
      * const aHandle = await page.evaluateHandle(() => document.body);
      * const resultHandle = await page.evaluateHandle(body => body.innerHTML, aHandle);
      * console.log(await resultHandle.jsonValue());
@@ -643,7 +651,7 @@ export declare class Page extends EventEmitter {
      * you instead get an {@link ElementHandle} back:
      *
      * @example
-     * ```
+     * ```ts
      * const button = await page.evaluateHandle(() => document.querySelector('button'));
      * // can call `click` because `button` is an `ElementHandle`
      * await button.click();
@@ -653,14 +661,14 @@ export declare class Page extends EventEmitter {
      *  a `JSHandle`, but if you know it's going to return an
      * `ElementHandle`, pass it as the generic argument:
      *
-     * ```
+     * ```ts
      * const button = await page.evaluateHandle<ElementHandle>(...);
      * ```
      *
      * @param pageFunction - a function that is run within the page
      * @param args - arguments to be passed to the pageFunction
      */
-    evaluateHandle<HandlerType extends JSHandle = JSHandle>(pageFunction: EvaluateHandleFn, ...args: SerializableOrJSHandle[]): Promise<HandlerType>;
+    evaluateHandle<Params extends unknown[], Func extends EvaluateFunc<Params> = EvaluateFunc<Params>>(pageFunction: Func | string, ...args: Params): Promise<HandleFor<Awaited<ReturnType<Func>>>>;
     /**
      * This method iterates the JavaScript heap and finds all objects with the
      * given prototype.
@@ -672,7 +680,7 @@ export declare class Page extends EventEmitter {
      *
      * @example
      *
-     * ```js
+     * ```ts
      * // Create a Map object
      * await page.evaluate(() => window.map = new Map());
      * // Get a handle to the Map object prototype
@@ -688,7 +696,7 @@ export declare class Page extends EventEmitter {
      * @returns Promise which resolves to a handle to an array of objects with
      * this prototype.
      */
-    queryObjects(prototypeHandle: JSHandle): Promise<JSHandle>;
+    queryObjects<Prototype>(prototypeHandle: JSHandle<Prototype>): Promise<JSHandle<Prototype[]>>;
     /**
      * This method runs `document.querySelector` within the page and passes the
      * result as the first argument to the `pageFunction`.
@@ -702,7 +710,7 @@ export declare class Page extends EventEmitter {
      *
      * @example
      *
-     * ```
+     * ```ts
      * const searchValue = await page.$eval('#search', el => el.value);
      * const preloadHref = await page.$eval('link[rel=preload]', el => el.href);
      * const html = await page.$eval('.main-container', el => el.outerHTML);
@@ -715,7 +723,7 @@ export declare class Page extends EventEmitter {
      *
      * @example
      *
-     * ```
+     * ```ts
      * // if you don't provide HTMLInputElement here, TS will error
      * // as `value` is not on `Element`
      * const searchValue = await page.$eval('#search', (el: HTMLInputElement) => el.value);
@@ -727,7 +735,7 @@ export declare class Page extends EventEmitter {
      *
      * @example
      *
-     * ```
+     * ```ts
      * // The compiler can infer the return type in this case, but if it can't
      * // or if you want to be more explicit, provide it as the generic type.
      * const searchValue = await page.$eval<string>(
@@ -747,7 +755,10 @@ export declare class Page extends EventEmitter {
      * is wrapped in an {@link ElementHandle}, else the raw value itself is
      * returned.
      */
-    $eval<ReturnType>(selector: string, pageFunction: (element: Element, ...args: unknown[]) => ReturnType | Promise<ReturnType>, ...args: SerializableOrJSHandle[]): Promise<WrapElementHandle<ReturnType>>;
+    $eval<Selector extends string, Params extends unknown[], Func extends EvaluateFunc<[
+        ElementHandle<NodeFor<Selector>>,
+        ...Params
+    ]> = EvaluateFunc<[ElementHandle<NodeFor<Selector>>, ...Params]>>(selector: Selector, pageFunction: Func | string, ...args: Params): Promise<Awaited<ReturnType<Func>>>;
     /**
      * This method runs `Array.from(document.querySelectorAll(selector))` within
      * the page and passes the result as the first argument to the `pageFunction`.
@@ -759,7 +770,7 @@ export declare class Page extends EventEmitter {
      *
      * @example
      *
-     * ```
+     * ```ts
      * // get the amount of divs on the page
      * const divCount = await page.$$eval('div', divs => divs.length);
      *
@@ -776,7 +787,7 @@ export declare class Page extends EventEmitter {
      *
      * @example
      *
-     * ```
+     * ```ts
      * // if you don't provide HTMLInputElement here, TS will error
      * // as `value` is not on `Element`
      * await page.$$eval('input', (elements: HTMLInputElement[]) => {
@@ -790,7 +801,7 @@ export declare class Page extends EventEmitter {
      *
      * @example
      *
-     * ```
+     * ```ts
      * // The compiler can infer the return type in this case, but if it can't
      * // or if you want to be more explicit, provide it as the generic type.
      * const allInputValues = await page.$$eval<string[]>(
@@ -810,15 +821,10 @@ export declare class Page extends EventEmitter {
      * is wrapped in an {@link ElementHandle}, else the raw value itself is
      * returned.
      */
-    $$eval<ReturnType>(selector: string, pageFunction: (elements: Element[], ...args: unknown[]) => ReturnType | Promise<ReturnType>, ...args: SerializableOrJSHandle[]): Promise<WrapElementHandle<ReturnType>>;
-    /**
-     * The method runs `document.querySelectorAll` within the page. If no elements
-     * match the selector, the return value resolves to `[]`.
-     * @remarks
-     * Shortcut for {@link Frame.$$ | Page.mainFrame().$$(selector) }.
-     * @param selector - A `selector` to query page for
-     */
-    $$<T extends Element = Element>(selector: string): Promise<Array<ElementHandle<T>>>;
+    $$eval<Selector extends string, Params extends unknown[], Func extends EvaluateFunc<[
+        Array<NodeFor<Selector>>,
+        ...Params
+    ]> = EvaluateFunc<[Array<NodeFor<Selector>>, ...Params]>>(selector: Selector, pageFunction: Func | string, ...args: Params): Promise<Awaited<ReturnType<Func>>>;
     /**
      * The method evaluates the XPath expression relative to the page document as
      * its context node. If there are no such elements, the method resolves to an
@@ -827,7 +833,7 @@ export declare class Page extends EventEmitter {
      * Shortcut for {@link Frame.$x | Page.mainFrame().$x(expression) }.
      * @param expression - Expression to evaluate
      */
-    $x(expression: string): Promise<ElementHandle[]>;
+    $x(expression: string): Promise<Array<ElementHandle<Node>>>;
     /**
      * If no URLs are specified, this method returns cookies for the current page
      * URL. If URLs are specified, only cookies for those URLs are returned.
@@ -836,7 +842,7 @@ export declare class Page extends EventEmitter {
     deleteCookie(...cookies: Protocol.Network.DeleteCookiesRequest[]): Promise<void>;
     /**
      * @example
-     * ```js
+     * ```ts
      * await page.setCookie(cookieObject1, cookieObject2);
      * ```
      */
@@ -854,7 +860,7 @@ export declare class Page extends EventEmitter {
         content?: string;
         type?: string;
         id?: string;
-    }): Promise<ElementHandle>;
+    }): Promise<ElementHandle<HTMLScriptElement>>;
     /**
      * Adds a `<link rel="stylesheet">` tag into the page with the desired URL or a
      * `<style type="text/css">` tag with the content.
@@ -865,7 +871,7 @@ export declare class Page extends EventEmitter {
         url?: string;
         path?: string;
         content?: string;
-    }): Promise<ElementHandle>;
+    }): Promise<ElementHandle<Node>>;
     /**
      * The method adds a function called `name` on the page's `window` object. When
      * called, the function executes `puppeteerFunction` in node.js and returns a
@@ -875,11 +881,11 @@ export declare class Page extends EventEmitter {
      *
      * NOTE: Functions installed via `page.exposeFunction` survive navigations.
      * @param name - Name of the function on the window object
-     * @param puppeteerFunction -  Callback function which will be called in
+     * @param pptrFunction -  Callback function which will be called in
      * Puppeteer's context.
      * @example
      * An example of adding an `md5` function into the page:
-     * ```js
+     * ```ts
      * const puppeteer = require('puppeteer');
      * const crypto = require('crypto');
      *
@@ -900,7 +906,7 @@ export declare class Page extends EventEmitter {
      * })();
      * ```
      * An example of adding a `window.readfile` function into the page:
-     * ```js
+     * ```ts
      * const puppeteer = require('puppeteer');
      * const fs = require('fs');
      *
@@ -925,7 +931,7 @@ export declare class Page extends EventEmitter {
      * })();
      * ```
      */
-    exposeFunction(name: string, puppeteerFunction: Function | {
+    exposeFunction(name: string, pptrFunction: Function | {
         default: Function;
     }): Promise<void>;
     /**
@@ -986,21 +992,6 @@ export declare class Page extends EventEmitter {
      * in seconds since an arbitrary point in the past.
      */
     metrics(): Promise<Metrics>;
-    private _emitMetrics;
-    private _buildMetricsObject;
-    private _handleException;
-    private _onConsoleAPI;
-    private _onBindingCalled;
-    private _addConsoleMessage;
-    private _onDialog;
-    /**
-     * Resets default white background
-     */
-    private _resetDefaultBackgroundColor;
-    /**
-     * Hides default white background
-     */
-    private _setTransparentBackgroundColor;
     /**
      *
      * @returns
@@ -1017,23 +1008,21 @@ export declare class Page extends EventEmitter {
      *
      * - `timeout` : Maximum time in milliseconds for resources to load, defaults
      *   to 30 seconds, pass `0` to disable timeout. The default value can be
-     *   changed by using the
-     *   {@link Page.setDefaultNavigationTimeout |
-     *   page.setDefaultNavigationTimeout(timeout)}
-     *   or {@link Page.setDefaultTimeout | page.setDefaultTimeout(timeout)}
-     *   methods.
-     *
-     * - `waitUntil`: When to consider setting markup succeeded, defaults to `load`.
-     *    Given an array of event strings, setting content is considered to be
-     *    successful after all events have been fired. Events can be either:<br/>
-     *  - `load` : consider setting content to be finished when the `load` event is
-     *    fired.<br/>
+     *   changed by using the {@link Page.setDefaultNavigationTimeout} or
+     *   {@link Page.setDefaultTimeout} methods.
+     *
+     * - `waitUntil`: When to consider setting markup succeeded, defaults to
+     *    `load`. Given an array of event strings, setting content is considered
+     *    to be successful after all events have been fired. Events can be
+     *    either:<br/>
+     *  - `load` : consider setting content to be finished when the `load` event
+     *    is fired.<br/>
      *  - `domcontentloaded` : consider setting content to be finished when the
-     *   `DOMContentLoaded` event is fired.<br/>
-     *  - `networkidle0` : consider setting content to be finished when there are no
-     *   more than 0 network connections for at least `500` ms.<br/>
-     *  - `networkidle2` : consider setting content to be finished when there are no
-     *   more than 2 network connections for at least `500` ms.
+     *    `DOMContentLoaded` event is fired.<br/>
+     *  - `networkidle0` : consider setting content to be finished when there are
+     *    no more than 0 network connections for at least `500` ms.<br/>
+     *  - `networkidle2` : consider setting content to be finished when there are
+     *    no more than 2 network connections for at least `500` ms.
      */
     setContent(html: string, options?: WaitForOptions): Promise<void>;
     /**
@@ -1048,15 +1037,12 @@ export declare class Page extends EventEmitter {
      *
      * - `timeout` : Maximum navigation time in milliseconds, defaults to 30
      *   seconds, pass 0 to disable timeout. The default value can be changed by
-     *   using the
-     *   {@link Page.setDefaultNavigationTimeout |
-     *   page.setDefaultNavigationTimeout(timeout)}
-     *   or {@link Page.setDefaultTimeout | page.setDefaultTimeout(timeout)}
-     *   methods.
+     *   using the {@link Page.setDefaultNavigationTimeout} or
+     *   {@link Page.setDefaultTimeout} methods.
      *
      * - `waitUntil`:When to consider navigation succeeded, defaults to `load`.
-     *    Given an array of event strings, navigation is considered to be successful
-     *    after all events have been fired. Events can be either:<br/>
+     *    Given an array of event strings, navigation is considered to be
+     *    successful after all events have been fired. Events can be either:<br/>
      *  - `load` : consider navigation to be finished when the load event is
      *    fired.<br/>
      *  - `domcontentloaded` : consider navigation to be finished when the
@@ -1087,14 +1073,14 @@ export declare class Page extends EventEmitter {
      * to the same URL with a different hash, which would succeed and return null.
      *
      * NOTE: Headless mode doesn't support navigation to a PDF document. See the
-     * {@link https://bugs.chromium.org/p/chromium/issues/detail?id=761295
-     * | upstream issue}.
+     * {@link https://bugs.chromium.org/p/chromium/issues/detail?id=761295 |
+     * upstream issue}.
      *
      * Shortcut for {@link Frame.goto | page.mainFrame().goto(url, options)}.
      */
     goto(url: string, options?: WaitForOptions & {
         referer?: string;
-    }): Promise<HTTPResponse>;
+    }): Promise<HTTPResponse | null>;
     /**
      * @param options - Navigation parameters which might have the following
      * properties:
@@ -1106,56 +1092,54 @@ export declare class Page extends EventEmitter {
      *
      * - `timeout` : Maximum navigation time in milliseconds, defaults to 30
      *   seconds, pass 0 to disable timeout. The default value can be changed by
-     *   using the
-     *   {@link Page.setDefaultNavigationTimeout |
-     *   page.setDefaultNavigationTimeout(timeout)}
-     *   or {@link Page.setDefaultTimeout | page.setDefaultTimeout(timeout)}
-     *   methods.
+     *   using the {@link Page.setDefaultNavigationTimeout} or
+     *   {@link Page.setDefaultTimeout} methods.
      *
      * - `waitUntil`: When to consider navigation succeeded, defaults to `load`.
      *    Given an array of event strings, navigation is considered to be
      *    successful after all events have been fired. Events can be either:<br/>
-     *  - `load` : consider navigation to be finished when the load event is fired.<br/>
+     *  - `load` : consider navigation to be finished when the load event is
+     *    fired.<br/>
      *  - `domcontentloaded` : consider navigation to be finished when the
-     *   DOMContentLoaded event is fired.<br/>
+     *    DOMContentLoaded event is fired.<br/>
      *  - `networkidle0` : consider navigation to be finished when there are no
-     *   more than 0 network connections for at least `500` ms.<br/>
+     *    more than 0 network connections for at least `500` ms.<br/>
      *  - `networkidle2` : consider navigation to be finished when there are no
-     *   more than 2 network connections for at least `500` ms.
+     *    more than 2 network connections for at least `500` ms.
      */
     reload(options?: WaitForOptions): Promise<HTTPResponse | null>;
     /**
-     * This resolves when the page navigates to a new URL or reloads. It is useful
-     * when you run code that will indirectly cause the page to navigate. Consider
-     * this example:
-     * ```js
+     * Waits for the page to navigate to a new URL or to reload. It is useful when
+     * you run code that will indirectly cause the page to navigate.
+     *
+     * @example
+     * ```ts
      * const [response] = await Promise.all([
      * page.waitForNavigation(), // The promise resolves after navigation has finished
      * page.click('a.my-link'), // Clicking the link will indirectly cause a navigation
      * ]);
      * ```
      *
-     * @param options - Navigation parameters which might have the following properties:
-     * @returns Promise which resolves to the main resource response. In case of
-     * multiple redirects, the navigation will resolve with the response of the
-     * last redirect. In case of navigation to a different anchor or navigation
-     * due to History API usage, the navigation will resolve with `null`.
      * @remarks
-     * NOTE: Usage of the
+     * 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.
      *
-     * Shortcut for
-     * {@link Frame.waitForNavigation | page.mainFrame().waitForNavigation(options)}.
+     * @param options - Navigation parameters which might have the following
+     * properties:
+     * @returns A `Promise` which resolves to the main resource response.
+     * - In case of multiple redirects, the navigation will resolve with the
+     *   response of the last redirect.
+     * - In case of navigation to a different anchor or navigation due to History
+     *   API usage, the navigation will resolve with `null`.
      */
     waitForNavigation(options?: WaitForOptions): Promise<HTTPResponse | null>;
-    private _sessionClosePromise;
     /**
      * @param urlOrPredicate - A URL or predicate to wait for
      * @param options - Optional waiting parameters
      * @returns Promise which resolves to the matched response
      * @example
-     * ```js
+     * ```ts
      * const firstResponse = await page.waitForResponse(
      * 'https://example.com/resource'
      * );
@@ -1183,7 +1167,7 @@ export declare class Page extends EventEmitter {
      * @param options - Optional waiting parameters
      * @returns Promise which resolves to the matched response.
      * @example
-     * ```js
+     * ```ts
      * const firstResponse = await page.waitForResponse(
      * 'https://example.com/resource'
      * );
@@ -1219,7 +1203,7 @@ export declare class Page extends EventEmitter {
      * @param options - Optional waiting parameters
      * @returns Promise which resolves to the matched frame.
      * @example
-     * ```js
+     * ```ts
      * const frame = await page.waitForFrame(async (frame) => {
      *   return frame.name() === 'Test';
      * });
@@ -1245,22 +1229,20 @@ export declare class Page extends EventEmitter {
      *
      * - `timeout` : Maximum navigation time in milliseconds, defaults to 30
      *   seconds, pass 0 to disable timeout. The default value can be changed by
-     *   using the
-     *   {@link Page.setDefaultNavigationTimeout
-     *   | page.setDefaultNavigationTimeout(timeout)}
-     *   or {@link Page.setDefaultTimeout | page.setDefaultTimeout(timeout)}
-     *   methods.
+     *   using the {@link Page.setDefaultNavigationTimeout} or
+     *   {@link Page.setDefaultTimeout} methods.
      *
      * - `waitUntil` : When to consider navigation succeeded, defaults to `load`.
      *    Given an array of event strings, navigation is considered to be
      *    successful after all events have been fired. Events can be either:<br/>
-     *  - `load` : consider navigation to be finished when the load event is fired.<br/>
+     *  - `load` : consider navigation to be finished when the load event is
+     *    fired.<br/>
      *  - `domcontentloaded` : consider navigation to be finished when the
-     *   DOMContentLoaded event is fired.<br/>
+     *    DOMContentLoaded event is fired.<br/>
      *  - `networkidle0` : consider navigation to be finished when there are no
-     *   more than 0 network connections for at least `500` ms.<br/>
+     *    more than 0 network connections for at least `500` ms.<br/>
      *  - `networkidle2` : consider navigation to be finished when there are no
-     *   more than 2 network connections for at least `500` ms.
+     *    more than 2 network connections for at least `500` ms.
      */
     goBack(options?: WaitForOptions): Promise<HTTPResponse | null>;
     /**
@@ -1274,38 +1256,38 @@ export declare class Page extends EventEmitter {
      *
      * - `timeout` : Maximum navigation time in milliseconds, defaults to 30
      *   seconds, pass 0 to disable timeout. The default value can be changed by
-     *   using the
-     *   {@link Page.setDefaultNavigationTimeout
-     *   | page.setDefaultNavigationTimeout(timeout)}
-     *   or {@link Page.setDefaultTimeout | page.setDefaultTimeout(timeout)}
-     *   methods.
+     *   using the {@link Page.setDefaultNavigationTimeout} or
+     *   {@link Page.setDefaultTimeout} methods.
      *
      * - `waitUntil`: When to consider navigation succeeded, defaults to `load`.
      *    Given an array of event strings, navigation is considered to be
      *    successful after all events have been fired. Events can be either:<br/>
-     *  - `load` : consider navigation to be finished when the load event is fired.<br/>
+     *  - `load` : consider navigation to be finished when the load event is
+     *    fired.<br/>
      *  - `domcontentloaded` : consider navigation to be finished when the
-     *   DOMContentLoaded event is fired.<br/>
+     *    DOMContentLoaded event is fired.<br/>
      *  - `networkidle0` : consider navigation to be finished when there are no
-     *   more than 0 network connections for at least `500` ms.<br/>
+     *    more than 0 network connections for at least `500` ms.<br/>
      *  - `networkidle2` : consider navigation to be finished when there are no
-     *   more than 2 network connections for at least `500` ms.
+     *    more than 2 network connections for at least `500` ms.
      */
     goForward(options?: WaitForOptions): Promise<HTTPResponse | null>;
-    private _go;
     /**
      * Brings page to front (activates tab).
      */
     bringToFront(): Promise<void>;
     /**
-     * Emulates given device metrics and user agent. This method is a shortcut for
-     * calling two methods: {@link Page.setUserAgent} and {@link Page.setViewport}
-     * To aid emulation, Puppeteer provides a list of device descriptors that can
-     * be obtained via the {@link Puppeteer.devices} `page.emulate` will resize
-     * the page. A lot of websites don't expect phones to change size, so you
-     * should emulate before navigating to the page.
+     * Emulates given device metrics and user agent.
+     *
+     * @remarks
+     * This method is a shortcut for calling two methods:
+     * {@link Page.setUserAgent} and {@link Page.setViewport} To aid emulation,
+     * Puppeteer provides a list of device descriptors that can be obtained via
+     * {@link devices}. `page.emulate` will resize the page. A lot of websites
+     * don't expect phones to change size, so you should emulate before navigating
+     * to the page.
      * @example
-     * ```js
+     * ```ts
      * const puppeteer = require('puppeteer');
      * const iPhone = puppeteer.devices['iPhone 6'];
      * (async () => {
@@ -1346,7 +1328,7 @@ export declare class Page extends EventEmitter {
      * values are `screen`, `print` and `null`. Passing `null` disables CSS media
      * emulation.
      * @example
-     * ```
+     * ```ts
      * await page.evaluate(() => matchMedia('screen').matches);
      * // → true
      * await page.evaluate(() => matchMedia('print').matches);
@@ -1376,7 +1358,7 @@ export declare class Page extends EventEmitter {
      * objects, emulates CSS media features on the page. Each media feature object
      * must have the following properties:
      * @example
-     * ```js
+     * ```ts
      * await page.emulateMediaFeatures([
      * { name: 'prefers-color-scheme', value: 'dark' },
      * ]);
@@ -1436,7 +1418,7 @@ export declare class Page extends EventEmitter {
      * If no arguments set, clears idle state emulation.
      *
      * @example
-     * ```js
+     * ```ts
      * // set idle emulation
      * await page.emulateIdleState({isUserActive: true, isScreenUnlocked: false});
      *
@@ -1457,7 +1439,7 @@ export declare class Page extends EventEmitter {
      * Simulates the given vision deficiency on the page.
      *
      * @example
-     * ```js
+     * ```ts
      * const puppeteer = require('puppeteer');
      *
      * (async () => {
@@ -1489,7 +1471,7 @@ export declare class Page extends EventEmitter {
      * In the case of multiple pages in a single browser, each page can have its
      * own viewport size.
      * @example
-     * ```js
+     * ```ts
      * const page = await browser.newPage();
      * await page.setViewport({
      * width: 640,
@@ -1551,7 +1533,7 @@ export declare class Page extends EventEmitter {
      *
      * @example
      *
-     * ```js
+     * ```ts
      * const result = await frame.evaluate(() => {
      *   return Promise.resolve(8 * 7);
      * });
@@ -1562,15 +1544,15 @@ export declare class Page extends EventEmitter {
      * recommended as they are easier to debug and use with TypeScript):
      *
      * @example
-     * ```
+     * ```ts
      * const aHandle = await page.evaluate('1 + 2');
      * ```
      *
      * To get the best TypeScript experience, you should pass in as the
      * generic the type of `pageFunction`:
      *
-     * ```
-     * const aHandle = await page.evaluate<() => number>(() => 2);
+     * ```ts
+     * const aHandle = await page.evaluate(() => 2);
      * ```
      *
      * @example
@@ -1578,7 +1560,7 @@ export declare class Page extends EventEmitter {
      * {@link ElementHandle} instances (including {@link JSHandle}s) can be passed
      * as arguments to the `pageFunction`:
      *
-     * ```
+     * ```ts
      * const bodyHandle = await page.$('body');
      * const html = await page.evaluate(body => body.innerHTML, bodyHandle);
      * await bodyHandle.dispose();
@@ -1589,7 +1571,7 @@ export declare class Page extends EventEmitter {
      *
      * @returns the return value of `pageFunction`.
      */
-    evaluate<T extends EvaluateFn>(pageFunction: T, ...args: SerializableOrJSHandle[]): Promise<UnwrapPromiseLike<EvaluateFnReturnType<T>>>;
+    evaluate<Params extends unknown[], Func extends EvaluateFunc<Params> = EvaluateFunc<Params>>(pageFunction: Func | string, ...args: Params): Promise<Awaited<ReturnType<Func>>>;
     /**
      * Adds a function which would be invoked in one of the following scenarios:
      *
@@ -1605,7 +1587,7 @@ export declare class Page extends EventEmitter {
      * @param args - Arguments to pass to `pageFunction`
      * @example
      * An example of overriding the navigator.languages property before the page loads:
-     * ```js
+     * ```ts
      * // preload.js
      *
      * // overwrite the `languages` property to use a custom getter
@@ -1621,7 +1603,7 @@ export declare class Page extends EventEmitter {
      * await page.evaluateOnNewDocument(preloadFile);
      * ```
      */
-    evaluateOnNewDocument(pageFunction: Function | string, ...args: unknown[]): Promise<void>;
+    evaluateOnNewDocument<Params extends unknown[], Func extends (...args: Params) => unknown = (...args: Params) => unknown>(pageFunction: Func | string, ...args: Params): Promise<void>;
     /**
      * Toggles ignoring cache for each request based on the enabled state. By
      * default, caching is enabled.
@@ -1646,7 +1628,7 @@ export declare class Page extends EventEmitter {
      *   applicable to `png` images.
      *
      * - `fullPage` : When true, takes a screenshot of the full
-     *   scrollable page. Defaults to `false`
+     *   scrollable page. Defaults to `false`.
      *
      * - `clip` : An object which specifies clipping region of the page.
      *   Should have the following fields:<br/>
@@ -1656,11 +1638,21 @@ export declare class Page extends EventEmitter {
      *  - `height` : height of clipping area.
      *
      * - `omitBackground` : Hides default white background and allows
-     *   capturing screenshots with transparency. Defaults to `false`
+     *   capturing screenshots with transparency. Defaults to `false`.
      *
      * - `encoding` : The encoding of the image, can be either base64 or
      *   binary. Defaults to `binary`.
      *
+     * - `captureBeyondViewport` : When true, captures screenshot
+     *   {@link https://chromedevtools.github.io/devtools-protocol/tot/Page/#method-captureScreenshot
+     *   | beyond the viewport}. When false, falls back to old behaviour,
+     *   and cuts the screenshot by the viewport size. Defaults to `true`.
+     *
+     * - `fromSurface` : When true, captures screenshot
+     *   {@link https://chromedevtools.github.io/devtools-protocol/tot/Page/#method-captureScreenshot
+     *   | from the surface rather than the view}. When false, works only in
+     *   headful mode and ignores page viewport (but not browser window's
+     *   bounds). Defaults to `true`.
      *
      * NOTE: Screenshots take at least 1/6 second on OS X. See
      * {@link https://crbug.com/741689} for discussion.
@@ -1668,7 +1660,6 @@ export declare class Page extends EventEmitter {
      * the value of `encoding`) with captured screenshot.
      */
     screenshot(options?: ScreenshotOptions): Promise<Buffer | string>;
-    private _screenshotTask;
     /**
      * Generates a PDF of the page with the `print` CSS media type.
      * @remarks
@@ -1717,7 +1708,7 @@ export declare class Page extends EventEmitter {
      * there's a separate `page.waitForNavigation()` promise to be resolved, you
      * may end up with a race condition that yields unexpected results. The
      * correct pattern for click and wait for navigation is the following:
-     * ```js
+     * ```ts
      * const [response] = await Promise.all([
      * page.waitForNavigation(waitOptions),
      * page.click(selector, clickOptions),
@@ -1771,7 +1762,7 @@ export declare class Page extends EventEmitter {
      * throws an error.
      *
      * @example
-     * ```js
+     * ```ts
      * page.select('select#colors', 'blue'); // single selection
      * page.select('select#colors', 'red', 'green', 'blue'); // multiple selections
      * ```
@@ -1806,7 +1797,7 @@ export declare class Page extends EventEmitter {
      *
      * To press a special key, like `Control` or `ArrowDown`, use {@link Keyboard.press}.
      * @example
-     * ```
+     * ```ts
      * await page.type('#mytextarea', 'Hello');
      * // Types instantly
      * await page.type('#mytextarea', 'World', { delay: 100 });
@@ -1825,37 +1816,6 @@ export declare class Page extends EventEmitter {
     type(selector: string, text: string, options?: {
         delay: number;
     }): Promise<void>;
-    /**
-     * @remarks
-     *
-     * This method behaves differently depending on the first parameter. If it's a
-     * `string`, it will be treated as a `selector` or `xpath` (if the string
-     * starts with `//`). This method then is a shortcut for
-     * {@link Page.waitForSelector} or {@link Page.waitForXPath}.
-     *
-     * If the first argument is a function this method is a shortcut for
-     * {@link Page.waitForFunction}.
-     *
-     * If the first argument is a `number`, it's treated as a timeout in
-     * milliseconds and the method returns a promise which resolves after the
-     * timeout.
-     *
-     * @param selectorOrFunctionOrTimeout - a selector, predicate or timeout to
-     * wait for.
-     * @param options - optional waiting parameters.
-     * @param args - arguments to pass to `pageFunction`.
-     *
-     * @deprecated Don't use this method directly. Instead use the more explicit
-     * methods available: {@link Page.waitForSelector},
-     * {@link Page.waitForXPath}, {@link Page.waitForFunction} or
-     * {@link Page.waitForTimeout}.
-     */
-    waitFor(selectorOrFunctionOrTimeout: string | number | Function, options?: {
-        visible?: boolean;
-        hidden?: boolean;
-        timeout?: number;
-        polling?: string | number;
-    }, ...args: SerializableOrJSHandle[]): Promise<JSHandle>;
     /**
      * Causes your script to wait for the given number of milliseconds.
      *
@@ -1869,7 +1829,7 @@ export declare class Page extends EventEmitter {
      *
      * Wait for 1 second:
      *
-     * ```
+     * ```ts
      * await page.waitForTimeout(1000);
      * ```
      *
@@ -1883,7 +1843,7 @@ export declare class Page extends EventEmitter {
      * function will throw.
      *
      * This method works across navigations:
-     * ```js
+     * ```ts
      * const puppeteer = require('puppeteer');
      * (async () => {
      * const browser = await puppeteer.launch();
@@ -1924,11 +1884,7 @@ export declare class Page extends EventEmitter {
      * (30 seconds). Pass `0` to disable timeout. The default value can be changed
      * by using the {@link Page.setDefaultTimeout} method.
      */
-    waitForSelector(selector: string, options?: {
-        visible?: boolean;
-        hidden?: boolean;
-        timeout?: number;
-    }): Promise<ElementHandle | null>;
+    waitForSelector<Selector extends string>(selector: Selector, options?: Exclude<WaitForSelectorOptions, 'root'>): Promise<ElementHandle<NodeFor<Selector>> | null>;
     /**
      * Wait for the `xpath` to appear in page. If at the moment of calling the
      * method the `xpath` already exists, the method will return immediately. If
@@ -1936,7 +1892,7 @@ export declare class Page extends EventEmitter {
      * function will throw.
      *
      * This method works across navigation
-     * ```js
+     * ```ts
      * const puppeteer = require('puppeteer');
      * (async () => {
      * const browser = await puppeteer.launch();
@@ -1981,11 +1937,14 @@ export declare class Page extends EventEmitter {
         visible?: boolean;
         hidden?: boolean;
         timeout?: number;
-    }): Promise<ElementHandle | null>;
+    }): Promise<ElementHandle<Node> | null>;
     /**
-     * The `waitForFunction` can be used to observe viewport size change:
+     * Waits for a function to finish evaluating in the page's context.
      *
-     * ```
+     * @example
+     * The {@link Page.waitForFunction} can be used to observe viewport size change:
+     *
+     * ```ts
      * const puppeteer = require('puppeteer');
      * (async () => {
      * const browser = await puppeteer.launch();
@@ -1996,8 +1955,11 @@ export declare class Page extends EventEmitter {
      * await browser.close();
      * })();
      * ```
-     * To pass arguments from node.js to the predicate of `page.waitForFunction` function:
-     * ```
+     *
+     * @example
+     * To pass arguments from node.js to the predicate of
+     * {@link Page.waitForFunction} function:
+     * ```ts
      * const selector = '.foo';
      * await page.waitForFunction(
      * (selector) => !!document.querySelector(selector),
@@ -2005,8 +1967,10 @@ export declare class Page extends EventEmitter {
      * selector
      * );
      * ```
-     * The predicate of `page.waitForFunction` can be asynchronous too:
-     * ```
+     *
+     * @example
+     * The predicate of {@link Page.waitForFunction} can be asynchronous too:
+     * ```ts
      * const username = 'github-username';
      * await page.waitForFunction(
      * async (username) => {
@@ -2025,32 +1989,27 @@ export declare class Page extends EventEmitter {
      * username
      * );
      * ```
+     *
      * @param pageFunction - Function to be evaluated in browser context
      * @param options - Optional waiting parameters
-     * @param args -  Arguments to pass to `pageFunction`
-     * @returns Promise which resolves when the `pageFunction` returns a truthy
-     * value. It resolves to a JSHandle of the truthy value.
-     *
-     * The optional waiting parameter can be:
-     *
-     * - `Polling`: An interval at which the `pageFunction` is executed, defaults to
-     *   `raf`. If `polling` is a number, then it is treated as an interval in
+     * - `polling` - An interval at which the `pageFunction` is executed, defaults
+     *   to `raf`. If `polling` is a number, then it is treated as an interval in
      *   milliseconds at which the function would be executed. If polling is a
-     *   string, then it can be one of the following values:<br/>
-     *    - `raf`: to constantly execute `pageFunction` in `requestAnimationFrame`
-     *      callback. This is the tightest polling mode which is suitable to
-     *      observe styling changes.<br/>
-     *    - `mutation`: to execute pageFunction on every DOM mutation.
-     *
-     * - `timeout`: maximum time to wait for in milliseconds. Defaults to `30000`
-     * (30 seconds). Pass `0` to disable timeout. The default value can be changed
-     * by using the
-     * {@link Page.setDefaultTimeout | page.setDefaultTimeout(timeout)} method.
-     *
+     *   string, then it can be one of the following values:
+     *    - `raf` - to constantly execute `pageFunction` in
+     *      `requestAnimationFrame` callback. This is the tightest polling mode
+     *      which is suitable to observe styling changes.
+     *    - `mutation`-  to execute pageFunction on every DOM mutation.
+     * - `timeout` - maximum time to wait for in milliseconds. Defaults to `30000`
+     *   (30 seconds). Pass `0` to disable timeout. The default value can be
+     *   changed by using the {@link Page.setDefaultTimeout} method.
+     * @param args -  Arguments to pass to `pageFunction`
+     * @returns A `Promise` which resolves to a JSHandle/ElementHandle of the the
+     * `pageFunction`'s return value.
      */
-    waitForFunction(pageFunction: Function | string, options?: {
+    waitForFunction<Params extends unknown[], Func extends EvaluateFunc<Params> = EvaluateFunc<Params>>(pageFunction: Func | string, options?: {
         timeout?: number;
         polling?: string | number;
-    }, ...args: SerializableOrJSHandle[]): Promise<JSHandle>;
+    }, ...args: Params): Promise<HandleFor<Awaited<ReturnType<Func>>>>;
 }
 //# sourceMappingURL=Page.d.ts.map