Cheat Sheet

Session and Driver Selection

Goal	Call
Phoenix mode (auto static/live switching)	`session()` or `session(:phoenix)`
Real browser behavior	`session(:browser)`
Public browser entrypoint	`session(:browser)`
Default project lane policy	Chrome-first (CI and regular local runs)
Unified default timeout	Static `0ms`, live/browser `500ms`
Per-session timeout override	`session(timeout_ms: 300)` or `session(:browser, timeout_ms: 300)`
Browser ready timeout default	`session(:browser, ready_timeout_ms: 2200)`
Per-driver timeout config	`config :cerberus, :live, timeout_ms: 700`
Global headed mode	`config :cerberus, :browser, headless: false`
Global slow motion	`config :cerberus, :browser, slow_mo: 120`
Global remote runtime	`config :cerberus, :browser, webdriver_url: "http://127.0.0.1:4444"`
Global screenshot defaults	`config :cerberus, :browser, screenshot_full_page: false, screenshot_artifact_dir: "tmp/screenshots"`

Core Navigation and Assertions

Task	Example
Visit page	`visit(session, "/articles")`
Click link/button	`click(session, ~l"link:Counter"r)`
Fill input	`fill_in(session, ~l"Search term"l, "Aragorn")`
Select option	`select(session, ~l"Race"l, option: ~l"Elf"e)`
Choose radio	`choose(session, ~l"Email Choice"l)`
Check checkbox	`check(session, ~l"Accept Terms"l)`
Uncheck checkbox	`uncheck(session, ~l"Receive updates"l)`
Upload file	`upload(session, ~l"Avatar"l, "/tmp/avatar.jpg")`
Submit form	`submit(session, ~l"button:Run Search"r)`
Bypass browser actionability checks	`click(session, ~l"button:Hidden Action"r, force: true)`
Assert text present	`assert_has(session, ~l"Articles"e)`
Assert text absent	`refute_has(session, ~l"Error"e)`
Assert checked state	`assert_checked(session, ~l"Mail Choice"l)`
Refute checked state	`refute_checked(session, ~l"Email Choice"l)`
Assert disabled state	`assert_disabled(session, ~l"Disabled textaread"l)`
Refute disabled state	`refute_disabled(session, ~l"Notes"l)`
Assert readonly state	`assert_readonly(session, ~l"Readonly notes"l)`
Refute readonly state	`refute_readonly(session, ~l"Notes"l)`
Assert scoped text	`assert_has(session, ~l"#secondary-panel"c, ~l"Status: secondary"e)`
Refute scoped text	`refute_has(session, ~l"#secondary-panel"c, ~l"Status: primary"e)`
Assert path/query	`assert_path(session, "/search/results", query: %{q: "Aragorn"}, timeout: 500)`
Scope to subtree	`within(session, ~l"#secondary-panel"c, fn s -> ... end)`

Actionability defaults:

browser waits for matched controls to become enabled
live retries briefly when a matched form control is still disabled after a LiveView update
static fails immediately on disabled controls

Browser assertion execution model:

assert_has/refute_has and path assertions use in-browser wait loops.
Cerberus adds bounded transient eval retries for navigation/context-reset races.

Multi-Session Operations

Task	Example
New user (isolated state)	`session()` / `session(:browser)`
New tab (shared user state)	`open_tab(session)`
Switch active tab/session	`switch_tab(session, other_session)`
Close current tab	`close_tab(session)`

Locators

Default strategy:

prefer user-facing locators first (label text, role + name, visible text)
use testid when text is ambiguous or intentionally hidden
use CSS as a last resort for structure-only targeting

Common Phoenix/LiveView cases

Goal	Preferred locator	Example
Fill a text input	label text	`fill_in(session, ~l"Email"l, "alice@example.com")`
Click a button	role + name	`click(session, ~l"button:Save"r)`
Click a link	role + name	`click(session, ~l"link:Billing"r)`
Assert rendered content	visible text	`assert_has(session, ~l"Settings saved"e)`
Operate inside repeated UI	scope + same locators	`within(session, ~l"#shipping-address"c, fn s -> fill_in(s, ~l"City"l, "Berlin") end)`
Disambiguate duplicate controls	`testid`	`click(session, testid("apply-secondary-button"))`

Supported role aliases

Click/assert roles: button, menuitem, tab, link, heading, img
Form-control roles: textbox, searchbox, combobox, listbox, spinbutton, checkbox, radio, switch

Helper constructors

text("...")
~l"..."l
testid("...")
css("...")
role(:button | :link | :textbox | ..., name: "...")

Composition (advanced)

scope chaining (descendant query): css("#actions") |> role(:button, name: "Apply")
same-element AND intersection: and_(role(:button, name: "Apply"), testid("apply-secondary-button"))
descendant requirement: role(:button, name: "Apply") |> filter(has: testid("apply-secondary-marker"))
descendant exclusion: role(:button, name: "Apply") |> filter(has_not: testid("apply-secondary-marker"))
visibility constraint: role(:button, name: "Apply") |> filter(visible: true)
alternatives (OR): or_(css("#primary"), css("#secondary"))
boolean algebra: and_(role(:button, name: "Apply"), not_(testid("apply-secondary-button")))
negated conjunction: not_(and_(role(:button, name: "Apply"), testid("apply-secondary-button")))
nearest ancestor scope: closest(css(".fieldset"), from: ~l"Email"le)

Sigil `~l`

Locator	Meaning
`~l"Save"`	exact text (default)
`~l"Save"e`	exact text
`~l"Save"i`	inexact text
`~l"Email"l`	field label locator (`<label>`, `aria-labelledby`, or `aria-label`)
`~l"button:Save"r`	role-style locator
`~l"button[type='submit']"c`	css locator
`~l"save-button"t`	testid locator (`exact: true` default)
`~l"button:Save"re`	role + exact

Rules:

at most one kind modifier (r, c, l, or t)
e and i are mutually exclusive
r requires ROLE:NAME
regex values are supported for text-like locators and role names, but cannot be combined with exact: true|false
text-like matching normalizes whitespace by default (normalize_ws: true), including NBSP characters
use normalize_ws: false to require exact raw whitespace matching

Use role(..., name: ...) for supported accessible-name matching on buttons, links, headings, and similar non-form elements.

Browser-Only Extensions

Use Cerberus.Browser only with session(:browser).

Task	Example
Screenshot	`Browser.screenshot(session, path: "tmp/page.png")`
Screenshot binary result	`png = Browser.screenshot(session, path: "tmp/page.png", return_result: true)`
Screenshot + open viewer	`Browser.screenshot(session, path: "tmp/page.png", open: true)`
Type keys	`Browser.type(session, css("#input"), "hello")`
Press key	`Browser.press(session, css("#input"), "Enter")`
Drag and drop	`Browser.drag(session, "#drag-source", "#drop-target")`
Dialog assert + dismiss	`Browser.assert_dialog(session, ~l"Delete item?"e)`
Dialog assert + confirm	`Browser.assert_dialog(session, ~l"Delete item?"e, accept: true)`
Popup capture	`session` \|> `Browser.with_popup(fn main -> click(main, ~l"button:Open Popup"r) end, fn _main, popup -> assert_path(popup, "/browser/popup/destination") end)`
Popup same-tab fallback	`session(:browser, browser: [popup_mode: :same_tab])` \|> `visit("/browser/popup/auto")` \|> `assert_path("/browser/popup/destination", timeout: 1500)`
Assert download (browser/static/live)	`session` \|> `click(~l"link:Download Report"r)` \|> `assert_download("report.txt")`
Evaluate JS (ignore result)	`Browser.evaluate_js(session, "window.__cerberusMarker = 'ready'")`
Evaluate JS (assert result)	`Browser.evaluate_js(session, "(() => 42)()", fn value -> assert value == 42 end)`
Cookie lookup	`Browser.cookie(session, "_my_cookie")`
Cookie callback	`Browser.cookie(session, "_my_cookie", fn cookie -> assert cookie end)`
Bulk cookie add	`Browser.add_cookies(session, [[name: "feature", value: "on"]])`
Clear cookies	`Browser.clear_cookies(session)`
Seed Phoenix session	`Browser.add_session_cookie(session, [value: %{user_id: user.id}], MyAppWeb.Endpoint.session_options())`

Warning
Browser extension helpers intentionally raise on non-browser sessions to prevent silent semantic drift.

Mode Switching Pattern

-session()
+session(:browser)
 |> visit("/articles")
 |> assert_has(~l"Articles"e)

← Previous Page Browser Support Policy