Bibbidi — W3C WebDriver BiDi Protocol for Elixir

I’m excited to share Bibbidi, a low-level Elixir implementation of the W3C WebDriver BiDi Protocol.

Bibbidi controlling another browser with Livebook1200×862 67.5 KB

BEAM Interface to Browsers with BiDi — the name is a nod to the Fairy Godmother’s spell in Disney’s Cinderella.

What is WebDriver BiDi?

WebDriver BiDi is a bidirectional protocol for browser automation. Unlike classic WebDriver (HTTP request/response), BiDi uses a persistent WebSocket connection that lets you send commands and receive real-time events from the browser — think console logs, network requests, navigation events, and more. It’s the successor to CDP (Chrome DevTools Protocol) but is a W3C standard with cross-browser support.

What is Bibbidi?

Bibbidi is a building-block library. It gives you WebSocket connectivity, command/response correlation, and event dispatch, but imposes no supervision tree. You supervise Bibbidi.Connection processes yourself, exactly how you want.

It’s designed as a foundation for RPA frameworks, browser testing libraries, and anything else that needs to talk BiDi to a browser.

Features

• Full protocol coverage — command builder modules for all BiDi domains: BrowsingContext, Script, Session, Input, Network, Storage, Browser, Emulation, Log, and WebExtension (although I’m adding more Integration tests to validate functionality)

• Real-time events — subscribe to browser events and receive them as regular Erlang messages ({:bibbidi_event, method, params})

• Swappable transport — ships with a mint_web_socket transport; bring your own via the Bibbidi.Transport behaviour

• Browser lifecycle — Bibbidi.Browser GenServer can launch and manage browser OS processes for you (OS process “culling” PRs or comments would be appreciated, this is an area for improvement)

• Types & events generated from the W3C CDDL spec — attempts to stay as close to the protocol definition as possible

• No opinionated supervision — fits into any OTP application architecture (I may add Igniter recipes in the future that include some useful supervision abstractions, but ideally this is not part of the library)

• Interactive Livebook — an included example with a Kino UI for navigating, clicking, running JS, taking screenshots, and watching live events

Quick example

{:ok, conn} = Bibbidi.Connection.start_link(url: "ws://localhost:9222/session")

{:ok, _caps} = Bibbidi.Session.new(conn)

{:ok, tree} = Bibbidi.Commands.BrowsingContext.get_tree(conn)

context = hd(tree["contexts"])["context"]

{:ok, _} = Bibbidi.Commands.BrowsingContext.navigate(conn, context, "https://example.com", wait: "complete")

{:ok, %{"result" => %{"value" => title}}} =

Bibbidi.Commands.Script.evaluate(conn, "document.title", %{context: context})

IO.puts("Page title: #{title}")

Supervision

Bibbidi doesn’t impose a process tree — add connections to your own supervisor:

children = [

{Bibbidi.Connection, url: "ws://localhost:9222/session", name: MyApp.Browser}

]

Supervisor.start_link(children, strategy: :one_for_one)

Try it in Livebook

The repo includes an Interactive Browser Livebook that lets you point-and-click navigate, run JavaScript, take screenshots, and watch browser events in real time.

Links

• Hex

• HexDocs

• GitHub

• W3C WebDriver BiDi Spec

Installation

def deps do

[
  {:bibbidi, "~> 0.1.0"}
]

end

This is v0.1.0 and still fairly early, so feedback, bug reports, and contributions are very welcome! I’d love to hear what you think and what you’d like to build with it.

https://github.com/petermueller/bibbidi