Skip to content

Browser provider

The browser provider drives Chrome / Chromium through the Chrome DevTools Protocol using chromedp. It is Go-native: no Node, no Playwright, no Selenium / WebDriver. Tales stays a single binary.

Reach for the browser provider when you need to assert behaviour that only the rendered page produces: cookies set by the server-side login flow, JavaScript-driven form interactions, redirects after authentication, etc. For pure HTTP / API checks, the HTTP provider is faster and gives you cleaner failure diagnostics.

step "browser" "<name>" {
target = "chrome" // required: config.browser.targets key
actions { // ordered list, runs sequentially
goto { url = "..." }
fill {
selector = "..."
value = "..."
}
click { selector = "..." }
wait_visible {
selector = "..."
timeout = "10s"
}
// …
}
expect { // optional, polled until timeout
visible { selector = "..." }
text {
selector = "..."
value = "..."
}
attribute {
selector = "..."
name = "..."
value = "..."
}
url { value = contains("/dashboard") }
title { value = "Dashboard" }
}
capture { // optional, evaluated against the
// post-step snapshot
heading = text("[data-testid='dashboard.title']")
csrf = attribute("meta[name='csrf-token']", "content")
current = browser.url
title = browser.title
}
}

Browser targets live under config.browser.targets:

config {
base_url = "${env("BASE_URL", "http://localhost:1337")}"
browser = {
targets = {
chrome = {
browser = "chrome" // "chrome" only in V1
headless = true // default true
executable = env("CHROME_PATH", "") // optional override
viewport = {
width = 1440 // default 1440
height = 1000 // default 1000
}
timeout = "30s" // default 30s: action / expect default
args = [
"--disable-gpu",
]
}
}
}
}

If target = "<name>" is omitted on a step and exactly one target is declared, that target is used. Multiple targets without an explicit target produce a clear error so misconfigurations don’t pick the wrong browser silently.

When headless = true (the default), Tales adds three Chrome flags on top of the user-supplied args so the browser starts cleanly in CI / Docker environments:

  • --no-sandbox: required on GitHub Actions runners and most Docker images, where the setuid sandbox cannot be created without CAP_SYS_ADMIN. Without it Chrome hangs silently at startup before CDP is reachable.
  • --disable-dev-shm-usage: avoids crashes on runners where /dev/shm is too small (typical 64 MiB containers).
  • --disable-gpu: removes a startup warning + saves a few hundred milliseconds in headless mode where GPU acceleration is irrelevant.

When headless = false, none of these flags are added: the local Chrome sandbox stays enabled and the GPU is used. To override a default in headless mode, pass the opposite flag in args (e.g. --enable-gpu if you really want it).

The provider looks for a Chrome executable in this order:

  1. The target’s executable field (when set)
  2. The CHROME_PATH environment variable
  3. Common binary names on PATH: google-chrome, google-chrome-stable, chromium, chromium-browser, chrome
  4. OS-specific install locations (macOS /Applications/Google Chrome.app/..., Linux /usr/bin/...)

A missing Chrome surfaces as a clear error suggesting executable or CHROME_PATH.

Actions execute in the order they appear in the .tales file. A failing action stops the step; subsequent actions are recorded as "skipped" so the visual report shows the full sequence.

ActionRequired attrsNotes
gotourlNavigates and waits for the document to settle
clickselector, optional forceWaits until the element is actionable, then moves the mouse to it, presses and releases
fillselector, valueClears and types value. Set secure = true to mask the value in reports
clearselectorErases the input value
presskey, optional selectorFocuses selector first if set, then presses key: a single character or a key name such as Enter. See below
submitselectorCalls HTMLFormElement.requestSubmit() (falls back to .submit())
scrollselector or x + yScrolls element into view, or scrolls the page by offset
wait_visibleselectorPolls until the element is visible
wait_not_visibleselectorPolls until the element is gone or hidden
wait_enabledselectorPolls until the element carries no disabled attribute
wait_disabledselectorPolls until the element carries the disabled attribute
hoverselector, optional forceWaits until the element is actionable, then moves the mouse over it (CSS :hover applies)
selectselector, valueSets <select> value and fires change
check / uncheckselector, optional forceClicks a checkbox / radio whose state differs, as click does, then verifies the new state. See below
upload_fileselector, pathsSets the files of an <input type="file">. See below
reloadnoneReloads the current page
back / forwardnoneNavigates the browser history. See limitations below

All actions accept an optional timeout = "<duration>" and interval = "<duration>". For click, hover, check and uncheck, interval is the pause between two actionability checks (default 100ms).

click, hover, check and uncheck drive the real mouse, and a mouse event only does what the test means when it reaches the right element. Before sending any event, these actions wait until their element is actionable, checking again until the action’s timeout expires (the action’s timeout, then the target’s timeout, then 30s):

CheckPasses whenApplies to
Visiblethe element exists, is not display: none or visibility: hidden, and has a non-empty box (opacity: 0 counts as visible)all four
Enabledit is not a disabled native form control (disabled, or inside a disabled <fieldset>), nor inside a disabled <button>click, check, uncheck
Stableits bounding box is the same on two consecutive animation framesall four
Receives eventsdocument.elementFromPoint at the click point, followed down open shadow roots, is the element or one of its descendantsall four

The element is first scrolled into view when it is not fully inside the viewport, and the click point, the center of its largest visible part, is computed after that scroll. When the point is covered, the next checks scroll the element to the end, the center, then the start of the viewport in turn, which gets it out from under a sticky header. Once the element is actionable, the mouse moves to the point, then presses and releases the left button; hover only moves it.

A click that cannot land therefore fails on the click itself, naming the check that was still failing when the timeout expired, instead of passing and leaving the next wait to time out on an unrelated selector:

action 1 (click): driver: click [data-testid='signup.submit']: not actionable after 5s: point (912, 684) is covered by <div class="toast" role="status">

The other reasons read element not found, element is not visible, element is disabled, element is not stable (its box moved between two animation frames), element is outside of the viewport, and point (x, y) hits its ancestor <div class="list">, not the element (pointer-events: none, or clipped?). When the element that takes the point belongs to a larger overlay, the overlay is named too: covered by <span class="msg"> from <div class="toast"> subtree.

The stability check costs about 50ms per pointer action (two animation frames).

check and uncheck accept an input[type=checkbox] or input[type=radio], a <label> of one (the label is clicked, the input’s state is read), or an element with role checkbox, switch or radio (aria-checked is read). They do nothing when the state already matches. Otherwise they click the element, with the checks above, then wait for the state to flip, and fail when the click did not change it. A radio button cannot be unchecked by a click: check another option of its group instead.

Styled checkboxes hide the input (display: none) or draw a substitute over it, so the input itself is not actionable. Point the selector at its <label>:

check {
selector = "label[for='newsletter']"
}

force = true skips the visible, enabled, stable and receives-events checks. The element must still be present, with a box inside the viewport, and the mouse still moves, presses and releases at its center. Keep it for the rare deliberate interaction with a covered element, for example a click on a modal’s backdrop that must dismiss it, or for an element that never stops moving (an infinite CSS animation):

click {
selector = "[data-testid='page.behind']" # covered by the modal's backdrop
force = true
}

press sends one keystroke to the focused element, after focusing selector when it is set. key is either a single character ("a", " ", or a raw control character such as "\r") or one of these key names, spelled as the W3C KeyboardEvent.key values:

GroupNames
EditingEnter, Tab, Escape, Backspace, Delete, Insert, Space
NavigationArrowUp, ArrowDown, ArrowLeft, ArrowRight, Home, End, PageUp, PageDown
FunctionF1 to F12
actions {
fill {
selector = "[data-testid='search.query']"
value = "tales"
}
press {
selector = "[data-testid='search.query']"
key = "Enter"
}
}
  • Names are case-sensitive, like the W3C values: "Enter" presses the key, "enter" is rejected with a hint pointing at "Enter".
  • Space presses the space bar. Its W3C value is a literal space, so key = " " does the same.
  • Any other string (empty, or longer than one character) is an error, never text to type. A literal key is checked when the suite loads, so a typo makes tales validate and tales test exit with code 2. A key computed at run time (from config, a capture or a function call) fails the press action instead. To type text, use fill.

wait_enabled uses the same predicate as the enabled expectation: HTML boolean-attribute semantics, where the presence of disabled is what counts (<input disabled="false"> is disabled). click already waits for a disabled control to arm (see Actionability), so reach for wait_enabled when the arming itself is what the test asserts, or when the next action does not go through the mouse (press, submit, fill).

actions {
wait_enabled {
selector = "[data-testid='form.submit']"
timeout = "10s"
}
submit {
selector = "[data-testid='form']"
}
wait_disabled {
selector = "[data-testid='form.submit']"
}
}

fill with secure = true masks the value to "***" in every report (console, JSONL, visual HTML, JUnit). The masking happens once inside the provider; reporters never see the plaintext.

fill {
selector = "[data-testid='login.password']"
value = config.test_password
secure = true
}

The value of an <input type="file"> is read-only from the DOM, so fill cannot drive a file picker. upload_file sets the input’s files through CDP (DOM.setFileInputFiles) and then dispatches input + change, so client-side code that reads the picked files — a pre-upload hash, a preview, a size check — runs exactly as it would for a real user.

step "browser" "attach_document" {
target = "chrome"
actions {
click { selector = "[data-testid='upload.open']" }
upload_file {
selector = "[data-testid='upload.input']"
paths = ["./fixtures/contract.pdf"]
timeout = "5s"
}
wait_visible { selector = "[data-testid='upload.ready']" }
}
}
  • paths takes a list, so an input with multiple is covered by a single action. A bare string is accepted as sugar for a one-file upload: paths = "./fixtures/avatar.png".
  • Relative paths resolve against the directory of the .tales file declaring the step, like body { multipart { file { path = ... } } } in the HTTP provider. Absolute paths are used as-is.
  • Every path is checked before Chrome is called: a missing path, a directory, or an empty list fails the action with an explicit message instead of a silent no-op.
  • The input does not have to be visible. Real apps routinely hide the input behind a styled <label>, so upload_file only requires the element to be present.
  • The action fails when the selector matches something that is not an input[type=file].

Expectations poll until the timeout elapses. Default timeout: 10s; default interval: 250ms.

expect {
visible { selector = "#dashboard" }
not_visible { selector = ".spinner" }
text {
selector = "h1"
value = "Dashboard" // exact match
}
text {
selector = "[data-testid='greeting']"
value = contains("Welcome") // matcher
}
attribute {
selector = "meta[name='csrf-token']"
name = "content"
value = is_string() // any string is fine
}
url { value = matches("/web/dashboard$") }
title { value = "Dashboard" }
}

All of Tales’ built-in matchers (contains, matches, one_of, any, exists, is_string, is_number, is_bool, is_array, is_object) are reusable in browser expect blocks.

Inside a browser step’s capture block, the runtime injects four browser-specific helpers backed by the snapshot recorded after the step ran:

HelperReturns
text("selector")The rendered text of the first matching element
attribute("selector", "name")The value of the named DOM attribute
browser.urlThe document URL after the step
browser.titleThe document title after the step
capture {
heading = text("h1")
csrf = attribute("meta[name='csrf-token']", "content")
current_url = browser.url
page_title = browser.title
}

These helpers are only available inside a browser step’s capture block. The standard expression scope (config, result, vars, input, generators, host, …) is still available.

V1 spawns one Chrome subprocess per (target, scenario) pair. This gives each scenario a fresh BrowserContext with its own cookies, localStorage, and history (at the cost of a ~600ms startup per scenario). The Provider holds the per-target session map and closes everything via io.Closer at suite end, so no Chrome processes leak after tales test returns.

Inside one scenario, all steps on the same target share the browser context. Use that to carry login state across steps.

On step failure (and per --capture-screenshots), the provider writes:

build/artifacts/browser/
<scenario-safe>-<hash>/<step-safe>/<phase>/attempt-<N>/
step/
screenshot.png // viewport PNG
dom.html // outerHTML of <html> when the step failed
console.jsonl // console messages and uncaught exceptions
network.jsonl // requests, responses, failures
state.json // focus, viewport, scroll, URL
actions/
0000-goto-<selector>/
screenshot.png // when --capture-screenshots=actions
dom.html
0001-fill-loginemail/
...

Artifact paths are surfaced on StepResult.Artifacts (types screenshot, dom, console, network, state) and per-action ActionResult.Screenshot / ActionResult.Hierarchy. The console reporter and JUnit list them under the failed step, the JSONL step event carries them in artifacts, and the visual HTML report links them from the step’s actions.

A screenshot and a DOM show where a step ended, not what led there. So the provider also records, from the start of every step, what the page logged and sent, and writes it next to dom.html:

  • console.jsonl: one line per console.* call ("type":"console", level such as log, warning, error) or uncaught exception ("type":"exception", with its stack). Each line has the time it was recorded, the text (the arguments rendered and joined by a space; an Error argument keeps its message line), and the url, line and column it came from.
  • network.jsonl: one line per network event of a request: request (method, url, resource_type), response (status, status_text, mime_type, from_cache; "redirect":true for a redirect, followed by the request to the new URL), finished (encoded_bytes) and failed (error_text, canceled, blocked_reason, cors_error). Every line carries the request_id linking the events of one request, and every line after the request carries elapsed_ms, the time since the request was sent by the browser’s clock. A request with no response line never got one before the files were written.
  • state.json: what the page looked like when the step failed: the active_element (tag, id, data_testid, name, type, classes, and a selector-like summary of them), the viewport size and device_pixel_ratio, the scroll offsets, the document size, the url, title and ready_state, plus captured_at.
{"time":"2026-10-21T08:14:22.309Z","type":"console","level":"log","text":"diagnostics page ready {step: 1, name: \"ping\"}","url":"http://localhost:1337/web/diagnostics","line":11,"column":15}
{"time":"2026-10-21T08:14:22.310Z","type":"exception","level":"error","text":"Uncaught Error: diagnostics boom","url":"http://localhost:1337/web/diagnostics","line":24,"column":15,"stack":[{"function":"explode","url":"http://localhost:1337/web/diagnostics","line":24,"column":15}]}
{"time":"2026-10-21T08:14:22.309Z","type":"request","request_id":"34197.2","method":"GET","url":"http://localhost:1337/web/diagnostics/ping","resource_type":"Fetch"}
{"time":"2026-10-21T08:14:22.314Z","type":"response","request_id":"34197.2","method":"GET","url":"http://localhost:1337/web/diagnostics/ping","resource_type":"Fetch","status":200,"status_text":"OK","mime_type":"application/json","elapsed_ms":12.1}

Every time uses the layout of the JSONL report’s started_at / ended_at action fields (UTC, millisecond precision), so a failed click can be lined up with what the page logged and sent around it. The click’s own point is in its JSONL action event.

When the files are written:

  • for a failed step (a failing action or a failing expectation), in every capture mode but none;
  • for every step, passing ones included, in actions mode;
  • never in none, which does not record either. A passing step in failures or steps mode writes nothing new.

The recording runs in memory and costs little: Chrome already sends these events to Tales, which only keeps them. It is bounded: the 1000 most recent console entries and the 2000 most recent network events are kept (a file that lost older ones starts with {"type":"dropped","count":N,"limit":L}), a console text is cut at 4 KiB and a stack at 20 frames ("truncated":true). state.json is read under the same bounds as a screenshot and is left out when the page does not answer; the console and network files come from memory and are written even then. A recording that saw nothing still writes its (empty) file.

--capture-screenshots <mode> (or default driven by --report-html):

  • none: no captures at all, and no failure diagnostics
  • failures (default without --report-html): one screenshot + dom.html + the failure diagnostics at step level when the step fails
  • steps: one screenshot + dom.html at the end of each step (success or failure), plus the failure diagnostics when the step fails
  • actions (default with --report-html): per-action capture, plus a failure capture if any action fails, plus the diagnostics of every step

A capture is evidence for the report, not part of what the step checks, so it runs under its own bounds instead of the step’s:

  • One capture (screenshot + dom.html) has a 5s budget, and each read inside it 2s. A read that runs out of time is tried again, up to 3 times within the budget.
  • Chrome never answers a screenshot once a navigation replaces the page it was requested on, for example a page that redirects by script right after goto. The provider watches for that navigation, gives up on the screenshot and takes it again on the new page, so the frame shows the page the browser landed on.
  • A read that still fails is skipped. The action keeps its own status and error, the next action keeps its whole timeout, and the action carries a note saying why the frame is missing (capture_note in the JSONL action event, the Capture row of the visual report), such as screenshot skipped: the browser did not answer in time (a navigation was probably in progress).

When --report-html is set, the browser provider populates the same report.ActionResult records used by the mobile provider’s visual replay. The HTML report shows:

  • Action timeline with per-action duration, start time and, for pointer actions, the point the mouse was sent to
  • Per-action screenshots (referenced via relative path under build/artifacts/browser/...)
  • Masked secure values
  • Per-action DOM snapshots (dom.html)
  • Links to the step’s own files: failure screenshot, dom.html, console.jsonl, network.jsonl, state.json

There is no browser-specific renderer: the visual layout is shared with mobile.

To share the report, ship the e2e-browser.html file together with the build/artifacts/browser/ directory (the HTML uses relative paths to load the PNG / DOM files). The CSS / JS template assets are baked into the HTML itself, so opening the report from any local folder that preserves the relative artifact layout works without a web server.

Tales applies timeouts in this precedence order (innermost first):

  1. Per-expectation timeout = "..." (just that expectation)
  2. Per-action timeout = "..." (just that action)
  3. Target driver.timeout (default for actions / expectations in the step)
  4. Built-in 10s default for expectations, 30s default for actions
  5. CLI --timeout (wraps the entire suite ctx)

Screenshot / DOM captures are bounded separately (see Captures never hold the run) and never eat into the timeout of the action that follows them.

CSS selectors only in V1. Recommended pattern: add data-testid="..." attributes to your application markup and select by those: they are stable across CSS / styling changes.

click { selector = "[data-testid='login.submit']" }

The provider also accepts any selector chromedp’s ByQuery mode supports (tag, id, class, attribute, descendant, combinator).

Browser steps are not seed-deterministic. Real-browser interaction depends on layout reflow timing, async script execution, and network latency, none of which the Tales seed mixer controls.

Pin flakiness with:

  • expect.<kind> { timeout = "10s" interval = "100ms" }: bounded polling
  • retry { attempts = 3 interval = "1s" } on the step
  • Synchronous waits (wait_visible) after navigations before asserting
  • Nothing for pointer actions: click, hover, check and uncheck already wait until their element is actionable

The seed mixer continues to work for everything outside the browser step (config, vars, generators, expressions evaluated before the provider runs).

Browser steps collect a Web Performance snapshot from Chrome after the actions settle. The snapshot is exposed under browser.performance and can be asserted via an expect { web_perf { ... } } block. Pair it with the numeric threshold matchers (lt, lte, gt, gte, between) and Go duration strings ("1800ms", "3s") to write readable budgets.

step "browser" "dashboard_perf" {
target = "chrome"
actions {
goto { url = "${config.base_url}/web/dashboard" }
wait_visible { selector = "[data-testid='dashboard.title']" }
}
expect {
web_perf {
fcp = lt("1800ms")
lcp = lt("2500ms")
cls = lt(0.1)
load = lt("3000ms")
dom_content_loaded = lt("1500ms")
resources_count = gte(1)
}
}
capture {
perf = browser.performance
}
}
Canonical name (capture)Friendly aliases (web_perf)Source
dom_content_loaded_msdom_content_loaded, dom_readyNavigation Timing API
load_event_msload, load_eventNavigation Timing API
fcp_msfcpPaint Timing API (first-contentful-paint)
lcp_mslcpPerformanceObserver (LCP)
clsclsPerformanceObserver (layout-shift)
resources_countresources_countResource Timing API
transfer_size_bytestransfer_sizeResource Timing API
encoded_body_size_bytesencoded_body_sizeResource Timing API
decoded_body_size_bytesdecoded_body_sizeResource Timing API
url, titlen/alocation / document
  • A small JS script is injected via Page.addScriptToEvaluateOnNewDocument before the first navigation. It installs PerformanceObservers for largest-contentful-paint and layout-shift so LCP and CLS accumulate from the first paint. Observer entries with hadRecentInput are excluded from CLS, matching the Web Vitals definition.
  • When a metric is intrinsically optional (LCP / CLS / FCP) and the browser did not surface a value (very simple pages or aborted navigations), expect.web_perf fails with browser performance metric "lcp_ms" is not available rather than silently passing or comparing against zero. Capture also exposes the metric as null, so HCL can branch on it.
  • Web performance is fundamentally non-deterministic. Use generous thresholds in shared CI and tighten them in environment-specific projects.
  • Chrome / Chromium only. Firefox and WebKit are out of scope.
  • CSS selectors only. No XPath, no role-based locators.
  • back and forward have known navigation-timing quirks. The naive chromedp navigation primitives hang waiting for a CDP response that the page tears down during navigation. V1 ships a workaround based on JS history.back() / history.forward() plus a short settle delay; in practice this works for the common case (back to the previous page) but may report context deadline exceeded on pages that redirect immediately. Prefer explicit goto calls when reliability matters.
  • Per-scenario Chrome startup cost (~600ms). Acceptable for now per the V1 brief; V2 may introduce a “shared context” mode.
  • No image / pixel diffing. Out of scope for V1.
Terminal window
make e2e-browser # passes when Chrome is present; skips otherwise
make e2e-browser-failure # asserts exit 1 on a deliberately broken scenario

The make targets gate on Chrome availability and exit 0 with a clear message when Chrome is missing, so CI runners without a browser stay green.

Set TALES_BROWSER_DEBUG=1 to enable verbose stderr logging from the browser provider and the Chrome builder. Each action, session start, and cleanup is timestamped.

Terminal window
TALES_BROWSER_DEBUG=1 tales test --verbose ./e2e/browser/login.tales