This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

BiDirectional functionality

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

10
12
Show full example
import pytest
from selenium.webdriver.common.by import By
from selenium.webdriver.support.wait import WebDriverWait


@pytest.mark.driver_type("bidi")
def test_add_console_log_handler(driver):
    driver.get('https://www.selenium.dev/selenium/web/bidi/logEntryAdded.html')
    log_entries = []

    driver.script.add_console_message_handler(log_entries.append)

    driver.find_element(By.ID, "consoleLog").click()
    WebDriverWait(driver, 5).until(lambda _: log_entries)
    assert log_entries[0].text == "Hello, world!"


@pytest.mark.driver_type("bidi")
def test_remove_console_log_handler(driver):
    driver.get('https://www.selenium.dev/selenium/web/bidi/logEntryAdded.html')
    log_entries = []

    id = driver.script.add_console_message_handler(log_entries.append)
    driver.script.remove_console_message_handler(id)

    driver.find_element(By.ID, "consoleLog").click()
    assert len(log_entries) == 0


@pytest.mark.driver_type("bidi")
def test_add_js_exception_handler(driver):
    driver.get('https://www.selenium.dev/selenium/web/bidi/logEntryAdded.html')
    log_entries = []

    driver.script.add_javascript_error_handler(log_entries.append)

    driver.find_element(By.ID, "jsException").click()
    WebDriverWait(driver, 5).until(lambda _: log_entries)
    assert log_entries[0].text == "Error: Not working"


@pytest.mark.driver_type("bidi")
def test_remove_js_exception_handler(driver):
    driver.get('https://www.selenium.dev/selenium/web/bidi/logEntryAdded.html')
    log_entries = []

    id = driver.script.add_javascript_error_handler(log_entries.append)
    driver.script.remove_javascript_error_handler(id)

    driver.find_element(By.ID, "consoleLog").click()
    assert len(log_entries) == 0
12
14
Show full example
# frozen_string_literal: true

require 'spec_helper'

RSpec.describe 'Logging' do
  let(:driver) { start_bidi_session }
  let(:wait) { Selenium::WebDriver::Wait.new(timeout: 2) }

  it 'adds console message handler' do
    driver.navigate.to 'https://www.selenium.dev/selenium/web/bidi/logEntryAdded.html'
    log_entries = []

    driver.script.add_console_message_handler { |log| log_entries << log }

    driver.find_element(id: 'consoleLog').click
    wait.until { log_entries.any? }
    expect(log_entries.first&.text).to eq 'Hello, world!'
  end

  it 'removes console message handler' do
    driver.navigate.to 'https://www.selenium.dev/selenium/web/bidi/logEntryAdded.html'
    log_entries = []

    id = driver.script.add_console_message_handler { |log| log_entries << log }
    driver.script.remove_console_message_handler(id)

    driver.find_element(id: 'consoleLog').click
    expect(log_entries).to be_empty
  end

  it 'adds JavaScript error handler' do
    driver.navigate.to 'https://www.selenium.dev/selenium/web/bidi/logEntryAdded.html'
    log_entries = []

    driver.script.add_javascript_error_handler { |error| log_entries << error }

    driver.find_element(id: 'jsException').click
    wait.until { log_entries.any? }
    expect(log_entries.first&.text).to eq 'Error: Not working'
  end

  it 'removes JavaScript error handler' do
    driver.navigate.to 'https://www.selenium.dev/selenium/web/bidi/logEntryAdded.html'
    log_entries = []

    id = driver.script.add_javascript_error_handler { |error| log_entries << error }
    driver.script.remove_javascript_error_handler(id)

    driver.find_element(id: 'jsException').click
    expect(log_entries).to be_empty
  end
end

Remove Handler

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

22
25
Show full example
import pytest
from selenium.webdriver.common.by import By
from selenium.webdriver.support.wait import WebDriverWait


@pytest.mark.driver_type("bidi")
def test_add_console_log_handler(driver):
    driver.get('https://www.selenium.dev/selenium/web/bidi/logEntryAdded.html')
    log_entries = []

    driver.script.add_console_message_handler(log_entries.append)

    driver.find_element(By.ID, "consoleLog").click()
    WebDriverWait(driver, 5).until(lambda _: log_entries)
    assert log_entries[0].text == "Hello, world!"


@pytest.mark.driver_type("bidi")
def test_remove_console_log_handler(driver):
    driver.get('https://www.selenium.dev/selenium/web/bidi/logEntryAdded.html')
    log_entries = []

    id = driver.script.add_console_message_handler(log_entries.append)
    driver.script.remove_console_message_handler(id)

    driver.find_element(By.ID, "consoleLog").click()
    assert len(log_entries) == 0


@pytest.mark.driver_type("bidi")
def test_add_js_exception_handler(driver):
    driver.get('https://www.selenium.dev/selenium/web/bidi/logEntryAdded.html')
    log_entries = []

    driver.script.add_javascript_error_handler(log_entries.append)

    driver.find_element(By.ID, "jsException").click()
    WebDriverWait(driver, 5).until(lambda _: log_entries)
    assert log_entries[0].text == "Error: Not working"


@pytest.mark.driver_type("bidi")
def test_remove_js_exception_handler(driver):
    driver.get('https://www.selenium.dev/selenium/web/bidi/logEntryAdded.html')
    log_entries = []

    id = driver.script.add_javascript_error_handler(log_entries.append)
    driver.script.remove_javascript_error_handler(id)

    driver.find_element(By.ID, "consoleLog").click()
    assert len(log_entries) == 0
23
26
Show full example
# frozen_string_literal: true

require 'spec_helper'

RSpec.describe 'Logging' do
  let(:driver) { start_bidi_session }
  let(:wait) { Selenium::WebDriver::Wait.new(timeout: 2) }

  it 'adds console message handler' do
    driver.navigate.to 'https://www.selenium.dev/selenium/web/bidi/logEntryAdded.html'
    log_entries = []

    driver.script.add_console_message_handler { |log| log_entries << log }

    driver.find_element(id: 'consoleLog').click
    wait.until { log_entries.any? }
    expect(log_entries.first&.text).to eq 'Hello, world!'
  end

  it 'removes console message handler' do
    driver.navigate.to 'https://www.selenium.dev/selenium/web/bidi/logEntryAdded.html'
    log_entries = []

    id = driver.script.add_console_message_handler { |log| log_entries << log }
    driver.script.remove_console_message_handler(id)

    driver.find_element(id: 'consoleLog').click
    expect(log_entries).to be_empty
  end

  it 'adds JavaScript error handler' do
    driver.navigate.to 'https://www.selenium.dev/selenium/web/bidi/logEntryAdded.html'
    log_entries = []

    driver.script.add_javascript_error_handler { |error| log_entries << error }

    driver.find_element(id: 'jsException').click
    wait.until { log_entries.any? }
    expect(log_entries.first&.text).to eq 'Error: Not working'
  end

  it 'removes JavaScript error handler' do
    driver.navigate.to 'https://www.selenium.dev/selenium/web/bidi/logEntryAdded.html'
    log_entries = []

    id = driver.script.add_javascript_error_handler { |error| log_entries << error }
    driver.script.remove_javascript_error_handler(id)

    driver.find_element(id: 'jsException').click
    expect(log_entries).to be_empty
  end
end

JavaScript Exception Handlers

Record or take actions on JavaScript exception events.

Add Handler

34
36
Show full example
import pytest
from selenium.webdriver.common.by import By
from selenium.webdriver.support.wait import WebDriverWait


@pytest.mark.driver_type("bidi")
def test_add_console_log_handler(driver):
    driver.get('https://www.selenium.dev/selenium/web/bidi/logEntryAdded.html')
    log_entries = []

    driver.script.add_console_message_handler(log_entries.append)

    driver.find_element(By.ID, "consoleLog").click()
    WebDriverWait(driver, 5).until(lambda _: log_entries)
    assert log_entries[0].text == "Hello, world!"


@pytest.mark.driver_type("bidi")
def test_remove_console_log_handler(driver):
    driver.get('https://www.selenium.dev/selenium/web/bidi/logEntryAdded.html')
    log_entries = []

    id = driver.script.add_console_message_handler(log_entries.append)
    driver.script.remove_console_message_handler(id)

    driver.find_element(By.ID, "consoleLog").click()
    assert len(log_entries) == 0


@pytest.mark.driver_type("bidi")
def test_add_js_exception_handler(driver):
    driver.get('https://www.selenium.dev/selenium/web/bidi/logEntryAdded.html')
    log_entries = []

    driver.script.add_javascript_error_handler(log_entries.append)

    driver.find_element(By.ID, "jsException").click()
    WebDriverWait(driver, 5).until(lambda _: log_entries)
    assert log_entries[0].text == "Error: Not working"


@pytest.mark.driver_type("bidi")
def test_remove_js_exception_handler(driver):
    driver.get('https://www.selenium.dev/selenium/web/bidi/logEntryAdded.html')
    log_entries = []

    id = driver.script.add_javascript_error_handler(log_entries.append)
    driver.script.remove_javascript_error_handler(id)

    driver.find_element(By.ID, "consoleLog").click()
    assert len(log_entries) == 0
34
36
Show full example
# frozen_string_literal: true

require 'spec_helper'

RSpec.describe 'Logging' do
  let(:driver) { start_bidi_session }
  let(:wait) { Selenium::WebDriver::Wait.new(timeout: 2) }

  it 'adds console message handler' do
    driver.navigate.to 'https://www.selenium.dev/selenium/web/bidi/logEntryAdded.html'
    log_entries = []

    driver.script.add_console_message_handler { |log| log_entries << log }

    driver.find_element(id: 'consoleLog').click
    wait.until { log_entries.any? }
    expect(log_entries.first&.text).to eq 'Hello, world!'
  end

  it 'removes console message handler' do
    driver.navigate.to 'https://www.selenium.dev/selenium/web/bidi/logEntryAdded.html'
    log_entries = []

    id = driver.script.add_console_message_handler { |log| log_entries << log }
    driver.script.remove_console_message_handler(id)

    driver.find_element(id: 'consoleLog').click
    expect(log_entries).to be_empty
  end

  it 'adds JavaScript error handler' do
    driver.navigate.to 'https://www.selenium.dev/selenium/web/bidi/logEntryAdded.html'
    log_entries = []

    driver.script.add_javascript_error_handler { |error| log_entries << error }

    driver.find_element(id: 'jsException').click
    wait.until { log_entries.any? }
    expect(log_entries.first&.text).to eq 'Error: Not working'
  end

  it 'removes JavaScript error handler' do
    driver.navigate.to 'https://www.selenium.dev/selenium/web/bidi/logEntryAdded.html'
    log_entries = []

    id = driver.script.add_javascript_error_handler { |error| log_entries << error }
    driver.script.remove_javascript_error_handler(id)

    driver.find_element(id: 'jsException').click
    expect(log_entries).to be_empty
  end
end

Remove Handler

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

46
49
Show full example
import pytest
from selenium.webdriver.common.by import By
from selenium.webdriver.support.wait import WebDriverWait


@pytest.mark.driver_type("bidi")
def test_add_console_log_handler(driver):
    driver.get('https://www.selenium.dev/selenium/web/bidi/logEntryAdded.html')
    log_entries = []

    driver.script.add_console_message_handler(log_entries.append)

    driver.find_element(By.ID, "consoleLog").click()
    WebDriverWait(driver, 5).until(lambda _: log_entries)
    assert log_entries[0].text == "Hello, world!"


@pytest.mark.driver_type("bidi")
def test_remove_console_log_handler(driver):
    driver.get('https://www.selenium.dev/selenium/web/bidi/logEntryAdded.html')
    log_entries = []

    id = driver.script.add_console_message_handler(log_entries.append)
    driver.script.remove_console_message_handler(id)

    driver.find_element(By.ID, "consoleLog").click()
    assert len(log_entries) == 0


@pytest.mark.driver_type("bidi")
def test_add_js_exception_handler(driver):
    driver.get('https://www.selenium.dev/selenium/web/bidi/logEntryAdded.html')
    log_entries = []

    driver.script.add_javascript_error_handler(log_entries.append)

    driver.find_element(By.ID, "jsException").click()
    WebDriverWait(driver, 5).until(lambda _: log_entries)
    assert log_entries[0].text == "Error: Not working"


@pytest.mark.driver_type("bidi")
def test_remove_js_exception_handler(driver):
    driver.get('https://www.selenium.dev/selenium/web/bidi/logEntryAdded.html')
    log_entries = []

    id = driver.script.add_javascript_error_handler(log_entries.append)
    driver.script.remove_javascript_error_handler(id)

    driver.find_element(By.ID, "consoleLog").click()
    assert len(log_entries) == 0
45
48
Show full example
# frozen_string_literal: true

require 'spec_helper'

RSpec.describe 'Logging' do
  let(:driver) { start_bidi_session }
  let(:wait) { Selenium::WebDriver::Wait.new(timeout: 2) }

  it 'adds console message handler' do
    driver.navigate.to 'https://www.selenium.dev/selenium/web/bidi/logEntryAdded.html'
    log_entries = []

    driver.script.add_console_message_handler { |log| log_entries << log }

    driver.find_element(id: 'consoleLog').click
    wait.until { log_entries.any? }
    expect(log_entries.first&.text).to eq 'Hello, world!'
  end

  it 'removes console message handler' do
    driver.navigate.to 'https://www.selenium.dev/selenium/web/bidi/logEntryAdded.html'
    log_entries = []

    id = driver.script.add_console_message_handler { |log| log_entries << log }
    driver.script.remove_console_message_handler(id)

    driver.find_element(id: 'consoleLog').click
    expect(log_entries).to be_empty
  end

  it 'adds JavaScript error handler' do
    driver.navigate.to 'https://www.selenium.dev/selenium/web/bidi/logEntryAdded.html'
    log_entries = []

    driver.script.add_javascript_error_handler { |error| log_entries << error }

    driver.find_element(id: 'jsException').click
    wait.until { log_entries.any? }
    expect(log_entries.first&.text).to eq 'Error: Not working'
  end

  it 'removes JavaScript error handler' do
    driver.navigate.to 'https://www.selenium.dev/selenium/web/bidi/logEntryAdded.html'
    log_entries = []

    id = driver.script.add_javascript_error_handler { |error| log_entries << error }
    driver.script.remove_javascript_error_handler(id)

    driver.find_element(id: 'jsException').click
    expect(log_entries).to be_empty
  end
end

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

Request Handlers

Response 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.

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.

21
28
<details class="mt-3">
  <summary>Show full example</summary>
  <div class="pt-2">
    <div class="highlight"><pre tabindex="0" style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-java" data-lang="java"><span style="display:flex;"><span><span style="color:#204a87;font-weight:bold">package</span><span style="color:#f8f8f8;text-decoration:underline"> </span><span style="color:#000">dev.selenium.bidi.cdp</span><span style="color:#000;font-weight:bold">;</span><span style="color:#f8f8f8;text-decoration:underline">

import dev.selenium.BaseTest; import org.junit.jupiter.api.Assertions; import org.junit.jupiter.api.BeforeEach; import org.junit.jupiter.api.Test; import org.openqa.selenium.Cookie; import org.openqa.selenium.chrome.ChromeDriver; import org.openqa.selenium.chromium.HasCdp; import java.util.HashMap; import java.util.Map; public class CdpTest extends BaseTest { @BeforeEach public void createSession() { driver = new ChromeDriver(); } @Test public void setCookie() { Map<String, Object> cookie = new HashMap<>(); cookie.put("name", "cheese"); cookie.put("value", "gouda"); cookie.put("domain", "www.selenium.dev"); cookie.put("secure", true); ((HasCdp) driver).executeCdpCommand("Network.setCookie", cookie); driver.get("https://www.selenium.dev"); Cookie cheese = driver.manage().getCookieNamed("cheese"); Assertions.assertEquals("gouda", cheese.getValue()); } }

<div class="text-end pb-2 mt-2">
  <a href="https://github.com/SeleniumHQ/seleniumhq.github.io/blob/display_full//examples/java/src/test/java/dev/selenium/bidi/cdp/CdpTest.java#L22-L27" target="_blank">
    <i class="fas fa-external-link-alt pl-2"></i>
    <strong>View full example on GitHub</strong>
  </a>
</div>
1
8
<details class="mt-3">
  <summary>Show full example</summary>
  <div class="pt-2">
    <div class="highlight"><pre tabindex="0" style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-py" data-lang="py"><span style="display:flex;"><span><span style="color:#204a87;font-weight:bold">def</span> <span style="color:#000">test_set_cookie</span><span style="color:#000;font-weight:bold">(</span><span style="color:#000">driver</span><span style="color:#000;font-weight:bold">):</span>

cookie = {'name': 'cheese', 'value': 'gouda', 'domain': 'www.selenium.dev', 'secure': True} driver.execute_cdp_cmd('Network.setCookie', cookie) driver.get('https://www.selenium.dev') cheese = driver.get_cookie(cookie['name']) assert cheese['value'] == 'gouda'

<div class="text-end pb-2 mt-2">
  <a href="https://github.com/SeleniumHQ/seleniumhq.github.io/blob/display_full//examples/python/tests/bidi/cdp/test_cdp.py#L2-L7" target="_blank">
    <i class="fas fa-external-link-alt pl-2"></i>
    <strong>View full example on GitHub</strong>
  </a>
</div>