The Vibium JS API
— all 68 methods.

Starting up

Install with npm install vibium, then import and start. The entry point is Vibium.start() — it returns a Browser instance. From there, every operation flows through the object model: browser → page → element.

Three lines to go from import to first interaction. The async/await model is consistent throughout — every method on Page, Element, and Browser returns a promise. There are no callbacks, no event emitters, no synchronous steps.

Pass { headless: true } to Vibium.start() for CI runs. The default is headed — the browser window is visible, which is what you want during development when you're watching what the script does.

Navigating

Seven methods, all on page. page.go(url) navigates and waits for load by default. Pass an options object with waitUntil to control the load condition — "networkidle" for SPAs, "commit" when you want to proceed immediately after the navigation commits without waiting for content.

page.url() and page.title() are the most common assertion primitives in navigation-heavy test suites — lightweight, readable, and independent of any element on the page. page.content() returns the full page HTML as a string, useful when you need to inspect raw markup without querying individual elements.

page.back(), page.forward(), and page.reload() mirror browser button behaviour. All three wait for the page to settle before resolving, so you can call page.find() immediately after without sleeping.

Finding elements

Two methods. The entire element interaction model flows through these two. page.find() returns a single Element handle — an object with 19 methods on it. page.findAll() returns an array of them.

page.find() waits for the element to appear before returning. The default timeout is 30 seconds — pass a timeout property in the selector object to override it. If the element doesn't appear within the timeout, the promise rejects with a descriptive error.

Element interactions

Nineteen methods on the Element object returned by page.find(). The pattern is consistent: find once, interact many times on the same handle.

el.fill() clears the field and types in one operation. el.type() appends character-by-character — use it when autocomplete needs to fire on each keystroke. el.select() picks a <select> option by its visible label or value attribute.

The four read methods cover the full spread of what you need from an element's content. el.text() is raw textContent — includes hidden text, line breaks from block-level children. el.innerText() is the rendered version — what a user would actually see and copy. el.value() reads the current value of any form input. el.getAttribute(name) retrieves any HTML attribute by name.

The four boolean methods are guard tools. Check el.isEnabled() before clicking a submit button if you're verifying that the form's validation state is correct. el.isVisible() tests whether the element is in the viewport and not hidden by CSS. el.isChecked() reads checkbox and radio state. el.isReadOnly() checks the readonly attribute on form fields.

el.bounds() returns the element's position and dimensions as { x, y, width, height } — useful for layout assertions or for computing coordinates when you need to interact with a specific region inside an element.

Keyboard and mouse

Eight methods across two sub-objects. The keyboard and mouse APIs are the low-level layer beneath the element methods — reach for them when you need precise control over input timing, key sequences, or coordinates.

page.keyboard.down() and page.keyboard.up() are the modifier-key pair — hold a key across multiple other key events. The example above selects two characters to the right using shift+arrow, which no single press() call can express.

The mouse API operates on raw page coordinates. The sequence move → down → move → up is how you implement a custom drag gesture on a target that el.scroll() can't reach — a canvas slider, a map pane, a custom range control built without semantic HTML.

Waiting

Four methods. page.wait(ms) is the unconditional sleep — fixed milliseconds, always blocking. Use it sparingly. The other three are conditional: they resolve the moment their condition is met, which makes tests faster and less brittle than a fixed sleep.

page.waitUntil(expression) evaluates a JavaScript string in the page context on a polling interval and resolves when the expression returns truthy. It's the general-purpose wait — use it for application-specific conditions that no CSS selector can express: a flag on window, a data attribute set by app logic, a third-party widget's internal state.

page.waitUntil.url() accepts a string, a glob, or a regex. Globs are the pragmatic choice after redirects where the exact final URL varies by environment — a pattern like '**/dashboard**' matches regardless of the host.

Page utilities and network capture

Seventeen methods split across two categories. The Page methods modify or observe the page as a whole. The Capture methods intercept events — dialogs, navigations, network requests — that would otherwise be hard to test because they happen asynchronously in response to an action.

The page.capture.* methods handle the hardest category of browser interaction to test: things that happen in response to another action. The key rule is that the action triggering the event must be fire-and-forget inside the capture callback — never awaited.

page.route() intercepts all requests matching a URL pattern and routes them through a handler. Use it to mock API responses in tests — return a fixed JSON payload without hitting the real server. page.unroute() removes the handler when the test is done.

page.setHeaders() adds custom HTTP headers to every subsequent request from the page — the clean way to inject an auth token for tests that can't use cookie-based sessions.

Browser context and the virtual clock

The three browser.* methods manage multi-page and multi-context sessions. browser.newPage() opens a fresh tab in the current context — it shares cookies and storage with existing pages. browser.newContext() creates an isolated context with its own cookies, storage, and permissions — the right choice when you need two sessions running in parallel without interference, such as testing an admin view alongside a user view.

The Clock API replaces the browser's real-time functions with a controllable fake. Call clock.install() once at the start of the test — after that, Date.now(), setTimeout, setInterval, and all related browser APIs respond to the clock you control.

clock.setTimezone() accepts any IANA timezone name and overrides what the page sees as its local timezone — making locale-sensitive UI logic fully testable without changing the system's actual timezone or running a VM. clock.runFor(ms) advances the clock by a duration and fires all timers that fall within that window, then pauses — the right tool for testing that a setInterval callback fires the expected number of times.