diff --git a/docs/api/index.md b/docs/api/index.md index dfbd20ef01a..735ce4e6776 100644 --- a/docs/api/index.md +++ b/docs/api/index.md @@ -6,40 +6,42 @@ sidebar_label: API ## Classes -| Class | Description | -| ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [Accessibility](./puppeteer.accessibility.md) | The Accessibility class provides methods for inspecting Chromium's accessibility tree. The accessibility tree is used by assistive technology such as [screen readers](https://en.wikipedia.org/wiki/Screen_reader) or [switches](https://en.wikipedia.org/wiki/Switch_access). | -| [Browser](./puppeteer.browser.md) | A Browser is created when Puppeteer connects to a Chromium instance, either through [PuppeteerNode.launch()](./puppeteer.puppeteernode.launch.md) or [Puppeteer.connect()](./puppeteer.puppeteer.connect.md). | -| [BrowserContext](./puppeteer.browsercontext.md) | BrowserContexts provide a way to operate multiple independent browser sessions. When a browser is launched, it has a single BrowserContext used by default. The method [Browser.newPage](./puppeteer.browser.newpage.md) creates a page in the default browser context. | -| [BrowserFetcher](./puppeteer.browserfetcher.md) | BrowserFetcher can download and manage different versions of Chromium and Firefox. | -| [CDPSession](./puppeteer.cdpsession.md) | The CDPSession instances are used to talk raw Chrome Devtools Protocol. | -| [Connection](./puppeteer.connection.md) | | -| [ConsoleMessage](./puppeteer.consolemessage.md) | ConsoleMessage objects are dispatched by page via the 'console' event. | -| [Coverage](./puppeteer.coverage.md) | The Coverage class provides methods to gathers information about parts of JavaScript and CSS that were used by the page. | -| [CSSCoverage](./puppeteer.csscoverage.md) | | -| [CustomError](./puppeteer.customerror.md) | | -| [Dialog](./puppeteer.dialog.md) | Dialog instances are dispatched by the [Page](./puppeteer.page.md) via the dialog event. | -| [ElementHandle](./puppeteer.elementhandle.md) | ElementHandle represents an in-page DOM element. | -| [EventEmitter](./puppeteer.eventemitter.md) | The EventEmitter class that many Puppeteer classes extend. | -| [FileChooser](./puppeteer.filechooser.md) | File choosers let you react to the page requesting for a file. | -| [Frame](./puppeteer.frame.md) |

Represents a DOM frame.

To understand frames, you can think of frames as <iframe> elements. Just like iframes, frames can be nested, and when JavaScript is executed in a frame, the JavaScript does not effect frames inside the ambient frame the JavaScript executes in.

| -| [HTTPRequest](./puppeteer.httprequest.md) | Represents an HTTP request sent by a page. | -| [HTTPResponse](./puppeteer.httpresponse.md) | The HTTPResponse class represents responses which are received by the [Page](./puppeteer.page.md) class. | -| [JSCoverage](./puppeteer.jscoverage.md) | | -| [JSHandle](./puppeteer.jshandle.md) |

Represents a reference to a JavaScript object. Instances can be created using [Page.evaluateHandle()](./puppeteer.page.evaluatehandle.md).

Handles prevent the referenced JavaScript object from being garbage-collected unless the handle is purposely [disposed](./puppeteer.jshandle.dispose.md). JSHandles are auto-disposed when their associated frame is navigated away or the parent context gets destroyed.

Handles can be used as arguments for any evaluation function such as [Page.$eval()](./puppeteer.page._eval.md), [Page.evaluate()](./puppeteer.page.evaluate.md), and [Page.evaluateHandle()](./puppeteer.page.evaluatehandle.md). They are resolved to their referenced object.

| -| [Keyboard](./puppeteer.keyboard.md) | Keyboard provides an api for managing a virtual keyboard. The high level api is [Keyboard.type()](./puppeteer.keyboard.type.md), which takes raw characters and generates proper keydown, keypress/input, and keyup events on your page. | -| [Mouse](./puppeteer.mouse.md) | The Mouse class operates in main-frame CSS pixels relative to the top-left corner of the viewport. | -| [Page](./puppeteer.page.md) |

Page provides methods to interact with a single tab or [extension background page](https://developer.chrome.com/extensions/background_pages) in Chromium.

:::note

One Browser instance might have multiple Page instances.

:::

| -| [ProductLauncher](./puppeteer.productlauncher.md) | Describes a launcher - a class that is able to create and launch a browser instance. | -| [ProtocolError](./puppeteer.protocolerror.md) | ProtocolError is emitted whenever there is an error from the protocol. | -| [Puppeteer](./puppeteer.puppeteer.md) |

The main Puppeteer class.

IMPORTANT: if you are using Puppeteer in a Node environment, you will get an instance of [PuppeteerNode](./puppeteer.puppeteernode.md) when you import or require puppeteer. That class extends Puppeteer, so has all the methods documented below as well as all that are defined on [PuppeteerNode](./puppeteer.puppeteernode.md).

| -| [PuppeteerNode](./puppeteer.puppeteernode.md) |

Extends the main [Puppeteer](./puppeteer.puppeteer.md) class with Node specific behaviour for fetching and downloading browsers.

If you're using Puppeteer in a Node environment, this is the class you'll get when you run require('puppeteer') (or the equivalent ES import).

| -| [SecurityDetails](./puppeteer.securitydetails.md) | The SecurityDetails class represents the security details of a response that was received over a secure connection. | -| [Target](./puppeteer.target.md) | Target represents a [CDP target](https://chromedevtools.github.io/devtools-protocol/tot/Target/). In CDP a target is something that can be debugged such a frame, a page or a worker. | -| [TimeoutError](./puppeteer.timeouterror.md) | TimeoutError is emitted whenever certain operations are terminated due to timeout. | -| [Touchscreen](./puppeteer.touchscreen.md) | The Touchscreen class exposes touchscreen events. | -| [Tracing](./puppeteer.tracing.md) | The Tracing class exposes the tracing audit interface. | -| [WebWorker](./puppeteer.webworker.md) | This class represents a [WebWorker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API). | +| Class | Description | +| --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [Accessibility](./puppeteer.accessibility.md) | The Accessibility class provides methods for inspecting Chromium's accessibility tree. The accessibility tree is used by assistive technology such as [screen readers](https://en.wikipedia.org/wiki/Screen_reader) or [switches](https://en.wikipedia.org/wiki/Switch_access). | +| [Browser](./puppeteer.browser.md) | A Browser is created when Puppeteer connects to a Chromium instance, either through [PuppeteerNode.launch()](./puppeteer.puppeteernode.launch.md) or [Puppeteer.connect()](./puppeteer.puppeteer.connect.md). | +| [BrowserContext](./puppeteer.browsercontext.md) | BrowserContexts provide a way to operate multiple independent browser sessions. When a browser is launched, it has a single BrowserContext used by default. The method [Browser.newPage](./puppeteer.browser.newpage.md) creates a page in the default browser context. | +| [BrowserFetcher](./puppeteer.browserfetcher.md) | BrowserFetcher can download and manage different versions of Chromium and Firefox. | +| [CDPSession](./puppeteer.cdpsession.md) | The CDPSession instances are used to talk raw Chrome Devtools Protocol. | +| [Connection](./puppeteer.connection.md) | | +| [ConsoleMessage](./puppeteer.consolemessage.md) | ConsoleMessage objects are dispatched by page via the 'console' event. | +| [Coverage](./puppeteer.coverage.md) | The Coverage class provides methods to gathers information about parts of JavaScript and CSS that were used by the page. | +| [CSSCoverage](./puppeteer.csscoverage.md) | | +| [CustomError](./puppeteer.customerror.md) | | +| [DeviceRequestPrompt](./puppeteer.devicerequestprompt.md) | Device request prompts let you respond to the page requesting for a device through an API like WebBluetooth. | +| [DeviceRequestPromptDevice](./puppeteer.devicerequestpromptdevice.md) | Device in a request prompt. | +| [Dialog](./puppeteer.dialog.md) | Dialog instances are dispatched by the [Page](./puppeteer.page.md) via the dialog event. | +| [ElementHandle](./puppeteer.elementhandle.md) | ElementHandle represents an in-page DOM element. | +| [EventEmitter](./puppeteer.eventemitter.md) | The EventEmitter class that many Puppeteer classes extend. | +| [FileChooser](./puppeteer.filechooser.md) | File choosers let you react to the page requesting for a file. | +| [Frame](./puppeteer.frame.md) |

Represents a DOM frame.

To understand frames, you can think of frames as <iframe> elements. Just like iframes, frames can be nested, and when JavaScript is executed in a frame, the JavaScript does not effect frames inside the ambient frame the JavaScript executes in.

| +| [HTTPRequest](./puppeteer.httprequest.md) | Represents an HTTP request sent by a page. | +| [HTTPResponse](./puppeteer.httpresponse.md) | The HTTPResponse class represents responses which are received by the [Page](./puppeteer.page.md) class. | +| [JSCoverage](./puppeteer.jscoverage.md) | | +| [JSHandle](./puppeteer.jshandle.md) |

Represents a reference to a JavaScript object. Instances can be created using [Page.evaluateHandle()](./puppeteer.page.evaluatehandle.md).

Handles prevent the referenced JavaScript object from being garbage-collected unless the handle is purposely [disposed](./puppeteer.jshandle.dispose.md). JSHandles are auto-disposed when their associated frame is navigated away or the parent context gets destroyed.

Handles can be used as arguments for any evaluation function such as [Page.$eval()](./puppeteer.page._eval.md), [Page.evaluate()](./puppeteer.page.evaluate.md), and [Page.evaluateHandle()](./puppeteer.page.evaluatehandle.md). They are resolved to their referenced object.

| +| [Keyboard](./puppeteer.keyboard.md) | Keyboard provides an api for managing a virtual keyboard. The high level api is [Keyboard.type()](./puppeteer.keyboard.type.md), which takes raw characters and generates proper keydown, keypress/input, and keyup events on your page. | +| [Mouse](./puppeteer.mouse.md) | The Mouse class operates in main-frame CSS pixels relative to the top-left corner of the viewport. | +| [Page](./puppeteer.page.md) |

Page provides methods to interact with a single tab or [extension background page](https://developer.chrome.com/extensions/background_pages) in Chromium.

:::note

One Browser instance might have multiple Page instances.

:::

| +| [ProductLauncher](./puppeteer.productlauncher.md) | Describes a launcher - a class that is able to create and launch a browser instance. | +| [ProtocolError](./puppeteer.protocolerror.md) | ProtocolError is emitted whenever there is an error from the protocol. | +| [Puppeteer](./puppeteer.puppeteer.md) |

The main Puppeteer class.

IMPORTANT: if you are using Puppeteer in a Node environment, you will get an instance of [PuppeteerNode](./puppeteer.puppeteernode.md) when you import or require puppeteer. That class extends Puppeteer, so has all the methods documented below as well as all that are defined on [PuppeteerNode](./puppeteer.puppeteernode.md).

| +| [PuppeteerNode](./puppeteer.puppeteernode.md) |

Extends the main [Puppeteer](./puppeteer.puppeteer.md) class with Node specific behaviour for fetching and downloading browsers.

If you're using Puppeteer in a Node environment, this is the class you'll get when you run require('puppeteer') (or the equivalent ES import).

| +| [SecurityDetails](./puppeteer.securitydetails.md) | The SecurityDetails class represents the security details of a response that was received over a secure connection. | +| [Target](./puppeteer.target.md) | Target represents a [CDP target](https://chromedevtools.github.io/devtools-protocol/tot/Target/). In CDP a target is something that can be debugged such a frame, a page or a worker. | +| [TimeoutError](./puppeteer.timeouterror.md) | TimeoutError is emitted whenever certain operations are terminated due to timeout. | +| [Touchscreen](./puppeteer.touchscreen.md) | The Touchscreen class exposes touchscreen events. | +| [Tracing](./puppeteer.tracing.md) | The Tracing class exposes the tracing audit interface. | +| [WebWorker](./puppeteer.webworker.md) | This class represents a [WebWorker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API). | ## Enumerations diff --git a/docs/api/puppeteer.devicerequestprompt.cancel.md b/docs/api/puppeteer.devicerequestprompt.cancel.md new file mode 100644 index 00000000000..a6416224ddd --- /dev/null +++ b/docs/api/puppeteer.devicerequestprompt.cancel.md @@ -0,0 +1,19 @@ +--- +sidebar_label: DeviceRequestPrompt.cancel +--- + +# DeviceRequestPrompt.cancel() method + +Cancel the prompt. + +#### Signature: + +```typescript +class DeviceRequestPrompt { + cancel(): Promise; +} +``` + +**Returns:** + +Promise<void> diff --git a/docs/api/puppeteer.devicerequestprompt.devices.md b/docs/api/puppeteer.devicerequestprompt.devices.md new file mode 100644 index 00000000000..7f422b0879c --- /dev/null +++ b/docs/api/puppeteer.devicerequestprompt.devices.md @@ -0,0 +1,15 @@ +--- +sidebar_label: DeviceRequestPrompt.devices +--- + +# DeviceRequestPrompt.devices property + +Current list of selectable devices. + +#### Signature: + +```typescript +class DeviceRequestPrompt { + devices: DeviceRequestPromptDevice[]; +} +``` diff --git a/docs/api/puppeteer.devicerequestprompt.md b/docs/api/puppeteer.devicerequestprompt.md new file mode 100644 index 00000000000..47ca8a8ad0d --- /dev/null +++ b/docs/api/puppeteer.devicerequestprompt.md @@ -0,0 +1,45 @@ +--- +sidebar_label: DeviceRequestPrompt +--- + +# DeviceRequestPrompt class + +Device request prompts let you respond to the page requesting for a device through an API like WebBluetooth. + +#### Signature: + +```typescript +export declare class DeviceRequestPrompt +``` + +## Remarks + +`DeviceRequestPrompt` instances are returned via the [Page.waitForDevicePrompt()](./puppeteer.page.waitfordeviceprompt.md) method. + +The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `DeviceRequestPrompt` class. + +## Example + +```ts +const [deviceRequest] = Promise.all([ + page.waitForDevicePrompt(), + page.click('#connect-bluetooth'), +]); +await devicePrompt.select( + await devicePrompt.waitForDevice(({name}) => name.includes('My Device')) +); +``` + +## Properties + +| Property | Modifiers | Type | Description | +| ----------------------------------------------------- | --------- | ------------------------------------------------------------------------- | ----------------------------------- | +| [devices](./puppeteer.devicerequestprompt.devices.md) | | [DeviceRequestPromptDevice](./puppeteer.devicerequestpromptdevice.md)\[\] | Current list of selectable devices. | + +## Methods + +| Method | Modifiers | Description | +| ---------------------------------------------------------------------------------- | --------- | ------------------------------------------------------------ | +| [cancel()](./puppeteer.devicerequestprompt.cancel.md) | | Cancel the prompt. | +| [select(device)](./puppeteer.devicerequestprompt.select.md) | | Select a device in the prompt's list. | +| [waitForDevice(filter, options)](./puppeteer.devicerequestprompt.waitfordevice.md) | | Resolve to the first device in the prompt matching a filter. | diff --git a/docs/api/puppeteer.devicerequestprompt.select.md b/docs/api/puppeteer.devicerequestprompt.select.md new file mode 100644 index 00000000000..192fdc6a107 --- /dev/null +++ b/docs/api/puppeteer.devicerequestprompt.select.md @@ -0,0 +1,25 @@ +--- +sidebar_label: DeviceRequestPrompt.select +--- + +# DeviceRequestPrompt.select() method + +Select a device in the prompt's list. + +#### Signature: + +```typescript +class DeviceRequestPrompt { + select(device: DeviceRequestPromptDevice): Promise; +} +``` + +## Parameters + +| Parameter | Type | Description | +| --------- | --------------------------------------------------------------------- | ----------- | +| device | [DeviceRequestPromptDevice](./puppeteer.devicerequestpromptdevice.md) | | + +**Returns:** + +Promise<void> diff --git a/docs/api/puppeteer.devicerequestprompt.waitfordevice.md b/docs/api/puppeteer.devicerequestprompt.waitfordevice.md new file mode 100644 index 00000000000..6cd38101d43 --- /dev/null +++ b/docs/api/puppeteer.devicerequestprompt.waitfordevice.md @@ -0,0 +1,29 @@ +--- +sidebar_label: DeviceRequestPrompt.waitForDevice +--- + +# DeviceRequestPrompt.waitForDevice() method + +Resolve to the first device in the prompt matching a filter. + +#### Signature: + +```typescript +class DeviceRequestPrompt { + waitForDevice( + filter: (device: DeviceRequestPromptDevice) => boolean, + options?: WaitTimeoutOptions + ): Promise; +} +``` + +## Parameters + +| Parameter | Type | Description | +| --------- | --------------------------------------------------------------------------------------------- | ------------ | +| filter | (device: [DeviceRequestPromptDevice](./puppeteer.devicerequestpromptdevice.md)) => boolean | | +| options | [WaitTimeoutOptions](./puppeteer.waittimeoutoptions.md) | _(Optional)_ | + +**Returns:** + +Promise<[DeviceRequestPromptDevice](./puppeteer.devicerequestpromptdevice.md)> diff --git a/docs/api/puppeteer.devicerequestpromptdevice.id.md b/docs/api/puppeteer.devicerequestpromptdevice.id.md new file mode 100644 index 00000000000..6eb10693a46 --- /dev/null +++ b/docs/api/puppeteer.devicerequestpromptdevice.id.md @@ -0,0 +1,15 @@ +--- +sidebar_label: DeviceRequestPromptDevice.id +--- + +# DeviceRequestPromptDevice.id property + +Device id during a prompt. + +#### Signature: + +```typescript +class DeviceRequestPromptDevice { + id: string; +} +``` diff --git a/docs/api/puppeteer.devicerequestpromptdevice.md b/docs/api/puppeteer.devicerequestpromptdevice.md new file mode 100644 index 00000000000..9d244ccc1e8 --- /dev/null +++ b/docs/api/puppeteer.devicerequestpromptdevice.md @@ -0,0 +1,24 @@ +--- +sidebar_label: DeviceRequestPromptDevice +--- + +# DeviceRequestPromptDevice class + +Device in a request prompt. + +#### Signature: + +```typescript +export declare class DeviceRequestPromptDevice +``` + +## Remarks + +The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `DeviceRequestPromptDevice` class. + +## Properties + +| Property | Modifiers | Type | Description | +| ----------------------------------------------------- | --------- | ------ | -------------------------------------- | +| [id](./puppeteer.devicerequestpromptdevice.id.md) | | string | Device id during a prompt. | +| [name](./puppeteer.devicerequestpromptdevice.name.md) | | string | Device name as it appears in a prompt. | diff --git a/docs/api/puppeteer.devicerequestpromptdevice.name.md b/docs/api/puppeteer.devicerequestpromptdevice.name.md new file mode 100644 index 00000000000..8ab990addc1 --- /dev/null +++ b/docs/api/puppeteer.devicerequestpromptdevice.name.md @@ -0,0 +1,15 @@ +--- +sidebar_label: DeviceRequestPromptDevice.name +--- + +# DeviceRequestPromptDevice.name property + +Device name as it appears in a prompt. + +#### Signature: + +```typescript +class DeviceRequestPromptDevice { + name: string; +} +``` diff --git a/docs/api/puppeteer.frame.waitfordeviceprompt.md b/docs/api/puppeteer.frame.waitfordeviceprompt.md index e37a0ecacc2..b9cba725281 100644 --- a/docs/api/puppeteer.frame.waitfordeviceprompt.md +++ b/docs/api/puppeteer.frame.waitfordeviceprompt.md @@ -30,7 +30,7 @@ class Frame { **Returns:** -Promise<DeviceRequestPrompt> +Promise<[DeviceRequestPrompt](./puppeteer.devicerequestprompt.md)> ## Example diff --git a/docs/api/puppeteer.page.waitfordeviceprompt.md b/docs/api/puppeteer.page.waitfordeviceprompt.md index 9b41e3deee1..a4c402ccfe7 100644 --- a/docs/api/puppeteer.page.waitfordeviceprompt.md +++ b/docs/api/puppeteer.page.waitfordeviceprompt.md @@ -30,7 +30,7 @@ class Page { **Returns:** -Promise<DeviceRequestPrompt> +Promise<[DeviceRequestPrompt](./puppeteer.devicerequestprompt.md)> ## Example diff --git a/packages/puppeteer-core/src/common/NetworkManager.ts b/packages/puppeteer-core/src/common/NetworkManager.ts index 2dbcf572536..381f43bd5f8 100644 --- a/packages/puppeteer-core/src/common/NetworkManager.ts +++ b/packages/puppeteer-core/src/common/NetworkManager.ts @@ -22,7 +22,7 @@ import {DeferredPromise} from '../util/DeferredPromise.js'; import {CDPSession} from './Connection.js'; import {EventEmitter} from './EventEmitter.js'; -import {Frame} from './Frame.js'; +import {FrameManager} from './FrameManager.js'; import {HTTPRequest} from './HTTPRequest.js'; import {HTTPResponse} from './HTTPResponse.js'; import {FetchRequestId, NetworkEventManager} from './NetworkEventManager.js'; @@ -68,20 +68,13 @@ export const NetworkManagerEmittedEvents = { RequestFinished: Symbol('NetworkManager.RequestFinished'), } as const; -/** - * @internal - */ -interface FrameManager { - frame(frameId: string): Frame | null; -} - /** * @internal */ export class NetworkManager extends EventEmitter { #client: CDPSession; #ignoreHTTPSErrors: boolean; - #frameManager: FrameManager; + #frameManager: Pick; #networkEventManager = new NetworkEventManager(); #extraHTTPHeaders: Record = {}; #credentials?: Credentials; @@ -100,7 +93,7 @@ export class NetworkManager extends EventEmitter { constructor( client: CDPSession, ignoreHTTPSErrors: boolean, - frameManager: FrameManager + frameManager: Pick ) { super(); this.#client = client; diff --git a/packages/puppeteer-core/src/common/Page.ts b/packages/puppeteer-core/src/common/Page.ts index 3e93dbf7f3d..be94960fcf6 100644 --- a/packages/puppeteer-core/src/common/Page.ts +++ b/packages/puppeteer-core/src/common/Page.ts @@ -21,6 +21,7 @@ import {Protocol} from 'devtools-protocol'; import type {Browser} from '../api/Browser.js'; import type {BrowserContext} from '../api/BrowserContext.js'; import {ElementHandle} from '../api/ElementHandle.js'; +import {HTTPRequest} from '../api/HTTPRequest.js'; import {HTTPResponse} from '../api/HTTPResponse.js'; import {JSHandle} from '../api/JSHandle.js'; import { @@ -61,7 +62,6 @@ import { FrameWaitForFunctionOptions, } from './Frame.js'; import {FrameManager, FrameManagerEmittedEvents} from './FrameManager.js'; -import {HTTPRequest} from './HTTPRequest.js'; import {Keyboard, Mouse, MouseButton, Touchscreen} from './Input.js'; import {WaitForSelectorOptions} from './IsolatedWorld.js'; import {MAIN_WORLD} from './IsolatedWorlds.js'; diff --git a/packages/puppeteer-core/src/common/common.ts b/packages/puppeteer-core/src/common/common.ts index 00501a784ea..ef4f2de99be 100644 --- a/packages/puppeteer-core/src/common/common.ts +++ b/packages/puppeteer-core/src/common/common.ts @@ -28,6 +28,7 @@ export * from './Coverage.js'; export * from './CustomQueryHandler.js'; export * from './Debug.js'; export * from './Device.js'; +export * from './DeviceRequestPrompt.js'; export * from './Dialog.js'; export * from './ElementHandle.js'; export * from './EmulationManager.js';