Learn Vibium in a Weekend

You can learn Vibium in a weekend by following a two-day plan: install it and run your first script on Saturday morning, master locators and auto-waiting by Saturday night, then wire up the MCP server and ship a real project on Sunday. Vibium is AI-native browser automation built on WebDriver BiDi, shipped as a single Go binary that auto-downloads Chrome. Because a complete script is just launch, go, find, act, and close, the learning curve is short and the payoff is immediate. This guide gives you a concrete hour-by-hour schedule with runnable JavaScript and Python code, the exact commands to type, and the internal guides to open at each step. By Sunday night you will have written scrapers, form-fillers, and screenshot scripts, and connected an AI agent to a live browser. Vibium was created by Jason Huggins, co-creator of Selenium and Appium; this site is an independent hub that simply teaches it.

What does the Vibium weekend plan actually cover?

The weekend plan is a four-stage path from zero to a shipped project, with each stage building on the last. You do not need to finish everything to be useful; each stage leaves you with a working skill you can stop at.

The idea is to spend Saturday on the deterministic core (the part every Vibium user needs) and Sunday on the AI-native layer and a real deliverable. Here is the map:

If you only have one day, do Stage 1 and Stage 2 — that is the 80% that makes Vibium worth learning. Save Stages 3 and 4 for later.

Saturday morning: how do I install Vibium and run my first script?

Start by installing Vibium into a fresh project, because it downloads its own Chrome for Testing and needs no separate browser or driver. Give yourself about 45 minutes for this stage, including the download.

Vibium has two supported clients with almost identical APIs. Pick one language for the whole weekend so your skills compound. If you are unsure which, the what is Vibium overview explains the tradeoffs.

For JavaScript, create a project and install the package:

mkdir vibium-weekend && cd vibium-weekend
npm init -y
npm install vibium

For Python, use a virtual environment so the install stays isolated:

mkdir vibium-weekend && cd vibium-weekend
python3 -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install vibium

If either command fails, the install Vibium guide covers Node and Python setup, PATH issues, and Linux Chrome dependencies in detail.

What should my very first script do?

Your first script should launch a real Chrome window, load a page, save a screenshot, and click a link, so you see every core method fire once. This is the "hello world" of browser automation.

Create hello.js and paste this. It uses the synchronous API, which reads top to bottom with no await:

const fs = require("fs");
const { browser } = require("vibium/sync");
 
// Launch Chrome and grab the default tab
const bro = browser.launch();
const page = bro.page();
 
// Navigate to a page
page.go("https://example.com");
console.log("Loaded:", page.title());
 
// Save a screenshot (screenshot() returns PNG bytes)
fs.writeFileSync("example.png", page.screenshot());
console.log("Saved example.png");
 
// Find a link, read it, then click it
const link = page.find("a");
console.log("Link text:", link.text());
link.click();
 
bro.close();

Run it with node hello.js. Chrome opens, loads the page, and closes; a new example.png appears in your folder.

The Python version is the same shape:

from vibium import browser
 
# Launch Chrome and grab the default tab
bro = browser.launch()
page = bro.page()
 
# Navigate to a page
page.go("https://example.com")
print("Loaded:", page.title())
 
# Save a screenshot (screenshot() returns PNG bytes)
with open("example.png", "wb") as f:
    f.write(page.screenshot())
print("Saved example.png")
 
# Find a link, read it, then click it
link = page.find("a")
print("Link text:", link.text())
link.click()
 
bro.close()

Run it with python3 hello.py. If you want a slower, more explained walkthrough of these lines, read your first Vibium script.

What does each first-script method do?

Each call maps to exactly one browser action, which is why Vibium scripts stay readable even as they grow.

By the end of Saturday morning you have installed Vibium and run a real script. That is genuinely the hardest part behind you.

Saturday afternoon: how do I find elements and avoid flaky waits?

Spend the afternoon on locators and auto-waiting, because those two topics separate scripts that break constantly from scripts you can trust. This is the most valuable hour of the weekend.

Vibium has one find() method with two signatures. Pass a string for a CSS selector, or an object for semantic strategies like role, text, and label. Semantic locators survive markup refactors far better than deep CSS paths.

const { browser } = require("vibium/sync");
 
const bro = browser.launch();
const page = bro.page();
page.go("https://duckduckgo.com");
 
// CSS selector — a plain string
page.find("input[name='q']").type("vibium browser automation");
 
// Semantic locators — an object (role, text, label, placeholder...)
page.find({ role: "button", text: "Search" }).click();
 
console.log(page.title());
bro.close();

In Python the semantic form uses keyword arguments, which reads even more cleanly:

from vibium import browser
 
bro = browser.launch()
page = bro.page()
page.go("https://duckduckgo.com")
 
page.find("input[name='q']").type("vibium browser automation")
page.find(role="button", text="Search").click()
 
print(page.title())
bro.close()

The combinable form — find({ role: "button", text: "Search" }) — is a Vibium signature feature. It matches on role and text in a single call, where older tools force you to chain filters. For a deeper tour of selectors and the returned element, see find element.

Why don't I need to write waits?

You do not write waits because Vibium enforces actionability inside its Go engine before every interaction. It polls until the target element is visible, stable, enabled, and able to receive the event, up to a 30-second default timeout.

That single design choice removes the setTimeout and stale-element retry code that makes older automation frustrating for beginners. When you call click(), Vibium has already confirmed the element is ready. This is how Vibium works under the hood, and it is the main reason the tool is beginner-friendly.

What should I practice on Saturday afternoon?

Practice by reading, typing, and clicking on a real site so the core loop becomes muscle memory. Try these three micro-exercises before you stop for the day:

1. Read data. Open a page, find() a heading, and print its text().
2. Fill a form. Locate an input with a semantic locator and type() into it. Follow the full pattern in automate a login with Vibium.
3. Capture proof. Save a screenshot() after an action so you can verify results. See screenshot for full-page and element captures.

Do these in both the sync style shown here and, optionally, the async style. The sync vs async guide explains when each is the right choice — the short version is sync for linear scripts, async when you are already inside async code.

What beginner mistakes should I avoid this weekend?

Most first-weekend problems come from a handful of predictable mistakes, so knowing them in advance saves you an hour of confusion. Watch for these four.

• Adding manual sleeps. Because Vibium already auto-waits, sprinkling page.wait(3000) calls slows your scripts down for no benefit and hides real timing issues. Only reach for an explicit wait when you are waiting on something that is not an element, like a network response.
• Over-specific CSS selectors. A selector like div.container > div:nth-child(3) > a.link breaks the moment the markup shifts. Prefer a semantic locator such as find({ role: "link", text: "Next" }), which describes intent instead of structure.
• Forgetting to close the browser. If a script throws before bro.close(), Chrome can linger. Wrap risky code in try/finally (JavaScript) or a try/finally block (Python) so the browser always shuts down.
• Confusing sync and async imports. require("vibium/sync") gives you the no-await API used all weekend; the bare require("vibium") is the async API and needs await on every call. Mixing them is the single most common beginner error.

Keeping these in mind turns Saturday's scripts from "works once" into "works every time," which is the whole point of the afternoon.

Sunday morning: how do I use the AI and MCP features?

On Sunday morning, add the AI-native layer that makes Vibium different from Selenium or Playwright. These features sit on top of the deterministic API you already learned, so nothing you did on Saturday is wasted.

Vibium ships two AI methods. page.check() verifies a plain-English claim about the page, and page.do() performs a plain-English action by planning real find/click/type calls under the hood.

const { browser } = require("vibium/sync");
 
const bro = browser.launch();
const page = bro.page();
page.go("https://example.com");
 
// Plain-English verification — returns a structured result
const result = page.check("the page has a heading and a link");
console.log(result.passed, result.reason);
 
bro.close();

The key mental model: check() and do() are AI planning, not AI puppeteering. They call Vibium's own deterministic commands, so their actions are the same ones you would write by hand. Treat them as a convenience for when you want to describe intent rather than name a selector.

How do I connect Vibium to an AI agent?

Connect Vibium to an AI coding agent by registering its built-in MCP server, which exposes browser commands as tools the agent can call. This turns "browse the web" into something Claude Code or Cursor can do directly.

For Claude Code, add the server with a single command:

claude mcp add vibium -- npx -y vibium mcp

Now an AI agent can launch a browser, navigate, and read pages on your behalf through natural-language requests. The full setup, including verification and troubleshooting, is in set up Vibium MCP in Claude Code.

This is a good moment to appreciate what you have assembled: the same Go binary that runs your scripts also serves the MCP endpoint, so there is nothing extra to install. Spend the rest of the morning asking your agent to perform small browsing tasks and watching which Vibium commands it invokes.

Sunday afternoon: what project should I ship?

Finish the weekend by combining your skills into one small, real project, because shipping something cements the learning far better than more tutorials. Pick the project that matches why you started.

Here is a decision table to choose fast:

How do I build a small scraper as my project?

Build a scraper by looping over the results of findAll() and reading each element, which is the foundation of nearly every data-extraction task. This example collects every link on a page:

const { browser } = require("vibium/sync");
 
const bro = browser.launch({ headless: true });
const page = bro.page();
page.go("https://example.com");
 
// findAll returns an array immediately
const links = page.findAll("a");
for (const link of links) {
  console.log(link.text(), "->", link.attr("href"));
}
 
console.log(`Found ${links.length} links`);
bro.close();

The Python equivalent uses the same methods:

from vibium import browser
 
bro = browser.launch(headless=True)
page = bro.page()
page.go("https://example.com")
 
links = page.find_all("a")
for link in links:
    print(link.text(), "->", link.attr("href"))
 
print(f"Found {len(links)} links")
bro.close()

Notice headless: True (or headless=True in Python) — that runs Chrome without a visible window, which is what you want for a real scraping or CI job. To extend this into a full data pipeline, follow the patterns in the how-to guides section of this site.

Headed versus headless is worth understanding before you ship. Run headed (the default, a visible window) while you develop, so you can watch the browser and spot when a locator misses. Switch to headless once the script works, because it starts faster, uses less memory, and runs on servers with no display. The behavior is identical either way — the only difference is whether a window is drawn — so a script debugged headed will behave the same headless. When something misbehaves in headless mode, flip it back to headed for one run and watch what the browser actually does.

How do I build a UI test as my project?

Build a UI test by wrapping the launch/act/assert flow in your test runner and quitting the browser in teardown. This Jest-style test verifies a page loads a heading:

const assert = require("node:assert");
const { browser } = require("vibium/sync");
 
test("example page has a heading", () => {
  const bro = browser.launch({ headless: true });
  const page = bro.page();
  try {
    page.go("https://example.com");
    const heading = page.find("h1");
    assert.ok(heading.text().length > 0, "heading should not be empty");
  } finally {
    bro.close();
  }
});

Always close the browser in a finally block or a teardown hook so a failed assertion never leaves a stray Chrome process behind. To scale this into a maintainable suite, adopt the page object model, which keeps your locators in one place as your tests grow.

What does a realistic weekend schedule look like?

A realistic schedule keeps each session to about two hours with breaks, because browser automation is best learned in short, hands-on bursts rather than one long marathon. Use this as your checklist.

If you fall behind, drop Sunday morning first — the MCP and AI layer is powerful but optional. The Saturday material is the true foundation, and finishing it alone makes the weekend a success.

How do I keep learning after the weekend?

Keep learning by picking one direction — testing, scraping, or AI agents — and going deep with the topic-specific guides on this site, rather than trying to learn everything at once. You now have the vocabulary to follow any of them.

Two habits accelerate the next phase. First, always prefer semantic locators over brittle CSS so your scripts survive site changes. Second, keep the glossary open for unfamiliar terms like actionability, BiDi, and MCP; a shared vocabulary makes every other article faster to read.

Vibium itself is Jason Huggins' open-source project at vibium.com and on GitHub. This site is an independent learning hub — we just teach the tool. If you want a longer, structured path beyond the weekend, the guided course sequences these topics into a full curriculum.

Next steps

• Install Vibium — the definitive setup guide for Node and Python.
• Your first Vibium script — a slower, line-by-line walkthrough.
• Find element — the full locator reference, CSS and semantic.
• Automate a login with Vibium — your first real end-to-end flow.
• Set up Vibium MCP in Claude Code — connect an AI agent to a live browser.
• Page object model — structure tests before they grow.
• The course — a guided path that goes beyond a single weekend.