Merge remote-tracking branch 'origin/master' into navigate_history

.gitattributes

@@ -0,0 +1,2 @@
+# Automatically normalize line endings for all text-based files.
+* text=auto

.github/workflows/auto-publish.yml

@@ -7,7 +7,7 @@ jobs:
   deploy:
     runs-on: ubuntu-20.04
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
     - uses: w3c/spec-prod@v2
       with:
         GH_PAGES_BRANCH: gh-pages

.github/workflows/test.yml

@@ -7,22 +7,45 @@ on:
   pull_request:
 
 jobs:
+  build:
+    runs-on: ubuntu-20.04
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v3
+        with:
+          # Python 3.11 is broken: https://github.com/tabatkins/bikeshed/issues/2386
+          python-version: "3.10"
+      - name: Build spec without warnings
+        run: ./scripts/build.sh --install
   cddl:
-    runs-on: ubuntu-18.04
+    runs-on: ubuntu-20.04
     steps:
-      - uses: actions/checkout@v2
-      - uses: actions/setup-node@v1
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with:
+          node-version: 16
+      - name: Get cddl version
+        run: curl -s https://crates.io/api/v1/crates/cddl | python3 -c "import sys, json; print(json.load(sys.stdin)['crate']['max_stable_version'])" | tee cddl.txt
+      - name: "Cache rust binaries"
+        uses: actions/cache@v3
+        id: cache-cddl
+        env:
+          cache-name: cache-cddl
         with:
-          node-version: 14.x
-      - name: Install Dependencies
-        run: npm install cddl parse5
-      - name: Extract CDDL content from spec into files
-        run: ./scripts/cddl/generate.js
-      - name: Print remote.cddl
-        run: cat remote.cddl
-      - name: Print local.cddl
-        run: cat local.cddl
+          path: |
+            ~/.cargo/bin/
+            ~/.cargo/git/db/
+            ~/.cargo/registry/cache/
+            ~/.cargo/registry/index/
+            ./target/
+          key: cddl-${{ hashFiles('cddl.txt') }}
+      - uses: actions-rs/toolchain@v1
+        with:
+          toolchain: stable
       - name: Validate CDDL files
-        run: |
-          npx cddl validate local.cddl
-          npx cddl validate remote.cddl
+        run: ./scripts/test.sh
+      - name: Archive CDDL files
+        uses: actions/upload-artifact@v3
+        with:
+          name: cddl
+          path: "*.cddl"

README.md

@@ -4,6 +4,46 @@ WebDriver BiDi is a proposed bidirectional protocol for browser automation,
 building on and extending [WebDriver](https://w3c.github.io/webdriver/).
 
 WebDriver BiDi is not ready. Here's what we have so far:
+
 - An [explainer](./explainer.md) with more background and goals
+- A [roadmap](./roadmap.md) based on real-world end-to-end user scenarios
 - Detailed [proposals](./proposals/) for the initial protocol
 - A [unofficial spec draft](https://w3c.github.io/webdriver-bidi/) waiting to be fleshed out
+
+## Status
+
+[![test](https://github.com/w3c/webdriver-bidi/actions/workflows/test.yml/badge.svg)](https://github.com/w3c/webdriver-bidi/actions/workflows/test.yml)
+
+## How to build the specification locally
+
+We use [bikeshed](https://tabatkins.github.io/bikeshed/) to generate the specification.
+
+Make sure you have the [right version of python](https://tabatkins.github.io/bikeshed/#install-py3) installed.
+
+Now you can run in your terminal:
+
+```bash
+./scripts/build.sh
+```
+
+This script will install `bikeshed` (if not installed yet) and generate an
+`index.html` file for the specification.
+
+Later on, you can use the `--upgrade` argument to force installing a newer version.
+
+## How to generate CDDL locally
+
+Make sure you have [npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm)
+and [rust](https://www.rust-lang.org/tools/install) installed.
+
+Now you can run in your terminal:
+
+```bash
+./scripts/test.sh
+```
+
+This script will install required npm and cargo packages (if not installed yet)
+and generate the CDDL files for the remote end (`remote.cddl`) and the client
+(`local.cddl`).
+
+Later on, you can use the `--upgrade` argument to force installing newer versions.

explainer.md

@@ -1,49 +1,49 @@
-# Bidirectional WebDriver Protocol
-
-## Overview
-
-This document presents a possible design for a bidirectional WebDriver protocol, incorporating scenarios and resolutions discussed at the TPAC 2019 working group meeting. The protocol uses JSON-RPC messaging over WebSockets as the transport mechanism. WebDriver's current model of the browser is extended to include service workers and other non-page targets and make it possible for clients to target these additional contexts. We also discuss how the new protocol can interoperate with the existing protocol. Sample protocol messages illustrating how the protocol would work are included, and an JSON API specification is included alongside the document.
-
-## Goals
-
-The protocol is designed with the following goals in mind:
-
-- **Support for the top customer scenarios identified at TPAC 2019:**
-    - Listen for DOM events
-    - Log what's going on in the browser including console and JS errors
-    - Fail fast on any JS error
-    - Mock backends and intercept network requests
-    - Record traffic
-    - Full-page screenshot
-    - Access to native devtools protocol
-    - Dynamic changes to iframe or documents
-    - Performance timings
-    - Notifying of new contexts
-    - Bootstrap scripts
-- **Interoperability with classical WebDriver commands**
-    - Allow existing test/automation code to be upgraded gradually.
-- **Feature parity with existing WebDriver commands**
-    - Existing commands can be sent over the new protocol so that new test/automation code can be written entirely in the new protocol.
-    - Update features to take advantage of bidi communication where appropriate. Useful for unhandled prompts and scenarios where polling is common.
-- **A machine and human-readable API specification**
-    - Makes it easier to generate up-to-date language bindings, documentation, and test cases.
-- **Easily mappable to/from native devtools protocols**
-    - Simple for browser vendors to implement and maintain.
-    - Possible for clients to enhance their WebDriver automation with browser-specific devtools protocol features.
-
-This document doesn't attempt to dive into the any of the new feature scenarios identified above, but rather tries to provide a solid foundation and the necessary primitives to build these features on. The document does walk through an example of an existing WebDriver feature (unhandled prompts) being updated for a bidirectional world.
-
-## Proposals
-
-- [Core Functionality](./proposals/core.md)
-- [Bootstrap Scripts](./proposals/bootstrap-scripts.md)
-
-[openrpc.json](./proposals/openrpc.json) contains an OpenRPC specification with an initial set of proposed commands and events.
-
-## References
-
-1. [WebDriver](https://w3c.github.io/webdriver/)
-2. [JSON-RPC 2.0 Specification](https://www.jsonrpc.org/specification)
-3. [OpenRPC Specification](https://spec.open-rpc.org/)
-4. [Browser Tools- and Testing WG, Day 1, TPAC 2019, Fukuoka](https://www.w3.org/2019/09/19-webdriver-minutes.html)
-5. [Browser Tools- and Testing WG, Day 2, TPAC 2019, Fukuoka](https://www.w3.org/2019/09/20-webdriver-minutes.html)
+# Bidirectional WebDriver Protocol
+
+## Overview
+
+This document presents a possible design for a bidirectional WebDriver protocol, incorporating scenarios and resolutions discussed at the TPAC 2019 working group meeting. The protocol uses JSON-RPC messaging over WebSockets as the transport mechanism. WebDriver's current model of the browser is extended to include service workers and other non-page targets and make it possible for clients to target these additional contexts. We also discuss how the new protocol can interoperate with the existing protocol. Sample protocol messages illustrating how the protocol would work are included, and an JSON API specification is included alongside the document.
+
+## Goals
+
+The protocol is designed with the following goals in mind:
+
+- **Support for top customer scenarios:**
+    - Listen for DOM events
+    - Log what's going on in the browser including console and JS errors
+    - Fail fast on any JS error
+    - Mock backends and intercept network requests
+    - Record traffic
+    - Full-page screenshot
+    - Access to native devtools protocol
+    - Dynamic changes to iframe or documents
+    - Performance timings
+    - Notifying of new contexts
+    - Bootstrap scripts
+- **Interoperability with classical WebDriver commands**
+    - Allow existing test/automation code to be upgraded gradually.
+- **Feature parity with existing WebDriver commands**
+    - Existing commands can be sent over the new protocol so that new test/automation code can be written entirely in the new protocol.
+    - Update features to take advantage of bidi communication where appropriate. Useful for unhandled prompts and scenarios where polling is common.
+- **A machine and human-readable API specification**
+    - Makes it easier to generate up-to-date language bindings, documentation, and test cases.
+- **Easily mappable to/from native devtools protocols**
+    - Simple for browser vendors to implement and maintain.
+    - Possible for clients to enhance their WebDriver automation with browser-specific devtools protocol features.
+
+This document doesn't attempt to dive into the any of the new feature scenarios identified above, but rather tries to provide a solid foundation and the necessary primitives to build these features on. See [the roadmap](roadmap.md) for some example real-world user scenarios we aim to enable.
+
+## Proposals
+
+- [Core Functionality](./proposals/core.md)
+- [Bootstrap Scripts](./proposals/bootstrap-scripts.md)
+
+[openrpc.json](./proposals/openrpc.json) contains an OpenRPC specification with an initial set of proposed commands and events.
+
+## References
+
+1. [WebDriver](https://w3c.github.io/webdriver/)
+2. [JSON-RPC 2.0 Specification](https://www.jsonrpc.org/specification)
+3. [OpenRPC Specification](https://spec.open-rpc.org/)
+4. [Browser Tools- and Testing WG, Day 1, TPAC 2019, Fukuoka](https://www.w3.org/2019/09/19-webdriver-minutes.html)
+5. [Browser Tools- and Testing WG, Day 2, TPAC 2019, Fukuoka](https://www.w3.org/2019/09/20-webdriver-minutes.html)