thunderstrike/puppeteer
thunderstrike/puppeteer
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: add DeviceRequestPrompt documentation (#9918)

Browse Source
This commit is contained in:
Nikolay Vitkov 2023-03-27 13:16:51 +02:00 committed by GitHub
parent 16bf0dc798
commit bb37df5f64
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
14 changed files with 230 additions and 47 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

70
docs/api/index.md
View File

@ -6,40 +6,42 @@ sidebar_label: API
## Classes ## Classes
| Class | Description | | 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). | | [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). | | [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. | | [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. | | [BrowserFetcher](./puppeteer.browserfetcher.md) | BrowserFetcher can download and manage different versions of Chromium and Firefox. |
| [CDPSession](./puppeteer.cdpsession.md) | The <code>CDPSession</code> instances are used to talk raw Chrome Devtools Protocol. | | [CDPSession](./puppeteer.cdpsession.md) | The <code>CDPSession</code> instances are used to talk raw Chrome Devtools Protocol. |
| [Connection](./puppeteer.connection.md) | | | [Connection](./puppeteer.connection.md) | |
| [ConsoleMessage](./puppeteer.consolemessage.md) | ConsoleMessage objects are dispatched by page via the 'console' event. | | [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. | | [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) | | | [CSSCoverage](./puppeteer.csscoverage.md) | |
| [CustomError](./puppeteer.customerror.md) | | | [CustomError](./puppeteer.customerror.md) | |
| [Dialog](./puppeteer.dialog.md) | Dialog instances are dispatched by the [Page](./puppeteer.page.md) via the <code>dialog</code> event. | | [DeviceRequestPrompt](./puppeteer.devicerequestprompt.md) | Device request prompts let you respond to the page requesting for a device through an API like WebBluetooth. |
| [ElementHandle](./puppeteer.elementhandle.md) | ElementHandle represents an in-page DOM element. | | [DeviceRequestPromptDevice](./puppeteer.devicerequestpromptdevice.md) | Device in a request prompt. |
| [EventEmitter](./puppeteer.eventemitter.md) | The EventEmitter class that many Puppeteer classes extend. | | [Dialog](./puppeteer.dialog.md) | Dialog instances are dispatched by the [Page](./puppeteer.page.md) via the <code>dialog</code> event. |
| [FileChooser](./puppeteer.filechooser.md) | File choosers let you react to the page requesting for a file. | | [ElementHandle](./puppeteer.elementhandle.md) | ElementHandle represents an in-page DOM element. |
| [Frame](./puppeteer.frame.md) | <p>Represents a DOM frame.</p><p>To understand frames, you can think of frames as <code>&lt;iframe&gt;</code> 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.</p> | | [EventEmitter](./puppeteer.eventemitter.md) | The EventEmitter class that many Puppeteer classes extend. |
| [HTTPRequest](./puppeteer.httprequest.md) | Represents an HTTP request sent by a page. | | [FileChooser](./puppeteer.filechooser.md) | File choosers let you react to the page requesting for a file. |
| [HTTPResponse](./puppeteer.httpresponse.md) | The HTTPResponse class represents responses which are received by the [Page](./puppeteer.page.md) class. | | [Frame](./puppeteer.frame.md) | <p>Represents a DOM frame.</p><p>To understand frames, you can think of frames as <code>&lt;iframe&gt;</code> 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.</p> |
| [JSCoverage](./puppeteer.jscoverage.md) | | | [HTTPRequest](./puppeteer.httprequest.md) | Represents an HTTP request sent by a page. |
| [JSHandle](./puppeteer.jshandle.md) | <p>Represents a reference to a JavaScript object. Instances can be created using [Page.evaluateHandle()](./puppeteer.page.evaluatehandle.md).</p><p>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.</p><p>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.</p> | | [HTTPResponse](./puppeteer.httpresponse.md) | The HTTPResponse class represents responses which are received by the [Page](./puppeteer.page.md) class. |
| [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. | | [JSCoverage](./puppeteer.jscoverage.md) | |
| [Mouse](./puppeteer.mouse.md) | The Mouse class operates in main-frame CSS pixels relative to the top-left corner of the viewport. | | [JSHandle](./puppeteer.jshandle.md) | <p>Represents a reference to a JavaScript object. Instances can be created using [Page.evaluateHandle()](./puppeteer.page.evaluatehandle.md).</p><p>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.</p><p>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.</p> |
| [Page](./puppeteer.page.md) | <p>Page provides methods to interact with a single tab or [extension background page](https://developer.chrome.com/extensions/background_pages) in Chromium.</p><p>:::note</p><p>One Browser instance might have multiple Page instances.</p><p>:::</p> | | [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. |
| [ProductLauncher](./puppeteer.productlauncher.md) | Describes a launcher - a class that is able to create and launch a browser instance. | | [Mouse](./puppeteer.mouse.md) | The Mouse class operates in main-frame CSS pixels relative to the top-left corner of the viewport. |
| [ProtocolError](./puppeteer.protocolerror.md) | ProtocolError is emitted whenever there is an error from the protocol. | | [Page](./puppeteer.page.md) | <p>Page provides methods to interact with a single tab or [extension background page](https://developer.chrome.com/extensions/background_pages) in Chromium.</p><p>:::note</p><p>One Browser instance might have multiple Page instances.</p><p>:::</p> |
| [Puppeteer](./puppeteer.puppeteer.md) | <p>The main Puppeteer class.</p><p>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 <code>puppeteer</code>. That class extends <code>Puppeteer</code>, so has all the methods documented below as well as all that are defined on [PuppeteerNode](./puppeteer.puppeteernode.md).</p> | | [ProductLauncher](./puppeteer.productlauncher.md) | Describes a launcher - a class that is able to create and launch a browser instance. |
| [PuppeteerNode](./puppeteer.puppeteernode.md) | <p>Extends the main [Puppeteer](./puppeteer.puppeteer.md) class with Node specific behaviour for fetching and downloading browsers.</p><p>If you're using Puppeteer in a Node environment, this is the class you'll get when you run <code>require('puppeteer')</code> (or the equivalent ES <code>import</code>).</p> | | [ProtocolError](./puppeteer.protocolerror.md) | ProtocolError is emitted whenever there is an error from the protocol. |
| [SecurityDetails](./puppeteer.securitydetails.md) | The SecurityDetails class represents the security details of a response that was received over a secure connection. | | [Puppeteer](./puppeteer.puppeteer.md) | <p>The main Puppeteer class.</p><p>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 <code>puppeteer</code>. That class extends <code>Puppeteer</code>, so has all the methods documented below as well as all that are defined on [PuppeteerNode](./puppeteer.puppeteernode.md).</p> |
| [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. | | [PuppeteerNode](./puppeteer.puppeteernode.md) | <p>Extends the main [Puppeteer](./puppeteer.puppeteer.md) class with Node specific behaviour for fetching and downloading browsers.</p><p>If you're using Puppeteer in a Node environment, this is the class you'll get when you run <code>require('puppeteer')</code> (or the equivalent ES <code>import</code>).</p> |
| [TimeoutError](./puppeteer.timeouterror.md) | TimeoutError is emitted whenever certain operations are terminated due to timeout. | | [SecurityDetails](./puppeteer.securitydetails.md) | The SecurityDetails class represents the security details of a response that was received over a secure connection. |
| [Touchscreen](./puppeteer.touchscreen.md) | The Touchscreen class exposes touchscreen events. | | [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. |
| [Tracing](./puppeteer.tracing.md) | The Tracing class exposes the tracing audit interface. | | [TimeoutError](./puppeteer.timeouterror.md) | TimeoutError is emitted whenever certain operations are terminated due to timeout. |
| [WebWorker](./puppeteer.webworker.md) | This class represents a [WebWorker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API). | | [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 ## Enumerations

19
docs/api/puppeteer.devicerequestprompt.cancel.md Normal file
View File

@ -0,0 +1,19 @@
---
sidebar_label: DeviceRequestPrompt.cancel
---
# DeviceRequestPrompt.cancel() method
Cancel the prompt.
#### Signature:
```typescript
class DeviceRequestPrompt {
cancel(): Promise<void>;
}
```
**Returns:**
Promise&lt;void&gt;

15
docs/api/puppeteer.devicerequestprompt.devices.md Normal file
View File

@ -0,0 +1,15 @@
---
sidebar_label: DeviceRequestPrompt.devices
---
# DeviceRequestPrompt.devices property
Current list of selectable devices.
#### Signature:
```typescript
class DeviceRequestPrompt {
devices: DeviceRequestPromptDevice[];
}
```

45
docs/api/puppeteer.devicerequestprompt.md Normal file
View File

@ -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. |

25
docs/api/puppeteer.devicerequestprompt.select.md Normal file
View File

@ -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<void>;
}
```
## Parameters
| Parameter | Type | Description |
| --------- | --------------------------------------------------------------------- | ----------- |
| device | [DeviceRequestPromptDevice](./puppeteer.devicerequestpromptdevice.md) | |
**Returns:**
Promise&lt;void&gt;

29
docs/api/puppeteer.devicerequestprompt.waitfordevice.md Normal file
View File

@ -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<DeviceRequestPromptDevice>;
}
```
## Parameters
| Parameter | Type | Description |
| --------- | --------------------------------------------------------------------------------------------- | ------------ |
| filter | (device: [DeviceRequestPromptDevice](./puppeteer.devicerequestpromptdevice.md)) =&gt; boolean | |
| options | [WaitTimeoutOptions](./puppeteer.waittimeoutoptions.md) | _(Optional)_ |
**Returns:**
Promise&lt;[DeviceRequestPromptDevice](./puppeteer.devicerequestpromptdevice.md)&gt;

15
docs/api/puppeteer.devicerequestpromptdevice.id.md Normal file
View File

@ -0,0 +1,15 @@
---
sidebar_label: DeviceRequestPromptDevice.id
---
# DeviceRequestPromptDevice.id property
Device id during a prompt.
#### Signature:
```typescript
class DeviceRequestPromptDevice {
id: string;
}
```

24
docs/api/puppeteer.devicerequestpromptdevice.md Normal file
View File

@ -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. |

15
docs/api/puppeteer.devicerequestpromptdevice.name.md Normal file
View File

@ -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;
}
```

2
docs/api/puppeteer.frame.waitfordeviceprompt.md
View File

@ -30,7 +30,7 @@ class Frame {
**Returns:** **Returns:**
Promise&lt;DeviceRequestPrompt&gt; Promise&lt;[DeviceRequestPrompt](./puppeteer.devicerequestprompt.md)&gt;
## Example ## Example

2
docs/api/puppeteer.page.waitfordeviceprompt.md
View File

@ -30,7 +30,7 @@ class Page {
**Returns:** **Returns:**
Promise&lt;DeviceRequestPrompt&gt; Promise&lt;[DeviceRequestPrompt](./puppeteer.devicerequestprompt.md)&gt;
## Example ## Example

13
packages/puppeteer-core/src/common/NetworkManager.ts
View File

@ -22,7 +22,7 @@ import {DeferredPromise} from '../util/DeferredPromise.js';
import {CDPSession} from './Connection.js'; import {CDPSession} from './Connection.js';
import {EventEmitter} from './EventEmitter.js'; import {EventEmitter} from './EventEmitter.js';
import {Frame} from './Frame.js'; import {FrameManager} from './FrameManager.js';
import {HTTPRequest} from './HTTPRequest.js'; import {HTTPRequest} from './HTTPRequest.js';
import {HTTPResponse} from './HTTPResponse.js'; import {HTTPResponse} from './HTTPResponse.js';
import {FetchRequestId, NetworkEventManager} from './NetworkEventManager.js'; import {FetchRequestId, NetworkEventManager} from './NetworkEventManager.js';
@ -68,20 +68,13 @@ export const NetworkManagerEmittedEvents = {
RequestFinished: Symbol('NetworkManager.RequestFinished'), RequestFinished: Symbol('NetworkManager.RequestFinished'),
} as const; } as const;
/**
* @internal
*/
interface FrameManager {
frame(frameId: string): Frame | null;
}
/** /**
* @internal * @internal
*/ */
export class NetworkManager extends EventEmitter { export class NetworkManager extends EventEmitter {
#client: CDPSession; #client: CDPSession;
#ignoreHTTPSErrors: boolean; #ignoreHTTPSErrors: boolean;
#frameManager: FrameManager; #frameManager: Pick<FrameManager, 'frame'>;
#networkEventManager = new NetworkEventManager(); #networkEventManager = new NetworkEventManager();
#extraHTTPHeaders: Record<string, string> = {}; #extraHTTPHeaders: Record<string, string> = {};
#credentials?: Credentials; #credentials?: Credentials;
@ -100,7 +93,7 @@ export class NetworkManager extends EventEmitter {
constructor( constructor(
client: CDPSession, client: CDPSession,
ignoreHTTPSErrors: boolean, ignoreHTTPSErrors: boolean,
frameManager: FrameManager frameManager: Pick<FrameManager, 'frame'>
) { ) {
super(); super();
this.#client = client; this.#client = client;

2
packages/puppeteer-core/src/common/Page.ts
View File

@ -21,6 +21,7 @@ import {Protocol} from 'devtools-protocol';
import type {Browser} from '../api/Browser.js'; import type {Browser} from '../api/Browser.js';
import type {BrowserContext} from '../api/BrowserContext.js'; import type {BrowserContext} from '../api/BrowserContext.js';
import {ElementHandle} from '../api/ElementHandle.js'; import {ElementHandle} from '../api/ElementHandle.js';
import {HTTPRequest} from '../api/HTTPRequest.js';
import {HTTPResponse} from '../api/HTTPResponse.js'; import {HTTPResponse} from '../api/HTTPResponse.js';
import {JSHandle} from '../api/JSHandle.js'; import {JSHandle} from '../api/JSHandle.js';
import { import {
@ -61,7 +62,6 @@ import {
FrameWaitForFunctionOptions, FrameWaitForFunctionOptions,
} from './Frame.js'; } from './Frame.js';
import {FrameManager, FrameManagerEmittedEvents} from './FrameManager.js'; import {FrameManager, FrameManagerEmittedEvents} from './FrameManager.js';
import {HTTPRequest} from './HTTPRequest.js';
import {Keyboard, Mouse, MouseButton, Touchscreen} from './Input.js'; import {Keyboard, Mouse, MouseButton, Touchscreen} from './Input.js';
import {WaitForSelectorOptions} from './IsolatedWorld.js'; import {WaitForSelectorOptions} from './IsolatedWorld.js';
import {MAIN_WORLD} from './IsolatedWorlds.js'; import {MAIN_WORLD} from './IsolatedWorlds.js';

1
packages/puppeteer-core/src/common/common.ts
View File

@ -28,6 +28,7 @@ export * from './Coverage.js';
export * from './CustomQueryHandler.js'; export * from './CustomQueryHandler.js';
export * from './Debug.js'; export * from './Debug.js';
export * from './Device.js'; export * from './Device.js';
export * from './DeviceRequestPrompt.js';
export * from './Dialog.js'; export * from './Dialog.js';
export * from './ElementHandle.js'; export * from './ElementHandle.js';
export * from './EmulationManager.js'; export * from './EmulationManager.js';