English · 日本語
Scenario cookbook¶
Task-oriented recipes: each answers "I want to do X" with a complete, runnable scenario. scenarios is the grammar reference (every step kind, wait, and assertion); this page holds worked examples. Every recipe below is trimmed from a real file that the repo's own CI runs. The link under each recipe leads to the full file, including the parts trimmed here for focus.
Related: scenarios · selectors · network · Getting started
To run any of these yourself, first build the showcase app or serve the web demo (see Getting started):
uv run bajutsu run --scenario <path-to-file> --target showcase-swiftui --backend ios --udid booted --no-erase
Navigate and assert a value changed¶
The simplest useful shape: land on a screen, act on one element, assert the result. This scenario is the
showcase's own guided tour. demos/tour/demo.sh runs it, then deliberately
breaks it twice: first an assertion, then a selector. A machine assertion catches the first break,
and triage diagnoses the second.
- name: favorite a horse
preconditions:
subject:
launch:
env: { SHOWCASE_UITEST: "1" }
steps:
- wait: { for: { id: stable.row.3 }, timeout: 10 }
- tap: { id: stable.row.3 }
- wait: { for: { id: horse.favorite }, timeout: 5 }
- tap: { id: horse.favorite }
expect:
- value: { sel: { id: horse.favorite.value }, equals: "on" }
Every wait before a tap is a condition wait, not a fixed sleep. Bajutsu polls until the
target id exists, or times out and fails loudly. Full file:
demos/showcase/scenarios/menu/tour.yaml.
Search and filter a list¶
Type into a field and assert the result count. The companion "no results" case matters as much as the happy path, so the recipe covers both.
- name: filter narrows the catalog
preconditions:
subject:
launch:
env: { SHOWCASE_UITEST: "1" }
steps:
- tap: { label: "Search", traits: [button] }
- wait: { for: { id: search.field }, timeout: 10 }
- type: { text: "Horse 3", into: { id: search.field } }
- wait: { for: { id: search.row.3 }, timeout: 5 }
expect:
- count: { sel: { idMatches: "search.row.*" }, equals: 1 }
- value: { sel: { id: search.count }, equals: "1" }
- exists: { id: search.results-empty, negate: true }
- name: no match shows the empty state
preconditions:
subject:
launch:
env: { SHOWCASE_UITEST: "1" }
steps:
- tap: { label: "Search", traits: [button] }
- wait: { for: { id: search.field }, timeout: 10 }
- type: { text: "zzz", into: { id: search.field } }
- wait: { for: { id: search.results-empty }, timeout: 5 }
expect:
- exists: { id: search.results-empty }
- count: { sel: { idMatches: "search.row.*" }, equals: 0 }
idMatches is a glob against the id, which lets a scenario assert "how many rows" without naming each one.
Full file (including the cross-platform id-candidate-list form):
demos/showcase/scenarios/search.yaml.
Grant a system permission dialog¶
A runtime permission prompt (notifications, location, …) is an out-of-process system alert, not
part of the app's own UI, so the iOS backend cannot tap it directly. A systemAlert entry in the
scenario's interrupts hands that one tap to the reactive alert guard. The guard watches for the
prompt and taps "Allow" through a deterministic native accessibility query, with no screenshot and
no model call, while every assertion around it stays machine-checked. Name the prompt you expect
and the choice to make on it: the guard answers no prompt that no entry names
(BE-0406,
BE-0473),
and the run resolves the button from the prompt and the pinned locale, so the file stays correct on a
Japanese Simulator too. An entry carries no vision instruction, since run reaches no model
(BE-0402).
- name: grant notification permission
tags: [permission, system]
preconditions:
subject:
launch:
env: { SHOWCASE_UITEST: "1" }
interrupts:
- systemAlert: notifications
choice: grant
steps:
- tap: { label: "Permissions", traits: [button] }
- wait: { for: { id: perm.requestNotif }, timeout: 10 }
- assert:
- value: { sel: { id: perm.notif.value }, equals: "notDetermined" }
- tap: { id: perm.requestNotif }
- wait: { for: { id: perm.notif.authorized }, timeout: 10 }
expect:
- value: { sel: { id: perm.notif.value }, equals: "authorized" }
A systemAlert entry is an alert handler, never an assertion. It never touches the pass/fail
verdict; it merely unblocks a step that would otherwise hang on an alert the iOS backend cannot see
into. On Android the same scenario runs with no prompt at all (the target config pre-grants the
permission), so the guard stays idle: one scenario, two platforms, no branching. Full file with the
platform-parity notes: demos/showcase/scenarios/permission.yaml.
Mock a network response¶
mocks intercepts a request in-protocol and answers it deterministically, with no real server and
no flaky network. request assertions confirm that the mocked call happened.
- name: log submit answered by a mock, toast appears and clears
preconditions:
subject:
launch:
env: { SHOWCASE_UITEST: "1" }
mocks:
- match: { method: POST, pathMatches: "/post$" }
respond: { status: 201, body: "{\"ok\":true}" }
steps:
- tap: { label: "Log", traits: [button] }
- wait: { for: { id: log.submit }, timeout: 10 }
- tap: { id: log.submit }
- wait: { for: { id: log.toast }, timeout: 4 }
- wait: { until: { gone: { id: log.toast } }, timeout: 5 }
- wait: { until: { request: { method: POST, path: /post, status: 201 } }, timeout: 6 }
expect:
- request: { method: POST, path: /post, status: 201 }
- value: { sel: { id: log.status }, equals: "done" }
wait: { until: { gone: … } } polls until an element disappears, which suits a transient toast
like this one. Arm a wait for something transient on the step right after the action that
triggers it, as above. A step boundary costs evidence capture (a screenshot and a tree read, which
on a loaded CI device can run past a second), so a wait reached one step later can find the toast
already gone. For the same reason the until: { request: … } wait sits last here: the toast
appears only once the response has landed, so the request wait is already satisfied when it runs. Full
file (the request also carries an Authorization header; sensitive headers are masked in captured
evidence by default, so this scenario needs no redact policy of its own for that):
demos/showcase/scenarios/network_mock.yaml.
Run the same scenario over a data table¶
data runs one scenario body once per row, each in its own clean environment, and substitutes
${row.*} tokens. Here the tokens appear in both the typed query and the asserted id, so each row
proves that the filter found exactly the horse it searched for.
- name: search finds the seeded horse
data:
- { q: "Horse 1", n: "1" }
- { q: "Horse 3", n: "3" }
- { q: "Horse 5", n: "5" }
preconditions:
subject:
launch:
env: { SHOWCASE_UITEST: "1" }
steps:
- tap: { label: "Search", traits: [button] }
- wait: { for: { id: search.field }, timeout: 10 }
- type: { into: { id: search.field }, text: "${row.q}" }
- wait: { for: { id: "search.row.${row.n}" }, timeout: 5 }
expect:
- value: { sel: { id: search.count }, equals: "1" }
- exists: { id: "search.row.${row.n}" }
Full file (with the cross-platform id-candidate-list form of each token):
demos/showcase/scenarios/data_driven.yaml.
Reuse a step sequence as a component¶
A component is a parameterized, reusable step sequence: a scenario DSL macro that the loader expands at load time, so the component never appears as its own step in the run result. Define it once:
# _components/search_for.yaml
params: [query]
steps:
- tap: { label: "Search", traits: [button] }
- wait: { for: { id: search.field }, timeout: 10 }
- type: { into: { id: search.field }, text: "${params.query}" }
Then call it from any scenario with use / with:
- name: search finds a horse by name
preconditions:
subject:
launch:
env: { SHOWCASE_UITEST: "1" }
steps:
- use: { component: _components/search_for.yaml, with: { query: "Horse 3" } }
- wait: { for: { id: search.row.3 }, timeout: 5 }
expect:
- value: { sel: { id: search.count }, equals: "1" }
Component files: demos/showcase/scenarios/menu/_components/search_for.yaml;
a caller: demos/showcase/scenarios/menu/features.yaml.
The same scenario shape on the web backend¶
Every recipe above is written against the iOS showcase, but nothing in the step/expect grammar is
iOS-specific. Only the selector's underlying attribute changes (accessibilityIdentifier becomes
the web's data-testid, through the same selector-resolution core). The web demo's own second
scenario shows the same shape: navigate, act repeatedly, assert a final value, with evidence capture on top.
scenarios:
- name: onboard, log in, and increment the counter three times
steps:
- tap: { id: onboarding.start }
- type: { text: "a@b.com", into: { id: auth.email } }
- type: { text: "pw", into: { id: auth.password } }
- tap: { id: auth.submit }
- wait: { for: { id: home.title }, timeout: 5 }
capture: [deviceLog, video]
- tap: { id: counter.increment }
- tap: { id: counter.increment }
- tap: { id: counter.increment }
expect:
- exists: { id: home.title }
- value: { sel: { id: counter.value }, equals: "3" }
Run it with uv run bajutsu run --scenario demos/web/scenarios/counter.yaml --target web --backend
web --config demos/web/demo.config.yaml (see the web track). Full file:
demos/web/scenarios/counter.yaml.
Where these come from¶
Every recipe on this page is a real scenario that the repo's own CI runs; none is
illustration-only. The showcase suite (demos/showcase/scenarios/)
has about 25 more covering gestures, multi-touch, device control, visual regression, relaunch/state
persistence, and more; showcase catalogs the identifiers each screen exposes. The web
demo (demos/web/scenarios/) and the web UI's own dogfooding suite
(demos/serve-ui/scenarios/) are worth a look too. The dogfooding
suite is itself a good example of testing a complex single-page app. For the full step/wait/assertion
grammar behind every recipe here, see scenarios; for the formal EBNF, see
dsl-grammar.