[Technical review] BiDi - add pages for session module's subscribe, unsubscribe commands and a how-to#43343
[Technical review] BiDi - add pages for session module's subscribe, unsubscribe commands and a how-to#43343
Conversation
dipikabh
requested review from
chrisdavidmills and
pepelsbey
and removed request for
a team
github-actions
bot
added
Content:WebDriver
|
Preview URLs (5 pages)
External URLs (1)URL:
(comment last updated: 2026-03-12 19:23:28) |
| sidebar: webdriver | ||
| --- | ||
|
|
||
| This page lists how-to guides for WebDriver. |
There was a problem hiding this comment.
Do you already have in mind how you want to structure the page by differentiating between WebDriver Classic and BiDi?
|
|
||
| ## Launching the browser with remote debugging enabled | ||
|
|
||
| To use WebDriver BiDi, you need to enable it in the browser by launching it with the `--remote-debugging-port` flag. The browser then listens for incoming WebSocket connections on the specified port. Port `9222` is a conventional default for browser debugging, but you can use any available port. |
There was a problem hiding this comment.
Just for clarity the initial connection is based on HTTP and we run a WebSocket upgrade over the same connection when the client connects. We could just reference https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/Protocol_upgrade_mechanism#upgrading_to_a_websocket_connection here.
| ``` | ||
|
|
||
| > [!NOTE] | ||
| > For Chrome, enabling WebDriver BiDi requires a different setup using ChromeDriver with the `webSocketUrl` capability. |
There was a problem hiding this comment.
Based on that note we should most likely split the how to in the following two sections:
-
Request to enable WebDriver BiDi via the
webSocketUrlcapability when creating a new WebDriver classic session. With the capability set totruethe webdriver client will make sure to start the relevant browser with the extra port open, which then can be used to upgrade to a WebSocket connection. This applies to all existing browsers including Firefox with geckodriver. -
A BiDi-only connection can be established as you described above. It is the client that have to correctly start the browser with the required command line argument set to open the connection at the given port. For Firefox no other binary is needed but Chrome and its derivates require the Chromium BiDi wrapper package. A client can also specify the port as
0which will allow the browser to use a freely chosen port by the system to avoid port collisions in case multiple Firefox processes run in parallel. To know which port has been chosen the client needs to listen to stderr and check forWebDriver BiDi listening on ws://127.0.0.1:46249(example from a Puppeteer job).
| > [!NOTE] | ||
| > For Chrome, enabling WebDriver BiDi requires a different setup using ChromeDriver with the `webSocketUrl` capability. | ||
|
|
||
| ## Getting the WebSocket URL |
There was a problem hiding this comment.
As pointed out in the other comment the real ws URL can be scraped from the stderr output in case of a BiDi-only connection.
If there is a BiDi-upgrade via a classic session the WebSocket URL is returned in the webSocketUrl capability. Note that in this case we return a URL specific to the WebDriver session as created by WebDriver classic.
|
|
||
| With the WebSocket URL, use any WebSocket client to open a connection. Common options include the `ws` package for Node.js and the `websockets` package for Python. | ||
|
|
||
| Once connected, you can send WebDriver BiDi commands as JSON messages and receive responses and events from the browser. See [`session.new`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/session/new) to create a BiDi session after connecting. |
There was a problem hiding this comment.
Feel free to as well reference our online WebDriver BiDi demo client.
| If specified, events are received only for those contexts and their descendants. | ||
| This field cannot be used if `userContexts` is also specified. | ||
| - `userContexts` {{optional_inline}} | ||
| - : An array of one or more user context IDs, each corresponding to a browser profile or container. |
There was a problem hiding this comment.
| - : An array of one or more user context IDs, each corresponding to a browser profile or container. | |
| - : An array of one or more user context IDs, each corresponding to a browser context or container. |
I wouldn't use the term profile here given that it would give a false indication. In terms of Chrome it is called a Browser Context while in Firefox we use Container.
|
|
||
| ### Return value | ||
|
|
||
| An object with the following fields: |
There was a problem hiding this comment.
| An object with the following fields: | |
| An object with the following field: |
... but if it's always used in plural form it will be fine as well.
| ### Errors | ||
|
|
||
| - [invalid argument](/en-US/docs/Web/WebDriver/Reference/Errors/InvalidArgument) | ||
| - : The `events` array is empty or omitted, an event name is not recognized, `contexts` or `userContexts` is provided but empty, or values for both `contexts` and `userContexts` were provided in the same request. |
There was a problem hiding this comment.
This also includes invalid types or out of bounds values as used for any of the parameters.
|
|
||
| ### Subscribing to an event globally | ||
|
|
||
| With a WebDriver BiDi connection and an active session, send the following message to subscribe to the `log.entryAdded` event for all browsing contexts: |
There was a problem hiding this comment.
Should we link the WebDriver BiDi connection to the HowTo?
| } | ||
| ``` | ||
|
|
||
| ### Subscribing to multiple events |
There was a problem hiding this comment.
| ### Subscribing to multiple events | |
| ### Subscribing to multiple events globally |
At least one other example would be nice when subscribing to a given context or user context.
juliandescottes
left a comment
juliandescottes
left a comment
There was a problem hiding this comment.
Looks great, just one comment on my side regarding the session.subscribe behavior.
| - : An array of one or more browsing context IDs, each corresponding to a tab or frame. | ||
| If specified, events are received only for those contexts and their descendants. |
There was a problem hiding this comment.
One thing to clarify here, is that even if the command accepts frames as contexts, the subscription will be created for the top level navigable which owns the frame.
See steps 8.1 & 8.2 of https://w3c.github.io/webdriver-bidi/#command-session-subscribe
| WebDriver is a browser automation interface that allows external programs to remotely inspect and control a browser. It is a platform- and language-neutral wire protocol, supporting both command-based automation and real-time, event-driven communication. | ||
|
|
||
| To have the ability to write instruction sets that can be run interchangeably in many browsers on different platforms is critical to deliver a consistent experience to users. With the new wave of developments on the web platform, the increase diversity in devices and demands for real interoperability between the technologies, WebDriver provides tooling for [cross-browser testing](/en-US/docs/Learn_web_development/Extensions/Testing/Introduction). | ||
| WebDriver provides tooling for [cross-browser testing](/en-US/docs/Learn_web_development/Extensions/Testing/Introduction), helping teams deliver consistent user experiences across many browsers and platforms. It is primarily intended to allow web authors to write tests to automate a browser from a separate controlling process, though it can also be used from scripts running within the browser itself. |
There was a problem hiding this comment.
though it can also be used from scripts running within the browser itself
I am not sure which scenario this corresponds to. There might be edge cases where you can achieve this setup but that's probably not what mainstream webdriver usage will look like and mentioning it here would be confusing.
Note: I see we previously had the following text: but may also be used in such a way as to allow in-browser scripts to control a — possibly separate — browser., but similarly I think this is/was confusing and should probably not be part of the landing page.
dipikabh
force-pushed
the
bidi-session-commands2
branch
from
a3af2ee to
2b924bc
Compare
|
Rebased this branch on main after #43251 merging |
4 participants
Description
This PR is a continuation of #43251 to document the remaining commands of the session module:
session.subscribesession.unsubscribeIt also adds a how-to page to explain creating a WebDriver BiDi connection.
Additionally, it updates the WebDriver landing page to rewrite the intro in simpler language, remove the usage example, and add BiDi to the Reference section.
Additional details
The pages in this PR cross-link to
session.new,session.end,sessionmodule, which are included in #43251.Those links will resolve once that PR merges.
Related issue
Doc issue: mdn/mdn#339