Define on a shared user facing API for BiDi and CDP

[diemol]

🚀 Feature Proposal

We'd like to define a shared user-facing API that users can interact with when using bi-directional WebDriver API. Until the standard is delivered, this API is likely to be backed by CDP.

Motivation

See https://github.com/w3c/webdriver-bidi/blob/master/proposals/core.md for more details. The API should focus on satisfying the following use cases:

Event-based use cases:

• Listen for DOM events
• Log what's going on in the browser including console and JS errors
• Fail fast on any JS error
• Intercept network requests allowing to mock backend requests
• Record traffic (Alex: Allow replaying it?)
• Authenticate on secure pages
• Bootstrap scripts (for example, execute JavaScript snippet on every page load)
• Listen for new contexts (Alex: Not sure what do we mean by contexts?)

Other use cases:

• Take full-page screenshots
• Access throttling and performance timings
• Dynamic changes to iframe or documents (Alex: Not sure it means to make changes or listen for changes?)

Example

Read the issue comments for examples.

[p0deje]

A use-csae of CDP used API I have is to add JS snippet to be executed on every new page load. In current Ruby this is done in the following way:

driver.devtools.page.enable
driver.devtools.page.add_script_to_evaluate_on_new_document('my javascript code string')

I'm not sure how Selenium API for it might look like.

[shs96c]

After discussion in the #selenium-tlc slack channel, the current suggestion is for me to put together some strawman APIs to feed the design process.

[p0deje]

After discussion in the #selenium-tlc slack channel, the API will essentially be a user-facing API for WebDriver BiDi so we can draft based on its scenarios from https://github.com/w3c/webdriver/blob/master/webdriver-bidi/webdriver.md#goals:

• 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

I'll turn this list into a checklist and pin to the issue so that we can track the work.

[shs96c]

Useful diffs for this:

Authentication: 6c198bc

Listen for page mutations: 65f0ae8

Listen out for console logs: 74f3b22

[shs96c]

Listen out for js errors: d6c10c6

[shs96c]

The following work remains on the Java bindings:

• Expose "pin script" (possibly on the JavascriptExecutor)
• Add a remote end point for "pin script"
• Add interfaces via the Augmenter

[jimevans]

One more use case (which is actually as subset of "intercept network requests," but current implementations do not do this): Get response information before page is displayed in the browser.

This is to solve for the "get the HTTP status code" use case. I will refrain from editorializing on the usefulness of this use case.

[titusfortner]

Can I propose adding the use case of setting cookies on a domain you aren't on? I'd like to be able to authenticate a user with an API, and set the resulting token value in a cookie so I can navigate to a specific page. Right now I have to navigate to the domain first (which isn't always possible with domain redirects).

[shs96c]

I think we now have these in all the language bindings. Closing.

We can always add more use-cases if we need to.