assert

assert

Assert that the page is what you expect, with JavaScript that must return true.

MCP tool	assert
HTTP	POST /browser/assert

Like execute_script, except the answer has to be a boolean: return a comparison, not the thing itself - return !!document.querySelector('#total'), not the element. Anything else is refused.

It asks again until the answer is true or wait_timeout passes, so an assertion straight after a click does not have to know how long a route change takes. wait_timeout=0 asks once.

For a guard - something that must be true BEFORE the flow acts - set stable_for. Asking until true means EVENTUALLY true, and an app that paints its signed-in shell for a moment before redirecting to the login page satisfies 'am I signed in' during that moment. stable_for=1 makes the answer hold for a second before it counts. Both it and wait_timeout are in seconds.

Give message the sentence whoever reads the failure should see - in a flow it becomes the failing step's error, and a flow cannot continue past one. Without a message the failure names only the page it was false on.

Use it to make a flow say what must be true: the page it landed on, that a form saved, or that it should not run at all because you are already signed in.

Parameters

Name	Type	Required	Default
script	string	yes	—
message	string	no	—
url	string	no	—
wait_timeout	integer	no	30
stable_for	number	no	0

Every call names its session: an X-Session-Key header, or ?session=<name>. Sending both is refused. See Sessions.

Returns

Field	Type	Notes
asserted	boolean	Always true: a false assertion is an error, not a result.
script	string	The expression that was true.
stable_for	number	Present when a hold was asked for: the seconds the answer had to stay true, and did.
url	string	Current URL after the action.
title	string	Page title after the action.

Errors

Status	Means
400	The request cannot succeed as sent — a missing field, a value that was rejected, or a locator that matched nothing before the wait ran out. Do not retry it unchanged.
401	Missing or wrong bearer token.
404	No such browser session. It ended, the Grid reaped it, or the id was never real. Open a new one and retry.
500	Something failed that this server did not expect.
503	The Grid could not serve this — unreachable, or no free slot for a new browser. Worth retrying after a wait.

Over MCP the same failures arrive as a tool error.

Example

MCP

assert(script="…")

HTTP

curl -X POST $SELENIUM_FLOW/browser/assert \
  -H "Authorization: Bearer $TOKEN" \
-H "X-Session-Key: $SESSION" \
  -H 'Content-Type: application/json' \
  -d '{
    "script": "…"
  }'

---

← All actions · Installing · Deployment