Writing specs

A suite is a Markdown file with YAML or JSON frontmatter and one top-level heading per test. Executable JavaScript frontmatter is rejected. Write either a goal with success conditions or exact steps with expected results.

Goal tests

---
suite: documentation smoke
baseUrl: https://example.com
tags: [smoke]
---

# Read the homepage

## Goal
Open the homepage and verify that it explains this example domain.

## Success
- Text: Example Domain
- URL: example.com

Goal execution requires a configured navigator profile. The agent chooses one action from a fresh observation at a time; the runtime independently checks the immutable success conditions. Jev selects ambiguous elements and does not replace the navigator. See Markdown goals and getting started.

Supported success conditions are Text:, Not text:, URL:, and Visual:. Text means normalized visible text. URL conditions use literal substring matching, not glob expressions. Pair negative checks with a positive observable result. Visual: homepage compares a reviewed baseline using exact image bytes; see baseline review.

Do not mix Goal/Success execution with Steps or hooks. Use approved Data keys for private input values; keep secrets in environment variables. A passing result proves the written acceptance conditions, not every unstated business rule.

Exact steps

Use this form to verify installation or exercise a deterministic journey without navigator inference:

---
suite: homepage smoke
baseUrl: https://example.com
---

# Read the homepage

## Steps
1. Open "/"

## Expected
1. Assert text "Example Domain"
1. Assert url "example.com"

Supported bounded instructions include:

• Open "/path"
• Click text "Save"
• Click role "button" named "Continue"
• Click action "primary checkout"
• Click element "Search"
• Fill field "Email" with "person@example.com"
• Fill field "Email" with env "USER_EMAIL"
• Assert text "Dashboard"
• Assert url "/dashboard"
• Wait for url "/complete"
• Wait for network "/api/orders" status 201
• Capture screenshot
• Capture visual checkpoint "homepage"

Exact unique visible names resolve locally. Ambiguous targets require configured selection and may be inconclusive. End the functional steps with an explicit text, URL, or visual check. Unsupported instructions are rejected before browser execution. Screenshot capture alone is not an assertion.

Engine boundaries

The bounded engine is the default. Goal agents can explicitly switch between observed frames and pages. Legacy scripted frame/popup commands, semantic Assert outcome, healing, browser traces, and journey recording are not translated into bounded contracts. See limits and authentication before migrating complex flows. The reference describes both engines; the migration guide explains the distinction.