Assertions Reference

Assertions validate the outcome of a step. The AI agent includes assertions in QA plan steps when building plans via MCP tools. Each step can contain an assertions array with one or more assertion objects. All assertions in a step must pass for the step to be considered successful.

HTTP Assertions

These assertions apply to steps with the http_request action type.

status_code

Check that the response status code matches an exact value.

{ "type": "status_code", "expected": 200 }

Field	Type	Description
type	"status_code"	Assertion type identifier.
expected	number	The expected HTTP status code.

status_code_in

Check that the response status code is one of the allowed values.

{ "type": "status_code_in", "expected": [200, 201] }

Field	Type	Description
type	"status_code_in"	Assertion type identifier.
expected	number[]	An array of acceptable HTTP status codes.

json_path

Validate a value at a specific JSON path in the response body.

{ "type": "json_path", "path": "$.user.email", "expected": "alice@example.com" }

Field	Type	Description
type	"json_path"	Assertion type identifier.
path	string	A JSONPath expression pointing to the value to check.
condition	"exists" | "not_exists" | "contains"	(optional) The comparison mode. Omit for exact match.
expected	any	(optional when using exists/not_exists) The expected value.

Condition behavior:

• Omitted — Performs an exact equality check between the value at path and expected.
• "exists" — Passes if a value exists at the given path. The expected field is ignored.
• "not_exists" — Passes if no value exists at the given path. The expected field is ignored.
• "contains" — Passes if the string value at path contains expected as a substring.

Binary responses: json_path always fails on a binary response (e.g. an image or PDF download) with an explicit message. Use header, body_size, or body_hash instead.

header

Validate a response header value. Header names are matched case-insensitively.

{ "type": "header", "name": "Content-Type", "expected": "application/json" }

{ "type": "header", "name": "Location", "condition": "contains", "expected": "/users/" }

{ "type": "header", "name": "X-Request-Id", "condition": "exists" }

{ "type": "header", "name": "Set-Cookie", "condition": "matches", "expected": "session_id=" }

Field	Type	Description
type	"header"	Assertion type identifier.
name	string	Header name (case-insensitive).
condition	"equals" | "contains" | "exists" | "not_exists" | "matches"	(optional) Match condition. Defaults to "equals". "matches" interprets expected as a regular expression.
expected	string	(required for equals/contains/matches) The expected value or regex pattern.

body_size

Validate the byte length of the response body. Useful for verifying that file downloads are non-empty or fall within an expected range.

{ "type": "body_size", "expected": 12345 }

{ "type": "body_size", "condition": "between", "expected": [1000, 5000] }

{ "type": "body_size", "condition": "greater_than", "expected": 0 }

Field	Type	Description
type	"body_size"	Assertion type identifier.
condition	"equals" | "greater_than" | "less_than" | "between"	(optional) Comparison condition. Defaults to "equals".
expected	number | [number, number]	Numeric byte count. For "between", pass a [min, max] tuple (inclusive on both ends).

body_hash

Validate the hash digest of the response body. Useful for golden-file comparisons of generated reports (PDF, Excel, etc.).

{ "type": "body_hash", "expected": "<sha256 hex>" }

{ "type": "body_hash", "algorithm": "md5", "expected": "<md5 hex>" }

Field	Type	Description
type	"body_hash"	Assertion type identifier.
algorithm	"sha256" | "md5"	(optional) Hash algorithm. Defaults to "sha256".
expected	string	Expected hex digest (case-insensitive).

body_contains

Assert that the (text) response body contains a substring. Useful for HTML pages, plain-text webhooks, and other non-JSON text responses.

{ "type": "body_contains", "expected": "Welcome back" }

Field	Type	Description
type	"body_contains"	Assertion type identifier.
expected	string	Substring that must appear in the response body.

Binary responses: body_contains always fails on a binary response with an explicit message. Use body_size or body_hash instead.

Browser Assertions

These assertions apply to steps with the browser action type.

element_text

Check the text content of an element.

{ "type": "element_text", "selector": ".welcome-message" }

{ "type": "element_text", "selector": ".welcome-message", "contains": "Hello" }

Field	Type	Description
type	"element_text"	Assertion type identifier.
selector	string	CSS selector for the target element.
contains	string	(optional) Substring that the element’s text must contain. If omitted, asserts that the element has any text content.

element_visible

Assert that an element is visible on the page.

{ "type": "element_visible", "selector": "#main-content" }

Field	Type	Description
type	"element_visible"	Assertion type identifier.
selector	string	CSS selector for the target element.

element_not_visible

Assert that an element is not visible on the page.

{ "type": "element_not_visible", "selector": ".error-banner" }

Field	Type	Description
type	"element_not_visible"	Assertion type identifier.
selector	string	CSS selector for the target element.

url_contains

Assert that the current page URL contains a substring.

{ "type": "url_contains", "expected": "/dashboard" }

Field	Type	Description
type	"url_contains"	Assertion type identifier.
expected	string	Substring that the URL must contain.

title

Assert that the page title matches an exact value.

{ "type": "title", "expected": "Dashboard - My App" }

Field	Type	Description
type	"title"	Assertion type identifier.
expected	string	The expected page title.

screenshot

Capture a screenshot. This assertion always passes and is used for visual documentation.

{ "type": "screenshot", "name": "checkout-page", "description": "Final state of the checkout form" }

Field	Type	Description
type	"screenshot"	Assertion type identifier.
name	string	(optional) A name for the screenshot file.
description	string	(optional) A description of what the screenshot captures.

element_count

Assert the number of elements matching a selector.

{ "type": "element_count", "selector": ".cart-item", "expected": 3 }

Field	Type	Description
type	"element_count"	Assertion type identifier.
selector	string	CSS selector for the target elements.
expected	number	The expected number of matching elements.

element_attribute

Assert the value of an element’s attribute.

{ "type": "element_attribute", "selector": "#submit-btn", "attribute": "disabled", "expected": "true" }

Field	Type	Description
type	"element_attribute"	Assertion type identifier.
selector	string	CSS selector for the target element.
attribute	string	The attribute name to check.
expected	string	The expected attribute value.

cookie_exists

Assert that a cookie with the given name exists.

{ "type": "cookie_exists", "name": "session_id" }

Field	Type	Description
type	"cookie_exists"	Assertion type identifier.
name	string	The cookie name to check for.

cookie_value

Assert the value of a cookie.

{ "type": "cookie_value", "name": "theme", "expected": "dark", "match": "exact" }

Field	Type	Description
type	"cookie_value"	Assertion type identifier.
name	string	The cookie name.
expected	string	The expected cookie value.
match	"exact" | "contains"	(optional) Match mode. Defaults to "exact".

localstorage_exists

Assert that a key exists in localStorage.

{ "type": "localstorage_exists", "key": "auth_token" }

Field	Type	Description
type	"localstorage_exists"	Assertion type identifier.
key	string	The localStorage key to check for.

localstorage_value

Assert the value of a localStorage entry.

{ "type": "localstorage_value", "key": "locale", "expected": "en-US", "match": "exact" }

Field	Type	Description
type	"localstorage_value"	Assertion type identifier.
key	string	The localStorage key.
expected	string	The expected value.
match	"exact" | "contains"	(optional) Match mode. Defaults to "exact".