How to Migrate from Selenium to Vibium

Migrating from Selenium to Vibium is designed to start as a one-line change. Vibium's documented migration path is a Selenium compatibility layer: you swap from selenium import webdriver for from vibium.compat.selenium import webdriver and most existing scripts keep running — with no chromedriver binary to download or version-match, because Vibium speaks WebDriver BiDi directly. The compat layer maps the common Selenium surface (get, find_element, click, send_keys, quit) onto Vibium's BiDi engine. It is a migration bridge, not a bug-for-bug clone — edge cases around implicit waits and stale-element references differ — so plan to fix a few timing-sensitive tests. Once you are running, the recommended path is to adopt Vibium's clean native API for new code, which unlocks the built-in MCP server and AI-native methods. Fittingly, Vibium was built by Jason Huggins, who co-created Selenium itself.

Why migrate from Selenium to Vibium?

The biggest practical wins are packaging and the AI layer. Vibium removes the driver binary entirely, ships as a single Go binary that auto-downloads Chrome for Testing on first run, and adds capabilities Selenium never had: a built-in MCP server for AI agents, plus check() and do() methods for plain-English assertions and actions.

Selenium remains excellent for multi-language and Grid-based setups. Migrate when you want a leaner, BiDi-first foundation or you are building agentic automation in Python or JavaScript.

How do I install Vibium?

Install the client for your language. Vibium handles the browser download itself.

# Python
pip install vibium
 
# JavaScript / TypeScript
npm install vibium

There is no separate driver to install. See the install guide for details.

Step 1: Use the Selenium compatibility layer

The fastest path is the compat shim, which keeps your existing API and removes the driver binary. Change only the import.

# Before
from selenium import webdriver
driver = webdriver.Chrome()
 
# After — no chromedriver binary needed
from vibium.compat.selenium import webdriver
driver = webdriver.Chrome()

Everything downstream — driver.get(url), driver.find_element(By.CSS_SELECTOR, sel), element.click(), element.send_keys("text"), driver.quit() — keeps working because the layer translates those Selenium calls into Vibium's BiDi commands under the hood.

Step 2: Run your suite and fix timing edges

Run your existing tests against the compat layer and watch for the documented differences. Two areas commonly need attention:

• Implicit waits. Selenium's implicit wait is global across every find_element; the compat layer respects driver.implicitly_wait(seconds) by configuring Vibium's find timeout, but the exact timing can shift.
• Stale element references. Vibium elements are backed by BiDi remote object references with different lifecycle semantics, so StaleElementReferenceException may surface at different moments.

These are bridge-level edge cases, not blockers. Adjust the handful of timing-sensitive tests and move on.

Step 3: Adopt the native Vibium API for new code

For new tests, the recommended path is Vibium's native API rather than the compat shim. It is a clean, modern rewrite with auto-waiting on find built in.

from vibium import browser_sync as browser
 
vibe = browser.launch()
vibe.go("https://example.com/login")
 
vibe.find("#username").type("admin")
vibe.find("#password").type("secret")
vibe.find(role="button", text="Sign In").click()
 
print(vibe.find(".welcome").text())
vibe.quit()

Notice the single find() method that accepts either a CSS string or semantic keywords like role and text — no separate By strategies. See the automate-login guide for a full walkthrough.

What does Vibium add that Selenium cannot?

Once on the native API, you gain capabilities that have no Selenium equivalent: a built-in MCP server so AI agents drive the browser with zero glue (set it up in Claude Code), network interception via page.route(), multi-page automation with no switch_to.window(), and AI-native verification:

result = vibe.check("the user is logged in")
assert result.passed

What is the recommended migration path?

Treat the move as three phases rather than a big-bang rewrite.

1. Drop-in replacement. Change the import to the compat layer and get green.
2. Hybrid. Write all new tests in the native find()/click()/type() API; leave old tests on the compat shim.
3. Full migration. Incrementally rewrite legacy tests to the native API and remove the compat dependency.

The verdict

Vibium gives Selenium users an unusually gentle migration: a one-line import change removes driver binaries and gets most scripts running, then you adopt the native API at your own pace to unlock MCP and AI methods. Keep Selenium if you depend on Grid or non-Python/JS languages; otherwise the compat-then-native path is a low-risk way to modernize onto a BiDi-first foundation built by Selenium's own creator.

Next steps

• Vibium vs Selenium
• What is Vibium?
• Set up Vibium MCP in Claude Code