これは、このセクションの複数ページの印刷可能なビューです。 印刷するには、ここをクリックしてください.

このページの通常のビューに戻る.

WebDriver BiDi (双方向機能)

WebDriver BiDi は、Selenium プロジェクトとブラウザベンダーが共同で策定した、ブラウザ自動化のための W3C 標準の双方向プロトコルです。WebDriver に WebSocket 接続を追加することで、ネットワークリクエスト、 コンソールメッセージ、JavaScript エラーといったブラウザイベントをリアルタイムに受け取って処理できます。 Chrome DevTools Protocol を置き換える、クロスブラウザな標準です。

BiDirectional means that communication is happening in two directions simultaneously. The traditional WebDriver model involves strict request/response commands which only allows for communication to happen in one direction at any given time. In most cases this is what you want; it ensures that the browser is doing the expected things in the right order, but there are a number of interesting things that can be done with asynchronous interactions.

This functionality is currently available in a limited fashion with the [Chrome DevTools Protocol] (CDP), but to address some of its drawbacks, the Selenium team, along with the major browser vendors, have worked to create the new WebDriver BiDi Protocol. This specification aims to create a stable, cross-browser API that leverages bidirectional communication for enhanced browser automation and testing functionality, including streaming events from the user agent to the controlling software via WebSockets. Users will be able to listen for and record or manipulate events as they happen during the course of a Selenium session.

Enabling BiDi in Selenium

In order to use WebDriver BiDi, setting the capability in the browser options will enable the required functionality:

options.setCapability("webSocketUrl", true);
options.enable_bidi = True
UseWebSocketUrl = true,
options.web_socket_url = true
Options().enableBidi();
options.setCapability("webSocketUrl", true);

This enables the WebSocket connection for bidirectional communication, unlocking the full potential of the WebDriver BiDi protocol.

Note that Selenium is updating its entire implementation from WebDriver Classic to WebDriver BiDi (while maintaining backwards compatibility as much as possible), but this section of documentation focuses on the new functionality that bidirectional communication allows. The low-level BiDi domains will be accessible in the code to the end user, but the goal is to provide high-level APIs that are straightforward methods of real-world use cases. As such, the low-level components will not be documented, and this section will focus only on the user-friendly features that we encourage users to take advantage of.

If there is additional functionality you’d like to see, please raise a feature request.

1 - WebDriver BiDi Logging Features

These features are related to logging. Because “logging” can refer to so many different things, these methods are made available via a “script” namespace.

Remember that to use WebDriver BiDi, you must enable it in Options. For more details, see Enabling BiDi

Console Message Handlers

Record or take actions on console.log events.

Add Handler

Implementation Missing

Implementation Missing

Implementation Missing

Remove Handler

You need to store the ID returned when adding the handler to delete it.

Implementation Missing

Implementation Missing

Implementation Missing

JavaScript Exception Handlers

Record or take actions on JavaScript exception events.

Add Handler

Implementation Missing

Implementation Missing

Implementation Missing

Remove Handler

You need to store the ID returned when adding the handler to delete it.

Implementation Missing

Implementation Missing

Implementation Missing

2 - WebDriver BiDi Network Features

These features are related to networking, and are made available via a “network” namespace.

The implementation of these features is being tracked here: #13993

Remember that to use WebDriver BiDi, you must enable it in Options. For more details, see Enabling BiDi

Authentication Handlers

Authentication handlers enable you to intercept authentication requests that occur during a network interaction. These handlers are useful for automating scenarios involving authentication prompts, such as Basic Auth or Digest Auth. They allow you to programmatically provide credentials or modify the authentication flow.

Add Handler

Request Handlers

Request handlers allow you to intercept and manipulate outgoing network requests before they are sent to the server. This can be used to modify request headers, change the request body, or block specific requests. Request handlers are essential for testing and debugging scenarios where you need control over outgoing traffic.

Add Handler

Response Handlers

Response handlers enable you to intercept and manipulate incoming responses from the server. They are particularly useful for testing scenarios involving response data, such as verifying or modifying response headers, status codes, or content before it reaches the browser.

Remove Handler

Clear Handlers

3 - WebDriver BiDi Script Features

These features are related to scripts, and are made available via a “script” namespace.

The implementation of these features is being tracked here: #13992

Remember that to use WebDriver BiDi, you must enable it in Options. For more details, see Enabling BiDi

Script Pinning

Execute Script

DOM Mutation Handlers

4 - Chrome DevTools Protocol

Examples of working with Chrome DevTools Protocol in Selenium. CDP support is temporary until WebDriver BiDi has been implemented.

Page being translated from English to Japanese. Do you speak Japanese? Help us to translate it by sending us pull requests!

Many browsers provide “DevTools” – a set of tools that are integrated with the browser that developers can use to debug web apps and explore the performance of their pages. Google Chrome’s DevTools make use of a protocol called the Chrome DevTools Protocol (or “CDP” for short). As the name suggests, this is not designed for testing, nor to have a stable API, so functionality is highly dependent on the version of the browser.

Selenium is working to implement a standards-based, cross-browser, stable alternative to CDP called [WebDriver BiDi]. Until the support for this new protocol has finished, Selenium plans to provide access to CDP features where applicable.

Using Chrome DevTools Protocol with Selenium

Chrome and Edge have a method to send basic CDP commands. This does not work for features that require bidirectional communication, and you need to know what domains to enable when and the exact names and types of domains/methods/parameters.

Add Example

Add Example

To make working with CDP easier, and to provide access to the more advanced features, Selenium bindings automatically generate classes and methods for the most common domains. CDP methods and implementations can change from version to version, though, so you want to keep the version of Chrome and the version of DevTools matching. Selenium supports the 3 most recent versions of Chrome at any given time, and tries to time releases to ensure that access to the latest versions are available.

This limitation provides additional challenges for several bindings, where dynamically generated CDP support requires users to regularly update their code to reference the proper version of CDP. In some cases an idealized implementation has been created that should work for any version of CDP without the user needing to change their code, but that is not always available.

Examples of how to use CDP in your Selenium tests can be found on the following pages, but we want to call out a couple commonly cited examples that are of limited practical value.

  • Geo Location — almost all sites use the IP address to determine physical location, so setting an emulated geolocation rarely has the desired effect.
  • Overriding Device Metrics — Chrome provides a great API for setting Mobile Emulation in the Options classes, which is generally superior to attempting to do this with CDP.

4.1 - Chrome DevTools Logging Features

Logging features using CDP.

Page being translated from English to Japanese. Do you speak Japanese? Help us to translate it by sending us pull requests!

While Selenium 4 provides direct access to the Chrome DevTools Protocol, these methods will eventually be removed when WebDriver BiDi implemented.

Console Logs

Implementation Missing

Add Example

JavaScript Exceptions

Implementation Missing

Implementation Missing

Add Example

4.2 - Chrome DevTools Network Features

Network features using CDP.

Page being translated from English to Japanese. Do you speak Japanese? Help us to translate it by sending us pull requests!

While Selenium 4 provides direct access to the Chrome DevTools Protocol, these methods will eventually be removed when WebDriver BiDi implemented.

Basic authentication

Some applications make use of browser authentication to secure pages. It used to be common to handle them in the URL, but browsers stopped supporting this. With this code you can insert the credentials into the header when necessary

Implementation Missing

Implementation Missing

Network Interception

Both requests and responses can be recorded or transformed.

Response information

Implementation Missing

Implementation Missing

Add Example

Response transformation

Implementation Missing

Implementation Missing

Add Example

Request interception

Implementation Missing

Implementation Missing

Add Example

Performance Metrics

Implementation Missing

Add Example

Setting Cookies

Implementation Missing

Add Example

Waiting for Downloads

Implementation Missing

Implementation Missing

Add Example

4.3 - Chrome DevTools Script Features

Script features using CDP.

Page being translated from English to Japanese. Do you speak Japanese? Help us to translate it by sending us pull requests!

While Selenium 4 provides direct access to the Chrome DevTools Protocol, these methods will eventually be removed when WebDriver BiDi implemented.

Script Pinning

Implementation Missing

Implementation Missing

Add Example

DOM Mutation Handlers

Implementation Missing

Add Example

5 - BiDirectional API (W3C compliant)

Page being translated from English to Japanese. Do you speak Japanese? Help us to translate it by sending us pull requests!

The following list of APIs will be growing as the WebDriver BiDirectional Protocol grows and browser vendors implement the same. Additionally, Selenium will try to support real-world use cases that internally use a combination of W3C BiDi protocol APIs.

If there is additional functionality you’d like to see, please raise a feature request.

5.1 - Browsing Context

Page being translated from English to Japanese. Do you speak Japanese? Help us to translate it by sending us pull requests!

Commands

This section contains the APIs related to browsing context commands.

Open a new window

Creates a new browsing context in a new window.

Selenium v4.8

Add Example

Selenium v4.8

Add Example

Open a new tab

Creates a new browsing context in a new tab.

Selenium v4.8

Add Example

Selenium v4.8

Add Example

Use existing window handle

Creates a browsing context for the existing tab/window to run commands.

Selenium v4.8

Add Example

Selenium v4.8

Add Example

Open a window with a reference browsing context

A reference browsing context is a top-level browsing context. The API allows to pass the reference browsing context, which is used to create a new window. The implementation is operating system specific.

Selenium v4.8

Add Example

Selenium v4.8

Add Example

Open a tab with a reference browsing context

A reference browsing context is a top-level browsing context. The API allows to pass the reference browsing context, which is used to create a new tab. The implementation is operating system specific.

Selenium v4.8

Add Example

Selenium v4.8

Add Example

Selenium v4.8

Add Example

Selenium v4.8

Add Example

Selenium v4.8

Add Example

Selenium v4.8

Add Example

Get browsing context tree

Provides a tree of all browsing contexts descending from the parent browsing context, including the parent browsing context.

Selenium v4.8

Add Example

Selenium v4.8

Add Example

Get browsing context tree with depth

Provides a tree of all browsing contexts descending from the parent browsing context, including the parent browsing context upto the depth value passed.

Selenium v4.8

Add Example

Selenium v4.8

Add Example

Get All Top level browsing contexts

Selenium v4.8

Add Example

Selenium v4.20.0

Add Example

Close a tab/window

Selenium v4.8

Add Example

Selenium v4.8

Add Example

Activate a browsing context

Selenium v4.14.1

Add Example

Selenium v4.15

Add Example

Reload a browsing context

Selenium v4.13.0

Add Example

Selenium v4.15

Add Example

Handle user prompt

Selenium v4.13.0

Add Example

Selenium v4.15

Add Example

Capture Screenshot

Selenium v4.13.0

Add Example

Selenium v4.15

Add Example

Capture Viewport Screenshot

Selenium v4.14.0

Add Example

Selenium v4.15

Add Example

Capture Element Screenshot

Selenium v4.14.0

Add Example

Selenium v4.15

Add Example

Set Viewport

Selenium v4.14.1

Add Example

Selenium v4.15

Add Example

Print page

Selenium v4.14.1

Add Example

Selenium v4.10

Add Example

Selenium v4.16.0

Add Example

Selenium v4.17

Add Example

Selenium v4.16.0

Add Example

Selenium v4.17

Add Example

Traverse history

Selenium v4.16.0

Add Example

Selenium v4.17

Add Example

Events

This section contains the APIs related to browsing context events.

Browsing Context Created Event

Selenium v4.10

Add Example

Selenium v4.9.2

Add Example

Dom Content loaded Event

Selenium v4.10

Add Example

Selenium v4.9.2

Add Example

Browsing Context Loaded Event

Selenium v4.10

Add Example

Selenium v4.9.2

Add Example

Selenium v4.15

Add Example

Add Example

Add Example

Fragment Navigated Event

Selenium v4.15

Add Example

Selenium v4.15.0

Add Example

User Prompt Opened Event

Selenium v4.15

Add Example

Add Example

Add Example

User Prompt Closed Event

Selenium v4.15

Add Example

Add Example

Add Example

Browsing Context Destroyed Event

Selenium v4.18

Add Example

Selenium v4.18.0

Add Example

5.2 - Browsing Context

Page being translated from English to Japanese. Do you speak Japanese? Help us to translate it by sending us pull requests!

This section contains the APIs related to input commands.

Perform Actions

Selenium v4.17

Add Example

Selenium v4.17

Add Example

Release Actions

Selenium v4.17

Add Example

Selenium v4.17

Add Example

5.3 - Network

Page being translated from English to Japanese. Do you speak Japanese? Help us to translate it by sending us pull requests!

Commands

This section contains the APIs related to network commands.

Add network intercept

Selenium v4.18

Selenium v4.32

Add Example

Selenium v4.18

Add Example

Remove network intercept

Selenium v4.18

Selenium v4.32

Add Example

Selenium v4.18

Add Example

Continue request blocked at authRequired phase with credentials

Selenium v4.18

Selenium v4.46

Add Example

Selenium v4.18

Add Example

Continue request blocked at authRequired phase without credentials

Selenium v4.18

Selenium v4.46

Add Example

Selenium v4.18

Add Example

Cancel request blocked at authRequired phase

Selenium v4.18

Selenium v4.46

Add Example

Selenium v4.18

Add Example

Fail request

Selenium v4.18

Selenium v4.46

Add Example

Add Example

Add Example

Events

This section contains the APIs related to network events.

Before Request Sent

Selenium v4.15

Selenium v4.32

Add Example

Selenium v4.18

Add Example

Response Started

Selenium v4.15

Add Example

Add Example

Selenium v4.18

Add Example

Response Completed

Selenium v4.15

Add Example

Add Example

Selenium v4.18

Add Example

Auth Required

Selenium v4.17

Selenium v4.46

Add Example

Add Example

Add Example

5.4 - Script

Page being translated from English to Japanese. Do you speak Japanese? Help us to translate it by sending us pull requests!

Commands

This section contains the APIs related to script commands.

Call function in a browsing context

Selenium v4.15

Add Example

Selenium v4.9

Add Example

Call function in a sandbox

Selenium v4.15

Add Example

Selenium v4.9

Add Example

Call function in a realm

Selenium v4.15

Add Example

Selenium v4.9

Add Example

Evaluate script in a browsing context

Selenium v4.15

Add Example

Selenium v4.9

Add Example

Evaluate script in a sandbox

Selenium v4.15

Add Example

Selenium v4.9

Add Example

Evaluate script in a realm

Selenium v4.15

Add Example

Selenium v4.9

Add Example

Disown handles in a browsing context

Selenium v4.15

Add Example

Selenium v4.9

Add Example

Disown handles in a realm

Selenium v4.15

Add Example

Selenium v4.9

Add Example

Get all realms

Selenium v4.15

Add Example

Selenium v4.9

Add Example

Get realm by type

Selenium v4.15

Add Example

Selenium v4.9

Add Example

Get browsing context realms

Selenium v4.15

Add Example

Selenium v4.9

Add Example

Get browsing context realms by type

Selenium v4.15

Add Example

Selenium v4.9

Add Example

Preload a script

Selenium v4.15

Add Example

Selenium v4.10

Add Example

Remove a preloaded script

Selenium v4.15

Add Example

Selenium v4.10

Add Example

Events

This section contains the APIs related to script events.

Message

Selenium v4.16

Add Example

Selenium v4.18

Add Example

Realm Created

Selenium v4.16

Add Example

Selenium v4.18

Add Example

Realm Destroyed

Selenium v4.16

Add Example

Selenium v4.19

Add Example

5.5 - BiDirectional API (W3C compliant)

Page being translated from English to Japanese. Do you speak Japanese? Help us to translate it by sending us pull requests!

This section contains the APIs related to logging.

Console logs

Listen to the console.log events and register callbacks to process the event.

Selenium v4.8

Selenium v4.15

Add Example

Add Example

JavaScript exceptions

Listen to the JS Exceptions and register callbacks to process the exception details.

Selenium v4.15

Add Example

Add Example

Listen to JS Logs

Listen to all JS logs at all levels and register callbacks to process the log.

Selenium v4.8

Add Example

Add Example

Add Example

Add Example