The Browser Flow monitor plugin
executes a list of steps in order. Each step has a type and a params
object. This page is the per-type reference.
All step types listed here are available on any plan that has
access to browser monitors. There’s no per-step entitlement.
Common params:
selector — CSS selector. Standard browser selector syntax
(#id, .class, [data-testid=foo], etc.).timeout_ms — how long to wait before giving up. Per-step
defaults shown; most interaction steps accept 0–30000 ms.force — bypass actionability checks. Use sparingly.- Boolean flags shown with a default apply that default when
omitted.
Navigation
| Type | Params | Effect |
|---|
navigate | url, wait_until?, timeout_ms? (max 60000) | Load a URL. wait_until is one of load (default), domcontentloaded, networkidle, commit. |
wait_for_navigation | url?, wait_until?, timeout_ms? (default 10000) | Pause until the next navigation completes. Optional URL match. |
check_url | url, wait_until?, assert_title?, assert_title_is_regex? (default false), assert_url?, assert_url_is_regex? (default false), timeout_ms? (default 30000, max 60000) | Navigate to a URL and optionally assert the resulting document title and/or final URL in one step. To assert the current URL without navigating, use assert_url. |
Interaction
| Type | Params | Effect |
|---|
click | selector, button? (left/right/middle, default left), timeout_ms?, force? | Click the matching element. |
double_click | selector, timeout_ms? | Double click. |
right_click | selector, timeout_ms? | Right click (opens context menu). |
hover | selector, timeout_ms? | Mouse hover. |
fill | selector, value, timeout_ms? | Type into an input. Replaces any existing value. |
clear_input | selector, timeout_ms? | Empty the input. |
select | selector, value, timeout_ms? | Pick an option from a <select>. |
check_checkbox | selector, checked? (default true), timeout_ms? | Check (or uncheck with checked: false) a checkbox. |
focus | selector, timeout_ms? | Move focus to the element. |
press_key | key, selector? | Send a keystroke. Enter, Tab, ArrowDown, etc. Selector optional. |
upload_file | selector, files (string), timeout_ms? | Provide a file for a file input. files is a path string — use a path that exists inside your runner image. |
drag_and_drop | source_selector, target_selector, timeout_ms? | Drag from source to target. |
scroll | x? (default 0), y? (default 0), selector? | Scroll the page by x/y pixels, or scroll within the element matched by selector. Positive y scrolls down. |
scroll_to_element | selector, timeout_ms? | Scroll until the element is in view. |
Waiting
| Type | Params | Effect |
|---|
wait | duration_ms (0–30000, default 1000) | Sleep. Use sparingly — prefer wait_for_element. |
wait_for_element | selector, state? (visible/hidden/attached/detached, default visible), timeout_ms? (default 5000) | Block until the element reaches the state. |
wait_for_api_response | url_pattern, status_code?, timeout_ms? (default 10000, max 60000) | Pause until a network response matching the URL pattern (and optional status code) arrives. |
Assertions
| Type | Params | Effect |
|---|
assert_text | text, selector?, is_regex? (default false), negate? (default false), case_sensitive? (default true) | Page (or scoped element) text contains the value. Set negate: true to pass when the text is absent. Matching is case-sensitive unless you turn it off. |
assert_title | title, is_regex? (default false) | Document title matches. |
assert_url | pattern, is_regex? (default false) | Current URL matches. |
assert_visible | selector, visible? (default true), timeout_ms? | Element is visible (or hidden with visible: false). |
assert_element_count | selector, count (≥0), operator? (eq/gt/lt/gte/lte, default eq) | Number of matching elements satisfies the comparison. |
assert_attribute | selector, attribute, value?, is_regex? (default false) | Attribute exists; if value is given, it must match. |
assert_css | selector, property, value, is_regex? (default false) | Computed CSS property matches. |
assert_cookie | name, value?, is_regex? (default false) | A cookie with that name exists; if value is given, it must match. |
assert_response | url?, status_code?, status_operator? (eq/neq/gt/lt/gte/lte/in/not_in, default eq), status_codes? (number array, for in/not_in), follow_redirects? (default true), expected_url?, expected_url_is_regex? (default false), timeout_ms? (default 10000) | Assert an HTTP response. With url set, waits for a response matching that pattern. With url omitted, asserts against the main-document response of the last navigate/check_url step — the reliable way to status-check the page itself. |
assert_response_time | max_ms (1–60000) | Wall-clock duration of the last navigate/check_url step is under the threshold. |
assert_redirect | url, method? (GET/HEAD/POST, default GET), expected_status? (301/302/303/307/308, default 302), expected_location?, expected_location_is_regex? (default false), timeout_ms? (default 10000) | Request the URL without following redirects and assert it answers with the expected redirect status and (optionally) Location target. |
assert_console_errors | level? (error/warning/all, default error), text?, is_regex? (default false), max_allowed? (default 0) | Fail when more than max_allowed console messages at the level have been logged. text filters which messages count. |
Browser state
| Type | Params | Effect |
|---|
set_cookie | name, value, domain?, path?, expires? (integer Unix timestamp, seconds) | Set a cookie before the flow continues. |
delete_cookies | name? | Delete the named cookie, or all cookies when name is omitted. |
set_local_storage | key, value | Write to localStorage. |
set_extra_headers | headers (JSON string) | Add headers to every subsequent request. Pass a JSON object as a string, e.g. {"X-Env": "synthetic"}. |
set_viewport | width (320–3840), height (240–2160) | Override viewport mid-flow. |
set_geolocation | latitude (−90–90), longitude (−180–180), accuracy? (≥0, default 100) | Spoof the geolocation API. |
set_permissions | permission (string), action? (grant/deny, default grant) | Pre-grant or pre-deny one browser permission (e.g. geolocation, notifications). One step per permission. |
emulate_device | device (string) | Use a built-in device preset (e.g. iPhone 13). |
block_request | url_pattern | Drop matching requests. Useful for testing without third-party calls. |
Auth helpers
| Type | Params | Effect |
|---|
http_basic_auth | username, password | Set HTTP Basic Auth credentials for subsequent navigation. |
http_request | url, method? (GET/POST/PUT/PATCH/DELETE, default POST), content_type? (application/json [default] / application/x-www-form-urlencoded / text/plain), headers? (JSON string), body?, store_response? (variable name), expected_status?, timeout_ms? (default 10000, max 60000) | Fire an out-of-band HTTP request from the browser context. store_response saves the response body into a variable; expected_status fails the step on a mismatch. Useful for token bootstrap. |
Tabs & frames
| Type | Params | Effect |
|---|
switch_to_tab | index?, url_contains?, timeout_ms? (default 5000) | Switch to a tab by zero-based index, or to the first tab whose URL contains the given string. |
close_tab | switch_to_index? (default 0) | Close the current tab and switch to the tab at the given index. |
switch_to_iframe | selector, timeout_ms? | Drop into an iframe. Subsequent selectors are scoped inside it. |
switch_to_main_frame | — | Pop back out of any iframe. |
Control flow
| Type | Params | Effect |
|---|
if_else | condition (element_visible / element_hidden / element_exists / variable_equals, default element_visible), selector?, variable_name?, variable_value?, negate? (default false), if_steps (Step[], max 20), else_steps (Step[], max 20) | Branch. Each branch can hold up to 20 nested steps. |
skip_steps_if | condition, selector?, variable_name?, variable_value?, negate? (default false), steps_to_skip (1–50) | Skip the next steps_to_skip steps if the condition holds. |
repeat_steps | times (1–100), step_count (1–50) | Repeat the preceding step_count steps so the block executes times times in total. There is no nested step array. |
Capture & misc
| Type | Params | Effect |
|---|
screenshot | label?, full_page? (default false), selector? | Save a screenshot artifact, optionally labelled or scoped to one element. |
store_value | variable_name, selector?, attribute?, expression? | Capture a value into a variable usable in later steps as {{variable_name}}. With selector alone it stores the element’s text; add attribute to store an attribute value; or use expression to store the result of a JavaScript expression. |
log_message | message, level? (info/warn/error, default info) | Annotate the step log. |
handle_dialog | action? (accept/dismiss, default accept), prompt_text? | Set the response to subsequent alert / confirm / prompt dialogs. |
execute_javascript | expression, timeout_ms? (default 5000) | Run a JavaScript expression in the page. To capture its result into a variable, use store_value with expression instead. |
Variables and secrets
Use {{name}} in any string param to substitute a variable.
Variables come from:
- Top-level
variables map on the monitor (visible in artifacts).
- Top-level
secrets map on the monitor (masked in artifacts).
store_value / store_response captures earlier in the flow.
Variables and secrets share one namespace — a secret named
password is referenced as {{password}}, exactly like a
variable. Secret values are masked in logs and artifacts.
Order matters — variables are resolved at step-execute time, so
store_value writes are visible to subsequent steps but not
earlier ones. An unresolved {{name}} is left as-is in the param.
Step caps
- A flow needs at least 1 step; there is no fixed cap on top-level
step count (the runtime cap bounds how much a flow can do).
- Max 20 steps nested inside any
if_else branch.
repeat_steps can repeat at most the preceding 50 steps
(step_count ≤ 50), up to 100 times (times ≤ 100).
Longer flows are usually a smell — split into multiple monitors
that share variables via the org’s secrets store.
