Skip to content

bidiwave

WebDriver BiDi for Python — a typed, async client for the W3C WebDriver Bidirectional Protocol. Talk to Chrome, Edge, and Firefox through a single standard API with real-time event streaming.

Why bidiwave?

  • W3C standard — no proprietary protocols, no browser-specific CDP hacks. One API for all browsers.
  • Real-time events — the WebSocket connection lets the browser push events to your script: console logs, network requests, navigation, and more. No polling.
  • Fully typed — every command, result, and event is a Pydantic model with type hints. IDE autocomplete and mypy strict mode work out of the box.
  • Async-first — built on asyncio and websockets. No threads, no blocking calls.
  • Resilient — automatic reconnection with exponential backoff.
  • Ergonomic — the Page object wraps browsing contexts with convenient methods. Pattern-match on RemoteValue for type-safe JS results.

Features

  • Browsing — create tabs/windows, navigate, take screenshots, wait for elements with MutationObserver-based selectors or JS expressions, control viewport with device pixel ratio, locate nodes via CSS/XPath
  • Script — evaluate JavaScript, call functions with arguments, handle remote values via typed RemoteValue subclasses, inject preload scripts with channel-based communication, inspect realms
  • Input — simulate mouse clicks, keyboard typing, scrolling, drag-and-drop, and file uploads with action sequences
  • Network — monitor requests/responses, intercept and block, modify headers/URLs, provide synthetic responses, cache overrides, retrieve response bodies, handle authentication challenges
  • Storage — get, set, and delete cookies with full attribute support (HttpOnly, Secure, SameSite, expires, etc.), monitor cookie changes
  • Emulation — override geolocation, network conditions, time zone, and user agent for device simulation
  • Permissions — grant or deny browser permissions (geolocation, camera, notifications) without user dialogs
  • Preload — inject scripts before page load for polyfills, monitoring, or test fixtures
  • CDP — access Chrome DevTools Protocol for browser-specific features not in the BiDi standard
  • Events — subscribe to browser events with async handlers, error isolation, and decorator support
  • Reconnection — automatic WebSocket reconnection with configurable retries and exponential backoff

Install

pip install bidiwave

See Installation for requirements and setup instructions.

Quick example

import asyncio
from bidiwave import BiDiClient, StringValue

async def main():
    async with await BiDiClient.connect("ws://localhost:9515/session") as client:
        # Listen to console logs
        async def on_log(entry):
            print(f"[{entry.level.upper()}] {entry.text}")

        client.on("log.entryAdded", on_log)
        await client.session.subscribe(["log.entryAdded"])

        # Open a page and interact with it
        async with await client.browsing.open("https://example.com") as page:
            result = await page.evaluate("document.title")
            match result:
                case StringValue(value=title):
                    print(f"Title: {title}")

            screenshot = await page.screenshot()
            with open("screenshot.png", "wb") as f:
                f.write(screenshot)

asyncio.run(main())

Documentation

Getting Started

Usage

  • Browsing — contexts, navigation, screenshots, waits, viewport
  • Script — evaluate JS, call functions, RemoteValue, preload scripts, realms
  • Events — real-time event subscriptions
  • Input Simulation — clicks, keyboard, scroll, drag
  • Network Interception — block, modify, mock, cache overrides, response bodies, auth
  • Cookies & Storage — get, set, delete cookies, cookie change events
  • Emulation — geolocation, network conditions, timezone, user agent
  • Permissions — grant or deny browser permissions
  • Preload Scripts — inject scripts before page load
  • CDP — Chrome DevTools Protocol access
  • Configuration — timeouts, reconnection, logging

Guides

API Reference

Reference