コンテンツにスキップ

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 を参照してください。