Skip to content

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's within loops back to Selector.
  • RequestMatch is shared by the request assertion, the until: { request } wait, and Mock.match.
  • Web, App, Group, and Component each nest a fresh Step list. App's own field is a bare bundleId string, not a Selector. App therefore has no edge into Selector, unlike Web's within.
  • ScenarioFile also reaches Component directly, since a file may declare its own components inline (§6.2).
  • The two control-flow steps nest Step lists too. If nests then/else under an Assertion condition, and ForEach nests steps under a Selector.

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 true and false are booleans. on, off, yes, and no stay strings. The deviation keeps the capturePolicy trigger key on: a key (not the boolean True) and keeps id and label values like on intact (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 config evidence.secrets and resolved from the environment by the run loop at action time (§6.4).
  • vars.*: runtime capture via extract (§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 use step calls it from the scenario's own setup, or from a target's hooks.setup in 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 former preconditions.setup prelude file. A scenario that must not run its targets' hooks.setup sets preconditions.inheritSetup: false.
  • secrets (declared in config as evidence.secrets — a list of environment-variable names): each declared name X is resolved from os.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). Unlike params.* / row.*, this namespace is resolved by the run loop, not at load.
  • tags + the --tag / --exclude CLI flags filter which scenarios run; exclude wins over include (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) -> str serializes back to YAML, dropping only fields the author never set and emitting alias keys (idMatches, inheritSetup, …). The output reloads cleanly — this is the round-trip record relies 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.