WebTest AI Docs

WebTest AI by AssertHive is agent-ready browser automation for testing real user flows. Write the intent and observable success conditions in Markdown. A bounded navigator chooses the next browser action, while the runtime owns execution, safety, assertions, evidence, and the final verdict.

The current phase-one runtime is intentionally small: Markdown goals, Chromium through native CDP, deterministic browser assertions, optional model navigation, and Jev-assisted element selection when a page has ambiguous controls.

How the runtime works

Layer	Responsibility	What it does not do
Markdown contract	Defines the user goal, approved data, and success conditions.	It does not contain a click sequence or brittle locator.
Navigator model	Reads the goal and fresh browser observation, then proposes one bounded action.	It cannot change assertions, invent tools, or decide the verdict.
Jev selector	Chooses one element reference from fresh candidates when intent is ambiguous.	It does not plan the journey or operate the browser.
Runtime	Executes approved actions, checks assertions, records evidence, and reports PASS, FAIL, or INCONCLUSIVE.	It does not accept a model claim as proof.

Unique targets are resolved locally. Jev is called only when local resolution cannot safely identify one candidate. Every model decision, selector choice, browser action, and assertion is bounded and recorded.

Why this is agent-ready

Goals stay readable to people and agent factories.
Fresh observations reduce stale locator decisions.
Jev receives only the candidate set and intent needed for a bounded choice.
Same-origin, action, step, tool-call, model-call, candidate, and timeout limits prevent open-ended browser behavior.
Assertions are fixed by the Markdown contract and cannot be rewritten by the model.
Reports expose screenshots, observations, actions, selected references, model metadata, usage, and cost status.

How it relates to Cypress, Playwright, and Selenium

Cypress, Playwright, and Selenium are browser control and test-runner layers. WebTest AI adds a goal, agent, selector, policy, and evidence layer above browser execution. The bounded runtime uses native Chrome DevTools Protocol for its primary Chromium path and retains Playwright for multi-engine coverage and rich debugging.

Concern	Traditional automation	WebTest AI
Authoring	Code, selectors, and ordered steps	Markdown goal and success contract
Next action	Written by the test author	Selected by a configured navigator model within runtime bounds
Ambiguous controls	Locator disambiguation in test code	Fresh candidates ranked by Jev or a configured selector model
Truth	Assertions are coupled to the test implementation	Runtime assertions remain independent of model decisions
Evidence	Runner-specific traces and screenshots	Agent-readable evidence, model calls, tool calls, usage, and cost status

Try the Everyday Goods demo

The demo is a lightweight local shop with twelve Markdown goals covering search, cart state, checkout, delivery, validation, reload persistence, quantity, and scoped shipping and billing controls.

npm install
npx playwright install chromium
npm run demo

The default demo uses deterministic local fixtures. It runs the real browser protocol and reporting pipeline without a live model or billed tokens. Use it for repeatable protocol and report demonstrations.

To let an external navigator such as a Codex session choose actions while keeping Jev mocked for a controlled demo:

node src/cli/index.js demo session headed

For a configured navigator model and real Jev selector:

WEBTEST_AI_MODEL_CONFIG=examples/config/goal-agent-jev.config.json
TYPESAFE_API_KEY=your-key
npm run demo:live

Reports and cost

Each run produces an HTML report for people, an agent JSON report, a newline-delimited tool-call ledger, and a manifest linking the artifacts. Model usage and cost are shown when the provider returns token usage and the profile includes pricing. Missing usage remains explicitly unavailable. Subscription bridges such as an external Codex session may execute successfully without exposing billable token metadata.

Start here

Legacy intent-mode guides remain available for compatibility. New bounded Markdown goals should follow the getting-started and agent-workflows guides above.