From 4ef91d64f23912142d8245fc41410cd143eb5996 Mon Sep 17 00:00:00 2001
From: Peter Hedenskog <peter@soulgalore.com>
Date: Wed, 13 Mar 2024 06:40:49 +0100
Subject: [PATCH] docs: More documentation for Bidi (#2102)

* bidi documentation

* moar docs
---
 jsdoc/tutorials/12-Bidi.md                    | 50 +++++++++++++++++++
 .../{12-Android.md => 13-Android.md}          |  0
 ...ps-and-tricks.md => 18-Tips-and-tricks.md} |  0
 jsdoc/tutorials/tutorials.json                |  7 ++-
 lib/core/engine/command/bidi.js               |  3 +-
 5 files changed, 57 insertions(+), 3 deletions(-)
 create mode 100644 jsdoc/tutorials/12-Bidi.md
 rename jsdoc/tutorials/{12-Android.md => 13-Android.md} (100%)
 rename jsdoc/tutorials/{13-Tips-and-tricks.md => 18-Tips-and-tricks.md} (100%)

diff --git a/jsdoc/tutorials/12-Bidi.md b/jsdoc/tutorials/12-Bidi.md
new file mode 100644
index 000000000..25e57719b
--- /dev/null
+++ b/jsdoc/tutorials/12-Bidi.md
@@ -0,0 +1,50 @@
+Send messages to the browser using the [BiDirectional WebDriver Protocol (Bidi)](https://w3c.github.io/webdriver-bidi/). This works in Firefox today and later more browsers. You can send, send and get and listen on events. This is a super powerful feature that enables you to do a lot.
+
+There's no user friendly documentation right now for Bidi.
+
+### Sending a command
+
+Here’s an example of sending a command that injects JavaScript that runs on every new document.
+
+```javascript
+/**
+ * @param {import('browsertime').BrowsertimeContext} context
+ * @param {import('browsertime').BrowsertimeCommands} commands
+ */
+export default async function (context, commands) {
+  const params = {
+  method: 'script.addPreloadScript',
+  params: {
+    functionDeclaration: "function() {alert('hello');}"
+   }
+  };
+  await commands.bidi.send(params);
+  await commands.measure.start('https://www.sitespeed.io');
+}
+```
+
+### Subscribe and usubscribe to events
+
+You need to subscribe to the event types that you are interested in with `commands.bidi.subscribe('messageType');` and unsubscribe when you are done. 
+
+### Listen on events
+
+When you subscribe on an event you want to do something when the events happen.
+
+```javascript
+/**
+ * @param {import('browsertime').BrowsertimeContext} context
+ * @param {import('browsertime').BrowsertimeCommands} commands
+ */
+export default async function (context, commands) {
+  // We want to to do something on all the requests that are sent
+  await commands.bidi.subscribe('network.beforeRequestSent');
+
+  await commands.bidi.onMessage(function (event) {
+    const myEvent = JSON.parse(Buffer.from(event.toString()));
+    console.log(myEvent);
+  });
+
+  await commands.navigate('https://www.sitespeed.io');
+}
+```
\ No newline at end of file
diff --git a/jsdoc/tutorials/12-Android.md b/jsdoc/tutorials/13-Android.md
similarity index 100%
rename from jsdoc/tutorials/12-Android.md
rename to jsdoc/tutorials/13-Android.md
diff --git a/jsdoc/tutorials/13-Tips-and-tricks.md b/jsdoc/tutorials/18-Tips-and-tricks.md
similarity index 100%
rename from jsdoc/tutorials/13-Tips-and-tricks.md
rename to jsdoc/tutorials/18-Tips-and-tricks.md
diff --git a/jsdoc/tutorials/tutorials.json b/jsdoc/tutorials/tutorials.json
index 19f3a3831..2e58bc0b4 100644
--- a/jsdoc/tutorials/tutorials.json
+++ b/jsdoc/tutorials/tutorials.json
@@ -33,10 +33,13 @@
     "11-Chrome-Devtools-Protocol": {
         "title": "Chrome Devtools Protocol (CDP)"
     },
-    "12-Android": {
+    "12-Bidi": {
+        "title": "Using Bidi"
+    },
+    "13-Android": {
         "title": "Android devices"
     },
-    "13-Tips-and-tricks": {
+    "18-Tips-and-tricks": {
         "title": "Tips and tricks"
     }
 }
\ No newline at end of file
diff --git a/lib/core/engine/command/bidi.js b/lib/core/engine/command/bidi.js
index d718e7f10..2298073ad 100644
--- a/lib/core/engine/command/bidi.js
+++ b/lib/core/engine/command/bidi.js
@@ -24,7 +24,8 @@ export class Bidi {
    * Add a fanction that will get the events that you subscribes.
    * @async
    * @example await commands.bidi.onMessage(function(event) {
-   *  console.log(event);
+   *  const myEvent = JSON.parse(Buffer.from(event.toString()));
+   *  console.log(myEvent);
    * });
    * @param {Function} f - The callback function to handle incoming messages. The function will get an event passed on to it. Remember to subscribe to the event.
    * @throws {Error} Throws an error if the method is called in a browser other than Firefox.