@spec alt(String.t() | Regex.t()) :: Cerberus.Locator.t()

Builds an alt-text locator.

@spec alt(String.t() | Regex.t(), Cerberus.Options.locator_leaf_opts()) ::
  Cerberus.Locator.t()

@spec alt(Cerberus.Locator.t(), String.t() | Regex.t()) :: Cerberus.Locator.t()

Builds or composes an alt-text locator.

Supported forms:

• alt(value, opts) for a leaf locator
• alt(locator, value) to compose with an existing locator

@spec alt(
  Cerberus.Locator.t(),
  String.t() | Regex.t(),
  Cerberus.Options.locator_leaf_opts()
) ::
  Cerberus.Locator.t()

Composes an alt-text constraint into an existing locator with locator options.

@spec and_(Cerberus.Locator.t(), Cerberus.Locator.t()) :: Cerberus.Locator.t()

Composes two locators with logical AND (same-element intersection).

Both sides must match the same DOM node.

@spec assert_checked(arg, Cerberus.Locator.t()) :: arg when arg: var

Asserts that at least one element matched by locator is checked.

Options

• :visible - Chooses visible text only, hidden only, or both. The default value is true.

• :timeout (non_neg_integer/0) - Retries text assertions for up to this many milliseconds. The default value is 0.

• :count (term/0) - Requires exactly this many text matches. The default value is nil.

• :min (term/0) - Requires at least this many text matches. The default value is nil.

• :max (term/0) - Requires at most this many text matches. The default value is nil.

• :between (term/0) - Requires text match count to fall within an inclusive range. The default value is nil.

@spec assert_disabled(arg, Cerberus.Locator.t()) :: arg when arg: var

Asserts that at least one element matched by locator is disabled.

Options

• :visible - Chooses visible text only, hidden only, or both. The default value is true.

• :timeout (non_neg_integer/0) - Retries text assertions for up to this many milliseconds. The default value is 0.

• :count (term/0) - Requires exactly this many text matches. The default value is nil.

• :min (term/0) - Requires at least this many text matches. The default value is nil.

• :max (term/0) - Requires at most this many text matches. The default value is nil.

• :between (term/0) - Requires text match count to fall within an inclusive range. The default value is nil.

@spec assert_download(arg, String.t(), Cerberus.Options.assert_download_opts()) :: arg
when arg: var

Asserts a file download by suggested filename across drivers.

Typical flow is sequential:

session
|> click(role(:link, name: "Download Report"))
|> assert_download("report.txt")

Browser driver waits on BiDi download events. Static/live drivers assert on the current response content-disposition headers.

Options

• :timeout (pos_integer/0) - Wait timeout in milliseconds for download detection. The default value is 1500.

@spec assert_has(arg, Cerberus.Locator.t()) :: arg when arg: var

Asserts that content matched by locator exists.

Unscoped: assert_has(session, ~l"Articles"e)

Composed locator form: assert_has(session, and_(css("a"), text("Counter", exact: true)))

For explicit scope boundaries, use within/3.

@spec assert_has(arg, Cerberus.Locator.t(), Cerberus.Options.assert_opts()) :: arg
when arg: var

Asserts content exists.

Options

• :visible - Chooses visible text only, hidden only, or both. The default value is true.

• :timeout (non_neg_integer/0) - Retries text assertions for up to this many milliseconds. The default value is 0.

• :count (term/0) - Requires exactly this many text matches. The default value is nil.

• :min (term/0) - Requires at least this many text matches. The default value is nil.

• :max (term/0) - Requires at most this many text matches. The default value is nil.

• :between (term/0) - Requires text match count to fall within an inclusive range. The default value is nil.

@spec assert_path(arg, String.t() | Regex.t(), Cerberus.Options.path_opts()) :: arg
when arg: var

Asserts the session path matches expected.

Options

• :exact (boolean/0) - Requires an exact path match unless disabled. The default value is true.

• :query (term/0) - Optionally validates query params as a subset map/keyword. The default value is nil.

• :timeout (non_neg_integer/0) - Retries path assertions for up to this many milliseconds. The default value is 0.

@spec assert_readonly(arg, Cerberus.Locator.t()) :: arg when arg: var

Asserts that at least one element matched by locator is readonly.

Options

• :visible - Chooses visible text only, hidden only, or both. The default value is true.

• :timeout (non_neg_integer/0) - Retries text assertions for up to this many milliseconds. The default value is 0.

• :count (term/0) - Requires exactly this many text matches. The default value is nil.

• :min (term/0) - Requires at least this many text matches. The default value is nil.

• :max (term/0) - Requires at most this many text matches. The default value is nil.

• :between (term/0) - Requires text match count to fall within an inclusive range. The default value is nil.

@spec assert_selected(arg, Cerberus.Locator.t()) :: arg when arg: var

Asserts that at least one element matched by locator is selected.

Options

• :visible - Chooses visible text only, hidden only, or both. The default value is true.

• :timeout (non_neg_integer/0) - Retries text assertions for up to this many milliseconds. The default value is 0.

• :count (term/0) - Requires exactly this many text matches. The default value is nil.

• :min (term/0) - Requires at least this many text matches. The default value is nil.

• :max (term/0) - Requires at most this many text matches. The default value is nil.

• :between (term/0) - Requires text match count to fall within an inclusive range. The default value is nil.

@spec assert_value(arg, Cerberus.Locator.t(), String.t() | Regex.t()) :: arg
when arg: var

Asserts that the current value of a form field matched by locator equals expected.

String values use exact matching. Regex values are matched against the current field value.

@spec assert_value(
  arg,
  Cerberus.Locator.t(),
  String.t() | Regex.t(),
  Cerberus.Options.assert_value_opts()
) :: arg
when arg: var

Asserts a form-field value.

Options

• :timeout (non_neg_integer/0) - Retries value assertions for up to this many milliseconds. The default value is 0.

• :checked (term/0) - Requires matched fields to be checked/unchecked. The default value is nil.

• :disabled (term/0) - Requires matched fields to be disabled/enabled. The default value is nil.

• :selected (term/0) - Requires matched fields to be selected/unselected. The default value is nil.

• :readonly (term/0) - Requires matched fields to be readonly/editable. The default value is nil.

• :count (term/0) - Requires exactly this many matched candidates. The default value is nil.

• :min (term/0) - Requires at least this many matched candidates. The default value is nil.

• :max (term/0) - Requires at most this many matched candidates. The default value is nil.

• :between (term/0) - Requires matched candidate count to fall within an inclusive range. The default value is nil.

• :first (boolean/0) - Selects the first matched candidate. The default value is false.

• :last (boolean/0) - Selects the last matched candidate. The default value is false.

• :nth (term/0) - Selects the nth (1-based) matched candidate. The default value is nil.

• :index (term/0) - Selects the index (0-based) matched candidate. The default value is nil.

@spec check(arg, Cerberus.Locator.t()) :: arg when arg: var

Checks a checkbox matched by locator.

Bare string/regex shorthand is not supported.

Use explicit locators like ~l"..."l, testid(...), css(...), or explicit text sigils (~l"..."e / ~l"..."i).

Sigil examples: check(session, ~l"#subscribe"c), check(session, ~l"subscribe-checkbox"t).

@spec check(arg, Cerberus.Locator.t(), Cerberus.Options.check_opts()) :: arg
when arg: var

Checks a matched checkbox.

Options

• :timeout (non_neg_integer/0) - Browser action timeout in milliseconds.

• :force (boolean/0) - Bypasses browser actionability checks before dispatching the action. The default value is false.

• :checked (term/0) - Requires matched fields to be checked/unchecked. The default value is nil.

• :disabled (term/0) - Requires matched fields to be disabled/enabled. The default value is nil.

• :selected (term/0) - Requires matched fields to be selected/unselected. The default value is nil.

• :readonly (term/0) - Requires matched fields to be readonly/editable. The default value is nil.

• :count (term/0) - Requires exactly this many matched candidates. The default value is nil.

• :min (term/0) - Requires at least this many matched candidates. The default value is nil.

• :max (term/0) - Requires at most this many matched candidates. The default value is nil.

• :between (term/0) - Requires matched candidate count to fall within an inclusive range. The default value is nil.

• :first (boolean/0) - Selects the first matched candidate. The default value is false.

• :last (boolean/0) - Selects the last matched candidate. The default value is false.

• :nth (term/0) - Selects the nth (1-based) matched candidate. The default value is nil.

• :index (term/0) - Selects the index (0-based) matched candidate. The default value is nil.

@spec choose(arg, Cerberus.Locator.t()) :: arg when arg: var

Chooses a radio input matched by locator.

Bare string/regex shorthand is not supported.

Use explicit locators like ~l"..."l, testid(...), css(...), or explicit text sigils (~l"..."e / ~l"..."i).

Sigil examples: choose(session, ~l"#contact_email"c), choose(session, ~l"contact-email"t).

@spec choose(arg, Cerberus.Locator.t(), Cerberus.Options.choose_opts()) :: arg
when arg: var

Chooses a matched radio input.

Options

• :timeout (non_neg_integer/0) - Browser action timeout in milliseconds.

• :force (boolean/0) - Bypasses browser actionability checks before dispatching the action. The default value is false.

• :checked (term/0) - Requires matched fields to be checked/unchecked. The default value is nil.

• :disabled (term/0) - Requires matched fields to be disabled/enabled. The default value is nil.

• :selected (term/0) - Requires matched fields to be selected/unselected. The default value is nil.

• :readonly (term/0) - Requires matched fields to be readonly/editable. The default value is nil.

• :count (term/0) - Requires exactly this many matched candidates. The default value is nil.

• :min (term/0) - Requires at least this many matched candidates. The default value is nil.

• :max (term/0) - Requires at most this many matched candidates. The default value is nil.

• :between (term/0) - Requires matched candidate count to fall within an inclusive range. The default value is nil.

• :first (boolean/0) - Selects the first matched candidate. The default value is false.

• :last (boolean/0) - Selects the last matched candidate. The default value is false.

• :nth (term/0) - Selects the nth (1-based) matched candidate. The default value is nil.

• :index (term/0) - Selects the index (0-based) matched candidate. The default value is nil.

@spec click(arg, Cerberus.Locator.t()) :: arg when arg: var

Clicks a matched element using unscoped shorthand (click(session, locator)).

@spec click(arg, Cerberus.Locator.t(), Cerberus.Options.click_opts()) :: arg
when arg: var

Clicks a matched element.

Options

• :timeout (non_neg_integer/0) - Browser action timeout in milliseconds.

• :force (boolean/0) - Bypasses browser actionability checks before dispatching the action. The default value is false.

• :checked (term/0) - Requires matched elements to be checked/unchecked. The default value is nil.

• :disabled (term/0) - Requires matched elements to be disabled/enabled. The default value is nil.

• :selected (term/0) - Requires matched elements to be selected/unselected. The default value is nil.

• :readonly (term/0) - Requires matched elements to be readonly/editable. The default value is nil.

• :count (term/0) - Requires exactly this many matched candidates. The default value is nil.

• :min (term/0) - Requires at least this many matched candidates. The default value is nil.

• :max (term/0) - Requires at most this many matched candidates. The default value is nil.

• :between (term/0) - Requires matched candidate count to fall within an inclusive range. The default value is nil.

• :first (boolean/0) - Selects the first matched candidate. The default value is false.

• :last (boolean/0) - Selects the last matched candidate. The default value is false.

• :nth (term/0) - Selects the nth (1-based) matched candidate. The default value is nil.

• :index (term/0) - Selects the index (0-based) matched candidate. The default value is nil.

@spec close_tab(arg) :: arg when arg: var

Closes the current tab for browser sessions.

@spec closest(Cerberus.Locator.t(), Cerberus.Options.closest_opts()) ::
  Cerberus.Locator.t()

Composes a locator that matches the closest ancestor of a nested from locator.

Example:

within(session, closest(~l".fieldset"c, from: ~l"textbox:Email"r), &assert_has(&1, ~l"can't be blank"e))

@spec css(String.t()) :: Cerberus.Locator.t()

Builds a CSS locator.

@spec css(String.t(), Cerberus.Options.locator_leaf_opts()) :: Cerberus.Locator.t()

@spec css(Cerberus.Locator.t(), String.t()) :: Cerberus.Locator.t()

Builds or composes a CSS locator.

Supported forms:

• css(value, opts) for a leaf locator
• css(locator, value) to compose with an existing locator

@spec css(Cerberus.Locator.t(), String.t(), Cerberus.Options.locator_leaf_opts()) ::
  Cerberus.Locator.t()

Composes a CSS constraint into an existing locator with locator options.

@spec fill_in(
  arg,
  Cerberus.Locator.t(),
  Cerberus.Options.fill_in_value(),
  Cerberus.Options.fill_in_opts()
) :: arg
when arg: var

Fills a form field matched by locator.

Bare string/regex shorthand is not supported.

Use explicit locators like ~l"..."l, role(...), placeholder(...), title(...), testid(...), css(...), or explicit text sigils (~l"..."e / ~l"..."i).

Sigil examples: fill_in(session, ~l"#search_q"c, "Aragorn"), fill_in(session, ~l"search-input"t, "Aragorn").

Options

• :timeout (non_neg_integer/0) - Browser action timeout in milliseconds.

• :force (boolean/0) - Bypasses browser actionability checks before dispatching the action. The default value is false.

• :checked (term/0) - Requires matched fields to be checked/unchecked. The default value is nil.

• :disabled (term/0) - Requires matched fields to be disabled/enabled. The default value is nil.

• :selected (term/0) - Requires matched fields to be selected/unselected. The default value is nil.

• :readonly (term/0) - Requires matched fields to be readonly/editable. The default value is nil.

• :count (term/0) - Requires exactly this many matched candidates. The default value is nil.

• :min (term/0) - Requires at least this many matched candidates. The default value is nil.

• :max (term/0) - Requires at most this many matched candidates. The default value is nil.

• :between (term/0) - Requires matched candidate count to fall within an inclusive range. The default value is nil.

• :first (boolean/0) - Selects the first matched candidate. The default value is false.

• :last (boolean/0) - Selects the last matched candidate. The default value is false.

• :nth (term/0) - Selects the nth (1-based) matched candidate. The default value is nil.

• :index (term/0) - Selects the index (0-based) matched candidate. The default value is nil.

@spec filter(
  Cerberus.Locator.t(),
  keyword()
) :: Cerberus.Locator.t()

Adds locator filters to an existing locator.

Supported filters:

• has: locator
• has_not: locator
• visible: boolean

@spec label(String.t() | Regex.t()) :: Cerberus.Locator.t()

Builds a label locator.

@spec label(String.t() | Regex.t(), Cerberus.Options.locator_leaf_opts()) ::
  Cerberus.Locator.t()

@spec label(Cerberus.Locator.t(), String.t() | Regex.t()) :: Cerberus.Locator.t()

Builds or composes a label locator.

Supported forms:

• label(value, opts) for a leaf locator
• label(locator, value) to compose with an existing locator

@spec label(
  Cerberus.Locator.t(),
  String.t() | Regex.t(),
  Cerberus.Options.locator_leaf_opts()
) ::
  Cerberus.Locator.t()

Composes a label constraint into an existing locator with locator options.

@spec not_(Cerberus.Locator.t()) :: Cerberus.Locator.t()

Negates a locator.

@spec not_(Cerberus.Locator.t(), Cerberus.Locator.t()) :: Cerberus.Locator.t()

Composes left AND NOT(right).

@spec open_browser(arg) :: arg when arg: var

Writes the current rendered page snapshot to a temporary HTML file and opens it.

This is primarily useful for human debugging because it lets you inspect the rendered page in a real browser tab.

For callback-based DOM inspection in-process (for example, by AI tooling), see render_html/2.

@spec open_tab(arg) :: arg when arg: var

Opens a new tab for browser sessions and returns the updated session.

@spec or_(Cerberus.Locator.t(), Cerberus.Locator.t()) :: Cerberus.Locator.t()

Composes two locators with logical OR (union).

Action operations still require a unique final target at execution time.

@spec placeholder(String.t() | Regex.t()) :: Cerberus.Locator.t()

Builds a placeholder locator.

@spec placeholder(String.t() | Regex.t(), Cerberus.Options.locator_leaf_opts()) ::
  Cerberus.Locator.t()

@spec placeholder(Cerberus.Locator.t(), String.t() | Regex.t()) ::
  Cerberus.Locator.t()

Builds or composes a placeholder locator.

Supported forms:

• placeholder(value, opts) for a leaf locator
• placeholder(locator, value) to compose with an existing locator

@spec placeholder(
  Cerberus.Locator.t(),
  String.t() | Regex.t(),
  Cerberus.Options.locator_leaf_opts()
) ::
  Cerberus.Locator.t()

Composes a placeholder constraint into an existing locator with locator options.

@spec refute_checked(arg, Cerberus.Locator.t()) :: arg when arg: var

Refutes that any element matched by locator is checked.

Options

• :visible - Chooses visible text only, hidden only, or both. The default value is true.

• :timeout (non_neg_integer/0) - Retries text assertions for up to this many milliseconds. The default value is 0.

• :count (term/0) - Requires exactly this many text matches. The default value is nil.

• :min (term/0) - Requires at least this many text matches. The default value is nil.

• :max (term/0) - Requires at most this many text matches. The default value is nil.

• :between (term/0) - Requires text match count to fall within an inclusive range. The default value is nil.

@spec refute_disabled(arg, Cerberus.Locator.t()) :: arg when arg: var

Refutes that any element matched by locator is disabled.

Options

• :visible - Chooses visible text only, hidden only, or both. The default value is true.

• :timeout (non_neg_integer/0) - Retries text assertions for up to this many milliseconds. The default value is 0.

• :count (term/0) - Requires exactly this many text matches. The default value is nil.

• :min (term/0) - Requires at least this many text matches. The default value is nil.

• :max (term/0) - Requires at most this many text matches. The default value is nil.

• :between (term/0) - Requires text match count to fall within an inclusive range. The default value is nil.

@spec refute_has(arg, Cerberus.Locator.t()) :: arg when arg: var

Refutes that content matched by locator exists.

Unscoped: refute_has(session, ~l"500 Internal Server Error"e)

Composed locator form: refute_has(session, and_(css("button"), text("Dangerous", exact: true)))

For explicit scope boundaries, use within/3.

@spec refute_has(arg, Cerberus.Locator.t(), Cerberus.Options.assert_opts()) :: arg
when arg: var

Refutes content exists.

Options

• :visible - Chooses visible text only, hidden only, or both. The default value is true.

• :timeout (non_neg_integer/0) - Retries text assertions for up to this many milliseconds. The default value is 0.

• :count (term/0) - Requires exactly this many text matches. The default value is nil.

• :min (term/0) - Requires at least this many text matches. The default value is nil.

• :max (term/0) - Requires at most this many text matches. The default value is nil.

• :between (term/0) - Requires text match count to fall within an inclusive range. The default value is nil.

@spec refute_path(arg, String.t() | Regex.t(), Cerberus.Options.path_opts()) :: arg
when arg: var

Refutes that the session path matches expected.

Options

• :exact (boolean/0) - Requires an exact path match unless disabled. The default value is true.

• :query (term/0) - Optionally validates query params as a subset map/keyword. The default value is nil.

• :timeout (non_neg_integer/0) - Retries path assertions for up to this many milliseconds. The default value is 0.

@spec refute_readonly(arg, Cerberus.Locator.t()) :: arg when arg: var

Refutes that any element matched by locator is readonly.

Options

• :visible - Chooses visible text only, hidden only, or both. The default value is true.

• :timeout (non_neg_integer/0) - Retries text assertions for up to this many milliseconds. The default value is 0.

• :count (term/0) - Requires exactly this many text matches. The default value is nil.

• :min (term/0) - Requires at least this many text matches. The default value is nil.

• :max (term/0) - Requires at most this many text matches. The default value is nil.

• :between (term/0) - Requires text match count to fall within an inclusive range. The default value is nil.

@spec refute_selected(arg, Cerberus.Locator.t()) :: arg when arg: var

Refutes that any element matched by locator is selected.

Options

• :visible - Chooses visible text only, hidden only, or both. The default value is true.

• :timeout (non_neg_integer/0) - Retries text assertions for up to this many milliseconds. The default value is 0.

• :count (term/0) - Requires exactly this many text matches. The default value is nil.

• :min (term/0) - Requires at least this many text matches. The default value is nil.

• :max (term/0) - Requires at most this many text matches. The default value is nil.

• :between (term/0) - Requires text match count to fall within an inclusive range. The default value is nil.

@spec refute_value(arg, Cerberus.Locator.t(), String.t() | Regex.t()) :: arg
when arg: var

Refutes that the current value of a form field matched by locator equals expected.

String values use exact matching. Regex values are matched against the current field value.

@spec refute_value(
  arg,
  Cerberus.Locator.t(),
  String.t() | Regex.t(),
  Cerberus.Options.assert_value_opts()
) :: arg
when arg: var

Refutes a form-field value.

Options

• :timeout (non_neg_integer/0) - Retries value assertions for up to this many milliseconds. The default value is 0.

• :checked (term/0) - Requires matched fields to be checked/unchecked. The default value is nil.

• :disabled (term/0) - Requires matched fields to be disabled/enabled. The default value is nil.

• :selected (term/0) - Requires matched fields to be selected/unselected. The default value is nil.

• :readonly (term/0) - Requires matched fields to be readonly/editable. The default value is nil.

• :count (term/0) - Requires exactly this many matched candidates. The default value is nil.

• :min (term/0) - Requires at least this many matched candidates. The default value is nil.

• :max (term/0) - Requires at most this many matched candidates. The default value is nil.

• :between (term/0) - Requires matched candidate count to fall within an inclusive range. The default value is nil.

• :first (boolean/0) - Selects the first matched candidate. The default value is false.

• :last (boolean/0) - Selects the last matched candidate. The default value is false.

• :nth (term/0) - Selects the nth (1-based) matched candidate. The default value is nil.

• :index (term/0) - Selects the index (0-based) matched candidate. The default value is nil.

@spec reload_page(arg, Cerberus.Options.reload_opts()) :: arg when arg: var

Reloads the current path, defaulting to / when the session has no current path.

@spec render_html(arg, Cerberus.Options.return_result_opts()) :: arg | LazyHTML.t()
when arg: var

@spec render_html(arg, (LazyHTML.t() -> term())) :: arg when arg: var

Renders the current page HTML.

This is primarily for debugging, and can be useful for AI-assisted workflows that need to inspect the entire DOM tree in-process.

Use either:

• callback form (render_html(session, fn lazy_html -> ... end)) to keep piping
• return_result: true (render_html(session, return_result: true)) to return LazyHTML

For human-oriented inspection in a browser, see open_browser/1.

Options

• :return_result (boolean/0) - When true, returns the computed value instead of the session. The default value is false.

@spec role(String.t() | atom()) :: Cerberus.Locator.t()

Builds a role locator.

@spec role(String.t() | atom(), Cerberus.Options.role_locator_opts()) ::
  Cerberus.Locator.t()

@spec role(Cerberus.Locator.t(), String.t() | atom()) :: Cerberus.Locator.t()

Builds or composes a role locator.

Supported forms:

• role(role_name, opts) for a leaf locator
• role(locator, role_name) to compose with an existing locator

@spec role(
  Cerberus.Locator.t(),
  String.t() | atom(),
  Cerberus.Options.role_locator_opts()
) ::
  Cerberus.Locator.t()

Composes a role constraint into an existing locator with locator options.

@spec scope(Cerberus.Locator.t(), Cerberus.Locator.t()) :: Cerberus.Locator.t()

Composes two locators with scope chaining (descendant query).

The right locator is resolved within each element matched by the left locator.

@spec select(arg, Cerberus.Locator.t()) :: arg when arg: var

Selects option text in a <select> field matched by locator.

Bare string/regex shorthand is not supported.

For multi-select fields, pass the full desired selection on every call (option: [~l"Elf"e, ~l"Dwarf"e]). Each select/3 call replaces the selection with the provided option value(s). Sigil examples: select(session, ~l"#race_select"c, option: ~l"Elf"e), select(session, ~l"race-select"t, option: ~l"Elf"e).

@spec select(arg, Cerberus.Locator.t(), Cerberus.Options.select_opts()) :: arg
when arg: var

Selects option text in a matched <select> field.

Options

• :option (term/0) - Required. Text locator (~l"..."e/text("...", exact: true)) or list of text locators to select; for multi-select inputs pass all desired values on each call.

• :exact_option (boolean/0) - Requires exact option-text matches unless disabled. The default value is true.

• :timeout (non_neg_integer/0) - Browser action timeout in milliseconds.

• :force (boolean/0) - Bypasses browser actionability checks before dispatching the action. The default value is false.

• :checked (term/0) - Requires matched selects to be checked/unchecked. The default value is nil.

• :disabled (term/0) - Requires matched selects to be disabled/enabled. The default value is nil.

• :selected (term/0) - Requires matched selects to be selected/unselected. The default value is nil.

• :readonly (term/0) - Requires matched selects to be readonly/editable. The default value is nil.

• :count (term/0) - Requires exactly this many matched candidates. The default value is nil.

• :min (term/0) - Requires at least this many matched candidates. The default value is nil.

• :max (term/0) - Requires at most this many matched candidates. The default value is nil.

• :between (term/0) - Requires matched candidate count to fall within an inclusive range. The default value is nil.

• :first (boolean/0) - Selects the first matched candidate. The default value is false.

• :last (boolean/0) - Selects the last matched candidate. The default value is false.

• :nth (term/0) - Selects the nth (1-based) matched candidate. The default value is nil.

• :index (term/0) - Selects the index (0-based) matched candidate. The default value is nil.

@spec session() :: Cerberus.Session.t()

Starts a default non-browser (:phoenix) session with default options.

@spec session(Cerberus.Options.session_common_opts()) :: Cerberus.Session.t()

@spec session(Plug.Conn.t()) :: Cerberus.Session.t()

@spec session(:phoenix) :: Cerberus.Session.t()

@spec session(:browser) :: Cerberus.Session.t()

Starts a non-browser (:phoenix) session.

This arity also accepts Plug.Conn and driver atoms:

• session(conn) seeds the new session from an existing conn.
• session(:phoenix) starts non-browser mode.
• session(:browser) starts browser mode with defaults.

Options

• :endpoint (term/0) - Endpoint module override.

• :conn (term/0) - Seed Plug.Conn for session state.

• :timeout_ms (non_neg_integer/0) - Default timeout in milliseconds.

@spec session(:phoenix, Cerberus.Options.session_common_opts()) ::
  Cerberus.Session.t()

@spec session(:browser, Cerberus.Options.session_browser_opts()) ::
  Cerberus.Session.t()

Starts a browser session.

Browser context defaults can be configured globally via config :cerberus, :browser and overridden per session with:

• user_agent: "..."

• browser: [viewport: [width: ..., height: ...] | {w, h}]

• browser: [user_agent: "..."]

• browser: [popup_mode: :allow | :same_tab] to control window.open behavior

• browser: [init_script: "..."] or browser: [init_scripts: ["...", ...]]
• webdriver_url: "http://remote-webdriver:4444" to use a remote WebDriver endpoint without local browser/chromedriver launch.

Options

• :endpoint (term/0) - Endpoint module override.

• :timeout_ms (non_neg_integer/0) - Default timeout in milliseconds.

• :ready_timeout_ms (pos_integer/0) - Browser readiness timeout in milliseconds.

• :ready_quiet_ms (pos_integer/0) - Browser readiness quiet window in milliseconds.

• :user_agent (term/0) - Top-level user-agent override for browser session context.

• :browser (keyword/0) - Per-session browser overrides.

• :webdriver_url (term/0) - Remote WebDriver URL.

• :chrome_webdriver_url (term/0) - Remote Chrome WebDriver URL.

• :chrome_binary (term/0) - Chrome binary path override.

• :chromedriver_binary (term/0) - ChromeDriver binary path override.

• :chrome_args (term/0) - Additional Chrome launch arguments.

• :headless (boolean/0) - Headless browser toggle.

• :slow_mo (non_neg_integer/0) - Delay in milliseconds applied before each browser BiDi command.

• :chromedriver_port (pos_integer/0) - ChromeDriver port override.

• :chrome_startup_retries (non_neg_integer/0) - Chrome startup retry count.

• :chromedriver_log_path (term/0) - ChromeDriver log file path.

• :startup_log_tail_bytes (non_neg_integer/0) - Startup log tail byte limit.

• :startup_log_tail_lines (non_neg_integer/0) - Startup log tail line limit.

• :base_url (term/0) - Base URL override for remote runtime.

@spec sigil_l(
  String.t(),
  charlist()
) :: Cerberus.Locator.t()

Builds a locator using ~l.

Supported forms:

• ~l"text" exact text (default)
• ~l"text"e exact text
• ~l"text"i inexact text
• ~l"text"l label locator form
• ~l"ROLE:NAME"r role locator form
• ~l"selector"c CSS locator form
• ~l"test-id"t testid locator form (defaults to exact matching)

Rules:

• use at most one locator-kind modifier (r, c, l, or t)
• e and i are mutually exclusive
• r requires ROLE:NAME input

@spec submit(arg) :: arg when arg: var

Submits the active form (the most recently interacted form field).

@spec submit(arg, Cerberus.Locator.t()) :: arg when arg: var

Submits a matched submit-capable control using default options.

@spec submit(arg, Cerberus.Locator.t(), Cerberus.Options.submit_opts()) :: arg
when arg: var

Submits a matched submit-capable control.

Options

• :timeout (non_neg_integer/0) - Browser action timeout in milliseconds.

• :force (boolean/0) - Bypasses browser actionability checks before dispatching the action. The default value is false.

• :checked (term/0) - Requires matched submit controls to be checked/unchecked. The default value is nil.

• :disabled (term/0) - Requires matched submit controls to be disabled/enabled. The default value is nil.

• :selected (term/0) - Requires matched submit controls to be selected/unselected. The default value is nil.

• :readonly (term/0) - Requires matched submit controls to be readonly/editable. The default value is nil.

• :count (term/0) - Requires exactly this many matched candidates. The default value is nil.

• :min (term/0) - Requires at least this many matched candidates. The default value is nil.

• :max (term/0) - Requires at most this many matched candidates. The default value is nil.

• :between (term/0) - Requires matched candidate count to fall within an inclusive range. The default value is nil.

• :first (boolean/0) - Selects the first matched candidate. The default value is false.

• :last (boolean/0) - Selects the last matched candidate. The default value is false.

• :nth (term/0) - Selects the nth (1-based) matched candidate. The default value is nil.

• :index (term/0) - Selects the index (0-based) matched candidate. The default value is nil.

@spec switch_tab(Cerberus.Session.t(), Cerberus.Session.t()) :: Cerberus.Session.t()

Switches the active tab to target_session for browser sessions.

@spec testid(String.t()) :: Cerberus.Locator.t()

Builds a test-id locator.

@spec testid(String.t(), Cerberus.Options.locator_leaf_opts()) :: Cerberus.Locator.t()

@spec testid(Cerberus.Locator.t(), String.t()) :: Cerberus.Locator.t()

Builds or composes a test-id locator.

Supported forms:

• testid(value, opts) for a leaf locator
• testid(locator, value) to compose with an existing locator

@spec testid(Cerberus.Locator.t(), String.t(), Cerberus.Options.locator_leaf_opts()) ::
  Cerberus.Locator.t()

Composes a test-id constraint into an existing locator with locator options.

@spec text(String.t() | Regex.t()) :: Cerberus.Locator.t()

Builds a text locator.

@spec text(String.t() | Regex.t(), Cerberus.Options.locator_leaf_opts()) ::
  Cerberus.Locator.t()

@spec text(Cerberus.Locator.t(), String.t() | Regex.t()) :: Cerberus.Locator.t()

Builds or composes a text locator.

Supported forms:

• text(value, opts) for a leaf locator
• text(locator, value) to compose with an existing locator

@spec text(
  Cerberus.Locator.t(),
  String.t() | Regex.t(),
  Cerberus.Options.locator_leaf_opts()
) ::
  Cerberus.Locator.t()

Composes a text constraint into an existing locator with locator options.

@spec title(String.t() | Regex.t()) :: Cerberus.Locator.t()

Builds a title locator.

@spec title(String.t() | Regex.t(), Cerberus.Options.locator_leaf_opts()) ::
  Cerberus.Locator.t()

@spec title(Cerberus.Locator.t(), String.t() | Regex.t()) :: Cerberus.Locator.t()

Builds or composes a title locator.

Supported forms:

• title(value, opts) for a leaf locator
• title(locator, value) to compose with an existing locator

@spec title(
  Cerberus.Locator.t(),
  String.t() | Regex.t(),
  Cerberus.Options.locator_leaf_opts()
) ::
  Cerberus.Locator.t()

Composes a title constraint into an existing locator with locator options.

@spec uncheck(arg, Cerberus.Locator.t()) :: arg when arg: var

Unchecks a checkbox matched by locator.

Bare string/regex shorthand is not supported.

Use explicit locators like ~l"..."l, testid(...), css(...), or explicit text sigils (~l"..."e / ~l"..."i).

Sigil examples: uncheck(session, ~l"#subscribe"c), uncheck(session, ~l"subscribe-checkbox"t).

@spec uncheck(arg, Cerberus.Locator.t(), Cerberus.Options.check_opts()) :: arg
when arg: var

Unchecks a matched checkbox.

Options

• :timeout (non_neg_integer/0) - Browser action timeout in milliseconds.

• :force (boolean/0) - Bypasses browser actionability checks before dispatching the action. The default value is false.

• :checked (term/0) - Requires matched fields to be checked/unchecked. The default value is nil.

• :disabled (term/0) - Requires matched fields to be disabled/enabled. The default value is nil.

• :selected (term/0) - Requires matched fields to be selected/unselected. The default value is nil.

• :readonly (term/0) - Requires matched fields to be readonly/editable. The default value is nil.

• :count (term/0) - Requires exactly this many matched candidates. The default value is nil.

• :min (term/0) - Requires at least this many matched candidates. The default value is nil.

• :max (term/0) - Requires at most this many matched candidates. The default value is nil.

• :between (term/0) - Requires matched candidate count to fall within an inclusive range. The default value is nil.

• :first (boolean/0) - Selects the first matched candidate. The default value is false.

• :last (boolean/0) - Selects the last matched candidate. The default value is false.

• :nth (term/0) - Selects the nth (1-based) matched candidate. The default value is nil.

• :index (term/0) - Selects the index (0-based) matched candidate. The default value is nil.

@spec unwrap(arg, (term() -> term())) :: arg when arg: var

Executes a callback with driver-native escape-hatch data.

Browser sessions receive a constrained Cerberus.Browser.Native handle. Prefer public Cerberus operations and Cerberus.Browser.* helpers for stable flows.

@spec upload(arg, Cerberus.Locator.t(), String.t(), Cerberus.Options.upload_opts()) ::
  arg
when arg: var

Uploads a file into a matched file input.

Bare string/regex shorthand is not supported.

Use explicit locators like ~l"..."l, testid(...), css(...), or explicit text sigils (~l"..."e / ~l"..."i).

Sigil examples: upload(session, ~l"#avatar"c, "/tmp/avatar.jpg"), upload(session, ~l"avatar-upload"t, "/tmp/avatar.jpg").

Options

• :timeout (non_neg_integer/0) - Browser action timeout in milliseconds.

• :force (boolean/0) - Bypasses browser actionability checks before dispatching the action. The default value is false.

• :checked (term/0) - Requires matched file inputs to be checked/unchecked. The default value is nil.

• :disabled (term/0) - Requires matched file inputs to be disabled/enabled. The default value is nil.

• :selected (term/0) - Requires matched file inputs to be selected/unselected. The default value is nil.

• :readonly (term/0) - Requires matched file inputs to be readonly/editable. The default value is nil.

• :count (term/0) - Requires exactly this many matched candidates. The default value is nil.

• :min (term/0) - Requires at least this many matched candidates. The default value is nil.

• :max (term/0) - Requires at most this many matched candidates. The default value is nil.

• :between (term/0) - Requires matched candidate count to fall within an inclusive range. The default value is nil.

• :first (boolean/0) - Selects the first matched candidate. The default value is false.

• :last (boolean/0) - Selects the last matched candidate. The default value is false.

• :nth (term/0) - Selects the nth (1-based) matched candidate. The default value is nil.

• :index (term/0) - Selects the index (0-based) matched candidate. The default value is nil.

@spec visit(arg, String.t(), Cerberus.Options.visit_opts()) :: arg when arg: var

Visits path and returns the updated session.

@spec within(arg, Cerberus.Locator.t(), (arg -> arg)) :: arg when arg: var

Executes callback within a narrowed scope.

scope must be a Locator.t() (for example, ~l"#secondary-panel"c). Use closest/2 when scope should resolve to the nearest matching ancestor around a nested element (for example, a field wrapper around a label).

Use within/3 when you need explicit scope boundaries for mixed operations.

Browser note: when locator-based within/3 matches an <iframe>, Cerberus switches the query root to that iframe document. Only same-origin iframes are supported.