Skip to content

WebDriver BiDi: Raw Protocol Tutorial

Learn WebDriver BiDi by talking directly to Firefox with nothing but a terminal and websocat. No libraries, no abstractions — just raw JSON over WebSocket.

By the end, you’ll understand exactly what Vibium does under the hood.

  • Firefox (any recent version)
  • websocat — WebSocket CLI tool
  • A terminal

macOS:

Terminal window
brew install websocat

Linux:

Terminal window
# Debian/Ubuntu
sudo apt install websocat
# Or via Cargo (any platform)
cargo install websocat

Windows:

Terminal window
# Via Scoop
scoop install websocat
# Or download from GitHub releases

macOS: Press Cmd+Space, type “Terminal”, press Enter

Linux: Press Ctrl+Alt+T or find Terminal in your applications

Windows: Press Win+R, type “cmd” or “powershell”, press Enter

Firefox has native WebDriver BiDi support. Launch it with remote debugging enabled.

macOS:

Terminal window
/Applications/Firefox.app/Contents/MacOS/firefox --remote-debugging-port=9222

Linux:

Terminal window
firefox --remote-debugging-port=9222

Windows (Command Prompt):

Terminal window
"C:\Program Files\Mozilla Firefox\firefox.exe" --remote-debugging-port=9222

Windows (PowerShell):

Terminal window
& "C:\Program Files\Mozilla Firefox\firefox.exe" --remote-debugging-port=9222

Firefox starts and listens for BiDi connections on port 9222. Leave this terminal open.

In a new terminal, connect to Firefox:

Terminal window
websocat ws://localhost:9222/session

You’re now talking directly to the browser over WebSocket. Every message you send and receive is JSON.

Send the session.new command to create a BiDi session:

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

Firefox responds with session info:

{
"type": "success",
"id": 1,
"result": {
"sessionId": "...",
"capabilities": { ... }
}
}

Firefox usually opens with a blank tab. Get its context ID:

{"id": 2, "method": "browsingContext.getTree", "params": {}}

Response:

{
"type": "success",
"id": 2,
"result": {
"contexts": [
{ "context": "abc123", "url": "about:blank", ... }
]
}
}

Note the "context" value — you’ll need it for all subsequent commands.

Go to example.com (replace abc123 with your actual context ID):

{"id": 3, "method": "browsingContext.navigate", "params": {"context": "abc123", "url": "https://example.com", "wait": "complete"}}

Response confirms navigation:

{
"type": "success",
"id": 3,
"result": {
"navigation": "...",
"url": "https://example.com/"
}
}

Use script.evaluate to run JavaScript in the page:

{"id": 4, "method": "script.evaluate", "params": {"expression": "document.title", "target": {"context": "abc123"}, "awaitPromise": false}}

Response:

{
"type": "success",
"id": 4,
"result": {
"type": "success",
"realm": "...",
"result": { "type": "string", "value": "Example Domain" }
}
}

What’s realm? A realm is BiDi’s term for a JavaScript execution environment — roughly one per page or iframe. The browser returns which realm the script ran in so you can track results across multiple contexts.

First, get the link’s position. Note: getBoundingClientRect() returns a DOMRect whose properties live on the prototype, so BiDi won’t serialize them directly. Extract them into a plain object:

{"id": 5, "method": "script.evaluate", "params": {"expression": "(() => { const r = document.querySelector('a').getBoundingClientRect(); return { x: r.x, y: r.y, width: r.width, height: r.height }; })()", "target": {"context": "abc123"}, "awaitPromise": false}}

Response gives you the bounding box:

{
"type": "success",
"id": 5,
"result": {
"type": "success",
"realm": "...",
"result": {
"type": "object",
"value": [
["x", { "type": "number", "value": 216 }],
["y", { "type": "number", "value": 203 }],
["width", { "type": "number", "value": 82 }],
["height", { "type": "number", "value": 20 }]
]
}
}
}

Now click at the center of that element using input.performActions (calculate center from the coordinates above):

{"id": 6, "method": "input.performActions", "params": {"context": "abc123", "actions": [{"type": "pointer", "id": "mouse", "actions": [{"type": "pointerMove", "x": 257, "y": 213}, {"type": "pointerDown", "button": 0}, {"type": "pointerUp", "button": 0}]}]}}

The browser clicks and navigates to the link target.

End the session:

{"id": 7, "method": "browser.close", "params": {}}

Firefox closes.


You automated a browser using nothing but:

  • WebSocket connection
  • JSON messages
  • The WebDriver BiDi protocol

This is how browser automation works at the protocol level — JSON commands over WebSocket. Vibium is built on BiDi from the start. Selenium has adopted it too. Playwright is investigating BiDi but still relies on CDP and custom protocols.

BrowserVibiumPlaywrightSelenium
ChromeWebDriver BiDiCDPWebDriver BiDi
FirefoxWebDriver BiDiCustom protocol (patched browser)WebDriver BiDi
Safari—Custom protocol (patched WebKit)WebDriver (classic)

Vibium supports Chrome and Firefox via BiDi. Vibium drives Firefox the same way this tutorial does: launch with --remote-debugging-port, then speak BiDi over the WebSocket. Safari BiDi is still in development by Apple.

Playwright requires patched browser builds maintained by Microsoft. Vibium uses stock browsers from each vendor via the W3C standard protocol.


Raw BiDi is powerful but tedious. Here’s what Vibium handles for you:

You had to manually:

  • Launch Firefox with the right flags
  • Connect to the WebSocket
  • Track context IDs

Vibium does this automatically. browser.start() handles everything.

When you clicked, you:

  • Found the element’s bounding box
  • Calculated the center coordinates
  • Sent pointer actions

But what if the element wasn’t visible? Or was covered by an overlay? Or still animating?

Vibium waits for elements to be actionable before interacting:

CheckWhat it means
VisibleHas non-zero size, not visibility: hidden
StableSame position for 2 consecutive checks (not animating)
Receives EventsNot covered by another element
EnabledNot disabled or aria-disabled
EditableFor typing: not readonly (in addition to above)

When you call element.click(), Vibium polls these checks until they all pass (or timeout). You never send a click to a hidden button.

You had to manually wait for navigation to complete ("wait": "complete").

Vibium’s find() automatically waits for elements to appear. No explicit waits, no sleep statements.

Raw BiDi errors are cryptic:

{"id": 5, "error": "no such element", "message": "Unable to locate element"}

Vibium gives you context:

TimeoutError: Element not found: button.submit
Waited 30s for element to appear
Page: https://example.com/checkout

LayerWhat it does
WebDriver BiDiThe protocol: JSON over WebSocket
BrowserExecutes commands, returns results
VibiumConnection management, actionability, auto-waiting, errors
Your codevibe.find({ css: 'a' }).click()

The raw protocol is simple. Everything else is saving you from writing it by hand.