Skip to main content

Captures and Assertions

Response Captures​

& body -> $VAR_NAME
& body.token -> $TOKEN := fallback
& body.items[0].name -> $VAR_NAME
& json(body.result.content[0].text).items[0].id -> $ITEM_ID
& header.content_type -> $CONTENT_TYPE
& status -> $STATUS

Use captures to thread values into later requests, assertions, and callbacks.

Dependency response captures are also supported:

&[Dependency Request].body -> $VAR_NAME
&[Dependency Request].status -> $STATUS

Dependency response captures require the referenced request to be declared in > requires: so the planner can guarantee the upstream result exists.

Append := default_value to a capture when you want a fallback if the selected path is missing.

Assertions​

^ & body.field == 'value'
^ & body.archivedAt == missing
^ & body.total === NUMBER
^ & json(body.result.content[0].text).items[0] ~= {"id":"123"}
^ $STATUS == 200

Supported operators include:

  • == and !=
  • ~=
  • ===
  • > >= < <=

Bare true, false, null, and missing are typed literals. Quoted values remain strings.

Use missing when the selected response path should be absent. Use null when the path should exist with an explicit JSON null value.

If you need a variable literally named missing, reference it explicitly as $missing.

Structural Matching​

~= supports:

  • substring or regex matching for strings
  • partial object matching for JSON object literals
  • unordered membership for array-vs-scalar JSON matches
  • unordered subset matching for JSON array literals

== and != compare structured JSON values structurally when both sides resolve to arrays or objects, and they can compare the built-in missing literal against absent paths.

Schema Validation​

=== validates the left-hand JSON value against a built-in or declared schema target.

  • the right-hand side must be a declared target name
  • the left-hand side must be a typed JSON operand

Use NUMBER when you want a concise built-in target for any JSON number.

Guards And Labels​

# The page loads
^ & status == 200

[ FEATURE_ENABLED == true ] ^ & body.user.id == "123"
[ & body.user === User ] ^ & body.user.role == "admin"
  • # ... labels the next assertion only
  • [predicate] guards assertions and fragment imports
  • guards may use === when the left-hand side resolves to typed JSON
  • schema guards return false on an ordinary schema mismatch
  • invalid schema targets and untyped left-hand operands still surface a real error

Blank lines or other request items break the label association. A false assertion guard marks that assertion as skipped.