English · 日本語
Scenario DSL grammar reference¶
This page is the normative grammar of the scenario DSL (domain-specific language). It lists every production, type, default, and validation constraint. The grammar derives directly from the pydantic models in bajutsu/scenario/ (the models/ subpackage). The models set extra="forbid", so unknown keys are rejected.
scenarios is the authoring guide: how to write a scenario, with examples. This page is the language spec: what parses and what is rejected. The page also covers the templating and macro layer around the core grammar. That layer holds components, data-driven rows, and setup preludes.
Related: scenarios (authoring guide) · selectors (how selectors/assertions evaluate) · evidence · getting-started
1. Notation¶
The DSL is a tree of YAML nodes, so the grammar is written over the abstract structure (mappings / sequences / scalars), not a character stream.
| Form | Meaning |
|---|---|
X ::= … |
production: X is defined as … |
A \| B |
alternation: A or B |
T? (on a value) |
optional value |
{ k: T } |
a YAML mapping with key k of type T |
{ k?: T } |
key k is optional |
A & B |
a mapping carrying the keys of both A and B |
list(T) |
a YAML sequence whose items are T |
map(K, V) |
a YAML mapping from K to V |
"literal" |
an exact string (a key name or an enum value) |
<Name> |
a non-terminal (defined elsewhere on this page) |
Scalar terminals: string, integer, number (int or float), boolean (only true /
false — see §3), any (any YAML value).
Every mapping rejects keys it does not declare (_Model, scenario/models/_base.py).
2. Grammar at a glance¶
The reference graph below shows which non-terminal references which. It makes visible the recursion and sharing that the EBNF text states but does not show directly:
Selector'swithinloops back toSelector.RequestMatchis shared by therequestassertion, theuntil: { request }wait, andMock.match.Web,App,Group, andComponenteach nest a freshSteplist.App's own field is a barebundleIdstring, not aSelector.Apptherefore has no edge intoSelector, unlikeWeb'swithin.ScenarioFilealso reachesComponentdirectly, since a file may declare its own components inline (§6.2).- The two control-flow steps nest
Steplists too.Ifneststhen/elseunder anAssertioncondition, andForEachnestsstepsunder aSelector.
The diagram omits two kinds of element. The first is actions that carry only scalars and reference no shared non-terminal. Examples are relaunch, setLocation, push, http, setClipboard, foreground, and the remaining device / status-bar steps. The second is the golden assertion, whose payload is a bare path.
graph LR
SF["ScenarioFile"] --> SC["Scenario"]
SF -->|components| CMP["Component"]
SC -->|preconditions| PRE["Preconditions"]
SC -->|steps| ST["Step"]
SC -->|expect| AS["Assertion"]
SC -->|capturePolicy| CR["CaptureRule"]
SC -->|network| NET["Network"]
SC -->|mocks| MK["Mock"]
SC -->|redact| RD["Redact"]
SC -->|interrupts| IR["Interrupt"]
SC -->|setup| ST
SC -->|cleanup| AR["CleanupRule"]
AR -->|steps| ST
ST -->|"tap·doubleTap·longPress·<br/>type·swipe·pinch·rotate·<br/>select·clear·delete·<br/>selectOption·setPickerValue·<br/>drag·scroll·handleSystemAlert"| SEL["Selector"]
ST -->|wait| WT["Wait"]
ST -->|assert| AS
ST -->|use| CMP["Component"]
ST -->|group| GRP["Group"]
ST -->|web| WEB["Web"]
ST -->|app| APP["App"]
ST -->|capture| CT["CaptureToken"]
ST -->|if| IF["If"]
ST -->|forEach| FE["ForEach"]
ST -->|setMocks| MK
CMP -->|steps| ST
GRP -->|steps| ST
WEB -->|within| SEL
WEB -->|steps| ST
APP -->|steps| ST
IR -->|condition| AS
IR -->|steps| ST
IF -->|condition| AS
IF -->|"then·else"| ST
FE -->|sel| SEL
FE -->|steps| ST
SEL -->|within| SEL
WT -->|"for · until:gone"| SEL
WT -->|until:request| RM["RequestMatch"]
AS -->|"exists·enabled·<br/>disabled·selected"| SEL
AS -->|"value·label"| TM["TextMatch"]
AS -->|count| CM["CountMatch"]
AS -->|"request·requestSequence·<br/>responseSchema"| RM
AS -->|event| EM["EventMatch"]
TM --> SEL
CM --> SEL
CR -->|on| TR["Trigger"]
CR -->|capture| CT
NET -->|filter| NF["NetworkFilter"]
MK -->|match| RM
MK -->|respond| MR["MockResponse"]
The productions in full follow.
# ── Files ──────────────────────────────────────────────────────────────
# Two on-disk forms: a bare sequence of scenarios, or a mapping that also carries a file-level
# `description` and/or `schema` (the cross-version read gate, BE-0119; default 1, an older
# bajutsu rejects a higher declared version rather than misinterpret it). Only the mapping form
# can carry `components` — file-scoped components (§6.2), keyed by the bare name a `use` in this
# same file refers to them by.
ScenarioFile ::= list(<Scenario>)
| { schema?: integer, description?: string,
components?: map(string,<Component>), scenarios: list(<Scenario>) }
ComponentFile ::= <Component> # a single mapping (loaded separately)
# ── Scenario ───────────────────────────────────────────────────────────
Scenario ::= {
name: string, # required
description?: string, # authoring metadata; `run` never reads it
from?: string, # provenance: the natural-language goal `record` authored this from (BE-0044)
tags?: list(string), # default [] — selection (§6.4)
targets?: list(string | list(string)), # default [] — every target this scenario drives (BE-0428); each name a `targets.<name>` config unit. `run` launches each declared target and interleaves their steps in one deterministic run (§4). An inner list of ≥ 2 names is a device group whose members share one device (BE-0447)
primaryTarget?: string, # the target a step or top-level `expect` entry runs against when it omits `target` (BE-0436); must equal the first name of `targets` (the first member of the first group), the entry the runner already treats as primary (§4)
installs?: list(string), # default [] — device-group members that install and launch at the start beside the primary (BE-0447); every other member of a group of ≥ 2 is a later member, brought up by `installApp` + `foreground` (§4)
data?: list(map(string,string)),# inline rows ┐ XOR
dataFile?: string, # CSV path ┘ (§6.3)
preconditions?: <Preconditions>, # default {} — the target's `subject` / `run` overridden per scenario (BE-0452, BE-0470), and the device state (BE-0469)
setup?: list(<Step>), # default [] — setup phase run ahead of `steps`, reported apart from it (BE-0392); each declared target's `hooks.setup` precede these
steps: list(<Step>), # required
expect?: list(<Assertion>), # default [] — final checks
cleanup?: list(<CleanupRule>), # default [] — teardown rules run once the verdict exists (BE-0392); each declared target's `hooks.cleanup` follow these
capturePolicy?: list(<CaptureRule>), # default []
network?: <Network>,
mocks?: list(<Mock>), # default []
redact?: <Redact>,
permissions?: <Permissions>, # pre-launch OS permission state; default {}
interrupts?: list(<InterruptEntry>), # default [] — what the run clears on its own at an unpredictable point (BE-0314, BE-0473), layered over the target's `hooks.interrupts`
}
Component ::= { params?: list(string), steps: list(<Step>) }
# A handler the runner checks opportunistically wherever in the step sequence the matching screen
# surfaces, running `steps` to clear it (BE-0314). Free on a `wait`'s poll tick; every other
# non-`wait` step pays one extra read. `target` names the declared target the entry watches; omitted,
# it watches the primary target (BE-0438).
Interrupt ::= { condition: <Assertion>, steps: list(<Step>), target?: string }
# One `interrupts` list holds three forms, told apart by the key an entry writes (BE-0473): a screen in
# the app's own tree, an operating-system prompt the system-alert guard answers, and Apple's TipKit
# popover. An entry that mixes keys of two forms fails at load. The target's `hooks.interrupts` takes
# the same forms. Screen entries concatenate, the target's first; how the other two forms combine is
# under SystemAlertInterrupt and TipKitInterrupt below.
InterruptEntry ::= <Interrupt> | <SystemAlertInterrupt> | <TipKitInterrupt>
# One teardown rule (BE-0392): the outcome it answers, and the steps to run for that outcome. The
# outcome is the scenario's own machine-checked verdict, never a model call.
CleanupRule ::= { on: "always" | "success" | "failure", steps: list(<Step>) }
# ── Preconditions ──────────────────────────────────────────────────────
# `subject` takes the target's own group name (BE-0452, BE-0470). Each field overrides the same field of every target the
# scenario drives; `subject.launch.env` merges key by key and `subject.launch.args` appends. A field no
# driven target's platform has fails the run before any device work. The former `preconditions.run`
# fails at load and names each field's new home (BE-0473). A scenario declares no device condition: `runsOn` belongs
# to the target alone (BE-0469).
Preconditions ::= {
subject?: {
reinstall?: ("overwrite" | "clean" | "erase"), # weakest first; unset: the target's `subject.reinstall`, else "clean"; iOS and Android, plus "erase" on web (BE-0473)
launch?: {
env?: map(string,string), # default {} — merged over the target's `subject.launch.env`
args?: list(string), # default [] — appended after the target's; iOS only
deeplink?: string, # unset: the target's `subject.launch.deeplink`; iOS and Android
},
},
device?: { ios?: <IosDevice>, android?: <AndroidDevice> }, # keyed by destination; a block for an undriven platform has no effect
inheritSetup?: boolean, # default true — false skips every declared target's `hooks.setup`; their cleanup still runs
}
# The iOS device state a scenario applies; each field replaces the target's `runsOn.ios` value of the
# same name. `seedPhotos` paths resolve against the scenario file, and a merged, non-empty list needs
# an effective `subject.reinstall: erase`.
IosDevice ::= { locale?: string, seedPhotos?: list(string) }
# The Android device state a scenario applies; `seedPhotos` replaces the target's
# `runsOn.android.seedPhotos`. Paths resolve against the scenario file; no erase is needed.
AndroidDevice ::= { seedPhotos?: list(string) }
# ── SystemAlertInterrupt (the reactive system-alert guard's answers) ───
# The guard is on unless `run --no-system-alert-handling`; no scenario or target switches it off as a
# whole. It answers a prompt by a native SpringBoard query + tap on XCUITest (no model, reusing
# BE-0316; BE-0315), plus an in-tree tap for a prompt that query cannot see. An alert no entry names
# is reported on the blocked step's own failure, never guessed at (BE-0402, BE-0406). Per prompt, a
# scenario entry replaces the target's `choice` and inherits an omitted `frozenScreenTimeout`; other
# prompts from both lists apply. One prompt appears at most once per list (BE-0473).
SystemAlertInterrupt ::= {
systemAlert: notifications|tracking|paste|savePassword|localNetwork,
choice: grant|deny|leave, # leave: answer nothing, e.g. when the scenario's own handleSystemAlert step does
pollInterval?: number, # native poll cadence, seconds (default 1); scenario › --alert-poll-interval › target, smallest within a layer
frozenScreenTimeout?: number, # frozen-screen stop, seconds (default 10, 0 = off); a prompt raised in the app's own tree (savePassword)
}
# savePassword is guard-only: iOS raises it in-process, so the in-tree dismissal
# alone answers it and the handleSystemAlert step below rejects it (BE-0406)
# ── TipKitInterrupt (Apple's TipKit popover; iOS only) ─────────────────
# Off unless an entry asks for it, since a tip is sometimes the assertion's own subject. The
# scenario's entry wins over the target's; `run --ios-tipkit-handling` / `--no-ios-tipkit-handling`
# set every scenario's entry to dismiss / leave. At most one per list (BE-0473).
TipKitInterrupt ::= { tipKit: dismiss|leave }
Permissions ::= map(PermissionService, PermissionAction) # applied before the app launches
PermissionService ::= "location" | "camera" | "microphone" | "contacts"
| "photos" | "calendar" | "notifications"
PermissionAction ::= "grant" | "revoke"
# ── Step = exactly one Action + optional modifiers ─────────────────────
Step ::= <Action> & <StepMods>
StepMods ::= { capture?: list(<CaptureToken>), extract?: map(string, <Extract>), name?: string, from?: string, target?: string }
# `from`: provenance, the natural-language phrase `record` normalized this step from (BE-0044)
# `name` becomes a real filesystem path segment (the run's step_id, the editor's
# artifact lookup) — a path separator, or a bare "." / "..", is a load error
# `target`: which of `scenario.targets` this step runs against (BE-0428); its
# requirement depends on `len(scenario.target_names)` and on `scenario.primaryTarget`
# (§4). Rejected outright on a step
# nested inside a `web:` block, which always runs against the block's own
# resolved target
Extract ::= { sel: <Selector>, prop?: ("value"|"label"|"identifier") } # default "value"
Action ::=
{ tap: <Selector> }
| { tapPoint: { x: number, y: number } } # normalized 0..1 (top-left origin); vision fallback for a control absent from the tree (e.g. a no-id tab-bar tab)
| { doubleTap: <Selector> }
| { longPress: { sel: <Selector>, duration: number } }
| { type: { text: string, into?: <Selector>, submit?: boolean } } # submit default false
| { clear: { into: <Selector> } } # focus the field and remove its entire current content (web-context raises)
| { delete: { into: <Selector>, count: integer } } # focus the field and delete count characters from the end (count > 0; web-context raises)
| { select: { into: <Selector>, mode?: "all" } } # focus the field and select its content (mode default "all"; web-context raises; codegen emits the native XCUITest equivalent)
| { copy: {} } # copy the active selection to the clipboard (requires a prior select; web-context raises)
| { paste: { into: <Selector> } } # focus the field and paste the clipboard at the caret (web-context raises)
| { selectOption:{ sel: <Selector>, option: string } } # set a web <select> to the option with this value (web only; iOS/Android raise)
| { navigate: string } # load a URL resolved against baseUrl; http/https only (web only; BE-0464)
| { openUrl: string } # hand an absolute URL to the OS for the app the scenario drives; any scheme but javascript:/data:/file:; not inside web: (iOS and Android; BE-0487)
| { setPickerValue:{ sel: <Selector>, value: string } } # move a wheel-style picker to the row with this value (iOS and Android; sel addresses one wheel)
| { swipe: <Swipe> } # directional form scrolls; coordinate form is a raw drag
| { drag: <Drag> } # pointer-drag a grabbed element (handle / divider / slider), not a scroll
| { scroll: <Scroll> } # scroll (non-inertially) until `to` is on-screen, else fail at a bound (BE-0326)
| { back: {} } # navigate back (Android system key / iOS OS back button / web history)
| { pinch: { sel: <Selector>, scale: number } } # scale > 0 (>1 in, <1 out)
| { rotate: { sel: <Selector>, radians: number } } # >0 clockwise
| { handleSystemAlert: { sel: <Selector>, timeout: number } } # tap an iOS SpringBoard permission prompt (iOS/XCUITest only); sel accepts only label/labelMatches/index
| { handleSystemAlert: { prompt: notifications|tracking|paste|localNetwork, choice: grant|deny, timeout: number } } # same step, label resolved from the run's locale (BE-0320), or by position under an uncovered language (BE-0445); savePassword is not nameable here (BE-0406)
| { wait: <Wait> }
| { sleep: { seconds: number, reason: string } } # fixed pause: 0 < seconds <= 30, reason non-blank; the one exception to condition waits
| { assert: list(<Assertion>) }
| { relaunch: { env?: map(string,string), args?: list(string) } }
| { setLocation: { lat: number, lon: number } }
| { push: { payload: map(string,any) } } # APNs payload, e.g. {aps:{alert:"…"}}
| { http: { method?: string, url: string, headers?: map(string,string), body?: string, status?: integer, saveBody?: string, extractBody?: list({ var: string, path: string }) } } # method default GET; saveBody → vars.<name>; extractBody → vars.<var> per JSON path (BE-0440)
| { totp: { secret: string, into?: { var: string }, name?: string, minRemaining?: integer } } # RFC 6238 OTP → vars.<var> (secret is base32); name registers the secret for `otp` (into and/or name required); minRemaining 1–30 (needs into): wait for the next 30s window when fewer seconds are left (BE-0474)
| { otp: { from: string, into: { var: string }, minRemaining?: integer } } # current code of the generator a totp step registered as `from` → vars.<var>; minRemaining as for totp
| { email: { match: { to?: string, subject?: string, subjectMatches?: string }, extract: { var: string, bodyMatches: string }, timeout: number } } # poll mailbox → vars.<var>
| { generate: <Generate> } # a random or current-datetime value computed at run time → vars.<var> (BE-0377)
| { eval: <Eval> } # transform a held value through a fixed op vocabulary → vars.* (BE-0472)
| { background: {} } # Home button (backgrounds via SpringBoard, no terminate)
| { foreground: {} } # bring the app to the front, no terminate; an app that is not running launches as `relaunch` would and waits until ready (iOS and Android, BE-0447); the other half of background
| { installApp: { from: string, keepData?: boolean } } # install a later device-group member's build on the step's device; keepData default true (install over, data kept), false uninstalls first; launches nothing (BE-0447)
| { setPrimaryTarget: { target: string } } # from here on, an omitted `target` (step, `interrupts` entry, top-level `expect`) resolves to `target`; top-level `steps` only (BE-0447)
| { clearKeychain: {} } # reset saved passwords / certificates
| { clearClipboard: {} } # clear the pasteboard
| { setClipboard: { text: string } } # seed the clipboard with text (simctl pbcopy; BajutsuAndroid on Android), for paste flows
| { setMocks: list(<Mock>) } # replace the app's whole stub table mid-scenario ([] removes every stub); iOS/XCUITest with network on (BE-0365)
| { overrideStatusBar: { time?: string, batteryLevel?: integer, batteryState?: string, cellularBars?: integer, wifiBars?: integer } }
| { clearStatusBar: {} } # restore the live status bar
| { use: { component: string, with?: map(string,string) } } # macro (§6.2; no modifier but target)
| { group: <Group> } # named run of steps, folded in report.html (§6.2; no capture/extract; does not nest)
| { if: <If> } # conditional (no capture/extract)
| { forEach: <ForEach> } # loop (no capture/extract)
| { web: <Web> } # enter a WebView's DOM context (BE-0037; no capture/extract)
| { app: <App> } # launch an app the test target never started and drive its UI (iOS/XCUITest and Android/adb; no capture/extract)
| { manual: { label: string, bypass?: string } } # human takeover recorded during `record` (BE-0185); fails loudly at run time — no deterministic equivalent unless `bypass` is wired
Group ::= { name: string, steps: list(<Step>) } # both required, non-empty; compile-time macro, gone before `run` (§6.2)
If ::= { condition: <Assertion>, then: list(<Step>), else?: list(<Step>) }
ForEach ::= { sel: <Selector>, as: string, steps: list(<Step>) }
Web ::= { within: <Selector>, steps: list(<Step>) }
# `within` resolves natively to exactly one WKWebView host; nested `steps` address the
# normalized DOM (`data-testid` → Element.identifier), not the native accessibility tree.
App ::= { bundleId: string, steps: list(<Step>) }
# `bundleId` names any installed app, launched (or already running) with no cooperation from
# the test target; nested `steps` address that app's own accessibility tree. Control returns to
# whatever was active before the block once it ends, the same enter/leave contract as `Web`.
# `com.apple.springboard` names the Home Screen itself (edit mode, the widget gallery); its
# measured constraints — `erase`, a pinned `locale`, no tree rows for gallery search results —
# are in scenarios.md.
Swipe ::=
{ on: <Selector>, direction: ("up"|"down"|"left"|"right"), amount?: number } # selector form ┐ XOR
| { from: <Point>, to: <Point> } # coordinate form ┘
# amount (selector form only): travel as a fraction of the screen, 0 < amount ≤ 1; omitted = a small default fraction (0.125)
Drag ::= { on: <Selector>, direction: ("up"|"down"|"left"|"right"), amount?: number } # element-anchored pointer drag (BE-0227), amount as in Swipe
Scroll ::= { to: <Selector>, direction?: ("up"|"down"|"left"|"right"), within?: <Selector>, amount?: number, maxScrolls?: integer }
# scroll until `to`'s frame center is on-screen, else fail (BE-0326). direction = scroll direction (default "down"), the inverse of Swipe's finger direction.
# within: the scrollable container to gesture inside (default: the whole screen). maxScrolls: step bound before failing (default 15, > 0).
# amount: one step's travel as a fraction of the viewport, 0 < amount ≤ 1; omitted = 0.6. Sets where the loop starts, not its recovery floor (BE-0400).
Point ::= [ number, number ]
Generate ::=
{ random: <Random>, into: { var: string } } # a fresh value the scenario did not already have ┐ XOR
| { datetime: <Datetime>, into: { var: string } } # the current time, as text ┘
Random ::=
{ string: { length: integer, charset?: ("alnum"|"alpha"|"numeric"|"hex") } } # length > 0; charset default "alnum" ┐
| { int: { min: integer, max: integer } } # inclusive range, min ≤ max │ XOR
| { float: { min: number, max: number, precision?: integer } } # min ≤ max; precision ≥ 0 decimals │
| { uuid: {} } # a version-4 UUID ┘
Datetime ::= { format?: string, offsetSeconds?: integer, offsetMinutes?: integer, offsetHours?: integer, offsetDays?: integer, timezone?: string }
# format: a strftime pattern; omitted = ISO 8601 to the second. The four offsets are signed and additive.
# timezone: an IANA name (e.g. "America/Los_Angeles"); omitted = UTC. An unrenderable format or an unknown zone fails at load.
Eval ::= { from: string, ops: list(<EvalOp>), into: { var: string } | { vars: list(string) } }
# ops: non-empty; each runs on the previous result. The loader tracks string/list from `from` (a string) to the end.
# into.var: a list result is stored as compact JSON array text. into.vars: needs a list result; element i → vars[i],
# extra elements dropped, a shorter list fails the step. Names in vars are distinct.
EvalOp ::=
"trim" | "json" | "count" | "unique" | "reverse" | "sort" # bare names
| { split: string | { by: string, regex?: boolean } } # string → list; by non-empty
| { join: string } # list → string
| { filter: { matches: string | equals: string | contains: string | notEmpty: true, not?: boolean } } # exactly one predicate
| { pick: "first" | "last" | integer } # list → string; index ≥ 0
| { sort: ("asc"|"desc") | { order?: ("asc"|"desc"), numeric?: boolean } }
| { regex: { pattern: string, group?: integer } } # string → string; group default 0
| { replace: { find: string, with: string, regex?: boolean } } # string → string
| { substring: { start: integer, end?: integer } } # string → string; both ≥ 0
| { case: ("lower"|"upper") } # string → string
# A free-text or index argument may hold ${vars.*} / ${secrets.*}; it is checked after substitution instead of at load.
# sort's order, case, and the regex / not / numeric flags take literal values only.
# ── Selector (≥1 field; provided fields are AND-ed) ────────────────────
Selector ::= {
id?: string | list(string), # a list is an OR over candidates (BE-0221) — one shared scenario can carry every platform's spelling of an id; list the canonical (dotted) form first
idMatches?: string | list(string), # glob over the id (fnmatch, e.g. "list.row.*"); a list ORs candidates the same way as id
label?: string,
labelMatches?: string, # regex over the label
traits?: list(string),
value?: string,
within?: <Selector>, # restrict to a container's subtree
index?: integer, # pick the k-th match when intentionally non-unique
}
# ── Wait (exactly one of for / until) ──────────────────────────────────
Wait ::= { for: <Selector>, timeout: number }
| { until: <Until>, timeout: number }
Until ::= "screenChanged" | "settled"
| { gone: <Selector> }
| { request: <RequestMatch> }
# ── Assertions (exactly one kind per item) ─────────────────────────────
Assertion ::=
{ exists: <Selector> & { negate?: boolean } } # selector inline; negate default false
| { value: <TextMatch> }
| { label: <TextMatch> }
| { count: <CountMatch> }
| { enabled: <Selector> }
| { disabled: <Selector> }
| { selected: <Selector> }
| { request: <RequestMatch> }
| { event: <EventMatch> } # an analytics/telemetry event the app sent (BE-0048)
| { requestSequence: list(<RequestMatch>) } # ≥1 matcher; an ordered/aggregate set of matched exchanges
| { responseSchema: <ResponseSchemaMatch> } # validate a captured response body against a JSON Schema (BE-0048)
| { visual: <VisualMatch> }
| { clipboard: <ClipboardMatch> } # read-back of the device clipboard (simctl pbpaste; BajutsuAndroid on Android)
| { attribute: <AttributeMatch> } # an HTML attribute of one element, read on demand (web only; BE-0466)
| { golden: <GoldenMatch> } # compare the live element tree to a recorded golden file (BE-0006)
TextMatch ::= { sel: <Selector> } & ( {equals:string} | {contains:string} | {matches:string} )
CountMatch ::= { sel: <Selector> } & ( {equals:integer} | {atLeast:integer} | {atMost:integer} )
CountOp ::= ( {equals:integer} | {atLeast:integer} | {atMost:integer} ) # a count comparison with no selector — an EventMatch's multiplicity
ClipboardMatch ::= ( {equals:string} | {matches:string} ) # exactly one; matches is a regex
AttributeMatch ::= { sel: <Selector>, name: string } # name: a valid HTML attribute name, never lowercased
& ( {equals:string} | {contains:string} | {matches:string} | {absent:true} ) # exactly one
GoldenMatch ::= { path: string } # resolved against the golden context's base directory (BE-0006)
VisualMatch ::= { # pixel-compare the screen against a baseline image
baseline: string, # filename resolved inside --baselines (default: baselines/ beside the scenario)
element?: <Selector>, # scope the comparison to this element's frame (BE-0171; default: whole screen)
compare?: "exact" | "pixelmatch", # comparison engine (default: config or "exact"; BE-0165)
threshold?: number, # max allowed diff, % of pixels (default 0.0 = exact)
colorTolerance?: number, # per-pixel perceptual color tolerance, 0–1 (pixelmatch; default 0.1)
antialiasing?: boolean, # discount anti-aliased pixels from the diff (pixelmatch; default true)
exclude?: list(<ExcludeRegion> | <SelectorRegion>), # regions masked before comparing (status bar, clock, …)
}
ExcludeRegion ::= { x: number, y: number, w: number, h: number } # screenshot pixels
SelectorRegion ::= { selector: <Selector> } # mask the element's frame (BE-0171); ambiguous → fail, no match → no-op
Every `Assertion` variant above also carries an optional `target?: string` (BE-0428), which
names which of `scenario.targets` the check runs against. It is legal only on a top-level
`expect` entry — an `Assertion` reached through a `Step`'s inline `assert:` list or an `If`'s
`condition` already has its target fixed by the enclosing step, so `target` is rejected there
outright (§4).
RequestMatch ::= { # ≥1 of the match fields below
method?: string,
url?: string, # exact full URL (the endpoint)
urlMatches?: string, # regex/substring over the full URL
path?: string, # exact path (query ignored)
pathMatches?: string, # regex over the path
query?: DictMatch, # URL-decoded query parameters; values: string | operator map (BE-0463)
body?: DictMatch, # parsed JSON request body; values: any DictValue (BE-0463)
status?: integer,
bodyMatches?: string, # regex/substring over the request body
count?: integer, # assertion → exact count; wait → lower bound
}
DictMatch ::= map(string, DictValue) # non-empty; a key starting `$$` names a field starting `$`
DictValue ::= string # equals the JSON value's text form (quoted: no bare 1/true/null)
| { $matches?: string, $exists?: boolean } # operator map (≥1 operator)
| map(string, DictValue) # subset of a JSON object
| list(DictValue) # JSON array of the same length, element by element
EventMatch ::= { # ≥1 of an endpoint field (method/url/urlMatches/path/pathMatches), query, or body
method?: string,
url?: string,
urlMatches?: string,
path?: string,
pathMatches?: string,
query?: DictMatch, # same grammar as RequestMatch.query
body?: DictMatch, # same grammar as RequestMatch.body
count?: <CountOp>, # expected multiplicity (default: at least one)
}
ResponseSchemaMatch ::= { request: <RequestMatch>, schema: string } # `schema` resolved against the app's schemas dir
# ── Evidence capture ───────────────────────────────────────────────────
CaptureToken ::= <Kind> ( "." <Modifier> )?
Kind ::= "screenshot" | "elements" | "actionLog" | "deviceLog" | "network" | "video" | "appTrace" | "rawTree"
Modifier ::= "before" | "after" | "around" | "onError"
CaptureRule ::= { on: <Trigger>, capture: list(<CaptureToken>), from?: string }
# `from`: provenance, the instruction this evidence rule was normalized from (BE-0044)
Trigger ::= # exactly one of action / event / result
{ action: string, idMatches?: string } # idMatches only alongside action
| { event: "screenChanged" }
| { result: "failure" }
# ── Network / mocks / redact ───────────────────────────────────────────
Network ::= { filter?: { domains?: list(string) } }
Redact ::= { labels?: list(string), headers?: list(string), fields?: list(string), unmaskHeaders?: list(string) }
# unmaskHeaders: an explicit, visible opt-out releasing one of the credential-bearing headers
# (authorization, cookie, set-cookie, …) masked by default (BE-0130)
Mock ::= { match: <RequestMatch>, respond?: <MockResponse> } # match: request-side fields only
MockResponse ::= { status?: integer, headers?: map(string,string), body?: string, delayMs?: number }
Grammar vs. wiring. This page specifies what parses and validates. How completely each action is actuated by a given backend, and which evidence kinds are acquired where, is a separate question tracked in drivers and the architecture status table.
3. The lexical layer (YAML)¶
A scenario file is YAML, parsed by Bajutsu's loader (common/_yaml.py). The loader makes one deliberate
deviation from YAML 1.1:
- Only
trueandfalseare booleans.on,off,yes, andnostay strings. The deviation keeps thecapturePolicytrigger keyon:a key (not the booleanTrue) and keeps id and label values likeonintact (scenarios).
Scalars map as follows: YAML strings to string, YAML ints to integer, and ints or floats to number. A
<Point> is a two-element flow sequence [x, y].
4. Cardinality & mutual-exclusion constraints¶
Beyond shapes, the models enforce the rules below. Each rule is a model_validator, and a violation is a load
error. The table is the authoritative list of "exactly one", "at least one", and "not both" constraints.
| Construct | Rule | Source |
|---|---|---|
Selector |
≥ 1 field present | scenario/models/selector.py |
Step |
exactly one action key (tap … use); capture/name are modifiers, not actions |
scenario/models/steps.py |
Step.use |
no modifier but target — refuses capture / extract / name / from, which expansion would otherwise discard with no warning; expansion stamps target onto the steps it produces instead (BE-0446) |
scenario/models/steps/step.py |
Swipe |
exactly one form: {on,direction} or {from,to} — never mixed, never half-specified |
scenario/models/actions.py |
Pinch |
scale > 0 |
scenario/models/actions.py |
HandleSystemAlert |
sel restricted to label / labelMatches / index (rejects id/idMatches/traits/value/within) |
scenario/models/actions.py |
Wait |
exactly one of for / until |
scenario/models/assertions.py |
Sleep |
seconds a number > 0 and ≤ 30; reason not blank |
scenario/models/actions/sleep.py |
Assertion |
exactly one kind (exists … request … visual) |
scenario/models/assertions.py |
TextMatch (value/label) |
exactly one of equals / contains / matches |
scenario/models/assertions.py |
CountMatch (count) |
exactly one of equals / atLeast / atMost |
scenario/models/assertions.py |
ClipboardMatch (clipboard) |
exactly one of equals / matches |
scenario/models/assertions.py |
AttributeMatch (attribute) |
exactly one of equals / contains / matches / absent: true (absent: false is rejected); name a non-empty, valid HTML attribute name |
scenario/models/assertions/attribute_match.py |
RequestMatch |
≥ 1 of method/url/urlMatches/path/pathMatches/query/body/status/bodyMatches (count is not a match field); a query/body dictionary is non-empty and holds only quoted scalars, $matches/$exists operator maps, and (in body) nested maps and lists |
scenario/models/assertions.py |
EventMatch (event) |
≥ 1 of method/url/urlMatches/path/pathMatches/query/body |
scenario/models/assertions.py |
CountOp (event.count) |
exactly one of equals / atLeast / atMost |
scenario/models/assertions.py |
Assertion.requestSequence |
≥ 1 item | scenario/models/assertions.py |
Trigger (capturePolicy[].on) |
exactly one of action / event / result; idMatches only with action |
scenario/models/evidence.py |
Scenario |
data and dataFile not both |
scenario/models/scenario.py |
Scenario.targets |
no duplicate name across the whole list, nested or not (BE-0428); an inner list holds ≥ 2 names (BE-0447); target_names below is every declared name, flattened across groups (BE-0447) |
scenario/models/scenario/_targets.py |
Scenario.primaryTarget |
omitted, or equal to the first name of targets (the first member of the first group); rejected when targets is empty (BE-0436) |
scenario/models/scenario/_targets.py |
Scenario.installs |
every entry a declared target, none repeated; a group of ≥ 2 that does not hold the primary lists ≥ 1 of its members (BE-0447) | scenario/models/scenario/_targets.py |
installApp |
from names a later member (neither the primary nor in installs, in a group of ≥ 2) of the group holding the step's device; at most one top-level installApp per member; rejected inside web: / app:, and in an interrupts recovery with no explicit device once the scenario contains a setPrimaryTarget (BE-0447) |
scenario/models/scenario/_targets.py |
setPrimaryTarget |
target names a declared target; top-level steps only — rejected inside if, forEach, a target group, web:, app:, an interrupts entry, setup, or cleanup; a component's is valid when its use: / group: call is top-level, and expansion never stamps a caller's target onto it (BE-0447) |
scenario/models/scenario/_targets.py, scenario/expand.py |
Step.target / Assertion.target (expect only) |
omitted or matching the one entry when len(target_names) ≤ 1; required — including on an if/forEach/web wrapper, not only a leaf action — naming a declared target, when len(target_names) ≥ 2 and primaryTarget is unset; optional when len(target_names) ≥ 2 and primaryTarget is set, an omitted one running against the primary at every nesting depth (BE-0436) — the current primary, which a setPrimaryTarget step moves (BE-0447); rejected on a step nested inside web:, and on an Assertion reached through an inline assert: list, an if's condition, or an interrupts entry's condition (BE-0428) |
scenario/models/scenario/_targets.py |
Step.target on a use: / group: step |
optional at any len(target_names), even with no primaryTarget, and never resolved itself; one that is set must name a declared target. Expansion stamps it onto every step the call produces that omits one, and refuses a produced step naming a different target (BE-0446) |
scenario/models/scenario/_targets.py, scenario/expand.py |
Interrupt.target, and Step.target in an interrupts entry's steps |
optional at any len(target_names), regardless of primaryTarget: an omitted entry target watches the primary target, and an omitted recovery-step target runs on the entry's own target (or an enclosing if/forEach step's when that step names one); a value that is set follows the Step.target rule above for naming a declared target (BE-0438) |
scenario/models/scenario/_targets.py |
Interrupt.target, and Step.target in its steps, under targets.<name>.hooks.interrupts |
rejected — the entry already belongs to the target that config block configures (BE-0438) | config/schema/target_config.py |
| every mapping | no unknown keys (extra="forbid") |
scenario/models/_base.py |
exists is special: its selector is written inline (exists: { id: home.title }), and an
optional negate: true checks absence. The loader rewrites that into { sel, negate } before
validation (Exists._inline, scenario/models/assertions.py).
5. Defaults¶
Omitted optional keys take the values below, so a minimal scenario is just name plus steps.
| Field | Default |
|---|---|
Scenario.tags / expect / capturePolicy / mocks / interrupts / setup / cleanup |
[] |
Scenario.preconditions |
{} (every field falls through to the target, then the built-in default) |
Scenario.permissions |
{} (no pre-launch permission state applied) |
Preconditions.inheritSetup |
true (every declared target's hooks.setup runs ahead of the scenario's setup) |
Preconditions.subject.reinstall |
unset — the target's subject.reinstall, else clean; --erase raises it to erase, --no-erase lowers an erase to clean (BE-0473) |
Preconditions.subject.launch.args |
[] |
Preconditions.subject.launch.env |
{} |
systemAlert entries |
none (the guard is on but answers no prompt; an alert it meets is named on the blocked step's failure) |
tipKit entry |
none (the target's entry, else off — a tip is sometimes the assertion; iOS only) |
TypeText.submit |
false |
Exists.negate |
false |
MockResponse.status |
200 |
MockResponse.headers |
{} |
Component.params |
[] |
ScenarioFile.schema |
1 (BE-0119) |
A complete minimal scenario:
- name: opens home
steps:
- tap: { id: onboarding.start }
- wait: { for: { id: home.title }, timeout: 5 }
expect:
- exists: { id: home.title }
6. The templating + macro layer¶
A small substitution and expansion layer surrounds the core grammar. It runs at load time, before the deterministic run, so the runner sees nothing but plain, fully expanded scenarios.
6.1 ${namespace.key} interpolation¶
The implementation is bajutsu/interp.py. A token is ${namespace.key}, and whitespace inside the braces is
trimmed. Substitution is type-preserving at the edges:
- A string that is exactly one token (
"${row.qty}") becomes the raw bound value (e.g. a number stays a number). - A token embedded in a larger string is spliced in as text (
"item-${row.id}"). - A token whose namespace is not being substituted right now is left intact, so each layer fills only its own namespace.
The namespaces are:
params.*: component parameters (§6.2).row.*: data-driven rows (§6.3).secrets.*: declared via configevidence.secretsand resolved from the environment by the run loop at action time (§6.4).vars.*: runtime capture viaextract(§6.5).
6.2 Components (use → reusable steps)¶
A <Component> pairs a list of params with a list of steps that reference them as
${params.<name>}. A use step invokes the component and binds the params via with. A component
lives either in a file of its own (ComponentFile) or inline in the scenario file that calls it
(ScenarioFile.components, BE-0422):
# login.component.yaml — a component file
params: [email, password]
steps:
- type: { text: "${params.email}", into: { id: auth.email } }
- type: { text: "${params.password}", into: { id: auth.password } }
- tap: { id: auth.submit }
# a scenario file — a file-scoped component beside the scenarios that call it
components:
dismiss:
steps:
- tap: { id: banner.close }
scenarios:
- name: s
steps:
- use: { component: login.component.yaml, with: { email: "a@b.com", password: "pw" } }
- use: { component: dismiss }
The ref's own shape decides how it resolves. One component: field carries both forms, with no new
syntax. A ref holding a / or ending in .yaml / .yml is a path. A path ref resolves as a component
file against the referring scenario file's own directory, and stays confined to the suite root
(BE-0174).
Anything else is a bare name, which resolves in the calling file's own components: map. A bare name
that the map does not define is an error, never a fallback file read.
The map is scoped to one file. The loader reads it per file and never merges it across a suite
directory. A name declared in one file stays invisible to every other. Crossing into a component
file drops the map entirely. That file declares no components: of its own, so a bare use
inside one is always undefined. A file-scoped component's own steps, by contrast, expand in the
declaring file's scope. A file-scoped component may use another by bare name, or use a file by path.
Reuse that spans files stays the path ref's job.
expand_components (scenario/expand.py) replaces each use with the component's substituted
steps, recursively: a component may itself use another, to a depth of 25. The function raises on a
missing or unknown param, a residual ${params.*} referencing something undeclared, an undefined bare
name, or a reference cycle.
ComponentResolver (scenario/load_expanded.py) is the one place that binds a resolve to a file. The
resolver carries that file's map, the suite root, and the base directory refs resolve against, so run
and every device-free reader expand a file identically.
Expansion descends into every if / else branch, every forEach body, and every web: / app:
block. A use in a branch the run never takes thus still expands, and a broken one fails the load.
Because expansion is pure and compile-time, no use survives into the run, and determinism holds.
A use step takes one modifier alone: target. The loader refuses a use that also sets any of
capture / extract / name / from, because expansion replaces the whole step and would drop those
fields with no warning. Expansion carries target forward instead (BE-0446): it stamps the value onto
every produced step that omits one. The stamp descends through if / forEach bodies and nested use
calls, and stops at a web: / app: block. The loader accepts a produced step naming the same target.
A produced step naming a different target fails the load, and the error message names the component
chain.
group is use's local sibling. A Group carries name and steps alone — no params, no
separate file. The same expand() recursion in expand_components replaces a group step with
its own steps, in place. It tags each with report_group / report_group_id — internal fields,
not part of the authored grammar — so report.html can fold them back together
(reporting.md). expand() raises on a group reached while it is
already inside another group. This covers an inner group written directly, and one arriving
through a use call. A Scenario-level validator refuses a directly-nested group too — one
written inside another group's steps, or inside an if / forEach / web / app step's
nested steps — at load time. expand() also raises on a group a component carries into one of
those bodies. A group step's own target follows the use rule above.
6.3 Data-driven scenarios (data / dataFile)¶
A scenario with data (inline rows) or dataFile (a CSV path) expands into
one scenario per row, substituting ${row.<column>} (expand_data, scenario/expand.py). The two
keys are mutually exclusive. Each derived scenario is renamed "<name> [row N: col=val, …]" and
keeps the original preconditions, so every row reinstalls the app fresh and inherits the template's
subject.reinstall.
- name: search returns a result
data:
- { q: apple, expect: "1 result" }
- { q: banana, expect: "2 results" }
steps:
- type: { text: "${row.q}", into: { id: home.search }, submit: true }
expect:
- label: { sel: { id: home.status }, equals: "${row.expect}" }
6.4 Shared setup, secrets, and tag selection¶
- Shared setup: a login / navigation flow written once is a component (§6.2). A
usestep calls it from the scenario's ownsetup, or from a target'shooks.setupin config. A target's component resolves when the config loads, against the config file's directory. It must stay inside the suite root (BE-0174). BE-0452 removed the formerpreconditions.setupprelude file. A scenario that must not run its targets'hooks.setupsetspreconditions.inheritSetup: false. secrets(declared in config asevidence.secrets— a list of environment-variable names): each declared nameXis resolved fromos.environ[X]and bound to${secrets.X}, substituted into the executed step at action time (cli/commands/run.py,orchestrator/substitution.py_interp_step). The scenario keeps the${secrets.X}token, never the value, and the literal values are auto-masked in evidence (Redactor). Unlikeparams.*/row.*, this namespace is resolved by the run loop, not at load.tags+ the--tag/--excludeCLI flags filter which scenarios run;excludewins overinclude(select_scenarios,scenario/select.py).
6.5 Expansion order¶
The load pipeline (cli/commands/run.py) applies the layers deterministically, in this order:
load_scenarios # parse + validate against this grammar
→ select_scenarios # --tag / --exclude
→ expand_components # `use` → component steps (${params.*})
→ expand_data # one scenario per row (${row.*})
→ run # the deterministic loop sees only expanded scenarios
7. Validation & round-trip¶
load_scenarios(text) -> list[Scenario]validates against everything above; the top level must be a sequence of scenarios or a{description, scenarios}mapping, and any rule in §4 failing is a load error (scenario/load.py).dump_scenarios(scenarios) -> strserializes back to YAML, dropping only fields the author never set and emitting alias keys (idMatches,inheritSetup, …). The output reloads cleanly — this is the round-triprecordrelies on (scenario/serialize.py).
For the semantics behind the shapes — how a selector resolves to 0/1/2+ elements, how each assertion compares, how waits time out — see selectors and run-loop. To start writing scenarios by example, see scenarios.