WebDriver BiDi

1. Introduction

This section is non-normative.

WebDriver defines a protocol for introspection and remote control of user agents. This specification extends WebDriver by introducing bidirectional communication. In place of the strict command/response format of WebDriver, this permits events to stream from the user agent to the controlling software, better matching the evented nature of the browser DOM.

2. Protocol

This section defines the basic concepts of the WebDriver BiDi protocol. These terms are distinct from their representation at the transport layer.

This specification uses Concise Data Definition Language (CDDL) [RFC8610] to describe the format of messages transmitted between the local end and remote end.

Note: These definitions do not form any normative requirements, rather they are used elsewhere as part of such requirements.

2.1. Modules

The WebDriver BiDi protocol is organized into modules. A module is defined by:

• A unique string name, implicit in its definition.

• A set of commands.

• A set of events.

Each module represents a collection of related commands and events pertaining to a certain aspect of the user agent. For example, a module might contain functionality for inspecting and manipulating the DOM, or for script execution.

2.2. Commands

A command is an asynchronous operation, requested by the local end and run on the remote end, resulting in either a result or an error being returned to the local end. Multiple commands can run at the same time, and commands can potentially be long-running. As a consequence, commands can finish out-of-order.

Each concrete command type is defined by:

• A string name, implicit in its definition.

• A parameter type, which is a map whose entries are the inputs to the command.

• A set of remote end steps.

• A return type, which may be null.

Command parameter types and return types are defined in this specification using CDDL.

The following table of commands lists the available commands by module and name.

2.3. Events

An event is a notification, sent by the remote end to the local end, signaling that something of interest has occurred on the remote end.

Each concrete event type is defined by:

• A string name, implicit in its definition.

• A parameter type, which is a map whose entries are the details of the event that has occurred.

Event parameter types are defined in this specification using CDDL.

2.4. Processing Model

3. Transport

Message transport is provided using the WebSocket protocol. [RFC6455]

Note: In the terms of the WebSocket protocol, the local end is the client and the remote end is the server / remote host.

Note: The encoding of commands and events as messages is similar to JSON-RPC, but this specification does not normatively reference it. [JSON-RPC] The normative requirements on remote ends are instead given as a precise processing model, while no normative requirements are given for local ends.

A WebSocket listener is a network endpoint that is able to accept incoming WebSocket connections.

A WebSocket listener has a host, a port, a secure flag, and a list of WebSocket resources.

When a WebSocket listener listener is created, a remote end must start to listen for WebSocket connections on the host and port given by listener’s host and port. If listener’s secure flag is set, then connections established from listener must be TLS encrypted.

A remote end has a set of WebSocket listeners active listeners, which is initially empty.

A WebDriver session has a WebSocket connection which is a network connection that follows the requirements of the WebSocket protocol.

When a WebSocket message has been received for a WebSocket connection connection with type type and data data, a remote end must handle an incoming message given connection, type and data.

When the WebSocket closing handshake is started or when the WebSocket connection is closed for a WebSocket connection connection, a remote end must handle a connection closing given connection.

Note: Both conditions are needed because it is possible for a WebSocket connection to be closed without a closing handshake.

Note: An intermediary node handling multiple sessions can use one or many WebSocket listeners. WebDriver defines that an endpoint node supports at most one session at a time, so it’s expected to only have a single listener.

Note: For an endpoint node the host in the above steps will typically be "localhost".

Note: This does not end any session.

Need to hook in to the session ending to allow the UA to close the listener if it wants.

3.1. Establishing a Connection

WebDriver clients opt in to a bidirectional connection by requesting a capability with the name "webSocketUrl" and value true.

This specification defines an additional webdriver capability with the capability name "webSocketUrl".

4. Modules

4.1. session

The session module contains commands and events for monitoring the status of the remote end.

4.1.1. status

The status command returns information about whether a remote end is in a state in which it can create new sessions, but may additionally include arbitrary meta information that is specific to the implementation.

Parameter Type

      {}

Return Type

      StatusResult = {
         ready: bool,
         message: text,
         * text => any
      }

The remote end steps are:

1. Let body be a new map with the following properties:

   "ready"

   The remote end’s readiness state.

   "message"

   An implementation-defined string explaining the remote end’s readiness state.

2. Return success with data body.

5. Conformance

This specification depends on the Infra Standard. [INFRA]