English · 日本語
シナリオ DSL 文法リファレンス¶
このページはシナリオ DSL(ドメイン固有言語)の 規範的な文法です。すべての生成規則、型、既定値、検証制約を扱います。文法は、bajutsu/scenario/(models/ サブパッケージ)の pydantic モデルから直接導いています。モデルは extra="forbid" を設定しているので、未知キーは拒否されます。
scenarios はオーサリングガイドで、例つきでシナリオの書き方を説明します。このページは言語仕様で、何がパースされ、何が拒否されるかを定めます。コア文法を取り巻くテンプレートとマクロ層、すなわちコンポーネント、データ駆動の行、setup プレリュードも扱います。
関連: scenarios(オーサリングガイド) · selectors(セレクタ/アサーションの評価) · evidence · getting-started
1. 記法¶
DSL は YAML ノードの木なので、文法は文字列ではなく 抽象構造(マッピング / シーケンス / スカラ)の上で記述します。
| 形 | 意味 |
|---|---|
X ::= … |
生成規則: X を … と定義する |
A \| B |
選択: A または B |
T?(値に付く) |
省略可能な値 |
{ k: T } |
キー k(型 T)を持つ YAML マッピング |
{ k?: T } |
キー k は省略可能 |
A & B |
A と B 両方のキーを持つマッピング |
list(T) |
要素が T の YAML シーケンス |
map(K, V) |
K → V の YAML マッピング |
"literal" |
厳密な文字列(キー名または列挙値) |
<Name> |
非終端記号(このページの別の場所で定義) |
スカラ終端は string、integer、number(整数か浮動小数)、boolean(true / false のみ。§3 を参照)、any(任意の YAML 値)です。
どのマッピングも、宣言していないキーは拒否します(_Model, scenario/models/_base.py)。
2. 文法の全体像¶
以下の 参照グラフは、どの非終端がどれを参照するかを示します。下の EBNF テキストが述べていても直接には見えない再帰と共有が、これで見て取れます。
SelectorのwithinがSelector自身へループします。RequestMatchは、requestアサーション、until: { request }待機、Mock.matchの三箇所が共有します。Web、App、Group、Componentは、それぞれ新しいStepの列を内側に持ちます。App自身のフィールドは素のbundleId文字列でありSelectorではないので、Appは、WebのwithinのようなSelectorへの辺を持ちません。ComponentへはScenarioFileからも辺が伸びます。シナリオファイルが自分のコンポーネントをインラインで宣言できるためです(§6.2)。- 制御フローの 2 つのステップも、
Stepの列を内側に持ちます。IfはAssertionの条件のもとにthen/elseを、ForEachはSelectorのもとにstepsを持ちます。
図は 2 種類の要素を省略しています。1 つめは、スカラのみを持ち共有の非終端を参照しないアクションです(relaunch、setLocation、push、http、setClipboard、foreground、その他デバイス / ステータスバー系のステップ)。2 つめは、ペイロードが単純なパスだけの golden アサーションです。
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"]
生成規則の全体を次に示します。
# ── ファイル ────────────────────────────────────────────────────────────
# ディスク上の形式は2つあります。シナリオの素のシーケンス、またはファイル単位の `description` や
# `schema`(クロスバージョン読み込みのゲート、BE-0119。既定は 1。より新しいバージョンを宣言した
# ファイルは、誤解釈するのではなく古い bajutsu 側が拒否します)も持てるマッピングです。
# `components` を持てるのはマッピング形式だけです。ファイルスコープのコンポーネント(§6.2)を、
# 同じファイル内の `use` が参照する素の名前をキーにして並べます。
ScenarioFile ::= list(<Scenario>)
| { schema?: integer, description?: string,
components?: map(string,<Component>), scenarios: list(<Scenario>) }
ComponentFile ::= <Component> # 単一マッピング(別ロード)
# ── Scenario ───────────────────────────────────────────────────────────
Scenario ::= {
name: string, # 必須
description?: string, # オーサリング用メタデータ。run は読まない
from?: string, # 由来: record がこのシナリオを起こした元の自然言語のゴール(BE-0044)
tags?: list(string), # 既定 [] — 選択(§6.4)
targets?: list(string | list(string)), # 既定 [] — このシナリオが操作するすべてのターゲット(BE-0428)。各エントリは `targets.<name>` の config ユニットを指す。run は宣言された各ターゲットを起動し、そのステップを1回の決定的な実行の中で組み合わせて実行する(§4)。2つ以上の名前を持つ内側の list は、メンバーが1台のデバイスを共有するデバイスグループ(BE-0447)
primaryTarget?: string, # `target` を省略したステップとトップレベルの `expect` エントリが走る先(BE-0436)。runner がすでに主ターゲットとして扱う `targets` の最初の名前(最初のグループの最初のメンバー)と一致しなければならない(§4)
installs?: list(string), # 既定 [] — プライマリと並んで開始時にインストールして起動するデバイスグループのメンバー(BE-0447)。2つ以上のメンバーを持つグループのそれ以外のメンバーは後から入るメンバーで、`installApp` と `foreground` が立ち上げる(§4)
data?: list(map(string,string)),# インライン行 ┐ XOR
dataFile?: string, # CSV パス ┘ (§6.3)
preconditions?: <Preconditions>, # 既定 {} — ターゲットの `subject` / `run` をシナリオごとに上書き(BE-0452、BE-0470)し、デバイスの状態を持つ(BE-0469)
setup?: list(<Step>), # 既定 [] — steps の前に独立したフェーズとして走るセットアップ(BE-0392)。宣言した各ターゲットの `hooks.setup` の後に連結される
steps: list(<Step>), # 必須
expect?: list(<Assertion>), # 既定 [] — 最終チェック
cleanup?: list(<CleanupRule>), # 既定 [] — 判定が出たあとに走るティアダウンのルール(BE-0392)。宣言した各ターゲットの `hooks.cleanup` はこの後に続く
capturePolicy?: list(<CaptureRule>), # 既定 []
network?: <Network>,
mocks?: list(<Mock>), # 既定 []
redact?: <Redact>,
permissions?: <Permissions>, # 起動前の OS 権限状態; 既定 {}
interrupts?: list(<InterruptEntry>), # 既定 [] — 予測できないタイミングで現れたものを run が自分で片付ける宣言(BE-0314、BE-0473)。ターゲットの `hooks.interrupts` に重ねる
}
Component ::= { params?: list(string), steps: list(<Step>) }
# 予測できないタイミングで現れる中断画面のハンドラです。ランナーは、ステップ列のどこで一致画面が現れても
# 機会をとらえて `condition` をチェックし、`steps` で解消します(BE-0314)。`wait` のポーリングの各回は
# 無料で済みますが、残りの `wait` 以外のステップは読み取りを 1 回余分に払います。`target` は、エントリが
# 監視する宣言済みターゲットを指定します。省略するとプライマリターゲットを監視します(BE-0438)。
Interrupt ::= { condition: <Assertion>, steps: list(<Step>), target?: string }
# 1 つの `interrupts` リストは 3 つの形を持ち、エントリが書くキーで区別します(BE-0473)。アプリ自身の
# ツリーにある画面、システムアラートガードが答える OS のプロンプト、Apple の TipKit の popover です。
# 2 つの形のキーを混ぜたエントリはロード時に失敗します。ターゲットの `hooks.interrupts` も同じ形を取ります。
# 画面のエントリは、ターゲットのものを先にして連結します。残る 2 つの形の重ね方は、後述の
# SystemAlertInterrupt と TipKitInterrupt に書きます。
InterruptEntry ::= <Interrupt> | <SystemAlertInterrupt> | <TipKitInterrupt>
# ティアダウンのルール 1 件です(BE-0392)。答える結末と、その結末のときに走らせるステップを組にします。
# 結末はシナリオ自身のマシンチェックされた判定であり、モデル呼び出しではありません。
CleanupRule ::= { on: "always" | "success" | "failure", steps: list(<Step>) }
# ── Preconditions ──────────────────────────────────────────────────────
# `subject` はターゲットと同じグループ名を使います(BE-0452、BE-0470)。各フィールドは、シナリオが動かす各ターゲットの
# 同じフィールドを上書きします。`subject.launch.env` はキーごとにマージし、`subject.launch.args` は追記します。
# 動かすどのターゲットのプラットフォームにもないフィールドは、デバイスを操作する前に run を失敗させます。
# 以前の `preconditions.run` はロード時に失敗し、各フィールドの移動先を示します(BE-0473)。シナリオは
# デバイスの条件を宣言しません。`runsOn` はターゲットだけが持ちます(BE-0469)。
Preconditions ::= {
subject?: {
reinstall?: ("overwrite" | "clean" | "erase"), # 弱い順。未設定はターゲットの `subject.reinstall`、なければ "clean"。iOS と Android、web は "erase" のみ(BE-0473)
launch?: {
env?: map(string,string), # 既定 {} — ターゲットの `subject.launch.env` にマージ
args?: list(string), # 既定 [] — ターゲットの引数の後ろに追記。iOS のみ
deeplink?: string, # 未設定はターゲットの `subject.launch.deeplink`。iOS と Android
},
},
device?: { ios?: <IosDevice>, android?: <AndroidDevice> }, # 宛先がキー。動かさないプラットフォームのブロックは効果なし
inheritSetup?: boolean, # 既定 true — false で、宣言した全ターゲットの `hooks.setup` を省く。cleanup は走る
}
# シナリオが適用する iOS のデバイスの状態です。各フィールドは、ターゲットの `runsOn.ios` の同名の値を
# 置き換えます。`seedPhotos` のパスはシナリオファイルを基準に解決します。重ね合わせたあとのリストが
# 空でなければ、実効の `subject.reinstall: erase` が必要です。
IosDevice ::= { locale?: string, seedPhotos?: list(string) }
# シナリオが適用する Android のデバイスの状態です。`seedPhotos` はターゲットの
# `runsOn.android.seedPhotos` を置き換えます。パスはシナリオファイルを基準に解決し、erase は要りません。
AndroidDevice ::= { seedPhotos?: list(string) }
# ── SystemAlertInterrupt(リアクティブなシステムアラートガードの答え)─
# ガードは `run --no-system-alert-handling` を付けない限り ON です。シナリオやターゲットがガード全体を
# OFF にする手段はありません。XCUITest ではネイティブの SpringBoard 照会 + tap(モデルなし、BE-0316 を
# 再利用。BE-0315)で答え、その照会に映らないプロンプトにはツリー内でタップします。どのエントリも名指し
# しないアラートは、推測せずブロックされたステップの失敗理由に書き出します(BE-0402、BE-0406)。
# プロンプトごとに、シナリオのエントリがターゲットの `choice` を置き換え、省略した `frozenScreenTimeout`
# はターゲットから受け継ぎます。それ以外のプロンプトは両方のリストから適用します。
# 1 つのリストに同じプロンプトは 1 回だけ書けます(BE-0473)。
SystemAlertInterrupt ::= {
systemAlert: notifications|tracking|paste|savePassword|localNetwork,
choice: grant|deny|leave, # leave は何も答えない。シナリオ自身の handleSystemAlert ステップが処理する場合など
pollInterval?: number, # ネイティブのポーリング間隔・秒(既定 1)。シナリオ › --alert-poll-interval › ターゲット、同じ層では最小値
frozenScreenTimeout?: number, # 止まった画面での打ち切り・秒(既定 10、0 で無効)。アプリ自身のツリーに出るプロンプト(savePassword)のみ
}
# savePassword はガード専用。iOS がプロセス内に出すため、ツリー内タップだけが答えられる。
# 後述の handleSystemAlert ステップはこれを拒否する(BE-0406)
# ── TipKitInterrupt(Apple の TipKit の popover。iOS のみ)─────────────
# エントリが求めない限り OFF です。tip 自体がアサーションの対象になる場合があるためです。シナリオの
# エントリがターゲットのエントリに優先します。`run --ios-tipkit-handling` / `--no-ios-tipkit-handling`
# は、すべてのシナリオのエントリを dismiss / leave に設定します。1 つのリストに 1 件までです(BE-0473)。
TipKitInterrupt ::= { tipKit: dismiss|leave }
Permissions ::= map(PermissionService, PermissionAction) # アプリの起動前に適用する
PermissionService ::= "location" | "camera" | "microphone" | "contacts"
| "photos" | "calendar" | "notifications"
PermissionAction ::= "grant" | "revoke"
# ── Step = ちょうど 1 アクション + 任意の修飾子 ─────────────────────────
Step ::= <Action> & <StepMods>
StepMods ::= { capture?: list(<CaptureToken>), extract?: map(string, <Extract>), name?: string, from?: string, target?: string }
# `from`: 由来。record がこのステップを正規化した元の自然言語の文(BE-0044)
# `name` はダウンストリームで実際のファイルシステムパスの一部になる(run の
# step_id、エディタの証跡参照)。パス区切り文字、または単独の「.」「..」はロードエラー
# `target`: このステップが scenario.targets のどれを操作するか(BE-0428)。要否は
# len(scenario.target_names) と scenario.primaryTarget で決まる(§4)。web ブロック内に入れ子になったステップでは
# 拒まれる。そのステップは、囲んでいる web ステップがすでに解決したターゲットへ常に
# 走るため
Extract ::= { sel: <Selector>, prop?: ("value"|"label"|"identifier") } # 既定 "value"
Action ::=
{ tap: <Selector> }
| { tapPoint: { x: number, y: number } } # 正規化座標 0..1(左上原点)。ツリーに現れない要素(ID なしアプリのタブバーのタブなど)への画像フォールバック
| { doubleTap: <Selector> }
| { longPress: { sel: <Selector>, duration: number } }
| { type: { text: string, into?: <Selector>, submit?: boolean } } # submit 既定 false
| { clear: { into: <Selector> } } # フィールドをフォーカスして現在の内容をすべて削除(web コンテキストは非対応)
| { delete: { into: <Selector>, count: integer } } # フィールドをフォーカスして末尾から count 文字削除(count > 0。web コンテキストは非対応)
| { select: { into: <Selector>, mode?: "all" } } # フィールドをフォーカスして内容を選択(mode 既定 "all"。web コンテキストは非対応。codegen は XCUITest の同等コードを出力)
| { copy: {} } # 選択中の内容をクリップボードにコピー(事前に select が必要。web コンテキストは非対応)
| { paste: { into: <Selector> } } # フィールドにフォーカスし、カーソル位置にクリップボードをペースト(web コンテキストは非対応)
| { selectOption:{ sel: <Selector>, option: string } } # web の <select> をこの value を持つ option に設定(web 専用。iOS/Android は非対応)
| { navigate: string } # baseUrl を基準に解決した URL を開く。http/https のみ(web 専用。BE-0464)
| { openUrl: string } # シナリオが操作中のアプリに向けて絶対 URL を OS へ渡す。javascript:/data:/file: 以外の任意のスキーム。web: の中には置けない(iOS と Android。BE-0487)
| { setPickerValue:{ sel: <Selector>, value: string } } # ホイール型のピッカーをこの value を持つ行へ動かす(iOS と Android。sel は 1 つのホイールを指す)
| { swipe: <Swipe> } # 方向指定形式はスクロール。座標形式は素のドラッグ
| { drag: <Drag> } # 掴んだ要素(ハンドル / 仕切り / スライダー)をポインタドラッグする。スクロールではない
| { scroll: <Scroll> } # `to` が画面に入るまで(慣性なしに)スクロールし、上限で失敗する(BE-0326)
| { back: {} } # 前の画面へ戻る(Android はシステムキー / iOS は OS 戻るボタン / web は履歴)
| { pinch: { sel: <Selector>, scale: number } } # scale > 0 (>1 拡大, <1 縮小)
| { rotate: { sel: <Selector>, radians: number } } # >0 時計回り
| { handleSystemAlert: { sel: <Selector>, timeout: number } } # iOS SpringBoard の権限プロンプトを tap(iOS/XCUITest 専用)。sel は label/labelMatches/index のみ
| { handleSystemAlert: { prompt: notifications|tracking|paste|localNetwork, choice: grant|deny, timeout: number } } # 同じステップ。label は run の locale から解決し、対応表にない言語ではボタンの位置で解決する(BE-0320、BE-0445)。savePassword はここでは名指しできない(BE-0406)
| { wait: <Wait> }
| { sleep: { seconds: number, reason: string } } # 固定の待機: 0 < seconds <= 30、reason は空白不可。条件待機の唯一の例外
| { assert: list(<Assertion>) }
| { relaunch: { env?: map(string,string), args?: list(string) } }
| { setLocation: { lat: number, lon: number } }
| { push: { payload: map(string,any) } } # APNs ペイロード 例 {aps:{alert:"…"}}
| { http: { method?: string, url: string, headers?: map(string,string), body?: string, status?: integer, saveBody?: string, extractBody?: list({ var: string, path: string }) } } # method 既定 GET; saveBody → vars.<name>; extractBody → JSON path ごとに vars.<var>(BE-0440)
| { totp: { secret: string, into?: { var: string }, name?: string, minRemaining?: integer } } # RFC 6238 OTP → vars.<var>(secret は base32)。name は otp 向けにシークレットを登録する(into と name の少なくとも一方が必要)。minRemaining は 1〜30(into が必要)で、残りがそれ未満なら次の 30 秒ウィンドウを待つ(BE-0474)
| { otp: { from: string, into: { var: string }, minRemaining?: integer } } # totp ステップが from の名前で登録したジェネレータの現在のコード → vars.<var>。minRemaining は totp と同じ
| { email: { match: { to?: string, subject?: string, subjectMatches?: string }, extract: { var: string, bodyMatches: string }, timeout: number } } # メールボックスをポーリング → vars.<var>
| { generate: <Generate> } # 実行時に計算した乱数または現在日時の値 → vars.<var>(BE-0377)
| { eval: <Eval> } # 保持している値を固定語彙の操作で変換 → vars.*(BE-0472)
| { background: {} } # Home ボタン(SpringBoard 経由でバックグラウンド化。終了はしない)
| { foreground: {} } # アプリを終了させずに前面に出す。動いていないアプリは `relaunch` と同じように起動し、準備が整うまで待つ(iOS と Android、BE-0447)。background の対
| { installApp: { from: string, keepData?: boolean } } # 後から入るデバイスグループのメンバーのビルドをステップのデバイスにインストールする。keepData 既定 true(上書きでデータを保持)、false は先にアンインストール。何も起動しない(BE-0447)
| { setPrimaryTarget: { target: string } } # 以降、省略した `target`(ステップ、`interrupts` エントリ、トップレベルの `expect`)を `target` に解決する。トップレベルの `steps` だけ(BE-0447)
| { clearKeychain: {} } # 保存済みパスワード / 証明書をリセット
| { clearClipboard: {} } # ペーストボードをクリア
| { setClipboard: { text: string } } # クリップボードにテキストを書き込む(simctl pbcopy、Android は BajutsuAndroid)。ペースト操作の準備用
| { setMocks: list(<Mock>) } # シナリオの途中でアプリのスタブテーブル全体を置き換える([] はすべてのスタブを外す)。iOS/XCUITest かつネットワーク収集が有効な場合のみ(BE-0365)
| { overrideStatusBar: { time?: string, batteryLevel?: integer, batteryState?: string, cellularBars?: integer, wifiBars?: integer } }
| { clearStatusBar: {} } # ライブのステータスバーに戻す
| { use: { component: string, with?: map(string,string) } } # マクロ(§6.2。修飾子は target のみ)
| { group: <Group> } # ステップに名前を付け、report.htmlで折りたたむ(§6.2。capture/extract 不可。入れ子不可)
| { if: <If> } # 条件分岐(capture/extract 不可)
| { forEach: <ForEach> } # ループ(capture/extract 不可)
| { web: <Web> } # WebView の DOM コンテキストに入る(BE-0037。capture/extract 不可)
| { app: <App> } # テスト対象アプリが起動していないアプリを起動してUIを操作する(iOS/XCUITest と Android/adb。capture/extract 不可)
| { manual: { label: string, bypass?: string } } # `record` 中に記録される人による操作の引き取り(BE-0185)。決定的な等価物がないため、`bypass` を配線しない限り実行時に明示的に失敗する
Group ::= { name: string, steps: list(<Step>) } # どちらも必須、空を許さない。コンパイル時マクロで、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` はネイティブに解決してちょうど1つの WKWebView ホストを指す。内側の `steps` はネイティブの
# アクセシビリティツリーではなく、正規化された DOM(`data-testid` → Element.identifier)を対象にする。
App ::= { bundleId: string, steps: list(<Step>) }
# `bundleId` はインストール済みの任意のアプリを名指しする。テスト対象アプリの協力なしに起動(また
# は、すでに起動していればそれを活用)する。内側の `steps` はそのアプリ自身のアクセシビリティツリー
# を対象にする。ブロックを抜けると、`Web` と同じ入る・抜けるの契約で、直前にアクティブだったものへ
# 戻る。
# `com.apple.springboard` はホーム画面そのもの(編集モード、ウィジェットギャラリー)を名指しする。
# 実測した制約(`erase`、`locale` の固定、ギャラリー検索結果の行がツリーに現れないこと)は
# scenarios.md にある。
Swipe ::=
{ on: <Selector>, direction: ("up"|"down"|"left"|"right"), amount?: number } # セレクタ形 ┐ XOR
| { from: <Point>, to: <Point> } # 座標形 ┘
# amount(セレクタ形のみ): 画面に対する移動量の割合。0 < amount ≤ 1。省略時は小さめの既定割合(0.125)
Drag ::= { on: <Selector>, direction: ("up"|"down"|"left"|"right"), amount?: number } # 要素アンカーのポインタドラッグ(BE-0227)。amount は Swipe と同じ
Scroll ::= { to: <Selector>, direction?: ("up"|"down"|"left"|"right"), within?: <Selector>, amount?: number, maxScrolls?: integer }
# `to` のフレーム中心が画面に入るまでスクロールし、入らなければ失敗する(BE-0326)。direction はスクロール方向(既定 "down")で、Swipe の指方向とは逆。
# within: ジェスチャを行うスクロール可能なコンテナ(既定は画面全体)。maxScrolls: 失敗までのステップ上限(既定 15、> 0)。
# amount: 1 ステップの移動量(ビューポートに対する割合、0 < amount ≤ 1。省略時 0.6)。ループの出発点を決めるもので、リカバリの下限は動かさない(BE-0400)。
Point ::= [ number, number ]
Generate ::=
{ random: <Random>, into: { var: string } } # シナリオがまだ持っていない新しい値 ┐ XOR
| { datetime: <Datetime>, into: { var: string } } # 現在時刻をテキストにした値 ┘
Random ::=
{ string: { length: integer, charset?: ("alnum"|"alpha"|"numeric"|"hex") } } # length > 0、charset の既定は "alnum" ┐
| { int: { min: integer, max: integer } } # min ≤ max の閉区間 │ XOR
| { float: { min: number, max: number, precision?: integer } } # min ≤ max、precision ≥ 0 は小数桁数 │
| { uuid: {} } # バージョン4の UUID ┘
Datetime ::= { format?: string, offsetSeconds?: integer, offsetMinutes?: integer, offsetHours?: integer, offsetDays?: integer, timezone?: string }
# format: strftime のパターン。省略時は秒までの ISO 8601。4つの offset は符号付きで、加算されます。
# timezone: IANA 名(例 "America/Los_Angeles")。省略時は UTC。描画できない format と解決できないゾーンはロード時に失敗します。
Eval ::= { from: string, ops: list(<EvalOp>), into: { var: string } | { vars: list(string) } }
# ops: 空にできません。各操作は直前の結果に適用します。ローダは from(文字列)から最後まで文字列かリストかを追跡します。
# into.var: リストの結果はコンパクトな JSON 配列テキストで保存します。into.vars: リストの結果が必要です。要素 i → vars[i]、
# 余った要素は捨て、リストが短ければステップを失敗させます。vars の名前は重複できません。
EvalOp ::=
"trim" | "json" | "count" | "unique" | "reverse" | "sort" # 名前だけで書く操作
| { split: string | { by: string, regex?: boolean } } # 文字列 → リスト。by は空にできません
| { join: string } # リスト → 文字列
| { filter: { matches: string | equals: string | contains: string | notEmpty: true, not?: boolean } } # 条件はちょうど1つ
| { pick: "first" | "last" | integer } # リスト → 文字列。添字 ≥ 0
| { sort: ("asc"|"desc") | { order?: ("asc"|"desc"), numeric?: boolean } }
| { regex: { pattern: string, group?: integer } } # 文字列 → 文字列。group の既定は 0
| { replace: { find: string, with: string, regex?: boolean } } # 文字列 → 文字列
| { substring: { start: integer, end?: integer } } # 文字列 → 文字列。どちらも ≥ 0
| { case: ("lower"|"upper") } # 文字列 → 文字列
# 自由文と添字の引数には ${vars.*} / ${secrets.*} を書けます。その引数はロード時ではなく置換後に検査します。
# sort の order、case、フラグの regex / not / numeric にはリテラルだけを書けます。
# ── Selector(1 条件以上・指定フィールドは AND)────────────────────────
Selector ::= {
id?: string | list(string), # リストは候補の OR(BE-0221)。1つのシナリオでプラットフォームごとの id 表記をすべて持てる。正本(ドット区切り)の形を先頭に置く
idMatches?: string | list(string), # id に対するグロブ(fnmatch, 例 "list.row.*")。リストは id と同じ形で候補を OR する
label?: string,
labelMatches?: string, # label に対する正規表現
traits?: list(string),
value?: string,
within?: <Selector>, # コンテナの部分木に限定
index?: integer, # 意図的に非一意なとき k 番目を選ぶ
}
# ── Wait(for / until のどちらか一方)──────────────────────────────────
Wait ::= { for: <Selector>, timeout: number }
| { until: <Until>, timeout: number }
Until ::= "screenChanged" | "settled"
| { gone: <Selector> }
| { request: <RequestMatch> }
# ── Assertions(1 項目につき 1 種類)───────────────────────────────────
Assertion ::=
{ exists: <Selector> & { negate?: boolean } } # セレクタはインライン・negate 既定 false
| { value: <TextMatch> }
| { label: <TextMatch> }
| { count: <CountMatch> }
| { enabled: <Selector> }
| { disabled: <Selector> }
| { selected: <Selector> }
| { request: <RequestMatch> }
| { event: <EventMatch> } # アプリが送信したアナリティクス / テレメトリのイベント(BE-0048)
| { requestSequence: list(<RequestMatch>) } # 1 つ以上のマッチャ。マッチしたやり取りの順序付き集合
| { responseSchema: <ResponseSchemaMatch> } # 取得したレスポンスボディを JSON Schema で検証する(BE-0048)
| { visual: <VisualMatch> }
| { clipboard: <ClipboardMatch> } # デバイスのクリップボードの読み戻し(simctl pbpaste、Android は BajutsuAndroid)
| { attribute: <AttributeMatch> } # 1 つの要素の HTML 属性を必要なときに読み取る(web のみ。BE-0466)
| { golden: <GoldenMatch> } # 実行中の要素ツリーを記録済みの golden ファイルと比較する(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} ) # セレクタを持たない件数比較。EventMatch の多重度に使う
ClipboardMatch ::= ( {equals:string} | {matches:string} ) # ちょうど 1 つ。matches は正規表現
AttributeMatch ::= { sel: <Selector>, name: string } # name は正しい HTML 属性名。小文字に変換しない
& ( {equals:string} | {contains:string} | {matches:string} | {absent:true} ) # ちょうど 1 つ
GoldenMatch ::= { path: string } # golden コンテキストのベースディレクトリに対して解決する(BE-0006)
VisualMatch ::= { # 画面をベースライン画像とピクセル比較する
baseline: string, # --baselines 内で解決されるファイル名(既定: シナリオ隣の baselines/)
element?: <Selector>, # 比較対象をこの要素のフレームに絞る(BE-0171、既定: 画面全体)
compare?: "exact" | "pixelmatch", # 比較エンジン(既定: config または "exact"、BE-0165)
threshold?: number, # 許容差分(ピクセルの%、既定 0.0 = 完全一致)
colorTolerance?: number, # ピクセル単位の知覚的色差許容値、0–1(pixelmatch 用、既定 0.1)
antialiasing?: boolean, # アンチエイリアスピクセルを差分から除外する(pixelmatch 用、既定 true)
exclude?: list(<ExcludeRegion> | <SelectorRegion>), # 比較前にマスクする領域(ステータスバー・時計など)
}
ExcludeRegion ::= { x: number, y: number, w: number, h: number } # スクリーンショットのピクセル
SelectorRegion ::= { selector: <Selector> } # 要素のフレームをマスクする(BE-0171)。曖昧なら失敗、不一致なら何もしない
上記の `Assertion` はどの種類も、任意の `target?: string` を持ちます(BE-0428)。これは、チェックが
`scenario.targets` のどれに対して走るかを名指しします。設定できるのは、トップレベルの `expect`
エントリだけです。`Step` のインラインの `assert:` リストや `If` の `condition` を通して届く
`Assertion` は、囲んでいるステップによってすでにターゲットが決まっています。そのため、そこでの
`target` の指定は拒まれます(§4)。
RequestMatch ::= { # 下記マッチフィールドの 1 つ以上
method?: string,
url?: string, # 完全一致 URL(エンドポイント)
urlMatches?: string, # URL 全体への正規表現/部分一致
path?: string, # 完全一致パス(クエリ無視)
pathMatches?: string, # パスへの正規表現
query?: DictMatch, # URL デコードしたクエリパラメータ。値は string か演算子 map(BE-0463)
body?: DictMatch, # 解析した JSON リクエストボディ。値は任意の DictValue(BE-0463)
status?: integer,
bodyMatches?: string, # リクエストボディへの正規表現/部分一致
count?: integer, # アサーション → 厳密一致数 / wait → 下限
}
DictMatch ::= map(string, DictValue) # 空は不可。`$$` で始まるキーは `$` で始まるフィールドを指す
DictValue ::= string # JSON 値のテキスト形式と等しい(引用符必須。裸の 1/true/null は不可)
| { $matches?: string, $exists?: boolean } # 演算子 map(演算子 1 つ以上)
| map(string, DictValue) # JSON オブジェクトの部分集合
| list(DictValue) # 同じ長さの JSON 配列。要素ごとに照合
EventMatch ::= { # エンドポイント条件(method/url/urlMatches/path/pathMatches)、query、body の 1 つ以上
method?: string,
url?: string,
urlMatches?: string,
path?: string,
pathMatches?: string,
query?: DictMatch, # RequestMatch.query と同じ文法
body?: DictMatch, # RequestMatch.body と同じ文法
count?: <CountOp>, # 期待する多重度(既定: 1 回以上)
}
ResponseSchemaMatch ::= { request: <RequestMatch>, schema: string } # `schema` はアプリの schemas ディレクトリに対して解決する
# ── 証跡キャプチャ ─────────────────────────────────────────────────────
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`: 由来。この証跡ルールを正規化した元の指示(BE-0044)
Trigger ::= # action / event / result のどれか 1 つ
{ action: string, idMatches?: string } # idMatches は 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: 既定でマスクされる認証情報系ヘッダ(authorization、cookie、set-cookie など)の
# うち1つを明示的に解除する opt-out(BE-0130)
Mock ::= { match: <RequestMatch>, respond?: <MockResponse> } # match はリクエスト側フィールドのみ
MockResponse ::= { status?: integer, headers?: map(string,string), body?: string, delayMs?: number }
文法と配線は別の問題です。 このページは何が パースされ検証されるか を規定します。各アクションがバックエンドでどこまで実行されるか、各証跡種別がどこで取得されるかは、drivers と architecture の実装状況 で扱います。
3. 字句レイヤ(YAML)¶
シナリオファイルは YAML で、Bajutsu のローダ(common/_yaml.py)が読みます。YAML 1.1 から 意図的に 1 点だけ逸脱しています。
- boolean は
true/falseのみです。on/off/yes/noは 文字列のまま扱います。これによりcapturePolicyのトリガキーon:が(boolean のTrueではなく)キーのまま保たれ、onのような id/label 値も壊れません(scenarios)。
スカラは次のように対応します。YAML 文字列は string、整数は integer、整数または浮動小数は number です。<Point> は 2 要素のフローシーケンス [x, y] です。
4. 個数と排他の制約¶
形だけでなく、モデルは次の規則も課します。各規則は model_validator で強制され、違反はロードエラーになります。この表が 「ちょうど 1 つ」「1 つ以上」「両方不可」の正本です。
| 構文 | 規則 | 出典 |
|---|---|---|
Selector |
1 条件以上 | scenario/models/selector.py |
Step |
アクションキー(tap … use)ちょうど 1 つ。capture/name は修飾子でアクションではない |
scenario/models/steps.py |
Step.use |
取れる修飾子は target だけ。capture / extract / name / from を拒否する(展開が警告なく捨ててしまうため)。target は展開後のステップへ刻印する(BE-0446) |
scenario/models/steps/step.py |
Swipe |
形は {on,direction} か {from,to} の ちょうど 1 つ(混在も片側だけの指定も不可) |
scenario/models/actions.py |
Pinch |
scale > 0 |
scenario/models/actions.py |
HandleSystemAlert |
sel を label / labelMatches / index に限定(id/idMatches/traits/value/within を拒否) |
scenario/models/actions.py |
Wait |
for / until の どちらか一方 |
scenario/models/assertions.py |
Assertion |
種類(exists … request … visual)ちょうど 1 つ |
scenario/models/assertions.py |
TextMatch(value/label) |
equals / contains / matches の ちょうど 1 つ |
scenario/models/assertions.py |
CountMatch(count) |
equals / atLeast / atMost の ちょうど 1 つ |
scenario/models/assertions.py |
ClipboardMatch(clipboard) |
equals / matches の ちょうど 1 つ |
scenario/models/assertions.py |
AttributeMatch(attribute) |
equals / contains / matches / absent: true の ちょうど 1 つ。absent: false は拒否します。name は空でない正しい HTML 属性名です |
scenario/models/assertions/attribute_match.py |
RequestMatch |
method/url/urlMatches/path/pathMatches/query/body/status/bodyMatches の 1 つ以上(count はマッチフィールドではない)。query/body の辞書は空にできず、引用符付きのスカラー、$matches/$exists の演算子 map、(body では)入れ子の map とリストだけを含む |
scenario/models/assertions.py |
EventMatch(event) |
method/url/urlMatches/path/pathMatches/query/body の 1 つ以上 |
scenario/models/assertions.py |
CountOp(event.count) |
equals / atLeast / atMost の ちょうど 1 つ |
scenario/models/assertions.py |
Assertion.requestSequence |
1 件以上 | scenario/models/assertions.py |
Trigger(capturePolicy[].on) |
action / event / result の ちょうど 1 つ。idMatches は action と 併用時のみ |
scenario/models/evidence.py |
Scenario |
data と dataFile は 両方不可 |
scenario/models/scenario.py |
Scenario.targets |
入れ子かどうかにかかわらず、一覧全体で同じ名前の重複不可(BE-0428)。内側の list は2つ以上の名前を持つ(BE-0447)。以下の target_names は、グループをまたいで平坦化した宣言済みの全名前(BE-0447) |
scenario/models/scenario/_targets.py |
Scenario.primaryTarget |
省略するか、targets の最初の名前(最初のグループの最初のメンバー)と一致。targets が空なら拒否(BE-0436) |
scenario/models/scenario/_targets.py |
Scenario.installs |
各エントリは宣言済みのターゲットで、重複不可。プライマリを含まない、2つ以上のメンバーを持つグループは、自分のメンバーを1つ以上書く(BE-0447) | scenario/models/scenario/_targets.py |
installApp |
from は、ステップのデバイスを持つグループの後から入るメンバー(プライマリでも installs 記載でもない、2つ以上のメンバーを持つグループのメンバー)を指す。トップレベルの installApp は1つのメンバーにつき1つまで。web: / app: の中では拒否。シナリオが setPrimaryTarget を含むとき、デバイスを明示しない interrupts の復旧ステップでも拒否(BE-0447) |
scenario/models/scenario/_targets.py |
setPrimaryTarget |
target は宣言済みのターゲットを指す。トップレベルの steps だけに書ける。if、forEach、ターゲットグループ、web:、app:、interrupts エントリ、setup、cleanup の中では拒否。コンポーネント内のものは、呼び出す use: / group: がトップレベルにあれば有効で、展開は呼び出し側の target をこのステップに刻まない(BE-0447) |
scenario/models/scenario/_targets.py、scenario/expand.py |
Step.target / Assertion.target(expect のみ) |
len(target_names) ≤ 1 なら省略可、または宣言済みの1つと一致。len(target_names) ≥ 2 で primaryTarget が未設定なら必須(if/forEach/web ラッパーも含み、末端のアクションだけではない)で、宣言済みターゲットの1つを名指し。len(target_names) ≥ 2 で primaryTarget を設定していれば省略可で、省略したものは入れ子の深さによらず主ターゲットに対して走る(BE-0436)。この主ターゲットは現在のプライマリで、setPrimaryTarget ステップが移す(BE-0447)。web ブロック内に入れ子になったステップと、インラインの assert: リスト・if の condition・interrupts エントリの condition を通して届く Assertion では拒否(BE-0428) |
scenario/models/scenario/_targets.py |
use: / group: ステップの Step.target |
len(target_names) によらず、primaryTarget がなくても省略可で、ステップ自身は解決しない。指定した値は宣言済みターゲットを名指しする。展開は、呼び出しが生むステップのうち target を省略したものへその値を刻印し、異なるターゲットを名指しするステップを拒否する(BE-0446) |
scenario/models/scenario/_targets.py、scenario/expand.py |
Interrupt.target と、interrupts エントリの steps にある Step.target |
primaryTarget の有無にかかわらず、len(target_names) にかかわらず省略可。エントリの target を省略するとプライマリターゲットを監視し、リカバリ用ステップの target を省略するとエントリ自身のターゲットで実行する(ただし、target を指定した if/forEach ステップの内側では、そのステップのターゲットで実行する)。指定した値は、宣言済みターゲットの名指しについて上の Step.target の規則に従う(BE-0438) |
scenario/models/scenario/_targets.py |
targets.<name>.hooks.interrupts の Interrupt.target と、その steps にある Step.target |
拒否。エントリは、その config ブロックが設定するターゲットにすでに属している(BE-0438) | config/schema/target_config.py |
| すべてのマッピング | 未知キー不可(extra="forbid") |
scenario/models/_base.py |
exists は特別です。セレクタを インラインで書き(exists: { id: home.title })、任意の negate: true で不在を確認します。ローダは検証前にこれを { sel, negate } へ書き換えます(Exists._inline, scenario/models/assertions.py)。
5. 既定値¶
省略した任意キーは次の値をとります。最小シナリオは name と steps だけで記述できます。
| フィールド | 既定値 |
|---|---|
Scenario.tags / expect / capturePolicy / mocks / interrupts / setup / cleanup |
[] |
Scenario.preconditions |
{}(どのフィールドもターゲットの値に、次に組み込みの既定値に従います) |
Scenario.permissions |
{}(起動前の権限状態を適用しない) |
Preconditions.inheritSetup |
true(宣言した各ターゲットの hooks.setup がシナリオの setup の前に走る) |
Preconditions.subject.reinstall |
未設定 — ターゲットの subject.reinstall、なければ clean。--erase は erase に引き上げ、--no-erase は erase を clean に下げます(BE-0473) |
Preconditions.subject.launch.args |
[] |
Preconditions.subject.launch.env |
{} |
systemAlert エントリ |
なし(ガードは ON ですが、どのプロンプトにも答えません。出会ったアラートはブロックされたステップの失敗理由に書き出します) |
tipKit エントリ |
なし(ターゲットのエントリ、なければ OFF。tip 自体が検証対象になる場合があるためです。iOS のみ) |
TypeText.submit |
false |
Exists.negate |
false |
MockResponse.status |
200 |
MockResponse.headers |
{} |
Component.params |
[] |
ScenarioFile.schema |
1(BE-0119) |
最小シナリオの全体:
- name: opens home
steps:
- tap: { id: onboarding.start }
- wait: { for: { id: home.title }, timeout: 5 }
expect:
- exists: { id: home.title }
6. テンプレートとマクロ層¶
コア文法の周りに、小さな置換と展開の層があります。この層はロード時、決定的 run の 前に実行されるため、ランナーは常に展開済みのプレーンなシナリオだけを見ます。
6.1 ${namespace.key} 補間¶
実装は bajutsu/interp.py です。トークンは ${namespace.key} の形をとります(波括弧内の空白は除去します)。置換は 端で型を保ちます。
- ちょうど 1 トークンだけの文字列(
"${row.qty}")は 生の束縛値になります(数値は数値のまま)。 - 大きな文字列に 埋め込まれたトークンはテキストとして差し込まれます(
"item-${row.id}")。 - いま置換していない名前空間のトークンは そのまま残るため、各層は自分の名前空間だけを埋めます。
名前空間は次の 4 つです。
params.*:コンポーネントのパラメータ(§6.2)。row.*:データ駆動の行(§6.3)。secrets.*:config のevidence.secretsで宣言し、run ループがアクション時に環境変数から解決します(§6.4)。vars.*:extract経由のランタイムキャプチャ(§6.5)。
6.2 コンポーネント(use → 再利用ステップ)¶
<Component> は、params のリストと、それを ${params.<name>} で参照する steps のリストからなります。use ステップが with で params を束縛して呼び出します。コンポーネントの置き場所は2つあります。専用のファイル(ComponentFile)か、呼び出すシナリオファイルの中(ScenarioFile.components、BE-0422)です。
# login.component.yaml(コンポーネントファイル)
params: [email, password]
steps:
- type: { text: "${params.email}", into: { id: auth.email } }
- type: { text: "${params.password}", into: { id: auth.password } }
- tap: { id: auth.submit }
# シナリオファイル側。呼び出すシナリオの隣にファイルスコープのコンポーネントを置きます
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 }
どちらとして解決するかは ref 自身の形が決めます。 component: フィールドは1つのままで、新しい構文は要りません。/ を含むか .yaml / .yml で終わる ref はパスです。参照元のシナリオファイルからの相対で解決し、スイートルートの内側に閉じ込めます(BE-0174 の封じ込め)。それ以外は素の名前です。呼び出し元ファイル自身の components: を引きます。components: にない素の名前はエラーになります。ファイルを読みに行くフォールバックは起きません。
components: の有効範囲は1ファイルです。ファイルごとに読み、スイートディレクトリをまたいで統合しません。あるファイルで宣言した名前は、ほかのファイルからは見えません。コンポーネントファイルへ入ると components: は完全に外れます。コンポーネントファイルは自分の components: を持たないため、その中の素の use は常に未定義です。参照元のシナリオファイルが何を宣言していても変わりません。一方、ファイルスコープのコンポーネント自身の steps は、宣言元ファイルのスコープで展開されます。別のファイルスコープのコンポーネントを素の名前で use できますし、パスでファイルも use できます。ファイルをまたぐ再利用はパス参照の役目のままです。
expand_components(scenario/expand.py)は各 use をコンポーネントの置換済みステップに 置き換えます。展開は再帰的で、コンポーネントが別のコンポーネントを use でき、深さは 25 までです。params の不足、未知の params、未宣言を指す残留した ${params.*}、未定義の素の名前、循環参照のいずれかがあるとエラーになります。
ComponentResolver(scenario/load_expanded.py)は、resolve をファイルの components: とルートと基準ディレクトリに束ねる唯一の場所です。おかげで run とデバイス不要のリーダーは、同じファイルを同一に展開します。
展開は if / else の分岐、forEach の本体、web: / app: ブロックにも降ります。そのため run が通らない分岐の use も展開され、壊れていればロードが失敗します。展開は純粋でコンパイル時に行われるため、use は run に残らず、決定性に影響しません。
use ステップが取れる修飾子は target だけです。展開がステップ全体を置き換えるので、capture / extract / name / from を併記した use ステップはローダーが拒否します。警告なしに捨てると、これらのフィールドが効いていないことに作成者が気付けないからです。target については、展開が捨てずに引き継ぎます(BE-0446)。展開は、生じたステップのうち target を省略したものへ値を刻印します。刻印は if / forEach の本体と入れ子の use 呼び出しへ降り、web: / app: ブロックで止まります。同じターゲットを名指しするステップは受け入れ、異なるターゲットを名指しするステップはロードを失敗させます。エラーメッセージにはコンポーネントの連鎖が入ります。
group は use の身近な兄弟です。 Group は name と steps だけを持ち、params と
別ファイルのどちらも持ちません。expand_components の同じ expand() 再帰が、group ステップを
その場で自分自身の steps へ置き換えます。各ステップには report_group / report_group_id
(内部フィールドで、書ける文法には含まれません)を付けます。これにより、report.html はそれらを
1つにまとめて折りたためます(reporting.md)。expand() は、すでに別の
group の中にいる状態で group に出会うとエラーを送出します。これは、内側の group が直接
書かれた場合も、use の呼び出しを経由して届いた場合も同じです。Scenario レベルのバリデータも、
別の group の steps の中や、if / forEach / web / app ステップの入れ子の steps の中に
直接書かれた group を、ロード時に拒否します。コンポーネントがそれらの本体へ持ち込んだ group も、
expand() が拒否します。group ステップ自身の target は、上の use の規則に従います。
6.3 データ駆動シナリオ(data / dataFile)¶
data(インライン行)か dataFile(CSV パス。両者は排他)を持つシナリオは、${row.<column>} を置換して 1 行 1 シナリオに展開されます(expand_data, scenario/expand.py)。派生シナリオは "<name> [row N: col=val, …]" に改名され、元の preconditions を保ちます。そのためどの行も、元の preconditions(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 共有のセットアップ、secrets、タグ選択¶
- 共有のセットアップ:1 度だけ記述するログインやナビゲーションの手順は、コンポーネント(§6.2)にします。シナリオ自身の
setupか、config にあるターゲットのhooks.setupからuseで呼び出します。ターゲットの hooks が呼ぶコンポーネントは config のロード時に config ファイルのディレクトリを基準に解決し、スイートのルートの内側に収まっている必要があります(BE-0174)。以前のpreconditions.setupプレリュードファイルは廃止しました(BE-0452)。ターゲットのhooks.setupを走らせたくないシナリオは、preconditions.inheritSetup: falseを指定します。 secrets(config のevidence.secretsで宣言する、環境変数名のリスト):宣言した各名Xはos.environ[X]から解決され${secrets.X}に束縛され、アクション時に実行ステップへ置換されます(cli/commands/run.py,orchestrator/substitution.py_interp_step)。シナリオは${secrets.X}トークンを保ち値は持たず、リテラル値は証跡で自動マスクされます(Redactor)。params.*/row.*と異なり、この名前空間はロード時ではなく run ループが解決します。tagsと CLI の--tag/--excludeで実行対象を絞ります。excludeがincludeより優先されます(select_scenarios,scenario/select.py)。
6.5 展開順¶
ロードパイプライン(cli/commands/run.py)はこれらを決定的に、この順で適用します。
load_scenarios # この文法に対しパース + 検証
→ select_scenarios # --tag / --exclude
→ expand_components # use → コンポーネントステップ(${params.*})
→ expand_data # 1 行 1 シナリオ(${row.*})
→ run # 決定的ループは展開済みシナリオだけを見る
7. 検証とラウンドトリップ¶
load_scenarios(text) -> list[Scenario]は上記すべてに対して検証します。トップレベルはシナリオのシーケンスか{description, scenarios}マッピングのいずれかが必須で、§4 のいずれかの規則違反はロードエラーになります(scenario/load.py)。dump_scenarios(scenarios) -> strは YAML へ戻します。著者が設定しなかったフィールドだけを落とし、エイリアスキー(idMatches、inheritSetupなど)で出力します。出力は そのまま再ロード可能で、recordが依存するラウンドトリップです(scenario/serialize.py)。
形の背後にある意味論(セレクタが 0/1/2+ 件にどう解決するか、各アサーションがどう比較するか、wait がどうタイムアウトするか)は selectors と run-loop を参照してください。例でシナリオを書き始めるには scenarios を参照してください。