API

Biloba API reference

Terse lookup for Biloba's Go API. Docs: https://onsi.github.io/biloba/. Sibling skills are named here without a prefix; invoke one with the same plugin prefix you loaded this skill under.

Naming conventions — assume these, they're only restated where an entry breaks them:

Selectors: CSS strings, XPath (xpath), or Locators. b.Immediate() opts out of poll-by-default; rarely needed.

Selectors / locators

CSS is the default (stable #id/[data-testid], not styling classes); locators for a11y + text/label identifiers; XPath the rare axis/ordinal tool. Speed: CSS > XPath > locators (full-document ARIA scan).

• CSS: "#id", .cls, :has(). >>> pierces one open-shadow-root / same-origin-iframe boundary per occurrence.
• XPath: b.XPath(...) — pierces neither.
• Locators (*Contains variant on every text-valued one): b.ByRole(r), b.ByText, b.ByLabel, b.ByPlaceholder, b.ByAltText, b.ByTitle, b.ByTestID(id) (attr = biloba.TestIDAttribute, default "data-testid"), b.ByCSS(sel) — raw CSS into the algebra, the only structural constructor (b.ByCSS(".story").Nth(1) for "the 2nd", not :nth-of-type). They pierce open shadow roots automatically. Accessible name covers aria-labelledby/aria-label/<label>/alt/placeholder/value/text/figcaption/caption/title.
• Role refinements: .WithName(n)/.WithNameContains(n), .Level(n), .Checked()/.Disabled()/.Expanded()/.Pressed()/.Selected().
• Composition (each accepts any CSS/XPath/Locator): .ContainingText/.NotContainingText, .Containing/.NotContaining, .And/.Or, .Within/.NotWithin, .Nth(i)/.First()/.Last(). E.g. b.ByRole("listitem").Containing(b.ByText("Delete")).Within("#cart").First().
• Trap — an unresolved scope matches nothing, so a negative assertion is vacuous. Anchor the scope first:

  Eventually("#published-list").Should(b.Exist())
  Consistently(b.ByTextContains("Draft").Within("#published-list")).ShouldNot(b.Exist())
  

Lifecycle

• biloba.SpinUpChrome(GinkgoT(), ...SpinUpOption) — start Chrome (process 1). Options: HighFidelityHeadless(), AutoInstallHeadlessShell(), HeadlessShellPath(p), StartingWindowSize(w,h), ChromeFlags(...), ChromeSandbox(enabled) (overrides the automatic Linux --no-sandbox). → setup
• biloba.ConnectToChrome(GinkgoT(), ...BilobaConfig) — open this process's root tab b. Config → debug-failures
• b.Prepare() — reset the root tab between specs (BeforeEach, OncePerOrdered).
• b.Context — the tab's chromedp context (escape hatch).

Poll config

Shallow *Biloba clones (like Realistic()); not reset by Prepare(). Use per-call: b.WithTimeout(5*time.Second).Click("#go").

b.WithTimeout(d) · b.WithPolling(d) · b.WithContext(ctx) (cancellation aborts the wait) · b.Immediate() (act once, fail fast).

Four-bucket rule — misapplying a knob is a hard error:

Configuring anything that resolves to a bare matcher — a (matcher) method (b.HaveScreenshot(name), b.Exist(), …), or the under-applied dual form (b.WithTimeout(d).Click()) — is also a hard error. Configure the Eventually, not the matcher.

Separate from all four: the CDP backstop. Every command Biloba sends Chrome carries a deadline (30s; 2min for RunAsync, whose length is set by the promise your page awaits) so an unresponsive Chrome fails the spec instead of hanging the suite. Not configurable and not a knob — WithTimeout bounds retries, not liveness, and does not shorten it. Every bucket gets it, including the two that reject every knob. Failures read deadline_exceeded / page_crashed / browser_gone → debug-failures.

.Capture(&target)

Every matcher that reads a value off the page returns a *ValueMatcher with .Capture(&x): it writes what it observed on a successful match (nothing on ShouldNot), so the gate and the read are one read (asserting then re-reading with a getter is two reads of a page that may have changed — TOCTOU). Decoded into your Go type, à la encoding/json. Full rules — typed decode, absent-vs-zero (**T), returns-a-new-matcher, narrowing JS objects vs. Biloba structs — → flaky-specs §1.

var blockID string
Eventually(".figure-frame").Should(b.HaveAttribute("data-block-id", Not(BeEmpty())).Capture(&blockID))

• Capturable: HaveAttribute, HaveProperty (both forms incl. existence-only), HaveValue, HaveInnerText, HaveTextContent, HaveText, HaveClass, HaveCount, HaveDistinctCount, HaveJSONAttribute, HaveComputedStyle, HaveComputedStyleNumeric, EachHaveInnerText, EachHaveTextContent, EachHaveClass, EachHaveProperty (both forms — the existence-only form reads values in the same round-trip, so no-arg EachHaveInnerText()/EachHaveTextContent() capture too), HaveBoundingBox, HaveScrollOffset, HaveOffsetTopWithin/HaveOffsetLeftWithin (both forms incl. existence-only), HaveGapBetween (both forms incl. existence-only), EvaluateTo, HaveURL, HaveTitle, HaveLocalStorageItem/HaveSessionStorageItem, HaveNumLocalStorageItems/HaveNumSessionStorageItems, HaveNumCookies, HaveCookie.
• Not capturable (won't compile): value-less matchers — Exist, BeVisible, BeEnabled, BeClickable, BeFocused, BeChecked, BeInViewport, BeAbove/BeBelow/BeLeftOf/BeRightOf/Encloses/Overlaps/BePrecededBy/BeFollowedBy, BeNetworkIdle, HaveScreenshot — and the actions-as-matchers (Click, SetValue, Type, …). Two read something but stay bare on purpose: MatchColor (a sub-matcher — capture off the HaveComputedStyle you hand it to) and HaveMadeRequest (a *RequestQuery builder; it renders observed requests in its failure message, and the request object comes from b.AllRequests().Find(b.RequestMatching(...))).
• Getter counterpart: the any-returning getters take an optional trailing pointer with the same decode rules — b.GetProperty("#row", "offsetWidth", &n), b.GetAttribute, b.GetValue, b.CurrentPropertyForEach, b.CurrentAttributeForEach, b.CurrentValueForEach. The value is still returned.

Navigation

• b.Navigate(url) — navigate, assert 200. / b.NavigateWithStatus(url, code).
• b.GetLocation() / b.GetTitle() → string — polling getters, all four knobs. A transient CDP error mid-navigation (Inspected target navigated or closed (-32000)) is a retryable miss.
• b.HaveURL(string|matcher) / b.HaveTitle(string|matcher) — same transient-error behavior.
• Gate on a DOM anchor, not the URL — Eventually("#dashboard-root").Should(b.Exist()) proves the navigation landed; a GetLocation() read is then a formality.

Cookies & storage (navigate to a real origin first)

• b.SetCookie(...Cookie) (default domain = current URL) · b.GetCookies() → Cookies · b.ClearCookies().
• b.HaveCookie(name|matcher) — chain .WithValue/.WithPath/.WithDomain/.WithSameSite/.WithSecure(...)/.WithHTTPOnly(...).
• b.CookieMatching(...) — predicate for Cookies.Find/Filter. · b.HaveNumCookies(int|matcher).
• b.LocalStorage() / b.SessionStorage() → Set(k,v), Get(k,&ptr), GetAll(), Remove(k), Clear(), Length() (JSON round-tripped).
• b.HaveLocalStorageItem(key[, value]) / HaveSessionStorageItem / HaveNumLocalStorageItems / HaveNumSessionStorageItems.

Tabs

• b.NewTab() → *Biloba — isolated tab (own context); closed by Prepare().
• tab.Close() → error (Eventually(tab.Close).Should(Succeed()) during downloads).
• b.AllTabs() / b.AllSpawnedTabs() → Tabs.
• b.HaveTab() / b.HaveSpawnedTab() — chain .WithURL/.WithTitle/.WithDOMElement(selector).
• b.TabMatching() — predicate for Tabs.Find/Filter.

Existence, count, visibility, enabled

• b.HasElement(selector) → bool (first; snapshot) · b.Exist().
• b.Count(selector) → int (snapshot) · b.HaveCount(int|matcher).
• b.HaveDistinctCount(attribute, int|matcher) — count of distinct values attribute takes across matches (dedupes double-painted nodes by a stable data-* key).
• b.BeVisible() — non-zero offsetWidth/offsetHeight. · b.BeEnabled() — !el.disabled. · b.BeClickable() — visible + enabled + topmost at its center (deterministic occlusion guard; Click does not run it). · b.EachBeVisible() / b.EachBeEnabled().
• Every Each* matcher means "≥1 match AND all satisfy" — it fails on zero matches instead of passing vacuously. Assert nothing matches with HaveCount(0) / ShouldNot(b.Exist()).

Contents, classes, attributes, state

• b.GetInnerText(selector) → string (polls on presence — "" is a valid value) · b.HaveInnerText(string|matcher) (exact).
• b.GetTextContent(selector) → string · b.HaveTextContent(string|matcher).
• b.HaveText(string|matcher) — trims & collapses whitespace first.
• b.CurrentInnerTextForEach(selector) → []string · b.EachHaveInnerText(value|matcher). Same pair for CurrentTextContentForEach/EachHaveTextContent. The no-arg EachHaveInnerText()/EachHaveTextContent() assert the property is defined on every match, and capture the slice — they do not mean "every text is empty". Sub-matcher and .Capture both see a typed []string (the same slice the Current*ForEach getter returns), so Equal([]string{...}) and HaveExactElements(...) both work — contrast the generic EachHaveProperty below, which hands over raw []any.
• b.HaveClass(string|matcher) — a string ⇒ "list contains"; a matcher receives []string. · b.EachHaveClass(string).
• b.HaveAttribute(name[, string|matcher]) — via getAttribute.
• b.HaveComputedStyle(prop, string|matcher) — via getComputedStyle; getter b.GetComputedStyle (see Geometry).
• b.BeChecked(). An element with no checked property at all is an error, not "unchecked" — selecting the wrapping <label>/<div> fails loudly instead of letting ShouldNot(b.BeChecked()) pass forever.
• b.BeFocused() — is document.activeElement.

Properties (. paths like dataset.name; JS types preserved — numbers are float64)

Two-axis polling: the singular Get* getters poll until the element is present AND every named property/attribute is defined.

• Trap: a property that doesn't exist on that element type (disabled on a <div>) blocks the poll to timeout. Wrap it — b.GetProperty("div.card", b.AllowMissing("disabled")) yields nil, no wait. Name params take string or AllowMissing; AllowMissing applies to GetProperty/GetProperties/GetAttribute/GetAttributes only.
• b.GetProperty(selector, name[, &ptr]) → any · b.SetProperty(selector, name, value) (dual) · b.HaveProperty(name[, value|matcher]) (matcher).
• b.GetProperties(selector, ...names) → Properties; GetString/GetInt/GetFloat64/GetBool/GetStringSlice.
• b.GetAttribute(selector, name[, &ptr]) → any (raw getAttribute markup, not the resolved property) · b.GetAttributes(selector, ...names) → Properties.
• b.GetJSONAttribute(selector, attribute, &out) (polls until present, set, and JSON-parseable, then decodes into *struct/*map/*any) · b.HaveJSONAttribute(attribute, matcher) — hands the sub-matcher the decoded value (map[string]any/[]any/float64); composes with gstruct.
• Snapshot plural getters — no poll, nil for absent, gate presence first with Eventually(sel).Should(b.HaveCount(n)): b.CurrentPropertyForEach(selector, name[, &ptr]) → []any · b.CurrentPropertiesForEach(selector, ...names) → SliceOfProperties (.Get(key), .Find(key, val|matcher), .Filter(key, val|matcher)) · b.CurrentAttributeForEach · b.CurrentAttributesForEach.
  • Trap: they return an empty slice when nothing matches, which satisfies a negated collection assertion (Ω(b.CurrentInnerTextForEach(".row")).ShouldNot(ContainElement("Draft")) passes against zero rows). The HaveCount(n) gate keeps the negative honest. Positive assertions are safer — Gomega's HaveEach errors on an empty slice.
• b.SetPropertyForEachImmediately(selector, name, value) — all matches now, no poll. · b.EachHaveProperty(name[, ...]) — sub-matcher and .Capture see the raw JSON-decoded []any (properties are heterogeneous, nothing honest to convert to); Equal([]string{...}) always fails here — use HaveExactElements(...).

Form values (rationalizes text/checkbox/radio/multi-select)

• b.GetValue(selector[, &ptr]) → any (polls on presence only — ""/unselected radio is a valid value; bool for checkbox, checked radio's value, []string for multi-select) · b.CurrentValueForEach(selector[, &ptr]) → []any.
• b.SetValue(selector, value) (dual) — requires visible+enabled; focuses, sets, fires input+change. Does not type real keys (use b.Type). For a <select> the value matches the option value, not its visible label.
• b.ValueLabel(label) — wrap a SetValue arg to target a <select> option by visible label: b.SetValue(sel, b.ValueLabel("Sonnet")). Multi-select: pass a slice (labels and raw values may mix). <select> only.
• b.HaveValue(value|matcher).

Geometry (pollable layout reads — use instead of hand-rolled b.Run geometry)

Getters poll until the element is present AND laid out (non-degenerate box). All values are viewport-relative CSS pixels. Each getter has a Have* matcher counterpart.

A missing element is an error, not a non-match. So Eventually("#toast").ShouldNot(b.BeInViewport()) times out — Gomega never counts an erroring matcher as satisfied, in either direction. Assert disappearance with ShouldNot(b.Exist()) or Should(b.HaveCount(0)); keep geometry matchers for elements that are there. Applies to HaveBoundingBox/HaveScrollOffset/HaveOffsetTopWithin/HaveOffsetLeftWithin/HaveGapBetween, the pairwise matchers, and any Consistently(sel).ShouldNot(...) on a conditionally-rendered sel. Under Eventually an error is still just a failed attempt, and a present-but-zero-area box is a silent retry, so positive assertions poll through late layout. (Matches BeVisible/BeEnabled/BeClickable, which always errored on a missing element. The pairwise/offset probes name which selector went missing: subject, container, or other.)

• b.GetBoundingBox(selector) → Box{Top,Left,Width,Height,Bottom,Right,CenterX,CenterY,ClientWidth,ClientHeight} · b.HaveBoundingBox(matcher) (receives the Box; compose with HaveField). Width/Height are border-box (incl. scrollbar gutter, like getBoundingClientRect); ClientWidth/ClientHeight are the client box (content+padding, scrollbar excluded) — "content width of this scroll container".
• b.GetScrollOffset(selector) → ScrollOffset{Top,Left,MaxTop,MaxLeft} (Top==MaxTop ⇒ scrolled to bottom) · b.HaveScrollOffset(matcher).
• b.GetOffsetTopWithin(selector, container) → float64 (element.top - container.top) · b.GetOffsetLeftWithin · b.HaveOffsetTopWithin(container[, value|matcher]) · b.HaveOffsetLeftWithin(...). No-arg form is existence-only: passes once both selector and container are laid out, without asserting on the offset value (and still captures it).
• Pairwise (both boxes read in one atomic frame — don't split into two GetBoundingBoxes): b.BeAbove(other) (subject.Bottom<=other.Top), b.BeBelow, b.BeLeftOf (subject.Right<=other.Left), b.BeRightOf, b.Encloses (all 4 edges), b.Overlaps. All matchers: Eventually(subject).Should(b.BeAbove(other)).
• b.GetGapBetween(selector, other) → BoxDelta{Top,Left,Bottom,Right,Width,Height,CenterX,CenterY} (subject minus other; CenterX~0 ⇒ shared center line, Width~0 ⇒ same size) · b.HaveGapBetween(other[, value|matcher]). No-arg form is existence-only: passes once both elements are laid out, without asserting on the delta (and still captures it).
• b.BeInViewport(options...) — laid out and intersecting the visible layout viewport (≠ BeVisible, which is only "rendered"). Partial overlap counts; b.Fully() requires all 4 edges on screen.
• b.BePrecededBy(other) / b.BeFollowedBy(other) — document order via compareDocumentPosition. Read the subject first: Should(b.BeFollowedBy(Y)) ⇔ X comes BEFORE Y; Should(b.BePrecededBy(Y)) ⇔ X comes AFTER Y. A backwards assertion doesn't flake — it silently passes on a fixture satisfying the inverse, so pin both sides (Ω(X).ShouldNot(b.BePrecededBy(Y))). Failure messages report the observed order (Actually: #note comes BEFORE #section.). "Anywhere after" includes inside — scope with Locator.NotWithin.
• b.GetComputedStyle(selector, property) → string (getPropertyValue, so kebab-case names and custom properties like --stage resolve).
• b.GetComputedStyleNumeric(selector, property) → float64 (leading number via parseFloat: "16px"→16; non-numeric fails) · b.HaveComputedStyleNumeric(property, number|matcher) — a plain number compares with BeNumerically.
• b.NormalizeColor(color) → string (pure transform: no selector, no poll) — any CSS <color> incl. a var(--token) chain (resolved against :root) → canonical rgb()/rgba(). · b.MatchColor(color) — normalizes both sides; pass as the expected: b.HaveComputedStyle("stroke", b.MatchColor("var(--tok-teal)")).

Clicking & interactions (pragmatic simulations)

• b.Click(selector) (dual) — visible+enabled, then el.click().
• b.DblClick (dual) — two clicks + dblclick. · b.RightClick — mousedown/mouseup/contextmenu. · b.MiddleClick — mousedown/mouseup/auxclick.
• b.Tap(selector) (dual) — synthetic touch/pointer + click (realistic: real CDP touchStart/touchEnd); accepts b.At(...), ignores modifiers.
• Pointer options — b.At(x,y) (offset from top-left; canvas/map/slider) and b.Shift()/b.Ctrl()/b.Alt()/b.Meta() (⌘/Win) — accepted by Click/DblClick/RightClick/MiddleClick/Tap, after the selector or in place of it (matcher form). They compose: b.Click(sel, b.At(30,40), b.Shift()). In fast mode any option switches the click off native el.click() to a synthetic event carrying coords+flags.
• b.DragTo(source, target) (dual) — pointer-based drag (pointerdown/move/up); drives @dnd-kit-style DnD, not native HTML5 draggable. Matcher subject is the source. In realistic mode both endpoints are measured at one scroll position (so a drag between two rows of one scroller works) and it fails, naming both, when no position shows them together.
• b.ScrollWheel(selector, deltaX, deltaY) (dual; matcher form drops the selector) — wheel event then scrolls the nearest scrollable ancestor; +deltaY=down, +deltaX=right.
• b.ClickEachImmediately(selector) — click all visible+enabled matches now, no poll (gate presence first).
• b.Focus / b.Blur / b.Hover (all dual; Hover fires pointer/mouse events, not CSS :hover).
• b.ScrollIntoView(selector, ...ScrollOption) (dual) — bare = native scrollIntoView(). Options: b.WithinScroller(container) (a specific container, not the nearest ancestor), b.AtTopOffset(px) (land px below the container top — "clear the sticky header"). Instant, occlusion-unaware.
• Fast clicks act in place — no scrollIntoView, no focus move. Scroll-into-view comes only from Realistic() and from focus-bearing ops (Focus/SetValue/Type).

Selecting text

Each produces a genuine window.getSelection() range and dispatches mouseup (drives highlight→menu/annotation UIs).

• b.SelectText(selector) (dual) — all of the element's text.
• b.SelectText(selector, substring[, b.Occurrence(n)]) (dual) — a substring; first occurrence by default, b.Occurrence(n) is 1-based. The matcher form requires an explicit b.Occurrence(n) so it can't be confused with select-all: Eventually("#passage").Should(b.SelectText("fox", b.Occurrence(2))).
• b.SelectRange(selector, start, end) (dual; matcher form drops the selector) — chars [start, end) across the element's text nodes; fails the spec if out of bounds.
• b.ClearSelection() — no matcher form.
• Read back with Eventually("window.getSelection().toString()").Should(b.EvaluateTo(…)).

Realistic mode → realistic-mode

b.Realistic() → *Biloba — a view of the same tab routed through real CDP input: scrolls into view, waits for stability, refuses to click through an occluding overlay, moves the real pointer (CSS :hover activates), dispatches genuine mouse/touch/key input. The whole interaction vocabulary works on it; it composes with the poll-config clones (b.Realistic().WithTimeout(d).Click(sel)). No per-call decorator. Per-spec opt-in — real round-trips, can reintroduce flake.

Keyboard (real key events, via chromedp)

• b.Type(...) (dual) — the element-targeted keyboard method: focuses (which scrolls into view), then genuine keystrokes (text and named Keys.*); appends. Arg disambiguation (after stripping modifiers):
  • b.Type(selector, payload...) — polling form: selector + ≥1 payload arg. b.Type("input", "hello", biloba.Keys.Enter).
  • b.Type(payload) — matcher form: a single string, or one-or-more Keys.*. Eventually("#in").Should(b.Type(biloba.Keys.Enter)).
  • The matcher form can't mix leading text + trailing keys (b.Type("hello", Keys.Enter) reads as selector="hello"). Use the polling form.
• b.SendKeysToWindowImmediately(...parts) — focus-free, no selector, no matcher, no poll: lands on the focused element, else fires on document/window (global hotkeys). Gate it yourself: Eventually(sel).Should(b.BeFocused()) then send. To type into an element use b.Type.
• biloba.Keys.{Enter,Tab,Escape,Backspace,Delete,Arrow{Up,Down,Left,Right},Home,End,PageUp,PageDown}.
• Modifiers b.Shift()/b.Ctrl()/b.Alt()/b.Meta() (same values as the pointer modifiers) work here too, in any position: b.Type("textarea", biloba.Keys.Enter, b.Shift()).

Uploads

• b.SetUpload(selector, ...paths) (dual) — set <input type=file> files via CDP (paths must exist on Chrome's machine); fires change. Matcher form: b.SetUpload(path) or, for multiple files, a single b.SetUpload([]string{...}) (bare variadic paths would be ambiguous with the immediate form).

Run JS on selected elements

• b.InvokeOn(selector, method, ...args) → any — el[method](...args). · b.InvokeOnEachImmediately(...) → []any.
• b.InvokeWith(selector, jsFn, ...args) → any — jsFn(el, ...args). · b.InvokeWithEachImmediately(...) → []any.

Dialogs (per-tab; reset by Prepare; register handlers BEFORE the triggering action)

• b.HandleAlertDialogs() / HandleConfirmDialogs() / HandlePromptDialogs() / HandleBeforeunloadDialogs() → DialogHandler; chain .MatchingMessage(string|matcher), .WithResponse(bool), .WithText(s). · b.RemoveDialogHandler(h).
• b.Dialogs() → Dialogs, filtered with .OfType(biloba.DialogTypeAlert|DialogTypeConfirm|DialogTypePrompt|DialogTypeBeforeunload), .MatchingMessage(string|matcher), .MostRecent(). There is no dialog matcher — assert with plain Gomega: Ω(b.Dialogs().MostRecent()).Should(HaveField("Message", "…")).
• Dialog{Type, Message, DefaultPrompt, HandleResponse, HandleText, Autohandled} (Autohandled = no registered handler matched, so a Biloba default ran).
• Default handling: alerts accepted; confirm/prompt cancelled; beforeunload accepted. An unhandled dialog also prints a "you should add an explicit dialog handler" warning — except the beforeunload that Prepare's own about:blank navigation raises when it unloads the previous spec's page, which is accepted silently and left out of b.Dialogs().

Downloads (per-tab; auto-tracked)

• b.AllDownloads() / b.AllCompleteDownloads() → Downloads.
• b.HaveDownloaded([filename]) — chain .WithURL(...), .WithContent([]byte|matcher); complete downloads only.
• b.DownloadMatching(...) — predicate for Downloads.Find.
• Download: .URL, .Filename, .IsComplete()/.IsCancelled()/.IsActive(), .Content() → []byte.

Arbitrary JS (runs on the global window; wrap object literals in parens)

• b.Run(script[, &ptr]) → any — a synchronous expression; returns the decoded value. A top-level return is illegal (errors with a hint pointing at RunAsync/IIFE). Pollable: Eventually(b.Run).WithArguments(expr).Should(matcher) — it's a func(string,...any) any. → flaky-specs
• b.RunAsync(script[, &ptr]) — the body of an async fn; you return the awaited value (use for await/fetch).
• b.RunErr(script, ...args) / b.RunErrAsync(...) → (any, error) — error-returning siblings; handle the error yourself instead of failing the spec.
• b.EvaluateTo(value|matcher) — assert a JS expression's result. Numbers decode to float64 — BeNumerically, not Equal(intLiteral). Asymmetry: the sub-matcher sees the raw JSON-decoded value ([]any of map[string]any — HaveKeyWithValue, not HaveField); .Capture(&typed) hands you the value decoded into your struct.
• b.JSFunc(script) → .Invoke(...args) string — JSON-encodes args into an invocable snippet. · b.JSVar(nameOrExpr) — reference a JS variable/expression as a JSFunc argument (don't quote it).
• b.GetJSValue(expression[, &ptr]) → any — polls until expression is defined (retries through undefined and a thrown error; null returns immediately), then returns it, decoded into a concrete type. The app-state barrier: point it at a global the app writes to prove the browser processed something — but it gates on definedness only, so it's vacuous against an eagerly-created path. Rules, the eager-path fix, and when absence itself is meaningful → flaky-specs §3.

Network (per-tab; reset by Prepare)

• b.StubRequest(url string|matcher, biloba.StubResponse{Status,Body,Headers}) — the first handler enables interception; unmatched requests pass through.
• b.AbortRequest(url string|matcher) — fail matching requests (the page's fetch rejects).
• b.ModifyRequest(url string|matcher) → .WithURL(u).WithMethod(m).WithHeader(n,v).WithBody(b) — continue to the real network, overriding only what you set.
• b.ModifyResponse(url string|matcher) → .WithStatus(s).WithHeader(n,v).WithBody(b) or .Using(func(biloba.InterceptedResponse) biloba.StubResponse) — rewrite the real response (reads real status/headers/body; heavier — pauses twice).
• Every registration returns a handle whose Count() reports how many dispatches that handler claimed — *RequestStub/*RequestAbort/*RequestModification/*ResponseModification (plus *ResponseHold below). A snapshot, safe to poll: Eventually(stub.Count).Should(Equal(1)). Assert your handler fired — a typo'd URL otherwise matches nothing, goes straight to the real network, and the spec passes for the wrong reason. Count is a fact about that handler, not the URL: first-match-wins means a handler shadowed by an earlier one stays at 0.
• All handlers share one ordered, first-match-wins list. In an Ordered container Prepare() is OncePerOrdered, so handlers accumulate across the Its: an earlier spec's handler permanently claims that URL and a later identical one is silent dead code. → flaky-specs §6
• While interception is on Biloba disables the HTTP cache (Network.setCacheDisabled(true), restored by Prepare()) — a cached response raises no Fetch event and would skip every handler.
• b.HaveMadeRequest(url string|matcher) — chain .WithMethod(m).
• b.AllRequests() → Requests (*Request has .URL/.Method/.Headers/.ResourceType); b.RequestMatching(...) predicate for .Find/.Filter.
• b.BeNetworkIdle() — zero in-flight requests at the instant it's polled, no quiet period. Tracks HTTP only (Network.requestWillBeSent/loadingFinished); a long-lived WebSocket does not keep it busy. It passes before your request has started — anchor with Eventually(b).Should(b.HaveMadeRequest(...)) first, then wait for idle.

b.HoldResponse(url string|matcher) → *ResponseHold

Intercepts the real response and holds it in flight until you release it (then it passes through unchanged). Builds on ModifyResponse — same tab scoping, same first-match-wins list. Holds every matching response by default. The tool for forcing arrival order in optimistic-UI reconciliation; full rules and reasoning (Limit/Release/ReleaseNext semantics, why Count/Release are network facts not app facts, the tab-wide/URL-based sharp edge) → flaky-specs §3.

• hold.Await() → InterceptedResponse — blocks until a match is held, returns the oldest one still held. Waiting command: own 30s default, honors WithTimeout/WithContext set on the tab you build the hold from; WithPolling/Immediate are a hard error.
• hold.Limit(n) → *ResponseHold — hold at most n concurrently; further matches pass straight through untouched (still counted).
• hold.Release() — terminal: releases everything held and disarms the hold.
• hold.Release(r) — release just that response; the hold stays armed.
• hold.ReleaseNext() — release the oldest still-held response and stay armed. Fails the spec when nothing is held.
• hold.Count() → int — every match intercepted so far, held or passed through. Snapshot, safe to poll.
• hold.Held() / hold.PassedThrough() → int — split of Count(); both snapshots, safe to poll.
• Held responses are force-released at spec end and by Prepare().

Screenshots, outline, window → debug-failures

• b.Outline() → string (indented DOM) · b.A11yOutline() → string (accessibility tree: role + name).
• b.CaptureScreenshot() → []byte (PNG) · b.CaptureImgcatScreenshot() → string · b.CaptureScreenshotToFile(path) → abs path.
• b.CaptureScreenshotOf(selector) · b.CaptureImgcatScreenshotOf(selector) · b.CaptureScreenshotOfToFile(selector, path) — clipped to the first match (any selector; works below the fold and across >>>).
• b.SetWindowSize(w, h, ...opt) · b.WindowSize(). SetWindowSize registers its own DeferCleanup to restore the prior size — don't restore manually, and don't call it from inside another DeferCleanup (Ginkgo forbids nesting). Call it bare in BeforeEach/BeforeAll.

Visual regression → visual-assertions

• b.HaveScreenshot(name string, ...ScreenshotOption) — bare matcher; compares the subject against the committed baseline <name>.png. Subject is a selector (element capture, clipped to its box) or the tab b (whole page). Every poll attempt captures and compares afresh, so the poll waits out fonts/ResizeObserver/rAF. name may contain / for subdirectories. Configure the Eventually (a knob on the matcher is a hard error); Gomega's 1s default is usually too short.

  Eventually(".card").WithTimeout(10*time.Second).Should(b.HaveScreenshot("card"))
  Eventually(b).Should(b.HaveScreenshot("home", b.InColorSchemes("light", "dark")))
  

• Options (ScreenshotOption): b.Mask(selectors...) paints matches flat gray on both sides of the comparison (no-op if nothing matches) · b.Tolerance(fraction) at most fraction (0..1) of pixels may differ · b.ChannelTolerance(delta) a pixel only counts as differing when an R/G/B/A channel is off by more than delta (the antialiasing absorber) · b.Animated() opts out of the automatic animation/transition/caret/smooth-scroll freeze (which reaches open shadow roots, not closed ones) · b.InColorSchemes(schemes...) compares once per emulated prefers-color-scheme, all must match, baseline per scheme <name>-<scheme>.png. Both tolerances default to 0 (exact).
• Baselines are committed (./biloba-baselines, BilobaConfigScreenshotBaselinesDir / BILOBA_SCREENSHOT_BASELINES_DIR); the .actual.png/.diff.png a failure writes are gitignored, landing in the failure-screenshots dir. Suite-wide tolerance: BilobaConfigScreenshotTolerance(fraction) / BilobaConfigScreenshotChannelTolerance(delta).
• A missing baseline fails (never write-and-pass) and says to re-run with BILOBA_UPDATE_SCREENSHOTS=1, which writes baselines and reports in words what changed. Update mode captures until three in a row match before writing (so a write takes ~0.5–2.2s) and warns if the page never settles. The var takes 1/t/true/y/yes/on; an unrecognised value warns. A failed comparison prints a text diagnosis (pixel counts, the changed-region shape, the untouched side) plus the three paths.