The Vibium Python API
— all 157 methods.

Starting up

Install with pip install vibium, then import and start. browser.start() returns a Browser instance synchronously. No event loop to manage, no async def, no asyncio.run() — just a function call that blocks until the browser is ready.

The naming follows Python conventions throughout: new_page, find_all, is_visible, set_content, inner_text. If you've used any Python test automation tool before, the method names will feel familiar before you finish the import line.

Pass headless=True to browser.start() for CI. The default is headed. Pass executable_path to point at a specific browser binary, or headers to set default request headers for every page in the session.

Navigating

Seven methods on page, identical in purpose to the JS surface. page.go(url) waits for load by default. For SPAs where the initial HTML lands fast but data populates asynchronously, follow the navigation with page.wait_until.url() or page.wait_until.loaded().

page.url() and page.title() read as natural assertions in Python — no boilerplate, no dot-notation on a result object. They return plain strings that sit cleanly inside assert expressions or pytest's assert introspection.

page.content() returns the current full-page HTML. Useful for snapshot testing — diff it against a stored baseline, or parse it with BeautifulSoup for structural assertions without depending on Vibium's element model.

Finding elements

page.find() returns a single Element. page.find_all() returns a list. Both accept keyword arguments: role, label, text, placeholder, selector. The most durable pattern is role + label — it survives layout changes and refactors because it targets semantics, not structure.

Find once, act many times. Once you hold an Element reference, every subsequent method call — .click(), .fill(), .text() — goes directly to that element without re-querying the DOM. This makes long interaction sequences both faster and more explicit about what the script is operating on.

Element interactions

Nineteen methods on every Element. The split between write and read methods is deliberate: fill() clears then types; type() types character-by-character without clearing first. Use fill for form inputs, type when you need to trigger per-keystroke event handlers.

is_visible(), is_enabled(), is_checked(), and is_editable() return plain Python booleans. They are the cleanest assertion primitives in the API — no wrapping, no helpers, no matcher libraries needed. Use them directly in assert statements.

bounds() returns a BoundingBox object with x, y, width, and height as attributes — access them as rect.x, rect.width, not dict-style. It's the right tool for layout assertions — checking that a tooltip appears above its trigger, that a modal is centred, or that two elements don't overlap.

Keyboard and mouse

When the element API doesn't reach — global keyboard shortcuts, drag operations, coordinate-based clicks in canvas elements — the page.keyboard and page.mouse sub-objects give you direct input control.

page.keyboard.type(text) types a full string with realistic per-character timing. Use it when element.type() isn't an option — for example, when the target element is a canvas-based input or a custom rich-text editor that intercepts keyboard events at the window level.

Waiting

Vibium's synchronous model means most actions already wait for the browser to settle. The explicit wait API is for cases where settling isn't defined by a single navigation — polling for an element to appear, waiting for a URL change after an async redirect, or confirming that a full SPA hydration is complete.

page.wait(ms) pauses execution for the given number of milliseconds. For waiting on element state, page.find() already auto-waits — the element wait is built into the find, not a separate step.

page.wait_until(expr) takes a JavaScript expression string. It evaluates the expression inside the page every 100ms until it returns a truthy value. This is the escape hatch for anything the built-in wait methods don't cover — custom DOM conditions, cross-element checks, or anything requiring a JS predicate before deciding the page is ready.

Capturing output and network

Dialog capture in Python follows the same fire-and-forget rule as TypeScript/JavaScript and MCP: the action that triggers the dialog must be called after starting the capture, and the call to the triggering action must not block before the dialog handler has run. In Python's synchronous model, this means starting the capture context manager, then calling the triggering action inside it.

page.route(url_pattern, handler) intercepts matching requests before they leave the browser. The handler receives a Route object with fulfill(), continue_(), and abort() — use it to stub APIs, inject feature flags, or simulate network errors without touching the server.

page.console_messages() returns a list of console entries captured since the last call. Filter by type — "error", "warning", "log" — to assert that a feature runs without producing console errors.

Browser contexts and the virtual clock

A browser context is an isolated session: separate cookies, separate storage, separate authentication state. Use bro.new_context() when you need to run tests as different users, or when parallel test workers must not share state.

ctx.storage() and ctx.cookies() read the current session state from a context where you've completed a login flow. Use them for inspection or to seed a new context via ctx.set_cookies() — keeping authentication state portable across contexts without repeating the login flow for every test.

The virtual clock intercepts Date, setTimeout, setInterval, and requestAnimationFrame inside the page. clock.install() freezes time at the current moment. clock.set_fixed_time() pins it to a specific ISO timestamp. clock.fast_forward() jumps time forward without blocking the test process — a timer that would take an hour to fire in production fires immediately in the test.