Docs/SDK/Jest-Style Assertions

Jest-Style Assertions

Updated 2026-01-15 — Comprehensive guide to Sentience assertions: predicates, state-aware checks, retries, confidence gating, and optional vision fallback.

Think Jest for AI web agents. Take a browser snapshot (rendered DOM + layout), then evaluate predicates that return pass/fail with structured details.

Introduction

What is an assertion in Sentience?

In Sentience, an assertion is a predicate:

Input: AssertContext (current snapshot, current url, and stepId)
Output: AssertOutcome (passed, reason, details)

Two layers

Predicates are pure functions — they read snapshot state and return AssertOutcome. Runtime execution decides how and when to evaluate predicates (once vs retry, confidence gating, fallback, tracing).

Getting Started

Install

pip install sentienceapi

Quick start: assert that text exists

from sentience import AsyncSentienceBrowser
from sentience.agent_runtime import AgentRuntime
from sentience.verification import exists
from sentience.tracing import Tracer, JsonlTraceSink

async with AsyncSentienceBrowser() as browser:
    page = await browser.new_page()
    await page.goto("https://example.com")

    tracer = Tracer(run_id="demo-run", sink=JsonlTraceSink("trace.jsonl"))
    runtime = await AgentRuntime.from_sentience_browser(browser=browser, page=page, tracer=tracer)

    await runtime.snapshot()
    runtime.assert_(exists("text~'Example Domain'"), label="example_domain_visible", required=True)

Python keyword

assert is a Python keyword, so the Python API uses assert_ instead.

Using Assertions

Basic predicates

These predicates are for simple checks:

URL predicates:

Python: url_matches, url_contains
TypeScript: urlMatches, urlContains

Element predicates:

Python: exists, not_exists, element_count
TypeScript: exists, notExists, elementCount

Composition:

Python: all_of, any_of, custom
TypeScript: allOf, anyOf, custom

Composed predicate example

from sentience.verification import all_of, exists, url_contains

on_checkout = all_of(
    url_contains("/checkout"),
    exists("text~'Order summary'")
)
runtime.assert_(on_checkout, label="checkout_loaded", required=True)

State-Aware Assertions

These predicates are deterministic checks against element state extracted from the live DOM:

is_enabled / isEnabled — enabled/disabled
is_checked / isChecked — checked/unchecked
value_contains / valueContains — value equals/contains
is_expanded / isExpanded — expanded/collapsed

from sentience.verification import is_enabled, is_checked, value_contains

runtime.assert_(is_enabled("role=button text~'Continue'"), label="continue_enabled", required=True)
runtime.assert_(is_checked("role=checkbox name~'Accept terms'"), label="terms_checked", required=True)
runtime.assert_(value_contains("role=textbox name~'Email'", "@"), label="email_has_at_symbol")

Retrying Assertions with `.eventually()`

Sentience provides a fluent assertion handle:

.once() — evaluates a predicate once (same semantics as assert/assert_)
.eventually() — retries with fresh snapshots until success, timeout, or exhaustion

ok = await runtime.check(
    exists("role=button text~'Continue'"),
    label="continue_visible",
    required=True,
).eventually(timeout_s=10, poll_s=0.25)

Snapshot confidence gating + exhaustion

If you pass minConfidence / min_confidence, .eventually() can treat low-confidence snapshots as failures and resnapshot.

ok = await runtime.check(
    exists("text~'Payment method'"),
    label="payment_ready",
    required=True,
).eventually(
    timeout_s=15,
    poll_s=0.25,
    min_confidence=0.7,
    max_snapshot_attempts=3,
)

Snapshot exhaustion

If confidence stays below the threshold for maxSnapshotAttempts, the assertion ends with reason_code = "snapshot_exhausted" and includes snapshot.diagnostics for debugging.

Optional vision fallback (last resort)

After snapshot_exhausted, you can optionally provide a vision-capable LLMProvider and let Sentience ask a strict YES/NO verifier question using a screenshot.

ok = await runtime.check(
    exists("text~'Order confirmed'"),
    label="order_confirmed",
    required=True,
).eventually(
    min_confidence=0.8,
    max_snapshot_attempts=2,
    vision_provider=llm,  # must supports_vision() and generate_with_image(...)
)

Vision is last resort

The verifier question is derived from the assertion label. Vision is only used after structured snapshot attempts are exhausted — never by default.

Setup and Teardown

Jest uses beforeAll/beforeEach/afterEach/afterAll. In Sentience, the idea is the same: create a browser + runtime once, snapshot as needed, then close.

# pytest-asyncio example
import pytest
from sentience import AsyncSentienceBrowser
from sentience.agent_runtime import AgentRuntime
from sentience.tracing import Tracer, JsonlTraceSink
from sentience.verification import exists

@pytest.fixture
async def runtime():
    tracer = Tracer(run_id="pytest-run", sink=JsonlTraceSink("trace.jsonl"))
    async with AsyncSentienceBrowser() as browser:
        page = await browser.new_page()
        rt = await AgentRuntime.from_sentience_browser(browser=browser, page=page, tracer=tracer)
        yield rt, page

@pytest.mark.asyncio
async def test_homepage_renders(runtime):
    rt, page = runtime
    await page.goto("https://example.com")
    await rt.snapshot()
    rt.assert_(exists("text~'Example Domain'"), label="example_domain_visible", required=True)

Guides

Use `AgentRuntime`

AgentRuntime is the recommended place to run assertions because it:

keeps the latest snapshot as assertion context
emits trace events (useful for debugging / Studio)
provides .check().eventually() for robust "wait until true" verification

When to use basic vs state-aware assertions

Use basic assertions for "presence/absence/count/url" checks.
Use state-aware assertions when you need deterministic checks of element state (enabled/checked/value/expanded) that commonly changes in SPAs.

How to read failures (reason codes + suggestions)

When an assertion fails, Sentience includes structured details:

reason_code (e.g. no_match, state_mismatch, snapshot_low_confidence, snapshot_exhausted)
nearest_matches (best-effort suggestions when a selector fails)

FAQ

Jest also has snapshot testing — how is that different from a Sentience snapshot?

Short answer

Jest snapshots freeze output. Sentience snapshots model interactive state. They solve different problems, even though they share the word "snapshot".

What Jest snapshot testing is

Jest snapshots are essentially golden files:

serialized React component trees
HTML strings, JSON responses, text output
captures a static representation
answers: "Did this output change?"

Jest snapshot characteristics:

Static: captures a representation at one point in time
Text/JSON-based: stored as serialized snapshots
Comparison-oriented: meant to diff over time
Great for regression detection
Not interaction-aware: no notion of timing, user actions, or success

What a Sentience snapshot is

A Sentience snapshot is a runtime perception frame of a live browser:

rendered DOM after hydration
semantic roles + names
UI state (enabled, checked, expanded, value)
geometry + ordering
grouping (lists, cards, feeds)
stability diagnostics (confidence, quiet time)

Sentience snapshot characteristics:

Live: gathered from a running page, not static HTML
Semantic: role/name/text-focused, not raw HTML strings
Spatial/ordinal-aware: uses layout and ordering
Repeated during execution
Designed for verification: evaluate assertions, not diff against golden files

Key difference

Aspect	Jest snapshot	Sentience snapshot
Purpose	Detect output changes	Enable reasoning & verification
Lifecycle	Stored & diffed	Ephemeral, per-step
Input	Render output / strings	Live browser state
Stability	Assumes determinism	Measures instability
Used for	Regression testing	Agent execution + QA verification
Handles SPAs	Poorly	Natively
Geometry / ordinality	No	Yes

Do I need `.eventually()` for every assertion?

No. A good rule of thumb:

Use single-shot assert/assert_ for stable, immediate checks (URL checks, "element exists", etc.)
Use .check(...).eventually() for anything that depends on async UI timing (SPAs, loading states, transitions, network-backed components)

Why does `.eventually()` sometimes fail with `snapshot_low_confidence` / `snapshot_exhausted`?

If you set minConfidence / min_confidence, the runtime treats low-confidence snapshots as unreliable and will resnapshot. After maxSnapshotAttempts / max_snapshot_attempts, it stops with snapshot_exhausted to avoid infinite retries and surfaces snapshot.diagnostics in details to help you debug instability.

Agent Runtime — Runtime verification support for agent loops
AI-Driven QA — Enterprise QA workflows with Sentience assertions

Agent Runtime

AI-Driven QA