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.
Install
Section titled “Install”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.
reflow init --upgrade Bombadil --collection <collection-id>Connect
Section titled “Connect”The binding takes no configuration (traces is only for replay):
{ "site": {"provider": "Browser", "configuration": {"targetUrl": "http://localhost:3000"}}, "explore": {"provider": "Bombadil", "configuration": {}}}Explore a screen
Section titled “Explore a screen”---name: Cart stays consistent whatever a user doesurl: /carts/zz-e2e-cartproviders: site: Browser explore: Bombadil---
### Open the seeded cart```rflopen /carts/zz-e2e-cartexpect role=heading name="Your cart"```
### Explore the cart for a minute```rflexplore.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```rflexpect 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")),);```| Argument | Meaning |
|---|---|
browser | The Browser alias of this flow whose page to explore. Required. |
spec | The spec: a .ts or .js file the flow carries. Required. |
time | How long to explore, 5s to 10m. Required. The statement’s timeout= must be at least 30 seconds longer. |
avoid | CSS selector list of elements never clicked, nor activated with Enter or Space. |
expectViolation | The 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.
Explore a disposable account
Section titled “Explore a disposable account”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.
Read a finding
Section titled “Read a finding”| Outcome | Meaning |
|---|---|
| held | Nothing in the spec was violated during time, after at least one action. |
| violated | A property was violated. The step names it with Bombadil’s explanation and keeps the actions, the last 8 screenshots and trace.bin. |
| spec error | The spec does not parse or fails to load. |
| refused | Wrong arguments, an import or re-export a spec may not use, or no Browser page to explore. |
| no verdict | The 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.
Repeat and reuse
Section titled “Repeat and reuse”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.
Replay a finding
Section titled “Replay a finding”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.