feat: add Page.waitForDevicePrompt (#9299)

Co-authored-by: Alex Rudenko <OrKoN@users.noreply.github.com>
Co-authored-by: Alex Rudenko <alexrudenko@chromium.org>

docs/api/puppeteer.frame.md

@@ -90,6 +90,7 @@ console.log(text);
 | [title()](./puppeteer.frame.title.md)                                                |           |                                                                                                                                                                                                                                                                            |
 | [type(selector, text, options)](./puppeteer.frame.type.md)                           |           | Sends a <code>keydown</code>, <code>keypress</code>/<code>input</code>, and <code>keyup</code> event for each character in the text.                                                                                                                                       |
 | [url()](./puppeteer.frame.url.md)                                                    |           |                                                                                                                                                                                                                                                                            |
+| [waitForDevicePrompt(options)](./puppeteer.frame.waitfordeviceprompt.md)             |           | <p>This method is typically coupled with an action that triggers a device request from an api such as WebBluetooth.</p><p>:::caution</p><p>This must be called before the device request is made. It will not return a currently active device prompt.</p><p>:::</p>       |
 | [waitForFunction(pageFunction, options, args)](./puppeteer.frame.waitforfunction.md) |           |                                                                                                                                                                                                                                                                            |
 | [waitForNavigation(options)](./puppeteer.frame.waitfornavigation.md)                 |           | <p>Waits for the frame to navigate. It is useful for when you run code which will indirectly cause the frame to navigate.</p><p>Usage of the [History API](https://developer.mozilla.org/en-US/docs/Web/API/History_API) to change the URL is considered a navigation.</p> |
 | [waitForSelector(selector, options)](./puppeteer.frame.waitforselector.md)           |           | <p>Waits for an element matching the given selector to appear in the frame.</p><p>This method works across navigations.</p>                                                                                                                                                |

docs/api/puppeteer.frame.waitfordeviceprompt.md

@@ -0,0 +1,45 @@
+---
+sidebar_label: Frame.waitForDevicePrompt
+---
+
+# Frame.waitForDevicePrompt() method
+
+This method is typically coupled with an action that triggers a device request from an api such as WebBluetooth.
+
+:::caution
+
+This must be called before the device request is made. It will not return a currently active device prompt.
+
+:::
+
+#### Signature:
+
+```typescript
+class Frame {
+  waitForDevicePrompt(
+    options?: WaitTimeoutOptions
+  ): Promise<DeviceRequestPrompt>;
+}
+```
+
+## Parameters
+
+| Parameter | Type                                                    | Description  |
+| --------- | ------------------------------------------------------- | ------------ |
+| options   | [WaitTimeoutOptions](./puppeteer.waittimeoutoptions.md) | _(Optional)_ |
+
+**Returns:**
+
+Promise&lt;DeviceRequestPrompt&gt;
+
+## Example
+
+```ts
+const [devicePrompt] = Promise.all([
+  frame.waitForDevicePrompt(),
+  frame.click('#connect-bluetooth'),
+]);
+await devicePrompt.select(
+  await devicePrompt.waitForDevice(({name}) => name.includes('My Device'))
+);
+```

docs/api/puppeteer.page.md

@@ -149,6 +149,7 @@ page.off('request', logRequest);
 | [type(selector, text, options)](./puppeteer.page.type.md)                                   |           | <p>Sends a <code>keydown</code>, <code>keypress/input</code>, and <code>keyup</code> event for each character in the text.</p><p>To press a special key, like <code>Control</code> or <code>ArrowDown</code>, use [Keyboard.press()](./puppeteer.keyboard.press.md).</p>                                                                                                                                                                                                                                                                                                                                |
 | [url()](./puppeteer.page.url.md)                                                            |           |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
 | [viewport()](./puppeteer.page.viewport.md)                                                  |           |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| [waitForDevicePrompt(options)](./puppeteer.page.waitfordeviceprompt.md)                     |           | <p>This method is typically coupled with an action that triggers a device request from an api such as WebBluetooth.</p><p>:::caution</p><p>This must be called before the device request is made. It will not return a currently active device prompt.</p><p>:::</p>                                                                                                                                                                                                                                                                                                                                    |
 | [waitForFileChooser(options)](./puppeteer.page.waitforfilechooser.md)                       |           | <p>This method is typically coupled with an action that triggers file choosing.</p><p>:::caution</p><p>This must be called before the file chooser is launched. It will not return a currently active file chooser.</p><p>:::</p>                                                                                                                                                                                                                                                                                                                                                                       |
 | [waitForFrame(urlOrPredicate, options)](./puppeteer.page.waitforframe.md)                   |           |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
 | [waitForFunction(pageFunction, options, args)](./puppeteer.page.waitforfunction.md)         |           | Waits for a function to finish evaluating in the page's context.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |

docs/api/puppeteer.page.waitfordeviceprompt.md

@@ -0,0 +1,45 @@
+---
+sidebar_label: Page.waitForDevicePrompt
+---
+
+# Page.waitForDevicePrompt() method
+
+This method is typically coupled with an action that triggers a device request from an api such as WebBluetooth.
+
+:::caution
+
+This must be called before the device request is made. It will not return a currently active device prompt.
+
+:::
+
+#### Signature:
+
+```typescript
+class Page {
+  waitForDevicePrompt(
+    options?: WaitTimeoutOptions
+  ): Promise<DeviceRequestPrompt>;
+}
+```
+
+## Parameters
+
+| Parameter | Type                                                    | Description  |
+| --------- | ------------------------------------------------------- | ------------ |
+| options   | [WaitTimeoutOptions](./puppeteer.waittimeoutoptions.md) | _(Optional)_ |
+
+**Returns:**
+
+Promise&lt;DeviceRequestPrompt&gt;
+
+## Example
+
+```ts
+const [devicePrompt] = Promise.all([
+  page.waitForDevicePrompt(),
+  page.click('#connect-bluetooth'),
+]);
+await devicePrompt.select(
+  await devicePrompt.waitForDevice(({name}) => name.includes('My Device'))
+);
+```

packages/puppeteer-core/src/api/Page.ts

@@ -24,6 +24,7 @@ import type {Accessibility} from '../common/Accessibility.js';
 import type {ConsoleMessage} from '../common/ConsoleMessage.js';
 import type {Coverage} from '../common/Coverage.js';
 import {Device} from '../common/Device.js';
+import {DeviceRequestPrompt} from '../common/DeviceRequestPrompt.js';
 import type {Dialog} from '../common/Dialog.js';
 import {EventEmitter, Handler} from '../common/EventEmitter.js';
 import type {FileChooser} from '../common/FileChooser.js';
@@ -2558,6 +2559,36 @@ export class Page extends EventEmitter {
   >(): Promise<HandleFor<Awaited<ReturnType<Func>>>> {
     throw new Error('Not implemented');
   }
+
+  /**
+   * This method is typically coupled with an action that triggers a device
+   * request from an api such as WebBluetooth.
+   *
+   * :::caution
+   *
+   * This must be called before the device request is made. It will not return a
+   * currently active device prompt.
+   *
+   * :::
+   *
+   * @example
+   *
+   * ```ts
+   * const [devicePrompt] = Promise.all([
+   *   page.waitForDevicePrompt(),
+   *   page.click('#connect-bluetooth'),
+   * ]);
+   * await devicePrompt.select(
+   *   await devicePrompt.waitForDevice(({name}) => name.includes('My Device'))
+   * );
+   * ```
+   */
+  waitForDevicePrompt(
+    options?: WaitTimeoutOptions
+  ): Promise<DeviceRequestPrompt>;
+  waitForDevicePrompt(): Promise<DeviceRequestPrompt> {
+    throw new Error('Not implemented');
+  }
 }
 
 /**