コンテンツにスキップ

English · 日本語

シナリオ仕様(オーサリングリファレンス)

シナリオは Bajutsu が永続化する 唯一の成果物です。プレーンな YAML で書き、git でバージョン管理し、PR でレビューできます。最初の 1 回は record(AI)が書き、以後は人間が所有して編集します。run はこの構造を AI なしで実行します。

実装: bajutsu/scenario/(models/ 配下の pydantic モデル。extra="forbid" で未知キーを拒否)。

すべての生成規則、型、既定値、検証規則を定めた 規範的な文法は dsl-grammar にあります。このページはオーサリングガイドであり、例を使ってシナリオの書き方を示します。

関連: cookbook(実例集) · dsl-grammar(形式文法) · selectors(セレクタとアサーションの評価方法) · evidence(証跡) · run-loop(実行)


ファイルの形

1 ファイルは シナリオの配列です。ファイルレベルの説明を付けたい場合は { description, scenarios } のマッピングにします。load_scenarios() はどちらの形式も受け付けます(どちらでもないトップレベルは拒否されます)。

- name: ...        # scenario 1
  steps: [...]
- name: ...        # scenario 2
  steps: [...]

ファイルレベルの説明(および任意の per-scenario description)を付ける場合は次のようにします。

description: What this file covers.
scenarios:
  - name: ...
    description: What this scenario checks.
    steps: [...]

ファイルの説明と各シナリオの description は、report.html(サマリーヘッダーと各シナリオカード)および bajutsu serve の UI に表示されます。

スキーマバージョン

マッピング形式では、トップレベルに整数の schema を置いて、シナリオスキーマのバージョンを示せます。schema を省いたファイルはバージョン 1 として扱うため、既存のシナリオはそのままで有効です。

schema: 1
scenarios:
  - name: ...
    steps: [...]

実行中の bajutsu が理解できるものより新しい schema をシナリオが宣言している場合、読み込みは「未知のフィールド」という分かりにくいエラーではなく、明快なアップグレード手順のメッセージで失敗します。これは、バージョンをまたいでシナリオツリーを読み込むとき(たとえば、固定した Git の ref から config を取得したとき)に生じる状況です。現在のバージョンは bajutsu/scenario/models/scenario.py の SCHEMA_VERSION です。版上げは読み込みを壊す変更のときだけ行います。以前必須だったフィールドの意味を取り除く変更や、古い bajutsu が単に拒否するのではなく誤解してしまう変更が該当します。純粋に追加的なオプションフィールドは、版上げを必要としません。

トップレベル構造(Scenario)

キー 型 既定 説明
name str 必須 シナリオ名(レポート / JUnit testcase / codegen のメソッド名に使う)
description str なし 任意の説明文。シナリオの report カードと serve UI に表示
from str なし 来歴(provenance):record がこのシナリオを書き起こした元の自然言語ゴール(来歴)。オーサリング用のメタデータで、run は読みません
tags list[str] [] 選択ラベル。CLI の --tag / --exclude で実行対象を絞る(再利用とデータ駆動とタグ)
targets list[str | list[str]] [] このシナリオが操作する target の一覧(下記)。各エントリは targets.<name> の config ユニットを指し、run が読み込む config から解決されます。1台のデバイスを共有する2つ以上の名前の配列も書けます(デバイスグループ)
primaryTarget str なし target を省略したステップやトップレベルの expect エントリが動くターゲット。targets の最初の名前(最初のグループの最初のメンバー)と一致する必要があります(下記)
installs list[str] [] プライマリと並んで開始時にインストールして起動するデバイスグループのメンバー。2つ以上のメンバーを持つグループのそれ以外のメンバーは、後から installApp ステップでインストールします(デバイスグループ)
data / dataFile list / str なし データ駆動の行。インライン data か dataFile(CSV パス)で指定する。1 行 1 run に展開し ${row.col} を置換する。両者は排他(再利用とデータ駆動とタグ)
preconditions object {} テスト前の環境準備です。ターゲットと同じグループ名の subject をターゲットの値に重ね、デバイスの状態を device に、ターゲットのセットアップを引き継ぐかを inheritSetup に書きます(下記)
setup list [] steps の前に独立したフェーズとして走るセットアップのステップ列。ここで失敗するとシナリオを打ち切る(下記)
steps list 必須 アクションの並び(下記)
expect list [] 全ステップ成功後の最終アサーション(selectors)
cleanup list [] ティアダウンのルール。各エントリは { on: always \| success \| failure, steps } で、判定が出たあと steps を抜けるすべての経路で走る(下記)
capturePolicy list [] 繰り返し発火する証跡ルール(evidence)
network object なし { filter: { domains: [...] } }。filter.domains は、レポートの Steps タイムラインに差し込む通信を URL ホストで絞る(親ドメインはサブドメインに一致)。未指定なら全件を表示する。Network タブは常に全件を表示する(reporting)
mocks list [] 決定的なネットワークスタブ。一致する送信リクエストには、ネットワークへ行かず定型レスポンスを返す(ネットワークモック)
redact object なし 証跡を書き出す前に適用するマスク(evidence)
permissions dict {} 宣言的な OS 権限の状態({ <service>: grant \| revoke })。アプリの起動前に適用する(下記)
interrupts list [] 予測できない時点で現れたときに run が自動で片付けるもの。ターゲットの hooks.interrupts の上に重なる。各エントリは書いたキーで 3 つの形のどれかに決まる。差し込み画面({ condition, steps }、下記)、OS のプロンプト({ systemAlert, choice }、下記)、Apple の TipKit のポップオーバー({ tipKit }、下記)のいずれかである
- 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" }

(demos/showcase/scenarios/search.yaml 実物)

preconditions(環境準備)

実装は scenario/models/scenario/preconditions.py の Preconditions です。各ターゲットへの重ね合わせは bajutsu/common/config/preconditions.py が行います。runner の launch_driver は重ね合わせた結果を読んで、 起動手順を組み立てます(run-loop)。

シナリオの preconditions は 2 つのグループと 1 つのフラグを持ちます。subject はターゲットと同じグループ名を 使うので、1 つのフィールドは config でもシナリオでも同じ綴りになります (BE-0452)。 device は、シナリオが適用するデバイスの状態を宛先ごとに持ちます。宛先は device.ios だけです (BE-0469)。 inheritSetup は、このシナリオの前にターゲットの hooks.setup を実行するかを決めます。 シナリオに書いたフィールドは、ターゲットの config の同じフィールドを上書きします。 例外は次の 2 つです。

  • subject.launch.env はキーごとにマージします。
  • subject.launch.args はターゲットの引数の後ろに追記します。

システムアラートや TipKit の tip のように、run が自動で答えるものは前提条件ではありません。シナリオは それらを自身のトップレベルの interrupts のエントリとして宣言し、そのエントリがターゲットの hooks.interrupts の上に重なります(下記)。

preconditions:
  subject:
    reinstall: erase
    launch: { env: { FEATURE_X: "1" }, args: ["-debug"], deeplink: "showcase://cart" }
  device:
    ios: { locale: ja_JP, seedPhotos: [photos/cat.jpg] }
  inheritSetup: false
キー 型 既定 説明
subject.reinstall overwrite | clean | erase 未設定(ターゲットの subject.reinstall、次に clean) 各 run の前にどこまで状態を戻すかを、弱い順に決めます。overwrite は既存アプリに上書き install します(データを保持します)。clean は uninstall してから install します(アプリとデータを fresh にします)。erase はデバイス全体を wipe してから install します(simctl erase。アプリ、データ、設定を消去します)。install にはターゲットの config の subject.path が必要です。デバイス全体の wipe がない Android では、erase は clean と同じに動きます。iOS と Android で使えます。web のターゲットが受け付けるのは erase だけで、新しいブラウザコンテキストがすでにこの値を満たします(BE-0473)
subject.launch.env dict {} 起動時の環境変数です。ターゲットの subject.launch.env にキーごとにマージします。iOS は SIMCTL_CHILD_* で、Android は intent extra で注入します。Web では Playwright のコード生成が読みます
subject.launch.args list[str] [] 起動引数です。ターゲットの subject.launch.args の後ろに追記します。iOS 専用です
subject.launch.deeplink str 未設定(ターゲットの subject.launch.deeplink) 起動後にアプリが開く URL です(iOS は simctl openurl、Android は intent)。Android では、アプリのどのアクティビティも解決できないディープリンクは、am start 自身の理由を付けて起動を失敗させます(BE-0487)
device.ios.locale str 未設定(ターゲットの runsOn.ios.locale) 起動時の locale と言語を強制し(-AppleLocale / -AppleLanguages)、Simulator のシステム言語も固定します。ターゲットと異なる値は cold respawn を強制します
device.ios.seedPhotos list[str] 未設定(ターゲットの runsOn.ios.seedPhotos) erase の経路で、Simulator の写真ライブラリに順に投入する画像です。パスはシナリオファイルを基準に解決します。シナリオのリストはターゲットのリストを置き換えます
device.android.seedPhotos list[str] 未設定(ターゲットの runsOn.android.seedPhotos) デバイスの共有ストレージにある Bajutsu 専用のディレクトリへ順に投入する画像です。どの reinstall の段階でも投入します。パスはシナリオファイルを基準に解決します。シナリオのリストはターゲットのリストを置き換えます
inheritSetup bool true false にすると、このシナリオが宣言する全ターゲットの hooks.setup を省きます。各ターゲットの hooks.cleanup は走ります(後述)

シナリオは、アプリを識別したりビルドしたりするフィールド(id、path、build、startWhen、 idNamespaces)を設定できません。これらはターゲットが持ちます。evidence.secrets はターゲット側の和集合の ままなので、シナリオからは設定できません。

各フィールドは、デバイスを操作する前に、シナリオが動かすターゲットと照合します。 動かすどの ターゲットのプラットフォームにもない subject のフィールドは、無視せずにフィールド名を示して run を 失敗させます。Web だけのシナリオの subject.launch.args が該当します。シナリオの interrupts にある tipKit のエントリも、動かすターゲットに iOS がなければ同じように失敗します。各ターゲットは自分のプラットフォームが持つ subject のフィールドだけを適用します。そのため、iOS と Web をまたぐシナリオは、iOS 側のために subject.launch.args を書けます。単一プラットフォームの複数のターゲットが paths.scenarios から同じ シナリオファイルを読む場合、そのファイルは targets を宣言するか、該当するターゲットだけが読む ディレクトリに置きます。device のブロックは宛先をキーにするので、iOS のターゲットを動かさない シナリオの device.ios は効果を持たず、エラーにもなりません。

シナリオはデバイスの条件を宣言しません。 run を動かす場所はターゲットが決めるので、モデルや OS の 範囲といった条件はターゲットの runsOn に書きます。iPad に しかない画面のシナリオは、iPad で動くターゲットを指定します。

# bajutsu.config.yaml
targets:
  app-ipad:
    platform: ios
    subject: { id: com.example.app }
    runsOn:
      ios: { model: "iPad Pro 13-inch (M4)", os: ">=18" }
# シナリオ
targets: [app-ipad]

そのターゲットにリストや範囲を書くと、ターゲットの各シナリオは複数の run に分かれます。規則は configuration にあります。

以前のリリースは preconditions.runsOn を受け付けていました。 ローダーは現在これを拒否します。 preconditions.runsOn.ios.locale や seedPhotos は失敗し、preconditions.device.ios.<フィールド> を 示します。preconditions.runsOn.ios.model のような条件は失敗し、代わりにそれを宣言するターゲットの パス runsOn.ios.model を示します。

subject.reinstall の解決順は このシナリオ自身の subject.reinstall > ターゲットの subject.reinstall > 組み込みの clean で、その結果を CLI のフラグが動かします (BE-0473、 configuration)。--erase は値を erase にし、 --no-erase は erase を clean に下げ、overwrite と clean はそのままにします。 未設定のシナリオ(多くの場合はこれ)は、ターゲットの config の値を継承します。 _filter_scenarios(run/cli.py)が run の開始前にフラグを反映します。そのため、erase を指定した ターゲットは --no-erase でアプリをアンインストールします。アプリのデータを残したいシナリオは overwrite と書きます。廃止した preconditions.run はロード時に失敗し、エラーメッセージが 各フィールドの移動先を示します(下記)。

iOS の写真の投入には wipe したデバイスが必要です。 重ね合わせたあとの iOS の seedPhotos が空でなければ、 実効の subject.reinstall(シナリオの値、なければターゲットの値に、フラグを反映したもの)が erase である 必要があります。写真ライブラリへの投入は erase の経路でだけ行うからです。ターゲットの subject.reinstall: erase でも条件を満たします。 複数のターゲットを動かすシナリオでは、写真を投入するのはプライマリだけです。重ね合わせたあとの seedPhotos を持つプライマリ以外のターゲットは、run を失敗させます。record、crawl、repl は、 写真を投入するターゲットに対する --no-erase を拒否します。どちらの拒否も、デバイスを操作する前に 終了コード 2 で終わります。Android では erase は要りません。投入先のディレクトリをシナリオごとに 空にするので、reinstall の段階にかかわらず、そのディレクトリには並べた画像だけが入ります。 リストが空のシナリオでも、以前の投入が作ったディレクトリは空にします。 プライマリだけが投入するという規則は Android にも当てはまります。

reinstall: clean は権限状態(permissions。後述)も同時にリセットします。iOS では simctl privacy reset all、Android では pm clear を使います。overwrite はどちらもリセットしません。overwrite は シナリオ間でデータを保持するために存在し、権限の許可状態もその保持対象に含まれるため、overwrite では前のシナリオが許可した権限がそのまま見え続けます。

BE-0452、BE-0469、BE-0473 より前に保存した run も読み込めます。 シナリオのローダーは、古い平坦なキーを 拒否します。対象は erase、reinstall、launchEnv、launchArgs、deeplink、locale、seedPhotos です。トップレベルの systemAlertHandling と iosTipKitHandling、preconditions.runsOn、preconditions.run も拒否します。 どのメッセージも、キーの移動先を示します。run ディレクトリをオフラインで読む処理は、保存された scenario.yaml のほうを読み替えます。該当するのは、レポートの再描画、trace、triage です。保存された preconditions.runsOn は、iOS の locale と seedPhotos を device.ios に移し、条件を捨てます。 条件は、その run が使うデバイスをすでに選び終えているからです。保存された preconditions.erase や preconditions.run.erase: true は subject.reinstall: erase になり、保存された false は捨てます。 保存された preconditions.run.systemAlertHandling は、ルールごとにシナリオの interrupts の systemAlert のエントリになります。保存された tipKitHandling は tipKit のエントリになり、 保存された inheritSetup は preconditions.inheritSetup に移ります。

どの環境でも、すべての前提条件を適用できるわけではありません。実機の iPhone では simctl erase を実行できず、 ブラウザには subject.launch.env を渡すアプリの起動がありません。ターゲットの環境が前提条件を適用できないとき、 シナリオはデバイスを使う前に失敗します。ターゲットは、その前提条件の無視を宣言できます (設定)。bajutsu lint --config <file> --target <name> は、 同じ指摘をデバイスなしで報告します(cli)。

tipKit(操作をブロックする TipKit の tip)

シナリオの interrupts に - tipKit: dismiss と書くと、操作をブロックしている Apple TipKit の tip を閉じます。 tip はフレームワークが所有する popover です。このガードがあれば、同じ回避策をシナリオごとに手で書かずに 済みます。ガードは tip を、閉じるための scrim(PopoverDismissRegion)とその tip 自身のコンテナ (TipView)の両方で判定します。ごく普通の confirmationDialog も同一の scrim を設置するので、 そちらには手を触れないようにする必要があるからです。同じ理由で、tip 向けの interrupts エントリを 手で書く場合は TipView を手がかりにします。TipView は TipKit 自身のコンテナです。SwiftUI と UIKit のどちらの表示でも、存在を計測で確認済みです。このガードは iOS 専用で、既定はオフです。 tip 自体がシナリオの検証対象になる場合があるからです。

- name: open the catalog past a blocking tip
  interrupts:
    - tipKit: dismiss
  steps:
    - tap: { id: catalog.open }

ターゲットの hooks.interrupts に同じエントリを書くと、そのターゲットのすべてのシナリオでガードが オンになります。シナリオがエントリを書いた場合は、ターゲットのエントリよりシナリオのものが優先します。 tip を検証するシナリオは - tipKit: leave と書いて、ターゲットの dismiss をオフにします。どちらにも エントリがなければ、ガードはオフのままです。CLI の --ios-tipkit-handling / --no-ios-tipkit-handling は、すべてのシナリオのエントリを dismiss または leave に設定します。

systemAlert(システムアラートガード)

interrupts のリストに書く systemAlert のエントリは、OS のプロンプトと、run がそれに返す答えを名指しします。このエントリは、シナリオ自身のトップレベルの interrupts にも、ターゲットの hooks.interrupts にも書けます(設定)。

iOS バックエンドは SpringBoard レベルのプロンプト(通知や App Tracking Transparency のリクエスト、"Allow Paste" など)を見ることも tap することもできません。これらのプロンプトはアプリを覆って要素ツリーを潰し、ステップを静かにブロックします。アラートガードがこれをリアクティブに片付けます。

iOS の XCUITest バックエンドでは、ガードは決定論的なネイティブ経路をとります(BE-0315)。BE-0316 の SpringBoard 照会を再利用してアラートが提示するボタンを把握し、systemAlert のエントリが名指しするボタンを押します。スクリーンショットもモデルへの往復も使わないため、頻出するプロンプトを 0.1 秒を大きく下回る時間で片付け、ANTHROPIC_API_KEY がなくても動作します。

決定論的な経路がどれも対処できない場合、ガードは何もしません(BE-0402)。該当するのは次の3つです。capability を持たないバックエンド、どのエントリも同定しないアラート、そして SpringBoard の照会が列挙できずどのエントリも同定しない画面です。エントリが同定する画面は、後述のツリー内の経路が片付けます。

ブロックされたステップまたは wait は、ガードを設定していないときとまったく同じように自身のタイムアウトまで進みます。そのタイムアウトがガードの見たものを名指しします。形は wait timeout: for {'id': 'submit'} (10.0s) — an unhandled system alert is blocking the screen (buttons: Allow, Don't Allow) です。何も列挙できなかった場合は、曖昧な … — the screen appears blocked, possibly by a system alert or another overlay outside the app's view になります。

BE-0402 より前は、capability を持たないバックエンド、どのエントリも同定しないアラート、列挙できない画面のどれでもスクリーンショットを読む AI 視覚ガードへフォールバックしていました。run はもうそれをしないため、どのフラグを付けてもモデルに到達しません。(record と crawl はオーサリング向けにそのガードを保持します。詳細)

wait ステップ(for/gone/settled/screenChanged)では、ガードは wait の途中でも働きます。XCUITest では wait 自身のツリー読み取りのたびに、ツリーを返す前にエントリが名指しするプロンプトへ答えます。SpringBoard の確認は pollInterval(既定は 1 秒)につき 1 回までです(BE-0461)。そのため wait 自体のタイムアウトを待たず、ステップが失敗する前に回復できます(BE-0269)。

XCUITest バックエンドでは、画面が止まったときに for と screenChanged の wait を早めに打ち切ります。止まった画面とは、読み取り自身の SpringBoard 確認がアラートなしと答えているのに、アプリケーション自身を除くどの要素も、ラベルと識別子のどちらも 10 秒間持たない状態です。iOS 26.5 の Simulator で、この状態を計測しました。iOS が Save Password アラートを提示する瞬間に通知の許諾リクエストが重なると、このアラートが提示の途中で止まることがあります。止まったアラートは描画されず、どのプロセスのアクセシビリティツリーにも現れませんが、アプリの上でモーダルのまま残ります。ガードが届く手段ではこのアラートを閉じられないため、wait は自身のタイムアウトまで待たずに、次の理由で失敗します。

wait stopped: for {'id': 'Close'} after 10.4s — no element below the application has carried a label or identifier for 10s while no system alert is up — …

この打ち切りは、savePassword のようなアプリ内のプロンプトを systemAlert のエントリで宣言したシナリオに限ります。それ以外のシナリオでは、長く空のツリーがアプリ自身のラベルのない読み込み画面である可能性があるため、wait は従来どおり自身のタイムアウトまで待ちます。ラベルのない読み込み画面が 10 秒を超えうるアプリでは、そのエントリの frozenScreenTimeout で上限を延ばせます。0 を指定すると打ち切りは無効になります。gone と settled の wait は、止まったツリーで条件を満たしてしまうため、この打ち切りの対象外です。handleSystemAlert ステップも対象外です。このステップは SpringBoard を待っており、プロンプトがあとから出る可能性があるためです。

このガードは 既定で ON です。XCUITest ではステップがすでに行う読み取りに相乗りし、成功するステップは再試行を受けません。そのため、成功するシナリオが払うのは pollInterval あたり最大 1 回の SpringBoard 確認だけです。ANTHROPIC_API_KEY は不要で、参照もしません。ガードをオフにするシナリオやターゲットのキーはありません。run 全体でオフにするには bajutsu run --no-system-alert-handling を使います。シナリオは、ガードに答えさせるプロンプトを、自身のトップレベルの interrupts に systemAlert のエントリとして宣言します。このエントリはターゲットの hooks.interrupts の上に重なります(後述)。

systemAlert のエントリがガードの宣言のすべてです(BE-0406、BE-0473)。シナリオは、現れると見込むプロンプトと、それぞれに返す選択を書きます。どの応答経路も、その宣言だけを見て一致を判定します。BE-0401 が導入した順序付きの labels は BE-0406 で削除しました。ボタンのラベルが名指しするのはボタンであって、そのボタンが載っているアラートではありません。「Cancel」も「Close」もアプリの通常の語彙ですから、ラベルはシナリオが記述していない画面へのタップまで許してしまっていたのです。record と crawl はオーサリング向けに自由記述の視覚の指示を残していますが、それを読むのは自身の --alert-vision-instruction フラグからだけで、シナリオや config からは読みません。

エントリは、プロンプトを表す systemAlert と、答えを表す choice を持ちます。任意のキーが 2 つあり、ガードを調整します。次の表の各行は、シナリオのトップレベルの interrupts に書く 1 つのエントリです。

エントリ 意味
(systemAlert のエントリなし) シナリオ自身はどのプロンプトにも答えない。ターゲットのエントリは引き続き有効で、どのエントリも名指ししないアラートは、ブロックされたステップの失敗理由に書き出す
{ systemAlert: notifications, choice: grant } 名指しした対応済みプロンプトに、他のプロンプトとどのラベルを共有していても、そのエントリ自身の選択で答える
{ systemAlert: notifications, choice: leave } そのプロンプトには、ターゲットのエントリが答える場合でも何も答えない
{ systemAlert: notifications, choice: grant, pollInterval: 2 } さらに、SpringBoard の確認を既定の 1 秒ではなく最大 2 秒に 1 回にする
{ systemAlert: savePassword, choice: deny, frozenScreenTimeout: 30 } さらに、ガード対象の wait が止まった画面で打ち切るまでの時間を、デフォルトの 10 秒ではなく 30 秒にする(0 で打ち切りを無効にする)。savePassword のように、アプリ自身の要素ツリーに出るプロンプトにだけ書ける
- name: grant notification permission
  interrupts:
    - systemAlert: notifications
      choice: grant       # accept the prompt instead of leaving it alone
  steps:
    - tap:  { id: sys.requestNotif }
    - wait: { for: { id: sys.notif.authorized }, timeout: 4 }   # the guard taps Allow, then this passes

choice: leave は、シナリオ自身の handleSystemAlert ステップが答えていることを示すために使います。このエントリはそのプロンプト 1 つについてだけターゲットの答えをオフにし、ターゲットが答える他のプロンプトはそのシナリオでも引き続き有効です。

ツリー内のタップで届くプロンプトにエントリを書くと、iOS ではもう 1 つ、ツリー内の経路も有効になります。相手は SpringBoard のアラートではありません。いま対応しているのは savePassword の 1 つだけです。iOS はこの「パスワードを保存」アラートをアプリ自身のプロセスに出すので、そのボタンはラベルを持ち識別子を持たない形で要素ツリーに現れ、SpringBoard の照会には決して映りません。つまりツリー内のタップだけが、これを片付けられます。

runner はこのタップを読み取りの中で行い、しかも同じ読み取りでの新たな SpringBoard 確認が空だったときに限ります。XCUITest は要素への操作を合成する前に、割り込んでいるプロセス外のアラートを解決してしまい、アプリのツリーからはそのアラートが見えないからです。したがって 2 つのプロンプトが同時に出ているときは、まず SpringBoard のアラートに答え、そのあとでアプリ側のアラートをツリーから片付けます。

割り込んできたアラートがどのボタンを受け取るかも、利用者の方針が決めます。XCUITest は割り込まれた操作より先にそのアラートを解決し、放っておけばアラート自身のデフォルトボタンで答えます。エントリが拒否したはずの権限を許可し、しかも実行結果には何も残りません。そこで runner は、エントリが名指ししたボタンを押す割り込み監視を入れます。判定の作法はネイティブ経路と同じで、押した結果は通常のアラートイベントとして報告されます。この監視が決して出会えないエントリは、送らずに落とします。savePassword は別プロセスの操作に割り込むことがないからです。どのエントリも同定しないアラートは、従来どおり XCUITest 自身の既定ハンドラに委ねられ、この tap 自体は変えられません。変わるのは沈黙のほうです。その割り込みに遭遇したステップや expect は、作者に代わって何かが答えたかのように続けるのではなく、アラートが差し出したボタン名を添えて失敗します。 (demos/showcase/scenarios/save_password_browser.yaml 実物)

エントリが名指しするのはプロンプトです。ガードは、そのプロンプトを画面上で同定できたときにだけ押します。同定に使うラベルがすべて、それぞれちょうど 1 つずつ揃っている必要があります。どのエントリも同定しなかったアラートには手を触れず、ブロックされたステップ自身の失敗理由に書き出します。当て推量のボタンを押すことはありません。

CLI の --no-system-alert-handling フラグは全シナリオでガードをオフにし、--system-alert-handling はオンのままにします。--alert-poll-interval は、その run にだけ pollInterval を与えます。入る位置はシナリオとターゲット config の中間です(後述の層の重ね方を参照)。 (demos/showcase/scenarios/permission.yaml 実物)

プロンプトに答える代わりに出さないようにする

アプリが出さないプロンプトには、答える必要がありません。テスト中にアプリが自分のプロンプトを省くための方法として、ターゲットの config(targets.<name>)の起動引数または環境変数(subject.launch.args と subject.launch.env)を用意しています。アプリは起動時にそれを読みます。

targets:
  my-app:
    platform: ios
    subject:
      id: com.example.myapp
      launch: { env: { UITEST_SKIP_ONBOARDING_PROMPTS: "1" } }   # the app checks this and asks nothing

出さないようにすればガードの出番は減りますが、ガードの代わりにはなりません。次の 3 つのプロンプトは、引き続きリアクティブに答えます。

  • 通知は、xcrun simctl privacy が許可できるプライバシーサービスではありません(BE-0276)。
  • App Tracking Transparency(ATT)も、simctl privacy のサービスにはありません。このコマンド自身のサービス一覧に載っていないことを確認しています。
  • パスワードの保存は、Simulator の「パスワードを自動入力」の設定に左右されます。実行前にこの設定を切る、サポートされた方法は見つかりませんでした。そのためシナリオは savePassword のエントリで答えます(BE-0461)。

通知バナーはタップせずスワイプで消す

フォアグラウンドの通知バナーは、システムアラートと同じようにステップへ割り込みます。答えるのも同じ割り込み監視です。ただし systemAlert のエントリが答えることはありません(BE-0416)。

バナーはアラートではありません。エントリが名指しできるボタンを 1 つも持ちません。タップできる領域は 1 つだけで、そこに載っているのは通知本文です。その領域を押すと通知元のアプリが開き、実行中のシナリオから離れてしまいます。

そこで runner は、バナー自身の実測フレームを起点に上方向へスワイプします。runner がそのフレームを読むのは、バナーが静止してからです。滑り込んでいる途中のバナーはフレームが画面より上にあり、そこを起点にしたスワイプは下向きに動いてしまうからです。そのうえで、割り込みを引き受けたと宣言する前に、バナーが消えたことを確認します。バナーが消えれば、ステップの操作はシナリオが名指しした要素に着弾します。

スワイプでバナーが消えなかった場合、runner はバナーが自動的に消えるのを最大 10 秒待ちます。割り込みを XCUITest に返すのは最後の手段です。iOS 26.5 では、XCUITest 自身のハンドラはバナーを無視します。XCUITest がバナーを探すたびに失敗が記録され、その失敗が runner のセッションを終わらせます。

消えたことを確認できた場合に限り、割り込まれたステップの記録として実行結果に残ります。種別はアラートとは別に立てます。押したボタンが存在しないので、並んで記録される文字列は通知本文そのものです。この種別があることで、読み手はその文字列をガードが選んだボタンだと読み違えずに済みます。

10 秒待ってもまだ表示されているバナーは、この記録を残しません。runner 自身の出力にログを書き、バナーを XCUITest に返します。一時的な形式のバナーは、たいていこの待機のうちに消えます。一方、常駐する形式のバナーは自動では消えないため、XCUITest への引き渡しに至ることがあります。iOS 26.5 では、返すことで runner が止まる場合もあります。

バナーについて宣言できることは何もありません。この経路は、システムアラートガードがオンかどうかにかかわらず動きます。BE-0416 より前は、ガードが有効な実行でバナーがアラート経路に入っていました。どのエントリにも一致せず、ステップは失敗しました。その理由には、期待したボタンとして通知本文が並びました。

この割り込み監視が答えるのは、何かに割り込んでいるバナーだけです。ただの問い合わせでは監視は起動しないため、何もタップしていない画面に居座るバナーは消えません。放置すると、after.png と、そこから作るビジュアルリグレッションの比較画像がそのまま壊れます。

この隙間を塞ぐのが、もう 1 つの能動的な掃除です。runner はバナーがないかを確認し、あればスクリーンショットを撮る直前にスワイプで消します。確認するのは 3 か所です。1 ステップにつき 1 回のそのスクリーンショット、visual アサーションが読む expect フェーズの撮影、そしてステップ自身の assert が持つ visual エントリ自身の撮影です(後述)。ステップごとの掃除は、その照会をシステムアラートガード自身が解決したポーリング間隔でレート制限しているため、通るシナリオが払うコストはステップごとではなく間隔ごとに 1 回です。expect フェーズとステップレベルの撮影は、それぞれステップよりずっと少ない頻度でしか動かないため、無条件に照会します。上記の割り込み経路と同じく、この 3 か所とも、シナリオや CLI 側のトグルは持たず、iOS の XCUITest バックエンドだけで動きます。

複数のプロンプトに違う答えを返す

1 つのオンボーディングの流れが複数のプロンプトに出会い、それぞれに違う答えを返したい場面はよくあります。1 つの systemAlert のエントリは、対応済みのプロンプト 1 つと選択 1 つを組にします。語彙は handleSystemAlert 自身の prompt / choice をそのまま再利用します。こうして、ファイルには「押されても構わない語」ではなく「現れると見込むプロンプト」が書かれます。

- name: onboarding — accept notifications, refuse tracking
  interrupts:
    - systemAlert: notifications
      choice: grant
    - systemAlert: tracking
      choice: deny
  steps:
    - tap:  { id: onboarding.start }
    - wait: { for: { id: home.title }, timeout: 10 }

ガードは、エントリの順序ではなく、そのエントリのプロンプトから画面上のどのアラートかを同定します。そのプロンプトを同定するラベルが、実行時のロケールで解決した形でアラート上に揃っていなければなりません。1 つのリストに同じプロンプトを指定するエントリが 2 つあると、読み込み時に失敗します。文脈や iOS のバージョンで見え方が変わるプロンプトは、その見え方の数だけ照合用の形を持ちます。ですから 1 つのエントリのままで、そのプロンプトのどの見え方にも答えます。

どのエントリも同定しなかったアラート、つまりラベル表の外にあるものや、どちらの応答経路も持たないバックエンド上のあらゆるアラートには手を触れず、ブロックされたステップ自身の失敗理由に書き出します。この沈黙こそが狙いです。ガードが答えるのは、シナリオが記述した画面だけになります。

すべてのプロンプトがすべての経路に届くわけではありません。 ラベル表は、プロンプトごとに、3 つの面のうちどれで宣言し応答できるかを記録しています。

prompt handleSystemAlert ステップ ガードのネイティブ SpringBoard 照会 ガードのツリー内タップ
notifications ✅ ✅ —
tracking ✅ ✅ —
paste ✅ ✅ —
savePassword — — ✅
localNetwork ✅ ✅ —

savePassword 以外は SpringBoard が持ち主なので、ステップとネイティブ照会の両方が届き、ツリーには現れません。savePassword はちょうど裏返しです。iOS がアプリ自身のプロセスに出すため springboard.alerts は決して列挙できず、ツリー内のタップだけが片付けられます。したがって savePassword を名指しした handleSystemAlert ステップは解析時に拒否されます。このステップは SpringBoard の照会しか読まないので、空のボタン一覧を締め切りまでポーリングするしかないからです(BE-0406)。

localNetwork は、iOS のローカルネットワークの許可を求めるプロンプトです。実機では、アプリが初めてホストへ報告するときに、Bajutsu 自身のネットワークの collector がこのプロンプトを出させます(iOS を実機とデバイスクラウドで動かすを参照してください)。ボタンは通知のプロンプトと同じなので、ボタンだけでは 2 つを区別できません。そこでガードはアラートのタイトルも読みます。タイトルは、アプリ名を %@ に置き換えた Apple の雛形にそろえます。localNetwork のエントリはこの雛形を識別に使い、notifications のエントリはこの雛形を除外します。したがって、notifications のエントリがローカルネットワークのプロンプトに答えることはなく、逆も同じです。ネットワークのやり取りを記録する実機のターゲットは、ほかのプロンプトと同じように宣言します。

interrupts:
  - { systemAlert: localNetwork, choice: grant }

アプリはこのプロンプトを起動中に、つまりシナリオの最初の手順より前に出します。ガードが最初に確認するのは本来、保留中の待機の中なので、最初の tap がプロンプトに当たることがあります。そこでガードは、最初の手順の前に SpringBoard の照会を 1 回だけ読み、すでに出ている宣言済みのプロンプトに答えます。

この確認はネイティブの経路だけを使います。アプリ自身のボタンはタップせず、宣言されていないアラートにも手を出しません。最初の手順が handleSystemAlert のときは、その手順のプロンプトを手順自身に残します。手順はエントリとは逆の選択をすることもあるからです。手順は prompt でプロンプトを名指しするので、見た目の似たプロンプトはタイトルで区別できます。そのため、notifications の手順より前に出たローカルネットワークのプロンプトには、これまでどおりエントリが答えます。sel で書いた手順はプロンプトを名指ししないので、この確認を省きます。

handleSystemAlert の手順も、同じようにタイトルを確かめます。notifications を名指しした手順は、ボタンが同じでも、ローカルネットワークのプロンプトを押しません。

他の 4 つのプロンプトが 1 通りの見え方しか持たないのに対し、savePassword は 3 通りの見え方を持ちます。

見え方 英語 日本語
Web フォーム Save Password / Never for This Website / Not Now パスワードを保存 / このWebサイトでは保存しない / 今はしない
アプリ自身の入力欄、iOS 18.6 Save Password / Not Now パスワードを保存 / 今はしない
アプリ自身の入力欄、iOS 26.5 Save / Not Now 保存 / 今はしない

それでも 1 つのエントリで 3 通りすべてを覆えます。choice: grant は動く許可側のボタンに追随し、choice: deny は拒否側のボタンを押します。拒否側はどの見え方でも「今はしない」です。対応している言語は、他のプロンプトと同じく英語と日本語です。

層の重ね方:1 つのキーは 3 か所から届く

宣言は、シナリオ、コマンドライン、ターゲット config の 3 か所から run に届きます(BE-0177、BE-0473)。シナリオ自身の interrupts とターゲットの hooks.interrupts は同じ 3 つの形を受け付け、形ごとに合わさり方が決まっています。

エントリの形 ターゲットとシナリオのエントリの合わさり方
画面 連結する。ターゲットのエントリが先
システムアラート プロンプトごとに決まる。シナリオのエントリはそのプロンプトについてターゲットの choice を置き換え、省略した frozenScreenTimeout はターゲットのエントリから引き継ぐ。それ以外のプロンプトは両方のものが有効
TipKit シナリオのエントリ(dismiss か leave)、なければターゲットのエントリ。どちらにもなければオフ

2 つの調整値は別の規則で決まります。ガードはシナリオごとにそれぞれ 1 つの値しか持たないからです。

値 層の合わせ方
pollInterval 値を持つ最初の層が勝つ。順序はシナリオ、--alert-poll-interval、ターゲット。1 つの層の中では最小の値が勝つ。短い間隔は、より長い間隔を求めたエントリの要求も満たすからである。ビルトイン既定は 1 秒
frozenScreenTimeout プロンプトに答えるエントリのうち、もっとも寛容な値。つまり最大の値で、0(停止オフ)はどの値よりも優先する。より厳しい上限は、別のエントリのアプリがそれだけ長く保つと宣言した画面で wait を止めてしまう。ビルトイン既定は 10 秒
ON / OFF --no-system-alert-handling が全シナリオでガードをオフにする。シナリオやターゲットのキーではオフにできない。--ios-tipkit-handling / --no-ios-tipkit-handling は、全シナリオの tipKit のエントリを dismiss または leave にする

宣言が来た層ではなく、限定の度合いが衝突を決めます。ターゲット config の tracking プロンプト向けのエントリは、シナリオが notifications のエントリしか書いていなくても tracking に答えます。どのエントリも、名指しした 1 つのプロンプトにだけ届くからです。両方の宣言が有効なままです。ターゲットのエントリを上書きするには、シナリオ側に同じプロンプトのエントリを書きます。上書きが及ぶ範囲は、名指しした 1 つのプロンプトだけです。何も答えずに上書きしたいときは choice: leave を使います。廃止された systemAlertHandling: false と違い、このエントリは答えないプロンプトを名指しします。そのため、ターゲットがあとから追加したプロンプトは、そのシナリオにも引き続き適用されます。自前の systemAlert のエントリを持つシナリオにターゲットのエントリが実際に答えるとき、run はそのプロンプトを名指しする通知を出します。通知は、影響を受けたシナリオとプロンプトの組ごとに 1 回だけ出ます。

旧来のキーからの移行

BE-0401、BE-0406、BE-0473 は下記のキーをエイリアスなしで削除しました。書いた内容と違う挙動に解釈されるのではなく、置き換え先を名指しするエラーで読み込みに失敗します。変更前に保存した run ディレクトリは、オフラインで読む処理(レポートの再描画、trace、triage)が scenario.yaml を新しいキーに読み替えるので、引き続き読み込めます。

削除されたもの 代わりに書くもの
preconditions.run.systemAlertHandling: { rules: [{ prompt: notifications, choice: grant }] } シナリオの interrupts の - { systemAlert: notifications, choice: grant }(BE-0473)
preconditions.run.systemAlertHandling: false シナリオ自身が答えるプロンプトごとの choice: leave。run 全体なら --no-system-alert-handling(BE-0473)
systemAlertHandling.pollInterval / .frozenScreenTimeout 同じキーを、その値が属する systemAlert のエントリに書く(BE-0473)
preconditions.run.tipKitHandling: true / false シナリオの interrupts の - tipKit: dismiss / - tipKit: leave(BE-0473)
preconditions.run.inheritSetup preconditions.inheritSetup(BE-0473)
visionInstruction なし。run はモデルに到達せず(BE-0402)、record / crawl は --alert-vision-instruction を使う
labels: ["Allow"] - { systemAlert: notifications, choice: grant } — ラベルはどのプロンプトも名指ししていなかったので、現れると見込むプロンプトを書く(BE-0406)
instruction: ["Allow"] 同じエントリの形。BE-0401 がこのキーを labels に改名し、BE-0406 がその labels を削除した
instruction: "tap Allow" 同じエントリの形。BE-0401 の改名先は visionInstruction だが、BE-0402 でどのコマンドにも届かなくなった
シナリオのトップレベルの systemAlertHandling: / alertHandling: / dismissAlerts: シナリオの interrupts の systemAlert のエントリ
シナリオのトップレベルの iosTipKitHandling: シナリオの interrupts の - tipKit: dismiss
--alert-labels "Allow,OK" / --alert-instruction "Allow,OK" シナリオまたはターゲット config の systemAlert のエントリ。プロンプトと選択の組をフラグの値 1 つで読みやすく運べないため、フラグは無い。serve の HTTP API に alertLabels を載せた run リクエストは 400 で拒否される
--alert-instruction "tap Allow" --alert-vision-instruction "tap Allow"(record / crawl 専用。run は BE-0402 で廃止)
--alert-handling / --dismiss-alerts --system-alert-handling

このリアクティブなガードと、下記のプロアクティブな handleSystemAlert ステップは、SpringBoard が持つプロンプトについては同じネイティブ機構(BE-0316 の照会と tap)を共有します。違うのはいつ発火するかです。ガードはプロンプトが現れた場所で自動的に、ステップは作者が置いた 1 か所で発火します。

handleSystemAlert(決定的なシステムアラートステップ)

上記の systemAlert のガードはリアクティブです。プロンプトが現れた場所で自動的に発火します。handleSystemAlert はそのプロアクティブな対の一方です。プロンプトが現れると見込んだ地点に作者が明示的に置く決定的なステップで、プロンプトのボタンをネイティブなアクセシビリティ照会で tap します。スクリーンショットもモデル呼び出しもありません(BE-0316)。リクエストと許可の流れ自体をテストしたいときに使います。OS の権限リクエストを発火させ、続いて現れるプロンプトを決定的に許可または拒否します。

- name: grant the notification prompt mid-flow
  steps:
    - tap: { id: perm.requestNotif }                              # OS の権限リクエストを発火させる
    - handleSystemAlert: { sel: { label: "Allow" }, timeout: 5 }  # プロンプトのボタンを label で tap する
    - wait: { for: { id: perm.notif.authorized }, timeout: 5 }    # 許可され、アプリの状態が更新される

許可ではなく拒否するには、拒否側のボタンを指定します(handleSystemAlert: { sel: { label: "Don't Allow" }, timeout: 5 })。

  • sel は label 系のみです。 SpringBoard のアラートボタンは、アプリが割り当てた identifier も trait も value も持たず、見えているテキストしか持ちません。そのため sel は label / labelMatches / index を受け付け、id / idMatches / traits / value / within はパース時に拒否します。
  • run が一致させるべき label は、ターゲットの runsOn.ios.locale が描画するものです。 プロンプトを所有しているのは SpringBoard なので、以前は Simulator がたまたま持っていたシステム言語で描画されていました。つまり label: "Allow" が通るのは英語の環境だけで、日本語の環境では失敗しました。現在は、アプリを起動する前に Simulator 自身のシステム言語をその locale に固定するため、CI でも、同僚の Mac でも、コントリビューターの Simulator でも、label / labelMatches は同じように解決します(BE-0320)。
  • timeout は必須です。 wait とまったく同じで、プロンプトを待つ条件待機には明示的な上限が要ります。ステップはプロンプトを待ち込んでから tap します。固定の sleep はありません。
  • 待っているあいだもリアクティブなガードが動きます(BE-0406)。この待機を持っているのはバックエンドではなくランナー自身です。そのためシステムアラートガードは、ステップがタイムアウトして失敗したあとではなく、ステップの最中に割り込みを片付けます。これが効くのは、別のプロンプトが先に画面を取ってしまった場面です。iOS のパスワード保存アラートはアプリ自身のプロセスから出るので SpringBoard の照会からは見えず、画面を覆ったまま、このステップが待っているプロンプトを iOS に出させません。ここでガードが動かなければ、ステップは timeout を使い切り、一度も見ていない権限プロンプトを名指しして失敗します。ガードはこのステップ自身のプロンプトには手を触れないので、シナリオが同じプロンプトに反対の choice を持つ systemAlert のエントリを書いていても、決めるのはステップのほうです。
  • 0 件のときと複数件のときは、どちらも失敗します。 timeout 以内にプロンプトが現れなければステップは失敗します。label に一致するボタンを複数見つけたときは曖昧と見なし、index で n 番目を選んだ場合を除いてタップしません。あらゆるセレクタが従う規則を、アラートのボタンに当てはめたものです。曖昧さは即座の失敗にはせず、期限までポーリングします。再描画で解消することがあるからです。期限の時点でも重複が残っていれば、ステップはその旨を述べて失敗します。タイムアウトはステップが実際に見たものを名指しします。何も出ていなかったのか、セレクタの名指ししないアラートだったのか、label を 2 つ持つアラートだったのかを、次のように書き分けます。
no system alert appeared within 5.0s: {'label': 'Allow'}
no system alert button matching {'label': 'Allow'} appeared within 5.0s (the alert on screen offered: Save Password, Not Now)
system alert button {'label': 'Allow'} is ambiguous and stayed ambiguous for 5.0s (the alert on screen offered: Allow, Allow) — add index to pick one

ガードが片付けられないプロンプトに出会っていれば、ブロックされた wait と同じように、ガード自身の注記も添えられます。 - iOS(XCUITest)専用です。 この能力を宣言するのは iOS バックエンドだけなので、Android や web バックエンドに対して handleSystemAlert を指定したシナリオは、デバイスを操作する前の preflight で失敗します。Android はシステムダイアログを通常の要素ツリーに出すため、そこでは素の tap で届きます。web バックエンドには OS レベルのプロンプト自体がありません。

handleSystemAlert と、隣り合う 2 つのアラート系フィールドのどちらを選ぶかの目安を次に示します。

フィールド 用途 タイミング 仕組み
permissions そもそも避けられる OS 権限プロンプト 起動前、アプリが動き出す前 決定的なデバイス操作
handleSystemAlert 既知の、途中で tap するつもりのプロンプト 作者が置いた明示的なステップ 決定的(ネイティブなアクセシビリティ tap)
interrupts の systemAlert のエントリ 想定外のプロンプト。プロセス外のものと、プロセス内のパスワード保存シート ステップや wait がブロックされたときに反応 XCUITest ではネイティブの SpringBoard 照会(モデルなし、BE-0316 を再利用)と、その照会に映らないシートへのツリー内タップ。どのエントリも同定しないプロンプトは失敗理由に書き出す

テキストではなく意図で指定する

permissions では先回りできないプロンプトが 3 つあります。通知の許可、App Tracking Transparency(ATT)、そしてプロセスをまたぐペーストの同意です。通知の許可は Transparency, Consent, and Control(TCC)のサービスではなく、ATT には simctl の切り替え手段がまったくありません。ペーストの同意を iOS は TCC の kTCCServicePasteboard として記録しますが、このサービスにも simctl の切り替え手段はありません(BE-0369)。この 3 つについては、sel の代わりに prompt と choice を指定できます。固定した locale が描画する label は run が解決します(BE-0320)。

- handleSystemAlert: { prompt: notifications, choice: grant, timeout: 5 }

prompt は notifications、tracking、paste、localNetwork のいずれかで、choice は grant か deny です。ボタンを押さないステップには意味がないので、ステップは choice: leave を読み込むときに拒否します。leave は systemAlert のエントリだけが取る値です。ガード自身の systemAlert のエントリは、このステップが取れないプロンプト savePassword も取ります。ステップのほうは解析時にこれを拒否します(上記の面の一覧を参照)。ボタンを意味で指定するため、同じファイルが en_US でも ja_JP でもプロンプトを許可します。どちらの言語のテキストも作者が書き写す必要はありません。これは英語だけを使う場合にも役立ちます。英語の拒否ボタンのアポストロフィは、手で打った label が持つ ASCII 文字ではなく、活字体のアポストロフィ(Don’t Allow、Don’t Allow Paste)だからです。

label の対応表が扱う言語は英語と日本語です。それ以外の言語では、ステップはボタンの位置で答えます(BE-0445)。3 つのプロンプトのどれでも、SpringBoard は拒否側のボタンを 1 番目に、許可側のボタンを 2 番目に並べます。この並びは、英語と日本語では iOS 18.6 と 26.5 で、アラビア語では 26.5 で、各ボタンを実際に押してアプリに残る許可状態を読み取って確かめたものです。

ここでいう並びは SpringBoard が報告する順序で、画面上の左右ではありません。アラビア語では通知プロンプトの拒否側のボタンが右側に描かれますが、報告される順序ではやはり 1 番目です。したがって choice: grant は 2 つのうち 2 番目のボタンを、choice: deny は 1 番目のボタンを押します。

ボタンの数が 2 つでないアラートには、この規則は何も指しません。その場合ステップはタイムアウトまで待ち、見えたボタンを挙げて失敗します。規則を測っていないアラートで、位置だけを頼りに押すわけにはいかないからです。

この規則が指すのはボタンで、プロンプトではありません。SpringBoard のタイトルとメッセージも言語ごとに訳されるので、言語が変わっても 2 ボタンのプロンプト同士を見分けられる手がかりはありません。ステップが待っているあいだに出た 2 ボタンの SpringBoard アラートは、どれも位置で答えられます。ステップは、プロンプトを出す操作の直後に置いてください。

locale を持たない呼び出し(record の再生)も同じ規則で答えます。ステップのレポート行には、押したボタンと、それを選んだ規則(sel、label table: <locale>、position: button 2 of 2 のいずれか)が出ます。ほかのアラートは、これまでどおり sel でボタンを指定します。

位置の規則を使うのはこのステップだけです。systemAlert のエントリは、宣言したどのプロンプトが画面に出ているかを先に見分ける必要があり、位置からはそれを見分けられません。そのため対応表にない言語では、ガードのエントリはこれまでどおり、デバイスを操作する前に扱える言語を名指ししてシナリオを失敗させます。

使う前に知っておきたい制限が 2 つあります。

  • Simulator 専用です。 言語の固定は simctl の操作なので、runsOn.ios.kind: device の target は実機が持つシステム言語のまま動きます。この形では、画面に出ている保証のない label を解決してしまいます。実機ではボタンを sel.label で指定してください。
  • 割り込み監視も英語を前提としていません。 systemAlert のエントリは、監視に届く前に固定した言語向けラベルへ解決されており、その背後にはもう組み込みのフォールバック一覧がありません。どのエントリも同定しないアラートは、どの locale でも常に辞退されます。その割り込みに遭遇したステップや expect は、ボタンを推測する代わりに、差し出されたボタン名を添えて失敗します。run 自身に決めさせたいプロンプトには、エントリを書いてください。

(実物は demos/showcase/scenarios/permission_system_alert.yaml と demos/showcase/scenarios/paste_system_alert.yaml)

permissions(起動前の権限状態)

システムアラートガードは権限プロンプトが現れた後にしか反応せず、できるのは tap だけです。権限を取り消すことも、アプリが既知の状態から起動することを保証することもできません。権限があらかじめわかっている場合、permissions を使えばアプリのプロセスが起動する前にその状態を設定できるため、プロンプトはそもそも現れません。モデルを一切呼ばない、決定的でマシンチェック可能なデバイス操作です(BE-0276)。

- name: profile — camera already granted
  permissions:
    camera: grant
    location: grant
    contacts: revoke
  steps:
    - tap: { id: profile.avatar.upload }   # no camera-permission prompt — already granted

各エントリは <service>: grant | revoke の形を取ります。<service> はバックエンドに依存しない小さな語彙で、location、camera、microphone、contacts、photos、calendar、notifications のいずれかです。各バックエンドは、この語彙をそれぞれのネイティブな仕組みにマップします。

  • iOS は simctl privacy <udid> <grant|revoke> <tcc-service> <bundle> を実行します。SpringBoard の権限プロンプトが参照するのと同じ TCC(Transparency, Consent, and Control)データベースです。
  • Android は pm grant / pm revoke を実行し、config レベルの subject.grantPermissions リスト(drivers)を支える仕組みを再利用します。シナリオの permissions は、この config レベルの既定の上に重なり、config が許可した権限を取り消すこともできます。

iOS には notifications に対応する TCC サービスがありません(iOS の通知許可は TCC の管轄外です)。そのため、iOS をターゲットにしたシナリオが notifications を指定すると、デバイスを一切操作する前の preflight が対応していない権限として個別に名指しして失敗します。そのプロンプト自体への対処は、引き続き systemAlert のエントリが担います。Android の POST_NOTIFICATIONS は実行時権限です(API 33 以降)。そのため Android は語彙のすべてに対応します。選んだバックエンドが対応しないサービスの組み合わせも、同じように preflight が個別に名指しして失敗させます。

permissions に対応する XCUITest / Espresso 側のコードはないため、codegen はコードを生成する代わりに、サービスごとにラベル付きの // TODO を出力します。フィールド自体は、生成したテストの起動処理より前に bajutsu 自身が適用します。

interrupts(予測できない差し込み画面への対処)

if ステップ(下記)は、ステップ列の1 か所で条件を判定します。分岐したい画面の直前にどのステップが来るかがわかっているときは、これが適切な道具です。画面の出現がどの単一ステップにも結び付かないときは、if は向きません。オンボーディングの重ね表示、チュートリアル、アクセシビリティツリーに見える権限プロンプトを考えます。いずれも、アカウントの状態やネットワークの間合い、A/B の振り分け次第で、想定より数ステップ早く、あるいは遅く現れます。まったく現れないこともあります。if を 1 つ置いても、その置いた位置にちょうど画面が現れたときしか捕まえられません。それ以外のタイミングはすり抜け、想定していない画面に対して残りのシナリオが失敗します。

このタイミングの読めない画面を扱うのが interrupts です。このリストは 3 つの形のエントリを持ち、エントリが書くキーで形が決まります。この節では画面の形を説明します。残りの 2 つの形は、OS のプロンプトを扱う systemAlert と、Apple の TipKit のポップオーバーを扱う tipKit です。2 つの形のキーを混ぜたエントリは読み込みに失敗し、エラーは両方の形を示します。

画面のエントリは condition(if が使うのと同じアサーション DSL)と、画面を片付ける steps を指定します。ランナーは各エントリを随時判定し、画面がステップ列のどこに現れても評価して、条件が一致すればエントリの steps を実行します。

この判定が追加コストなしで済むのは、そのステップのために読んだばかりのツリーに乗れる場合だけです。wait のポーリングの各回と、持ち越したツリーがないときに screenChanged ポリシー付きステップが読む before が、これにあたります。残りの wait 以外のステップは、判定のために driver.query() を 1 回余分に呼びます。前のステップから持ち越したツリー(BE-0234)を before に使う screenChanged ポリシー付きステップも同じです。ガードはそれを古い可能性があるものとして読み直すため、同じ 1 回を払います。

ハンドラの実行後は、中断されたステップが元の位置から再開します。wait は元のタイムアウトに向けてポーリングを続け、操作ステップは自分の操作を試みます。そのため、if を置く 1 か所を作者があらかじめ言い当てる必要はありません。

# config.yaml — アプリ全体の既定。このアプリのオンボーディング画面を全シナリオで扱う
targets:
  myapp:
    platform: ios
    subject: { id: com.example.myapp }
    hooks:
      interrupts:
        - condition: { exists: { id: onboarding.skip } }
          steps:
            - tap: { id: onboarding.skip }
# scenario.yaml — このシナリオ独自の追加。config レベルのリストに後続として連結される
- name: log in
  interrupts:
    - condition: { exists: { id: att.dialog } }   # App Tracking Transparency のプロンプト
      steps:
        - tap: { id: att.allow }
  steps:
    - tap:  { id: login.button }
    - wait: { for: { id: home.title }, timeout: 10 }   # 途中で差し込み画面が出ても片付けてから、この wait が通る

config レベル(targets.<name>.hooks.interrupts)に置いた interrupts リストはアプリ全体の既定です。シナリオ独自の interrupts はその後ろに連結され、config のエントリを先に判定します。どの形のエントリも従う、config が先でシナリオが後という重ね方です(層の重ね方)。エントリの steps は、if の分岐とまったく同じように、囲んでいるシナリオの vars.* バインディングを共有します。

シナリオ側のハンドラの steps では、ほかのステップと同じようにコンポーネントを use で呼び出せます。展開は run の前に済みます。config レベルのエントリでも use を使えます。targets.<name>.hooks.interrupts の下に置いた use は、config の読み込み時に config ファイルのディレクトリを基準に解決します(再利用)。

ハンドラ自身の steps が condition を解消しないとき(セレクタの誤りや、同じ内容で再描画され続ける画面)は、エントリはステップごとに小さな上限回数までしか発火しません。そのあとはステップが本来の結末(成功、失敗、タイムアウト)へ戻ります。設定を誤ったエントリは、実行をハングさせずに、ステップをきれいに失敗させます。

シナリオが2つ以上のターゲットを宣言すると、interrupts の各エントリはそのうち1つを監視します。 エントリは自身の target フィールドで監視先を指定します。target を省略したエントリは、プライマリターゲットを監視します。 プライマリターゲットは、シナリオの targets リストの先頭の名前です。 ステップの target と違い、エントリの target は宣言したターゲットの数にかかわらず省略できます。 たいていのエントリはプライマリターゲットを対象にするので、必須にすると全エントリに同じ名前を繰り返し書くことになります。 エントリの steps にあるリカバリ用のステップも target を省略できます。 省略したステップは、プライマリではなく、エントリが監視するターゲットで実行されます。

- name: a web consent banner during a cross-platform flow
  targets: [showcase-app, showcase-web]
  interrupts:
    - condition: { exists: { id: onboarding.skip } }   # target なし: showcase-app を監視
      steps:
        - tap: { id: onboarding.skip }
    - target: showcase-web
      condition: { exists: { id: cookie.accept } }
      steps:
        - tap: { id: cookie.accept }                   # showcase-web で実行
  steps:
    - target: showcase-app
      tap: { id: post.like }
    - target: showcase-web
      wait: { for: { id: post.likeCount }, timeout: 10 }

config レベルのエントリには target を書きません。 エントリはそれを宣言した targets.<name> ブロックにすでに属しているため、target を書いてもその名前の繰り返しか矛盾にしかならないからです。 config の読み込みは、そうしたエントリと、その steps にあるステップのどちらに書かれた target も拒否します。

判定に使うのは決定的なアサーション DSL であり、モデル呼び出しではありません。そのため interrupts は run の判定に AI を持ち込みません。BE-0402 以降は systemAlert のエントリも同じです。両者の違いは届く先です。アラートガードは、アクセシビリティツリーに見えないプロセス外のシステムプロンプトを SpringBoard の照会で扱います。一方 interrupts は、ツリーに見える画面を、マシンチェック可能な条件で扱います。どちらを選ぶかの目安を次に示します。

フィールド 対象 タイミング 仕組み
if ステップ列のわかっている位置に出る画面 台本どおりの 1 回の判定 決定的(アサーション DSL)
interrupts 予測できない位置に出る、ツリーに見える画面 全体を通して随時判定 決定的(アサーション DSL)
handleSystemAlert 途中で tap するつもりの既知のプロセス外プロンプト 作者が置いた明示的なステップ 決定的(ネイティブなアクセシビリティ tap)
interrupts の systemAlert のエントリ 想定外のプロンプト。プロセス外のものと、プロセス内のパスワード保存シート ステップや wait がブロックされたときに反応 XCUITest ではネイティブの SpringBoard 照会(モデルなし、BE-0316 を再利用)と、その照会に映らないシートへのツリー内タップ。どのエントリも同定しないプロンプトは失敗理由に書き出す
permissions そもそも避けられる OS 権限プロンプト 起動前、アプリが動き出す前 決定的なデバイス操作

「この条件をテスト全体を通して随時判定する」に対応するネイティブな XCUITest / Espresso / Playwright の構文はありません。そのため codegen はコードを生成する代わりに、フィールドと設定された各条件を名指ししたラベル付きの // TODO を出力します。bajutsu run が忠実に実行する経路です。

setup / cleanup(セットアップとティアダウンのフェーズ)

steps の先頭に書いたセットアップは、シナリオ自身のステップと見分けが付きません。レポートは 1 つの連番の並びとして表示し、セットアップの失敗も、セットアップ由来であるという印のない、ふつうのステップ失敗として現れます。ティアダウンにいたっては仕組みそのものがありません。後片付けを置ける場所は steps の末尾だけです。しかしステップループは最初の失敗で打ち切られる(run ループ)ため、末尾の後片付けのステップが走るのは、それより前のステップがすべて成功した run に限られます。つまり、後片付けをもっとも必要としなかった run でしか走らないのです。テストユーザーを作ってから 3 ステップ先の壊れたボタンで失敗したシナリオは、そのユーザーを残したままになります。

setup と cleanup は、この 2 つの穴を塞ぎます。setup は最初に走る順序付きのステップ列で、レポートでは独立したセクションになり、ここで失敗すると steps と expect をまったく実行せずにシナリオを打ち切ります。cleanup はルールのリストで、各ルールは結末(always、success、failure)と、その結末のときに走らせる steps を組にします。ランナーはシナリオの判定が出てからルールを評価し、失敗した経路も含め、steps を抜けるすべての経路でこのフェーズに到達します。どちらのフィールドも通常のステップ文法とアサーション DSL をそのまま使うので、フックのステップはシナリオ自身のステップと同じだけマシンチェック可能です。また、どちらも run の ${vars.*} バインディングを共有します(実行時変数)。

- name: sign up, then release the account
  setup:
    # シードのエンドポイントは、作成したユーザーの id だけをレスポンスボディで返す
    - http: { method: POST, url: "https://api.test/users", saveBody: userId }
  steps:
    - tap:  { id: login.button }
    - type: { text: "${vars.userId}", into: { id: login.username } }
  cleanup:
    - on: always
      steps:
        - tap: { id: session.logout }
    - on: success
      steps:
        - http: { method: DELETE, url: "https://api.test/users/${vars.userId}" }
    - on: failure
      steps:
        - http: { method: POST, url: "https://api.test/diagnostics", body: '{"failed":true}' }

(demos/showcase/scenarios/setup_cleanup.yaml 実物)

2 つのフィールドは、BE-0452 までは before と after という名前で、結末の語 failure も error でした。BE-0452 は、ターゲットのフックとシナリオのフェーズを 1 組の語で呼ぶように揃えました。ローダーは古い名前を読みません。古い名前を書いたシナリオは読み込みに失敗し、エラーが新しい名前を示します。

同じ on の値を持つルールは複数書けます。同じ結末を共有するルールは宣言順に走ります。1 つの capturePolicy トリガーを 2 つのルールが共有できるのと同じ扱いです。あるルールの steps が失敗しても、フェーズは止まりません。残りのルールもそのまま走ります。後片付けの残りを飛ばすことこそ、ティアダウンが避けようとしている結末だからです。その失敗が run の判定に与える影響は、run がそれまでどうなっていたかで変わります。成功していた run では、失敗したルールがそのまま run の failure(cleanup: step 0 (tap): …)になります。すでに失敗していた run なら、失敗したルールは元の failure を置き換えず、その後ろへ追記されます。読み手が最初に目にする理由を、後片付けの失敗という症状ではなく元の原因のままとするためです。

キャンセルされた run(SIGTERM、serve Web UI のキャンセルボタン)もこのフェーズに到達し、cleanup は failure の結末として振り分けられます。後片付けのルールには、キャンセルの猶予時間のうち一定の割合が与えられます。その持ち時間を使い切ると残りのルールは打ち切られます。レポートを書き出すシャットダウンの後始末を、猶予時間のうちに収めるためです。

ターゲットのフック:hooks.setup と hooks.cleanup

targets.<name>.hooks.setup はシナリオの setup と、targets.<name>.hooks.cleanup はシナリオの cleanup と同じ形を取り、アプリ全体の既定になります。シナリオ自身のフィールドとの重ね方は、2 つで逆向きです。

フィールド 重ね方 理由
setup config(hooks.setup)が先、シナリオが後 アプリ全体のセットアップが用意した状態の上に、このシナリオ自身のセットアップが積み上がる。interrupts が従うのと同じ、config が先でシナリオが後という重ね方
cleanup シナリオが先、config(hooks.cleanup)が後 このシナリオが作ったものを解放してから、アプリ全体のティアダウンがその外側を閉じる。フィクスチャ方式のテストフレームワークのセットアップとティアダウンの対が与える、後から確保したものを先に解放する順序

フックのステップは use: でコンポーネントを呼び出せます。ターゲットの全シナリオで共有するログイン手順は、この形で 1 度だけ記述します。setup プレリュードファイルは、ターゲットレベルと preconditions.setup の両方で廃止しました(BE-0452)。ターゲットのセットアップを走らせたくないシナリオは、preconditions.inheritSetup: false を指定します。その場合も hooks.cleanup は走ります。後片付けは、シナリオを抜けるすべての経路で走るからです。

どれを選ぶか

近い領域に 3 つのフィールドがあり、それぞれ答える問いが違います。

フィールド 走る位置 レポートでの扱い 対象
setup / cleanup 独立したフェーズとして、steps の前と判定の後 独立した setup / cleanup のブロック 検証対象のシナリオと読み手が区別できる必要のあるセットアップとティアダウン
use(コンポーネント) 呼び出したステップの位置で展開 連番のステップの一部 複数のシナリオで共有する再利用可能な手順で、区別が要らない場合
capturePolicy ステップループ全体を通してステップごとに ステップに紐づく証跡 ステップが失敗したときに追加の証跡を取ること。ステップを走らせることではない

capturePolicy の on: { result: failure } トリガーと cleanup ルールの on: failure は、同じ考え方に同じ語を当てたもので、粒度だけが違います。capturePolicy のトリガーは、run のどこで起きたかを問わず 1 つのステップの失敗ごとに発火します。cleanup のルールはシナリオ全体の判定に対して一度だけ発火します。

codegen が出力するもの

setup にはフレームワークの構文が要りません。codegen はそのステップを、生成したテスト本体の先頭に // setup の区切りコメントとともにそのまま展開します。最初に走り、失敗すれば後続を打ち切るという、フェーズの意味そのままだからです。cleanup には構文が要り、ターゲットごとに手段が違います。Playwright と UI Automator では、テスト本体を try / catch / finally で包みます。どちらのターゲットもアサーションが例外を投げるので、catch は判定の元になったはずの失敗をそのまま捕まえられるからです。XCUITest では代わりに addTeardownBlock を 1 つだけ登録します。XCTAssert は例外を投げずに失敗を記録するだけなので、結末は testRun?.hasSucceeded から読みます(codegen)。

セレクタ(要素の指定)

セレクタは、操作またはアサーションの対象となる どの要素か を指定します。1 つ以上のフィールドを与え、複数指定したフィールドは AND(すべて一致)で評価し、最低 1 つは必須です。セレクタが一意の要素にどう絞られるか、また曖昧なセレクタが最初の一致を選ばず失敗する理由は selectors を参照してください。形式的な形は dsl-grammar にあります。

フィールド 型 説明
id str | list[str] 完全一致の accessibilityIdentifier。第一候補(安定していてローカライズされない)。リストは候補の OR で、要素の id がいずれかに一致すればよい
idMatches str | list[str] id へのグロブ(例 "list.row.*"。複数一致を前提とする)。リストはいずれかのグロブに一致すればよい
label str 完全一致の accessibilityLabel(可視テキスト)。補助や曖昧性解消に使う
labelMatches str label への正規表現 / 部分一致(re.search)
traits list[str] アクセシビリティ trait で絞る(部分集合判定、例 [button])
value str 完全一致の accessibility value
within Selector コンテナに限定する。一致要素は、ネストしたセレクタが解決する要素の内側になければならない(入れ子可)
index int 複数一致の k 番目を選ぶ(負数可)。最終手段であり、順序に依存する
- tap: { id: counter.increment }                               # by id (recommended)
- tap: { id: [stable.refresh, stable_refresh] }                # id 候補の OR(下記参照)
- tap: { label: "Delete" }                                     # by visible label (e.g. an alert button)
- tap: { id: row.action, within: { id: list.row.3 } }          # scoped to a container's subtree
- tap: { labelMatches: "^Item ", traits: [button], index: 0 }  # first matching button, fields AND-ed

まず id を使います。要素の集合(count / 存在確認)には idMatches を使います。index は最終手段です。順序が変わると壊れます。解決の完全な意味論は selectors にあります。

プラットフォームをまたぐ id:候補のリスト(BE-0221)

シナリオがプラットフォーム間で共有できるのは、セレクタが id を使う範囲までであり、その id をアプリ側のどの属性が満たすかはドライバ内に閉じています。ただし SPEC の id をそのまま再現できないプラットフォームがあります。Android の android:id(Views toolkit)は . も - も許さないので、stable.refresh は stable_refresh、search.results-empty は search_results_empty として現れます。1 つのシナリオをどこでもそのまま走らせるため、id / idMatches に候補のリストを与えると、照合はその OR になります。

- wait: { for: { id: [stable.refresh, stable_refresh] }, timeout: 10 }
- count: { sel: { idMatches: [stable.row.*, stable_row_*] }, equals: 5 }

ドット形は iOS と Android Compose(どちらもそのまま再現します)に、アンダースコア形は Android Views に一致します。あるアプリの画面に現れる形は常に一方だけなので、決定的なままです。仮に両方の形が同時に画面にあれば、そのセレクタは曖昧として即座に失敗します。OR が 2 件以上の一致を暗黙に 1 つへ絞ることはありません。これにより id 規約はシナリオに明示的に残り、別々の id を取り違えかねないドライバ側の暗黙の .↔_ 書き換えに頼りません。showcase の共有シナリオはこれを使い、showcase-swiftui / showcase-compose / showcase-views が同じファイルで走ります。

アンダースコア形は、Views ターゲットが実際に実行するシナリオにだけ書きます。対象は demos/showcase/android/Makefile の E2E_VIEWS_SCENARIOS と、showcase-views を直接駆動するレーンです。それ以外のシナリオでは、どのレーンもアンダースコア形の候補を解決しません。候補にタイポがあってもテストは失敗せず、読み手には必要な候補と使われない候補の区別がつきません。そうしたシナリオにはドット形の id だけを書きます。

ステップ文法(steps)

各ステップは ちょうど 1 アクション と、任意の修飾子(capture: / name:)からなります。1 ステップに 2 アクション以上を書くと検証エラーになります(scenario/models/steps.py の _one_action)。

アクション 形 説明
tap tap: <Selector> 一意解決を要求する(曖昧なら失敗)
tapPoint tapPoint: { x: <frac>, y: <frac> } セレクタではなく正規化座標(0..1、左上原点)でタップします。アクセシビリティツリーが要素として公開しない操作対象(id のないタブバーのタブなど)に使う、安定性の梯子の最下段です。record の vision 経路がこれを出力し、run はそのときの画面サイズに合わせて再生します
doubleTap doubleTap: <Selector> 解決した要素を 2 回素早くタップする
longPress longPress: { sel: <Selector>, duration: <sec> } 長押し
type type: { text: "...", into?: <Selector>, submit?: <bool> } into 指定時は先にフォーカスする
clear clear: { into: <Selector> } フィールドをフォーカスして現在の内容をすべて削除する。web コンテキストは非対応
delete delete: { into: <Selector>, count: <int> } フィールドをフォーカスして末尾から count 文字削除する(count > 0)。web コンテキストは非対応
select select: { into: <Selector>, mode?: "all" } フィールドをフォーカスして内容を選択する(mode 既定 all)。web コンテキストは非対応。iOS(XCUITest)バックエンドはネイティブに対応し、codegen もネイティブの等価物を出力する
copy copy: {} 選択中の内容をクリップボードへコピーする。事前の select が必要。web コンテキストは非対応。iOS(XCUITest)バックエンドはネイティブに対応する
paste paste: { into: <Selector> } フィールドにフォーカスし、そのタップで置かれたカーソル位置にクリップボードをペーストする(文字列のあるフィールドでは、タップした位置になる)。選択中の内容があれば置き換える。クリップボードには copy か setClipboard が入れた内容が入っている。結果は value アサーションで確かめる。web コンテキストは非対応。iOS では編集メニューの「Paste」項目をタップする(setClipboard で入れたクリップボードはハードウェアの Cmd+V では貼り付けられないため)。メニューはアプリのローカライズに従うので、UIKit の Paste ラベルをどの言語でも受け付ける。Simulator のビルドによってはこの貼り付けで iOS の貼り付け同意ダイアログが出るので、interrupts: [{ systemAlert: paste, choice: grant }] を宣言してガードに応答させる
selectOption selectOption: { sel: <Selector>, option: "..." } web の <select> をこの value を持つ option に合わせる。web 専用(iOS / Android は失敗する)
selectPhotos selectPhotos: { indices: [0, 1], timeout: 10 } アプリがすでに開いたシステムの写真選択画面から、指定した位置のセル(0 が先頭で、新しい画像ほど前)を選んで確定する。iOS(XCUITest)では PHPickerViewController、adb では Android 13 以降の写真選択画面を操作する。単一選択の画面は 1 回のタップで閉じる。見えているグリッドを超える位置は失敗する
setPickerValue setPickerValue: { sel: <Selector>, value: "..." } ホイール型のピッカー(iOS では UIPickerView かホイール表示の UIDatePicker、Android では NumberPicker かスピナー表示の DatePicker)をこの value を持つ行へ動かす(後述)。iOS(XCUITest)と Android(adb)で使える。sel は 1 つのホイールを指し、複数コンポーネントのピッカーは within / traits / index で兄弟のホイールを区別し、コンポーネントごとに 1 ステップずつ書く
swipe swipe: { on: <Selector>, direction: up\|down\|left\|right } または swipe: { from: [x,y], to: [x,y] } セレクタ形と座標形は混在できない。方向指定形式はスクロールする
drag drag: { on: <Selector>, direction: up\|down\|left\|right, amount?: <frac> } 要素そのものをドラッグする(ハンドル/仕切り/スライダー)。スクロールではない
scroll scroll: { to: <Selector>, direction?: up\|down\|left\|right, within?: <Selector>, amount?: <frac>, maxScrolls?: <int> } to が画面に入るまで(慣性なしに)スクロールし、上限に達したら失敗する。direction はスクロール方向(既定 down)で、swipe とは逆向き
back back: {} 1 階層戻ります。各バックエンドがプラットフォームに合った手段(Android のシステム戻るキー、iOS の OS 提供の戻るボタン、web の履歴)を使います(BE-0210)
navigate navigate: "<url>" 現在のページで URL を開きます。値はターゲットの baseUrl を基準に解決します(後述)。web 専用です(iOS / Android は preflight で失敗します)
openUrl openUrl: "<url>" ディープリンクなどの絶対 URL を、その時点でシナリオが操作しているアプリに向けて OS へ渡し、そのアプリが前面に来るまで待ちます(後述)。iOS(16.4 以降)と Android で使えます(web バックエンドは preflight で失敗します)
pinch pinch: { sel: <Selector>, scale: <num> } 2 本指の拡縮。scale > 0(>1 で拡大, <1 で縮小)
rotate rotate: { sel: <Selector>, radians: <num> } 2 本指の回転。>0 で時計回り
handleSystemAlert handleSystemAlert: { sel: <Selector>, timeout: <sec> } iOS SpringBoard の権限プロンプトのボタンを決定的に tap する(下記)。iOS(XCUITest)専用。sel は label / labelMatches / index のみ受け付け、run が Simulator を固定するシステム言語に対して解決する。sel の代わりに prompt: notifications\|tracking\|paste と choice: grant\|deny を指定すると、ボタンを意味で指定でき、run がその label を解決する(BE-0320)。label の対応表にない言語では、ボタンの位置で解決する(BE-0445)
wait wait: { for\|until: ..., timeout: <sec> } 条件待機(下記)
sleep sleep: { seconds: <sec>, reason: "..." } どの条件でも観測できない遅延のための固定の待機。上限 30 秒、理由は必須(下記)
assert assert: [ <Assertion>... ] ステップ途中の中間検証
relaunch relaunch: { env?: {...}, args?: [...] } アプリを terminate + 再起動し(launch env/args を再適用し、指定分で上書き)、ready まで待つ
setLocation setLocation: { lat: <num>, lon: <num> } シミュレータの GPS 位置を上書きする(simctl location set)
push push: { payload: {...} } この APNs(Apple Push Notification service)ペイロードで疑似プッシュ通知を配信する(simctl push)
http http: { method?, url, headers?, body?, status?, saveBody?, extractBody?: [{ var, path }] } HTTP リクエストを送る(テストデータ準備 / Webhook / API)。status を検証し、ボディを ${vars.<saveBody>} に保存する、または path で指定した JSON のフィールドを ${vars.<var>} に取り出す(後述)
totp totp: { secret, into?: { var }, name? } RFC 6238 の時刻ベースワンタイムパスワード(2FA)をローカルで生成し ${vars.<var>} に入れる。name を指定すると、後続の otp ステップ向けにシークレットも登録する
otp otp: { from, into: { var }, minRemaining? } totp ステップが from の名前で登録したジェネレータの現在のコードを ${vars.<var>} に入れる(後述)
email email: { match: { to?, subject?, subjectMatches? }, extract: { var, bodyMatches }, timeout } 設定したメールボックスを一致するメッセージが届くまでポーリングし、コードを ${vars.<var>} に取り出す
generate generate: { random\|datetime: {...}, into: { var } } 乱数または現在日時の値を実行時に計算し、${vars.<var>} に保存する(後述)
eval eval: { from, ops: [...], into: { var } \| { vars: [...] } } シナリオがすでに持つ値を分割、結合、絞り込みなどで変換し、${vars.*} に保存する(後述)
manual manual: { label: "...", bypass?: "..." } record 中に記録される人による操作の引き取り(BE-0185)。決定的な実行時の等価物がないため、run 時に明示的に失敗する(合格を偽装しない)
background background: {} アプリをバックグラウンドへ送る(Home ボタン)
foreground foreground: {} ステップのターゲットのアプリを、終了させずに前面へ出す。動いていないアプリは、終了を除いて relaunch と同じように起動し、準備が整うまで待つ。iOS と Android
installApp installApp: { from: <target>, keepData?: bool } 後から入るデバイスグループのメンバーのビルドを、ステップのデバイスにインストールする。同じ識別子の既存ビルドの上に入れる(keepData、デフォルト true)か、先にアンインストールする(false)。何も起動しない(デバイスグループ)
setPrimaryTarget setPrimaryTarget: { target: <target> } このステップ以降、target を省略したステップ、interrupts エントリ、トップレベルの expect エントリを target で動かす。トップレベルの steps にだけ書ける(デバイスグループ)
clearKeychain clearKeychain: {} Simulator のキーチェーンをリセットする(保存済みパスワード / 証明書)
clearClipboard clearClipboard: {} デバイスのクリップボードをクリアします(iOS Simulator と、BajutsuAndroid を組み込んだ Android)
setClipboard setClipboard: { text: "..." } ペースト操作のため、デバイスのクリップボードにテキストを投入します(iOS Simulator と、BajutsuAndroid を組み込んだ Android)
setMocks setMocks: [ { match, respond }... ] アプリ内制御チャネルを通して、シナリオの途中でアプリのスタブテーブル全体を置き換える(後述)。[] はすべてのスタブを外す。iOS(XCUITest)かつネットワーク収集が有効な場合のみ(BE-0365)
overrideStatusBar overrideStatusBar: { time?, batteryLevel?, batteryState?, cellularBars?, wifiBars? } 決定的なスクリーンショットのためステータスバーを上書きする
clearStatusBar clearStatusBar: {} ステータスバーの上書きを解除する(ライブ表示に戻す)
use use: { component: <file>, with?: {...} } 再利用コンポーネントの steps を展開する。コンパイル時マクロ(再利用)。取れる修飾子は target だけ:capture / extract / name / from は拒否され、target は展開後の全ステップに刻印される(複数ターゲット)
group group: { name: <str>, steps: [...] } 連続するステップに名前を付ける。コンパイル時マクロで、report.html では折りたたんで表示する(後述)
web web: { within: <Selector>, steps: [...] } WebView の DOM コンテキストに入ります。within がホストの WebView をネイティブに解決し、入れ子の steps はネイティブツリーではなく正規化された DOM を対象にします(後述)

修飾子(use ステップに付けられるのは target だけです。上表を参照):

  • capture: [<token>...]:このステップだけの証跡(evidence)。
  • name: <str>:ステップ ID(証跡の出力先ディレクトリ名やレポート表示に使う)。省略時は step<i>。
  • from: <str>:来歴(後述)。このステップを記録した元のフレーズ。オーサリング用のメタデータで、run は読みません。
  • target: <str>:このステップが操作する対象を、シナリオ自身の targets から選んで指定します。

tap

- tap: { id: counter.increment }      # exact id (recommended)
- tap: { label: "Delete" }            # exact label (for an in-app alert etc. with no id)

type

- type: { text: "a@b.com", into: { id: auth.email } }   # focus, then type
- type: { text: "hello", submit: true }                 # submit appends a newline / confirm (uses current focus)

実装上は、into を指定すると内部で対象を tap してから type_text します(orchestrator/actions/ の _do_action)。

selectOption

- selectOption: { sel: { id: nav.theme-picker }, option: midnight }   # value が "midnight" の option に <select> を合わせる

ネイティブの HTML <select> は、ドロップダウンがページの要素ツリーに含まれないため、座標タップでは値を決定的に切り替えられません。selectOption は、ほかのアクションと同じ一意解決のコアで <select> を解決したうえで、表示ラベルではなく option の value を指定して値を設定し、change イベントを発火します。これにより、ユーザーが選んだときと同じようにページが反応します。指定する value は value アサーションが <select> から読み取る値と一致するので、選択結果はそのまま検証できます。

selectOption は web 専用のアクションです。<select> は iOS や Android にネイティブの対応物がないため、これらのバックエンドは何もせずに済ませるのではなく、「サポート外のアクション」という明確な理由でステップを失敗させます。

- navigate: /settings                       # ターゲットの baseUrl を基準に解決する
- navigate: https://idp.example.com/login   # 絶対 URL は書いたとおりに使う
- navigate: "/items/${vars.itemId}"         # ${...} トークンはほかのステップのフィールドと同じく展開される

navigate は、シナリオの途中で URL を開くステップです(BE-0464)。 どのコントロールからもリンクされていないページ(メールのリンク、共有アイテムの URL など)を開くときに使います。 UI をたどらないと届かない深いページへ直接移るときや、リダイレクトを検証するときにも使います。 値はマッピングではなく、ただの文字列です。 値はブラウザがリンクを解決するのと同じ規則(urljoin)で、ターゲットの baseUrl を基準に解決します。 /settings は baseUrl のパスを置き換え、settings はそのパスを基準に解決します。 http / https の絶対 URL は、別のオリジンであっても書いたとおりに使います。 それ以外のスキーム(javascript:、file:、data:)は拒否します。 リテラルの値はシナリオの読み込み時に拒否します。 ${...} トークンを含む値は、実行時に展開した後で検査し、規則に反すればステップを失敗させます。

ステップは、ページの load イベントが発火した時点で戻ります。 レスポンスのステータスは読まないので、404 のページでも読み込めればステップは成功し、判定は次の assert や wait が下します。 Cookie とストレージは保たれるので、navigate はセッションを初期化せずに続けます。 存在しないホストやタイムアウトのように、URL そのものが原因の失敗は、ブラウザのメッセージを付けてステップを失敗させます。 navigate には urlNavigation ケーパビリティが必要で、これを公開するのは web バックエンドだけです。 そのため iOS や Android で navigate を使うシナリオは、デバイスを確保する前の preflight で失敗します。 web: ブロックの中に置いた navigate も同じく preflight で失敗します。

openUrl

- use: signIn
- openUrl: "showcase://tabs/settings"          # テスト対象のアプリが URL を受け取る
- assert: [{ exists: { id: settings.title } }]
- openUrl: "showcase://items/${vars.itemId}"   # ${...} トークンはほかのステップのフィールドと同じく展開される
- app:
    bundleId: ${vars.browserId}                # ブラウザが URL を受け取る
    steps:
      - openUrl: "https://example.com/promo"
      - tap: { label: "Open in app" }

openUrl は、モバイルのシナリオの途中で URL を OS へ渡すステップです(BE-0487)。 起動時のディープリンク(subject.launch.deeplink)はどのステップよりも先に開くので、サインインが必要な画面には届きません。 openUrl を使えば、そうした画面にもシナリオの途中から移れます。 値はマッピングではなく、ただの文字列です。 値はスキームを持つ絶対 URL でなければなりません。 モバイルのバックエンドには解決の基準になる baseUrl がないので、/settings のようにスキームのない値は拒否します。 javascript:、data:、file: の URL も、アプリの中の行き先を指さないので拒否します。 リテラルの値はシナリオの読み込み時に検査します。 ${...} トークンを含む値は実行時に展開した後で検査し、規則に反すればステップを失敗させます。

URL を受け取るのは、その時点でシナリオが操作しているアプリです。 app: ブロックの外では、テスト対象のアプリが受け取ります。 app: ブロックの中では、そのブロックで指定したアプリが受け取ります。 したがって、ブラウザを指定した app: ブロックでステップを囲めば、ブラウザが URL を開きます。 受け取るアプリを 1 つに絞ることで、ステップは決定的になります。 受け取り先を絞らない intent を Android へ送ると、同じ URL を扱えるアプリが 2 つあるときにアプリの選択画面が出てしまうためです。

ステップは、OS が URL を受け付け、受け取ったアプリが前面に来た時点で成功します。 前面に来るまでの待ち時間の上限は、同じバックエンドの app: ブロックと同じです(iOS は約 10 秒、Android は 30 秒)。 ステップは画面の内容を待ちません。 URL が開く画面は、続く wait や assert で待ちます。 URL を受け付けたかどうかの判定方法は、バックエンドによって異なります。

バックエンド URL の渡し方 ステップが失敗する条件
iOS(XCUITest) ランナーが、受け取るアプリに対して XCUIApplication.open(_:) を呼ぶ 呼び出しが例外を投げるか失敗を記録した場合(そのメッセージが理由になる)。デバイスの iOS が 16.4 より前の場合
Android(adb) am start -W --activity-single-top -a android.intent.action.VIEW -d <url> <package> を実行する am start が Error で始まる行、例外、ok 以外のステータスを出力した場合。実行中のアクティビティが受け取ったことを示すもの以外の Activity not started の警告を出力した場合

iOS では、受け取るアプリはたいてい最初から前面にあるので、前面待ちは何も証明しません。 判定は open(_:) が投げる例外や記録する失敗に頼ります。 どのアプリも扱わない URL に対して open(_:) が何も報告しなければ、ステップは成功します。 その場合は、続くアサーションが想定と違う画面を検出します。

Android では --activity-single-top を付けるので、起動時のディープリンクと同じ URL も開けます。 タスクの最前面にあるアクティビティが、onNewIntent で URL を受け取るためです。 アプリ側は onNewIntent でディープリンクを扱う必要があり、ディープリンクを受け付けるアプリの多くはすでにそうしています。

URL が出したシステムの確認ダイアログ(ブラウザが別のアプリを開いてよいか尋ねるダイアログなど)は、ステップの後も表示されたままです。 実際のユーザーが目にする確認を、ステップが勝手に答えることはしません。 このダイアログは、interrupts の systemAlert エントリーか、続く handleSystemAlert ステップで閉じます。 openUrl には openUrl ケーパビリティが必要で、これを公開するのは iOS と Android のバックエンドです。 そのため web バックエンドで openUrl を使うシナリオは preflight で失敗します。web バックエンドでは navigate でページを開きます。 web: ブロックの中に置いた openUrl は、シナリオの読み込み時に拒否します。 web: ブロックの中のステップはページに対して動くので、URL を渡す先の OS がないためです。

setPickerValue

- setPickerValue:                                                # ホイールを「大学」の行へ動かす
    sel: { within: { id: form.school }, traits: [pickerWheel] }
    value: "大学"

ホイール型のピッカーは、iOS でも Android でもフォームでありふれたコントロールです。iOS では UIPickerView や、ホイール表示に切り替えた UIDatePicker がこれにあたります。Android では android.widget.NumberPicker と、スピナー表示の DatePicker や TimePicker がこれにあたり、後の 2 つは各欄を NumberPicker のホイールで構成します。ホイールの値を設定できるステップは setPickerValue だけです。

ホイールの各行は個別に指定できる要素になっていないため、解決したハンドルを対象とする tap では特定の行に到達できません。

座標を扱うステップも同様です。swipe / drag / scroll は距離や方向を指定するドラッグであり、ホイールを目的の値のあたりまで回せても、そこで止まる保証はありません。tapPoint にいたっては、すでに表示されている行を叩けるだけで、表示されていない行へホイールを動かせません。いずれの場合も、結果のアサーションはドラッグの距離が行の高さとたまたま一致することに依存します。Bajutsu がほかのすべてのステップで排除している、近似的な操作そのものです。

iOS では、setPickerValue は、セレクタが解決した要素に対して XCUITest 自身の adjust(toPickerWheelValue:) を呼びます。swipe のような座標指定ではなく、tap と同じハンドル指定です。

Android の adb バックエンドは、tap が対象を解決するのと同じ手順でホイールを解決し、そのホイールの識別情報を常駐 UI Automator サーバーへ渡します。座標は渡しません。サーバーは NumberPicker 自身が持つアクセシビリティのスクロール操作でホイールを 1 行ずつ進め、1 行進めるたびに選択中の行を読み直します。

表示中の行と指定した値がどちらも整数なら、値に近づく向きから回し始めるので、年のホイールは近い側を回ります。それ以外の場合は前方向から回します。端のあるホイールは最後の行で逆向きに戻り、循環するホイールは回り始めた行に戻った時点で止まります。回す行数には 400 行の上限があり、期限も設けています。このステップは常駐サーバーを必要とし、サーバーがない場合は座標でホイールをドラッグせずに失敗します。

sel が解決すべきなのはホイールそのものですが、識別子を持つ要素がホイールであることはまれです。UIPickerView は識別子をピッカー側に付け、ピッカーの下にあるホイールを別の子要素として公開します。そのため、識別子だけを指定したセレクタは親であるピッカーを解決し、ステップは失敗します。adjust(toPickerWheelValue:) は、ホイールでない要素に対しては例外を投げるからです。上の例のように識別子と pickerWheel トレイトを組み合わせると、セレクタは子要素のホイールに届きます。

Android の NumberPicker は、自身のノードに resource-id をまったく持ちません。そのため識別子はホイールを囲むコンテナに付け、同じ within と pickerWheel の組み合わせで内側のホイールを指します。adb バックエンドは NumberPicker のノードに、クラス名から得る numberPicker に加えて pickerWheel トレイトも付けます。

ホイールが持たない値を指定すると、ホイールが止まった位置をそのままにするのではなく、その値を名指ししてステップが失敗します。したがって、後続のアサーションが検証するのはアプリであって、ジェスチャの当たり外れではありません。

複数コンポーネントのピッカー(年のホイールと月のホイールが並ぶもの)は、コンポーネントごとに独立した pickerWheel 要素として現れます。sel は常にそのうちの 1 つを指します。区別には、どのセレクタも持っている within / traits / index を使い、コンポーネントごとに 1 ステップずつ書きます。コンポーネントの並び順も行のラベルも、run が固定するロケールに従います。下の例は ja_JP を前提としており、ホイールは年 | 月 | 日の順に並びます。ロケールを指定しない場合は en_US となり、月 | 日 | 年の順で、同じ行のラベルは May や 2016 です。demos/showcase/scenarios/picker_wheel.yaml はロケールを指定していないため、en_US の並びを前提に書いてあります。

- setPickerValue:
    sel: { within: { id: form.birthdate }, traits: [pickerWheel], index: 0 }   # 年のホイール
    value: "2016年"
- setPickerValue:
    sel: { within: { id: form.birthdate }, traits: [pickerWheel], index: 1 }   # 月のホイール
    value: "5月"

within はフレームの包含関係で範囲を絞ります。したがって within が名指しするコンテナは、ホイールを収めるだけの大きさを持っていなければなりません。ホイール表示の UIDatePicker は、単体ではその大きさに届きません。iOS は UIDatePicker のコンポーネントを本来の高さで配置し、ピッカーの枠に合わせて切り詰めて表示するからです。各コンポーネントは識別子を持つピッカーよりも高いフレームを報告するため、UIDatePicker を名指しした within はどの要素にも一致しません。識別子は、コンポーネントを覆う大きさを持つ外側のコンテナに付けてください。demos/showcase/ios/swiftui/Sources/PickerView.swift が見出しとホイールとミラーのテキストを1つの識別子でまとめているのは、そのためです。

この指定方法は、datePicker の分類の隙間(セレクタ)も回避します。UIDatePicker のコンテナ要素自体は other に落ちますが、setPickerValue が指すのはその下にあるホイールの子要素であり、そちらは pickerWheel に分類されるためです。

setPickerValue は iOS(XCUITest)と Android(adb)で動きます。Android では、ホイールがどこに置かれていても NumberPicker を操作でき、Jetpack Compose の画面が AndroidView 経由で載せたものも対象です。一方、Compose が自前で描くホイールは対象外です。Compose には標準のホイールがなく、アプリごとのホイールがそれぞれ異なるアクセシビリティの形を公開するからです。

web ページにはホイール型のピッカーがありません。web で同じ意図を表すのは <select> であり、それを設定するのは selectOption です。したがって web バックエンドは pickerWheel ケーパビリティを公開せず、シナリオは作業が始まる前の preflight で、該当ステップの位置を名指しして棄却されます。

web(WebView の DOM コンテキストに入る)

- web:
    within: { id: checkout.webview }
    steps:
      - tap: { id: pay.submit }
      - wait: { for: { id: pay.confirmation }, timeout: 10 }

web は、ネイティブアプリが埋め込んだブラウザのビューである WebView の Document Object Model(DOM)に対して、入れ子の steps を実行します。ステップが対象にするのは、アプリのネイティブなアクセシビリティツリーではなく、ページの正規化された DOM(data-testid → Element.identifier)です。アプリの UI の一部をアプリ内の web コンテンツが担うハイブリッド画面向けの構造です。iOS は BE-0037、Android は BE-0482 で対応しました。同じブロックが、両方のプラットフォームで変更なしに動きます。ブロックの steps を終えると、制御はネイティブドライバーに戻ります。

入れ子の steps は、if や forEach の分岐と同じく、囲むシナリオの vars.* を共有します。capture / extract 修飾子は web ステップ自体には使えません。

ブロックが WebView を指す仕組み。 within は通常のセレクタで、id を必ず含みます。run はセレクタ全体をネイティブのツリーで解決し、ちょうど 1 つの要素、つまりホストの WebView を得ます。一致が 0 件、または 2 件以上ならステップは失敗します。ほかのセレクタと同じ扱いです。

その要素の背後にあるページは、プラットフォームごとに次のように探します。

プラットフォーム run がページに到達する経路 選ぶページ
iOS BajutsuKit の WebView ブリッジです。アプリ内の Hypertext Transfer Protocol(HTTP)サーバーで、run が BAJUTSU_WEBVIEW_PORT として渡すポートで待ち受けます。 アクセシビリティ識別子が within の最初の id と等しい WKWebView です。
Android Chrome DevTools Protocol(CDP)です。WebView のデバッグ用ソケットを、run がブロックの間だけ adb で転送します。 アタッチ済みで表示中のページのうち、within が解決したフレームを矩形に含む 1 つです。一致が 0 件、または 2 件以上なら、あいまいとしてステップを失敗させます。

Android は、等しさではなく包含で照合します。2 つの矩形の測る範囲が違うからです。ネイティブのツリーは、ビューの範囲を画面と祖先のビューで切り詰めて報告します。CDP は、ページの切り詰めていない矩形を報告します。そのため、ツールバーの下に一部が隠れた WebView でも一致します。

アプリが用意するもの。 用意がないときは、何もせず済ませるのではなく、足りないものを名指しする理由でステップを失敗させます。

  • iOS:アプリが BajutsuKit をリンクし、BajutsuNet.startIfEnabled() を呼びます。この呼び出しは、run がポートを渡したときにブリッジを起動します。WKWebView にはアクセシビリティ識別子を付けます。
  • Android:デバッグ可能なビルドが、Application.onCreate、または最初の WebView を作る直前に Bajutsu.enableWebViewDebugging(context) を呼びます。このヘルパーは BajutsuAndroid の関数です。どの debug ビルドタイプも android:debuggable を設定します。このヘルパーはデバッグ可能でないビルドでは何もしないので、リリースビルドがソケットを開くことはありません。bajutsu を動かすマシンには android extra(websockets)が要ります。構成済みのバックエンドに Android が含まれていれば、scripts/install.sh がこの extra を入れます。

ブロックが対応する範囲。 ブロックの中では tap / tapPoint / doubleTap / type / wait / assert が動きます。longPress / swipe / drag / clear / delete / select / copy / paste / selectOption / scroll / back / navigate / pinch / rotate / handleSystemAlert / setPickerValue はそこに届きません。いずれも「web コンテキストは非対応」という明確な理由で失敗します。次の場合も、ブロックの対象外です。

場合 起きること
<iframe> の中のコンテンツ DOM の走査はフレームの文書を飛ばすので、セレクタはその中の要素を指せません。
ファイル選択(<input type="file">) タップは入力欄に届きますが、開く選択画面はページの外にあるシステムの画面なので、ブロックからは操作できません。
Android で重なり合う 2 つの WebView 両方の矩形がフレームを含むので、推測せずにあいまいとしてステップを失敗させます。
Android でブロックの途中にアプリが再起動する デバッグ用ソケットが閉じ、通信の理由でステップが失敗します。
Android で別のデバッガーがすでにページにアタッチしている ページは 2 本目の接続を受け付けず、ステップが失敗します。
web: ブロックを使わず、WebView の中身をネイティブのラベルでタップする 非対応です。ネイティブのツリーは WebView の中身を選択できるほど細かく示さないことが多く、対応する経路はブロックです。
システムがアプリの上に表示するブラウザのタブ 非対応です。そのビューは別のブラウザアプリに属するので、ブリッジにもアプリのデバッグ用ソケットにも届きません。

app

- app:
    bundleId: com.apple.mobilesafari
    steps:
      - assert:
          - exists: { id: TabBarItemTitle }

app は、別アプリのUIを操作するステップです。バンドルIDで名指ししたアプリをactivateします。テスト対象アプリが一度も起動していないアプリでも構いません。実行中のアプリは前面に出します。入れ子のstepsは、テスト対象アプリのものではなく、そのアプリ自身のアクセシビリティツリーを対象にします。この挙動の裏付けとなるフィージビリティ調査の結果はdocs/specs/ios-cross-app-ui-control-feasibility.mdにあります。

ブロックのstepsを終えると、webと同じ入る・抜けるの契約で、直前にアクティブだったものへ制御が戻ります。appブロックを別のappブロックの中に入れ子にした場合、戻る先は直近の親であり、テスト対象アプリへ無条件に戻るわけではありません。

bundleIdは素のstringであり、固定の集合から選ぶ値ではありません。インストール済みの任意のアプリを名指しできます。テスト対象アプリ自身では開く手段がないアプリも含みます。iOS(XCUITest)とAndroid(adb)が対応しています。webのbackendでこのステップを使うシナリオは、デバイス側の作業を始める前にpreflightで失敗します。

bundleIdには、デバイスへインストール済みのアプリを指定します。前面化が遅いアプリ(コールドスタート、権限プロンプトなど)はElementNotFoundとしてステップを失敗させます。iOSでは、インストールされていないアプリを名指しした場合、この例外できれいに失敗するとは限りません。

Androidでは、bundleIdにパッケージ名(たとえばcom.android.settings)を書きます。adbのドライバはパッケージのランチャーアクティビティをam startで起動し、そのパッケージがresumedのアクティビティを持つまで待ちます。ランチャーアクティビティを持たないパッケージは、起動の前にElementNotFoundでステップを失敗させます。インストールされていないパッケージも同じです。ブロックを抜けるときは、1つ下のアプリを同じ手順で前面に戻します。テスト対象アプリはその間もプロセスを保つので、この切り替えがクラッシュとして扱われることはありません。iOSと同じく、入ったアプリはリセットしません。以前のブロックや実行が残した状態を、そのまま保ちます。

ただし、戻るときにAndroid固有の制限があります。ランチャーアクティビティがsingleTaskかsingleInstanceのアプリは、起動し直すと、タスクが上に積んだアクティビティがすべて破棄されます。clearTaskOnLaunchを設定したアプリも同じです。そのため、離れたときの画面ではなく、最初の画面へ戻ります。

ホーム画面を操作する(com.apple.springboard)

ホーム画面を描くプロセスであるSpringBoardも、appにとってはバンドルIDの1つにすぎません。長押しで編集モードに入り、ウィジェットギャラリーを開いてウィジェットを追加し、ホーム画面にあることをassertするまで、新しいステップもランナーの変更も要りません。demos/showcase/scenarios/widget.yamlは、そこまでを行ったうえで、ウィジェットをタップしてホストアプリを開きます。根拠となる実測(en_USとja_JPでの各画面のラベルと、以下に挙げる不足)はdocs/specs/ios-home-screen-widget-feasibility.mdにあります。

- background: {}                       # まず画面をホーム画面に渡す
- app:
    bundleId: com.apple.springboard
    steps:
      - longPress: { sel: { id: "Home screen icons" }, duration: 2 }   # 空いた壁紙を長押しして編集モードへ
      - tap: { label: "Edit", traits: [button] }
      - tap: { label: "Add Widget", traits: [button] }

シナリオが所有しないOSの画面を扱うので、次の制約があります。

  • 実測したのはiOS Simulatorだけです。 iOS 26.5で確かめました。実機とほかのランタイムは確かめていません。
  • preconditions.subject.reinstall: eraseでレイアウトを固定します。 長押しはアイコングリッドの中心に当たるので、グリッドの中心は空いた壁紙でなければなりません。eraseと再インストールのあと、SpringBoardはテスト用アプリをインストールしたページを開きます。このページは下半分が空いています。eraseは前の実行が追加したウィジェットも消すので、新しいウィジェットへのassertが一意に保たれます。
  • preconditions.device.ios.localeで言語を固定します。 ラベルはすべてSpringBoard自身の文言です。アイコンのidentifierでさえローカライズ済みの名前になります(英語ではCalendar、日本語ではカレンダー)。
  • 検索結果の行はツリーに現れません。 ギャラリーの検索欄に文字が入ると、SpringBoardのスナップショットは結果の一覧を空のコンテナとして返します。行は画面に表示されています。検索欄の下の決まった位置にある先頭の行を、tapPointでタップします(iPhone 17 Proでは{ x: 0.5, y: 0.29 })。
  • サイズの選択にはswipeではなくdragを使います。 サイズのカルーセルは、弾くように動かしたときだけページが切り替わります。swipeは慣性のないスクロールなので、元のページへ戻ってしまいます。
  • ホストアプリの初回起動でプロンプトが出ることがあります。 Calendarは位置情報と通知の許可を求めます。順序は一定でなく、2つが同時に出ることもあります。その場合、押すべきボタンが1つに決まりません。widget.yamlはプロンプトを残したままにし、次の実行のeraseで消します。

swipe

- swipe: { on: { id: comp.swipearea }, direction: left }   # frame 中心 → 方向へ画面に対する割合分(既定 0.125)
- swipe: { from: [100, 400], to: [100, 200] }              # raw coordinates (last resort)

{on,direction} と {from,to} は、どちらか一方だけでなければなりません(混在や片側の欠落は検証エラーになります)。

方向指定形式の意味は「スクロール」であり、各バックエンドは実際にスクロールを起こすプリミティブで実現します。iOS や Android では OS の本物のドラッグを使います。web ではマウスドラッグがページをスクロールしないため、wheel イベント(デスクトップ)かタッチドラッグ(モバイルの runsOn.browser.emulate)を使います(BE-0227)。座標形式は、それ自体を目的とする素のポインタドラッグ(canvas やマップのパン、ドラッグハンドル)であり、どのバックエンドでも素のドラッグの最終手段です。

drag

- drag: { on: { id: replay.divider }, direction: right }             # 掴んだハンドルをドラッグする
- drag: { on: { id: volume.slider }, direction: up, amount: 0.3 }    # 画面に対する割合で

drag は要素アンカーのポインタドラッグです。要素そのものを掴んで方向へ動かすもので、リサイズ用の仕切り、スライダーのつまみ、並べ替えハンドルなど、スクロールではなくドラッグする操作に使います。方向指定 swipe と同じジオメトリを共有します(amount は画面に対する割合で 0 < amount ≤ 1、省略時は小さな既定値)。方向指定 swipe がスクロールするのに対して、drag は本物のポインタドラッグを行います。

差が出るのは web だけです。web では方向指定 swipe が wheel スクロールになり、掴んだハンドルを動かせないため、その場合は drag を使います。iOS / Android では OS の本物のドラッグがスクロールもハンドル移動も兼ねるので、両者は一致します。

scroll

- scroll: { to: { id: notice.row.20 } }                 # 行が現れるまで下へスクロールし、続けて…
- tap: { id: notice.row.20 }
- scroll: { to: { label: "Log out", traits: [button] }, # 特定のコンテナをスクロールする…
            within: { id: settings.list }, maxScrolls: 25 }
- scroll: { to: { id: chart.point.7 }, amount: 0.2 }    # …既定より細かい歩幅で

scroll は画面外の要素を表示領域に入れます。1 ステップ分スクロールしてツリーを再クエリし、to が解決してそのフレームの中心が画面内に入った時点で止まります。中心は続く tap が狙う点なので、ビューポートより高い要素でも、中心が入りさえすれば成功します。

スクロールする領域(画面全体、または within が指すコンテナ)が末尾に達したと判定するには、証拠が必要です。scroll がコンテンツの末尾に達した(対象は領域内にない)と報告するのは、連続する 2 回の読み取りがコンテンツの静止を示したときだけです。示す形は次の 3 つです。

  • ループが動くのを見た要素がまだ存在して止まっており、しかも上部のクロームではなくスクロールする領域に属していること
  • 領域の境界が何も切っていないので、動きを隠せる frame がないこと
  • ツリーがそのどちらも示せないとき、描画された画面もステップの前後で変化していないこと

ふつうの行が並ぶツリーは 2 つめを最初のステップで満たすので、to の打ち間違いはそこで即座に失敗します。画面全体を覆うウィンドウや root view を報告するツリーは満たさないので、そうしたバックエンドでは 1 ステップ遅れて、描画された画面が速い失敗を受け持ちます。

どの証拠も得られないときは、scroll はステップを続け、maxScrolls(既定 15)に達した時点で、領域が動いたかどうかを観測できなかったと報告します。この失敗は、リストが終わったという主張とは別のことを述べています。両者の違いは実在します。Android は要素の bounds を見えている部分に切り取って報告するので、画面より高い行は、その裏でコンテンツがスクロールしていても同じ frame を報告します。

逆向きの誤りは、ステップの前に視野にあったものがその後どれも画面に残らなかったステップです。対象をビューポートの外へ運んでしまった可能性があるからです。一部だけ残っている場合も残ったと数えるので、一度に 1 枚のカードだけを見せる画面でのふつうのステップを取り違えることはありません。scroll は歩幅を半分にし、通り過ぎた範囲を読むために 1 回だけ逆向きにスクロールします。ループが取る最小の歩幅でもなお何も残らないときは、対象が見つからないと報告する代わりに、行き過ぎたことを名指して失敗します。

amount は 1 ステップが進む距離を、ビューポートに対する比で指定します。単位と範囲は swipe と drag の amount と同じで、0 より大きく 1 以下です。省略すると 1 ステップはビューポートの 0.6 を進みます。既定の歩幅が粗すぎて目的の要素をまたいでしまう画面では、amount を小さくします。1 ステップで現れる量が少なすぎて、maxScrolls が対象へ届く前に尽きる画面では大きくします。

amount が決めるのはループの出発点だけです。行き過ぎたときの半減は、amount が置いた歩幅からそのまま働きます。半減が止まる下限は amount に連動しません。下限と同じかそれより小さい amount には半減する余地がないので、最初に行き過ぎたステップで、そのステップが取った歩幅を名指して失敗します。

ステップが領域を動かしたかどうかは、1 回のクエリではなく再読み取りが判定します。再読み取りが効くのは Android です。Android ではジェスチャがリストを動かした後にアクセシビリティツリーが公開されるため、1 回だけ読み取ったツリーはスクロール前の画面を表し、末尾に達した状態と同じに見えます。確認にかかるのは Android が読み取りに対して申告した猶予の分だけで、しかも scroll が失敗するときの最後のステップに限られます。読み取りが遅れない web と iOS では、時間がかかりません。

within はジェスチャと、末尾および行き過ぎの判定を、1 つのスクロール可能なコンテナに限定します。省略すると画面全体をスクロールします。

対象を現れさせるなら scroll、決まったジェスチャなら swipe、掴んだハンドルを動かすなら drag を使います。各ステップは慣性を残しません。画面に対する有限の距離を進んで止まるので、同じシナリオが高速な実機と遅い CI エミュレータのどちらでも同じように対象へ届きます。手作業で調整した swipe の連鎖では保証できなかった決定論です。

1 ステップが進む距離は、そのステップが求めた距離になります。すべてのバックエンドで成り立ちます。ドライバー conformance スイートが 1 ステップの実移動量を測り、ジェスチャの終点より先へコンテンツが運ばれるバックエンドを不合格にするからです。それでも行き過ぎたステップは、前提として済ませずに、上の逆向きの読み取りで検出します。

scroll の direction は、指ではなくコンテンツが動く向きです。swipe とは逆になります。scroll: { direction: down } は fold より下のコンテンツを現します(ドライバーは指を上へスワイプします)。swipe: { direction: up } は指が上に動きます。scroll に手を伸ばす書き手は「リストを下へスクロールする」と考えるので、scroll はその向きを名前にします。swipe は指を名前にします。

doubleTap / pinch / rotate(ジェスチャ)

- doubleTap: { id: gest.doubletap }                    # two quick taps
- pinch:  { sel: { id: gest.pinch },  scale: 2.0 }     # >1 zooms in, 0<scale<1 zooms out
- rotate: { sel: { id: gest.rotate }, radians: 1.57 }  # >0 clockwise (radians)

scale は > 0 が必須です(違反は検証エラー)。pinch / rotate はマルチタッチが必要で、iOS(XCUITest)バックエンドと生成された XCUITest(pinch(withScale:) / rotate(_:))のどちらも備えています。マルチタッチのないバックエンドは "needs multiTouch" の理由で失敗します。doubleTap はどこでも動作します(2 回タップ)。

実物: doubleTap / longPress は demos/showcase/scenarios/gestures.yaml、pinch / rotate は demos/showcase/scenarios/gestures_multitouch.yaml です。

wait(条件待機)

wait が固定時間だけ待つことはありません(固定の待機は別の sleep ステップが担います)。timeout は必須です(無限待ちはできません)。

- wait: { for: { id: home.title }, timeout: 5 }            # until an element appears
- wait: { until: { gone: { id: home.spinner } }, timeout: 15 }  # until an element disappears
- wait: { until: screenChanged, timeout: 5 }              # until query() changes
- wait: { until: settled, timeout: 3 }                    # until the screen stops changing
- wait: { until: { request: { method: GET, path: /items, status: 200 } }, timeout: 8 }  # until a matching request is observed

for と until は排他です(片方のみ)。until の値は screenChanged / settled / { gone: <Selector> } / { request: <RequestMatch> } のいずれかです。

request 形式はネットワーク collector(evidence、--network 実行フラグ)をポーリングし、観測した通信が 1 件でも一致するまで待ちます。マッチャは request アサーションと同じで、method / url / urlMatches / path / pathMatches / status / bodyMatches を AND で評価し、count で閾値を上げられます。エンドポイントは url(完全一致の URL)か urlMatches(正規表現/部分一致)、または path だけで指定します。

タイムアウトの扱いは種別で異なります(run-loop)。for / gone / screenChanged / request はタイムアウトするとステップ失敗になります。settled は安定化のヒントなので、タイムアウトしても現在の画面で続行し、失敗にはなりません。

sleep(固定の待機)

wait が固定時間だけ待つことはありません。画面、ツリー、ネットワークログのどの条件でも観測できない、まれな遅延には sleep を使います。典型は、サーバー側の再試行制限や、until: settled より長く続くアニメーションです。

- sleep: { seconds: 2, reason: "the server throttles a retry for two seconds" }
  • seconds は 0 より大きく 30 以下です。これより長い固定の待機はほぼ確実に条件の書き漏れなので、読み込み時に拒否し、wait を案内します。
  • reason は必須で、空白だけにはできません。どの wait の条件でも表せない理由を書きます。進捗ログ、report.html、生成コードのコメントに表示されます。
  • このステップはツリーを読まず、入力も送りません。すべてのバックエンドで動き、run をキャンセルすると 0.25 秒以内に待機を抜けます。
  • bajutsu audit はすべての sleep を fixed-sleep の finding として列挙します。1 つのシナリオで固定の待機の合計が 10 秒を超えると Moderate と評価します。
  • record と crawl はモデルに sleep を提示せず、triage --ai は sleep を足す修正案に警告を出します。MCP サーバー経由で書いたシナリオは対象外なので、そこでの sleep は人が確認してください。

assert(中間検証)

ステップ途中での検証です。DSL(ドメイン固有言語)は expect と同一です(次節)。visual も例外ではありません。

ステップ自身の assert に含めた visual エントリは、その場で新しいスクリーンショットを1回だけ撮影します。撮影先はそのステップ自身のエビデンスディレクトリに限定されるため、シナリオの expect フェーズの撮影とも、別のステップの撮影とも衝突しません。responseSchema だけは、ステップの assert では評価できません。そこでは常に「no schema context」で失敗するため、expect に置いてください。

- assert:
    - disabled: { id: auth.submit }
- tap: { id: modal.open }
- assert:
    - visual: { baseline: modal.png }   # モーダルが開いた直後にその描画を検証する
- tap: { id: modal.dismiss }

ステップレベルの検証の最初の baseline は、bajutsu approve や serve UI の Approve ボタンからはまだ届きません。どちらも、現状はシナリオの expect 側の結果しか読みません。この対応が追いつくまでは、手動で baseline を用意してください。失敗したステップ自身の assertion_results は、実行の manifest.json に visual.actual としてパスを記録します(レポートの raw JSON 表示でも確認できます)。そのパスが指すファイルを、baseline: フィールドが指定する名前で baseline ディレクトリへコピーします。

setLocation / push(デバイス制御)

- setLocation: { lat: 35.681, lon: 139.767 }              # simctl location set
- push: { payload: { aps: { alert: "You have mail" } } }  # simctl push (APNs payload)

どちらも simctl 経由で Simulator を操作し、デバイスごとの制御チャネルが必要です。そのため fake ドライバや並列実行では使えず、その場合ステップはクリーンに失敗します(クラッシュはしません)。push は payload を APNs JSON として対象アプリに配信します。

http(テストデータ準備用のリクエスト)

- http: { method: POST, url: "https://api.test/seed", body: '{"n":1}', status: 200 }   # status が 200 以外なら失敗
- http: { url: "https://api.test/token", saveBody: token }   # vars.token ← レスポンスボディのテキスト
- http:
    method: POST
    url: "${secrets.API}/login"
    body: '{"user": "e2e"}'
    status: 200
    extractBody:
      - { var: token, path: "data.token" }        # vars.token ← ボディ全体ではなくネストしたフィールド
      - { var: userId, path: "data.user.id" }
- assert:
    - exists: { id: home.title }

http はリクエストを runner から HTTP で送ります。UI ドライバは経由しません。そのため status の不一致はステップ失敗になり、saveBody はレスポンスボディのテキストを ${vars.<name>} に保存して後続ステップで使えます。デバイスに触れない、ここで唯一のデバイス非依存アクションです。

extractBody(BE-0440)は、同じステップで saveBody と併用できます。片方だけの指定、両方の指定、どちらも指定しない場合のいずれも許されます。各エントリはレスポンスボディを JSON として解析し、path をたどって見つけた値を vars.<var> に保存します。

path はオブジェクトのキーと、[n](0 始まり)の配列インデックスからなります。先頭のキーに . は付けません(data.token)。インデックスは、キーの後にも別のインデックスの後にも続けられます(items[0].id、rows[0][1])。ボディ自体が JSON 配列なら、path はインデックスから始めても構いません([0].id)。

文字列の値はそのまま保存します。それ以外の JSON の値(数値、真偽値、null、オブジェクト、配列)は、キャプチャしたイベントボディのフィールドと同じ形式で保存します。具体的には、コンパクトな JSON テキスト(42、true、null、{"id":42})です。後続の ${vars.*} 比較が、API の返した形をそのまま読めるようにするためです。

レスポンスボディが JSON として解析できない場合は、JSON パーサーのメッセージのままステップが失敗します。path が解決できない場合は、var と path を含むエラーで失敗します。キーが見つからない場合、インデックスが範囲外の場合が、これにあたります。オブジェクト以外にキーを適用する場合、配列以外にインデックスを適用する場合も同様です。不正な path(負のインデックス、数値でないインデックス、空のセグメント、末尾のドット)も同じく失敗します。

path と var はそれ自体に ${vars.*} / ${secrets.*} 置換を使えます(path: "items[${vars.i}].id")。ただし path に差し込む値は、1 つのパスセグメントだけを供給しなければなりません。空の値や、.、[、] を含む値はステップを失敗させます。レスポンスボディ由来のフィールド名で、たどり先を別のフィールドへすり替えることを防ぐためです。

extractBody の 2 つのエントリが同じ var を持つ場合、または var が saveBody と一致する場合は、シナリオの読み込みでエラーになります。置換によって初めて衝突が判明する場合は、実行時のステップ失敗になります。どちらの場合も、書き込む順序によって片方が黙って上書きされることはありません。

totp(二要素認証のワンタイムパスワード)

- totp: { secret: "${secrets.TOTP_SEED}", into: { var: code } }   # vars.code ← 現在の 6 桁 OTP
- type: { text: "${vars.code}", into: { id: auth.code } }

totp は RFC 6238 の時刻ベースワンタイムパスワードを、共有 secret(base32。YAML に直書きせず ${secrets.*} に置く)と現在時刻からローカルで計算し、現在のコードを ${vars.<var>} に保存します。後続の type / assert で使えます。スクリプトのエスケープハッチも LLM も使わずに 2FA サインインを自動化でき、値は secret と時刻の決定的な関数です(BE-0046)。

コードが有効なのは、時刻を 30 秒ごとに区切った1つのウィンドウの間だけです。ウィンドウの終わり際に totp を実行すると、後続の type と tap で送信する前にコードが期限切れになることがあります。この失敗を防ぐには、minRemaining に後続のステップが必要とする秒数を指定します。

- totp: { secret: "${secrets.TOTP_SEED}", into: { var: code }, minRemaining: 10 }

現在のウィンドウの残りが minRemaining 秒より少ないとき、ステップは次のウィンドウが始まるまで待ってからコードを生成します(BE-0474)。値は 1 から 30 までの整数で、省略すると待ちません。

待機は、作成者が決めた長さで止まるのではなく、時計が決めるウィンドウの境界で終わります。そのため待ち時間は1ウィンドウ以内に収まり、決定性監査も fixed-sleep として挙げません。実行中のログはこのステップを totp (≥10s left) と表示し、待った時間はレポートのステップの所要時間に現れます。

待機の途中で壁時計が飛んだ場合(Network Time Protocol(NTP)による補正など)も、ステップは成功として扱われます。その代わり、レポートのステップ行に警告が残り、飛んだ秒数と残り秒数を示します。後のサインインが期限切れのコードで失敗したとき、この警告が原因の手がかりになります。

otp で後から新しいコードを取得する

コードを何度も入力するシナリオや、開始からかなり後でコードを入力するシナリオでは、シークレットを一度だけ登録し、コードが必要な時点でそれぞれ取得します。 totp ステップに name を付け、otp ステップの from でそのジェネレータを指定します。

- totp: { secret: "${secrets.TOTP_SEED}", name: main }   # ジェネレータを登録する。コードは書き込まない
- tap: { id: auth.change_password }
# ... 任意の数のステップ ...
- otp: { from: main, into: { var: code }, minRemaining: 10 }   # vars.code ← この時点で有効なコード
- type: { text: "${vars.code}", into: { id: auth.code } }

totp ステップには name と into の少なくとも一方が必要です。ジェネレータを登録するだけのステップは into を省略できます。 使用中の名前に別のシークレットを登録すると、ステップは失敗します。 totp ステップの minRemaining には into が必要です。コードを生成しないステップには、有効に保つコードがないからです。 totp ステップはシークレットを登録する時点で検証するので、不正なシークレットはあとの otp ではなくその totp ステップを失敗させます。

otp ステップは実行された時点で時計を読むので、各 otp はそのステップの時点で有効な窓のコードを書き込みます。 totp と同じ minRemaining の待機を指定でき、実行中のログはこのステップを otp (≥10s left) と表示します。 登録の順序は実行の順序に従います。 ジェネレータがまだ登録されていない otp はステップの失敗になり、実行されなかった if 分岐の中の totp も何も登録しません。 ジェネレータはシナリオの実行が終わるまで有効で、if、forEach、group の本体からも使えます。

登録したシークレットには、どの ${...} トークンからも届きません。そのため、シナリオがシークレットを読み出して入力欄へ入れることはできません。 otp ステップ自体はシークレットを持たないので、証跡に残るのはジェネレータの名前だけです。

email(メールで届くコードをメールボックスから取得)

- email:
    match: { to: "test@example.com", subjectMatches: "verification" }   # どのメッセージを待つか
    extract: { var: code, bodyMatches: "[0-9]{6}" }                     # vars.code ← 最初のキャプチャグループ
    timeout: 30
- type: { text: "${vars.code}", into: { id: auth.otp } }

email はメールで届く 2FA / 検証コードを待ちます。汎用 HTTP メールボックス(targets.<name>.services.mailbox で設定。configuration 参照)をポーリングし、ステップ開始後に届いたメッセージのうち match を満たすものが現れるまで待ちます。その本文から bodyMatches の正規表現(最初のキャプチャグループ、無ければマッチ全体)で値を ${vars.<var>} に取り出します。

待機は timeout 必須の条件待機です(固定 sleep なし)。タイムアウト、本文に正規表現が当たらない一致メッセージ、到達不能 / 2xx 以外のメールボックスは、いずれもクリーンなステップ失敗で、黙って誤った値を返すことはありません。対象はステップ開始より新しいメールだけ(メッセージ id で判定するので、以前の run の古いコードには一致しません)で、新着の一致が複数あれば最新を採ります。決定的で LLM 非依存です。エンドポイントと認証情報は config 参照の ${secrets.*} に置くので、シナリオはアプリ非依存のままです(BE-0046)。

generate(実行時に計算する値)

- generate: { random: { string: { length: 8, charset: alnum } }, into: { var: username } }
- type: { text: "${vars.username}", into: { id: signup.username } }

- generate: { random: { uuid: {} }, into: { var: orderRef } }        # バージョン4の UUID
- generate: { random: { int: { min: 1, max: 100 } }, into: { var: quantity } }
- generate: { random: { float: { min: 0, max: 50, precision: 2 } }, into: { var: amount } }   # 例 "12.30"

- generate: { datetime: { format: "%Y-%m-%d", offsetDays: 1 }, into: { var: tomorrow } }
- type: { text: "${vars.tomorrow}", into: { id: booking.date } }

generate はランナー側で値を計算し、${vars.<var>} に保存します。これにより、作者がリテラルとして 書けない入力値をシナリオが供給できます。以前の run がまだ使っていないユーザー名、予約フォームに 入れる翌日の日付、他のシナリオと衝突しない参照番号などです。データ駆動の行(再利用) は事前に用意した固定の表を配り、extract はアプリがすでに表示している値を取り込みます。どちらも シナリオ自身が値を作り出すわけではありません(BE-0377)。

値を作る生成カテゴリは、ちょうど1つ指定します。random が生成するのは、次の4種類です。

  • string:charset から length 文字を引いた文字列。charset の既定は alnum で、 ほかに alpha、numeric、hex を選べます。
  • int:[min, max] の閉区間の整数。
  • float:[min, max] の範囲の数値。任意の precision で小数桁数に丸めます。
  • uuid:バージョン4の UUID。

datetime は現在時刻をテキストにします。format は strftime のパターンを取り、省略時は 秒までの ISO 8601 になります。符号付きの offsetSeconds、offsetMinutes、offsetHours、 offsetDays は加算されて時刻をずらします。timezone は America/Los_Angeles のような Internet Assigned Numbers Authority(IANA)のゾーン名を取ります。既定のゾーンは UTC なので、 アプリがデバイス自身のゾーンで描画する日付に入力を一致させたいシナリオは、そのゾーンを明示します。 デバイス自身のゾーンを固定する部分は別の関心事です (BE-0158)。

値は run ごとに変わりますが、フローは決定的なままです。ローダが受理した generate ステップは、常に 実行され常に成功します。生成器から値を引くか、クロックを読むだけで、ネットワークとモデルのいずれにも触れません。 run ごとに違うのは生成された値だけで、これは totp の時刻由来のコードがすでにそうであるのと同じです。 描画できない format と解決できない timezone は、シナリオのロード時に拒否され、実行中に黙って別の 値に置き換わることはありません。

生成した値は manifest とレポートに記録されるので、後で失敗したときに その run が実際に使った値がわかります。特定の値を検証しなければならないシナリオは、その値を ${vars.*} に取り込んでから比較します。事前には知り得なかったリテラルと比較するわけにはいきません。 generate はアプリではなくランナーで動くため、どの codegen ターゲットもラベル付きの // TODO として 描画します。

eval(変数に入った値の変換)

- tap: { id: cart.open }
  extract:
    items: { sel: { id: cart.summary }, prop: label }   # "Apple, banana ,Cherry"

- eval:
    from: "${vars.items}"
    ops:
      - split: { by: "\\s*,\\s*", regex: true }
      - filter: { notEmpty: true }
      - sort
    into: { var: sortedItems }                           # ["Apple","Cherry","banana"]

- eval: { from: "${vars.sortedItems}", ops: [json, { pick: first }], into: { var: firstItem } }

- eval:
    from: "Taro Yamada"
    ops: [{ split: " " }]
    into: { vars: [givenName, familyName] }              # givenName=Taro, familyName=Yamada

- eval:
    from: "${secrets.API_TOKEN}"
    ops: [{ substring: { start: 0, end: 8 } }]
    into: { var: tokenPrefix }                           # 以後のすべての成果物でマスクされる

eval は、シナリオがすでに持っている値を変換し、結果を ${vars.*} に保存します。ターゲットが表示する値と、 後のステップが必要とする値は一致しないことがよくあります。たとえばカートのラベルを並べ替えた品目にしたい場合や、 Order #A-1042 confirmed というバナーから A-1042 だけを取り出したい場合です。eval がなければ、 作者は文字列全体を検証するか、変換をシナリオ外のスクリプトへ移すしかありません (BE-0472)。

名前に反して、このステップは任意のコードを実行しません。ops は固定の語彙から選び、シナリオが操作を追加することは できません。from は通常の ${...} 展開が効く文字列なので、2つの変数をつなぐだけなら操作は要りません (from: "${vars.a}-${vars.b}")。ops の各要素は、1つ前の要素の結果に対して順に適用されます。 引数のない操作は名前だけで書き、それ以外の操作はキーを1つだけ持つマッピングで書きます。

操作 書き方 入力 → 出力 動作
split split: "," または split: { by, regex? } 文字列 → リスト 区切り文字で分割する。regex が true なら正規表現で分割し、パターンのキャプチャグループは結果に含めない
join join: "-" リスト → 文字列 要素を区切り文字でつなぐ。空の区切り文字も使える
filter filter: { matches \| equals \| contains \| notEmpty, not? } リスト → リスト ちょうど1つの条件を満たす要素を残す。not: true なら満たさない要素を残す
pick pick: first、last、または添字 リスト → 文字列 要素を1つ取り出す。添字は 0 から数える
count count リスト → 文字列 要素数を10進数の文字列で返す
sort sort、sort: desc、または sort: { order, numeric? } リスト → リスト Unicode のコードポイント順に並べる。numeric: true なら数値順に並べる。desc は sort の後に reverse を適用した結果と同じ
unique unique リスト → リスト 重複を除き、最初に現れた要素を残す
reverse reverse リスト → リスト 順序を逆にする
json json 文字列 → リスト JSON 配列を解析する。文字列でない要素はコンパクトな JSON テキストにする
regex regex: { pattern, group? } 文字列 → 文字列 最初の一致のうち、キャプチャグループ group を返す。group を省略すると 0(一致全体)になる
replace replace: { find, with, regex? } 文字列 → 文字列 一致する箇所をすべて置き換える
substring substring: { start, end? } 文字列 → 文字列 start から end の手前までの文字を返す。どちらも 0 から数える
trim trim 文字列 → 文字列 前後の空白を取り除く
case case: lower または upper 文字列 → 文字列 大文字と小文字を変換する

結果は into に保存します。

  • into: { var }:値を1つ保存します。文字列はそのまま保存します。リストは ["a","b"] のような コンパクトな JSON 配列テキストとして保存し、後の eval で json を使うとリストに戻せます。
  • into: { vars: [...] }:リストの結果を、先頭から順に複数の変数へ振り分けます。最初の要素は最初の名前に、 2番目の要素は2番目の名前に入ります。リストが vars より長ければ、余った要素は使いません。リストが短ければ ステップを失敗させます。値の入らない変数を残すと、後のステップで無関係な不一致として表面化するからです。

ローダは、実行の前にステップを検査します。from から最後まで、値が文字列かリストかを追跡し、型の合わない操作が あればロード時のエラーにして、その操作を名指しします。ほかにも、空の ops、空の split 区切り文字、条件が 0個または複数の filter、負の添字、未知の sort の順序を拒否します。文字列の結果に対する into.vars と、 不正な正規表現も同じく拒否します。

自由文と添字の引数には ${vars.*} や ${secrets.*} のトークンを書けます。トークンを含む 引数はロード時に判定できないので、実行時に置換してから同じ検査を適用します。決まった値から選ぶ引数 (sort の order と case)と、フラグの regex、not、numeric にはリテラルだけを書けます。

次の場合、ステップは実行時に失敗し、代わりの値を使いません。

  • regex が一致しない、または指定した group がない
  • 添字や substring の範囲が値の外にある
  • json が JSON 配列でないテキストを読んだ
  • numeric の並べ替えで数値でない要素に出会った
  • ${...} のトークンに値が束縛されていない
  • 値が 1,048,576 文字または 10,000 要素を超えた

失敗メッセージは操作の位置と名前を示し、値そのものは引用しません。失敗したステップは変数に何も書き込みません。 生成した値は、generate と同じくマニフェストとレポートに記録します。

secret から導いた結果は、それ自体も secret として扱います。入力が secret とみなされるのは、from か引数に ${secrets.*} が含まれるときです。以前の eval が secret とした ${vars.*} が含まれるときも同じです。 このとき run は、その結果をシナリオのそれ以降の証拠でマスクする値に加えます。あわせて、保存先の変数を secret として記録します。マスクはそのステップ自身のレポート行にも及びます。例外は count だけです。 要素数には入力の文字が1文字も含まれないからです。

ステップより前に書いた証拠は書き換えません。失敗理由と生成した値もマスクするので、マニフェスト、レポート、CI の注記にその値は現れません。 どの codegen ターゲットも eval をラベル付きの // TODO として出力します。このステップはアプリではなくランナーの中で動くからです。

manual

record 中に記録される人による操作の引き取りです。

- manual: { label: "ログインの CAPTCHA を解く" }                          # 決定的な等価物なし(本物の CAPTCHA)
- manual: { label: "Face ID を許可する", bypass: "device-control の生体認証マッチ(BE-0052)" }   # 作者が配線できる橋渡しを名指し

record は、詰まりが AI に実行できない操作そのものであるとき manual ステップを出します。CAPTCHA、生体認証のプロンプト、AI が繰り返し解けないジェスチャが該当します。人が実際のデバイスを操作して制御を返し(acted ハンドオフ、recording)、ステップは生のジェスチャではなく観測した遷移のマーカーを記録します。

bypass を設定すると、そのステップを再生可能にするために作者が配線できるテストビルド用のフラグ、あるいは device-control / device-state プリミティブ(BE-0035 / BE-0052)を名指しします。省略すると、そうした等価物のない引き取り(本物の CAPTCHA)であることを示します。どの codegen ターゲットもこれをラベル付きの // TODO として描画します。

manual ステップは決して黙って合格しません。決定的な実行時の等価物がないため、run 時には label と bypass のヒントを示して ManualStepRequired で明示的に失敗します(原則 1・2)。作者にとって再生可能なシナリオへの道は、名指しした bypass を配線し、そのうえで manual ステップを決定的なアクションに置き換えることです(BE-0185)。

デバイス / システム制御

- background: {}                                                        # Home ボタン(SpringBoard 経由でバックグラウンド化。終了はしない)
- foreground: {}                                                        # アプリを前面に出す。動いていなければ起動する
- clearKeychain: {}                                                     # 保存済みパスワード / 証明書をリセット
- clearClipboard: {}                                                    # ペーストボードをクリア
- setClipboard: { text: "COUPON123" }                                   # ペーストボードに投入(ペースト操作用)
- overrideStatusBar: { time: "9:41", batteryLevel: 100, wifiBars: 3 }   # ステータスバーを固定
- clearStatusBar: {}                                                    # ライブのステータスバーに戻す

iOS では、これらのステップは setLocation / push と同じく simctl 経由で Simulator を操作します。そのためデバイスごとの制御チャネルが必要で、fake ドライバや並列実行ではクリーンに失敗します。Android では、この一覧のうち clearKeychain 以外のステップが動きます。Android にはキーチェーンがないからです。overrideStatusBar は、スクリーンショットや visual アサーションの直前に使います。時計や電波表示を固定して、画像を安定させます。

Android では、adb がアプリ内のコードなしでこれらのステップを動かします(BE-0478)。

ステップ Android での仕組み
background Home キーを押します(input keyevent KEYCODE_HOME)。アプリのプロセスは残ります
overrideStatusBar System UI のデモモードに入り、指定したフィールドごとにコマンドを1つ送ります
clearStatusBar デモモードを抜け、実際のステータスバーに戻します

background は、アプリが resumed activity でなくなるまで条件待ちをします。アプリが前面に残ったままなら、ステップは失敗します。background のあとはランチャーが前面に来ます。そのため、テスト対象アプリの要素を指すセレクタは何も見つけません。iOS でホーム画面が前面にあるときと同じです。デバイスグループの中では、foreground ステップでアプリを戻すまで、読み取りが AppNotInFront で失敗します。

デモモードには、simctl status_bar と違う点が3つあります。

  • 未指定のフィールドも固定されます。 デモモードに入ると、すべてのアイコンが固定されます。ステップが指定しなかったフィールドは、実際の値ではなくデモモード自身の固定値になります。iOS のステータスバーは通知アイコンを出さないので、このステップも通知アイコンを隠します。
  • 受け付ける値が狭くなります。 Android で受け付ける値は下の表のとおりです。それ以外の値は、プリフライトがデバイスを操作する前に失敗させ、そのステップを名指しします。System UI はそうした値を無視しますが、ブロードキャストは成功を返してしまうからです。
  • Wi-Fi の本数は換算します。 Android の Wi-Fi レベルは 0–4 なので、iOS で満タンの電波は Android でも満タンにします。換算は下の表のとおりです。
フィールド Android で受け付ける値 換算
time H:MM または HH:MM 4桁の時刻にします(9:41 は 0941)
batteryLevel 0–100 そのまま
batteryState charging、charged、discharging 前の2つで plugged を true にします
cellularBars 0–4 そのまま
wifiBars 0–3 0、1、2、3 をレベル 0、1、3、4 にします

どちらのプラットフォームでも、上書きは clearStatusBar ステップを実行するまでデバイスに残ります。

background / foreground はバックグラウンド/フォアグラウンド遷移の対で、foreground は何も終了させません。foreground が待つかどうかは場合によって異なります。

  • iOS でデバイスグループに入っていない場合、動いているアプリはまったく待たずに復帰します。必要なら直後に具体的な要素を待ってください。
  • installApp の直後のように動いていないアプリは、relaunch と同じように起動します。foreground はその後、アプリの準備が整うまで条件待ちをします。
  • Android と、デバイスグループ内の iOS では、動いているアプリにも条件待ちをします。アプリが前面に来なければ、ステップは AppNotInFront で失敗します。 この待ちは、ターゲットの subject.startWhen ではなく、そのアプリ自身の画面が出るのを待ちます。subject.startWhen は 起動直後の画面を指しますが、再開したアプリは離れたときの画面に戻るからです。

setClipboard はペースト操作のためペーストボードに値を投入します(BE-0052)。

targets / target(複数ターゲットシナリオ、BE-0428)

シナリオのトップレベル targets フィールドは、このシナリオが操作する target をすべて名指しします。たとえば、同じサービスの2つのクライアントである iOS の target と web の target を並べられます。1つのシナリオが、あるターゲットで操作し、別のターゲット で結果を確認できます。この2つは自由に組み合わせられ、1回の決定的な run として1つの判定にまとまります。 各エントリは targets.<name> の config ユニットを名指しします。--target がすでに解決するのと同じユニットです。 同じターゲット名を2回名指しすると、読み込み時のエラーになります。targets を宣言しないシナリオ (既定)は、今日の挙動のままです。その中のステップも target の省略が必須です。

bajutsu run は、シナリオの最初のステップより前に、宣言済みのターゲットをすべて起動します。最後の ステップのあとに、まとめて終了させます。ステップがターゲットの起動を待つことはありません。上で述べた 組み合わせに、余分な起動時間はかかりません。宣言済みの各名前は、その起動が読み込む1つの config ファイル から解決します。両方のターゲットが、そのファイルに targets.<name> エントリとして並んでいる必要が あります。2つの config ファイルを結合する仕組みはありません (configuration)。

targets が2つ以上のエントリを持ち、primaryTarget(後述)を設定していないシナリオでは、 すべてのステップが自分の target を設定しなければなりません。 if / forEach / web のラッパーステップも対象で、末端のアクションだけではありません。トップレベルの expect エントリも同様で、それぞれが宣言済みのターゲットの1つを名指しします。

- name: liking a post on the app shows up on the web
  targets: [showcase-app, showcase-web]
  steps:
    - target: showcase-app
      tap: { id: post.like }
      extract:
        postId: { sel: { id: post.id } }
    - target: showcase-web
      wait: { for: { id: "post.${vars.postId}.likeCount" }, timeout: 10 }
  expect:
    - target: showcase-web
      value: { sel: { id: "post.${vars.postId}.likeCount" }, equals: "1" }

1つのターゲットの流れを軸にしたシナリオは、そのターゲットを primaryTarget として宣言できます (BE-0436)。宣言すると、ステップとトップレベルの expect エントリは target を省略でき、省略した ものは主ターゲットに対して走ります。target を書くのは別のターゲットを操作するステップだけになるので、 読み手はそのステップをひと目で見分けられます。

- name: liking a post on the app shows up on the web
  targets: [showcase-app, showcase-web]
  primaryTarget: showcase-app
  steps:
    - tap: { id: post.like }              # target を省略:showcase-app で走る
      extract:
        postId: { sel: { id: post.id } }
    - target: showcase-web
      wait: { for: { id: "post.${vars.postId}.likeCount" }, timeout: 10 }
  expect:
    - target: showcase-web
      value: { sel: { id: "post.${vars.postId}.likeCount" }, equals: "1" }

primaryTarget には targets の先頭のエントリを指定しなければなりません。runner は、すでにその エントリを主ターゲットとして扱い、リース、復旧、エビデンスの基準にしています。primaryTarget を 先頭のエントリに固定しておけば、ファイルと runner が主ターゲットについて食い違うことはありません。 primaryTarget を直さずに targets の順序を入れ替えると、読み込み時のエラーになります。targets を 宣言していないシナリオに primaryTarget を設定した場合も、読み込み時のエラーです。宣言済みの ターゲットが1つのときは、そのターゲットを primaryTarget に指定でき、挙動は変わりません。

この省略時の解決は、入れ子の深さによらず同じように働きます。if や forEach の中のステップも target を省略でき、省略したステップは、囲んでいるラッパーがどのターゲットを指していても主ターゲット に対して走ります。ステップが主ターゲットを明示してもかまわず、どちらの書き方でも挙動は同じです。 ローダーは、解決したターゲット名をステップに書き戻しません。serve のエディタと、run が保存する scenario.yaml のスナップショットは、作者が書いたとおりの簡潔なステップを保ちます。

自分で targets を宣言するシナリオは、ターゲットを自力で解決します。bajutsu run --scenario <file> には --target がまったく要りません。そのシナリオに --target を明示して渡した場合、そのシナリオが 宣言しているターゲットのどれかを名指ししている必要があります。ファイルを編集したあとに残った古いフラグは、 run を止めます。ファイルが外したターゲットを選ぶことはありません。完全な規則と、どの起動で --target が依然として必須かは、コマンドラインリファレンスにあります。

宣言済みターゲットが1つだけのとき、ステップは target を省略できます。そのターゲットを直接名指し してもかまいません。どちらの書き方でも挙動は同じです。

シナリオは、自分を実行するマシンへの要件を宣言しません。Bajutsu がシナリオから要件を算出します。要件は、 宣言した各ターゲットが解決するドライバと、宣言したターゲットの数です。数はすべてのドライバをまたいで 合計するので、Simulator のターゲットとブラウザのターゲットは合わせて2つと数えます。bajutsu run は デバイスを操作する前に、この要件をマシンの worker 能力ファイルと ホストの OS に照らします(BE-0450)。このマシンで実行できないシナリオは、 worker-capability-unsupported: で始まり、ドライバか上限を名指しする理由で失敗します。残りのシナリオは 実行します。

${vars.*} は、1回の run の中で宣言済みのすべてのターゲットをまたいで持ち越されます。これは runtime variables が指すのと同じ、extract が生成する変数です。あるターゲット のステップが捕まえた値は、別のターゲットに対するアサーションから読み出せます。プラットフォームをまたぐ 検査は、これによって両側が触れたレコードそのものを名指しできます。単に何かのカウントが変わったこと だけを主張する必要はありません。

web ブロックまたは app ブロック内で入れ子になったステップだけは例外です。target は完全に 省略しなければなりません。このステップは、囲んでいるブロックがすでに解決したデバイスに対して、 常に走ります。web なら自分自身の WebView ブリッジ、app なら変わらない同じネイティブドライバ です。

ターゲットグループ:連続するステップに対してターゲットを1回だけ書く(BE-0437)

上で見た target は、1つのターゲットに対して連続するステップの列に、同じ値を繰り返し書かせます。 ターゲットグループは、この繰り返しをなくします。target を1回だけ設定し、そのステップ1つ1つに target を刻む代わりに、実行するアクションをすべて自分の steps の下にまとめる、そういうステップ です。

- name: favorite a horse on the iOS showcase, then carry what it captured into the web demo
  targets: [showcase-swiftui, web]
  steps:
    - target: showcase-swiftui
      steps:
        - wait: { for: { id: [stable.row.1, stable_row_1] }, timeout: 10 }
        - tap: { id: [stable.row.1, stable_row_1] }
        - wait: { for: { id: [horse.favorite, horse_favorite] }, timeout: 5 }
        - tap: { id: [horse.favorite, horse_favorite] }
          extract:
            favorited: { sel: { id: [horse.favorite.value, horse_favorite_value] } }
    - target: web
      steps:
        - tap: { id: onboarding.start }
        - type: { text: "favorited-${vars.favorited}@example.com", into: { id: auth.email } }
        - type: { text: "pw", into: { id: auth.password } }
        - tap: { id: auth.submit }
        - wait: { for: { id: home.title }, timeout: 5 }
        - tap: { id: counter.increment }
  expect:
    - target: showcase-swiftui
      value: { sel: { id: [horse.favorite.value, horse_favorite_value] }, equals: "on" }
    - target: web
      value: { sel: { id: counter.value }, equals: "1" }

フラットな書き方、つまり1ステップに1行の target: では、この同じシナリオに10行が要ります。ここでは ターゲットを2箇所で名指しするだけで、同じ2つのまとまりを表せます。上の行と食い違う target: 行 そのものが、存在しません。

ターゲットグループは、純粋な記述の糖衣構文です。この節より先にあるほかの規則を適用する前に、ロード時 の1パスがターゲットグループを展開します。展開後の形は、手書きのシナリオがすでに使っている、フラット で1ステップ1行の target: です。bajutsu run、レポート、CLI のどれも、ターゲットグループを目にしま せん。見るのは、展開済みのステップだけです。

ターゲットグループ自身の target は、必須です。シナリオがターゲットを0個または1個しか宣言していなく ても、primaryTarget(前述)を宣言していても、これは変わりません。末端のアクション自身の target とは、ここが違います。末端のアクションなら target を省略して、プライマリに対して走らせられます。 ターゲットグループの役割は、自分の配下にあるステップに対してターゲットを1回だけ固定することなので、 固定する先がつねに要ります。capture / extract / name / from も、ターゲットグループには 許されません。どれも、run が実行する、たった1つのステップから読み出すフィールドです。ターゲット グループは run に届くことがありません。展開が、ターゲットグループを自分の配下のステップに置き換えて しまうからです。この4つのどれかを設定しても、その値は黙って消えます。

グループ自身の steps へ直接入れ子になったステップは、target を省略しなければなりません。 末端のアクション、if、forEach、web / app ブロックのどれであっても同じです。グループが すでに固定しているからです。それでも子が target を設定すると、暗黙に上書きされるのではなく、 ロード時のエラーになります。ターゲットグループを別のターゲットグループへ直接入れ子にした場合も、 同じ理由でエラーです。ネストしたグループは自分自身の target をつねに設定しますが、それこそが 直接の子には許されない設定だからです。

この省略の規則は、直接の子だけに及び、再帰しません。グループへ直接入れ子になった if や forEach は、末端のアクションと同じように、自分自身へグループのターゲットを継承します。ただし、その then、else、本体の中は新しいスコープです。そこでは、グループの外と同じく、それぞれが自分の target かターゲットグループを、あらためて明示しなければなりません。グループへ直接入れ子に なった web ブロックや app ブロックも、同じようにグループのターゲットを継承します。そのターゲット に対して、自分のブリッジを開きます。そのブロックの中へさらに入れ子になったステップは、グループとは 関係なく、上で述べた既存の規則どおり target を省略し続けます。

ターゲットグループは、web: ブロックや app: ブロック自身の入れ子ステップの中では、頭から拒まれ ます。そこではどのステップも、ブロック自身がすでに解決した1つのターゲットに対して、すでに走ってい ます。グループを置いても、同じターゲットを無意味に繰り返すか、どのドライバも開いていない別のター ゲットを名指しするかのどちらかにしかなりません。

複数ターゲット run での、残りの config の扱い

宣言済みの各ターゲットは、主ターゲットのものではなく、自分自身の config を読みます。ターゲットごとに 解決するものは次のとおりです。

そのターゲット自身の config を読むもの 理由
hooks.setup / hooks.cleanup のライフサイクルステップ 各ターゲット自身のものが宣言順に畳み込まれ、そのターゲット名が刻まれます。アプリ側のティアダウンと web 側のティアダウンが、それぞれ正しいドライバに対して走ります
services.mailbox email や totp のステップは、自分のターゲットが設定した受信箱をポーリングします
runsOn.ios.locale、subject.launch.env、evidence.capture、hooks.interrupts どれも run ではなく、テスト対象アプリの性質です
paths.baselines / paths.schemas / paths.goldens visual や golden のアサーションは、そのターゲットが自分でディレクトリを設定していればそちらと、していなければ run のものと比較します
バックエンドの capability 各ターゲットのステップは、デバイスを1つも確保する前に、そのターゲット自身のバックエンドに対して検査されます。片方のプラットフォームだけが対応する構文は、正しいほうを落とします

フック自身の if や forEach のステップが target を省略すると、そのフック自身のターゲットに 解決されます。シナリオの primaryTarget には解決されません。上で述べた、入れ子の深さによらない 省略時の解決は、シナリオ自身のステップにだけ働きます。

run 全体で共有されるものが2つあります。redact の秘密情報の集合は、宣言済みの各ターゲット自身の秘密情報(evidence.secrets) の和集合を取ります。その和集合が、すべてのターゲットの証跡をマスクします。広くマスクしすぎるほうが安全な 誤りだからです。run ディレクトリは run 単位の成果物で、もともとターゲットごとではありません。

web エンジンのフラグは、run の単一の web ターゲットに対して引き続き適用されます。対象は --headed、 --browser、--browsers の3つです。web プラットフォームのターゲットを2つ名指しするシナリオは、この3つ をすべて拒みます。どちらを指しているのかに答えがないためです。クロスブラウザマトリックスを複数ターゲットの run へ広げるのは、別の作業です。

デバイスグループ(1台のデバイスで複数のアプリを動かす、BE-0447)

宣言した各ターゲットは、デフォルトではそれぞれ専用のデバイスを持ちます。しかし、1台のデバイスに2つの アプリが要る流れもあります。

  • アプリのアップデート:旧ビルドの上に新ビルドをインストールします。そのうえで、旧ビルドの書いた データが残っているかを確かめます。
  • コンパニオンアプリ:テスト対象のアプリの隣で動き、コードを渡します。多要素認証(MFA)アプリが一例です。

デバイスグループは、このどちらも表せます。デバイスグループとは、2つ以上の名前を持つ targets の エントリのことで、そのメンバーは1台のデバイスを共有します。

config は変わりません。1つのアプリの2つのビルドは、2つのターゲットになります。2つのターゲットは subject.id(バンドル識別子。Android ではパッケージ)を共有し、それぞれ自分の subject.path を持ちます。コンパニオン アプリは、独立した1つのターゲットです。

targets:
  showcase-previous:                      # シナリオの開始時に動かす旧ビルド
    platform: ios
    subject: { id: com.example.showcase, path: build/Showcase-1.app }
  showcase:                               # 現行ビルド
    platform: ios
    subject: { id: com.example.showcase, path: build/Showcase-2.app }

targets に書いた素の名前は、メンバーが1つだけのグループとして扱われます。配列を書かないシナリオは、 これまでどおりに動きます。ローダーは一覧に次の3つの規則を課します。

  • 名前は、入れ子かどうかにかかわらず、一覧全体で一度だけ現れます。
  • 配列は2つ以上の名前を持ちます。ターゲットが1つなら素の名前で書きます。
  • primaryTarget は、最初のグループの最初のメンバーを指します。

開始時に動かすメンバー(installs)

グループのすべてのメンバーが、開始時からデバイスに載っているとは限りません。アップデートのシナリオは 旧ビルドで始まり、新ビルドを後に取っておきます。トップレベルの installs 一覧は、プライマリと並んで 開始時に動かすメンバーを指定します。

メンバー 開始時の扱い
プライマリ(最初のグループの最初のメンバー) subject.path をインストールして起動します。installs への記載は任意です
メンバーが1つのグループ(素の名前) 複数ターゲットシナリオと同じく、インストールして起動します
installs に書いたメンバー インストールして起動します
2つ以上のメンバーを持つグループの、それ以外のメンバー 後から入るメンバーです。installApp ステップと foreground ステップが立ち上げるまで、インストールも起動もしません

プライマリを含まないグループは、自分のメンバーを少なくとも1つ installs に書く必要があります。 そうすれば、どのメンバーで始めるかをローダーが推測せずに済みます。

デバイス全体の準備は、グループごとに一度だけ走ります。対象は消去(erase)、システムロケールの固定、 写真の投入です。2つ目に開始するメンバーは消去を繰り返さずにインストールするので、最初のメンバーを 消すことはありません。

後から入るメンバーのインストール(installApp)

installApp: { from: <target> } は、後から入るメンバー from のビルドをインストールします。 インストール先は、ステップ自身の target のデバイスです。target を省略したステップは、プライマリの デバイスにインストールします。ステップはまず、同じ識別子で動いているアプリを終了させます。その後に ビルドをインストールします。

  • keepData: true(デフォルト)では、既存のビルドの上にインストールします。データコンテナは残ります。
  • keepData: false では、先にその識別子のアプリをアンインストールします。

このステップは何も起動しません。メンバーに宛てた foreground ステップがビルドを起動します。

ローダーは、次の場合の installApp を拒みます。

  • from が、開始時に動かすメンバーを指しています。
  • from が、ステップのデバイスを持つグループとは別のグループに属しています。
  • トップレベルの2つ目の installApp が、同じメンバーを指しています。メンバーのインストールは シナリオにつき一度です。
  • ステップが web: や app: ブロックの中にあります。ブロックはデバイスを選ばないためです。
  • ステップが interrupts の復旧ステップの中にあり、ステップとエントリのどちらにも target を書いていません。この規則は、シナリオが setPrimaryTarget を含むときに適用されます。

ループや復旧が同じ installApp へ二度目に到達した場合は、実行時に名前付きのエラーで失敗します。 シナリオが指すのはターゲットであってパスではないので、ビルド成果物は config に留まります。

デフォルトのターゲットの移動(setPrimaryTarget)

setPrimaryTarget: { target: <target> } は、デフォルトのターゲットを移します。このステップ以降、 target を省略したステップは、指定したターゲットで動きます。interrupts エントリとトップレベルの expect エントリも同じです。

このステップが変えるのはルーティングだけです。デバイスの確保、証跡のディレクトリ、クラッシュからの 復旧は、宣言したプライマリのままです。setup と cleanup のフェーズでも、省略した target は宣言した プライマリに解決します。後片付けは run がどこで止まっても走る必要があるためです。

setPrimaryTarget を書けるのは、シナリオのトップレベルの steps だけです。ローダーは、次の構文の 中にある setPrimaryTarget を拒みます。

  • if や forEach
  • ターゲットグループ、web:、app:
  • interrupts エントリ
  • setup や cleanup

この配置の制限があるので、ローダーはステップを順にたどって現在のプライマリを追えます。コンポーネントの 中の setPrimaryTarget は、そのコンポーネントを呼ぶ use: や group: がトップレベルにあれば有効です。 展開は、呼び出し側の target を setPrimaryTarget に刻みません。

アプリの切り替えと、退いたメンバー

デバイスが前面に出せるアプリは一度に1つなので、シナリオは明示的に切り替えます。メンバーに宛てた foreground ステップは、そのメンバーのアプリを前面に出します。アプリがまだ動いていなければ、 foreground はアプリを起動し、準備が整うまで待ちます。ランナーが、ステップの間で勝手にアプリを 切り替えることはありません。

1台のデバイスが2つ以上のメンバーを持つ場合、各メンバーのドライバは、まず自分のアプリが前面にあるかを 確かめます。アプリが別のアプリの裏にあるメンバーへのステップは、AppNotInFront で失敗します。この エラーは原因を名指しし、foreground を案内します。ステップが別のアプリのツリーに対してセレクタを 解決することはありません。

後から入るメンバーは、3つの状態を順に進みます。状態が許していないステップをメンバーに宛てると、 名前付きのエラーで失敗します。

状態 メンバーに宛てられるステップ
未インストール installApp と setPrimaryTarget
インストール済み、未起動 foreground と setPrimaryTarget
実行中 すべてのステップ

インストールは、ビルドと識別子を共有するすべてのメンバーを退かせます。アップデートのシナリオでは、 新ビルドが上書きインストールされた時点で、旧ビルドのメンバーが退きます。退いたメンバーに宛てた ステップは、名前付きのエラーで失敗し、新ビルドには届きません。コンパニオンアプリは識別子が異なるので、 インストールしても最初のアプリの隣に2つ目のアプリが加わるだけで、どのメンバーも退きません。

デバイスを確保する前に run が確かめること

run は、デバイスを確保する前に、すべてのデバイスグループを config と照合します。拒んだ場合、 run は終了コード 2 で終わります。拒むのは次の場合です。

  • 1つのグループのメンバーの間で、プラットフォーム、バックエンド、デバイスの経路、実効 locale の いずれかが異なります。デバイスの経路とは、デバイスプロバイダ(--worker-config で指定する appium 環境)と runsOn.ios.kind のことです。
  • 2つ以上のメンバーを持つグループに web ターゲットがあります。ブラウザには共有するデバイスがないためです。
  • 1つのグループで開始時に動かす2つのメンバーが、識別子を共有しています。2つ目のインストールが 1つ目を置き換えてしまいます。
  • installApp.from のターゲットに subject.path がないか、その subject.path が存在しません。Git から 取得する config では、プライマリと同じく必要なときにバイナリをビルドします。
  • setPrimaryTarget が、先行する installApp で退いたメンバーを指しています。

デバイスプロバイダによっては、アプリをインストール済みの状態でデバイスを渡してきます。run は そうしたデバイスを予約した時点で、そのプロバイダから来たメンバーを含むグループを拒みます。バイナリを 持っているのはプロバイダなので、手元のビルドを隣にインストールできないためです。

iOS Simulator(XCUITest)と Android(adb)のバックエンドがデバイスグループに対応しています。実機の iPhone は対応していません。コード生成は、installApp と setPrimaryTarget をラベル付きの // TODO として出力します。

2つの例

アップデートのシナリオは、旧ビルドで始めてデータを作ります。その上に新ビルドをインストールし、 データが残っているかを確かめます。

- name: notes survive the update
  targets: [[showcase-previous, showcase]]
  primaryTarget: showcase-previous
  steps:
    - tap: { id: notes.add }
    - type: { text: hello, into: { id: notes.field } }
    - installApp: { from: showcase }          # showcase-previous が退く
    - setPrimaryTarget: { target: showcase }
    - foreground: {}                          # プライマリになった showcase を起動する
    - wait: { for: { id: notes.item }, timeout: 10 }
  expect:
    - exists: { id: notes.item, label: hello }   # showcase に解決する

コンパニオンのシナリオは、1台のデバイスでアプリと並べて認証アプリを開始します。web クライアントは 別のデバイスを使います。

- name: read the code in the authenticator, enter it in the app
  targets:
    - [showcase, authenticator]     # 2つのアプリを載せる1台のデバイス
    - showcase-web                  # 専用のデバイス
  primaryTarget: showcase
  installs: [authenticator]
  steps:
    - target: authenticator
      foreground: {}
    - target: authenticator
      tap: { id: code.show }
      extract:
        code: { sel: { id: code.value } }
    - foreground: {}                # showcase に戻る
    - type: { text: "${vars.code}", into: { id: login.otp } }
    - target: showcase-web
      wait: { for: { id: session.active }, timeout: 10 }

showcase のデモは、この 2 つの流れを iOS と Android の両方で実行します。実物は次の 2 つのファイルです。

デモのアップデートのシナリオは、インストールをまたいで内容が残る画面にメモを保存し、新ビルドを インストールしたあとでそのメモを読み戻します。コンパニオンアプリには、bundle id が異なるもう一方の ツールキットの showcase アプリを使います。

制限

Assertion.target は Step.target より狭い規則に従います。トップレベルの expect エントリだけが、 これを設定できます。ステップのインラインの assert: リストを通して届くアサーションは、囲んでいる ステップ自身の target によって、すでにターゲットが決まっています。if の condition を通して届く アサーションも同様です。そこで target を設定すると、その値を言い直すか、矛盾させるかのどちらかに なります。interrupts エントリの condition も同じように拒まれます。condition がポーリングする ツリーは、エントリ自身の target が決めます。ローダーは、以上の3か所すべてで、読み込むときに target を 拒みます。

同じバックエンドの2つのターゲットは、1つのデバイスプールを共有します。シナリオは、デバイスグループ ごとに1台のデバイスを、そのシナリオの全長にわたって保持します。素の名前は、メンバーが1つのグループと 数えます。グループに入れていない iOS のターゲットが2つあれば、デバイスも2台必要です。--udid a,b の 形で、グループごとに1台ずつ渡してください。プールのデバイス数がシナリオの必要数に満た ないとき、run は起動の時点で拒みます。空きが永久に出ないキューで待ち続ける代わりです。run は --workers も抑えます。同時に走るシナリオが互いのデバイスを奪い合わないようにするためです。

レポートに出るもの

レポートの各ステップの行には、それを走らせたターゲットの名前が出ます。ターゲットを宣言しないシナリオは、 このラベルが従来どおり空です。manifest.json はステップごとに同じ名前を持ちます。さらに、宣言済みの ターゲットごとに target_devices の行を1つ持ちます。各行には、そのターゲットのバックエンド、デバイス、 機種、OS バージョンが入ります。

複数ターゲットの run では、単数形の4つのフィールドが空のままになります。backend、device、 device_name、device_runtime の4つです。どれももう、シナリオ全体を説明していません。これは engine がすでに使っている「空は該当なしを意味する」規則と同じです。単一ターゲットの run の読み手には、4つとも 従来どおり見えます。

アサーション DSL

expect(最終検証)と assert(中間検証)で共通です。リスト内はすべて AND で評価し、1 つでも失敗するとステップ失敗になります。評価の仕組み(要素の解決と比較)は selectors にあります。

アサーション 意味 例
exists 一致要素が存在する(negate: true で不在を検証) exists: { id: home.title } / exists: { id: settings.banner, negate: true }
value accessibility value の一致 value: { sel: { id: counter.value }, equals: "2" }
label label の完全一致 / 部分一致 / 正規表現 label: { sel: { id: settings.status }, contains: "done" }
count 一致要素数 count: { sel: { idMatches: "list.row.*" }, equals: 5 }
enabled / disabled 操作可否(notEnabled trait) disabled: { id: auth.submit }
selected 選択 / トグル状態(selected trait) selected: { id: tab.home }
request 一致するネットワーク通信が観測された(--network が必要) request: { method: POST, path: /login, status: 200, count: 1 }
event アプリが送った分析 / テレメトリイベント。エンドポイント+JSON ボディのフィールドを count とともに検証(--network が必要) event: { url: "https://t.example.com/track", body: { name: purchase_completed }, count: { equals: 1 } }
requestSequence 複数のマッチャがこの順序で観測されたか検証(--network が必要) requestSequence: [ { urlMatches: "/auth/refresh" }, { urlMatches: "/api/account" } ]
responseSchema 捕捉したレスポンスボディが JSON Schema に適合するか検証(--network が必要) responseSchema: { request: { urlMatches: "/api/items" }, schema: items.json }
visual 画面が baseline 画像に一致する(ビジュアルリグレッション) visual: { baseline: home.png, threshold: 0.02 }
clipboard デバイスのクリップボードが一致する(iOS は simctl pbpaste、Android は BajutsuAndroid の受信側で読み戻す) clipboard: { equals: "COUPON123" } / clipboard: { matches: "\\d{6}" }
attribute 要素の HTML 属性が一致する、または属性がない(web のみ) attribute: { sel: { id: docs.link }, name: href, equals: /docs } / attribute: { sel: { id: panel }, name: aria-busy, absent: true }
  • exists はセレクタを インラインで書きます({ id: ... } を直書き)。negate は任意です。
  • value / label は sel: と、equals / contains / matches の いずれか 1 つを指定します。
  • count は sel: と、equals / atLeast / atMost の いずれか 1 つを指定します。
  • enabled / disabled / selected はセレクタを直書きします。
  • request は 観測されたネットワーク通信に一致するか検証します(下記)。--network 実行フラグが必要です。
  • event は アプリが送った分析 / テレメトリイベントに一致するか検証します(下記)。--network 実行フラグが必要です。
  • requestSequence は複数の request マッチャが 順序どおりに観測されたかを検証します(下記)。--network 実行フラグが必要です。
  • responseSchema は捕捉した レスポンスボディが JSON Schema に適合するかを検証します(下記)。--network 実行フラグが必要です。
  • visual はスクリーンショットを baseline 画像とピクセル比較します(下記)。
  • clipboard はデバイスのクリップボードを読み戻し、equals / matches(正規表現)の いずれか 1 つを検証します。読み戻しには、iOS では simctl pbpaste を、Android ではアプリに組み込んだ BajutsuAndroid の受信側を使います(BE-0233)。setClipboard の読み戻し側で、「コピー」操作の検証に使います。デバイスごとの制御チャネルが必要なため、fake ドライバや並列実行では利用できず、その場合はクリーンに失敗します(BE-0052)。
  • attribute は sel: と name: に加えて、equals / contains / matches / absent: true の いずれか 1 つを取ります。詳細は後述と BE-0466 を参照してください。属性は web(Playwright)バックエンドから必要なときに読み取ります。ほかのバックエンドでは、デバイスの確保前に失敗します。

ロケール注意: label/value の文字列比較や、可視テキストを見るアサーションは翻訳で壊れます。これらはターゲットの固定 runsOn.ios.locale を前提に書き、セレクタ自体は id で書いてください。

request(ネットワークアサーション)

request は、run のネットワーク collector が 一致する HTTP 通信を観測したことを表明します(--network 実行フラグと、アプリ内の BajutsuKit が必要)。同じマッチャを until: { request: ... } の wait と mocks(下記)で共有します。マッチフィールドは最低 1 つ必須で、列挙したフィールドは AND で評価します。

フィールド 型 説明
method str HTTP メソッド(GET, POST, …)
url str 完全一致の URL(エンドポイント)
urlMatches str URL 全体への正規表現 / 部分一致
path str 完全一致のパス(クエリは無視)
pathMatches str パスへの正規表現
query map URL のクエリパラメータに対するキーと値の辞書(下記「キーと値の辞書」を参照)
body map JSON のリクエストボディに対するキーと値の辞書(下記「キーと値の辞書」を参照)
status int レスポンスのステータスコード
bodyMatches str 生のリクエストボディへの正規表現 / 部分一致
count int 一致した通信数。アサーションでは 厳密、wait では 下限
- assert:
    - request: { method: POST, path: /login, status: 200, count: 1 }
    - request: { urlMatches: "/search", bodyMatches: "apple" }   # match on the request body

count はマッチフィールド ではありません。method / url / urlMatches / path / pathMatches / query / body / status / bodyMatches の少なくとも 1 つが必要です。 (demos/showcase/scenarios/network_mock.yaml 実物)

キーと値の辞書(query と body)

URL やボディに対する正規表現は、意味の変わらない変更でも壊れます。urlMatches: "page=2&sort=asc" は、 アプリがパラメータの順序を入れ替えると失敗します。bodyMatches: '"id":\s*42' は、JSON が整形されると 失敗します。query と body の辞書は、正規表現の代わりにキーを名指しします (BE-0463)。 そのため、順序や整形の違いに左右されません。

expect:
  - request:
      method: POST
      path: /api/orders
      query: { page: "2", sort: { $matches: "^(asc|desc)$" } }
      body:
        user: { id: "42", email: { $exists: true } }
        items: [ { sku: A-1, qty: "1" } ]
        coupon: { $exists: false }
  • query:URL のクエリ文字列を検査します。キーと値は URL デコードしてから比較します(+ は空白として 読みます)。値が空または欠けたキー(?debug、?page=)は、値 "" を持つものとして扱います。同じキーが 繰り返し現れる場合は、どれか 1 つが値を満たせば一致します。
  • body:JSON として解析したリクエストボディを検査し、入れ子の map とリストまで再帰的にたどります。 JSON でない、オブジェクトでない、あるいは存在しないボディは、どの body 条件にも一致しません。

各値は、次の 4 つの形のどれかで書きます。

形 例 一致する条件
スカラー id: "42" JSON 値のテキスト形式が文字列と等しいこと("42" は数値 42 に一致します。真偽値と null は true / false / null として読みます)
演算子 map id: { $matches: "^4" } すべての演算子が成り立つこと。$matches はテキスト形式を正規表現で検索し、$exists: true / false はキーの有無を要求します
通常の map user: { id: "42" } JSON 値がオブジェクトで、列挙したキーがそれぞれ成り立つこと。列挙していないキーは無視します
リスト tags: [a, b] JSON 値が同じ長さの配列で、各要素が同じ位置のマッチャを満たすこと

クエリ文字列には入れ子がないため、query に書けるのはスカラーと演算子 map だけです。

辞書が文法に反するとき、シナリオの読み込みは失敗します。

  • 引用符のないスカラー:qty: 1、ok: true、note: null のような値は拒否します。書き間違えた値が 黙って一致しなくなるのを防ぐためです。qty: "1" のように引用符で囲んでください。
  • 空の辞書:query: {} や body: {} は、すべての通信に一致してしまいます。
  • 混在した演算子 map と未知の演算子:$ で始まるキーと通常のキーを混ぜた map は拒否します。 $matches と $exists 以外の演算子も拒否します。
  • 最上位の演算子:query と body の最上位のキーは、常にフィールド名を表します。

名前自体が $ で始まるフィールドは、$ を重ねて書きます。たとえば $$ref はフィールド $ref を検査します。

アサーションが成り立たず、エンドポイントとメソッドの条件を満たす通信がちょうど 1 件だったとします。この 場合、メッセージは成り立たなかった最初のキーを示します(例:query.page: expected "2", got "3")。候補が 0 件または複数件のとき、あるいは count を指定したときは、従来どおり件数のメッセージを出します。

query と body は、このマッチャを使うすべての場所で使えます。対象は request、event、 requestSequence、responseSchema.request、until: { request } です。値には ${vars.*} / ${secrets.*} トークンを書けます。mocks では、どちらのフィールドもいまのところ拒否します。アプリ内の マッチャがこれらのフィールドを無視し、シナリオの記述より多くの通信をスタブしてしまうためです。

event(イベントアサーション)

event は、画面には現れない振る舞い、すなわちアプリが送った分析 / テレメトリイベントを表明します (BE-0048)。 request が読むのと同じ観測済み通信に対する純粋な検査なので(--network 実行フラグが必要)、判定は機械のみで LLM は介在しません。 まず、イベントのエンドポイント(request と同じ method / url / urlMatches / path / pathMatches マッチャ)でタイムラインを絞ります。 続けて query / body の辞書で絞り、残った通信数を count 演算子と突き合わせます。

フィールド 型 説明
method / url / urlMatches / path / pathMatches str エンドポイントのマッチャ(AND)。意味は request と同じ
query map URL のクエリパラメータに対するキーと値の辞書。文法は request と同じ(上記「キーと値の辞書」を参照)
body map JSON リクエストボディに対するキーと値の辞書。文法は request と同じ。平坦な形は最上位のフィールドをテキストとして比較します(amount: "300" は JSON の数値 300 に一致)。入れ子の map、リスト、$matches、$exists も使えます
count object 期待する多重度。equals / atLeast / atMost の いずれか 1 つ。省略時は 1 件以上
expect:
  # 購入イベントが正しい金額でちょうど 1 回発火したこと
  - event:
      url: "https://t.example.com/track"
      body: { name: purchase_completed, amount: "300" }
      count: { equals: 1 }

エンドポイントのフィールド、query、body の少なくとも 1 つが必須で、イベントは必ず何かを特定します。 JSON でない、オブジェクトでない、あるいは存在しないリクエストボディは body 条件に一致しません(推測せず 失敗します)。辞書の値は DSL の他の箇所と同じく ${vars.*} / ${secrets.*} トークンを使えます。単独の $ は演算子を表すため、$ で始まる最上位の body キーは $$ と書きます。

requestSequence(順序付きリクエスト)

requestSequence は、複数のリクエストが 指定した順序で起きたことを表明します。たとえば保護された 呼び出しの前にトークンリフレッシュが起きたこと、といった検証です (BE-0048)。 観測済みタイムラインに対する純粋な検査なので(--network 実行フラグが必要)、判定は機械のみです。空でない request マッチャのリスト(同じフィールド)を取り、順序を保った部分列 として照合します。各マッチャは、直前のマッチより厳密に後ろの位置にある別々の通信に一致しなければなりません。 間に無関係な通信が挟まってもよいのでノイズに強く、同じマッチャを2回並べれば順序を保った2件の出現を要求します。

expect:
  - requestSequence:
      - { method: POST, urlMatches: ".*/auth/refresh" }
      - { method: GET,  urlMatches: ".*/api/account" }

各マッチャは request と同じフィールド(method / url / urlMatches / path / pathMatches / status / bodyMatches)を使います。マッチャ自身の count はここでは無視されます。シーケンスの役割は 順序だからです。純粋な多重度の検査には request の count を使ってください。

responseSchema(レスポンスの JSON Schema)

responseSchema は、捕捉した レスポンスボディが JSON Schema に適合することを表明します。画面では 表現できない契約の検査です(BE-0048)。 観測済みタイムラインと保存済みのスキーマファイルに対する純粋で決定的な検査なので(--network 実行フラグが 必要)、判定は機械のみです。request(同じマッチャフィールド)で検証対象の交信を選び、schema はターゲットの スキーマディレクトリ(--schemas フラグ、config の targets.<name>.paths.schemas、またはシナリオ脇の schemas/)内で解決するファイルパスです。検証には jsonschema ライブラリを使うので、schema extra を インストールしてください(pip install bajutsu[schema])。

expect:
  - responseSchema:
      request: { method: GET, urlMatches: ".*/api/items" }
      schema: items.json        # スキーマディレクトリ内で解決

検証するのは最初に一致した交信のレスポンスです。一致する交信がない、スキーマファイルが無い、 レスポンスにボディが無い、JSON でない、あるいは適合しない場合は(推測せず)失敗します。スキーマ ディレクトリの解決順は visual の --baselines と同じです。

visual(ビジュアルリグレッション)

- assert:
    - visual: { baseline: "home.png", threshold: 0.02, exclude: [{ x: 0, y: 0, w: 390, h: 47 }] }
    - visual: { baseline: "detail.png", compare: pixelmatch, colorTolerance: 0.1, antialiasing: true }
    - visual: { baseline: "summary-card.png", element: { id: "summary-card" } }  # 1 要素だけ比較
    - visual: { baseline: "home.png", exclude: [{ selector: { label: "last updated" } }] }  # 要素でマスク

visual はスクリーンショットを取得し、baseline(run の baselines ディレクトリ内の PNG。--baselines、またはシナリオ脇の baselines/)と比較します。

比較エンジンは compare で選択できます(BE-0165)。

エンジン 説明 既定
exact ピクセル完全一致。いずれかのチャネルが異なればそのピクセルは「差分」として計上されます。 はい(後方互換)
pixelmatch 知覚的 YIQ 色差 + アンチエイリアシング検出。サブピクセルレンダリングノイズや 1 ピクセルのエッジシフトを許容します。 いいえ

compare を省略すると、ターゲットの evidence.visualCompare 設定(defaults.evidence または targets.<name>.evidence で指定)にフォールバックし、さらに未設定なら exact になります。

threshold は許容する差分ピクセルの割合(既定 0.0 = 完全一致)で、すべてのエンジン共通です。colorTolerance(0–1、既定 0.1)は pixelmatch のピクセル単位の知覚的色差許容値、antialiasing(既定 true)はアンチエイリアスされたピクセルを差分から除外します。exclude は比較前にマスクする領域のリストで、ステータスバーや時計などに使います。各要素は、スクリーンショットのピクセル座標で表す矩形({ x, y, w, h })か、マスク対象の要素を指す { selector: <Selector> }(BE-0171)のどちらかです。後者は評価時に要素のフレームへ解決されます。

baseline は approve コマンド(cli)か serve UI で作成・更新します。baseline が無いとアサーションは失敗します。overrideStatusBar と併用すると時計やバッテリーを固定できます。

差分は report.html に表示されます。pixelmatch では、除外されなかった(非 AA)ピクセルのみが差分画像に表示されます。

approve とレポートの差分ストリップが読むのは、シナリオ末尾の expect の結果だけです。ステップ自身の assert に含めた visual エントリは、最初の baseline を手動で用意してください(上記のassertを参照)。

要素スコープ比較(BE-0171)。 visual は既定で画面全体を比較するため、無関係な変化(バナー、行が増えたリストなど)があるたびにアサーションが失敗し、baseline が揺れます。element: <Selector> を指定すると、その要素だけを比較します。スクリーンショットは要素のフレームにクロップされ、baseline はそのクロップ画像になるので、フレームの外側の変化は無視されます。セレクタは通常の一意解決規則で解決し、曖昧なセレクタは最初の一致をクロップせず即座に失敗します。何にも一致しないセレクタも失敗します。approve は要素スコープの baseline も画面全体の baseline と同じ手順で昇格します(baseline は単に小さい画像になるだけです)。

セレクタによるマスク(BE-0171)。 exclude のピクセル矩形は、レイアウトが変わったりデバイスの解像度が変わったりした瞬間にずれます。代わりに要素を指定すると({ selector: { label: "last updated" } })、そうした変化に強くなります。要素をフレームへ解決し、矩形と同じ方法でマスクするからです。何にも一致しないマスクセレクタは何もしません(画面上に隠すものが無いため)。曖昧なセレクタは、決定論の原則どおり失敗します。セレクタと矩形は一つの exclude リストに混在でき、どちらも要素スコープ比較と併用できます(クロップした要素の内側のマスクは、クロップの座標系へ変換されます)。

attribute(要素の HTML 属性)

- assert:
    - attribute: { sel: { id: docs.link }, name: href, equals: /docs }
    - attribute: { sel: { id: hero.image }, name: alt, contains: Bajutsu }
    - attribute: { sel: { id: panel }, name: data-state, matches: "^(ready|idle)$" }
    - attribute: { sel: { id: panel }, name: aria-busy, absent: true }

attribute は、web(Playwright)バックエンドで 1 つの要素の HTML 属性を 1 つ検証します(BE-0466)。リンクの href、画像の alt、状態を表す data-* や aria-* 属性のように、要素ツリーに含まれない値を確かめるために使います。

  • sel は value と同じ方法で解決します。一致する要素がなければ失敗し、2 つ以上あれば曖昧として失敗します。対象は web のクエリが列挙する要素に限られます。data-testid、role、インタラクティブなタグのいずれかを持つ要素か、label で指定するテキストの要素です。素の <img> はテキストを持たないので、検証するには data-testid が必要です。内容がまったく同じ要素が 2 つあり、属性の値が食い違う場合も、ほかに見分ける手がかりがないので曖昧として失敗します。
  • name は正しい HTML 属性名でなければなりません。空文字列や、空白、引用符、>、/、=、制御文字を含む名前は受け付けません。Bajutsu は属性名を小文字に変換しません。書いたとおりの名前が DOM の getAttribute に渡ります。そのため、HTML 要素では大文字と小文字を区別せずに一致します。SVG と MathML の要素では、大文字と小文字まで完全に一致する必要があります。
  • 演算子は 4 つのうち 1 つだけを指定します。equals、contains、matches(正規表現)は value や label と同じ規則に従います。absent: true は、要素がその名前の属性を持たないときに成功します。absent: false はシナリオの読み込み時に拒否します。
  • 属性がないことと値が空であることは区別します。 値が空の属性は "" として読むので、equals: "" は成功し、absent: true は失敗します。属性がない場合、equals、contains、matches は失敗し、理由で属性の欠如を示します(expected equals='x' but attribute 'href' is absent)。値が一致しない場合は、実際の値を理由に含めます(expected equals='/docs' but actual='/about')。この理由も、ほかの理由と同じくアーティファクトの秘匿化境界を通ります。
  • 期待する文字列の ${...} トークンは、ほかのアサーションのフィールドと同じく展開します。

attribute は、ステップの assert、expect、if の条件、interrupts の条件で使えます。wait の条件には使えません。runner は、ブロックを評価するクエリの直後に、そのつど属性を読み取ります。そのため、ステップの assert では条件待機の各ティックで読み取りを繰り返します。繰り返しは、属性が一致するか、レーンの待機下限(BAJUTSU_MIN_WAIT_TIMEOUT)が尽きるまで続きます。要素のスナップショット、golden、クロールの出力、レポートにはフィールドが増えません。レポートに載る属性は、アサーションが名前を挙げたものだけです。

このアサーションには elementAttribute capability が必要です。この capability を宣言するのは web バックエンドだけです。ほかのバックエンドでシナリオのどこかに attribute があれば、capability preflight がデバイスを確保する前に拒否します。web: ブロックの iOS WebView コンテキストも拒否の対象です。また、web 以外のターゲットの hooks.interrupts に attribute があれば、設定の検証が設定の読み込み時に拒否します。attribute が読むのは属性であって、DOM のプロパティではありません。フォーム部品の現在の値は、引き続き value アサーションで検証します。

ネットワークモック(決定的スタブ)

mocks はテストをライブサーバから独立させます。送信リクエストが一致すると、BajutsuKit はネットワークへ行かずに定型レスポンスを返します。各モックは { match, respond } です。

  • match はリクエストマッチャの リクエスト側フィールドを再利用します(method / url / urlMatches / path / pathMatches / bodyMatches)。status / count はモックの match には 適用されません。
  • respond は定型の返答です。status(既定 200)、headers(既定 {})、body(文字列)、delayMs(人工的な遅延)を指定します。respond を省くと空の 200 を返します。
- name: GET answered by a mock stub
  mocks:
    - match: { method: GET, urlMatches: "example.com" }
      respond:
        status: 418                       # real example.com returns 200; 418 proves the stub served it
        headers: { Content-Type: text/plain }
        body: "stubbed by bajutsu"
  steps:
    - tap:  { id: net.fetch }
    - wait: { until: { request: { method: GET, urlMatches: "example.com", status: 418 } }, timeout: 6 }
  expect:
    - request: { method: GET, urlMatches: "example.com", status: 418 }

モックは BAJUTSU_MOCKS env で BajutsuKit に渡されます(dump_mocks, scenario/serialize.py)。形式的な形は dsl-grammar にあります。

シナリオの途中でモックを変える(setMocks)

シナリオレベルの mocks は、アプリの起動時に固定されます。最初は成功し、次の更新では失敗するといったように、途中で別のレスポンスが必要になるシナリオでは setMocks ステップを使います。setMocks はアプリのスタブテーブル全体を、自分が持つリストで置き換えます。リストの各要素は mocks と同じ { match, respond } の形です。新しいテーブルは古いテーブルに追加されるのではなく、置き換わります。setMocks: [] はすべてのスタブを外します。

- name: profile refresh fails after a first success
  mocks:
    - match: { path: /api/profile }
      respond: { status: 200, body: '{"name":"A"}' }
  steps:
    - tap: { id: profile.refresh }
    - wait: { until: { request: { path: /api/profile, status: 200 } }, timeout: 6 }
    - setMocks:
        - match: { path: /api/profile }
          respond: { status: 500 }
    - tap: { id: profile.refresh }
    - wait: { until: { request: { path: /api/profile, status: 500 } }, timeout: 6 }

新しいテーブルは、アプリ内制御チャネル(BE-0365)を通って実行中のアプリへ届きます。setMocks ステップは、アプリがテーブルの適用を確認するまで待ちます。そのため、setMocks の後のステップが古いスタブのまま実行されることはありません。アプリがテーブルを拒否した場合や、5 秒以内に応答しない場合は、setMocks ステップが理由付きで失敗します。relaunch ステップでアプリを再起動すると、アプリは起動時の mocks を読み直します。

setMocks を使うには、次の 3 つの条件を満たす必要があります。run は最初の 2 つを、デバイスを操作する前に確認します。

  • xcuitest バックエンドで、ネットワーク収集が有効であること(Web、Android、fake はチャネルを運べません)。また、ステップがシナリオのプライマリアプリを対象にしていること(web: や app: ブロックの中に置いたり、別のターゲットを指定したりはできません)。
  • シナリオとターゲットのどちらでも、BAJUTSU_CONTROL_CHANNEL を "1" 以外に固定していないこと(run が自分で "1" を設定します)。
  • アプリの BajutsuKit が -DBAJUTSU_ENABLE_CONTROL_CHANNEL 付きでコンパイルされていること。このフラグがないとアプリは応答せず、ステップはタイムアウトで失敗します。

再利用とデータ駆動とタグ

コア文法の周りには、小さなテンプレートとマクロの層があります。これはロード時、決定的 run の 前に実行されるため、ランナーは常に展開済みのプレーンなシナリオだけを見ます。展開順、${ns.key} 補間、深さ制限といった規範的な規則は dsl-grammar にあります。ここではオーサリングの視点から説明します。

コンポーネント(use → 再利用ステップ)

コンポーネントは、params のリストと、それを ${params.<name>} で参照する steps のリストからなります。use ステップが with で params を束縛して呼び出します。use は コンパイル時マクロであり、expand_components(scenario/expand.py)が run の前に、コンポーネントの置換済みステップへ置き換えます。展開は再帰的で、コンポーネントが別のコンポーネントを use でき、深さは 25 までです。params 不足、未知の params、未宣言を指す残留 ${params.*}、循環参照ではエラーになります。use は run に残らないため、決定性には影響しません。

展開の対象は、シナリオ自身の steps と、interrupts の各エントリの回復用 steps です。その中にある if / else の分岐、forEach の本体、web: / app: ブロックにも展開は及ぶので、そこに書いた use もロード時に展開されます。

run が一度も通らない分岐にある壊れた use も、ロードを失敗させます。

use ステップが取れる修飾子は target だけです。capture / extract / name / from を併記した use ステップは、ローダーが拒否します。展開はステップ全体を置き換えるので、拒否しなければこれらのフィールドは警告なく失われます。target については、展開が捨てずに引き継ぎます。その規則は後述の複数ターゲットの節で説明します。

コンポーネントは専用のファイルに置けます。スイート全体から再利用できます。

# login.component.yaml: コンポーネントファイル(単一マッピング。別ファイルとして読み込む)
params: [user, pass]
steps:
  - type: { text: "${params.user}", into: { id: auth.user } }
  - type: { text: "${params.pass}", into: { id: auth.pass } }
  - tap:  { id: auth.submit }
# シナリオ側: 上の 3 ステップに params を置換して展開される
steps:
  - use: { component: login.component.yaml, with: { user: alice, pass: hunter2 } }
  - tap: { id: home.tab }

ファイルスコープのコンポーネント(components:)

1つのファイルの中だけで使い回すステップ列に、専用のファイルは要りません。シナリオファイルの先頭の components: に宣言し、下のシナリオから名前で呼び出せます(BE-0422)。コンポーネントは、それを使うシナリオの隣に並びます。1つのファイルでしか使わない名前のために、スイートのディレクトリ一覧が増えることもありません。

# シナリオファイル1つだけ。別のコンポーネントファイルは要らない
components:
  search:
    params: [query]
    steps:
      - type: { text: "${params.query}", into: { id: home.search }, submit: true }

scenarios:
  - name: search returns dogs
    steps:
      - use: { component: search, with: { query: dog } }
    expect:
      - label: { sel: { id: home.status }, equals: "1 result" }
  - name: search returns cats
    steps:
      - use: { component: search, with: { query: cat } }
    expect:
      - label: { sel: { id: home.status }, equals: "2 results" }

components: を持てるのは、シナリオファイルのうち {description, scenarios} のマッピング形式だけです。シナリオの素のリストとして書いたファイルは、先にマッピング形式へ書き換えます。

どちらとして解決するかは ref 自身の形が決めます。 component: フィールド1つで両方をまかない、既存のシナリオはそのまま動きます。

ref 解決先
/ を含む、または .yaml / .yml で終わる コンポーネントファイル。シナリオファイルからの相対で解決し、スイートルートの内側に閉じ込める
それ以外(素の名前) そのファイル自身の components: のエントリ

components: にない素の名前は、ref を名指ししたエラーになります。代わりにファイルを開こうとするフォールバックは起きません。

components: の有効範囲は1ファイルです。ファイルごとに読み、スイートディレクトリをまたいで統合しません。あるファイルで宣言した名前は、隣のファイルからは見えません。ファイルをまたぐ再利用はコンポーネントファイルの役目のままです。コンポーネントファイルへ入ると components: は完全に外れます。コンポーネントファイルは components: を持たないため、その中の素の use は常に未定義です。参照元のファイルが何を宣言していても変わりません。

一方、ファイルスコープのコンポーネント自身の steps は宣言元ファイルのスコープで展開されます。別のファイルスコープのコンポーネントを素の名前で use できますし、パスでファイルも use できます。

ターゲットの hooks もコンポーネントを呼び出せます(上記)。この use は config のロード時に、config ファイルのディレクトリを基準に、スイートのルートの内側で解決します。config は components: マップを持たないので、フックの use はコンポーネントファイルをパスで指定します。with の値はロード時に置換され、${secrets.*} と ${vars.*} はステップの実行時に解決します。フックでは、直接でもコンポーネント経由でも、group: と setMocks を使えません。

複数ターゲットシナリオでのコンポーネント

2つ以上のターゲットを宣言したシナリオでも、 コンポーネントは同じように呼び出せます(BE-0446)。 展開後の各ステップにはターゲットが必要で、次の2つのどちらかから受け取ります。

呼び出し側(use: ステップ) 展開後のステップが target を省略 展開後のステップが target を指定
target: X を指定 X が刻印されます X と等しければ受け入れ、異なればロード時に拒否します
target を省略 同じ位置に手書きしたステップと同じく解決します。primaryTarget があればそれに、なければロード時エラーになります 書かれたまま残し、宣言済みターゲットと照合します

1行目は、単一ターゲット向けのコンポーネントに向いています。たとえば、呼び出し元のデバイスを 問わないサインイン処理です。2行目は、ターゲット横断のコンポーネントに向いています。 コンポーネント自身が、各ステップをシナリオのターゲットへ振り分けます。

components:
  web-sign-in:
    params: [email]
    steps:
      - tap: { id: onboarding.start }
      - type: { text: "${params.email}", into: { id: auth.email } }
      - tap: { id: auth.submit }
  like-and-verify:
    steps:
      - target: showcase-swiftui
        tap: { id: horse.favorite }
      - target: web
        wait: { for: { id: favorites.updated }, timeout: 5 }

scenarios:
  - name: web でサインインし、アプリでいいねする
    targets: [showcase-swiftui, web]
    steps:
      # 呼び出し側がターゲットを決める。`web-sign-in` の全ステップが `web` で動く
      - use: { component: web-sign-in, with: { email: a@b.com } }
        target: web
      # コンポーネント自身が、両ターゲットへステップを振り分ける
      - use: { component: like-and-verify }

ターゲットが食い違うと、どちらかを優先させずにロードを失敗させます。コンポーネントの指定を上書きすると、 作者が想定していないデバイスへステップを送ることになります。コンポーネントを優先すると、 呼び出し側の指定が気付かれないまま破られます。エラーは、コンポーネントの連鎖とステップを名指しします。

use: web-sign-in > step 'submit': target 'showcase-swiftui' conflicts with the caller's target 'web'

呼び出し側のターゲットは、展開で生じるすべてのステップへ、深さを問わず届きます。if / else の分岐、 forEach の本体、入れ子の use 呼び出しにも降りていきます。web: / app: ブロックでは止まります。 ブロック自体はターゲットを受け取り、その内側のステップは引き続き target を省略します。 コンポーネントはターゲットを param で受け取ることもできます(target: ${params.device})。 param の置換は、どのターゲット検査よりも先に走るからです。 ターゲットグループの中の use ステップは、グループのターゲットを呼び出し側のターゲットとして受け取ります。

interrupts エントリの回復用 use も同じ表に従いますが、1点だけ異なります。展開後の回復ステップが target を省略した場合、そのステップは割り込みを検知したランナーの上に残り、primaryTarget には解決されません。

ステップのグループ化(group: → report.htmlで折りたたむ)

group ステップは、連続するステップに名前を付けます。expand_components は use ステップと同じ やり方で、group ステップを自分自身の steps へ置き換えます。コンパイル時マクロなので、run は これを見ません。

steps:
  - group:
      name: ログイン
      steps:
        - tap: { id: auth.open }
        - type: { text: "${vars.user}", into: { id: auth.user } }
        - tap: { id: auth.submit }
  - tap: { id: home.tab }

use: と違い、group: は params を取らず、別ファイルも名指ししません。1つのシナリオの steps: を整理するための、その場限りのラベルです。同じステップ列を複数の場所から呼びたいときは、 代わりに use: / components: を使ってください。

report.html は、グループのステップを1つの折りたたみ区画にまとめます。見出しはグループ名と ステップ数を示します。ステップがすべて成功しているグループはデフォルトで畳まれます。失敗した ステップを含むグループは、自動で展開されます。既存の「全展開」「全折りたたみ」操作は、グループも 一緒に開閉します。ネットワーク交信行や未実行のステップが割り込むと、1つの group: 呼び出しが report内で複数の折りたたみに分かれることがあります。それぞれの断片が、独立した見出しを持ちます。

group: は入れ子にできません。別の group: の steps: の中に書いた group: は、ロード時に 失敗します。if / forEach / web / app の入れ子の steps: の中に書いた場合も同様です。 コンポーネントが use 経由でそこへ持ち込んだ group: も、同じく失敗します。

targets を2つ以上宣言したシナリオでは、 group: ステップの target は use: ステップと同じ働きをします。展開はその値を、グループが生む すべてのステップへ刻印します。深さと食い違いの規則も同じです。 target を省略した group: ステップでは、各子ステップが手書きのステップと同じように解決します。

データ駆動シナリオ(data / dataFile)

data(インライン行)か dataFile(CSV パス。両者は 排他)を持つシナリオは、${row.<column>} を置換して 1 行 1 シナリオに展開されます(expand_data, scenario/expand.py)。派生シナリオは "<name> [row N: col=val, …]" に改名され、元の preconditions を保ちます。そのため各行ともアプリを fresh に再インストールし、テンプレートの subject.reinstall を継承します。

- name: search returns a result
  data:
    - { q: dog, expect: "1 result" }
    - { q: cat, expect: "2 results" }
  steps:
    - type: { text: "${row.q}", into: { id: search.field }, submit: true }
  expect:
    - label: { sel: { id: home.status }, equals: "${row.expect}" }

ちょうど 1 トークンだけの文字列("${row.qty}")は 生の値になります(数値は数値のまま)。大きな 文字列に 埋め込まれたトークンは、テキストとして差し込まれます("item-${row.id}")。

CSV の dataFile は、列名を与えるヘッダ行を持ち、以降の各行が 1 シナリオになります。

参照はスイートの中にとどまります。 use コンポーネントと dataFile のパスは、シナリオファイルを 起点に解決します。解決後のファイルは、読み込みを始めた scenarios ディレクトリ(スイートのルート)の中に とどまらなければなりません。ルートの外へ出る参照、すなわち絶対パス、ルートを抜ける ../ の連鎖、外を 指すシンボリックリンクは、明確なエラーで拒まれ、読み込まれることはありません。そのため、シナリオが ローダに自分の木の外のファイルを開かせることはできません(BE-0174)。 ルートの中にとどまる相対参照は、今までどおり動きます。たとえば同じ階層の components/shared.yaml や、 サブディレクトリにあるシナリオからルートより上に出ない ../shared.yaml です。

タグと選択

tags はシナリオにラベルを付けます。CLI の --tag / --exclude フラグで実行対象を絞ります。シナリオは、少なくとも 1 つの --tag を持ち(または --tag 未指定で)、かつ --exclude のタグを 1 つも持たない場合に実行対象として残ります。--exclude が --tag より優先されます(select_scenarios, scenario/select.py)。両フラグともカンマ区切りで複数指定できます。

- name: checkout smoke
  tags: [smoke, checkout]
  steps:
    - tap: { id: cart.checkout }
uv run bajutsu run --target showcase-swiftui --tag smoke --exclude wip   # run @smoke, skip anything @wip (across the app's scenarios dir)

シークレット(${secrets.X})

シークレットの環境変数名を config で宣言します(evidence: { secrets: [API_TOKEN, ...] })。宣言した各名 X は環境から解決され、アクション時に実行ステップへ ${secrets.X} として置換されます。シナリオファイルは トークンを保持し、実値は持ちません。さらにリテラル値は証跡で 自動マスクされるため、シークレットはコミットしてもレビューしても安全です。${params.*} / ${row.*}(ロード時の展開)と異なり、この名前空間は run ループが解決します。

# config が宣言: evidence: { secrets: [API_TOKEN] }
steps:
  - type: { text: "${secrets.API_TOKEN}", into: { id: auth.token } }   # real value typed; token kept in the report

ランタイム変数 (${vars.*})

ステップの extract 修飾子は、ステップ実行後に UI 要素のプロパティを vars.* に取り込みます。後続のステップやシナリオレベルの expect で、${vars.<name>} として参照できます。

steps:
  - tap: { id: counter.inc }
    extract:
      count: { sel: { id: counter.value } }          # vars.count ← element's value (default)
      heading: { sel: { id: header }, prop: label }   # vars.heading ← element's label
  - assert:
      - value: { sel: { id: other.field }, equals: "${vars.count}" }

各 extract エントリは、sel(セレクタ、resolve_unique で一意解決)と、省略可能な prop(value | label | identifier、既定 value)を指定します。セレクタが一意に解決できない場合や、プロパティが None の場合、ステップは失敗します。

条件分岐 (if)

ステップでアサーション DSL と同じ条件を評価し、分岐できます。

steps:
  - if:
      condition: { exists: { id: dialog.alert } }
      then:
        - tap: { id: dialog.dismiss }
      else:
        - tap: { id: home.start }

条件は現在の要素ツリーに対して評価されます(${...} 補間あり)。条件が成立すれば then のステップ群が、そうでなければ else のステップ群が実行されます(else 省略時は何もしません)。ネストしたステップは、外側のシナリオと同じ vars.* バインディングを共有します。capture / extract 修飾子は if ステップでは使えません。

要素のイテレーション (forEach)

セレクタに一致する全要素に対して、ステップを繰り返し実行できます。

steps:
  - forEach:
      sel: { idMatches: "item.*" }
      as: current
      steps:
        - tap: { id: "${vars.current}" }

要素リストはループ開始時に 1 回スナップショットされます。各要素の identifier が vars.<as> に格納され、ネストしたステップで参照できます。identifier のない要素はステップを失敗させます。0 件一致は no-op(成功)です。セレクタは ${...} 補間に対応しています。capture / extract 修飾子は forEach ステップでは使えません。

capture トークン文法

capture:(ステップ単体)と capturePolicy[].capture(ルール)で共通です。形は <kind>[.<modifier>] です。

  • 種別: screenshot / elements / actionLog / deviceLog / network / video / appTrace / rawTree
  • 修飾子: before / after / around / onError

検証は、種別と修飾子の集合に対して行われます(scenario/models/_base.py の _validate_capture)。種別ごとの取得タイミングと、どれが取得されるかは evidence にあります。

YAML の注意点

PyYAML(YAML 1.1)は on/off/yes/no を真偽値に解決します。capturePolicy のトリガーキー on: が True になるのを防ぐため、Bajutsu の YAML ローダ(common/_yaml.py)は true/false だけを真偽値として扱い、on/off/yes/no は文字列のまま読みます。

from(来歴)

from: は、ある構成要素がどの自然言語フレーズから記録されたかを残します(BE-0044)。任意の文字列で、シナリオ(元のゴール)、use を除く各ステップ、各 expect アサーション、各 capturePolicy ルールという 4 つのレベルに付きます。use ステップが取れる修飾子は target だけなので、from: は付きません。これにより、レビュアーは各部分がなぜ存在するのかを見て、record が意図を忠実に正規化できているかを判断できます。

- name: 設定を開いて再生成する
  from: "設定を開いて、再インデックスして、正規化設定が消えていることを確認して"   # 元のゴール
  steps:
    - tap: { id: settings.open }
      from: "設定を開く"
  expect:
    - exists: { label: "正規化設定が変更されています", negate: true }
      from: "正規化設定が消えていること"
  capturePolicy:
    - on: { action: tap, idMatches: "*.submit" }
      capture: [screenshot.after, network]
      from: "送信を押すたびにスクショとネットワークログを残して"
  • 書き込むのは record(Tier 1、AI)だけです。 ゴールを構造化シナリオへ正規化する際に from: を埋めます。手書きのシナリオは単に省略でき、書き出した YAML も汚れません(未設定の from: は間引かれます)。
  • run(Tier 2)は一切読みません。 来歴はオーサリング用のメタデータで、オーケストレータは参照しないので、ゲートに AI を加えず、pass/fail にも影響しません。
  • グルーピングは創発的です。 1 つの発話が複数ステップを生むとき、それらは同じ from: 文字列を持ちます。範囲(span)構文はありません。lint は来歴カバレッジ(from: を持つステップ数)を advisory として報告しますが、run を落とすことはありません。
  • trace とレポートに表示します。 bajutsu trace は各ステップのフレーズを ← "<フレーズ>" としてインライン表示し、report.html はステップの下に表示します。どちらも同じフレーズの連続を 1 つのラベルにまとめ、タイムラインを「自然言語 ↔ 操作」の対応図にします。
  • フレーズは、著者が書いた言語のまま逐語的に保ちます(翻訳しません)。

ラウンドトリップ(読込 ⇄ 書出)

  • load_scenarios(text) -> list[Scenario]: YAML 文字列 → 検証済みモデル。
  • dump_scenarios(scenarios) -> str: モデル → YAML。著者が設定しなかったフィールドだけを落とします。

record の出力はこの dump_scenarios を通ります。生成された YAML は load_scenarios でそのまま読み戻せます。