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

* adds session.subscribe page

* edits for better phrasing

* adds session.unsubscribe page, plus consistency edits to subscribe page

* updates webdriver landing page

* adds how to page

* adds how-to to sidebar

* fixes tech review comments

* minor updates

* address tech review comments

* address tech review comments

* tweak how-to intro

* add links for existing capability pages

* Apply suggestions from code review

Co-authored-by: Dipika Bhattacharya <dipika@foss-community.org>

* fix lint errors

Author: dipikabh

files/en-us/web/webdriver/how_to/create_bidi_connection/index.md

@@ -0,0 +1,54 @@
+---
+title: Create a WebDriver BiDi connection
+short-title: Create a BiDi connection
+slug: Web/WebDriver/How_to/Create_BiDi_connection
+page-type: how-to
+sidebar: webdriver
+---
+
+The client and the browser communicate using the WebDriver BiDi protocol over a WebSocket connection. There are two ways a client can establish this connection.
+
+In one method, when creating a classic WebDriver session, the WebDriver client sets the [`webSocketUrl`](/en-US/docs/Web/WebDriver/Reference/Capabilities/webSocketUrl) capability to `true` to request BiDi to be enabled; the client then starts the browser with the WebSocket port open.
+
+In the other method, the WebDriver client starts the browser from the command line by passing the required flag and the desired port. This method works with Firefox directly; however, Chromium-based browsers require the additional Chromium BiDi wrapper package. The sections in this article walk you through this method using Firefox.
+
+## Launching the browser
+
+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, or specify `0` to let the system assign a free port automatically.
+
+```bash
+firefox --remote-debugging-port 9222
+```
+
+On macOS, `firefox` may not be in your PATH. In that case, use the full path instead:
+
+```bash
+/Applications/Firefox.app/Contents/MacOS/firefox --remote-debugging-port 9222
+```
+
+## Getting the WebSocket URL
+
+Firefox exposes the BiDi WebSocket directly at:
+
+```plain
+ws://127.0.0.1:PORT/session
+```
+
+For example, if you launched Firefox with `--remote-debugging-port 9222`, the URL is `ws://127.0.0.1:9222/session`. If you specified port `0`, check the `stderr` output for a message like `WebDriver BiDi listening on ws://127.0.0.1:46249` to find the assigned port.
+
+> [!NOTE]
+> Firefox uses `127.0.0.1` rather than `localhost` for the BiDi WebSocket endpoint.
+
+## Connecting to the WebSocket endpoint
+
+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](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules#commands) as JSON messages and receive responses and [events](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules#events) from the browser. See [`session.new`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/session/new) to create a BiDi session after connecting.
+
+## See also
+
+- [WebDriver BiDi reference](/en-US/docs/Web/WebDriver/Reference/BiDi)
+- [`session.new`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/session/new) command
+- [WebSockets API](/en-US/docs/Web/API/WebSockets_API)
+- [Chromium BiDi wrapper](https://github.com/GoogleChromeLabs/chromium-bidi)
+- [WebDriver BiDi web client](https://firefox-dev.tools/bidi-web-client/web/)

files/en-us/web/webdriver/how_to/index.md

@@ -0,0 +1,11 @@
+---
+title: WebDriver how to
+short-title: How to
+slug: Web/WebDriver/How_to
+page-type: listing-page
+sidebar: webdriver
+---
+
+This page lists how-to guides for WebDriver.
+
+{{SubpagesWithSummaries}}

files/en-us/web/webdriver/index.md

@@ -5,64 +5,32 @@ page-type: landing-page
 sidebar: webdriver
 ---
 
-WebDriver is a remote control interface that enables introspection and control of user agents. It provides a platform- and language-neutral wire protocol as a way for out-of-process programs to remotely instruct the behavior of web browsers.
+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 intended to allow web authors to write tests to automate a browser from a separate controlling process.
 
-Provided is a set of interfaces to discover and manipulate DOM elements in web documents and to control the behavior of a user agent. It is primarily intended to allow web authors to write tests that automate a user agent from a separate controlling process, but may also be used in such a way as to allow in-browser scripts to control a — possibly separate — browser.
-
-## Usage
-
-So what does WebDriver let you do and what does it look like? Since WebDriver is programming language neutral, the answer to this question depends on which WebDriver client you're using and the choice of language.
-
-But using a popular client written in Python, your interaction with WebDriver might look like this:
-
-```python
-from selenium import webdriver
-from selenium.webdriver.common.by import By
-from selenium.webdriver.common.keys import Keys
-from selenium.webdriver.support.ui import WebDriverWait
-from selenium.webdriver.support.expected_conditions import presence_of_element_located
-
-with webdriver.Firefox() as driver:
-
-    driver.get("https://google.com/ncr")
-    wait = WebDriverWait(driver, 10)
-    driver.find_element(By.NAME, "q").send_keys(f"cheese{Keys.RETURN}")
-    wait.until(presence_of_element_located((By.XPATH, '//*[@id="rcnt"]')))
-    results = driver.find_elements(By.XPATH, "//a[@href]")
-
-    for i, elem in enumerate(results):
-        print(f'#{i} {elem.text} ({elem.get_attribute("href")})')
-```
-
-This might produce output akin to this:
-
-```plain
-#1 Cheese - Wikipedia (https://en.wikipedia.org/wiki/Cheese)
-```
+WebDriver is available in two variants: [WebDriver classic](/en-US/docs/Web/WebDriver/Reference/Classic) that uses HTTP, and [WebDriver BiDi](/en-US/docs/Web/WebDriver/Reference/BiDi) that uses WebSocket and enables bidirectional, event-driven communication.
 
 ## Reference
 
 Browse the complete [WebDriver reference](/en-US/docs/Web/WebDriver/Reference) documentation.
 
-### WebDriver classic reference
+- [WebDriver BiDi](/en-US/docs/Web/WebDriver/Reference/BiDi)
+  - : Reference for WebDriver BiDi modules, commands, and events.
 
-- [Commands](/en-US/docs/Web/WebDriver/Reference/Classic/Commands)
-  - : Reference for all WebDriver classic commands.
+- [WebDriver classic](/en-US/docs/Web/WebDriver/Reference/Classic)
+  - : Reference for WebDriver classic commands and timeouts.
 
 - [Capabilities](/en-US/docs/Web/WebDriver/Reference/Capabilities)
-  - : Reference for all WebDriver classic capabilities.
+  - : Reference for WebDriver capabilities.
 
 - [Errors](/en-US/docs/Web/WebDriver/Reference/Errors)
-  - : Reference for WebDriver classic errors.
-
-- [Timeouts](/en-US/docs/Web/WebDriver/Reference/Classic/Timeouts)
-  - : Reference for WebDriver classic timeouts.
+  - : Reference for WebDriver errors.
 
 ## Specifications
 
 - [WebDriver](https://w3c.github.io/webdriver/)
+- [WebDriver BiDi](https://w3c.github.io/webdriver-bidi/)
 
 ## See also
 

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

@@ -65,3 +65,7 @@ The following is a sample event message sent by the browser when the client is s
 ## Browser compatibility
 
 {{Compat}}
+
+## See also
+
+- [WebDriver BiDi web client](https://firefox-dev.tools/bidi-web-client/web/)

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

@@ -34,7 +34,7 @@ The `result` field in the response is an empty object (`{}`).
 
 ### Ending an automation session with the browser
 
-With a WebDriver BiDi connection established, send the following message to end the current session:
+With a [WebDriver BiDi connection](/en-US/docs/Web/WebDriver/How_to/Create_BiDi_connection) established, send the following message to end the current session:
 
 ```json
 {

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

@@ -41,7 +41,7 @@ The `params` field contains:
 
 The `alwaysMatch` and `firstMatch` objects can include the following features:
 
-- `acceptInsecureCerts` {{optional_inline}}
+- [`acceptInsecureCerts`](/en-US/docs/Web/WebDriver/Reference/Capabilities/acceptInsecureCerts) {{optional_inline}}
   - : A boolean that indicates whether untrusted TLS certificates (for example, self-signed or expired) are accepted for the duration of the session.
 - `browserName` {{optional_inline}}
   - : A string that specifies the name of the browser to use (for example, `"firefox"` or `"chrome"`).
@@ -62,7 +62,7 @@ The following fields in the `result` object of the response describe the charact
   - : A string that contains the unique identifier for the newly created session.
 - `capabilities`
   - : An object that describes the capabilities that were negotiated and are active for the session. It includes the following fields:
-    - `acceptInsecureCerts`
+    - [`acceptInsecureCerts`](/en-US/docs/Web/WebDriver/Reference/Capabilities/acceptInsecureCerts)
       - : A boolean that indicates whether untrusted TLS certificates (for example, self-signed or expired) are accepted for the duration of the session.
     - `browserName`
       - : A string that contains the name of the browser.
@@ -78,7 +78,7 @@ The following fields in the `result` object of the response describe the charact
       - : An object that describes the active proxy configuration. An empty object (`{}`) indicates no proxy is configured.
     - `unhandledPromptBehavior` {{optional_inline}}
       - : An object that describes the default behavior when a user prompt (such as an `alert`, `confirm`, or `prompt` dialog) is encountered during a command. This field is present only when specified in the `capabilities` parameter.
-    - `webSocketUrl` {{optional_inline}}
+    - [`webSocketUrl`](/en-US/docs/Web/WebDriver/Reference/Capabilities/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).

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

@@ -41,7 +41,7 @@ The `result` object in the response with the following fields:
 
 ### Checking browser status before creating a session
 
-With a WebDriver BiDi connection established, send the following message to check whether the browser is ready to create a new session:
+With a [WebDriver BiDi connection](/en-US/docs/Web/WebDriver/How_to/Create_BiDi_connection) established, send the following message to check whether the browser is ready to create a new session:
 
 ```json
 {

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

@@ -0,0 +1,153 @@
+---
+title: session.subscribe command
+short-title: session.subscribe
+slug: Web/WebDriver/Reference/BiDi/Modules/session/subscribe
+page-type: webdriver-command
+browser-compat: webdriver.bidi.session.subscribe
+sidebar: webdriver
+---
+
+The `session.subscribe` [command](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules#commands) of the [`session`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/session) module registers the client to receive events asynchronously, either per event or per module, globally or scoped to specific contexts.
+
+## Syntax
+
+```json-nolint
+{
+  "method": "session.subscribe",
+  "params": {
+    "events": ["<event name>"]
+  }
+}
+```
+
+### Parameters
+
+The `params` field contains:
+
+- `events`
+  - : An array of one or more event name strings. Use a module name (for example, `"log"`) to subscribe to all events in that module or a specific event name (for example, `"log.entryAdded"`) to subscribe to only that event.
+- `contexts` {{optional_inline}}
+  - : An array of one or more context IDs ([UUIDs](/en-US/docs/Glossary/UUID)), each corresponding to a tab or frame.
+    If specified, events are received only for those contexts and their descendants.
+    If the context ID corresponds to a frame, the subscription is created for the top-level context (tab) that owns the frame.
+
+    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 context or container.
+    If specified, events are received only for those user contexts.
+
+    This field cannot be used if `contexts` is also specified.
+
+If neither `contexts` nor `userContexts` is provided, the subscription is global, so events are received for all contexts.
+
+### Return value
+
+The `result` field in the response is an object with the following field:
+
+- `subscription`
+  - : A string that contains the unique identifier for this subscription.
+
+### Errors
+
+- [`invalid argument`](/en-US/docs/Web/WebDriver/Reference/Errors/InvalidArgument)
+  - : Thrown in any of the following cases:
+    - The `events` array is empty, omitted, or contains an unrecognized event name.
+    - `contexts` or `userContexts` is provided but empty.
+    - Both `contexts` and `userContexts` are provided in the same request.
+    - A parameter value has an invalid type.
+
+## Examples
+
+### Subscribing to an event globally
+
+With a [WebDriver BiDi connection](/en-US/docs/Web/WebDriver/How_to/Create_BiDi_connection) and an [active session](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/session/new), send the following message to subscribe to the `log.entryAdded` event for all contexts:
+
+```json
+{
+  "id": 2,
+  "method": "session.subscribe",
+  "params": {
+    "events": ["log.entryAdded"]
+  }
+}
+```
+
+The browser responds with a subscription ID as follows:
+
+```json
+{
+  "id": 2,
+  "type": "success",
+  "result": {
+    "subscription": "c7b7b3a2-1f4b-4b4e-8a1f-2a3b4c5d6e7f"
+  }
+}
+```
+
+### Subscribing to multiple events globally
+
+With a [WebDriver BiDi connection](/en-US/docs/Web/WebDriver/How_to/Create_BiDi_connection) and an [active session](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/session/new), send the following message to subscribe to all events in the `log` module and a specific event from the `network` module:
+
+```json
+{
+  "id": 3,
+  "method": "session.subscribe",
+  "params": {
+    "events": ["log", "network.beforeRequestSent"]
+  }
+}
+```
+
+The browser responds with a subscription ID as follows:
+
+```json
+{
+  "id": 3,
+  "type": "success",
+  "result": {
+    "subscription": "e9d0a5c4-3h6d-6d6g-0c3h-4c5d6e7f8g9h"
+  }
+}
+```
+
+### Subscribing to events scoped to a tab
+
+Suppose your automation has two tabs open — one for the homepage and another for the checkout page. To receive `log.entryAdded` events only from the Checkout tab, send the following message with that tab's context ID:
+
+```json
+{
+  "id": 4,
+  "method": "session.subscribe",
+  "params": {
+    "events": ["log.entryAdded"],
+    "contexts": ["9b4e2f1a-3c7d-4b8e-a2f5-6d1c9e3b7f4a"]
+  }
+}
+```
+
+The browser responds with a subscription ID as follows:
+
+```json
+{
+  "id": 4,
+  "type": "success",
+  "result": {
+    "subscription": "a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d"
+  }
+}
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [`session.unsubscribe`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/session/unsubscribe) command
+- [`session.new`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/session/new) command
+- [`session.end`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/session/end) command