コンテンツにスキップ

English · 日本語

実行ループ(Orchestrator)と実行パイプライン

Tier 2 の決定的ランナーです。各ステップを act → (wait) → verify で処理し、合否は機械アサーション のみで決めます。AI は関与しません。最初の失敗で停止します。

実装:

  • bajutsu/common/orchestrator/ はループ本体です。package のモジュールは loop、waits、 substitution、evidence_rules、actions、control_channel です。
  • bajutsu/common/runner/ は実機の起動とレポートの連結を担います。package のモジュールは pipeline、pool、launch です。

関連: scenarios · selectors · evidence · reporting


run_scenario(1 シナリオの実行)

def run_scenario(driver, scenario, clock=None, sink=None, alert_guard=None, ...) -> RunResult
  • driver: base.Driver(実ドライバ or FakeDriver)。ループはこれにしか依存しません。
  • clock: 時刻 / sleep の注入(テストで待機を決定化)。既定 RealClock(time.monotonic / time.sleep)。
  • sink: 証跡の出力先(既定 NullSink は何も書かない)。詳細は evidence。
  • alert_guard: ステップ失敗時に「ブロッカー(システムアラート等)を片付けたら、その片付けたイベントを返す」ハンドラです。イベントを返した場合、そのステップを 1 回だけ再試行します(recording の alert guard)。wait ステップ(for/settled/screenChanged)では、同じハンドラが wait の途中でも待ち構えています(BE-0269)。すでにポーリング済みの画面のツリーが崩壊して見えた時点で発火し、デバウンスとクールダウンを挟んで、1 回の wait につき最大 2 回までです。末尾の再試行とは独立に、wait 自体のタイムアウトを待たず回復できます。
  • target_runtimes: シナリオが宣言したターゲットごとに 1 つずつの束で、名前をキーにします。各束は、そのターゲット自身のライブドライバと、そのリースに紐づく残りすべてを持ちます。ターゲットを宣言しないシナリオにはありません。その場合は上の平坦な引数をそのまま読みます。

ステップを自分のターゲットへ振り分ける(複数ターゲットシナリオ)

2 つ以上のターゲットを宣言するシナリオでも、 ステップループは 1 本です。ターゲットごとには増えません。run_scenario は宣言済みのターゲットごとに ステップランナーを 1 つ作ります。どれも共有された 1 つのループ状態の上で動きます。各ステップは、 自分の target が名指しするランナーへ渡ります。

ターゲットごとの束が持つものは次のとおりです。

フィールド 紐づく先
driver そのターゲットのライブドライバ
sink そのターゲットの証跡の出力先
network / transitions / channel そのターゲット自身のコレクタ
webview_bridge そのターゲットの WebView ブリッジ。web: ブロックが正しいアプリを開きます
control / relaunch そのターゲットのデバイス
mailbox / locale / capture / interrupts そのターゲット自身の config(services.mailbox、runsOn.ios.locale、evidence.capture、hooks.interrupts)
ctx そのターゲットの paths.baselines / paths.schemas / paths.goldens ディレクトリ

ループ状態を共有することから、3 つの帰結が出ます。

  • 採番が 1 つ。 どのターゲットが走らせたかによらず、各ステップは次の番号を取ります。2 つのターゲットの証跡ディレクトリが衝突しません。
  • ${vars.*} の辞書が 1 つ。 live_bindings はどのドライバのものでもありません。あるターゲットの extract が捕まえた値は、別のターゲットに対するアサーションから読めます。
  • 判定が 1 つ。 2 つめのターゲットでの取りこぼしは、1 つめでの取りこぼしと同じようにシナリオを終わらせます。

target を名指ししないステップは、すでにアクティブなドライバをそのまま使います。この規則が効くのは web: ブロックの内側です。その入れ子のステップは、ブロック自身の WebContextDriver に対して走り続ける 必要があります。取りこぼすと、その下のアプリの画面に届いてしまいます。

末尾の expect ブロックは、各エントリを名指しされたターゲットごとにまとめます。参照されたターゲット ごとに 1 回、そのターゲットのドライバとネットワークソースに対してポーリングします。結果はシナリオの 宣言順に戻して束ねます。読み手には、書いたとおりのブロックが見えます。

ステップループを挟む 2 つのライフサイクルフェーズ

シナリオの setup / cleanup(scenarios)は、ステップループの前後にもう 2 つのフェーズを足します。どちらも同じステップランナーが動かすので、フックのステップは他のステップとまったく同じことができ、run の vars.* バインディングを共有します。

  1. setup が最初に走ります。 ここで失敗すると failure = "setup: …" を立て、steps と expect をまったく実行しません。setup はシナリオ内部のステップではなく、シナリオの前提条件だからです。
  2. steps と expect はそのまま走り、判定はこれまでどおり計算されます。
  3. 判定が出てから cleanup が走ります。 成功した経路、失敗した経路、キャンセルされた経路を含め、steps を抜けるすべての経路で到達します。on が always かその判定に一致するルールが、宣言順に走ります。run が成功していたなら、ルール自身の失敗がその run の failure になります。そうでなければ、ルール自身の失敗は既存の failure の後ろに追記されます。

キャンセルされた run では、キャンセル用のソースで cleanup フェーズを縛れません。ソースはラッチされた threading.Event.is_set です。フェーズ内での最初の読み取りがふたたび RunCancelled を投げ、後片付けのステップが 1 つも走らなくなります。

代わりにフェーズは専用の期限のもとで走ります。期限は grace_seconds() の 1 割で、これを過ぎると残りのルールを打ち切ります。後片付けに限られた実行機会を与えつつ、シャットダウンの後始末が serve の無条件 kill までの猶予時間を超えないようにするためです。

各フェーズはステップを 0 から数え直し、それぞれ専用の RunResult のリストに記録します。そのためレポートは、シナリオの連番のステップとは別のブロックとして setup と cleanup を表示します。RunResult.after_verdict には、cleanup フェーズがルールを振り分けた判定を記録します。BE-0452 より前に保存した run はここに error を持ちますが、レポートのローダーは error を failure として読みます。そのため、以前の run も cleanup のブロックを表示できます。

1 ステップの流れ

各ステップ i について(orchestrator/loop.py 内):

  1. kind = _action_of(step):どのアクションか判定します。
  2. step_id = step.name or f"step{i}":証跡の出力単位です。
  3. (capturePolicy に screenChanged トリガーがあれば)操作前の query() を控えます。
  4. 区間証跡を開始します(video / deviceLog のうち、操作前から始める必要があるもの)。_pre_intervals は「ステップ自身から判定可能なトリガー」だけを拾います(screenChanged/error は遅すぎるため対象外)。
  5. _run_step_body で act(or wait / assert)を実行し、(ok, reason, assertion_results) を得ます。
  6. 失敗かつ alert_guard がブロッカーを片付けた場合は 1 回再試行します。
  7. 区間証跡を停止します(ステップが落ち着いてから)。アーティファクトを記録します。
  8. 瞬時証跡(screenshot / elements)を取得します(_collect_captures の発火結果)。
  9. StepOutcome を積みます。失敗なら failure を設定して break します。

_run_step_body(act / wait / assert の分岐)

  • wait → _wait(条件待機、下記)。
  • assert_ → assertions.evaluate(driver.query(), ...) を評価し AND を取ります。
  • それ以外(tap/longPress/type/swipe/relaunch)→ _do_action。
  • SelectorError / NotImplementedError を捕捉して (False, 理由, []) に変換します(例外を上に投げません)。

_do_action(操作の実体)

アクション 実体
tap driver.tap(sel)
longPress driver.long_press(sel, duration)
type into があれば先に driver.tap(into) → driver.type_text(text)
swipe {from,to} ならそのまま driver.swipe。{on,direction} なら対象を resolve_unique → frame 中心から方向へ画面に対する割合分(_SWIPE_FRACTION、既定 0.125。amount で上書き)。固定量ではなく割合にすることで、frame の単位が異なる backend 間(iOS はポイント、Android はピクセル)でもスクロール到達量が揃います
relaunch runner が注入する relauncher でアプリを terminate + 再起動します(launch env/args 再適用+上書き)。ready まで待ちます

待機(条件待機)

_wait(driver, w, clock) -> (ok, reason) に固定 sleep はありません。query() を _POLL = 0.05s 間隔でポーリングし、条件成立か timeout 到達まで繰り返します。

固定の待機は別の sleep ステップだけが担います。_do_sleep が clock.sleep を 0.25 秒ずつ区切って呼ぶので、キャンセルされた run は 1 区切り以内に抜けます。sleep ステップはツリーを読まず、決定性の監査がすべての sleep を列挙します(scenarios)。

形 成立条件 タイムアウト時
for: <sel> 一致要素が現れる 失敗
until: { gone: <sel> } 一致要素が消える 失敗
until: screenChanged query() が初期値から変化 失敗
until: settled iOS でアプリが画面遷移イベントを報告している場合(BE-0310):短い静止の窓のあいだ、それ以上の遷移が報告されない。それ以外:画面が安定(連続 2 回 query() 不変、かつ id を持つ要素がある) 続行(失敗にしない)

settled は「遷移 / アニメーションが落ち着くのを待つ」安定化ヒントであり、正しさのアサーションではありません。空 / 崩壊したツリー(描画途中やシステムアラートで覆われた状態)は、ツリー差分の経路では settled と見なしません。タイムアウトしても現在画面で先に進みます。

画面遷移シグナル(BE-0310)は「最後の遷移が終わり、新しい遷移が始まっていない」という肯定的な判定であり、読み取り専用でオプトインです(アプリが BajutsuKit の observer を組み込んでいる場合)。このシグナルを報告しないターゲットでは、ツリー差分の挙動をそのまま保ちます。

証跡ルールの発火

capturePolicy の各ルールがこのステップで発火するかを判定します(evidence)。

  • _rule_fires: on.action(+ 任意の idMatches)/ on.event == screenChanged / on.result == error のいずれかに一致するかを確認します。アクション名は DSL(ドメイン固有言語)名へ変換します(long_press→longPress、assert_→assert)。
  • _collect_captures: 先頭に elements を置いたうえで、インライン step.capture、発火したルールの capture、ターゲットの evidence.capture(他の2つと異なり常に適用される最低保証)を集めて重複排除します。 先頭の elements があるため、3つの取得元が何を要求したかによらず、どのステップにも動作後のツリーが 残ります。ステップ前の baseline はツリーを取得しません(BE-0407)。そのためこの取得がそのステップの 唯一のツリー取得であり、elements.json という 1 つのファイル名に書き込まれます。
  • 対になるもう一方の after.png は、この一覧にはありません。_handle_action が、ステップの動作の直後に 自分で撮ります。ここでツリーを読みうる処理(screenChanged の比較、for wait のタイムアウト診断、 extract)よりも先に撮るためです。そのうえで、上記の一覧から screenshot.after を取り除きます。 どの取得元から来た screenshot 単体のトークンも先に screenshot.after へ正規化するのは、このためです。 同じ 1 枚を二重に撮ることはありません。ただし、この撮影より前に読まれるツリーが 1 つあります。 動作しないステップ(assert、wait)は、自身が評価に使ったツリーを読み直さずに再利用します (BE-0259)。この 2 種類では、elements.json は after.png の直後ではなく直前の時点のものになります。
  • 瞬時種別(screenshot/elements)は sink の capture() で取得し、区間種別(video/deviceLog)は事前に start_intervals() で開始済みのものを停止して回収します。

primary_id は「ステップの主対象セレクタの id」です(tap なら tap 先、type なら into、swipe なら on)。idMatches トリガーはこの id に対して fnmatch します。

実行結果(データ構造)

@dataclass
class StepOutcome:
    index: int
    action: str                  # "tap" / "wait" / ...
    target: str                  # それを走らせた宣言済みターゲット。宣言がなければ ""
    ok: bool
    reason: str                  # 失敗理由
    duration_s: float            # 計時
    actuations: list[Actuation]  # ドライバが実際に行ったこと(送った座標・ジェスチャ)
    assertion_results: list[AssertionResult]
    artifacts: list[Artifact]    # このステップで取れた証跡

@dataclass
class RunResult:
    scenario: str
    ok: bool
    steps: list[StepOutcome]
    expect_results: list[AssertionResult]  # 最終 expect の評価
    failure: str | None          # 例: "step 3 (tap): no match: {...}"
    before_outcomes: list[StepOutcome]  # setup フェーズ自身のステップ
    after_outcomes: list[StepOutcome]   # cleanup フェーズ自身のステップ
    after_verdict: str           # "success" / "failure" — どの cleanup ルールが走ったか。なければ ""
    target_devices: dict[str, TargetDeviceInfo]  # 宣言済みターゲットごとに 1 行(複数ターゲットのみ)
    coordinates: str             # 例: "iPhone SE (3rd generation) / iOS 17"。条件がなければ ""
    run_coordinates: dict[str, dict[str, str]]  # 同じ座標を、ターゲットと条件のフィールドごとに持つ

RunResult の単数形の backend / device / device_name / device_runtime は、どれも 1 つのターゲット だけを説明します。複数ターゲットの run では 4 つとも空のままにし、代わりに target_devices を埋めます。 宣言済みのターゲットごとに 1 行あり、そのターゲットのバックエンド、udid、機種、OS バージョンを持ちます。 単一ターゲットの run は単数形のフィールドを埋め、target_devices を空にします。どちらの読み手にも、 従来どおりの値が見えます。

expect は全ステップ成功後にのみ評価されます。alert_guard があれば expect も 1 回だけ再評価します。これらはそのまま report/ の manifest.json / JUnit / HTML になります(reporting)。

runner(実行パイプライン)

実装: bajutsu/common/runner/。orchestrator を実機と接続し、レポートまで連結します。

launch_driver(アプリを起動して準備済みドライバを返す)

preconditions に従って simctl で環境を構築します:

erase(pre.subject.reinstall が erase なら shutdown → erase) → boot → bootstatus -b(起動の完了を待つ)
  → terminate(bundle)(クリーンな起動状態に)
  → launch(bundle, [subject.launch.args, *locale_args(locale)], {**subject.launch.env, **preconditions.subject.launch.env})
  → openurl(deeplink)(あれば) → make_driver(actuator, udid)
  → await_ready(query() が 2 要素以上返すまで最大 10s ポーリング)

await_ready は、利用できる中で最も強いレディネスシグナルを、次の順に探してポーリングします。

  1. 明示的な subject.startWhen の条件
  2. アプリが報告する画面遷移イベント (BE-0310。BajutsuKit 経由のオプトイン)
  3. 宣言済みの subject.idNamespaces に属する id を持つ要素
  4. どれも無ければ、「アプリが UI を描画した(ルート要素より多い)」ことへのフォールバック。最大 10s まで待ちます

各段の詳細は configuration を参照してください。

どの段で決まった場合も、ゲートは続けて画面が動かなくなるのを待ちます。連続する 2 回のクエリが同じ要素の識別子、ラベル、frame を返した時点で返ります。どの段も答えているのは「アプリの最初の内容が画面に出た」ことであり、遷移の途中の画面もこれを満たします。動いている画面に合成されたタッチは Simulator が取りこぼすことがあります。その場合、操作は配送済みとして報告される一方、失敗はずっと後の無関係なステップの wait タイムアウトとして現れます。

この確認にかかるポーリングは、その段自身のツリー読み取りが比較の起点になる場合は 1 回です。自前の読み取りを持たない screenChanged の段では 2 回かかります。上限は 3 回で、上限に達した場合は、静止しない画面を待ち続けるのではなく ready を返し、最初の wait の診断に settled: false を記録します。この確認が、ready なアプリをタイムアウトに変えることはありません。

locale は launch 時に適用されます。シナリオの preconditions.device.ios.locale がターゲットの runsOn.ios.locale を上書きし、env.locale_args で launch 引数として渡ります。simctl boot は起動を要求した時点で返るため、boot に続く手順はいずれも bootstatus で起動の完了を待ってから進みます。システムロケールの固定が行うもう 1 回の起動も同じです(BE-0359)。simctl の launch 手順は、make -C demos/showcase run-swiftui と ios-e2e.yml CI ワークフローで実機(iPhone 17 Pro)検証済みです。

複数のターゲットをまとめて起動する

run_all は、宣言済みのターゲットごとに TargetPool を 1 つ受け取ります。各 TargetPool は、その ターゲットの解決済み config と、そのバックエンドを受け持つプールを持ちます。さらに、そのターゲット自身 の capability 事前検査が読む actuator とデバイス指定も持ちます。この対応表を埋めるのはコマンドライン層 です。パイプラインは、2 つめのターゲットを起動するために config ファイルもデバイスのレジストリも必要 としません。

パイプラインが作るプールは、ターゲットごとではなく actuator ごとに 1 つです。プールは 1 つの RunEnvironment のデバイスカタログを解決し、そのバックエンド自身のコレクタを先に起動します。iOS の ターゲットと web のターゲットには、作り方の違う 2 つのプールが要ります。actuator を共有する 2 つの ターゲットは、1 つのプールを共有します。両者を区別するのは、それぞれが lease() に渡す config です。 それが、そのリースの起動するアプリを決めます。

パイプラインは、シナリオの最初のステップより前に、宣言済みのターゲットをすべてリースします。どのワーカー も、プールを 1 つの固定順で取ります。プールの actuator、次にターゲット名の順です。この順序が、デッドロック に必要な循環待ちを排除します。すべてのワーカーが同じ向きですべてのプールへ向かうので、互いの次のプールを 握り合うことがありません。途中で起動に失敗したときは、すでに起動済みのものをすべて解放してから例外を 伝播します。シナリオ自身の終了時には、一式をまとめて解放します。

device_pool / run_all / run_and_report

  • device_pool(udids, backends, ...): actuator を選び、(lease, shutdown) の組を返します。lease(eff, scenario) は空いているデバイスをリースし、シナリオごとに launch_driver します。
  • run_all(eff, scenarios, lease, ...): 各シナリオを 新しくリースした、新しいドライバで 実行します(クリーン分離)。
  • run_and_report(...): run_all の結果を write_report(runs_dir/run_id, ...) で書き出し、(results, manifest_path) を返します。

CLI の run はこの run_and_report を呼びます(cli)。

デバイスの条件から作る run(BE-0452)。 シナリオを動かすターゲットの runsOn は、デバイスの条件を宣言できます。そのときは、シナリオを実行する前に bajutsu/run/device_matrix.py が呼び出し全体の計画を、次の順で立てます。

  1. 各プールを 1 回だけ読みます(common/devices/facts.py)。
  2. 各シナリオの run を作り、run ごとに適格なデバイスを選びます(common/devices/runs.py)。
  3. 同じデバイスを使う run を、1 つのセルにまとめます。

セルは 1 つずつ順に実行します。各セルは、適格なデバイスに絞ったプールで run_and_report を通ります。そのため、--workers はセルの run を同一のデバイスに振り分けます。合うデバイスがない run は失敗します。片側が開いた範囲なら、その run は対象外の記録になり(configuration)、ドライバには届きません。どのターゲットも条件を宣言していない呼び出しは、上の経路をそのまま通ります。

ウォームな XCUITest ランナー(BE-0291)。 各シナリオは今も新しく起動したアプリと新しいドライバで 実行します(クリーンな分離)。XCUITest バックエンドの常駐 xcodebuild ランナーは、コールド起動が 最大の固定コストです。そこでプールは、このランナーをデバイスごとにリースをまたいで常駐させ、 シナリオの切り替えではアプリだけを再起動します。これにより、スイートが払うコールド起動は シナリオごと 1 回ではなくデバイスごと 1 回で済みます。

プールはウォームランナーを (udid, actuator) をキーに保持します。次の 3 つの場合は、ランナーを ティアダウンして起動し直します。別の actuator に解決されるリース(BE-0240)、デバイスを erase する シナリオ、境界の定まった /health プローブに失敗したランナーです。プローブの失敗はキャッシュ ミスとして扱うため、コールド起動 1 回分の追加で済み、run を失いません。adb と Playwright の各バック エンドはこの常駐プロセスを持たず、挙動は変わりません。

常駐ランナーは app.launch() を数回繰り返すとクラッシュします。 これは XCTest セッションの制約です(docs/architecture.md を参照)。そのためウォーム再利用には上限を設けています(BE-0287)。 BAJUTSU_XCUITEST_MAX_WARM_REUSES 回(既定 3)再利用したら、次の起動でランナーがクラッシュする前に 先回りしてコールド再生成します。クラッシュがシナリオの途中で起きて run を失うのを防ぐためです。 上記の /health プローブは、すでにクラッシュしたランナーを検知する事後的なものにすぎません。 長いスイートをクラッシュから守るのは、この先回りの再生成です。より早くクラッシュするデバイスでは、 この値を 0 にするとウォーム再利用を完全に無効化できます(毎リースをコールドにします)。

バックエンドクラッシュからの復旧。 上記の先回りの再生成はクラッシュの窓を狭めるだけで、完全には 閉じません。バックエンドがそれでもシナリオの途中でクラッシュした場合、_ScenarioRunner.run_one は バックエンドに依存しない base.BackendCrashError(XCUITest に限らず、どのドライバも送出できます)を 捕まえます。そして死んだリースを破棄し、新しいリースを取得して、シナリオ全体を最初からやり直します。 プールは死んだウォームランナーを捨てるため、新しいリースはコールド再生成になります。

再試行には 2 つの上限があります。

  • crash_retries:リトライ回数の上限です。既定は 1 で、最初のクラッシュ後に 1 回だけ再試行します。 環境変数 BAJUTSU_CRASH_RETRIES で上書きできます。
  • crash_recovery_budget:再生成に費やす合計時間の任意の wall-clock 上限です。既定は無制限で、 環境変数 BAJUTSU_CRASH_RECOVERY_BUDGET(秒単位)で上書きできます。

この予算があるのは、回数の上限だけでは時間を制限できないためです。復旧しないランナーを相手にすると、 crash_retries の試行のたびにコールド起動の上限いっぱいまで時間を費やし、はっきりした失敗ではなく 黙ったジョブのハングになりかねません。試行のたびにクラッシュするシナリオはどちらかの予算を使い切り、 はっきりと失敗します。黙って合格扱いにはしないので、本当にクラッシュを誘発するシナリオが flaky の 温床に紛れ込むのを防ぎます。

2 つ目の run 単位の予算は run_crash_recovery_budget で、こちらも既定は無制限です。 環境変数 BAJUTSU_RUN_CRASH_RECOVERY_BUDGET で上書きできます。この予算は、この run 内のすべてのシナリオを通じて 累積した復旧時間に上限を設けます。crash_recovery_budget だけではシナリオが変わるたびにリセット されてしまいます。劣化し続けるデバイスはこの予算を何度も払い続け、最終的には run 自体がはっきりと 失敗する代わりに、外部の CI タイムアウトが診断不能な形でジョブを打ち切ることになります。

最終的に成功する復旧にこの run 単位の予算を使い切っただけでは、何もラッチされません。デバイスが まだ機能していることを示しているにすぎないからです。あるシナリオ自身のクラッシュ再試行ループが、 この予算を主因として実際に失敗した後は、run_one がそれ以降のどのシナリオでも、その先頭でこの状態を 確認します。確認はクラッシュ再試行ループ自身の except 節の中だけでなく、そのシナリオ自身の最初の リースすらまだ試みていない時点でも行います。これにより、すでに復旧できないと分かっているデバイスに 対して、残る全シナリオが同じ打ち切りに至るまでにコールド起動の試行を 1 回ずつ余計に払わずに済みます。

このラッチにはもう 1 つの原因があり、そこには同じ限定が要りません。デバイスの準備がタイムアウトした 場合です(BE-0374、下記)。予算は測定値であり、時間はかかったものの最終的に成功した復旧でも超える ことがあります。一方、返ってこなかったデバイス操作は、あらゆる操作の背後にあるサービスが応答を やめたという直接の観測なので、タイムアウトは単独でラッチします。ラッチはどちらの原因で立ったかを 保持します。そのため、後続シナリオの失敗は実際の原因を報告します。run 単位の予算は既定で未設定 なので、報告できる予算を持たない run もあります。

XCUITest バックエンドでは特に、コールド再生成それ自体の起動が、自動操作を受け付けなくなった Simulator の再起動または置き換えというデバイス修復の代金も払うことがあります。どちらの予算もこの デバイス修復を止められません。CrashRecoveryBudget.on_crash はクラッシュとクラッシュのあいだでしか 参照されず、進行中の起動を短く切り上げることはできないためです。修復自体の上限 (BAJUTSU_XCUITEST_RECOVERY_TIMEOUT、および上限のない再準備)だけが、これを制限します。

再試行はまた、preconditions.subject.reinstall: erase を強制します。シナリオがこの値を宣言した ときにすでに得られるのと同じデバイスのリセットです。XCUITest では Simulator 自体の再起動、adb では アプリレベルのクリーンな状態化であり、直前にクラッシュしたそのデバイスへのその場での respawn ではありません。次の 3 つの場合は、強制 erase をスキップします。

  • マージ後の reinstall(シナリオの値、なければターゲットの値)が overwrite で、アプリのデータを リースをまたいで残す場合。
  • 経路自体が erase の precondition をそもそも受け付けない場合。実機(runsOn.ios.kind: device)や、 appium グリッドへの live 経路です。
  • 明示的な bajutsu run --no-erase。CLI はこのフラグを force_erase_on_retry として run に渡すため、 オペレーターの明示的な選択は強制再試行を止められます。

組み込みの既定であるマージ後の clean は、強制 erase をスキップしません。clean もアプリのデータを 消すので、その値を見るガードでは、強制 erase がまさに対象としている実運用の経路そのもので強制再試行を 無効にしてしまいます。CLI は、すべてのシナリオに erase の具体的な値を書き込むことをやめました。 _filter_scenarios がシナリオの reinstall を動かすのは、フラグが値を変えるときだけです (BE-0473)。

強制 erase 用のリース自体が、デバイスレベルの不具合で失敗したとします。不具合は simctl.DeviceError か adb.DeviceError で、BackendCrashError とは別系統の型であり、その派生ではありません。このときは、同じその場での respawn に切り替えます。切り替えなければ、この不具合がこのループの外まで伝播し、run 全体が run_all を越えて中断されてしまいます。例外はタイムアウト(device_errors.DeviceTimeout。iOS では simctl.DeviceTimeout)で、このときは切り替えずにシナリオを失敗させます(BE-0374)。

切り替えが答えているのは、応答したうえで拒否したデバイスです。拒否は 1 つの操作についての証拠なので、 強制 erase が入る前と同じその場での respawn を与えるのが筋にかないます。まったく応答しなかった デバイスは、操作そのものについての証拠を何も出しておらず、あらゆる操作の背後にあるサービスが応答を やめたことだけを示します。そこへ再試行するのは、タイムアウトが否定したことをそのまま前提に置く行為 です。失敗するのはそのシナリオだけで、失敗の文面には超過したコマンドと期限が入り、run がすでに得た 判定はすべて残ります。判定を残すことは、そもそも切り替えが守ろうとしていた性質です。同じ分岐は続けて run をラッチします(上記の run 単位の予算を参照)。固まったホストは、たまたま出会ったシナリオでは なくホストに属する性質なので、後続のどのシナリオにも自前の期限を払わせて同じことを再発見させません。

再生成されたアプリのデータは既定で消去されるため、再試行が安全なのはクラッシュ地点まで冪等な シナリオに限られます。次の 2 種類のシナリオは、再実行時に失敗するか、誤った状態のまま合格する ことがあります。クラッシュ前にサーバー側書き込みのような永続的な副作用を伴うシナリオと、同じ シナリオの前のステップがすでに用意した状態に依存するシナリオです。この判定ロジックは bajutsu/common/runner/recovery.py にあり、オンデバイスのドライバ適合性スイートと共有しています。 これにより、Simulator のインフラ障害が起きても、無関係な PR で必須チェックを赤くすることなく 同じように復旧します(BE-0334)。

強制 erase のさらに上に、Simulator の XCUITest 経路にかぎってデバイスの置き換えという段が あります(BE-0354)。erase が消すのはデバイスのデータです。アプリのデータ破損はそれで復旧しますが、 画面キャプチャの機構が固まった Simulator は復旧しません。CI では、erase したデバイスが固まったまま 戻り、再試行が 1 回目の試行をそのまま再現しました。そこで、強制 erase 付きで走った再試行がまた クラッシュした場合、次のリースはそのリースの環境に対して、何も実行したことのないデバイスを要求します。 作成の手順は、消えたデバイスを置き換えるときと同じものを使います。劣化したデバイスはシャットダウン し、以後プールに戻しません。この手順は、新しいデバイスに古いデバイス自身のデバイスタイプと ランタイムを引き継がせ、できなければ run を失敗させます。config で指定したモデルや最新の iPhone に 切り替えることはありません (BE-0452)。

試行が残した映像の証跡から、この段を直接選ぶこともできます。録画が書き込みを始めたことを確認できない まま終わった場合、それが機構の固まりの最初の兆候なので、1 回目のクラッシュで置き換えへ進み、 この兆候がすでに否定した erase を飛ばします。置き換えの試行では強制 erase を外します。これから 作成するデバイスには消すものがないからです。

この段が働くのは、udid を固定しておらず subject.path を持つ run にかぎります。

  • --udid はオペレーターが名指ししたデバイスであり、置き換えれば run が黙ってそのデバイスから 離れてしまいます。udid を固定しない run はデバイス 1 台をワーカー 1 つで扱うので、置き換えを要求 した試行の次のリースは必ず同じデバイスを取り直します。
  • まっさらなデバイスには入れるアプリが必要です。そのため、この段は subject.path を要求します。

置き換えが消すものは erase より多いので、erase の段が尊重する 2 つの離脱指定、 reinstall: overwrite と bajutsu run --no-erase も同じように尊重します。ほかの経路は要求を無視し、 それぞれが今持つもっとも強い再試行を保ちます。どちらの兆候も選ぶのは段だけで、判定には触れません。 クラッシュし続けるシナリオは予算を使い切り、はっきりと失敗します。

協調的なキャンセル(BE-0370)。 キャンセルされた run は、その場で死ぬのではなく自分の手順で終わり、 失敗した run として run 履歴に残ります。bajutsu run は SIGTERM を受けると、Python の既定動作 (即座のプロセス終了)に任せる代わりにイベントを立てます。パイプラインは、そのイベントを 3 つの 安全な境界で読みます。

  • run_all のディスパッチループでシナリオを始める直前
  • 1 つのシナリオのステップとステップのあいだ
  • 条件待ちを支える既存のポーリングループの内側

キャンセル要求が届いたシナリオは RunResult(ok=False, failure="cancelled") になります。これは バックエンドのクラッシュや preflight の失敗がすでに作るのと同じ形です。そのため run_all は今までどおり 宣言順にシナリオ 1 件あたり 1 件の結果を返し、run_and_report は manifest.json、report.html、 JUnit XML を、ほかの失敗した run とまったく同じように書きます。長いスイートの早い段階でキャンセル したオペレーターには、実行に至らなかったシナリオも失敗として数えられて見えます。キャンセルされた run を失敗として扱うこと自体から出てくる帰結として、これを受け入れます。

イベントを読む場所は、この 3 つのほかにもう 1 つあります。バックエンドのクラッシュがコールド再生成を 新たに始めてしまう地点(上記の再試行)です。その立ち上げは下記の猶予窓を越えることがあり、run は何も 書かないまま終わらせられてしまいます。

シャットダウンは、外側で待っている者がいるかどうかに関わらず有界です。1 回のドライバ呼び出しの内側で 止まっているシナリオは、その呼び出しが返るまでキャンセル要求に気付きません。XCUITest の HTTP リクエスト、adb のサブプロセス、Playwright の呼び出しは、いずれもその長さだけシナリオを保持します。 そのため協調的な経路には猶予窓を与えます。猶予窓は BAJUTSU_CANCEL_GRACE で決めます。既定は 90 秒で、 一過性リトライに乗る読み取りが保持しうる 60 秒に、その後ろのシャットダウンの尻尾(残るシナリオを 失敗させ、レポートを書き、合否の行を出力する分)30 秒を足した値です。呼び出しと同じ長さの窓では、 この尻尾に何も残りません。

その猶予窓よりさらに後ろに置いたハンドラ自身の期限を過ぎると、ハンドラは SIGTERM の既定動作を 復元して再送出します。これにより、本当に固まったランナーは、ハンドラがなかった場合とまったく同じように 死にます。ハンドラは serve Web UI の Cancel ボタンだけでなく、あらゆる送り手に応えます。 docker stop、systemd のユニット停止、CI ジョブのキャンセルも同じハンドラに届きます。serve の側は、 無条件の kill に上げる前に同じ猶予窓を自前のタイマーで待ちます。さらに、その窓を起動する run にも 渡します。run 側の内部期限は、独立に選んだ定数ではなく serve が実際に待っている窓に結び付きます。

クロスブラウザの matrix run では、エンジンのパスとパスのあいだでもイベントを読みます。各パスは まず device_pool を丸ごと立ち上げます(環境の解決、デバイスカタログの読み取り、デバイスごとの コレクタの起動)。この確認がないと、最初のエンジンの途中でキャンセルしても、run が終わるまでに残りの エンジンすべての立ち上げと片付けを支払うことになります。走らなかったエンジンのシナリオは、レポートから 落とすのではなくキャンセルとして失敗させます。そのため manifest の matrix ブロックは要求された エンジンをすべて並べ、cancelled と表示されたセルが「その軸は要求されたが実行されなかった」ことを そのまま示します。落としてしまうと、ok は実際に走ったパスだけを集約することになり、最初のエンジンが 全件合格した後に届いたキャンセルは、走り切っていない run を PASS として記録してしまいます。