Skip to content

JavaScript API Reference

All 186 entries of the JavaScript client API, grouped by object. Each entry shows the signature from the client’s own source, then the matching CLI command and MCP tool where one exists.

Entries marked (nightly) are not in the latest release (26.11.16); (changed in nightly) means the documented signature differs from that release. Signatures come from the latest nightly build. See What’s in Nightly. The same data for every surface is in the API matrix and in /api.json.

Examples assume bro is a started browser and vibe is its page, as in the quickstart.

browser.start(opts?)

Launch browser and connect

start(urlOrOptions?: string | StartOptions, options?: StartOptions): Promise<Browser>;

Example: const bro = await browser.start({ headless: true })

CLI vibium start · MCP browser_start

browser.page()

Get the default page

page(): Promise<Page>;

Get the default page (first browsing context).

Example: const vibe = await bro.page()

browser.newPage()

Create a new page

newPage(): Promise<Page>;

Create a new page (tab) in the default context.

Example: const second = await bro.newPage()

CLI vibium page new · MCP browser_new_page

browser.newContext()

Create a new browser context

newContext(): Promise<BrowserContext>;

Create a new browser context (isolated, incognito-like).

browser.pages()

List all pages

pages(): Promise<Page[]>;

Get all open pages.

CLI vibium pages · MCP browser_list_pages

browser.stop()

Stop the browser

stop(): Promise<void>;

Stop the browser and clean up.

Example: await bro.stop()

CLI vibium stop · MCP browser_stop

browser.onPage(cb)

Listen for new page events

onPage(callback: (page: Page) => void): void;

Register a callback for when a new page is created (e.g. new tab).

browser.onPopup(cb)

Listen for popup events

onPopup(callback: (page: Page) => void): void;

Register a callback for when a popup is opened (window.open or target=_blank).

browser.removeAllListeners(ev?)

Remove all event listeners

removeAllListeners(event?: 'page' | 'popup'): void;

Remove all listeners for a given event, or all events if no event specified. Supported events: ‘page’, ‘popup’.

page.go(url)

Navigate to a URL

go(url: string): Promise<void>;

Example: await vibe.go('https://example.com')

CLI vibium go <url> · MCP browser_navigate

page.back()

Go back

back(): Promise<void>;

Navigate back in history.

Example: await vibe.back()

CLI vibium back · MCP browser_back

page.forward()

Go forward

forward(): Promise<void>;

Navigate forward in history.

CLI vibium forward · MCP browser_forward

page.reload()

Reload page

reload(): Promise<void>;

Reload the page.

Example: await vibe.reload()

CLI vibium reload · MCP browser_reload

page.url()

Get current URL

url(): Promise<string>;

Get the current page URL.

Example: const url = await vibe.url()

CLI vibium url · MCP browser_get_url

page.title()

Get page title

title(): Promise<string>;

Get the current page title.

Example: const title = await vibe.title()

CLI vibium title · MCP browser_get_title

page.content()

Get page HTML

content(): Promise<string>;

Get the full HTML content of the page.

Example: const html = await vibe.content()

page.find(locator, opts?)

Find a single element by description (a bare string), css, tag, semantic locator, or reference image; strategy auto, cv, vlm, or tree

find(selector: string | SelectorOptions, options?: FindOptions): FluentElement;

Find an element. A string is a natural-language description; an options object gives an exact locator (css, tag, role, text, …) or a reference image. Waits for the element to exist.

Example: const button = await vibe.find({ role: 'button', text: 'Submit' })

CLI vibium find <description> · MCP browser_find

page.findAll(locator, opts?)

Find all matching elements, same locator forms

findAll(selector: string | SelectorOptions, options?: FindOptions): Promise<Element[]>;

Find all elements matching a description, image, css, or semantic options. Waits up to the timeout for at least one match, then returns an empty array if there is none. A timeout of 0 checks once without waiting. Each element carries a snapshot of its tag, text, and box taken at findAll time, readable via el.info with no further round trips: els.map(el => el.info.text). Live reads like el.text() re-resolve the element and fail if the page has changed since findAll.

Example: const links = await vibe.findAll({ role: 'link' })

CLI vibium find --all <description> · MCP browser_find_all

page.screenshot(opts?)

Take a page screenshot

screenshot(options?: ScreenshotOptions): Promise<Buffer>;

Take a screenshot of the page. Returns a PNG buffer.

Example: fs.writeFileSync('page.png', await vibe.screenshot())

CLI vibium screenshot · MCP browser_screenshot

page.pdf(opts?)

Generate PDF

pdf(options?: PdfOptions): Promise<Buffer>;

Print the page to PDF. Returns a PDF buffer. Only works in headless mode.

CLI vibium pdf · MCP browser_pdf

page.evaluate(expr)

Evaluate JavaScript

evaluate<T = unknown>(expression: string | (() => T | Promise<T>)): Promise<T>;

Evaluate a JS expression string or argless function and return the deserialized value.

Example: const count = await vibe.evaluate('document.links.length')

CLI vibium eval <expr> · MCP browser_evaluate

page.addScript(src)

Add a script tag

addScript(source: string): Promise<void>;

Inject a script into the page. Pass a URL or inline JavaScript.

page.addStyle(src)

Add a style tag

addStyle(source: string): Promise<void>;

Inject a stylesheet into the page. Pass a URL or inline CSS.

page.expose(name, fn)

Expose a function to the page

expose(name: string, fn: string | ((...args: unknown[]) => unknown)): Promise<void>;

Expose a function on window. Pass a function to expose a host callback: the page calls window[name](…args), this function runs here, and its return value resolves the page’s promise. Arguments and results cross as JSON. Pass a string to inject it as JS source instead, defining window[name] inside the page. Either form survives navigation, and re-exposing a name replaces it.

page.wait(ms)

Wait for a duration

wait(ms: number): Promise<void>;

Wait for a fixed amount of time (milliseconds). Discouraged but useful for debugging.

CLI vibium sleep <ms> · MCP browser_sleep

page.waitForFunction(fn, opts?)

Wait for JS function to return truthy

waitForFunction(fn: string, options?: {
timeout?: number;
}): Promise<unknown>;

Wait until a function returns a truthy value.

Example: await vibe.waitForFunction('document.readyState === "complete"')

CLI vibium wait fn <expr> · MCP browser_wait_for_fn

page.waitForURL(url, opts?)

Wait for URL to match

waitForURL(pattern: string, options?: {
timeout?: number;
}): Promise<void>;

Wait until the page URL matches a pattern.

Example: await vibe.waitForURL('**/next')

CLI vibium wait url <pat> · MCP browser_wait_for_url

page.waitForLoad(opts?)

Wait for page load

waitForLoad(state?: string, options?: {
timeout?: number;
}): Promise<void>;

Wait until the page reaches a load state.

Example: await vibe.waitForLoad()

CLI vibium wait load · MCP browser_wait_for_load

page.scroll(dir?, amt?, sel?)

Scroll the page

scroll(direction?: string, amount?: number, selector?: string): Promise<void>;

Scroll the page in a direction.

CLI vibium scroll <dir> <amt> · MCP browser_scroll

page.setViewport(size)

Set viewport size

setViewport(size: {
width: number;
height: number;
}): Promise<void>;

Set the viewport size.

Example: await vibe.setViewport({ width: 375, height: 812 })

CLI vibium viewport <w> <h> · MCP browser_set_viewport

page.viewport()

Get viewport size

viewport(): Promise<{
width: number;
height: number;
}>;

Get the current viewport size.

CLI vibium viewport · MCP browser_get_viewport

page.emulateMedia(opts)

Override CSS media features

emulateMedia(opts: {
media?: 'screen' | 'print' | null;
colorScheme?: 'light' | 'dark' | 'no-preference' | null;
reducedMotion?: 'reduce' | 'no-preference' | null;
forcedColors?: 'active' | 'none' | null;
contrast?: 'more' | 'no-preference' | null;
}): Promise<void>;

Override CSS media features (colorScheme, reducedMotion, forcedColors, contrast, media type).

CLI vibium media <scheme> · MCP browser_emulate_media

page.setContent(html)

Set page HTML

setContent(html: string): Promise<void>;

Replace the page HTML content.

Example: await vibe.setContent('<h1>Hello</h1>')

CLI vibium content <html> · MCP browser_set_content

page.setGeolocation(coords)

Override geolocation

setGeolocation(coords: {
latitude: number;
longitude: number;
accuracy?: number;
}): Promise<void>;

Override the browser’s geolocation.

CLI vibium geolocation <lat> <lon> · MCP browser_set_geolocation

page.setWindow(opts)

Set window size/position

setWindow(options: {
width?: number;
height?: number;
x?: number;
y?: number;
state?: 'normal' | 'maximized' | 'minimized' | 'fullscreen';
}): Promise<void>;

Set the OS browser window size, position, or state.

CLI vibium window <opts> · MCP browser_set_window

page.window()

Get window info

window(): Promise<{
state: string;
width: number;
height: number;
x: number;
y: number;
}>;

Get the current OS browser window state and dimensions.

CLI vibium window · MCP browser_get_window

page.a11yTree(opts?)

Get accessibility tree

a11yTree(options?: {
everything?: boolean;
root?: string;
}): Promise<A11yNode>;

Get the accessibility tree for the page.

Example: const tree = await vibe.a11yTree()

CLI vibium a11y-tree · MCP browser_a11y_tree

page.frames()

List all frames

frames(): Promise<Page[]>;

Get all child frames of this page (recursive, flattened).

CLI vibium frames · MCP browser_frames

page.frame(nameOrUrl)

Get a frame by name/URL

frame(nameOrUrl: string): Promise<Page | null>;

Find a frame by name attribute or URL substring. Returns null if not found.

CLI vibium frame <ref> · MCP browser_frame

page.mainFrame()

Get the main frame

mainFrame(): Page;

Returns this page — the page IS its own main frame.

page.bringToFront()

Bring page to front

bringToFront(): Promise<void>;

Bring this page/tab to the foreground.

CLI vibium page switch <idx> · MCP browser_switch_page

page.close()

Close the page

close(): Promise<void>;

Close this page/tab.

CLI vibium page close · MCP browser_close_page

page.route(pattern, handler)

Register a route handler

route(pattern: string, handler: (route: Route) => void): Promise<void>;

Intercept network requests matching a URL pattern. The handler receives a Route object that can fulfill, continue, or abort the request.

page.unroute(pattern)

Remove a route handler

unroute(pattern: string): Promise<void>;

Remove a previously registered route. If no handler given, removes all routes for the pattern.

page.setHeaders(headers)

Set extra HTTP headers

setHeaders(headers: Record<string, string>): Promise<void>;

Set extra HTTP headers for all requests in this page.

page.onRequest(fn)

Listen for requests

onRequest(fn: (request: Request) => void): void;

Register a callback for every outgoing request.

Example: vibe.onRequest((req) => console.log(req.method(), req.url()))

page.onResponse(fn)

Listen for responses

onResponse(fn: (response: Response) => void): void;

Register a callback for every completed response.

Example: vibe.onResponse((resp) => console.log(resp.status(), resp.url()))

page.onDialog(fn)

Listen for dialogs

onDialog(handler: (dialog: Dialog) => void): void;

Register a handler for browser dialogs (alert, confirm, prompt). If no handler is registered, dialogs are automatically dismissed.

page.onConsole(fn)

Listen for console messages

onConsole(handler: ((message: ConsoleMessage) => void) | 'collect'): void;

Register a handler for console messages, or pass ‘collect’ to buffer them for consoleMessages().

Example: vibe.onConsole((msg) => console.log(msg.type(), msg.text()))

page.onError(fn)

Listen for page errors

onError(handler: ((error: Error) => void) | 'collect'): void;

Register a handler for uncaught page errors, or pass ‘collect’ to buffer them for errors().

page.onDownload(fn)

Listen for downloads

onDownload(handler: (download: Download) => void): void;

Register a handler for file downloads.

page.onWebSocket(fn)

Subscribe to WebSocket events

onWebSocket(fn: (ws: WebSocketInfo) => void): void;

Listen for WebSocket connections opened by the page. Monitoring is installed in the engine before the next command on this connection is sent, so a socket opened by the very next call cannot be missed (#351).

page.removeAllListeners(ev?)

Remove all event listeners

removeAllListeners(event?: 'request' | 'response' | 'dialog' | 'console' | 'error' | 'download' | 'navigation' | 'websocket'): void;

Remove all listeners for a given event, or all events if no event specified. Supported events: ‘request’, ‘response’, ‘dialog’, ‘console’, ‘error’, ‘download’, ‘websocket’.

page.capture.response(pat, fn?)

Capture response (before action)

response(pattern: string, fn?: () => Promise<void>, options?: {
timeout?: number;
}): Promise<Response>;

Capture a response matching a URL pattern. Optionally pass fn to trigger the action.

Example: const resp = await vibe.capture.response('**/api/users', () => vibe.find({ role: 'button', text: 'Users' }).click())

page.capture.request(pat, fn?)

Capture request (before action)

request(pattern: string, fn?: () => Promise<void>, options?: {
timeout?: number;
}): Promise<Request>;

Capture a request matching a URL pattern. Optionally pass fn to trigger the action.

page.capture.navigation(fn?)

Capture navigation (before action)

navigation(fn?: () => Promise<void>, options?: {
timeout?: number;
}): Promise<string>;

Capture a navigation event. Optionally pass fn to trigger the action. Resolves with URL.

page.capture.event(name, fn?)

Capture event (before action)

event(name: string, fn?: () => Promise<void>, options?: {
timeout?: number;
}): Promise<unknown>;

Capture a named event. Optionally pass fn to trigger the action.

page.capture.download(fn?)

Capture download (before action)

download(fn?: () => Promise<void>, options?: {
timeout?: number;
}): Promise<Download>;

Capture a download. Optionally pass fn to trigger the action.

Example: const download = await vibe.capture.download(() => vibe.find({ role: 'link', text: 'Download' }).click())

page.capture.dialog(fn?)

Capture dialog (before action)

dialog(fn?: () => Promise<void>, options?: {
timeout?: number;
}): Promise<Dialog>;

Capture a dialog. Optionally pass fn to trigger the action.

page.consoleMessages()

Get buffered console messages

consoleMessages(): {
type: string;
text: string;
}[];

Return collected console messages and clear the buffer. Returns [] if not collecting.

page.errors()

Get buffered page errors

errors(): {
message: string;
}[];

Return collected errors and clear the buffer. Returns [] if not collecting.

page.context

Owning browser context

get context(): BrowserContext;

The parent BrowserContext that owns this page.

page.id

Browsing context id

get id(): string;

The browsing context ID for this page.

page.capture

One-shot capture namespace

readonly capture: {
/** Capture a response matching a URL pattern. Optionally pass fn to trigger the action. */
response(pattern: string, fn?: () => Promise<void>, options?: {
timeout?: number;
}): Promise<Response>;
/** Capture a request matching a URL pattern. Optionally pass fn to trigger the action. */
request(pattern: string, fn?: () => Promise<void>, options?: {
timeout?: number;
}): Promise<Request>;
/** Capture a navigation event. Optionally pass fn to trigger the action. Resolves with URL. */
navigation(fn?: () => Promise<void>, options?: {
timeout?: number;
}): Promise<string>;
/** Capture a download. Optionally pass fn to trigger the action. */
download(fn?: () => Promise<void>, options?: {
timeout?: number;
}): Promise<Download>;
/** Capture a dialog. Optionally pass fn to trigger the action. */
dialog(fn?: () => Promise<void>, options?: {
timeout?: number;
}): Promise<Dialog>;
/** Capture a named event. Optionally pass fn to trigger the action. */
event(name: string, fn?: () => Promise<void>, options?: {
timeout?: number;
}): Promise<unknown>;
};

Capture namespace — set up a listener before performing an action.

page.keyboard

Keyboard input for the page

readonly keyboard: Keyboard;

Page-level keyboard input.

page.mouse

Mouse input for the page

readonly mouse: Mouse;

Page-level mouse input.

page.touch

Touch input for the page

readonly touch: Touch;

Page-level touch input.

page.clock

Clock control for the page

readonly clock: Clock;

Page-level clock control for faking timers and Date.

page.waitUntil(fn, opts?)

Deprecated alias for the wait helpers

readonly waitUntil: ((fn: string, options?: {
timeout?: number;
}) => Promise<unknown>) & {
/** @deprecated Use waitForURL(). */
url(pattern: string, options?: {
timeout?: number;
}): Promise<void>;
/** @deprecated Use waitForLoad(). */
loaded(state?: string, options?: {
timeout?: number;
}): Promise<void>;
};

Wait until a condition is met. Callable with a function, or use .url() / .loaded() sub-methods. @deprecated Use waitForFunction(), waitForURL(), or waitForLoad().

mode of onConsole(‘collect’)

Enable console collect mode

mode of onError(‘collect’)

Enable error collect mode

page.routeWebSocket(pattern, fn)

Intercept WebSockets (unsupported: throws)

routeWebSocket(_pattern: string, _handler: unknown): never;

Intercept WebSocket connections. Not supported by BiDi.

el.click(opts?)

Click an element

click(options?: ActionOptions): Promise<void>;

Click the element. Waits for element to be visible, stable, receive events, and enabled.

Example: await vibe.find({ role: 'button', text: 'Submit' }).click()

CLI vibium click <sel> · MCP browser_click

el.dblclick(opts?)

Double-click an element

dblclick(options?: ActionOptions): Promise<void>;

Double-click the element.

CLI vibium dblclick <sel> · MCP browser_dblclick

el.fill(value, opts?)

Fill an input field

fill(value: string, options?: ActionOptions): Promise<void>;

Fill the element with text (clears existing content first). For inputs and textareas.

Example: await vibe.find({ label: 'Email' }).fill('user@example.com')

CLI vibium fill <sel> <val> · MCP browser_fill

el.type(text, opts?)

Type text character by character

type(text: string, options?: ActionOptions): Promise<void>;

Type text into the element (appends to existing content). Waits for element to be visible, stable, receive events, enabled, and editable.

Example: await vibe.find({ label: 'Email' }).type('user@example.com')

CLI vibium type <text> · MCP browser_type

el.press(key, opts?)

Press a key on focused element

press(key: string, options?: ActionOptions): Promise<void>;

Press a key while the element is focused. Supports key names (“Enter”, “Tab”) and combos (“Control+a”).

Example: await vibe.find({ label: 'Email' }).press('Enter')

CLI vibium press <key> · MCP browser_press

el.clear(opts?)

Clear an input field

clear(options?: ActionOptions): Promise<void>;

Clear the element’s content (select all + delete).

el.set(value?, opts?)

Check a checkbox

set(value?: boolean, options?: ActionOptions): Promise<void>;

Check a checkbox (no-op if already checked).

Example: await vibe.find({ css: 'input[type="checkbox"]' }).set()

CLI vibium set <sel> · MCP browser_set

el.unset(opts?)

Uncheck a checkbox

unset(options?: ActionOptions): Promise<void>;

Uncheck a checkbox (no-op if already unchecked).

CLI vibium unset <sel> · MCP browser_unset

el.selectOption(val, opts?)

Select a dropdown option

selectOption(value: string, options?: ActionOptions): Promise<void>;

Select an option in a <select> element by value.

Example: await vibe.find({ label: 'Country' }).selectOption('de')

CLI vibium select <sel> <val> · MCP browser_select

el.hover(opts?)

Hover over an element

hover(options?: ActionOptions): Promise<void>;

Hover over the element (move mouse to center, no click).

Example: await vibe.find({ role: 'button', text: 'Menu' }).hover()

CLI vibium hover <sel> · MCP browser_hover

el.focus(opts?)

Focus an element

focus(options?: ActionOptions): Promise<void>;

Focus the element.

CLI vibium focus <sel> · MCP browser_focus

el.dragTo(target, opts?)

Drag an element to a target

dragTo(target: Element, options?: ActionOptions): Promise<void>;

Drag this element to a target element.

CLI vibium drag <sel> <x> <y> · MCP browser_drag

el.tap(opts?)

Tap an element (touch)

tap(options?: ActionOptions): Promise<void>;

Tap the element (touch action).

el.scrollIntoView(opts?)

Scroll element into view

scrollIntoView(options?: ActionOptions): Promise<void>;

Scroll the element into view.

CLI vibium scroll into-view <sel> · MCP browser_scroll_into_view

el.dispatchEvent(type, init?)

Dispatch a DOM event

dispatchEvent(eventType: string, eventInit?: Record<string, unknown>, options?: ActionOptions): Promise<void>;

Dispatch a DOM event on the element.

el.setFiles(files, opts?)

Set files on a file input

setFiles(files: string[], options?: ActionOptions): Promise<void>;

Set files on an <input type=“file”> element.

CLI vibium upload <sel> <paths> · MCP browser_upload

el.highlight()

Highlight an element

highlight(options?: ActionOptions): Promise<void>;

Highlight the element with a brief outline, for visual debugging.

CLI vibium highlight <sel> · MCP browser_highlight

el.text()

Get element text content

text(): Promise<string>;

Get the element’s textContent (trimmed).

Example: const heading = await vibe.find({ css: 'h1' }).text()

CLI vibium text <sel> · MCP browser_get_text

el.innerText()

Get element inner text

innerText(): Promise<string>;

Get the element’s innerText (rendered text only).

CLI vibium text <sel> · MCP browser_get_text

el.html()

Get element outer HTML

html(): Promise<string>;

Get the element’s innerHTML.

CLI vibium html <sel> · MCP browser_get_html

el.value()

Get input element value

value(): Promise<string>;

Get the element’s value (for inputs, textareas, selects).

Example: const email = await vibe.find({ label: 'Email' }).value()

CLI vibium value <sel> · MCP browser_get_value

el.attr(name)

Get element attribute

attr(name: string): Promise<string | null>;

Get an attribute value. Short name for getAttribute.

Example: const href = await vibe.find({ role: 'link', text: 'Next' }).attr('href')

CLI vibium attr <sel> <name> · MCP browser_get_attribute

el.bounds()

Get element bounding box

bounds(): Promise<BoundingBox>;

Get the element’s bounding box. Short name for boundingBox.

el.boundingBox()

Bounding box (Playwright-compat alias for bounds)

boundingBox(): Promise<BoundingBox>;

Get the element’s bounding box. Alias for bounds().

el.getAttribute(name)

Get attribute (alias for attr)

getAttribute(name: string): Promise<string | null>;

Get an attribute value. Alias for attr().

el.info

Find-time snapshot of tag, text, and box

readonly info: ElementInfo;

el.isVisible()

Check if element is visible

isVisible(): Promise<boolean>;

Check if the element is visible (has dimensions, not display:none/visibility:hidden/opacity:0).

Example: const visible = await vibe.find({ role: 'button', text: 'Submit' }).isVisible()

CLI vibium is visible <sel> · MCP browser_is_visible

el.isHidden()

Check if element is hidden

isHidden(): Promise<boolean>;

Check if the element is hidden (inverse of isVisible).

el.isEnabled()

Check if element is enabled

isEnabled(): Promise<boolean>;

Check if the element is enabled (not disabled).

CLI vibium is enabled <sel> · MCP browser_is_enabled

el.isSet()

Check if element is checked

isSet(): Promise<boolean>;

Check if the element is checked (for checkboxes/radios).

CLI vibium is set <sel> · MCP browser_is_set

el.isEditable()

Check if element is editable

isEditable(): Promise<boolean>;

Check if the element is editable (not disabled and not readonly).

el.role()

Get element ARIA role

role(): Promise<string>;

Get the element’s computed ARIA role.

el.label()

Get element accessible label

label(): Promise<string>;

Get the element’s accessible name (label).

el.screenshot()

Screenshot an element

screenshot(): Promise<Buffer>;

Take a screenshot of just this element. Returns a PNG buffer.

el.waitUntil(state?, opts?)

Wait for element state

waitUntil(state?: string, options?: {
timeout?: number;
}): Promise<void>;

Wait until the element reaches a state: “visible”, “hidden”, “attached”, or “detached”.

CLI vibium wait <sel> --state <st> · MCP browser_wait

el.find(sel, opts?)

Find a child element (scoped)

find(selector: string | SelectorOptions, options?: {
timeout?: number;
}): FluentElement;

Find a child element by CSS selector or semantic options. Scoped to this element.

Example: const home = await (await vibe.find({ css: 'nav' })).find({ role: 'link', text: 'Home' })

el.findAll(sel, opts?)

Find all child elements (scoped)

findAll(selector: string | SelectorOptions, options?: {
timeout?: number;
}): Promise<Element[]>;

Find all child elements by description, image, css, or semantic options. Scoped to this element.

context.newPage()

Create a page in a context

newPage(): Promise<Page>;

Create a new page (tab) in this context.

context.close()

Close the context

close(): Promise<void>;

Close this context and all its pages.

context.cookies(urls?)

Get cookies

cookies(urls?: string[]): Promise<Cookie[]>;

Get cookies for this context. Optionally filter by URLs.

CLI vibium cookies · MCP browser_get_cookies

context.setCookies(cookies)

Set cookies

setCookies(cookies: SetCookieParam[]): Promise<void>;

Set cookies in this context.

CLI vibium cookies <n> <v> · MCP browser_set_cookie

context.clearCookies()

Clear cookies

clearCookies(): Promise<void>;

Clear all cookies in this context.

CLI vibium cookies clear · MCP browser_delete_cookies

context.storage()

Get storage state

storage(): Promise<StorageState>;

Get the storage state (cookies + localStorage + sessionStorage).

CLI vibium storage · MCP browser_storage_state

context.setStorage(state)

Set storage state

setStorage(state: StorageState): Promise<void>;

Set the storage state (cookies + localStorage + sessionStorage).

MCP browser_restore_storage

context.clearStorage()

Clear all storage

clearStorage(): Promise<void>;

Clear all storage (cookies + localStorage + sessionStorage).

context.addInitScript(script)

Add an init script

addInitScript(script: string): Promise<string>;

Add an init script that runs before page scripts in this context.

context.id

User context id

get id(): string;

The user context ID for this browser context.

context.recording

Recording controls for the context

readonly recording: Recording;

keyboard.press(key)

Press a key

press(key: string): Promise<void>;

Press and release a key. Supports combos like “Control+a”.

Example: await vibe.keyboard.press('Enter')

CLI vibium keys <keys> · MCP browser_keys

keyboard.down(key)

Key down

down(key: string): Promise<void>;

Press a key down (without releasing).

keyboard.up(key)

Key up

up(key: string): Promise<void>;

Release a key.

keyboard.type(text)

Type text

type(text: string): Promise<void>;

Type a string of text character by character.

mouse.click(x, y, opts?)

Click at coordinates

click(x: number, y: number): Promise<void>;

Click at (x, y) coordinates.

CLI vibium mouse click <x> <y> · MCP browser_mouse_click

mouse.move(x, y, opts?)

Move mouse

move(x: number, y: number): Promise<void>;

Move mouse to (x, y) coordinates.

CLI vibium mouse move <x> <y> · MCP browser_mouse_move

mouse.down(opts?)

Mouse button down

down(): Promise<void>;

Press mouse button down.

CLI vibium mouse down · MCP browser_mouse_down

mouse.up(opts?)

Mouse button up

up(): Promise<void>;

Release mouse button.

CLI vibium mouse up · MCP browser_mouse_up

mouse.wheel(dx, dy)

Scroll mouse wheel

wheel(deltaX: number, deltaY: number): Promise<void>;

Scroll the mouse wheel at the current pointer position.

touch.tap(x, y)

Tap at coordinates

tap(x: number, y: number): Promise<void>;

Tap at (x, y) coordinates.

CLI vibium tap <x> <y> · MCP browser_tap

touch.swipe(direction, opts?)

Swipe in a direction (up, down, left, right; from an edge or point; speed, hold) or between coordinates

  • swipe(direction: SwipeDirection, options?: SwipeOptions): Promise<void>;
  • swipe(x1: number, y1: number, x2: number, y2: number, durationMs?: number): Promise<void>;

Swipe in a direction, or from (x1, y1) to (x2, y2). The finger stays down for the move, so the gesture reads as a swipe/fling rather than two taps. swipe(‘up’) // from the center, half the viewport swipe(‘up’, { from: ‘bottom’, speed: ‘fast’ }) // phone home gesture via Roadie swipe(40, 100, 240, 100, 200) // coordinates, 200ms

CLI vibium swipe <direction> · MCP browser_swipe

touch.longPress(x, y, durationMs?)

Long-press at coordinates

longPress(x: number, y: number, durationMs?: number): Promise<void>;

Press and hold at (x, y) for durationMs before releasing (default 500).

CLI vibium long-press <x> <y> · MCP browser_long_press

clock.install(opts?)

Install fake timers

install(options?: ClockInstallOptions): Promise<void>;

Install fake clock, overriding Date, setTimeout, setInterval, etc.

MCP page_clock_install

clock.fastForward(ticks)

Fast-forward time

fastForward(ticks: number): Promise<void>;

Jump forward by ticks ms, fire each due timer at most once.

MCP page_clock_fast_forward

clock.runFor(ticks)

Run timers for a duration

runFor(ticks: number): Promise<void>;

Advance ticks ms, firing all callbacks systematically (including interval reschedules).

MCP page_clock_run_for

clock.pauseAt(time)

Pause clock at a time

pauseAt(time: number | string | Date): Promise<void>;

Jump to a specific time and pause — no timers fire until resumed/advanced.

MCP page_clock_pause_at

clock.resume()

Resume clock

resume(): Promise<void>;

Resume real-time progression from current fake time.

MCP page_clock_resume

clock.setFixedTime(time)

Set fixed fake time

setFixedTime(time: number | string | Date): Promise<void>;

Freeze Date.now() at a value permanently. Timers still run.

MCP page_clock_set_fixed_time

clock.setSystemTime(time)

Set system time

setSystemTime(time: number | string | Date): Promise<void>;

Set Date.now() without triggering timers.

MCP page_clock_set_system_time

clock.setTimezone(tz)

Set timezone

setTimezone(timezone: string): Promise<void>;

Override the browser timezone. Pass an IANA timezone ID, or empty string to reset to system default.

MCP page_clock_set_timezone

recording.start(opts?)

Start recording

start(options?: RecordingStartOptions): Promise<void>;

CLI vibium record start · MCP browser_record_start

recording.stop(opts?)

Stop recording, return trace

stop(options?: RecordingStopOptions): Promise<RecordingResult>;

Stop recording and deliver the zip to the declared path. The result carries where it landed and what it holds; the zip bytes are included only for bytes-only recordings (start path: null).

CLI vibium record stop · MCP browser_record_stop

recording.startChunk(opts?)

Start a recording chunk

startChunk(options?: {
name?: string;
title?: string;
}): Promise<void>;

Start a new recording chunk (resets event buffer, keeps resources).

CLI vibium record chunk start · MCP browser_record_start_chunk

recording.stopChunk(opts?)

Stop a recording chunk

stopChunk(options?: RecordingStopOptions): Promise<RecordingResult>;

Stop the current chunk. The result carries the path it was written to, or the chunk’s bytes when no path was given.

CLI vibium record chunk stop · MCP browser_record_stop_chunk

recording.startGroup(name, opts?)

Start a logical group

startGroup(name: string, options?: {
location?: {
file: string;
line?: number;
column?: number;
};
}): Promise<void>;

Start a named group of actions in the recording.

CLI vibium record group start <name> · MCP browser_record_start_group

recording.stopGroup()

Stop a logical group

stopGroup(): Promise<void>;

End the current group.

CLI vibium record group stop · MCP browser_record_stop_group

route.request (property)

Access intercepted request

readonly request: Request;

route.fulfill(resp?)

Fulfill an intercepted request

fulfill(response?: {
status?: number;
headers?: Record<string, string>;
contentType?: string;
body?: string;
}): Promise<void>;

Fulfill the request with a custom response (mock response).

route.continue(overrides?)

Continue an intercepted request

continue(overrides?: {
url?: string;
method?: string;
headers?: Record<string, string>;
postData?: string;
}): Promise<void>;

Continue the request with optional overrides.

route.abort()

Abort an intercepted request

abort(): Promise<void>;

Abort the request.

dialog.message()

Get dialog message

message(): string;

The dialog message text.

dialog.type()

Get dialog type

type(): string;

The dialog type: ‘alert’, ‘confirm’, ‘prompt’, or ‘beforeunload’.

dialog.defaultValue()

Get dialog default value

defaultValue(): string;

The default value for prompt dialogs.

dialog.accept(promptText?)

Accept the dialog

accept(promptText?: string): Promise<void>;

Accept the dialog. For prompt dialogs, optionally provide text.

CLI vibium dialog accept · MCP browser_dialog_accept

dialog.dismiss()

Dismiss the dialog

dismiss(): Promise<void>;

Dismiss the dialog (cancel/close).

CLI vibium dialog dismiss · MCP browser_dialog_dismiss

download.saveAs(path)

Save a download to path

saveAs(path: string): Promise<void>;

Wait for the download to complete, then save to the specified path.

download.url()

Get download URL

url(): string;

The URL of the download.

download.suggestedFilename()

Get download filename

suggestedFilename(): string;

The filename suggested by the server (from Content-Disposition).

download.path()

Get download path

path(): Promise<string | null>;

Wait for the download to complete and return the temp file path, or null if failed.

request.url()

Get request URL

url(): string;

The request URL.

request.method()

Get HTTP method

method(): string;

The HTTP method (GET, POST, etc.).

request.headers()

Get request headers

headers(): Record<string, string>;

Request headers as a simple key-value object.

request.requestId()

Get BiDi request ID

requestId(): string;

The request ID (BiDi network request identifier).

request.postData()

Get request body

postData(): Promise<string | null>;

Request body / post data. Uses BiDi network.getData when a data collector is active.

response.url()

Get response URL

url(): string;

The response URL.

response.status()

Get HTTP status

status(): number;

The HTTP status code.

response.headers()

Get response headers

headers(): Record<string, string>;

Response headers as a simple key-value object.

response.requestId()

Get associated request ID

requestId(): string;

The request ID associated with this response.

response.body()

Get response body

body(): Promise<string | null>;

Response body as a string. Requires a data collector (set up by onResponse/expect.response).

response.json()

Parse response body as JSON

json(): Promise<unknown>;

Response body parsed as JSON. Requires a data collector (set up by onResponse/expect.response).

message.type()

Get console message type

type(): string;

The console method: ‘log’, ‘warn’, ‘error’, ‘debug’, ‘info’, etc.

message.text()

Get formatted message text

text(): string;

The message text.

message.args()

Get console arguments

args(): unknown[];

The serialized arguments passed to the console call.

message.location()

Get source location

location(): {
url: string;
lineNumber: number;
columnNumber: number;
} | null;

The source location of the console call, if available.

socket.url()

Get WebSocket URL

url(): string;

socket.onMessage(fn)

Listen for messages

onMessage(fn: MessageHandler): void;

socket.onClose(fn)

Listen for close

onClose(fn: CloseHandler): void;

socket.isClosed()

Check whether socket is closed

isClosed(): boolean;

browser.check(claim, opts?)

Independently verify the active session or a saved archive

check(claim: string, options?: CheckOptions): Promise<CheckResult>;

Independently verify this session, or inspect a saved archive.

CLI vibium check <claim> · MCP vibium_check

page.check(claim, opts?)

Independently verify a pinned page or a saved archive

check(claim: string, options?: CheckOptions): Promise<CheckResult>;

Verify this exact page, or inspect a read-only archive.

browser.run(goal, opts?)

Accomplish a goal in the active browser session

run(goal: string, options?: RunOptions): Promise<RunResult>;

Accomplish a live browser goal; provider settings are read in the runtime.

CLI vibium run <goal> · MCP vibium_run

page.run(goal, opts?)

Accomplish a goal on a pinned page

run(goal: string, options?: RunOptions): Promise<RunResult>;

Accomplish a live browser goal; provider settings are read in the runtime.

browser.say(text, opts?)

Speak text into the session, this machine’s speakers, or a WAV file

say(text: string, options?: SayOptions): Promise<SayResult>;

Speak text into the current page’s microphone, or into the device.

CLI vibium say <text> · MCP vibium_say

page.say(text, opts?)

Speak text into a pinned page

say(text: string, options?: SayOptions): Promise<SayResult>;

Speak text into this page’s microphone, or into the device.

browser.listen(opts?)

Hear the session, this machine’s microphone, or a WAV file, and return a transcript

listen(options?: ListenOptions): Promise<ListenResult>;

Hear what the current page, or the device, plays, and return its words.

CLI vibium listen · MCP vibium_listen

page.listen(opts?)

Hear a pinned page and return a transcript

listen(options?: ListenOptions): Promise<ListenResult>;

Hear what this page, or the device, plays, and return its words.

Option and result types named in the signatures above.

interface A11yNode {
role: string;
name?: string;
value?: string | number;
description?: string;
disabled?: boolean;
expanded?: boolean;
focused?: boolean;
checked?: boolean | 'mixed';
pressed?: boolean | 'mixed';
selected?: boolean;
required?: boolean;
readonly?: boolean;
level?: number;
valuemin?: number;
valuemax?: number;
children?: A11yNode[];
}
interface ActionOptions {
/** Timeout in milliseconds for actionability checks. Default: 30000 */
timeout?: number;
}
interface BoundingBox {
x: number;
y: number;
width: number;
height: number;
}
interface Browser {
(goal: string, options?: RunOptions): Promise<RunResult>;
}
interface CheckOptions extends ModelOptions {
/** Read-only archive on the runtime host. */
record?: string;
/** Site under test: opened first unless the current page already shares its
* origin; relative navigation paths resolve against it. Not the AI provider
* endpoint; that is aiBaseURL. */
baseURL?: string;
}
interface CheckResult {
status: 'passed' | 'failed' | 'inconclusive';
claim: string;
summary: string;
/** Machine-readable cause of an inconclusive verdict. */
reason?: 'action_limit' | 'insufficient_evidence' | 'safety_stop' | 'archive_missing_evidence';
evidence: {
type: 'observation';
summary: string;
}[];
}
interface ClockInstallOptions {
time?: number | string | Date;
timezone?: string;
}
type CloseHandler = (code?: number, reason?: string) => void;
interface Cookie {
name: string;
value: string;
domain: string;
path: string;
size: number;
httpOnly: boolean;
secure: boolean;
sameSite: string;
expiry?: number;
}
interface ElementInfo {
tag: string;
text: string;
box: BoundingBox;
/** The @eN ref find registered; the CLI and MCP address the same element by it. */
ref?: string;
role?: string;
/** Accessible name. */
name?: string;
/** What backs the match: dom, tree, image, or vlm. */
source?: string;
/** The DOM selector of a DOM-backed match. Absent for a visual region. */
selector?: string;
/** Diagnostics, when the find asked for details. */
details?: Record<string, unknown>;
}
interface FindOptions {
/** Timeout in milliseconds to wait for element. Default: 30000 */
timeout?: number;
}
type FindStrategy = 'auto' | 'cv' | 'vlm' | 'tree';
type FluentElement = Promise<Element> & {
click(options?: ActionOptions): Promise<void>;
interface ListenOptions extends SpeechOptions {
/** Trailing silence that ends the reply, in ms. 0 turns endpointing off. Default 1000. */
silence?: number;
/** How long to wait for speech to start, from the call, in ms. Default 10000. */
timeout?: number;
/** Maximum capture length from the call, in ms. Default 30000. */
duration?: number;
/** Return an empty transcript instead of throwing when nothing is heard. */
allowSilence?: boolean;
/** Also save the captured audio as a WAV file. */
path?: string;
/** false captures without a transcript. Default true. */
transcribe?: boolean;
}
interface ListenResult {
text: string;
/** False when the capture was not sent to a provider. */
transcribed: boolean;
/** False when no speech was detected (only with allowSilence). */
speech: boolean;
/** Times are ms from the start of the capture. */
segments: {
startMs: number;
endMs: number;
text: string;
}[];
/** Present when the provider returns word timings. */
words?: {
startMs: number;
endMs: number;
word: string;
}[];
/** When speech started and ended in the capture. */
onsetMs?: number;
speechEndMs?: number;
/** Speech onset minus the end of the preceding say. */
latencyMs?: number;
stoppedBy: 'silence' | 'duration' | 'eof' | 'timeout';
/** Length of the captured audio. */
durationMs: number;
target: string;
provider: string;
model: string;
path?: string;
/** Audio the target dropped on its way here, in ms. The transcript may miss words. */
lostMs?: number;
}
type MessageHandler = (data: string, info: {
direction: 'sent' | 'received';
interface ModelOptions {
provider?: 'openai' | 'xai' | 'anthropic' | 'google' | 'openai-compatible' | 'local';
model?: string;
/** The AI provider's API base URL (the model endpoint, not the site under
* test). Empty string resets the endpoint to the provider default. */
aiBaseURL?: string;
/** Empty string clears an inherited effort. */
reasoningEffort?: string;
}
interface OriginState {
origin: string;
localStorage: {
name: string;
value: string;
}[];
sessionStorage: {
name: string;
value: string;
}[];
}
interface Page {
(goal: string, options?: RunOptions): Promise<RunResult>;
}
interface PdfOptions {
/** Landscape orientation (default: portrait). */
landscape?: boolean;
/** Print scale, 0.1-2 (default: 1). */
scale?: number;
/** Print background graphics (default: false). */
background?: boolean;
/** Top margin in cm (default: 1). */
marginTop?: number;
/** Bottom margin in cm (default: 1). */
marginBottom?: number;
/** Left margin in cm (default: 1). */
marginLeft?: number;
/** Right margin in cm (default: 1). */
marginRight?: number;
/** Page width in cm (default: 21.59). */
pageWidth?: number;
/** Page height in cm (default: 27.94). */
pageHeight?: number;
/** Pages to print, e.g. [1, '3-5'] (default: all). */
pageRanges?: Array<number | string>;
/** Shrink content to fit the page width (default: true). */
shrinkToFit?: boolean;
}
interface RecordingResult {
/** Where the zip landed. Absent for bytes-only recordings. */
path?: string;
/** The zip itself. Present only for bytes-only recordings (start path: null). */
bytes?: Buffer;
steps?: number;
durationMs?: number;
videos?: RecordingVideoSummary[];
/** Why no video was recorded (video omitted on an engine without support). */
videoUnavailable?: string;
/** Where the zip was uploaded, when stop() asked for it. */
upload?: RecordingUpload;
}
interface RecordingStartOptions {
name?: string;
screenshots?: boolean;
snapshots?: boolean;
sources?: boolean;
title?: string;
bidi?: boolean;
/** Screenshot format: 'jpeg' (default, faster/smaller) or 'png' (lossless). */
format?: 'jpeg' | 'png';
/** JPEG quality 0.0-1.0 (default 0.5). Ignored for PNG. */
quality?: number;
/**
* Video track (Firefox 154+, local browsers). Omitted: record video if the
* engine supports it; the stop result reports videoUnavailable otherwise.
* `true` (or explicit dimensions): start fails if the engine can't deliver.
* `false`: off.
*/
video?: boolean | RecordingVideoOptions;
/**
* Where the recording zip lands at stop. Defaults to a timestamped
* record-YYYYMMDD-HHMMSS.zip in the working directory, so a rerun never
* clobbers the previous one. `null` selects bytes-only capture: no file
* is written and the recording is lost if the session closes before
* stop().
*/
path?: string | null;
}
interface RecordingStopOptions {
/** Overrides the path declared at start. */
path?: string;
/**
* Also upload the zip to a station's Record Store: `true` for the station
* the browser is connected through, or a station URL. Needs the API key
* the connection was made with; the zip still lands at its path either
* way, and the result's `upload` says where it went.
*/
upload?: boolean | string;
}
interface RecordingUpload {
/** Where the station serves the file. */
url: string;
sha256: string;
size: number;
/** The hold the recording was filed under, when the station knows one. */
hold?: string;
device?: string;
/** The id of the file event the station signed for it. */
event?: string;
}
interface RecordingVideoOptions {
/** Video width in pixels (defaults to the viewport). */
width?: number;
/** Video height in pixels (defaults to the viewport). */
height?: number;
/** Video frame rate (engine default if omitted). */
frameRate?: number;
/**
* On a remote browser connection, 'keep' records anyway and leaves the
* video on the remote host: the stop result and zip manifest carry its
* remotePath, and retrieval and cleanup are yours. Ignored on local
* connections.
*/
remote?: 'keep';
}
interface RecordingVideoSummary {
context: string;
durationMs: number;
width: number;
height: number;
/** Where a remote-keep video lives on the remote host. */
remotePath?: string;
/** Set when the video pipeline died; the zip delivered without or with a partial video. */
error?: string;
/** True when the video file also holds what the recording said and heard. */
audio?: boolean;
}
interface RunOptions extends ModelOptions {
/** Site under test: opened first unless the current page already shares its
* origin; relative navigation paths resolve against it. Not the AI provider
* endpoint; that is aiBaseURL. */
baseURL?: string;
}
interface RunResult {
status: 'completed' | 'not_completed';
goal: string;
summary: string;
/** Machine-readable cause of a not_completed result. */
reason?: 'action_limit' | 'missing_information' | 'safety_stop';
evidence: {
type: 'observation';
summary: string;
}[];
}
interface SayOptions extends SpeechOptions {
/** A WAV file to play as it is. Pass an empty text with it. */
file?: string;
voice?: string;
speed?: number;
/** false renders again and replaces the cached audio. Default true. */
cache?: boolean;
cacheDir?: string;
}
interface SayResult {
text: string;
target: string;
provider: string;
model: string;
voice: string;
durationMs: number;
cached: boolean;
/** SHA-256 of the audio that was played. */
sha256: string;
/** Present for file targets. */
path?: string;
/** Present when a file was played in place of text. */
file?: string;
}
interface ScreenshotOptions {
/** Capture full scrollable page instead of just the viewport. */
fullPage?: boolean;
/** Capture a specific region of the page. */
clip?: {
x: number;
y: number;
width: number;
height: number;
};
}
interface SelectorOptions {
/** Natural-language description, e.g. 'the Add to Cart button'. Stands alone. */
description?: string;
/** Reference image to locate on screen: a file path, a data: URL, or PNG/JPEG bytes. Stands alone. */
image?: string | Uint8Array;
/** CSS selector. Exact; never sent to a model. */
css?: string;
/** Same as css. */
selector?: string;
/** HTML tag name. */
tag?: string;
/** Accessible-name filter: the text, label, alt, or aria-label a person reads the element by. */
name?: string;
/**
* auto (default): page evidence first, a vision model only when needed
* and configured. cv: local image matching only. vlm: vision model only.
* tree: the page's DOM/accessibility tree only.
*/
strategy?: FindStrategy;
/** Include diagnostics in info.details. */
details?: boolean;
/** Per-call AI overrides, as for check and run. */
provider?: string;
model?: string;
aiBaseURL?: string;
reasoningEffort?: string;
role?: string;
text?: string;
label?: string;
placeholder?: string;
alt?: string;
title?: string;
testid?: string;
xpath?: string;
near?: string;
timeout?: number;
}
interface SetCookieParam {
name: string;
value: string;
domain?: string;
url?: string;
path?: string;
httpOnly?: boolean;
secure?: boolean;
sameSite?: string;
expiry?: number;
}
interface SpeechOptions {
/** 'session', 'local', or a path ending in .wav. */
target?: string;
provider?: string;
model?: string;
language?: string;
}
interface StartOptions {
/** Browser engine to launch: 'chrome' (default) or 'firefox'. */
engine?: 'chrome' | 'firefox';
/**
* Release channel of the engine to install and run, e.g. 'beta'.
* Currently honored by Firefox only.
*/
channel?: string;
headless?: boolean;
headers?: Record<string, string>;
/** Extra alwaysMatch capabilities for classic WebDriver endpoints
* (cloud grids take their config this way, via vendor-prefixed capability keys). */
caps?: Record<string, unknown>;
executablePath?: string;
/**
* Extra command-line flags for the launched browser, e.g.
* ['--use-fake-device-for-media-stream', '--lang=fr']. Each is passed to the
* engine as-is and wins over Vibium's defaults. Ignored in connect mode,
* where the browser is already running elsewhere.
*/
args?: string[];
/**
* Persistent browser profile directory, created if missing and reused
* across sessions (cookies, logins survive). Omit for the default: a
* temporary profile wiped on close. Ignored in connect mode.
*/
userDataDir?: string;
}
interface StorageState {
cookies: Cookie[];
origins: OriginState[];
}
type SwipeDirection = 'up' | 'down' | 'left' | 'right';
interface SwipeOptions {
/** Start at an edge or corner of the viewport, its center (default), or a point. */
from?: 'top' | 'bottom' | 'left' | 'right' | 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' | 'center' | {
x: number;
y: number;
};
/** Pixels to move (default: half the viewport). */
distance?: number;
/** 'slow', 'normal', 'fast', or pixels per second. Instead of duration. */
speed?: 'slow' | 'normal' | 'fast' | number;
/** Milliseconds the move takes (default 300). */
duration?: number;
/** Milliseconds to rest at the end before lifting. */
hold?: number;
}