Try rewriting the explainer #98

gsnedders · 2021-04-11T18:03:41Z

This attempts to follow the TAG-given advice at https://w3ctag.github.io/explainers

It also tries to bring the explainer in-line with today's spec.

This attempts to follow the TAG-given advice at https://w3ctag.github.io/explainers It also tries to bring the explainer in-line with today's spec.

jgraham · 2021-04-11T19:11:57Z

explainer.md

+
+### Considered alternatives
+
+\[FIXME: Adopting CDP wholesale\]


Maybe mention: reluctant to standardise, exposes implementation details, chatty protocol only designed for local usage.

Yeah, some of the FIXME was definitely "it's Sunday and I'm meant to be tidying my flat, not trying to improve the explainer due to WebDriver BiDi getting mentioned on orange site" (there are currently no interesting comments).

Maybe this is where we mention WebTransport and CBOR, two newer things we're not going to use right now.

jgraham · 2021-04-11T19:13:28Z

explainer.md

+
+### Choice of Transport Layer
+
+\[FIXME\]


Dunno what you want here, but JSON-over-WebSockets is close the the prior art and the most standard thing for a bidi communication protocol on the web stack.

Ignoring the prior art for a second, it's not immediately obvious why JSON-over-WebSockets is a better solution than CBOR-over-TCP, especially when it comes to non-local usage.

I think "this is not where we want to spend our complexity budget; tooling in this space uniformly has access to JSON parsing, and WebSockets is the common denominator in existing implementations", but also "this is something we could change later if we end up in a place where the transport is having a noticable effect on performance" (but I'd be surprised if we end up in that place; if the deserialization cost is that high the protocol got too chatty anyway).

Unusually for a W3C spec, we expect implementations to be provided in many different client languages. WebSockets and JSON give us a widely-supported base for local end implementations to be built from, and opens the door to quick shell scripts to do useful things.

I think this could just note that existing debugging protocols use WebSockets, so we will too.

shs96c · 2021-04-12T11:53:44Z

explainer.md


-The protocol is designed with the following goals in mind:
+WebDriver BiDi should help ensure a better end-user experience across all browsers by allowing
+developers to use the same tooling across all browsers.


There's an additional motivation, which is to decouple automation tools from an ever-changing debugging protocol. Primarily, this reduces the maintenance burden of tool vendors whilst allowing them to (as you point out) target multiple different browsers at the same time. Because the CDP protocol changes regularly, and webdriver bidi would be stable, this would also allow cross-version testing, which is also important.

Secondarily, this allows the Chromium team to make any changes they need to the protocol without fear of breaking those tools.

@shs96c agreed that allowing the debugging protocols to evolve to keep up with devtools product needs is an important reason why "just standardize CDP" didn't fly. Do you have a wording suggestion for this?

Note that since BiDi will be implemented on top of CDP, changes to CDP will actually very much come with the fear of breaking tools using BiDi, and only rigorous internal testing will mitigate that.

As such we should really do better in creating detailed WebDriver-bidi tests that will cover nearly all (important) cases for individual commands and events. For WebDriver HTTP I still see a lot of untested areas, especially around navigation. :(

shs96c · 2021-04-12T11:54:56Z

explainer.md

@@ -31,19 +43,50 @@ The protocol is designed with the following goals in mind:
    - Simple for browser vendors to implement and maintain.
    - Possible for clients to enhance their WebDriver automation with browser-specific devtools protocol features.


Although not discussed at the time, being able to support something like lighthouse would be a useful thing for this spec to be able to do.

shs96c · 2021-04-12T11:56:31Z

explainer.md

+\[FIXME. Why JSON?\]
+
+CDDL is used to describe the protocol layer because it provides formal semantics, accomplishing the
+"machine-readable API specification" goal while being similar to JSON-RPC used in the prior art.


The original WebDriver spec also uses JSON, so we're following in an already established precedent.

This could do with some tweaking I think. CDDL describes the shapes of messages that can be encoded as JSON, and we're using CDDL to describe something very similar to JSON-RPC, but CDDL itself is not similar to JSON-RPC, they're on different layers.

Perhaps "while allowing us to define a protocol similar to JSON-RPC used in the prior art"?

shs96c · 2021-04-12T11:58:38Z

explainer.md

+
+### Choice of Transport Layer
+
+\[FIXME\]


Unusually for a W3C spec, we expect implementations to be provided in many different client languages. WebSockets and JSON give us a widely-supported base for local end implementations to be built from, and opens the door to quick shell scripts to do useful things.

foolip

This is a great improvement, there are some FIXMEs, but "try" is too humble a description. With just a few small fixes I'd be happy for us to land this.

foolip · 2021-05-06T09:40:34Z

explainer.md


-## Overview
+WebDriver BiDi (Bi-Directional) is being developed to allow web developers to migrate from


foolip · 2021-05-06T09:47:05Z

explainer.md


-## Goals
+Many developer tools are exclusively targetting Chrome, relying on CDP, resulting in websites being


Among test tooling not using WebDriver, I think Cypress is the most popular, and it's Chrome+Firefox. Puppeteer isn't hugely popular for testing (mostly automation) but it too is Chrome+Firefox.

I'd describe the problem as "Many developer tools are targeting mainly Chrome, and sometimes Firefox, relying on different and non-standard protocols for each supported browser. This results in websites being better tested in those browsers, leading to site compatibility bits for other browsers."

WDYT?

There are also lessons in Web Testing Report (should we link that?) about support for a browser in a test framework not leading directly to that browser being tested. It also needs to be really simple (multi-browser by default I think) and above all the developer needs to want to test the browser to begin with, probably already doing some manual testing in it.

@whimboo you might be interested in this wording as well, given your comment at #98 (comment)

foolip · 2021-05-06T09:52:15Z

explainer.md


-The protocol is designed with the following goals in mind:
+WebDriver BiDi should help ensure a better end-user experience across all browsers by allowing
+developers to use the same tooling across all browsers.


@shs96c agreed that allowing the debugging protocols to evolve to keep up with devtools product needs is an important reason why "just standardize CDP" didn't fly. Do you have a wording suggestion for this?

Note that since BiDi will be implemented on top of CDP, changes to CDP will actually very much come with the fear of breaking tools using BiDi, and only rigorous internal testing will mitigate that.

foolip · 2021-05-06T09:52:42Z

explainer.md

+## Non-goals
+
+Feature parity with CDP is a non-goal at this time; many features of CDP are rarely used by
+existing developer tooling, and being able to entirely supplant CDP is not a goal at this time.


foolip · 2021-05-06T09:53:03Z

explainer.md

+
+## Prior Art
+
+\[FIXME: [CDP](https://chromedevtools.github.io/devtools-protocol/),


Just turn this into a list, or is there additional fixing needed?

foolip · 2021-05-06T09:55:45Z

explainer.md

+
+### Choice of Transport Layer
+
+\[FIXME\]


I think this could just note that existing debugging protocols use WebSockets, so we will too.

foolip · 2021-05-06T09:58:43Z

explainer.md

+
+### Choice of Protocol Layer
+
+\[FIXME. Why JSON?\]


I think the answer is it matches the prior art. We should also say why we can't use JSON-RPC verbatim, and perhaps say that using CBOR is a future possibility, and the design allows for it by avoiding sending binary WebSockets messages entirely, and the first line of https://w3c.github.io/webdriver-bidi/#handle-an-incoming-message

(Although maybe we should change that first line to silently drop binary messages or respond with an error instead of closing the connectin...)

foolip · 2021-05-06T10:01:23Z

explainer.md

+\[FIXME. Why JSON?\]
+
+CDDL is used to describe the protocol layer because it provides formal semantics, accomplishing the
+"machine-readable API specification" goal while being similar to JSON-RPC used in the prior art.


This could do with some tweaking I think. CDDL describes the shapes of messages that can be encoded as JSON, and we're using CDDL to describe something very similar to JSON-RPC, but CDDL itself is not similar to JSON-RPC, they're on different layers.

Perhaps "while allowing us to define a protocol similar to JSON-RPC used in the prior art"?

foolip · 2021-05-06T10:02:21Z

explainer.md

+
+### Considered alternatives
+
+\[FIXME: Adopting CDP wholesale\]


Maybe this is where we mention WebTransport and CBOR, two newer things we're not going to use right now.

foolip · 2021-05-06T10:04:21Z

explainer.md

- [Bootstrap Scripts](./proposals/bootstrap-scripts.md)
+Any protocol that can be used for web testing automation can also open browsers up to malicious
+actors. It is vital that any functionality cannot be accessed from web platform content; browsers
+with multi-process architectures may want to minimise the amount of functionality within the web


A very good point!

Aside: This is actually relevant to the question of whether the navigate command should support relative URLs, because to do so would require going to the content process to resolve the URL, or using a cached-and-maybe-stale URL in another process.

whimboo · 2021-05-07T09:00:18Z

explainer.md


-## Overview
+WebDriver BiDi (Bi-Directional) is being developed to allow web developers to migrate from
+Chromium-only [CDP](https://chromedevtools.github.io/devtools-protocol/)-based (Chrome DevTools


Shall we remove the Chromium-only bit here given that we also have (partial) support for it in Firefox?

Probably makes sense to say something about it being non-standard and de-facto defined by Chromium?

Try rewriting the explainer

0dcbb43

This attempts to follow the TAG-given advice at https://w3ctag.github.io/explainers It also tries to bring the explainer in-line with today's spec.

gsnedders requested review from jgraham and foolip April 11, 2021 18:03

jgraham reviewed Apr 11, 2021

View reviewed changes

shs96c reviewed Apr 12, 2021

View reviewed changes

foolip reviewed May 6, 2021

View reviewed changes

whimboo reviewed May 7, 2021

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Try rewriting the explainer #98

Try rewriting the explainer #98

gsnedders commented Apr 11, 2021 •

edited

Loading

jgraham Apr 11, 2021

gsnedders Apr 11, 2021

foolip May 6, 2021

jgraham Apr 11, 2021

gsnedders Apr 11, 2021

jgraham Apr 12, 2021

shs96c Apr 12, 2021

foolip May 6, 2021

shs96c Apr 12, 2021

foolip May 6, 2021

whimboo May 7, 2021

shs96c Apr 12, 2021

shs96c Apr 12, 2021

foolip May 6, 2021

shs96c Apr 12, 2021

foolip left a comment

foolip May 6, 2021

foolip May 6, 2021

foolip May 7, 2021

foolip May 6, 2021

foolip May 6, 2021

foolip May 6, 2021

foolip May 6, 2021

foolip May 6, 2021

foolip May 6, 2021

foolip May 6, 2021

foolip May 6, 2021

whimboo May 7, 2021

gsnedders May 7, 2021


		### Considered alternatives

		\[FIXME: Adopting CDP wholesale\]

		@@ -31,19 +43,50 @@ The protocol is designed with the following goals in mind:
		- Simple for browser vendors to implement and maintain.
		- Possible for clients to enhance their WebDriver automation with browser-specific devtools protocol features.


		## Overview
		WebDriver BiDi (Bi-Directional) is being developed to allow web developers to migrate from


		## Goals
		Many developer tools are exclusively targetting Chrome, relying on CDP, resulting in websites being


		## Prior Art

		\[FIXME: [CDP](https://chromedevtools.github.io/devtools-protocol/),

Try rewriting the explainer #98

Are you sure you want to change the base?

Try rewriting the explainer #98

Conversation

gsnedders commented Apr 11, 2021 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

foolip left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

gsnedders commented Apr 11, 2021 •

edited

Loading