Predicate reference

A predicate declares what should be true. It is the argument to until on reticle_act_and_wait, and to predicate on reticle_assert and reticle_wait_for. Every predicate is { kind, ...fields }.

Not all predicates prove the same thing

Reticle grades them, and it will tell you when you have chosen a weak one. This is a real response from a text assertion:

{
  "verified": "yes",
  "pass": true,
  "advice": "This predicate only checks element/text presence, not an observable consequence. A locator healed to the wrong element (or a stale render) can satisfy it while the feature is broken. Prefer a { signal } or { net } assertion — or allOf it with one — so green means the feature actually worked."
}

Take the advice. element and text are convenient and weak; signal, state and net are what make a green trustworthy.

Kind	Grade	Proves
`signal`	strongest	The app declared success in its own words
`state`	strong	A registered store actually changed
`net`	strong	A specific request fired, with a countable cardinality
`route`	medium	Navigation happened
`console`	medium	Something logged, or nothing did
`element` / `text`	weak	Something rendered. A mock renders too

The leaves

element

{
  "kind": "element",
  "query": { "role": "dialog", "name": "Confirm" },
  "state": "visible"
}

query accepts role, name, text, label, placeholder, testid, alt, scope. state is one of visible, hidden, enabled, disabled, checked, expanded, focused, present. Add "absent": true to assert something is gone. The predicate for a removal, a dismissed toast, or a regression check.

text

{ "kind": "text", "contains": "Saved successfully", "visible": true }

Both contains and value are accepted. absent: true asserts the text is not present.

net

{ "kind": "net", "method": "POST", "urlContains": "/api/order", "status": 200 }

The one that catches the expensive bug:

{ "kind": "net", "method": "POST", "urlContains": "/api/order", "count": 1 }

Exactly one. Double-submit fails at two, and nothing on screen would have told you.

route

{ "kind": "route", "pathname": "/success" }

contains also works.

route asserts the route changed. Asserting the route you are already on always fails, and the response says so: expected: "a route change to /", assertion: "route.changed".

console

{ "kind": "console", "level": "error", "absent": true }

“The flow completed and logged nothing.” Worth attaching to most actions. Plenty of features work while quietly throwing.

signal

{ "kind": "signal", "name": "webhook:received", "dataMatches": { "provider": "stripe", "id": "*" } }

The app emitted a named signal via reticle.signal(). dataMatches is shallow JSON matching, and * means “present, any value”. Nothing outranks this. A 200 proves the server was reachable; a rendered row proves React ran. A signal is the application itself saying the thing succeeded. See instrumentation for how to emit them.

state

{ "kind": "state", "store": "app", "path": "deployments.0.status", "equals": "live" }

Walks a dot-path, with numeric array indices. equals takes a literal, or an operator pattern:

Operator	Meaning
`$gte` `$lte` `$gt` `$lt`	numeric comparison
`$contains`	substring or array membership
`$length`	collection size

Omit equals entirely to assert presence. This is the predicate that catches a UI-versus-store desync. A deploy that only looks shipped. Deterministically, in one call, with no model involved. On a miss it names the real store value and the keys that were available, so a failure is legible rather than a blind “no”.

animation

{ "kind": "animation", "name": "dialog-in", "completed": true }

Combinators

{
  "kind": "allOf",
  "predicates": [
    { "kind": "signal", "name": "auth:granted" },
    { "kind": "net", "method": "POST", "urlContains": "/api/login", "count": 1 },
    { "kind": "console", "level": "error", "absent": true }
  ]
}

{ "kind": "anyOf", "predicates": [ … ] }
{ "kind": "not", "predicate": { … } }

A combinator needs its own kind, and the children go in predicates. A bare { "allOf": [ … ] } does not parse, and neither does { "kind": "allOf", "allOf": [ … ] }.Reticle refuses the call rather than running half of it: “Nothing ran, the predicate was not evaluated, so no verdict was produced.” Better to be told than to get a green from an assertion that never executed.

allOf is the workhorse. “The signal fired and exactly one request went out and the console stayed clean” is a genuinely strong check, and it is one call. Each child reports its own evidence:

"evidence": [
  { "name": "auth:granted", "data": { "email": "admin@reticle.dev" } },
  { "matched": 1 },
  { "absent": true }
]

Timing and scoping

Field	Where	What it does
`timeout_ms`	`assert`, `wait_for`, `act_and_wait`	Wait up to N ms for it to become true
`since`	`net` and `console` leaves, and the call itself	Only consider events after this cursor

The since cursor comes from a prior reticle_act response. Use it whenever you are asserting something an action was supposed to cause. Without it, an assertion can pass on an event from two clicks ago.

Where predicates get used

Naming the consequence before the action is the whole point.

Tools

Beyond the loop

CLI

Libraries

Grammar

Long form

Predicate reference

Not all predicates prove the same thing

The leaves

element

text

net

route

console

signal

state

animation

Combinators

Timing and scoping

Where predicates get used

​Not all predicates prove the same thing

​The leaves

​element

​text

​net

​route

​console

​signal

​state

​animation

​Combinators

​Timing and scoping

Where predicates get used

Not all predicates prove the same thing

The leaves

element

text

net

route

console

signal

state

animation

Combinators

Timing and scoping