docs: editing

puppeteer · Nov 27, 2023 · ddab3f2 · ddab3f2
1 parent 83d68bc
commit ddab3f2
Show file tree

Hide file tree

Showing 3 changed files with 148 additions and 107 deletions.
diff --git a/docs/api/puppeteer.browserconnectoptions.md b/docs/api/puppeteer.browserconnectoptions.md
@@ -18,6 +18,7 @@ export interface BrowserConnectOptions
 | ----------------- | --------------------- | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------- | --------------------------- |
 | defaultViewport   | <code>optional</code> | [Viewport](./puppeteer.viewport.md) \| null                 | Sets the viewport for each page.                                                          | '{width: 800, height: 600}' |
 | ignoreHTTPSErrors | <code>optional</code> | boolean                                                     | Whether to ignore HTTPS errors during navigation.                                         | <code>false</code>          |
+| protocol          | <code>optional</code> | [ProtocolType](./puppeteer.protocoltype.md)                 |                                                                                           | 'cdp'                       |
 | protocolTimeout   | <code>optional</code> | number                                                      | Timeout setting for individual protocol (CDP) calls.                                      | <code>180_000</code>        |
 | slowMo            | <code>optional</code> | number                                                      | Slows down Puppeteer operations by the specified amount of milliseconds to aid debugging. |                             |
 | targetFilter      | <code>optional</code> | [TargetFilterCallback](./puppeteer.targetfiltercallback.md) | Callback to decide if Puppeteer should connect to a given target or not.                  |                             |
diff --git a/docs/faq.md b/docs/faq.md
@@ -27,38 +27,15 @@ support to browsers such as Safari. This effort includes exploration of a
 standard for executing cross-browser commands (instead of relying on the
 non-standard DevTools Protocol used by Chrome).
 
-Update 2023-11-17: Puppeteer offers experimental support for
-[WebDriver BiDi](https://w3c.github.io/webdriver-bidi/) with Firefox.
-From Puppeteer vX.X.X. onwards you can specify
-[`puppeteer.launch({product:'firefox', protocol: 'webDriverBiDi'})`](./api/puppeteer.puppeteernode.launch)
-to run your Puppeteer scripts in Firefox Nightly, using WebDriver BiDi.
-WebDriver BiDi is a new browser automation standard, an extension to the
-WebDriver protocol. Just like CDP implementation in Firefox, the WebDriver BiDi
-does not support all of the Puppeteer features. Refer to the
-[API documentation](https://pptr.dev/api/puppeteer.puppeteernode) to learn if a
-particular feature is supported with WebDriver BiDi.
+Update 2023-11-17: Puppeteer has experimental support for the new
+[WebDriverBiDi](https://w3c.github.io/webdriver-bidi/) protocol that can be used
+to automate Firefox. The WebDriver BiDi implementation in Firefox will replace
+the current CDP implementation in Firefox in the future. See
+https://pptr.dev/webdriver-bidi for more details.
 
 ## Q: Does Puppeteer support WebDriver BiDi?
 
-Puppeteer has experimental support for WebDriver BiDi with Firefox. You can
-track the implementation progress
-[here](https://puppeteer.github.io/ispuppeteerwebdriverbidiready/).
-
-To launch Firefox with WebDriver BiDi protocol on, use the `protocol` parameter:
-
-```ts
-import puppeteer from 'puppeteer';
-
-const browser = await puppeteer.launch({
-  product: 'firefox',
-  protocol: 'webDriverBiDi',
-});
-const page = await browser.newPage();
-...
-await browser.close();
-```
-
-WebDriver BiDi support for Chrome is still under development.
+Puppeteer has experimental support for WebDriver BiDi. See https://pptr.dev/webdriver-bidi.
 
 ## Q: What are Puppeteer’s goals and principles?
 

diff --git a/docs/webdriver-bidi.md b/docs/webdriver-bidi.md
@@ -1,18 +1,26 @@
 # Experimental WebDriver BiDi Support
 
 [WebDriver BiDi](https://w3c.github.io/webdriver-bidi/) is a new cross-browser
-automation protocol that extends WebDriver with events. Here are the resources if you want to learn more about WebDriver BiDi:
+automation protocol that adds browser-driven events to WebDriver. Here are the
+resources if you want to learn more about WebDriver BiDi:
 
 - [WebDriver BiDi - The future of cross-browser automation](https://developer.chrome.com/articles/webdriver-bidi/)
 - [WebDriver BiDi: 2023 status update](https://developer.chrome.com/blog/webdriver-bidi-2023/)
 
-
 ## Automate with Chrome and Firefox
 
-supporting WebDriver BiDi whenever possible and currently has experimental
-Puppeteer aims at support for automating Firefox and Chrome over WebDriver BiDi. Firefox
-support almost reaching feature parity with the previous CDP-based
-implementation.
+Firefox support has almost reaching feature parity with the previous CDP-based
+implementation. To see which features are fully supported with WebDriver BiDi we
+used the [Puppeteer test suite](https://puppeteer.github.io/ispuppeteerwebdriverbidiready/). Currently,
+we still have [60](https://puppeteer.github.io/ispuppeteerwebdriverbidiready/firefox-delta.json) tests
+that are failing with Firefox and WebDriver BiDi compared to the previous CDP
+implementation in Firefox but we also have [82](https://puppeteer.github.io/ispuppeteerwebdriverbidiready/firefox-delta.json)
+new tests that work with WebDriver BiDi and that didn't work with CDP.
+
+For Chrome, around 68% of the tests are currently passing with WebDriver BiDi so
+the CDP-based implementation remains more powerful. Some of the Puppeteer
+functionality is relying on CDP even with WebDriver BiDi enabled. Therefore, the
+test pass rate is currently higher than that one of Firefox.
 
 Example of launching Firefox with WebDriver BiDi:
 
@@ -44,81 +52,136 @@ await browser.close();
 
 ## Puppeteer features supported over WebDriver BiDi
 
-- Frame.goto() (except `referer` and `referrerPolicy``)
-- Page.$ (ARIA selectors only supported in Chrome)
-- Page.$$ (ARIA selectors only supported in Chrome)
-- Page.$eval (ARIA selectors only supported in Chrome)
-- Page.$$eval (ARIA selectors only supported in Chrome)
-- Page.setViewport (width, height, dpr only)
-- Page.screenshot (not all attributes)
-- Page.createPDFStream (partial support)
-- Page.waitForSelector (ARIA selectors only supported in Chrome)
+- Browser and page automation
+
+  - Puppeteer.launch
+  - Browser.close
+  - Page.bringToFront
+  - Page.goto
+  - Page.reload (except for `ignoreCache` parameter)
+  - Page.setViewport (`width`, `height`, `deviceScaleFactor` only)
+
+- [Script evaluation](https://pptr.dev/guides/evaluate-javascript):
+
+  - Page.evaluate
+  - Page.exposeFunction
+  - JSHandle.evaluate
+  - JSHandle.evaluateHandle
+
+- [Selectors](https://pptr.dev/guides/query-selectors) and [locators](https://pptr.dev/guides/locators) except for ARIA:
+
+  - Page.$ (ARIA selectors only supported in Chrome)
+  - Page.$$ (ARIA selectors only supported in Chrome)
+  - Page.$eval (ARIA selectors only supported in Chrome)
+  - Page.$$eval (ARIA selectors only supported in Chrome)
+  - Frame.goto() (except `referer` and `referrerPolicy`)
+  - Page.waitForSelector (ARIA selectors only supported in Chrome)
+
+- Input
+
+  - ElementHandle.click
+  - Keyboard.down
+  - Keyboard.press
+  - Keyboard.sendCharacter
+  - Keyboard.type
+  - Keyboard.up
+  - Mouse events (except for dedicated drag'n'drop API methods)
+  - TouchScreen.\*
+  - Page.tap
+
+- JavaScript dialog interception
+
+  - page.on('dialog')
+  - Dialog.\*
+
+- Screenshots (not all parameters are supported)
+
+  - Page.screenshot (supported parameters `clip`, `encoding`, `fullPage`)
+
+- PDF generation (not all parameters are supported)
+
+  - Page.pdf (only `format`, `height`, `landscape`, `margin`, `pageRanges`, `printBackground`, `scale`, `width` are supported)
+  - Page.createPDFStream (only `format`, `height`, `landscape`, `margin`, `pageRanges`, `printBackground`, `scale`, `width` are supported)
 
 ## Puppeteer features not yet supported over WebDriver BiDi
 
-- Browser.userAgent()
-- BrowserContext.overridePermissions()
-- BrowserContext.clearPermissionOverrides()
-- ElementHandle.uploadFile()
-- Frame.isOOPFrame()
-- Frame.waitForDevicePrompt()
+- [Request interception](https://pptr.dev/guides/request-interception)
+
+  - HTTPRequest.client()
+  - HTTPRequest.continueRequestOverrides()
+  - HTTPRequest.responseForRequest()
+  - HTTPRequest.abortErrorReason()
+  - HTTPRequest.interceptResolutionState()
+  - HTTPRequest.isInterceptResolutionHandled()
+  - HTTPRequest.finalizeInterceptions()
+  - HTTPRequest.failure()
+  - HTTPRequest.continue()
+  - HTTPRequest.respond()
+  - HTTPRequest.abort()
+  - Page.setRequestInterception()
+
+- Permissions
+
+  - BrowserContext.overridePermissions()
+  - BrowserContext.clearPermissionOverrides()
+
+- Various emulations (most are only supported with Chrome)
+
+  - Page.emulate() (supported only in Chrome)
+  - Page.setJavaScriptEnabled() (supported only in Chrome)
+  - Page.setBypassCSP() (supported only in Chrome)
+  - Page.emulateMediaType() (supported only in Chrome)
+  - Page.emulateCPUThrottling() (supported only in Chrome)
+  - Page.emulateMediaFeatures() (supported only in Chrome)
+  - Page.emulateTimezone() (supported only in Chrome)
+  - Page.emulateIdleState() (supported only in Chrome)
+  - Page.emulateVisionDeficiency() (supported only in Chrome)
+  - Page.setCacheEnabled() (supported only in Chrome)
+  - Page.setGeolocation() (supported only in Chrome)
+
+- CDP-specific features
+
+  - Page.createCDPSession() (supported only in Chrome)
+
 - Tracing (supported only in Chrome)
 - Coverage (supported only in Chrome)
 - Accessibility (supported only in Chrome)
-- Target.opener()
-- HTTPResponse.securityDetails()
-- HTTPResponse.buffer()
-- HTTPResponse.fromServiceWorker()
-- Input.drag()
-- Input.dragOver()
-- Input.drop()
-- Input.dragAndDrop()
-- HTTPRequest.client()
-- HTTPRequest.continueRequestOverrides()
-- HTTPRequest.responseForRequest()
-- HTTPRequest.abortErrorReason()
-- HTTPRequest.interceptResolutionState()
-- HTTPRequest.isInterceptResolutionHandled()
-- HTTPRequest.finalizeInterceptions()
-- HTTPRequest.failure()
-- HTTPRequest.continue()
-- HTTPRequest.respond()
-- HTTPRequest.abort()
-- PageEvent.popup
-- PageEvent.WorkerCreated
-- PageEvent.WorkerDestroyed
-- Page.isServiceWorkerBypassed()
-- Page.isDragInterceptionEnabled()
-- Page.isJavaScriptEnabled() (supported only in Chrome)
-- Page.waitForFileChooser()
-- Page.setGeolocation() (supported only in Chrome)
-- Page.createCDPSession() (supported only in Chrome)
-- Page.workers()
-- Page.setRequestInterception()
-- Page.setBypassServiceWorker()
-- Page.setDragInterception()
-- Page.setOfflineMode()
-- Page.emulateNetworkConditions()
-- Page.queryObjects() (supported only in Chrome)
-- Page.cookies()
-- Page.deleteCookie()
-- Page.setCookie()
-- Page.authenticate()
-- Page.setExtraHTTPHeaders()
-- Page.setUserAgent()
-- Page.metrics()
-- Page.goBack()
-- Page.goForward()
-- Page.emulate() (supported only in Chrome)
-- Page.setJavaScriptEnabled() (supported only in Chrome)
-- Page.setBypassCSP() (supported only in Chrome)
-- Page.emulateMediaType() (supported only in Chrome)
-- Page.emulateCPUThrottling() (supported only in Chrome)
-- Page.emulateMediaFeatures() (supported only in Chrome)
-- Page.emulateTimezone() (supported only in Chrome)
-- Page.emulateIdleState() (supported only in Chrome)
-- Page.emulateVisionDeficiency() (supported only in Chrome)
-- Page.setCacheEnabled() (supported only in Chrome)
-- Page.screencast() (supported only in Chrome)
-- Page.tap()
-- Page.waitForDevicePrompt()
+
+- Other methods:
+
+  - Browser.userAgent()
+  - ElementHandle.uploadFile()
+  - Frame.isOOPFrame()
+  - Frame.waitForDevicePrompt()
+  - Target.opener()
+  - HTTPResponse.securityDetails()
+  - HTTPResponse.buffer()
+  - HTTPResponse.fromServiceWorker()
+  - Input.drag()
+  - Input.dragOver()
+  - Input.drop()
+  - Input.dragAndDrop()
+  - PageEvent.popup
+  - PageEvent.WorkerCreated
+  - PageEvent.WorkerDestroyed
+  - Page.isServiceWorkerBypassed()
+  - Page.isDragInterceptionEnabled()
+  - Page.isJavaScriptEnabled() (supported only in Chrome)
+  - Page.waitForFileChooser()
+  - Page.workers()
+  - Page.setBypassServiceWorker()
+  - Page.setDragInterception()
+  - Page.setOfflineMode()
+  - Page.emulateNetworkConditions()
+  - Page.queryObjects() (supported only in Chrome)
+  - Page.cookies()
+  - Page.deleteCookie()
+  - Page.setCookie()
+  - Page.authenticate()
+  - Page.setExtraHTTPHeaders()
+  - Page.setUserAgent()
+  - Page.metrics()
+  - Page.goBack()
+  - Page.goForward()
+  - Page.screencast() (supported only in Chrome)
+  - Page.waitForDevicePrompt()