Skip to content

Bombadil plugin

Use Bombadil to check what must hold whatever a user does on a screen: the page never throws, a cart total always equals the sum of its lines, an error toast always goes away, a counter never jumps. Browser steps sign in and reach the screen; one Bombadil step then clicks, types, scrolls and goes back at random for a time you choose, checking the properties of a spec your flow carries after every action; Browser steps then carry on in the same tab.

Bombadil is Antithesis’s open-source property-based tester for web interfaces (MIT). A Browser step checks one journey you wrote; Bombadil tries orders of actions nobody wrote. Start with Browser steps. Add Bombadil for a screen with rules that must hold in every state, and keep a Browser step with an explicit expect as the regression test for anything it finds.

Bombadil is an optional plugin. It carries the Bombadil 0.8.0 release for your platform (macOS on Apple silicon, Linux arm64 and x64); it uses the Browser plugin’s page and needs no browser of its own. reflow init downloads it once from the release your CLI was installed from and checks it; plan and apply never download.

Terminal window
reflow init --upgrade Bombadil --collection <collection-id>

The binding takes no configuration (traces is only for replay):

{
"site": {"provider": "Browser", "configuration": {"targetUrl": "http://localhost:3000"}},
"explore": {"provider": "Bombadil", "configuration": {}}
}
---
name: Cart stays consistent whatever a user does
url: /carts/zz-e2e-cart
providers:
site: Browser
explore: Bombadil
---
### Open the seeded cart
```rfl
open /carts/zz-e2e-cart
expect role=heading name="Your cart"
```
### Explore the cart for a minute
```rfl
explore.run browser="site" spec="cart.spec.ts" time=60s timeout=2m avoid="[data-testid=checkout], a[href$='/logout']"
```
### The tab is back on the cart
```rfl
expect role=heading name="Your cart"
```
```ts file="cart.spec.ts"
import { extract, always, eventually, now } from "@antithesishq/bombadil";
export * from "@antithesishq/bombadil/browser/defaults";
const cart = extract((state) => {
const lines = [...state.document.querySelectorAll("[data-testid=line-total]")];
const total = state.document.querySelector("[data-testid=cart-total]");
if (!total) return null;
const cents = (el) => Math.round(Number(el.textContent.replace(/[^0-9.]/g, "")) * 100);
return { lines: lines.reduce((sum, el) => sum + cents(el), 0), total: cents(total) };
});
const toast = extract((state) => state.document.querySelector("[role=alert]")?.textContent ?? null);
export const totalIsSumOfLines = always(() => cart.current === null || cart.current.total === cart.current.lines);
export const errorsGoAway = always(
now(() => toast.current !== null).implies(eventually(() => toast.current === null).within(5, "seconds")),
);
```
ArgumentMeaning
browserThe Browser alias of this flow whose page to explore. Required.
specThe spec: a .ts or .js file the flow carries. Required.
timeHow long to explore, 5s to 10m. Required. The statement’s timeout= must be at least 30 seconds longer.
avoidCSS selector list of elements never clicked, nor activated with Enter or Space.
expectViolationThe step passes only when exactly this property is violated.

The spec exports properties (always, eventually(…).within, next over values extract reads from the page) and actions. export * from "@antithesishq/bombadil/browser/defaults" adds checks for uncaught exceptions, console errors and failing document loads, and clicks, typing, scrolling and Back. It may import other files the flow carries and Bombadil’s own modules, nothing else. The Bombadil manual describes the language.

Where it explores. Only the page the Browser steps opened, and only on the application’s own origin: not the sign-in origins you granted, not other tabs. History before the step cannot be reached. Dialogs are dismissed, never accepted. Navigations elsewhere are refused as for any Browser step.

After the step the same tab is back on the URL exploration started on, freshly loaded, with the same sign-in. What the exploration changed stays changed: data, local storage, in-page state. If it signed out, or the page cannot return there, the step fails. Start the next steps from a state you set up again.

Exploration clicks and types anything it can reach. Point it at a test account in a test tenant whose server cannot send real invitations, take payments or delete what other tests need, on data earlier steps created and cleanup steps remove. List sign-out, delete, pay and invite controls in avoid, and filter actions in the spec (clicks.filter(…)). avoid is a safety aid: typing, autosave and forms submitted another way are not filtered. Do not read secrets in a spec: what it extracts is kept as evidence.

OutcomeMeaning
heldNothing in the spec was violated during time, after at least one action.
violatedA property was violated. The step names it with Bombadil’s explanation and keeps the actions, the last 8 screenshots and trace.bin.
spec errorThe spec does not parse or fails to load.
refusedWrong arguments, an import or re-export a spec may not use, or no Browser page to explore.
no verdictThe engine stopped without proof that anything was checked.

Open trace.bin with bombadil browser inspect trace.bin to step through every state with its screenshot. A pass keeps no screenshots and no trace.

Exploration is random and Bombadil has no seed, so a pass means nothing was violated in that sample. Reflow reuses a passed step like any other until the flow, its files, its inputs or the target change; reflow taint explores again. A flow with Browser steps always runs from its first step, so exploration always starts from the state your steps build. Keep exploration out of golden flows.

explore.replay repeats a recorded trace’s actions on the page and checks the spec again, for debugging on your machine. Save trace.bin from the finding into a private directory, name it in the binding as traces, and pin it:

explore.replay browser="site" spec="cart.spec.ts" trace="found.bin" sha256="<traceSha256 of the finding>"

It passes when the recorded actions run and nothing is violated, fails naming what was violated, and fails as diverged when the page does not offer a recorded action.