<picture id="README">
<source media="(prefers-color-scheme: dark)" srcset="docs/images/biloba-dark.png">
<img alt="Biloba" src="docs/images/biloba.png">
</picture>
[](https://github.com/onsi/biloba/actions/workflows/test.yml?query=branch%3Amaster) [](https://onsi.github.io/biloba/) [](https://github.com/sponsors/onsi)
---
# Biloba
> "Automated browser testing is slow and flaky" - _every developer, ever_
Biloba builds on top of [chromedp](https://github.com/chromedp/chromedp) to bring stable, performant, automated browser testing to Ginkgo. It embraces three principles:
- Performance via parallelization
- Stability via pragmatism
- Conciseness via Ginkgo and Gomega
It's [blazing fast](#performance) and designed to work [_really_ well with AI toolchains like Claude Code](#using-biloba-with-claude-code).
Take a look at the [documentation](https://onsi.github.io/biloba) to learn more and [get started](https://onsi.github.io/biloba/#getting-started)! Biloba tests can be written in Go using Ginkgo, [and in typescript using vitest](#vitest-support) ([quick-start for vitest](https://onsi.github.io/biloba/vitest.html#getting-set-up)).
Or [let Claude Code set it up for you](#using-biloba-with-claude-code).
Biloba is remarkably feature complete and in active development. A 1.0 release milestone has not been reached yet, so the public API contract may shift as the project evolves. Send feedback!
Here's a quick taste of what Biloba specs look like in Ginkgo:
```go
func login(tab *Biloba, user string, password string) {
GinkgoHelper()
tab.Navigate("/login")
Eventually(tab.ByLabel("Username")).Should(tab.SetValue(user)) // locator: a form control by its label
tab.SetValue(tab.ByLabel("Password"), password)
tab.Click(tab.ByRole("button").WithName("Log in")) // locator: role + accessible name
Eventually(".chat-page").Should(tab.Exist())
}
Describe("a simple chat app", func() {
// b is a *Biloba instance spun up in our BeforeSuite (not shown). We open an
// isolated tab per user, and generate reusable selectors/locators off b.
var tabSally, tabJane *Biloba
BeforeEach(func() {
tabSally = b.NewTab()
login(tabSally, "sally", "yllas")
tabJane = b.NewTab()
login(tabJane, "jane", "enaj")
})
It("shows all logged in users as present", func() {
// both tabs should show both users online, by the names a user actually reads
for _, tab := range []*Biloba{tabSally, tabJane} {
Eventually(b.ByText("Sally").Within("#user-list")).Should(tab.HaveClass("online"))
Eventually(b.ByText("Jane").Within("#user-list")).Should(tab.HaveClass("online"))
}
})
It("shows Jane that Sally is typing", func() {
lastEntry := b.ByRole("listitem").Within("#conversation").Last()
tabSally.SetValue("#input", "Hey Jane, how are you?")
Eventually(lastEntry).Should(SatisfyAll(
tabJane.HaveText("Sally is typing..."),
tabJane.HaveClass("typing"),
))
tabSally.SetValue("#input", "")
Eventually(lastEntry).ShouldNot(SatisfyAny(
tabJane.HaveText("Sally is typing..."),
tabJane.HaveClass("typing"),
))
})
It("delivers messages between Sally and Jane", func() {
lastEntry := b.ByRole("listitem").Within("#conversation").Last()
tabSally.Type("#input", "Hey Jane, how are you?") // real keystrokes...
tabSally.Type("#input", biloba.Keys.Enter) // ...sent by pressing Enter
Eventually(lastEntry).Should(tabJane.HaveText("Hey Jane, how are you?"))
tabJane.Type("#input", "I'm splendid, Sally!")
tabJane.Click(b.ByRole("button").WithName("Send"))
Eventually(lastEntry).Should(tabSally.HaveText("I'm splendid, Sally!"))
})
It("lets Sally share a document that Jane can download", func() {
tabSally.SetUpload(b.ByLabel("Attach a file"), "./fixtures/report.pdf")
tabSally.Click(b.ByRole("button").WithName("Send"))
doc := b.ByRole("link").WithName("report.pdf")
Eventually(doc).Should(tabJane.BeVisible()) // Jane sees the shared document...
tabJane.Click(doc) // ...and downloads it
Eventually(tabJane).Should(tabJane.HaveDownloaded("report.pdf"))
})
It("reveals message actions on hover", func() {
rb := tabSally.Realistic() // a view of the same tab, driven by real Chrome input
tabSally.SetValue("#input", "Hey Jane")
tabSally.Click(b.ByRole("button").WithName("Send"))
last := b.ByRole("listitem").Within("#conversation").Last()
rb.Hover(last) // genuine CSS :hover — one of the few things the fast track can't do
Eventually(b.ByRole("button").WithName("React").Within(last)).Should(tabSally.BeVisible())
})
It("renders a message bubble exactly as designed", func() {
tabSally.SetValue("#input", "Hey Jane")
tabSally.Click(b.ByRole("button").WithName("Send"))
// compare against a committed baseline — masking the volatile timestamp,
// in both themes. A failure says what moved and where, in words.
Eventually(b.ByRole("listitem").Within("#conversation").Last()).Should(
tabSally.HaveScreenshot("message-bubble",
tabSally.Mask(".timestamp"),
tabSally.InColorSchemes("light", "dark")))
})
It("shows an error when a message fails to send", func() {
tabSally.AbortRequest(ContainSubstring("/messages")) // make the send fail, hermetically
tabSally.SetValue("#input", "Hey Jane")
tabSally.Click(b.ByRole("button").WithName("Send"))
Eventually(b.ByRole("alert")).Should(tabSally.HaveText("Message failed to send"))
})
It("loads conversation history", func() {
// stub the history response
tabSally.StubRequest(ContainSubstring("/history"), biloba.StubResponse{
Body: `[{"from":"Jane","text":"Welcome back!"}]`,
})
tabSally.Navigate("/chat")
Eventually(b.ByRole("listitem").Within("#conversation")).Should(tabSally.HaveText("Welcome back!"))
})
It("tracks when users aren't online", func() {
jane := b.ByText("Jane").Within("#user-list")
Eventually(jane).Should(tabSally.HaveClass("online"))
tabJane.Close()
Eventually(jane).Should(tabSally.HaveClass("offline"))
})
})
```
Run these in series with `ginkgo`. And in parallel with `ginkgo -p` for fast, stable, isolated browser tests.
## Poll by default
Browsers are asynchronous, so Biloba's interactions and value-getters **poll by default**. A fully-applied call like `tab.Click("#go")` or `tab.SetValue("#input", "hi")` retries — finding-and-acting atomically in the browser — until it succeeds or times out.
When you want to make the wait explicit (to compose with `Consistently`, or assert on a richer condition), every interaction also has a Gomega matcher form:
```go
Eventually("#go").Should(tab.Click())
Eventually(tab.ByLabel("Email")).Should(tab.SetValue("me@example.com"))
```
And when you genuinely want act-once / fail-fast semantics — no polling — opt out with `tab.Immediate()`:
```go
tab.Immediate().Click("#go") // act now; fail immediately if it isn't clickable yet
```
Polling timeout, interval, and context are configurable Gomega-style with `tab.WithTimeout(...)`, `tab.WithPolling(...)`, and `tab.WithContext(...)`.
## Fast and realistic interaction tracks
By default Biloba interactions are **fast**: atomic JavaScript simulations (`el.click()`, value-set, synthetic events) that run as a single in-browser snippet — no scroll, no occlusion check, no real cursor. This is what keeps Biloba quick and stable, and it's the right default for the vast majority of specs.
For the handful of specs that need genuine input fidelity — real CSS `:hover`, occlusion-aware clicks, scroll-into-view, real keystrokes/drags/wheel/touch — `b.Realistic()` returns a view of the *same tab* whose interactions route through real Chrome DevTools Protocol input. Same API, just a more faithful (and slightly slower) interaction engine. See the [documentation](https://onsi.github.io/biloba) (and the `biloba-go:realistic-mode` Claude Code skill).
## Performance
Biloba is fast. [**onsi/biloba-comparison**](https://github.com/onsi/biloba-comparison) is a reproducible, three-way speed comparison against Playwright — an identical 32-scenario suite run under biloba-fast, biloba-realistic, and Playwright. On an Apple M1 Max (whole-suite wall clock, median of 15 runs):
| config | parallel (8 workers) | serial |
|---|---:|---:|
| **biloba-fast** | **2.57s** | **9.55s** |
| **biloba-realistic** | **3.26s** | **18.60s** |
| playwright | 8.23s | 38.37s |
biloba-fast runs the suite **~3.2× faster in parallel / ~4.0× serial** than Playwright; even biloba-realistic — doing the same real-CDP-input work Playwright does — stays **~2.5× / ~2.1×** ahead. See [the comparison repo](https://github.com/onsi/biloba-comparison) for the methodology, the per-bucket breakdown, and the charts.
Of course, synthetic benchmarks don't necessarily capture real-world performance. Here are two real-life data-points:
- [A 1,689 spec Ginkgo Biloba suite completes in under 60s](https://claude.ai/code/artifact/d2e1b070-780c-478b-80f9-5fc617dd81d5?org=b6fadba7-f133-4a3c-b118-3b76f250d94f) on an M1 Max Macbook Pro. These are real-browser tests for an interaction-rich javascript app backed by a go server.
- A mature 165 scenario playwright suite was converted to a Biloba vitest suite. [Runtime went from ~3m10s down to ~1m13s](https://onsi-public.s3.amazonaws.com/biloba-playwright.html) - a 2.6x observed speedup.
Fast browser test suites foster better discipline and open the door to more stable suites. A recommended workflow is to run a local flake-hunt periodically after an extended coding session. The 1,689 spec suite described above has a less than 1% suite flake rate thanks to this ceremony (it takes more than 60 suite runs to see a flake appear). The [documentation](https://onsi.github.io/biloba/#nurturing-maintainable-suites) and `flake-hunt` skill describe how to set flake hunts up.
### What about Lightpanda?
[Lightpanda](https://github.com/lightpanda-io/browser) is a headless browser built for automation that speaks the Chrome DevTools Protocol. We pointed Biloba at it and ran Biloba's own suite plus the real-world app suite described above. The gains were modest. Specs that passed on both browsers ran about 1.5× faster in Biloba's suite and about 1.2× faster in the real-world app. Biloba already avoids most of what makes Chrome slow: it reuses tabs on one shared chrome-headless-shell, and a round trip to Chrome takes well under a millisecond. Most of a spec's time goes to the app's own JavaScript, which runs on V8 in both browsers, and to its server.
The cost was steep: 17% of Biloba's specs and 28% of the real-world app's specs failed. Lightpanda has no layout engine, so element geometry, viewport and scroll checks don't work, and neither do visibility checks that depend on layout. Screenshots aren't real renders, so visual regression is out. Each connection gets one page, so there are no new or spawned tabs. Downloads, much of network interception, the accessibility tree and realistic input are also missing. If you'd still like a faster DOM-only lane built on Lightpanda, [open an issue](https://github.com/onsi/biloba/issues) and we can explore it.
## Using Biloba with Claude Code
Biloba ships separate [Claude Code](https://claude.com/claude-code) plugins for its Go/Gomega and TypeScript/Vitest clients, with this repo doubling as the marketplace. Install the client you use:
```
/plugin marketplace add onsi/biloba
/plugin install biloba-go@biloba
/plugin install biloba-vitest@biloba
```
(or use `claude plugin marketplace add onsi/biloba` followed by `claude plugin install biloba-go@biloba` or `claude plugin install biloba-vitest@biloba`.)
Or let Claude Code do the whole setup. Paste one of these into Claude Code at the root of your project and it will install the plugin, add Biloba, and get a first suite running:
**Go (Ginkgo and Gomega):**
```text
Set up Biloba (https://github.com/onsi/biloba) browser tests for this Go project.
1. Install the Claude Code plugins for this project:
claude plugin marketplace add onsi/biloba --scope project
claude plugin install biloba-go@biloba --scope project
claude plugin marketplace add onsi/ginkgo --scope project
claude plugin install ginkgo@ginkgo --scope project
claude plugin marketplace add onsi/gomega --scope project
claude plugin install gomega@gomega --scope project
If the biloba-go skills aren't available in this session afterwards, stop and ask me to restart Claude Code, then carry on from step 2.
2. Read the biloba-go:overview and biloba-go:setup skills and follow setup: go get github.com/onsi/biloba, install chrome-headless-shell, and bootstrap a Ginkgo suite for the browser specs (in ./e2e unless this project has a better place).
3. Work out how the suite should start and serve the app, one stable origin per parallel process (ask me if it isn't obvious). Then use biloba-go:explore-unfamiliar-page to look at a real page and write a first spec against it with biloba-go:write-tests.
4. Run the suite with ginkgo -p until it passes, gitignore the failure screenshots directory, and tell me how to run the suite myself.
```
**TypeScript (Vitest):**
```text
Set up Biloba (https://github.com/onsi/biloba) browser tests with Vitest for this TypeScript project.
1. Install the Claude Code plugin for this project:
claude plugin marketplace add onsi/biloba --scope project
claude plugin install biloba-vitest@biloba --scope project
If the biloba-vitest skills aren't available in this session afterwards, stop and ask me to restart Claude Code, then carry on from step 2.
2. Read the biloba-vitest:overview and biloba-vitest:setup skills and follow setup: add vitest and biloba as dev dependencies with this project's package manager, run npx biloba install-chrome, start one shared Chrome in Vitest's global setup, and connect a session per test file.
3. Work out how the tests should start and serve the app (ask me if it isn't obvious). Then write a first test against a real page with biloba-vitest:write-tests.
4. Run the suite until it passes, gitignore the failure screenshots directory, add a script to package.json that runs it, and tell me how to run it myself.
```
## Failure Output
Biloba automatically captures and emits screenshots and any JavaScript console output when tests fail. It even hooks into Ginkgo's progress emitter infrastructure so `^T`/`SIGNIFO` on a mac (`SIGUSR2` on linux) will spit out a screenshot.
Screenshots are great for humans but won't show up in most CI systems and don't help AI agents. Biloba autodetects when it's being run in CI or by an agent and spits out DOM outlines and puts screenshot files on disk instead automatically.
The same instinct shapes `b.HaveScreenshot`, Biloba's visual-regression matcher: when a comparison against a committed baseline fails, Biloba writes the usual `.actual.png`/`.diff.png` pair *and* tells an agnet in words what changed — how many pixels, where the changed boxes are, and whether the shape of the change reads as one region, a uniform shift, or something scattered across every text run. Those three are different bugs, and you can tell them apart without opening an image.
## Vitest Support
Biloba's TypeScript client lets a `vitest` suite drive Chrome through Biloba. Read [**Biloba for Vitest**](https://onsi.github.io/biloba/vitest.html) to learn more. Each `vitest` worker process spawns a small [Go daemon](https://onsi.github.io/biloba/vitest.html#why-theres-a-daemon) (`bilobad`) and talks to it over framed JSON on stdin/stdout. Every daemon attaches to one shared Chrome — the same "one browser, one isolated tab per parallel process" model that makes the Go suites fast.
To [get started](https://onsi.github.io/biloba/vitest.html#getting-set-up):
```bash
npm install -D vitest biloba
npx biloba install-chrome # fetches chrome-headless-shell; once per Chrome version
```
the `install` command pulls in the library and a precompiled `bilobad` — no Go toolchain required - for macOS/Linux, x64/armn64. Windows isn't supported yet - open an issue if you want it.
Here's the chat app from the top of this README, in TypeScript. Actions and assertions poll by default, exactly as they do in Go:
```ts
import {beforeEach, describe, it} from "vitest";
import {contains, Keys, not, type Session} from "biloba";
async function login(tab: Session, user: string, password: string) {
await tab.navigate("/login");
await tab.getByLabel("Username").setValue(user); // locator: a form control by its label
await tab.getByLabel("Password").setValue(password);
await tab.getByRole("button", {name: "Log in"}).click(); // locator: role + accessible name
await tab.locator(".chat-page").expectExists();
}
describe("a simple chat app", () => {
// session is a root Session opened in a beforeAll (not shown). We open an isolated tab per
// user off of it, and generate reusable locators off each tab.
let tabSally: Session, tabJane: Session;
beforeEach(async () => {
tabSally = await session.newTab();
await login(tabSally, "sally", "yllas");
tabJane = await session.newTab();
await login(tabJane, "jane", "enaj");
});
it("shows all logged in users as present", async () => {
// both tabs should show both users online, by the names a user actually reads
for (const tab of [tabSally, tabJane]) {
await tab.getByText("Sally").within("#user-list").expectClass("online");
await tab.getByText("Jane").within("#user-list").expectClass("online");
}
});
it("shows Jane that Sally is typing", async () => {
const lastEntry = tabJane.getByRole("listitem").within("#conversation").last();
await tabSally.locator("#input").setValue("Hey Jane, how are you?");
await lastEntry.expectText("Sally is typing...");
await lastEntry.expectClass("typing");
await tabSally.locator("#input").setValue("");
await lastEntry.expectNotText("Sally is typing...");
await lastEntry.expectClass(not(contains("typing")));
});
it("delivers messages between Sally and Jane", async () => {
await tabSally.locator("#input").type("Hey Jane, how are you?"); // real keystrokes...
await tabSally.locator("#input").type(Keys.Enter); // ...sent by pressing Enter
await tabJane.getByRole("listitem").within("#conversation").last()
.expectText("Hey Jane, how are you?");
await tabJane.locator("#input").type("I'm splendid, Sally!");
await tabJane.getByRole("button", {name: "Send"}).click();
await tabSally.getByRole("listitem").within("#conversation").last()
.expectText("I'm splendid, Sally!");
});
it("lets Sally share a document that Jane can download", async () => {
await tabSally.getByLabel("Attach a file").setUploadFiles(["./fixtures/report.pdf"]);
await tabSally.getByRole("button", {name: "Send"}).click();
const doc = tabJane.getByRole("link", {name: "report.pdf"});
await doc.expectVisible(); // Jane sees the shared document...
await doc.click(); // ...and downloads it
await tabJane.expectDownload({filename: "report.pdf"});
});
it("reveals message actions on hover", async () => {
await tabSally.locator("#input").setValue("Hey Jane");
await tabSally.getByRole("button", {name: "Send"}).click();
const last = tabSally.getByRole("listitem").within("#conversation").last();
await last.realistic().hover(); // genuine CSS :hover — one of the few things the fast track can't do
await tabSally.getByRole("button", {name: "React"}).within(last).expectVisible();
});
it("renders a message bubble exactly as designed", async () => {
await tabSally.locator("#input").setValue("Hey Jane");
await tabSally.getByRole("button", {name: "Send"}).click();
// compare against a committed baseline — masking the volatile timestamp,
// in both themes. A failure says what moved and where, in words.
await tabSally.getByRole("listitem").within("#conversation").last()
.expectScreenshot("message-bubble", {
mask: [tabSally.locator(".timestamp")],
colorSchemes: ["light", "dark"],
});
});
it("shows an error when a message fails to send", async () => {
await tabSally.abortRequest(contains("/messages")); // make the send fail, hermetically
await tabSally.locator("#input").setValue("Hey Jane");
await tabSally.getByRole("button", {name: "Send"}).click();
await tabSally.getByRole("alert").expectText("Message failed to send");
});
it("loads conversation history", async () => {
// stub the history response
await tabSally.stubRequest(contains("/history"), {
body: new TextEncoder().encode('[{"from":"Jane","text":"Welcome back!"}]'),
});
await tabSally.navigate("/chat");
await tabSally.getByRole("listitem").within("#conversation").expectText("Welcome back!");
});
it("tracks when users aren't online", async () => {
const jane = tabSally.getByText("Jane").within("#user-list");
await jane.expectClass("online");
await tabJane.close();
await jane.expectClass("offline");
});
});
```
### Running Vitest Tests
Start one Chrome for the whole run in vitest's global setup and hand its connection to the workers. Register that setup — and a process pool, so each test file really is its own worker with its own daemon — in your vitest config:
```ts
// vitest.config.ts
import {defineConfig} from "vitest/config";
export default defineConfig({
test: {
environment: "node",
globalSetup: ["./test/global-setup.ts"],
pool: "forks",
fileParallelism: true,
},
});
```
Then run the suite the way you run any other vitest suite:
```bash
npx vitest run # the whole suite, files in parallel across worker processes
npx vitest # watch mode
npx vitest run chat # just the files whose path matches "chat"
```
Every worker shares the one Chrome that global setup started, so adding workers costs a daemon and a tab rather than a browser. See the [setup section of the Vitest docs](https://onsi.github.io/biloba/vitest.html#getting-set-up) for the `global-setup.ts` and per-file `connect`/`openSession` boilerplate.
---
Ginkgo Tree Graphics Designed By 可行 From <a href="https://lovepik.com/image-401791345/ginkgo-branches-in-autumn.html">LovePik.com</a>