Firefox Tomorrow

listing page

WebDriver BiDi modules

View on MDN ↗

The WebDriver BiDi protocol is organized into modules. Each module represents a collection of related commands and events used in specific browser automation cases.

Both command and event names use the module name as a prefix: module_name.command_name for commands and module_name.event_name for events.

List of modules

Commands

A command is an asynchronous operation sent from the client to the browser. Each command message you send to the browser has three fields:

  • id: A number you assign to the command. Unlike HTTP where each request waits for a response, a WebSocket connection can have multiple commands in flight at the same time and responses may arrive out of order. The id lets you match each response to the command that triggered it.
  • method: The command to run, in the form module_name.command_name.
  • params: An object with any additional information the command needs. Some commands require no parameters, but an empty params object ({}) must still be sent.

For example, to create a new session, you would send the session.new command as follows:

{
  "id": 1,
  "method": "session.new",
  "params": {}
}

Each command results in either a success response containing a result field or an error response containing an error field. The structure of result is specific to each command.

All commands except session.new and session.status require an active WebDriver BiDi session.

Events

An event is a notification sent by the browser to the client when something of interest occurs. To receive events, the client must first subscribe to them using the session.subscribe command.

The client can subscribe to a specific event or to all events in a module. For example, subscribing to "browsingContext.contextCreated" subscribes the client to that single event, while subscribing to "browsingContext" subscribes the client to every event in the browsingContext module.

Every event notification you receive from the browser has three fields:

  • type: Always "event".
  • method: The event name, in the form module_name.event_name.
  • params: An object containing the event-specific data. The structure of params is specific to each event.

The following is a sample event message sent by the browser when the client is subscribed to log.entryAdded and a console message is logged (some fields have been omitted for brevity):

{
  "type": "event",
  "method": "log.entryAdded",
  "params": {
    "type": "console",
    "level": "info",
    "text": "Hello world",
    "timestamp": 1657282076037,
    "method": "log"
  }
}

Browser compatibility

Browser compatibilityCompatibility data is available on the canonical MDN page.

See also