feat: add Page.waitForDevicePrompt

[mzgoddard]

What kind of change does this PR introduce?

Add a feature through Page.waitForDevicePrompt() and DeviceRequestPrompt to respond to DeviceAccess.deviceRequestPrompted protocol events.

Did you add tests for your changes?

This change adds tests for the interface that simulate interaction with a mock session object.

These tests cover the added code except for Page.waitForDevicePrompt itself.

If relevant, did you update the documentation?

Page.waitForDevicePrompt includes a jsdoc with a comment with a likely common use case:

const [deviceRequest] = Promise.all([
  page.waitForDevicePrompt(),
  page.click('#connect-bluetooth'),
]);
await devicePrompt.select(
  await devicePrompt.waitForDevice(({name}) => name.includes('My Device'))
);

Summary

Page.waitForDevicePrompt resolves to a DeviceRequestPrompt when the next DeviceAccess.deviceRequestPrompted events are emitted by the session. DeviceRequestPrompt.select and DeviceRequestPrompt.cancel can be be called to respond to the prompt. DeviceRequestPrompt.waitForDevice resolves to the first device in the prompt that matches a given filter. That device can be listed in DeviceRequestPrompt.devices when waitForDevice is called or from future DeviceAccess.deviceRequestPrompted events.

This wraps devtools protocol events and methods added in
https://chromium-review.googlesource.com/c/chromium/src/+/3933844. That commit log integrates those events with WebBluetooth. When WebBluetooth's requestDevice is called, after some steps are performed, if they succeed, a prompt for the user is opened to select a device. This interface and the protocol additions it depends on add a way to automate responding to that prompt.

[mzgoddard]

To further test this interface with the devtools protocol additions, without mocking them, a test environment with a specific hardware setup like bluetooth hardware with nearby reliable devices or some degree of detailed virtualization. Chromium uses Mojo services to fake parts of its WebBluetooth implementation in tests. Tests here could use that as well but these features are not normally shipped, to my knowledge, because the size of the released build they add. But I am thinking that would be "too much" here to automate testting this code, so I've used a mock session object here to test it.

The commit log https://chromium-review.googlesource.com/c/chromium/src/+/3933844 isn't merged yet, so I used a npm-linked version of devtools-protocol I've pushed to https://github.com/mzgoddard/devtools-protocol/tree/device-access-device-request-prompted while writing this change and testing it.

[OrKoN]

@mzgoddard thanks for the PR. Would you mind rebasing?

[mzgoddard]

I rebased onto main. The CL this depends on has merged and devtools-bot pushed to devtools-protocol a commit including the change ChromeDevTools/devtools-protocol@97f8fcb.

As I understand it, puppeteer tracks Chrome's Beta release. So, this PR will wait until then when the dependency on devtools-protocol will be bumped to include that. Is that right?

[OrKoN]

@mzgoddard yes, that's right. We can land it once we rolled the Chromium binary version that supports this feature.

[OrKoN]

This should not be committed. I think the file has been removed from the tree but accidentally pushed here.

[OrKoN]

@mzgoddard let me know if need help rebasing this. We can land it now.

[OrKoN]

@mzgoddard could you please run npm run format to update the formatting based on the latest rules?

[OrKoN]

Also, the docs need to be re-generated npm run docs. The current comments seem to differ from the generated markdown.

[kblok]

@mzgoddard, sorry for quite a late comment. But what's the purpose of this expect?
How the manager won't be truthy?