[doc] testdriver bidi documentation (#49098)

* Extend testdriver documentation with **BiDi** section.
* Improve jsdoc for bidi methods.

docs/writing-tests/testdriver.md

@@ -27,6 +27,35 @@ document when using testdriver from a different context):
 <script src="/resources/testdriver-vendor.js"></script>
 ```
 
+## WebDriver BiDi ##
+
+The api in `test_driver.bidi` provides access to the
+[WebDriver BiDi](https://w3c.github.io/webdriver-bidi) protocol.
+
+### Context ###
+
+A WebDriver BiDi "browsing context" is equivalent to an
+[HTML navigable](https://html.spec.whatwg.org/multipage/document-sequences.html#navigable).
+In WebDriver BiDi, you can interact with any browsing context, regardless of whether
+it's currently active. You can target a specific browsing context using either its
+unique string ID or its `WindowProxy` object.
+
+```eval_rst
+:Context: (*String|WindowProxy*)  A browsing context. Can be specified by its ID
+          (a string) or using a `WindowProxy` object.
+```
+
+### Events ###
+
+To receive WebDriver BiDi [events](https://w3c.github.io/webdriver-bidi/#events), you
+need to subscribe to them. Events are only emitted for browsing contexts with an
+active subscription. You can also create a global subscription to receive events from
+all the contexts.
+
+If there are
+[buffered events](https://w3c.github.io/webdriver-bidi/#log-event-buffer), they will
+be emitted before the `subcsribe` command's promise is resolved.
+
 ## API ##
 
 testdriver.js exposes its API through the `test_driver` variable in
@@ -57,6 +86,7 @@ the global scope.
 ### Permissions ###
 ```eval_rst
 .. js:autofunction:: test_driver.set_permission
+.. js:autofunction:: test_driver.bidi.permissions.set_permission
 ```
 
 ### Authentication ###
@@ -222,3 +252,29 @@ Note that if an action uses an element reference, the context will be
 derived from that element, and must match any explicitly set
 context. Using elements in multiple contexts in a single action chain
 is not supported.
+
+### Log
+
+This module corresponds to the WebDriver BiDi
+[Log](https://w3c.github.io/webdriver-bidi/#module-log) module and provides access to
+browser logs.
+
+#### Entry added
+
+This provides methods to subscribe to and listen for the
+[`log.entryAdded`](https://w3c.github.io/webdriver-bidi/#event-log-entryAdded) event.
+
+**Example:**
+
+```javascript
+await test_driver.bidi.log.entry_added.subscribe();
+const log_entry_promise = test_driver.bidi.log.entry_added.once();
+console.log("some message");
+const event = await log_entry_promise;
+```
+
+```eval_rst
+.. js:autofunction:: test_driver.bidi.log.entry_added.subscribe
+.. js:autofunction:: test_driver.bidi.log.entry_added.on
+.. js:autofunction:: test_driver.bidi.log.entry_added.once
+```

resources/testdriver.js

@@ -53,46 +53,66 @@
          Represents `WebDriver BiDi <https://w3c.github.io/webdriver-bidi>`_ protocol.
          */
         bidi: {
+            /**
+             * @typedef {(String|WindowProxy)} Context A browsing context. Can
+             * be specified by its ID (a string) or using a `WindowProxy`
+             * object.
+             */
+
             /**
              * `log <https://w3c.github.io/webdriver-bidi/#module-log>`_ module.
              */
             log: {
-                /**
-                 * `log.entryAdded <https://w3c.github.io/webdriver-bidi/#event-log-entryAdded>`_ event.
-                 */
                 entry_added: {
                     /**
-                     * Subscribe to the `log.entryAdded` event. This does not
-                     * add actual listeners. To listen to the event, use the
-                     * `on` or `once` methods.
-                     * @param {{contexts?: null | (string | Window)[]}} params - Parameters for the subscription.
-                     * * `contexts`: an array of window proxies or browsing
-                     * context ids to listen to the event. If not provided, the
-                     * event subscription is done for the current window's
-                     * browsing context. `null` for the global subscription.
-                     * @return {Promise<void>}
+                     * @typedef {object} LogEntryAdded `log.entryAdded <https://w3c.github.io/webdriver-bidi/#event-log-entryAdded>`_ event.
+                     */
+
+                    /**
+                     * Subscribes to the event. Events will be emitted only if
+                     * there is a subscription for the event. This method does
+                     * not add actual listeners. To listen to the event, use the
+                     * `on` or `once` methods. The buffered events will be
+                     * emitted before the command promise is resolved.
+                     *
+                     * @param {object} [params] Parameters for the subscription.
+                     * @param {null|Array.<(Context)>} [params.contexts] The
+                     * optional contexts parameter specifies which browsing
+                     * contexts to subscribe to the event on. It should be
+                     * either an array of Context objects, or null. If null, the
+                     * event will be subscribed to globally. If omitted, the
+                     * event will be subscribed to on the current browsing
+                     * context.
+                     * @returns {Promise<void>} Resolves when the subscription
+                     * is successfully done.
                      */
                     subscribe: async function (params = {}) {
                         return window.test_driver_internal.bidi.log.entry_added.subscribe(params);
                     },
                     /**
-                     * Add an event listener for the `log.entryAdded
-                     * <https://w3c.github.io/webdriver-bidi/#event-log-entryAdded>`_ event. Make sure `subscribe` is
-                     * called before using this method.
+                     * Adds an event listener for the event.
                      *
-                     * @param callback {function(event): void} - The callback
-                     * to be called when the event is fired.
-                     * @returns {function(): void} - A function to call to
-                     * remove the event listener.
+                     * @param {function(LogEntryAdded): void} callback The
+                     * callback to be called when the event is emitted. The
+                     * callback is called with the event object as a parameter.
+                     * @returns {function(): void} A function that removes the
+                     * added event listener when called.
                      */
                     on: function (callback) {
                         return window.test_driver_internal.bidi.log.entry_added.on(callback);
                     },
+                    /**
+                     * Adds an event listener for the event that is only called
+                     * once and removed afterward.
+                     *
+                     * @return {Promise<LogEntryAdded>} The promise which is resolved
+                     * with the event object when the event is emitted.
+                     */
                     once: function () {
                         return new Promise(resolve => {
                             const remove_handler = window.test_driver_internal.bidi.log.entry_added.on(
-                                data => {
-                                    resolve(data);
+                                event => {
+                                    resolve(event);
                                     remove_handler();
                                 });
                         });
@@ -104,11 +124,25 @@
              */
             permissions: {
                 /**
-                 * `permissions.setPermission <https://w3c.github.io/permissions/#webdriver-bidi-command-permissions-setPermission>`_
-                 * command.
+                 * Sets the state of a permission
+                 *
+                 * This function causes permission requests and queries for the status
+                 * of a certain permission type (e.g. "push", or "background-fetch") to
+                 * always return ``state`` for the specific origin.
+                 *
+                 * Matches the `permissions.setPermission <https://w3c.github.io/permissions/#webdriver-bidi-command-permissions-setPermission>`_
+                 * WebDriver BiDi command.
+                 *
+                 * @example
+                 * await test_driver.bidi.permissions.set_permission({
+                 *     {name: "geolocation"},
+                 *     state: "granted",
+                 * });
+                 *
                  * @param {object} params - Parameters for the command.
                  * @param {PermissionDescriptor} params.descriptor - a `PermissionDescriptor
-                 *                               <https://w3c.github.io/permissions/#dom-permissiondescriptor>`_.
+                 *                               <https://w3c.github.io/permissions/#dom-permissiondescriptor>`_
+                 *                               or derived object.
                  * @param {PermissionState} params.state - a `PermissionState
                  *                          <https://w3c.github.io/permissions/#dom-permissionstate>`_
                  *                          value.