api

name

api

description

One-line reference for every Biloba method and matcher, grouped by area — selectors/locators, lifecycle, navigation, cookies/storage, tabs, DOM existence/visibility/contents/properties/forms, clicking and interactions (incl. drag/scroll/tap/modifiers/text-selection), realistic mode, keyboard, uploads, element JS, dialogs, downloads, arbitrary JS, network stubbing/aborting/modifying/observing, and screenshots/outline/window. Use to look up the exact method or matcher name and shape. Methods marked (dual) act immediately when fully applied and return a pollable matcher when under-applied.

Biloba API reference

Terse lookup. (dual) = acts immediately when fully applied, returns a Gomega matcher when under-applied (poll with Eventually). (matcher) = always returns a matcher. first = acts on the first match; each = acts on all matches (empty slice when none). Selectors are CSS strings, XPath (see biloba:xpath), or semantic **Locator**s. Full docs: https://onsi.github.io/biloba/.

Selectors / locators

Three pathways, all flow through every method/matcher. CSS is the default (target stable #id/[data-testid] hooks, not styling classes); locators second (a11y assertions + readable text/label identifiers); XPath the rare power tool (axis/ordinal). CSS fastest, XPath fast, locators slowest (full-document ARIA scan).

• CSS string ("#id", ".cls", :has()); >>> pierces open shadow roots / same-origin iframes (one boundary per >>>). XPath via b.XPath(...) (see biloba:xpath) — does not pierce shadow/iframe.
• Locator constructors (all have a *Contains variant where text-valued): b.ByRole(role); b.ByText(t)/b.ByTextContains(t); b.ByLabel(t)/b.ByLabelContains(t); b.ByPlaceholder(t); b.ByAltText(t); b.ByTitle(t); b.ByTestID(id) (attr = biloba.TestIDAttribute, default "data-testid").
• Role refinements: .WithName(n)/.WithNameContains(n) (accessible name); .Level(n) (heading level); ARIA-state filters .Checked()/.Disabled()/.Expanded()/.Pressed()/.Selected().
• Composition (all accept any CSS/XPath/Locator): .ContainingText(t)/.NotContainingText(t); .Containing(sel)/.NotContaining(sel); .And(sel)/.Or(sel) (intersection/union); .Within(scope); .Nth(i)/.First()/.Last(). Example: b.ByRole("listitem").Containing(b.ByText("Delete")).Within("#cart").First().
• Locators pierce open shadow roots automatically (no >>> needed). Accname covers aria-labelledby/aria-label/<label>/alt/placeholder/value/text/figcaption/caption/title.

Lifecycle / config

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

Navigation

• b.Navigate(url) — navigate, assert 200.
• b.NavigateWithStatus(url, code) — navigate, assert a specific status.
• b.Location() / b.Title() — current URL / title (pollable).
• b.HaveURL(string|matcher) (matcher) — assert tab URL.
• b.HaveTitle(string|matcher) (matcher) — assert tab title.

Cookies & storage (navigate to a real origin first)

• b.SetCookie(...Cookie) — set one or more cookies (default domain = current URL).
• b.GetCookies() → Cookies — all cookies in this context.
• b.ClearCookies() — clear them.
• b.HaveCookie(name|matcher) (matcher) — chain .WithValue/.WithPath/.WithDomain/.WithSameSite/.WithSecure(...)/.WithHTTPOnly(...).
• b.CookieMatching(...) — same query as a predicate for Cookies.Find/Filter.
• b.HaveNumCookies(int|matcher) (matcher).
• b.LocalStorage() / b.SessionStorage() → handle with Set(k,v), Get(k,&ptr), GetAll(), Remove(k), Clear(), Length() (JSON round-tripped).
• b.HaveLocalStorageItem(key[, value]) / b.HaveSessionStorageItem(...) (matcher).
• b.HaveNumLocalStorageItems(...) / b.HaveNumSessionStorageItems(...) (matcher).

Tabs

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

Existence, count, visibility, enabled

• b.HasElement(selector) → bool (first).
• b.Exist() (matcher) — element matches.
• b.Count(selector) → int / b.HaveCount(int|matcher) (matcher).
• b.BeVisible() (matcher) — non-zero offsetWidth/offsetHeight. / b.EachBeVisible() (matcher) — every match visible (vacuously true if none).
• b.BeEnabled() (matcher) — !el.disabled. / b.EachBeEnabled() (matcher) — every match enabled (vacuously true if none).
• b.BeClickable() (matcher) — visible + enabled + topmost at its center (deterministic occlusion guard; opt-in, Click does not run it).

Contents, classes, attributes, state

• b.InnerText(selector) → string (first) / b.HaveInnerText(string|matcher) (matcher, exact).
• b.HaveText(string|matcher) (matcher) — trims & collapses whitespace before matching.
• b.InnerTextForEach(selector) → []string (each) / b.EachHaveInnerText(...) (matcher).
• b.HaveClass(string|matcher) (matcher) — string ⇒ "list contains"; matcher receives []string. / b.EachHaveClass(string) (matcher) — every match has the class (vacuously true if none).
• b.HaveAttribute(name[, string|matcher]) (matcher) — HTML attribute via getAttribute.
• b.HaveComputedStyle(prop, string|matcher) (matcher) — via getComputedStyle.
• b.BeChecked() (matcher) — checkbox/radio checked.
• b.BeFocused() (matcher) — is document.activeElement.

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

• b.GetProperty(selector, name) → any (first) / b.SetProperty(selector, name, value) (dual) / b.HaveProperty(name[, value|matcher]) (matcher).
• b.GetPropertyForEach(selector, name) → []any / b.SetPropertyForEach(selector, name, value) (no matcher; gate on the matches being present first) / b.EachHaveProperty(name[, ...]) (matcher).
• b.GetProperties(selector, ...names) → Properties (first); getters GetString/GetInt/GetFloat64/GetBool/GetStringSlice.
• b.GetPropertiesForEach(selector, ...names) → SliceOfProperties (each); same getters return slices; .Get(key), .Find(key, val|matcher), .Filter(key, val|matcher).

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

• b.GetValue(selector) → any (first; bool for checkbox, checked radio's value, []string for multi-select).
• b.SetValue(selector, value) (dual) — requires visible+enabled; focuses, sets, blurs, fires input+change. Does not type real keys. For a <select> the value is matched against the option value, not its visible label (assert labels via option.textContent).
• b.ValueLabel(label) — wrap a SetValue arg to target a <select> option by its visible label instead of its value: b.SetValue(sel, b.ValueLabel("Sonnet")). Multi-select: pass a slice whose entries are ValueLabels (labels and raw values may be mixed). <select> only.
• b.HaveValue(value|matcher) (matcher).

Clicking & interactions (pragmatic simulations)

• b.Click(selector) (dual) — visible+enabled, then el.click().
• b.DblClick(selector) (dual) — two clicks + dblclick. b.RightClick(selector) (dual) — mousedown/mouseup/contextmenu. b.MiddleClick(selector) (dual) — mousedown/mouseup/auxclick.
• b.Tap(selector) (dual) — synthetic touch/pointer events + click (realistic: real CDP touchStart/touchEnd); accepts b.At(...), ignores modifiers.
• Pointer options — b.At(x,y) (offset from top-left, à la canvas/map/slider), 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 a click off native el.click() to a synthetic event carrying coords+flags; realistic uses real CDP input natively.
• 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: Eventually(src).Should(b.DragTo(tgt)).
• b.ScrollWheel(selector, deltaX, deltaY) (dual; matcher form b.ScrollWheel(deltaX, deltaY)) — wheel event then scrolls nearest scrollable ancestor (realistic: real CDP wheel); +deltaY=down, +deltaX=right.
• b.ClickEach(selector) — click all visible+enabled matches (no matcher; gate on the matches being present first).
• b.Focus(selector) (dual) / b.Blur(selector) (dual) / b.Hover(selector) (dual; fires pointer/mouse events, not CSS :hover) / b.ScrollIntoView(selector) (dual).
• b.SelectText(selector) (dual) — select all of the element's text as a real window.getSelection() range, dispatching mouseup (drives highlight→menu/annotation UIs).
• b.SelectRange(selector, start, end) (dual; matcher form b.SelectRange(start, end)) — select chars [start, end) across the element's text nodes; same range+mouseup. Read back with Eventually("window.getSelection().toString()").Should(b.EvaluateTo(…)).
• b.ClearSelection() — clear any active selection (no matcher).

Realistic mode (opt-in; real CDP input instead of fast JS simulation)

• b.Realistic() → *Biloba — a view of the same tab whose interactions run through real Chrome DevTools Protocol 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. Per-spec opt-in (real round-trips, can reintroduce flake); the whole interaction vocabulary above works on it. No per-call decorator.
• Compose inline (b.Realistic().Click(sel)), per-spec (rb := b.Realistic()), or per-suite (Label("realistic") + BeforeEach{ rb = b.Realistic() }, then ginkgo --label-filter='realistic'/'!realistic'). Fast-vs-realistic capability matrix: https://onsi.github.io/biloba/#realistic-interactions.

Keyboard (real key events, via chromedp)

• b.Type(selector, text) (dual) — focus, then genuine keystrokes; appends. Focusing scrolls the element into view.
• b.SendKeys([selector,] ...parts) — send text + named keys; selector optional (else focused element). No matcher form (the keys-only shape is reserved for the focused element); gate on readiness first (Eventually(sel).Should(b.BeEnabled())) when the target appears asynchronously.
• 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() work here too (same values as the pointer modifiers): pass them in any position to Type/SendKeys for Shift-Enter, ⌘-A, etc. — b.SendKeys("textarea", biloba.Keys.Enter, b.Shift()).

Uploads

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

Run JS on selected elements

• b.InvokeOn(selector, method, ...args) → any (first) — el[method](...args).
• b.InvokeOnEach(selector, method, ...args) (each).
• b.InvokeWith(selector, jsFn, ...args) → any (first) — jsFn(el, ...args).
• b.InvokeWithEach(selector, jsFn, ...args) (each).

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

• b.HandleAlertDialogs() / HandleConfirmDialogs() / HandlePromptDialogs() / HandleBeforeUnloadDialogs() → DialogHandler.
• chain .MatchingMessage(string|matcher), .WithResponse(bool), .WithText(s).
• b.RemoveDialogHandler(h).
• b.Dialogs() → filter .OfType(biloba.DialogType...), .MatchingMessage(...), .MostRecent().
• b.HaveAlertDialog(...) etc. (matcher). Defaults: alerts accepted; confirm/prompt cancelled; beforeunload accepted.

Downloads (per-tab; auto-tracked)

• b.AllDownloads() / b.AllCompleteDownloads() → Downloads.
• b.HaveDownloaded([filename]) (matcher) — 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 — synchronous expression; returns the decoded value (no return allowed at top level — it errors with a hint pointing to RunAsync/IIFE). Pollable: Eventually(b.Run).WithArguments(expr).Should(matcher) (it's a func(string,...any) any) — the fix for a single-shot read that races an async settle (biloba:flaky-specs).
• b.RunAsync(script[, &ptr]) / b.RunErrAsync(...) — body of an async fn; you return the awaited value (use this for await/fetch).
• b.EvaluateTo(value|matcher) (matcher) — assert a JS expression's result. Numbers decode to float64 — use BeNumerically, not Equal(intLiteral).
• 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).

Network (per-tab; reset by Prepare)

• b.StubRequest(url string|matcher, biloba.StubResponse{Status,Body,Headers}) — first handler enables interception; unmatched requests pass through. Handlers below share one ordered, first-match-wins list.
• b.AbortRequest(url string|matcher) — fail matching requests (page's fetch rejects).
• b.ModifyRequest(url string|matcher) → builder .WithURL(u).WithMethod(m).WithHeader(n,v).WithBody(b) — continue to the real network with overrides (only what you set).
• b.ModifyResponse(url string|matcher) → builder .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).
• b.HaveMadeRequest(url string|matcher) (matcher) — chain .WithMethod(m).
• b.AllRequests() → Requests (each *Request has .URL/.Method/.Headers/.ResourceType); b.RequestMatching(...) predicate for .Find/.Filter.
• b.BeNetworkIdle() (matcher) — zero in-flight requests. Tracks HTTP requests only (keyed on Network.requestWillBeSent/loadingFinished request IDs); a long-lived WebSocket does not keep it busy, so it won't wait for WS frames.

Screenshots, outline, window (details in biloba:debug-failures)

• b.Outline() → string — indented DOM text.
• b.A11yOutline() → string — accessibility tree (role + name).
• b.CaptureScreenshot() → []byte (PNG) / b.CaptureImgcatScreenshot() → string / b.CaptureScreenshotToFile(path) → abs path.
• b.CaptureScreenshotOf(selector) → []byte / b.CaptureImgcatScreenshotOf(selector) → string / b.CaptureScreenshotOfToFile(selector, path) → abs path — clipped to the first matching element (any selector; works below the fold and across >>> boundaries).
• b.SetWindowSize(w, h, ...opt) (auto-resets via DeferCleanup) / b.WindowSize(). Because it registers its own DeferCleanup to restore the prior size, you don't need a manual restore — and you must not call it from inside another DeferCleanup (Ginkgo forbids nesting), so call it bare in BeforeEach/BeforeAll.