puppeteer
Version:
A high-level API to control headless Chrome over the DevTools Protocol
1,623 lines (1,521 loc) • 296 kB
TypeScript
/// <reference types="node" />
import type { ChildProcess } from 'child_process';
import type { ParseSelector } from 'typed-query-selector/parser.js';
import { PassThrough } from 'stream';
import { Protocol } from 'devtools-protocol';
import type { ProtocolMapping } from 'devtools-protocol/types/protocol-mapping.js';
import { Session } from 'chromium-bidi/lib/cjs/protocol/protocol.js';
/**
* The Accessibility class provides methods for inspecting the browser's
* accessibility tree. The accessibility tree is used by assistive technology
* such as {@link https://en.wikipedia.org/wiki/Screen_reader | screen readers} or
* {@link https://en.wikipedia.org/wiki/Switch_access | switches}.
*
* @remarks
*
* Accessibility is a very platform-specific thing. On different platforms,
* there are different screen readers that might have wildly different output.
*
* Blink - Chrome's rendering engine - has a concept of "accessibility tree",
* which is then translated into different platform-specific APIs. Accessibility
* namespace gives users access to the Blink Accessibility Tree.
*
* Most of the accessibility tree gets filtered out when converting from Blink
* AX Tree to Platform-specific AX-Tree or by assistive technologies themselves.
* By default, Puppeteer tries to approximate this filtering, exposing only
* the "interesting" nodes of the tree.
*
* @public
*/
export declare class Accessibility {
#private;
/* Excluded from this release type: __constructor */
/**
* Captures the current state of the accessibility tree.
* The returned object represents the root accessible node of the page.
*
* @remarks
*
* **NOTE** The Chrome accessibility tree contains nodes that go unused on
* most platforms and by most screen readers. Puppeteer will discard them as
* well for an easier to process tree, unless `interestingOnly` is set to
* `false`.
*
* @example
* An example of dumping the entire accessibility tree:
*
* ```ts
* const snapshot = await page.accessibility.snapshot();
* console.log(snapshot);
* ```
*
* @example
* An example of logging the focused node's name:
*
* ```ts
* const snapshot = await page.accessibility.snapshot();
* const node = findFocusedNode(snapshot);
* console.log(node && node.name);
*
* function findFocusedNode(node) {
* if (node.focused) return node;
* for (const child of node.children || []) {
* const foundNode = findFocusedNode(child);
* return foundNode;
* }
* return null;
* }
* ```
*
* @returns An AXNode object representing the snapshot.
*/
snapshot(options?: SnapshotOptions): Promise<SerializedAXNode | null>;
private serializeTree;
private collectInterestingNodes;
}
/* Excluded from this release type: Action */
/**
* @public
*/
export declare interface ActionOptions {
/**
* A signal to abort the locator action.
*/
signal?: AbortSignal;
}
/**
* @public
*/
export declare type ActionResult = 'continue' | 'abort' | 'respond';
/* Excluded from this release type: addPageBinding */
/* Excluded from this release type: ARIAQueryHandler */
/* Excluded from this release type: assert */
/* Excluded from this release type: AsyncDisposableStack */
/* Excluded from this release type: asyncDisposeSymbol */
/* Excluded from this release type: AsyncIterableUtil */
/**
* @public
*/
export declare interface AutofillData {
creditCard: {
number: string;
name: string;
expiryMonth: string;
expiryYear: string;
cvc: string;
};
}
/**
* @public
*/
export declare type Awaitable<T> = T | PromiseLike<T>;
/**
* @public
*/
export declare type AwaitableIterable<T> = Iterable<T> | AsyncIterable<T>;
/* Excluded from this release type: AwaitableIterator */
/**
* @public
*/
export declare type AwaitablePredicate<T> = (value: T) => Awaitable<boolean>;
/**
* @public
*/
export declare type AwaitedLocator<T> = T extends Locator<infer S> ? S : never;
/* Excluded from this release type: Binding */
/* Excluded from this release type: BindingPayload */
/* Excluded from this release type: bindIsolatedHandle */
/**
* @public
*/
export declare interface BoundingBox extends Point {
/**
* the width of the element in pixels.
*/
width: number;
/**
* the height of the element in pixels.
*/
height: number;
}
/**
* @public
*/
export declare interface BoxModel {
content: Quad;
padding: Quad;
border: Quad;
margin: Quad;
width: number;
height: number;
}
/**
* {@link Browser} represents a browser instance that is either:
*
* - connected to via {@link Puppeteer.connect} or
* - launched by {@link PuppeteerNode.launch}.
*
* {@link Browser} {@link EventEmitter.emit | emits} various events which are
* documented in the {@link BrowserEvent} enum.
*
* @example Using a {@link Browser} to create a {@link Page}:
*
* ```ts
* import puppeteer from 'puppeteer';
*
* const browser = await puppeteer.launch();
* const page = await browser.newPage();
* await page.goto('https://example.com');
* await browser.close();
* ```
*
* @example Disconnecting from and reconnecting to a {@link Browser}:
*
* ```ts
* import puppeteer from 'puppeteer';
*
* const browser = await puppeteer.launch();
* // Store the endpoint to be able to reconnect to the browser.
* const browserWSEndpoint = browser.wsEndpoint();
* // Disconnect puppeteer from the browser.
* await browser.disconnect();
*
* // Use the endpoint to reestablish a connection
* const browser2 = await puppeteer.connect({browserWSEndpoint});
* // Close the browser.
* await browser2.close();
* ```
*
* @public
*/
export declare abstract class Browser extends EventEmitter<BrowserEvents> {
/* Excluded from this release type: __constructor */
/**
* Gets the associated
* {@link https://nodejs.org/api/child_process.html#class-childprocess | ChildProcess}.
*
* @returns `null` if this instance was connected to via
* {@link Puppeteer.connect}.
*/
abstract process(): ChildProcess | null;
/**
* Creates a new {@link BrowserContext | browser context}.
*
* This won't share cookies/cache with other {@link BrowserContext | browser contexts}.
*
* @example
*
* ```ts
* import puppeteer from 'puppeteer';
*
* const browser = await puppeteer.launch();
* // Create a new browser context.
* const context = await browser.createBrowserContext();
* // Create a new page in a pristine context.
* const page = await context.newPage();
* // Do stuff
* await page.goto('https://example.com');
* ```
*/
abstract createBrowserContext(options?: BrowserContextOptions): Promise<BrowserContext>;
/**
* Gets a list of open {@link BrowserContext | browser contexts}.
*
* In a newly-created {@link Browser | browser}, this will return a single
* instance of {@link BrowserContext}.
*/
abstract browserContexts(): BrowserContext[];
/**
* Gets the default {@link BrowserContext | browser context}.
*
* @remarks The default {@link BrowserContext | browser context} cannot be
* closed.
*/
abstract defaultBrowserContext(): BrowserContext;
/**
* Gets the WebSocket URL to connect to this {@link Browser | browser}.
*
* This is usually used with {@link Puppeteer.connect}.
*
* You can find the debugger URL (`webSocketDebuggerUrl`) from
* `http://HOST:PORT/json/version`.
*
* See {@link https://chromedevtools.github.io/devtools-protocol/#how-do-i-access-the-browser-target | browser endpoint}
* for more information.
*
* @remarks The format is always `ws://HOST:PORT/devtools/browser/<id>`.
*/
abstract wsEndpoint(): string;
/**
* Creates a new {@link Page | page} in the
* {@link Browser.defaultBrowserContext | default browser context}.
*/
abstract newPage(): Promise<Page>;
/**
* Gets all active {@link Target | targets}.
*
* In case of multiple {@link BrowserContext | browser contexts}, this returns
* all {@link Target | targets} in all
* {@link BrowserContext | browser contexts}.
*/
abstract targets(): Target[];
/**
* Gets the {@link Target | target} associated with the
* {@link Browser.defaultBrowserContext | default browser context}).
*/
abstract target(): Target;
/**
* Waits until a {@link Target | target} matching the given `predicate`
* appears and returns it.
*
* This will look all open {@link BrowserContext | browser contexts}.
*
* @example Finding a target for a page opened via `window.open`:
*
* ```ts
* await page.evaluate(() => window.open('https://www.example.com/'));
* const newWindowTarget = await browser.waitForTarget(
* target => target.url() === 'https://www.example.com/',
* );
* ```
*/
waitForTarget(predicate: (x: Target) => boolean | Promise<boolean>, options?: WaitForTargetOptions): Promise<Target>;
/**
* Gets a list of all open {@link Page | pages} inside this {@link Browser}.
*
* If there are multiple {@link BrowserContext | browser contexts}, this
* returns all {@link Page | pages} in all
* {@link BrowserContext | browser contexts}.
*
* @remarks Non-visible {@link Page | pages}, such as `"background_page"`,
* will not be listed here. You can find them using {@link Target.page}.
*/
pages(): Promise<Page[]>;
/**
* Gets a string representing this {@link Browser | browser's} name and
* version.
*
* For headless browser, this is similar to `"HeadlessChrome/61.0.3153.0"`. For
* non-headless or new-headless, this is similar to `"Chrome/61.0.3153.0"`. For
* Firefox, it is similar to `"Firefox/116.0a1"`.
*
* The format of {@link Browser.version} might change with future releases of
* browsers.
*/
abstract version(): Promise<string>;
/**
* Gets this {@link Browser | browser's} original user agent.
*
* {@link Page | Pages} can override the user agent with
* {@link Page.setUserAgent}.
*
*/
abstract userAgent(): Promise<string>;
/**
* Closes this {@link Browser | browser} and all associated
* {@link Page | pages}.
*/
abstract close(): Promise<void>;
/**
* Disconnects Puppeteer from this {@link Browser | browser}, but leaves the
* process running.
*/
abstract disconnect(): Promise<void>;
/**
* Returns all cookies in the default {@link BrowserContext}.
*
* @remarks
*
* Shortcut for
* {@link BrowserContext.cookies | browser.defaultBrowserContext().cookies()}.
*/
cookies(): Promise<Cookie[]>;
/**
* Sets cookies in the default {@link BrowserContext}.
*
* @remarks
*
* Shortcut for
* {@link BrowserContext.setCookie | browser.defaultBrowserContext().setCookie()}.
*/
setCookie(...cookies: Cookie[]): Promise<void>;
/**
* Removes cookies from the default {@link BrowserContext}.
*
* @remarks
*
* Shortcut for
* {@link BrowserContext.deleteCookie | browser.defaultBrowserContext().deleteCookie()}.
*/
deleteCookie(...cookies: Cookie[]): Promise<void>;
/**
* Whether Puppeteer is connected to this {@link Browser | browser}.
*
* @deprecated Use {@link Browser | Browser.connected}.
*/
isConnected(): boolean;
/**
* Whether Puppeteer is connected to this {@link Browser | browser}.
*/
abstract get connected(): boolean;
/* Excluded from this release type: [disposeSymbol] */
/* Excluded from this release type: [asyncDisposeSymbol] */
/* Excluded from this release type: protocol */
/**
* Get debug information from Puppeteer.
*
* @remarks
*
* Currently, includes pending protocol calls. In the future, we might add more info.
*
* @public
* @experimental
*/
abstract get debugInfo(): DebugInfo;
}
/* Excluded from this release type: BrowserCloseCallback */
/**
* {@link BrowserContext} represents individual user contexts within a
* {@link Browser | browser}.
*
* When a {@link Browser | browser} is launched, it has at least one default
* {@link BrowserContext | browser context}. Others can be created
* using {@link Browser.createBrowserContext}. Each context has isolated storage
* (cookies/localStorage/etc.)
*
* {@link BrowserContext} {@link EventEmitter | emits} various events which are
* documented in the {@link BrowserContextEvent} enum.
*
* If a {@link Page | page} opens another {@link Page | page}, e.g. using
* `window.open`, the popup will belong to the parent {@link Page.browserContext
* | page's browser context}.
*
* @example Creating a new {@link BrowserContext | browser context}:
*
* ```ts
* // Create a new browser context
* const context = await browser.createBrowserContext();
* // Create a new page inside context.
* const page = await context.newPage();
* // ... do stuff with page ...
* await page.goto('https://example.com');
* // Dispose context once it's no longer needed.
* await context.close();
* ```
*
* @remarks
*
* In Chrome all non-default contexts are incognito,
* and {@link Browser.defaultBrowserContext | default browser context}
* might be incognito if you provide the `--incognito` argument when launching
* the browser.
*
* @public
*/
export declare abstract class BrowserContext extends EventEmitter<BrowserContextEvents> {
#private;
/* Excluded from this release type: __constructor */
/**
* Gets all active {@link Target | targets} inside this
* {@link BrowserContext | browser context}.
*/
abstract targets(): Target[];
/* Excluded from this release type: startScreenshot */
/* Excluded from this release type: waitForScreenshotOperations */
/**
* Waits until a {@link Target | target} matching the given `predicate`
* appears and returns it.
*
* This will look all open {@link BrowserContext | browser contexts}.
*
* @example Finding a target for a page opened via `window.open`:
*
* ```ts
* await page.evaluate(() => window.open('https://www.example.com/'));
* const newWindowTarget = await browserContext.waitForTarget(
* target => target.url() === 'https://www.example.com/',
* );
* ```
*/
waitForTarget(predicate: (x: Target) => boolean | Promise<boolean>, options?: WaitForTargetOptions): Promise<Target>;
/**
* Gets a list of all open {@link Page | pages} inside this
* {@link BrowserContext | browser context}.
*
* @remarks Non-visible {@link Page | pages}, such as `"background_page"`,
* will not be listed here. You can find them using {@link Target.page}.
*/
abstract pages(): Promise<Page[]>;
/**
* Grants this {@link BrowserContext | browser context} the given
* `permissions` within the given `origin`.
*
* @example Overriding permissions in the
* {@link Browser.defaultBrowserContext | default browser context}:
*
* ```ts
* const context = browser.defaultBrowserContext();
* await context.overridePermissions('https://html5demos.com', [
* 'geolocation',
* ]);
* ```
*
* @param origin - The origin to grant permissions to, e.g.
* "https://example.com".
* @param permissions - An array of permissions to grant. All permissions that
* are not listed here will be automatically denied.
*/
abstract overridePermissions(origin: string, permissions: Permission[]): Promise<void>;
/**
* Clears all permission overrides for this
* {@link BrowserContext | browser context}.
*
* @example Clearing overridden permissions in the
* {@link Browser.defaultBrowserContext | default browser context}:
*
* ```ts
* const context = browser.defaultBrowserContext();
* context.overridePermissions('https://example.com', ['clipboard-read']);
* // do stuff ..
* context.clearPermissionOverrides();
* ```
*/
abstract clearPermissionOverrides(): Promise<void>;
/**
* Creates a new {@link Page | page} in this
* {@link BrowserContext | browser context}.
*/
abstract newPage(): Promise<Page>;
/**
* Gets the {@link Browser | browser} associated with this
* {@link BrowserContext | browser context}.
*/
abstract browser(): Browser;
/**
* Closes this {@link BrowserContext | browser context} and all associated
* {@link Page | pages}.
*
* @remarks The
* {@link Browser.defaultBrowserContext | default browser context} cannot be
* closed.
*/
abstract close(): Promise<void>;
/**
* Gets all cookies in the browser context.
*/
abstract cookies(): Promise<Cookie[]>;
/**
* Sets a cookie in the browser context.
*/
abstract setCookie(...cookies: CookieData[]): Promise<void>;
/**
* Removes cookie in the browser context
* @param cookies - {@link Cookie | cookie} to remove
*/
deleteCookie(...cookies: Cookie[]): Promise<void>;
/**
* Whether this {@link BrowserContext | browser context} is closed.
*/
get closed(): boolean;
/**
* Identifier for this {@link BrowserContext | browser context}.
*/
get id(): string | undefined;
/* Excluded from this release type: [disposeSymbol] */
/* Excluded from this release type: [asyncDisposeSymbol] */
}
/**
* @public
*/
export declare const enum BrowserContextEvent {
/**
* Emitted when the url of a target inside the browser context changes.
* Contains a {@link Target} instance.
*/
TargetChanged = "targetchanged",
/**
* Emitted when a target is created within the browser context, for example
* when a new page is opened by
* {@link https://developer.mozilla.org/en-US/docs/Web/API/Window/open | window.open}
* or by {@link BrowserContext.newPage | browserContext.newPage}
*
* Contains a {@link Target} instance.
*/
TargetCreated = "targetcreated",
/**
* Emitted when a target is destroyed within the browser context, for example
* when a page is closed. Contains a {@link Target} instance.
*/
TargetDestroyed = "targetdestroyed"
}
/**
* @public
*/
export declare interface BrowserContextEvents extends Record<EventType, unknown> {
[BrowserContextEvent.TargetChanged]: Target;
[BrowserContextEvent.TargetCreated]: Target;
[BrowserContextEvent.TargetDestroyed]: Target;
}
/**
* @public
*/
export declare interface BrowserContextOptions {
/**
* Proxy server with optional port to use for all requests.
* Username and password can be set in `Page.authenticate`.
*/
proxyServer?: string;
/**
* Bypass the proxy for the given list of hosts.
*/
proxyBypassList?: string[];
/**
* Behavior definition for when downloading a file.
*
* @remarks
* If not set, the default behavior will be used.
*/
downloadBehavior?: DownloadBehavior;
}
/**
* All the events a {@link Browser | browser instance} may emit.
*
* @public
*/
export declare const enum BrowserEvent {
/**
* Emitted when Puppeteer gets disconnected from the browser instance. This
* might happen because either:
*
* - The browser closes/crashes or
* - {@link Browser.disconnect} was called.
*/
Disconnected = "disconnected",
/**
* Emitted when the URL of a target changes. Contains a {@link Target}
* instance.
*
* @remarks Note that this includes target changes in all browser
* contexts.
*/
TargetChanged = "targetchanged",
/**
* Emitted when a target is created, for example when a new page is opened by
* {@link https://developer.mozilla.org/en-US/docs/Web/API/Window/open | window.open}
* or by {@link Browser.newPage | browser.newPage}
*
* Contains a {@link Target} instance.
*
* @remarks Note that this includes target creations in all browser
* contexts.
*/
TargetCreated = "targetcreated",
/**
* Emitted when a target is destroyed, for example when a page is closed.
* Contains a {@link Target} instance.
*
* @remarks Note that this includes target destructions in all browser
* contexts.
*/
TargetDestroyed = "targetdestroyed",
/* Excluded from this release type: TargetDiscovered */
}
/**
* @public
*/
export declare interface BrowserEvents extends Record<EventType, unknown> {
[BrowserEvent.Disconnected]: undefined;
[BrowserEvent.TargetCreated]: Target;
[BrowserEvent.TargetDestroyed]: Target;
[BrowserEvent.TargetChanged]: Target;
/* Excluded from this release type: targetdiscovered */
}
/**
* Describes a launcher - a class that is able to create and launch a browser instance.
*
* @public
*/
export declare abstract class BrowserLauncher {
#private;
/* Excluded from this release type: puppeteer */
/* Excluded from this release type: __constructor */
get browser(): SupportedBrowser;
launch(options?: LaunchOptions): Promise<Browser>;
abstract executablePath(channel?: ChromeReleaseChannel, validatePath?: boolean): string;
abstract defaultArgs(object: LaunchOptions): string[];
/* Excluded from this release type: computeLaunchArguments */
/* Excluded from this release type: cleanUserDataDir */
/* Excluded from this release type: closeBrowser */
/* Excluded from this release type: waitForPageTarget */
/* Excluded from this release type: createCdpSocketConnection */
/* Excluded from this release type: createCdpPipeConnection */
/* Excluded from this release type: createBiDiOverCdpBrowser */
/* Excluded from this release type: createBiDiBrowser */
/* Excluded from this release type: getProfilePath */
/* Excluded from this release type: resolveExecutablePath */
}
/* Excluded from this release type: BrowserWebSocketTransport */
/* Excluded from this release type: Callback */
/* Excluded from this release type: CallbackRegistry */
/* Excluded from this release type: CDP_BINDING_PREFIX */
/* Excluded from this release type: CdpBrowser */
/* Excluded from this release type: CdpBrowserContext */
/* Excluded from this release type: CdpCDPSession */
/* Excluded from this release type: CdpDialog */
/* Excluded from this release type: CdpElementHandle */
/**
* @public
*/
export declare type CDPEvents = {
[Property in keyof ProtocolMapping.Events]: ProtocolMapping.Events[Property][0];
};
/* Excluded from this release type: CdpFrame */
/* Excluded from this release type: CdpHTTPRequest */
/* Excluded from this release type: CdpHTTPResponse */
/* Excluded from this release type: CdpJSHandle */
/* Excluded from this release type: CdpKeyboard */
/* Excluded from this release type: CdpMouse */
/* Excluded from this release type: CdpPage */
/* Excluded from this release type: CdpPreloadScript */
/**
* The `CDPSession` instances are used to talk raw Chrome Devtools Protocol.
*
* @remarks
*
* Protocol methods can be called with {@link CDPSession.send} method and protocol
* events can be subscribed to with `CDPSession.on` method.
*
* Useful links: {@link https://chromedevtools.github.io/devtools-protocol/ | DevTools Protocol Viewer}
* and {@link https://github.com/aslushnikov/getting-started-with-cdp/blob/HEAD/README.md | Getting Started with DevTools Protocol}.
*
* @example
*
* ```ts
* const client = await page.createCDPSession();
* await client.send('Animation.enable');
* client.on('Animation.animationCreated', () =>
* console.log('Animation created!'),
* );
* const response = await client.send('Animation.getPlaybackRate');
* console.log('playback rate is ' + response.playbackRate);
* await client.send('Animation.setPlaybackRate', {
* playbackRate: response.playbackRate / 2,
* });
* ```
*
* @public
*/
export declare abstract class CDPSession extends EventEmitter<CDPSessionEvents> {
/* Excluded from this release type: __constructor */
abstract connection(): Connection | undefined;
/* Excluded from this release type: parentSession */
abstract send<T extends keyof ProtocolMapping.Commands>(method: T, params?: ProtocolMapping.Commands[T]['paramsType'][0], options?: CommandOptions): Promise<ProtocolMapping.Commands[T]['returnType']>;
/**
* Detaches the cdpSession from the target. Once detached, the cdpSession object
* won't emit any events and can't be used to send messages.
*/
abstract detach(): Promise<void>;
/**
* Returns the session's id.
*/
abstract id(): string;
}
/**
* Events that the CDPSession class emits.
*
* @public
*/
export declare namespace CDPSessionEvent {
/* Excluded from this release type: Disconnected */
/* Excluded from this release type: Swapped */
/* Excluded from this release type: Ready */
const SessionAttached: "sessionattached";
const SessionDetached: "sessiondetached";
}
/**
* @public
*/
export declare interface CDPSessionEvents extends CDPEvents, Record<EventType, unknown> {
/* Excluded from this release type: [CDPSessionEvent.Disconnected] */
/* Excluded from this release type: [CDPSessionEvent.Swapped] */
/* Excluded from this release type: [CDPSessionEvent.Ready] */
[CDPSessionEvent.SessionAttached]: CDPSession;
[CDPSessionEvent.SessionDetached]: CDPSession;
}
/* Excluded from this release type: CdpTarget */
/* Excluded from this release type: CdpTouchHandle */
/* Excluded from this release type: CdpTouchscreen */
/* Excluded from this release type: CdpWebWorker */
/**
* @public
*/
export declare interface ChromeHeadlessShellSettings {
/**
* Tells Puppeteer to not download the browser during installation.
*
* Can be overridden by `PUPPETEER_CHROME_HEADLESS_SHELL_SKIP_DOWNLOAD`
* or `PUPPETEER_SKIP_CHROME_HEADLESS_SHELL_DOWNLOAD`.
*
* @defaultValue false
*/
skipDownload?: boolean;
/**
* Specifies the URL prefix that is used to download the browser.
*
* Can be overridden by `PUPPETEER_CHROME_HEADLESS_SHELL_DOWNLOAD_BASE_URL`.
*
* @remarks
* This must include the protocol and may even need a path prefix.
* This must **not** include a trailing slash similar to the default.
*
* @defaultValue https://storage.googleapis.com/chrome-for-testing-public
*/
downloadBaseUrl?: string;
/**
* Specifies a certain version of the browser you'd like Puppeteer to use.
*
* Can be overridden by `PUPPETEER_CHROME_HEADLESS_SHELL_VERSION`.
*
* See {@link PuppeteerNode.launch | puppeteer.launch} on how executable path
* is inferred.
*
* @example 119.0.6045.105
* @defaultValue The pinned browser version supported by the current Puppeteer
* version.
*/
version?: string;
}
/* Excluded from this release type: ChromeLauncher */
/**
* @public
*/
export declare type ChromeReleaseChannel = 'chrome' | 'chrome-beta' | 'chrome-canary' | 'chrome-dev';
/**
* @public
*/
export declare interface ChromeSettings {
/**
* Tells Puppeteer to not download the browser during installation.
*
* Can be overridden by `PUPPETEER_CHROME_SKIP_DOWNLOAD`.
*
* @defaultValue false
*/
skipDownload?: boolean;
/**
* Specifies the URL prefix that is used to download the browser.
*
* Can be overridden by `PUPPETEER_CHROME_DOWNLOAD_BASE_URL`.
*
* @remarks
* This must include the protocol and may even need a path prefix.
* This must **not** include a trailing slash similar to the default.
*
* @defaultValue https://storage.googleapis.com/chrome-for-testing-public
*/
downloadBaseUrl?: string;
/**
* Specifies a certain version of the browser you'd like Puppeteer to use.
*
* Can be overridden by `PUPPETEER_CHROME_VERSION`
* or `PUPPETEER_SKIP_CHROME_DOWNLOAD`.
*
* See {@link PuppeteerNode.launch | puppeteer.launch} on how executable path
* is inferred.
*
* @example 119.0.6045.105
* @defaultValue The pinned browser version supported by the current Puppeteer
* version.
*/
version?: string;
}
/**
* @public
*/
export declare interface ClickOptions extends MouseClickOptions {
/**
* Offset for the clickable point relative to the top-left corner of the border box.
*/
offset?: Offset;
}
/* Excluded from this release type: ClientProvider */
/**
* @public
*/
export declare interface CommandOptions {
timeout: number;
}
/**
* @public
*/
export declare interface CommonEventEmitter<Events extends Record<EventType, unknown>> {
on<Key extends keyof Events>(type: Key, handler: Handler<Events[Key]>): this;
off<Key extends keyof Events>(type: Key, handler?: Handler<Events[Key]>): this;
emit<Key extends keyof Events>(type: Key, event: Events[Key]): boolean;
once<Key extends keyof Events>(type: Key, handler: Handler<Events[Key]>): this;
listenerCount(event: keyof Events): number;
removeAllListeners(event?: keyof Events): this;
}
/* Excluded from this release type: CommonPuppeteerSettings */
/* Excluded from this release type: ComplexPSelector */
/* Excluded from this release type: ComplexPSelectorList */
/* Excluded from this release type: CompoundPSelector */
/**
* Defines options to configure Puppeteer's behavior during installation and
* runtime.
*
* See individual properties for more information.
*
* @public
*/
export declare interface Configuration {
/**
* Defines the directory to be used by Puppeteer for caching.
*
* Can be overridden by `PUPPETEER_CACHE_DIR`.
*
* @defaultValue `path.join(os.homedir(), '.cache', 'puppeteer')`
*/
cacheDirectory?: string;
/**
* Specifies an executable path to be used in
* {@link PuppeteerNode.launch | puppeteer.launch}.
*
* Can be overridden by `PUPPETEER_EXECUTABLE_PATH`.
*
* @defaultValue **Auto-computed.**
*/
executablePath?: string;
/**
* Specifies which browser you'd like Puppeteer to use.
*
* Can be overridden by `PUPPETEER_BROWSER`.
*
* @defaultValue `chrome`
*/
defaultBrowser?: SupportedBrowser;
/**
* Defines the directory to be used by Puppeteer for creating temporary files.
*
* Can be overridden by `PUPPETEER_TMP_DIR`.
*
* @defaultValue `os.tmpdir()`
*/
temporaryDirectory?: string;
/**
* Tells Puppeteer to not download during installation.
*
* Can be overridden by `PUPPETEER_SKIP_DOWNLOAD`.
*/
skipDownload?: boolean;
/**
* Tells Puppeteer to log at the given level.
*
* @defaultValue `warn`
*/
logLevel?: 'silent' | 'error' | 'warn';
/**
* Defines experimental options for Puppeteer.
*/
experiments?: ExperimentsConfiguration;
chrome?: ChromeSettings;
['chrome-headless-shell']?: ChromeHeadlessShellSettings;
firefox?: FirefoxSettings;
}
/**
* @public
*/
export declare const
/**
* @public
*/
/**
* @public
*/
connect: (options: PuppeteerCore.ConnectOptions) => Promise<PuppeteerCore.Browser>;
/**
* @public
*/
declare const
/**
* @public
*/
/**
* @public
*/
connect_2: (options: Puppeteer_2.ConnectOptions) => Promise<Puppeteer_2.Browser>;
/**
* @public
*/
export declare class Connection extends EventEmitter<CDPSessionEvents> {
#private;
constructor(url: string, transport: ConnectionTransport, delay?: number, timeout?: number, rawErrors?: boolean);
static fromSession(session: CDPSession): Connection | undefined;
/* Excluded from this release type: delay */
get timeout(): number;
/* Excluded from this release type: _closed */
/* Excluded from this release type: _sessions */
/**
* @param sessionId - The session id
* @returns The current CDP session if it exists
*/
session(sessionId: string): CDPSession | null;
url(): string;
send<T extends keyof ProtocolMapping.Commands>(method: T, params?: ProtocolMapping.Commands[T]['paramsType'][0], options?: CommandOptions): Promise<ProtocolMapping.Commands[T]['returnType']>;
/* Excluded from this release type: _rawSend */
/* Excluded from this release type: closeBrowser */
/* Excluded from this release type: onMessage */
dispose(): void;
/* Excluded from this release type: isAutoAttached */
/* Excluded from this release type: _createSession */
/**
* @param targetInfo - The target info
* @returns The CDP session that is created
*/
createSession(targetInfo: Protocol.Target.TargetInfo): Promise<CDPSession>;
/* Excluded from this release type: getPendingProtocolErrors */
}
/**
* @license
* Copyright 2020 Google Inc.
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @public
*/
export declare interface ConnectionTransport {
send(message: string): void;
close(): void;
onmessage?: (message: string) => void;
onclose?: () => void;
}
/**
* Generic browser options that can be passed when launching any browser or when
* connecting to an existing browser instance.
* @public
*/
export declare interface ConnectOptions {
/**
* Whether to ignore HTTPS errors during navigation.
* @defaultValue `false`
*/
acceptInsecureCerts?: boolean;
/**
* Sets the viewport for each page.
*
* @defaultValue '\{width: 800, height: 600\}'
*/
defaultViewport?: Viewport | null;
/**
* Sets the download behavior for the context.
*/
downloadBehavior?: DownloadBehavior;
/**
* Slows down Puppeteer operations by the specified amount of milliseconds to
* aid debugging.
*/
slowMo?: number;
/**
* Callback to decide if Puppeteer should connect to a given target or not.
*/
targetFilter?: TargetFilterCallback;
/* Excluded from this release type: _isPageTarget */
/**
* @defaultValue Determined at run time:
*
* - Launching Chrome - 'cdp'.
*
* - Launching Firefox - 'webDriverBiDi'.
*
* - Connecting to a browser - 'cdp'.
*
* @public
*/
protocol?: ProtocolType;
/**
* Timeout setting for individual protocol (CDP) calls.
*
* @defaultValue `180_000`
*/
protocolTimeout?: number;
browserWSEndpoint?: string;
browserURL?: string;
transport?: ConnectionTransport;
/**
* Headers to use for the web socket connection.
* @remarks
* Only works in the Node.js environment.
*/
headers?: Record<string, string>;
/**
* WebDriver BiDi capabilities passed to BiDi `session.new`.
*
* @remarks
* Only works for `protocol="webDriverBiDi"` and {@link Puppeteer.connect}.
*/
capabilities?: SupportedWebDriverCapabilities;
}
/* Excluded from this release type: _connectToCdpBrowser */
/* Excluded from this release type: ConsoleAPICalledCallback */
/**
* ConsoleMessage objects are dispatched by page via the 'console' event.
* @public
*/
export declare class ConsoleMessage {
#private;
/* Excluded from this release type: __constructor */
/**
* The type of the console message.
*/
type(): ConsoleMessageType;
/**
* The text of the console message.
*/
text(): string;
/**
* An array of arguments passed to the console.
*/
args(): JSHandle[];
/**
* The location of the console message.
*/
location(): ConsoleMessageLocation;
/**
* The array of locations on the stack of the console message.
*/
stackTrace(): ConsoleMessageLocation[];
}
/**
* @public
*/
export declare interface ConsoleMessageLocation {
/**
* URL of the resource if known or `undefined` otherwise.
*/
url?: string;
/**
* 0-based line number in the resource if known or `undefined` otherwise.
*/
lineNumber?: number;
/**
* 0-based column number in the resource if known or `undefined` otherwise.
*/
columnNumber?: number;
}
/**
* The supported types for console messages.
* @public
*/
export declare type ConsoleMessageType = 'log' | 'debug' | 'info' | 'error' | 'warn' | 'dir' | 'dirxml' | 'table' | 'trace' | 'clear' | 'startGroup' | 'startGroupCollapsed' | 'endGroup' | 'assert' | 'profile' | 'profileEnd' | 'count' | 'timeEnd' | 'verbose';
/**
* @public
*/
export declare interface ContinueRequestOverrides {
/**
* If set, the request URL will change. This is not a redirect.
*/
url?: string;
method?: string;
postData?: string;
headers?: Record<string, string>;
}
export declare function convertCookiesPartitionKeyFromPuppeteerToCdp(partitionKey: CookiePartitionKey | string | undefined): Protocol.Network.CookiePartitionKey | undefined;
/**
* Represents a cookie object.
*
* @public
*/
export declare interface Cookie {
/**
* Cookie name.
*/
name: string;
/**
* Cookie value.
*/
value: string;
/**
* Cookie domain.
*/
domain: string;
/**
* Cookie path.
*/
path: string;
/**
* Cookie expiration date as the number of seconds since the UNIX epoch. Set to `-1` for
* session cookies
*/
expires: number;
/**
* Cookie size.
*/
size: number;
/**
* True if cookie is http-only.
*/
httpOnly: boolean;
/**
* True if cookie is secure.
*/
secure: boolean;
/**
* True in case of session cookie.
*/
session: boolean;
/**
* Cookie SameSite type.
*/
sameSite?: CookieSameSite;
/**
* Cookie Priority. Supported only in Chrome.
*/
priority?: CookiePriority;
/**
* True if cookie is SameParty. Supported only in Chrome.
*/
sameParty?: boolean;
/**
* Cookie source scheme type. Supported only in Chrome.
*/
sourceScheme?: CookieSourceScheme;
/**
* Cookie partition key. In Chrome, it is the top-level site the
* partitioned cookie is available in. In Firefox, it matches the
* source origin
* (https://w3c.github.io/webdriver-bidi/#type-storage-PartitionKey).
*/
partitionKey?: CookiePartitionKey | string;
/**
* True if cookie partition key is opaque. Supported only in Chrome.
*/
partitionKeyOpaque?: boolean;
}
/**
* Cookie parameter object used to set cookies in the browser-level cookies
* API.
*
* @public
*/
export declare interface CookieData {
/**
* Cookie name.
*/
name: string;
/**
* Cookie value.
*/
value: string;
/**
* Cookie domain.
*/
domain: string;
/**
* Cookie path.
*/
path?: string;
/**
* True if cookie is secure.
*/
secure?: boolean;
/**
* True if cookie is http-only.
*/
httpOnly?: boolean;
/**
* Cookie SameSite type.
*/
sameSite?: CookieSameSite;
/**
* Cookie expiration date, session cookie if not set
*/
expires?: number;
/**
* Cookie Priority. Supported only in Chrome.
*/
priority?: CookiePriority;
/**
* True if cookie is SameParty. Supported only in Chrome.
*/
sameParty?: boolean;
/**
* Cookie source scheme type. Supported only in Chrome.
*/
sourceScheme?: CookieSourceScheme;
/**
* Cookie partition key. In Chrome, it matches the top-level site the
* partitioned cookie is available in. In Firefox, it matches the
* source origin
* (https://w3c.github.io/webdriver-bidi/#type-storage-PartitionKey).
*/
partitionKey?: CookiePartitionKey | string;
}
/**
* Cookie parameter object used to set cookies in the page-level cookies
* API.
*
* @public
*/
export declare interface CookieParam {
/**
* Cookie name.
*/
name: string;
/**
* Cookie value.
*/
value: string;
/**
* The request-URI to associate with the setting of the cookie. This value can affect
* the default domain, path, and source scheme values of the created cookie.
*/
url?: string;
/**
* Cookie domain.
*/
domain?: string;
/**
* Cookie path.
*/
path?: string;
/**
* True if cookie is secure.
*/
secure?: boolean;
/**
* True if cookie is http-only.
*/
httpOnly?: boolean;
/**
* Cookie SameSite type.
*/
sameSite?: CookieSameSite;
/**
* Cookie expiration date, session cookie if not set
*/
expires?: number;
/**
* Cookie Priority. Supported only in Chrome.
*/
priority?: CookiePriority;
/**
* True if cookie is SameParty. Supported only in Chrome.
*/
sameParty?: boolean;
/**
* Cookie source scheme type. Supported only in Chrome.
*/
sourceScheme?: CookieSourceScheme;
/**
* Cookie partition key. In Chrome, it matches the top-level site the
* partitioned cookie is available in. In Firefox, it matches the
* source origin
* (https://w3c.github.io/webdriver-bidi/#type-storage-PartitionKey).
*/
partitionKey?: CookiePartitionKey | string;
}
/**
* Represents a cookie partition key in Chrome.
*
* @public
*/
export declare interface CookiePartitionKey {
/**
* The site of the top-level URL the browser was visiting at the start of the request
* to the endpoint that set the cookie.
*
* In Chrome, maps to the CDP's `topLevelSite` partition key.
*/
sourceOrigin: string;
/**
* Indicates if the cookie has any ancestors that are cross-site to
* the topLevelSite.
*
* Supported only in Chrome.
*/
hasCrossSiteAncestor?: boolean;
}
/**
* Represents the cookie's 'Priority' status:
* https://tools.ietf.org/html/draft-west-cookie-priority-00
*
* @public
*/
export declare type CookiePriority = 'Low' | 'Medium' | 'High';
/**
* @license
* Copyright 2024 Google Inc.
* SPDX-License-Identifier: Apache-2.0
*/
/**
* Represents the cookie's 'SameSite' status:
* https://tools.ietf.org/html/draft-west-first-party-cookies
*
* @public
*/
export declare type CookieSameSite = 'Strict' | 'Lax' | 'None';
/**
* Represents the source scheme of the origin that originally set the cookie. A value of
* "Unset" allows protocol clients to emulate legacy cookie scope for the scheme.
* This is a temporary ability and it will be removed in the future.
*
* @public
*/
export declare type CookieSourceScheme = 'Unset' | 'NonSecure' | 'Secure';
/**
* The Coverage class provides methods to gather information about parts of
* JavaScript and CSS that were used by the page.
*
* @remarks
* To output coverage in a form consumable by {@link https://github.com/istanbuljs | Istanbul},
* see {@link https://github.com/istanbuljs/puppeteer-to-istanbul | puppeteer-to-istanbul}.
*
* @example
* An example of using JavaScript and CSS coverage to get percentage of initially
* executed code:
*
* ```ts
* // Enable both JavaScript and CSS coverage
* await Promise.all([
* page.coverage.startJSCoverage(),
* page.coverage.startCSSCoverage(),
* ]);
* // Navigate to page
* await page.goto('https://example.com');
* // Disable both JavaScript and CSS coverage
* const [jsCoverage, cssCoverage] = await Promise.all([
* page.coverage.stopJSCoverage(),
* page.coverage.stopCSSCoverage(),
* ]);
* let totalBytes = 0;
* let usedBytes = 0;
* const coverage = [...jsCoverage, ...cssCoverage];
* for (const entry of coverage) {
* totalBytes += entry.text.length;
* for (const range of entry.ranges) usedBytes += range.end - range.start - 1;
* }
* console.log(`Bytes used: ${(usedBytes / totalBytes) * 100}%`);
* ```
*
* @public
*/
export declare class Coverage {
#private;
/* Excluded from this release type: __constructor */
/* Excluded from this release type: updateClient */
/**
* @param options - Set of configurable options for coverage defaults to
* `resetOnNavigation : true, reportAnonymousScripts : false,`
* `includeRawScriptCoverage : false, useBlockCoverage : true`
* @returns Promise that resolves when coverage is started.
*
* @remarks
* Anonymous scripts are ones that don't have an associated url. These are
* scripts that are dynamically created on the page using `eval` or
* `new Function`. If `reportAnonymousScripts` is set to `true`, anonymous
* scripts URL will start with `debugger://VM` (unless a magic //# sourceURL
* comment is present, in which case that will the be URL).
*/
startJSCoverage(options?: JSCoverageOptions): Promise<void>;
/**
* Promise that resolves to the array of coverage reports for
* all scripts.
*
* @remarks
* JavaScript Coverage doesn't include anonymous scripts by default.
* However, scripts with sourceURLs are reported.
*/
stopJSCoverage(): Promise<JSCoverageEntry[]>;
/**
* @param options - Set of configurable options for coverage, defaults to
* `resetOnNavigation : true`
* @returns Promise that resolves when coverage is started.
*/
startCSSCoverage(options?: CSSCoverageOptions): Promise<void>;
/**
* Promise that resolves to the array of coverage reports
* for all stylesheets.
*
* @remarks
* CSS Coverage doesn't include dynamically injected style tags
* without sourceURLs.
*/
stopCSSCoverage(): Promise<CoverageEntry[]>;
}
/**
* The CoverageEntry class represents one entry of the coverage report.
* @public
*/
export declare interface CoverageEntry {
/**
* The URL of the style sheet or script.
*/
url: string;
/**
* The content of the style sheet or script.
*/
text: string;
/**
* The covered range as start and end positions.
*/
ranges: Array<{
start: number;
end: number;
}>;
}
/* Excluded from this release type: createClientError */
/* Excluded from this release type: createEvaluationError */
/* Excluded from this release type: createProtocolErrorMessage */
/**
* @public
*/
export declare interface Credentials {
username: string;
password: string;
}
/**
* @public
*/
export declare class CSSCoverage {
#private;
constructor(client: CDPSession);
/* Excluded from this release type: updateClient */
start(options?: {
resetOnNavigation?: boolean;
}): Promise<void>;
stop(): Promise<CoverageEntry[]>;
}
/**
* Set of configurable options for CSS coverage.
* @public
*/
export declare interface CSSCoverageOptions {
/**
* Whether to reset coverage on every navigation.
*/
resetOnNavigation?: boolean;
}
/* Excluded from this release type: CSSSelector */
/**
* @public
*/
export declare interface CustomQueryHandler {
/**
* Searches for a {@link https://developer.mozilla.org/en-US/docs/Web/API/Node | Node} matching the given `selector` from {@link https://developer.mozilla.org/en-US/docs/Web/API/Node | node}.
*/
queryOne?: (node: Node, selector: string) => Node | null;
/**
* Searches for some {@link https://developer.mozilla.org/en-US/docs/Web/API/Node | Nodes} matching the given `selector` from {@link https://developer.mozilla.org/en-US/docs/Web/API/Node | node}.
*/
queryAll?: (node: Node, selector: string) => Iterable<Node>;
}
/* Excluded from this release type: CustomQueryHandlerRegistry */
/* Excluded from this release type: customQueryHandlers */
declare interface CustomQuerySelector {
querySelector(root: Node, selector: string): Awaitable<Node | null>;
querySelectorAll(root: Node, selector: string): AwaitableIterable<Node>;
}
/**
* This class mimics the injected {@link CustomQuerySelectorRegistry}.
*/
declare