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.
When to use it
Section titled “When to use it”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.
Anatomy of a browser step
Section titled “Anatomy of a browser step”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 }}Configuration
Section titled “Configuration”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.
Headless defaults
Section titled “Headless defaults”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 withoutCAP_SYS_ADMIN. Without it Chrome hangs silently at startup before CDP is reachable.--disable-dev-shm-usage: avoids crashes on runners where/dev/shmis 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).
Chrome resolution
Section titled “Chrome resolution”The provider looks for a Chrome executable in this order:
- The target’s
executablefield (when set) - The
CHROME_PATHenvironment variable - Common binary names on
PATH:google-chrome,google-chrome-stable,chromium,chromium-browser,chrome - 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
Section titled “Actions”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.
| Action | Required attrs | Notes |
|---|---|---|
goto | url | Navigates and waits for the document to settle |
click | selector, optional force | Waits until the element is actionable, then moves the mouse to it, presses and releases |
fill | selector, value | Clears and types value. Set secure = true to mask the value in reports |
clear | selector | Erases the input value |
press | key, optional selector | Focuses selector first if set, then presses key: a single character or a key name such as Enter. See below |
submit | selector | Calls HTMLFormElement.requestSubmit() (falls back to .submit()) |
scroll | selector or x + y | Scrolls element into view, or scrolls the page by offset |
wait_visible | selector | Polls until the element is visible |
wait_not_visible | selector | Polls until the element is gone or hidden |
wait_enabled | selector | Polls until the element carries no disabled attribute |
wait_disabled | selector | Polls until the element carries the disabled attribute |
hover | selector, optional force | Waits until the element is actionable, then moves the mouse over it (CSS :hover applies) |
select | selector, value | Sets <select> value and fires change |
check / uncheck | selector, optional force | Clicks a checkbox / radio whose state differs, as click does, then verifies the new state. See below |
upload_file | selector, paths | Sets the files of an <input type="file">. See below |
reload | none | Reloads the current page |
back / forward | none | Navigates 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).
Actionability
Section titled “Actionability”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):
| Check | Passes when | Applies to |
|---|---|---|
| Visible | the element exists, is not display: none or visibility: hidden, and has a non-empty box (opacity: 0 counts as visible) | all four |
| Enabled | it is not a disabled native form control (disabled, or inside a disabled <fieldset>), nor inside a disabled <button> | click, check, uncheck |
| Stable | its bounding box is the same on two consecutive animation frames | all four |
| Receives events | document.elementFromPoint at the click point, followed down open shadow roots, is the element or one of its descendants | all 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
Section titled “check and uncheck”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']"}Opting out with force
Section titled “Opting out with force”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}Pressing keys
Section titled “Pressing keys”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:
| Group | Names |
|---|---|
| Editing | Enter, Tab, Escape, Backspace, Delete, Insert, Space |
| Navigation | ArrowUp, ArrowDown, ArrowLeft, ArrowRight, Home, End, PageUp, PageDown |
| Function | F1 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". Spacepresses the space bar. Its W3C value is a literal space, sokey = " "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 validateandtales testexit with code2. A key computed at run time (fromconfig, a capture or a function call) fails thepressaction instead. To type text, usefill.
Waiting for a control to arm
Section titled “Waiting for a control to arm”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']" }}Secure values
Section titled “Secure values”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}File uploads
Section titled “File uploads”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']" } }}pathstakes a list, so an input withmultipleis 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
.talesfile declaring the step, likebody { 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>, soupload_fileonly requires the element to be present. - The action fails when the selector matches something that is not an
input[type=file].
Expectations
Section titled “Expectations”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.
Capture helpers
Section titled “Capture helpers”Inside a browser step’s capture block, the runtime injects four browser-specific helpers backed by the snapshot recorded after the step ran:
| Helper | Returns |
|---|---|
text("selector") | The rendered text of the first matching element |
attribute("selector", "name") | The value of the named DOM attribute |
browser.url | The document URL after the step |
browser.title | The 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.
Sessions and isolation
Section titled “Sessions and isolation”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.
Artifacts
Section titled “Artifacts”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.
Failure diagnostics
Section titled “Failure diagnostics”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 perconsole.*call ("type":"console",levelsuch aslog,warning,error) or uncaught exception ("type":"exception", with itsstack). Each line has thetimeit was recorded, thetext(the arguments rendered and joined by a space; anErrorargument keeps its message line), and theurl,lineandcolumnit 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":truefor a redirect, followed by the request to the new URL),finished(encoded_bytes) andfailed(error_text,canceled,blocked_reason,cors_error). Every line carries therequest_idlinking the events of one request, and every line after the request carrieselapsed_ms, the time since the request was sent by the browser’s clock. A request with noresponseline never got one before the files were written.state.json: what the page looked like when the step failed: theactive_element(tag,id,data_testid,name,type,classes, and a selector-like summary of them), theviewportsize anddevice_pixel_ratio, thescrolloffsets, thedocumentsize, theurl,titleandready_state, pluscaptured_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
actionsmode; - never in
none, which does not record either. A passing step infailuresorstepsmode 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 modes
Section titled “Capture modes”--capture-screenshots <mode> (or default driven by --report-html):
none: no captures at all, and no failure diagnosticsfailures(default without--report-html): one screenshot + dom.html + the failure diagnostics at step level when the step failssteps: one screenshot + dom.html at the end of each step (success or failure), plus the failure diagnostics when the step failsactions(default with--report-html): per-action capture, plus a failure capture if any action fails, plus the diagnostics of every step
Captures never hold the run
Section titled “Captures never hold the run”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_notein the JSONL action event, the Capture row of the visual report), such asscreenshot skipped: the browser did not answer in time (a navigation was probably in progress).
Visual report integration
Section titled “Visual report integration”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.
Timeout layering
Section titled “Timeout layering”Tales applies timeouts in this precedence order (innermost first):
- Per-expectation
timeout = "..."(just that expectation) - Per-action
timeout = "..."(just that action) - Target
driver.timeout(default for actions / expectations in the step) - Built-in 10s default for expectations, 30s default for actions
- 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.
Selectors
Section titled “Selectors”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).
Determinism caveat
Section titled “Determinism caveat”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 pollingretry { attempts = 3 interval = "1s" }on the step- Synchronous waits (
wait_visible) after navigations before asserting - Nothing for pointer actions:
click,hover,checkanduncheckalready 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).
Web performance budgets
Section titled “Web performance budgets”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 }}Available metrics
Section titled “Available metrics”| Canonical name (capture) | Friendly aliases (web_perf) | Source |
|---|---|---|
dom_content_loaded_ms | dom_content_loaded, dom_ready | Navigation Timing API |
load_event_ms | load, load_event | Navigation Timing API |
fcp_ms | fcp | Paint Timing API (first-contentful-paint) |
lcp_ms | lcp | PerformanceObserver (LCP) |
cls | cls | PerformanceObserver (layout-shift) |
resources_count | resources_count | Resource Timing API |
transfer_size_bytes | transfer_size | Resource Timing API |
encoded_body_size_bytes | encoded_body_size | Resource Timing API |
decoded_body_size_bytes | decoded_body_size | Resource Timing API |
url, title | n/a | location / document |
Implementation notes
Section titled “Implementation notes”- A small JS script is injected via
Page.addScriptToEvaluateOnNewDocumentbefore the first navigation. It installsPerformanceObservers forlargest-contentful-paintandlayout-shiftso LCP and CLS accumulate from the first paint. Observer entries withhadRecentInputare 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_perffails withbrowser performance metric "lcp_ms" is not availablerather than silently passing or comparing against zero. Capture also exposes the metric asnull, 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.
V1 limitations
Section titled “V1 limitations”- Chrome / Chromium only. Firefox and WebKit are out of scope.
- CSS selectors only. No XPath, no role-based locators.
backandforwardhave 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 JShistory.back()/history.forward()plus a short settle delay; in practice this works for the common case (back to the previous page) but may reportcontext deadline exceededon pages that redirect immediately. Prefer explicitgotocalls 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.
CI example
Section titled “CI example”make e2e-browser # passes when Chrome is present; skips otherwisemake e2e-browser-failure # asserts exit 1 on a deliberately broken scenarioThe 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.
Debugging
Section titled “Debugging”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.
TALES_BROWSER_DEBUG=1 tales test --verbose ./e2e/browser/login.tales