[Editorial review] BiDi - Add pages for new, status, and end commands of the session module by dipikabh · Pull Request #43251 · mdn/content

dipikabh · 2026-02-25T23:04:39Z

Description

This PR adds the following pages:

session listing page
session.new
session.status
session.end

It also updates:

Modules landing page - adds basic info about how commands and events are structured
WebDriver sidebar (webdriver.yaml)

UPDATE: As part of addressing review feedback, this PR now also adds stub pages for all modules.

Additional details

Since BiDi builds on capabilities and errors defined in Classic, we can share a lot of those pages between the two.
So it might make sense to move them to common location under Web/WebDriver/Reference and out of the folders under Web/WebDriver/Reference/Classic where they currently sit.

I plan to place them directly under Web/WebDriver/Reference so that both Classic and BiDi commands can link to them.
On the individual capability and error pages, we can note any differences in the behavior or format between Classic and BiDi.

I'll make these changes in a separate PR. ✅
UPDATE: Done in #43314

@whimboo pointed out that the top landing page https://developer.mozilla.org/en-US/docs/Web/WebDriver is also in need of an update since the addition of our BiDi section - I'll update this page along with the above structural changes.

Spec links

session.new: https://w3c.github.io/webdriver-bidi/#command-session-new
session.status: https://w3c.github.io/webdriver-bidi/#command-session-status
session.end: https://w3c.github.io/webdriver-bidi/#command-session-end

Related issue

Doc issue: mdn/mdn#339

github-actions · 2026-02-25T23:06:24Z

Preview URLs (21 pages)

Flaws (48)

Note! 19 documents with no flaws that don't need to be listed. 🎉

Found an unexpected or unresolvable flaw? Please report it here.

URL: /en-US/docs/Web/WebDriver/Reference/Capabilities
Title: WebDriver capabilities
Flaw count: 12

broken_links:
- Link /en-US/docs/Web/WebDriver/Reference/Classic/Capabilities/setWindowRect doesn't resolve
- Link /en-US/docs/Web/WebDriver/Reference/Capabilities/browserName doesn't resolve
- Link /en-US/docs/Web/WebDriver/Reference/Capabilities/browserVersion doesn't resolve
- Link /en-US/docs/Web/WebDriver/Reference/Capabilities/platformName doesn't resolve
- Link /en-US/docs/Web/WebDriver/Reference/Capabilities/pageLoadStrategy doesn't resolve
- and 7 more flaws omitted

URL: /en-US/docs/Web/WebDriver/Reference/Errors
Title: WebDriver errors
Flaw count: 36

broken_links:
- Link /en-US/docs/Web/WebDriver/Reference/Errors/UnexpectedAlertOpen doesn't resolve
- Link /en-US/docs/Web/WebDriver/Reference/Errors/UnexpectedAlertOpen doesn't resolve
- Link /en-US/docs/Web/WebDriver/Reference/Clients doesn't resolve
- Link /en-US/docs/Web/WebDriver/Reference/Errors/ElementClickIntercepted doesn't resolve
- Link /en-US/docs/Web/WebDriver/Reference/ElementClick doesn't resolve
- and 31 more flaws omitted

(comment last updated: 2026-03-11 23:26:46)

juliandescottes

This looks great! I'll let Henrik do the final technical review, just one nitpick on my side.

files/sidebars/webdriver.yaml

whimboo

That's a great start with the session module @dipikabh! Very well written with all the details and nice examples. I've some questions and suggestions still, which you can find inline. Please let one of us know when something is unclear, and we can help to clarify.

files/en-us/web/webdriver/reference/bidi/modules/index.md

files/en-us/web/webdriver/reference/bidi/modules/session/index.md

files/en-us/web/webdriver/reference/bidi/modules/session/new/index.md

whimboo · 2026-02-26T17:22:22Z

files/en-us/web/webdriver/reference/bidi/modules/session/new/index.md

+    - `webSocketUrl` {{optional_inline}}
+      - : A string that contains the WebSocket URL for the session.
+
+The browser may also return vendor-specific capabilities prefixed with a browser identifier (for example, `moz:buildID` for Firefox).


I wonder if we can have a separate page for those vendor specific capabilities.

There's a precedent with firefoxOptions for vendor-specific capabilities. However, that's client-sent.

We don't have dedicated pages for browser-sent capabilities. So we might not cover them in that detail. But if important, I can include an example or a note about Firefox-specific metadata included in return value.

Is it that we don't want to cover vendor specific capabilities or what's the reason why we cannot cover them in such a detail? Maybe we could have a separate section on the firefoxOptions page that handles return-only capabilities?

As I understand it, this metadata, moz:buildID, comes under Extensible in the spec - it's an implementation detail that can vary by browser. That said, we do already document firefoxOptions.

It might open the door for other browsers to add content for their return capability parameters.

I'm curious - how many such Firefox-specific fields are there in the return value, and what is the expected level of detail?
Is it something your team can help put together as a first draft and I can edit?

separate section on the firefoxOptions page that handles return-only capabilities

I think if we document return-only capabilities, they would be better as new, separate pages.

Currently we have the following Mozilla specific vendor capabilities:

https://searchfox.org/firefox-main/rev/0894e095dfb46b6dac785365432791a54861fe09/remote/shared/webdriver/Capabilities.sys.mjs#492-497,508-510

Some of them are only returned and others are used for processing capabilities as well (means, they will be fed with the new session command).

Perhaps I can queue up this task for a future date

files/en-us/web/webdriver/reference/bidi/modules/session/new/index.md

whimboo

I think that looks good for the initial landing of the session module. Great additions to have the placeholders for all modules present as well now. Thanks a lot!

dipikabh · 2026-03-02T17:56:22Z

Thanks a lot @whimboo for the tech review and approval!

I've addressed/answered your comments and questions. There is just one more minor update since your last review.

I also have two open questions (here and here) before I invite the content team for an edit review.

github-actions · 2026-03-02T19:34:39Z

This pull request has merge conflicts that must be resolved before it can be merged.

dipikabh · 2026-03-02T20:00:42Z

Rebased this branch to include the changes in #43314, which moves Capabilities and Errors out of Classic.

dipikabh · 2026-03-03T15:28:47Z

Hi Chris, I'd appreciate if you can provide me an editorial review for this when you get a chance. Thanks!

chrisdavidmills

Hey @dipikabh, here's my editorial review!

I think this is largely useful and well-structured. My comments are fairly picky, and some are definitely a result of my inexperience with WebDriver BiDi. Still worth asking through, IMO.

I was approaching these articles as a beginner (which I am) while trying to put myself in the mindset of someone with previous BiDi experience, and thinking about what they might need.

files/en-us/web/webdriver/reference/bidi/modules/bluetooth/index.md

files/en-us/web/webdriver/reference/bidi/modules/emulation/index.md

files/en-us/web/webdriver/reference/bidi/modules/webextension/index.md

files/sidebars/webdriver.yaml

files/en-us/web/webdriver/reference/bidi/modules/index.md

files/en-us/web/webdriver/reference/bidi/modules/session/new/index.md

files/en-us/web/webdriver/reference/bidi/modules/session/status/index.md

dipikabh · 2026-03-11T03:23:25Z

Thanks for the thorough review, Chris! Lots of food for thought.
I'll tackle the remaining comments in session/new tomorrow.

chrisdavidmills

OK, I'm pretty happy with this now, @dipikabh, so I'm approving from an editorial standpoint.

You've done a great job on this first set of documentation for WebDriver BiDi. It's obviously an unknown for us on the MDN team, and there will likely be things you'll want to improve on later after you've had some wider feedback. But for now, I think this is more than good enough to publish.

Good work.

dipikabh · 2026-03-12T13:19:59Z

Thanks so much, @chrisdavidmills! Your feedback has helped me think through the phrasing and details to look out for. It'll definitely help as I work through more BiDi pages.
Really appreciate the thoughtful review.

there will likely be things you'll want to improve on later after you've had some wider feedback.

Agree, that's always the case

dipikabh requested a review from a team February 25, 2026 23:04

dipikabh requested review from a team as code owners February 25, 2026 23:04

dipikabh requested review from hamishwillee and pepelsbey and removed request for a team February 25, 2026 23:04

github-actions bot added the Content:WebDriver WebDriver docs label Feb 25, 2026

dipikabh removed request for hamishwillee and pepelsbey February 25, 2026 23:04

github-actions bot added the size/m [PR only] 51-500 LoC changed label Feb 25, 2026

juliandescottes reviewed Feb 26, 2026

View reviewed changes

files/sidebars/webdriver.yaml Outdated Show resolved Hide resolved

whimboo requested changes Feb 26, 2026

View reviewed changes

github-actions bot added size/l [PR only] 501-1000 LoC changed and removed size/m [PR only] 51-500 LoC changed labels Feb 27, 2026

whimboo approved these changes Mar 2, 2026

View reviewed changes

github-actions bot added the merge conflicts 🚧 [PR only] label Mar 2, 2026

dipikabh added 10 commits March 2, 2026 14:39

adds bidi folder, initial landing pages

4a57f87

fixes page-types

b5adf94

updates to organize docs by modules

fd2e198

adds pages for session commands new, end, and status

cc4bf01

fixes broken links

8a52403

fixes comments in modules page

7cb5c6b

adds stubs for all modules

974e561

updates sidebar

2309d70

adds stubs for three more modules

629a98c

adds stub for one more module

fa06e36

dipikabh added 2 commits March 2, 2026 14:55

fixes comments in session landing page

99bf04f

fixes comments in session.new page

4c1ac73

dipikabh force-pushed the bidi-session-commands1 branch from f88503e to 4c1ac73 Compare March 2, 2026 19:58

github-actions bot removed the merge conflicts 🚧 [PR only] label Mar 2, 2026

updates example prose

9c7a422

dipikabh changed the title ~~[Technical review] BiDi - Add pages for new, status, and end commands of the session module~~ [Editorial review] BiDi - Add pages for new, status, and end commands of the session module Mar 3, 2026

dipikabh requested a review from chrisdavidmills March 3, 2026 15:27

dipikabh mentioned this pull request Mar 5, 2026

[Technical review] BiDi - add pages for session module's subscribe, unsubscribe commands and a how-to #43343

Open

chrisdavidmills requested changes Mar 9, 2026

View reviewed changes

dipikabh added 3 commits March 10, 2026 11:47

addresses review feedback

9124c3d

addresses review feedback plus sidebar updates

8334dc6

updates the landing pages for caps and errs

c462c70

addresses review feedback

b75c5fa

dipikabh requested a review from chrisdavidmills March 12, 2026 02:06

chrisdavidmills approved these changes Mar 12, 2026

View reviewed changes

dipikabh merged commit fbf7337 into mdn:main Mar 12, 2026
8 checks passed

Conversation

dipikabh commented Feb 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Additional details

Spec links

Related issue

Uh oh!

github-actions bot commented Feb 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

juliandescottes left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

whimboo left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

whimboo Feb 26, 2026

Choose a reason for hiding this comment

Uh oh!

dipikabh Mar 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

whimboo Mar 2, 2026

Choose a reason for hiding this comment

Uh oh!

dipikabh Mar 3, 2026

Choose a reason for hiding this comment

Uh oh!

whimboo Mar 3, 2026

Choose a reason for hiding this comment

Uh oh!

dipikabh Mar 11, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

whimboo left a comment

Choose a reason for hiding this comment

Uh oh!

dipikabh commented Mar 2, 2026

Uh oh!

github-actions bot commented Mar 2, 2026

Uh oh!

dipikabh commented Mar 2, 2026

Uh oh!

dipikabh commented Mar 3, 2026

Uh oh!

chrisdavidmills left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

dipikabh commented Mar 11, 2026

Uh oh!

chrisdavidmills left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dipikabh commented Mar 12, 2026

Uh oh!

Uh oh!

dipikabh commented Feb 25, 2026 •

edited

Loading

github-actions bot commented Feb 25, 2026 •

edited

Loading

dipikabh Mar 2, 2026 •

edited

Loading

chrisdavidmills left a comment •

edited

Loading

chrisdavidmills left a comment •

edited

Loading