Skip to content

JavaScript and TypeScript

The vibium npm package drives a real browser from Node.js. It ships TypeScript types and bundles the vibium binary for your platform.

  • Node.js 18 or newer
  • Linux x64/arm64, macOS x64/arm64, or Windows x64
Terminal window
npm install vibium

Chrome for Testing downloads the first time a browser starts. To fetch it ahead of time, run npx vibium install.

Save this as hello.mjs:

import { writeFileSync } from 'node:fs'
import { browser } from 'vibium'
// Launch a browser. The window is visible by default.
const bro = await browser.start()
const vibe = await bro.page()
await vibe.go('https://example.com')
writeFileSync('screenshot.png', await vibe.screenshot())
const link = await vibe.find({ role: 'link' })
console.log('Found link:', await link.text())
await link.click()
await bro.stop()

Run it:

Terminal window
node hello.mjs

A Chrome window opens, loads the page, clicks the link, and closes. The script prints Found link: Learn more and leaves screenshot.png in the folder.

CallWhat it does
browser.start()Launches Chrome and returns a Browser
bro.page()Returns the default page (tab)
vibe.go(url)Navigates to a URL
vibe.screenshot()Returns the page as PNG bytes
vibe.find({ role: 'link' })Finds an element by its accessible role
link.click()Clicks the element
bro.stop()Closes the browser

The default import is async. vibium/sync exposes the same API without await, which suits short scripts and the Node REPL:

const { browser } = require('vibium/sync')
const bro = browser.start()
const vibe = bro.page()
vibe.go('https://example.com')
console.log(vibe.find({ role: 'link' }).text())
bro.stop()

Hide the browser window:

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

Launch Firefox instead of Chrome:

import { firefox, browser } from 'vibium'
const bro = await firefox.start()
// same as: await browser.start({ engine: 'firefox' })

See Using Firefox for engine details.

find takes semantic locators. They survive markup changes better than CSS:

await vibe.find({ role: 'button', text: 'Sign in' })
await vibe.find({ label: 'Email' })
await vibe.find({ placeholder: 'Search...' })
await vibe.find({ testid: 'checkout' })

A bare string is a plain-language description (vibe.find('the Add to Cart button')), and { css: '...' } takes an exact CSS selector. Before 26.11.16 a bare string was a CSS selector.

const result = await vibe.run('open the contact page')
const verdict = await vibe.check('the page lists an email address')