English · 日本語
CLI リファレンス¶
実装:
bajutsu/cli/(Typer。各コマンドは所属する機能のディレクトリに置かれます。例:run/cli.py、record/cli.py)。cli/commands/に残るのは、機能を持たないdoctor、lint、schema、config、report、runnerだけです。エントリポイントはpyproject.tomlのbajutsu = "bajutsu.cli:app"。 この CLI(コマンドラインインターフェース)のすべてのコマンドは--target <name>で 1 アプリを選び、--config(既定bajutsu.config.yaml)で設定を指します。アプリ固有の差分は config 側にあります(configuration)。
関連: run-loop · recording · codegen · configuration
共通¶
- 全コマンドの前に
.envを読み込みます(_bootstrap、下記)。 - config がない、アプリが未定義、または actuator が使えないときの結果は、メッセージの出力と 終了コード 2。
--backendは選択ではなく検査です。ターゲットは 1 つのplatformを名指しし、それが actuator を 決めます(drivers)。このフラグが受け付けるのは、ターゲットの platform(例ios)、その platform の actuator 名(xcuitest、adb、playwright)、fakeです。 それ以外の値やカンマ区切りのリストは終了コード 2 で終わります。空ならターゲット自身の platform を 使います(BE-0452)。--udidは URL を受け付けません。Appium グリッド経由でデバイスを動かすコマンドは、--worker-configのファイルのappium環境でグリッドを名指しします(runを参照)。
run¶
シナリオを 決定的に実行します。合否は機械判定のみで、BE-0402 以降はどのフラグを付けてもモデルに到達しません。アラートガードは、--no-system-alert-handling を付けない限り ON です。ガードが答えるのは、シナリオの interrupts とターゲットの hooks.interrupts にある systemAlert エントリが名指しする OS プロンプトです。答えにはネイティブの SpringBoard 経路(iOS XCUITest、モデル不使用)を使います。どのエントリも名指ししないプロンプトや、その経路が名指しできないプロンプトには手を触れず、ブロックされたステップ自身の失敗理由に書き出します。詳しくは systemAlert の interrupts エントリ を参照してください。
bajutsu run --target <name> [--scenario <file.yaml>] [options]
bajutsu run --scenario <self-declaring.yaml> [options] # --target は省略可
既定では、アプリの設定済みシナリオディレクトリ(targets.<name>.paths.scenarios、configuration 参照)の
すべての *.yaml を読み込んで実行します。config だけで実行できます。1 ファイルだけ実行するには --scenario <file> を渡してください。このフラグを繰り返すと、指定した複数ファイルを1つの warm な runner を共有しながら1プロセスで実行できます。
run は run 本体を子プロセスで実行します(BE-0449)。
run はフラグを子プロセスに渡し、bajutsu worker --once と同じ 1 回実行の経路を通ります。そのため、コマンドラインと worker は同じ実装で run を実行します。
子プロセスは端末の標準入力、標準出力、標準エラーを引き継ぎます。
したがって PASS|FAIL の行は stdout に、進捗は stderr に出て、--step もこれまでどおり端末から読みます。
子プロセスは独自のセッションで動くので、Ctrl-C は run 本体ではなく run に届きます。
run は SIGINT、SIGTERM、SIGHUP を、serve の job が受けるキャンセルに変えます。
run は次の安全な区切りで止まり、マニフェストとレポートを書き出します(BE-0370)。
呼び出し側がすでに無視しているシグナルは無視したままにします(nohup が SIGHUP を無視する場合など)。
子プロセスが独自のセッションで動くことで、端末での振る舞いがほかに 3 つ変わります。
- 2 回目の Ctrl-C。 1 回目の Ctrl-C は run に停止を求めます。ドライバーの呼び出しが進行中なら、停止まで猶予時間(既定 90 秒、
BAJUTSU_CANCEL_GRACE)かかることがあります。もう一度 Ctrl-C を押すと、マニフェストを書かずに run をすぐ止めます。 - Ctrl-Z。
runは run のプロセスグループを停止してから、自身も停止します。fgかbgで両方が再開します。 - バックグラウンドの
--stepの run。 run は端末のジョブ制御に属さないので、&で起動した run の--stepプロンプトは、ジョブを停止せずに端末から読みます。--stepはフォアグラウンドで実行してください。
run 自身が捕捉できない形で終了した場合(kill -9、メモリ不足による強制終了)も、run 本体は呼び出し側がいなくなったことに気づき、同じ方法で自らをキャンセルします。
web backend が動く Windows では、run は BE-0449 以前と同じく run 本体を自身のプロセスで実行します。子プロセス、シグナルの中継、上記の端末での 3 つの振る舞いは、macOS と Linux だけに当てはまります。
| 終了コード | 条件 |
|---|---|
| 0 | すべてのシナリオが成功した。対象外の記録が並んでいても変わらない |
| 1 | いずれかのシナリオが失敗した。または、すべての記録が対象外だった(no run executed) |
| 2 | 未知のフラグや読み込めない config などの使い方の誤り |
| 128 + シグナル番号 | run が SIGINT(130)、SIGTERM(143)、SIGHUP(129)を受け取った。キャンセルされた run の結果にかかわらずこの値です |
--target を省略できる場合¶
自分で targets を宣言するシナリオは、
必要なターゲットをすべて config から解決します。--target が決めることは、もう残っていません。ここから
規則が4つ導かれます。
| 規則 | 何が起きるか |
|---|---|
代わりに --scenario が必須になります |
スイート全体の短縮記法は、1つのターゲットの設定済みシナリオディレクトリを glob します。2つ以上のターゲットを名指しするシナリオは、そのどのディレクトリにも属しません。そのため、ファイルを明示的に名指しします |
--target を明示したら、無視せず検査します |
自分で宣言するシナリオに添えて渡した場合、そのシナリオが宣言しているターゲットのどれかを名指しする必要があります。ファイルを編集したあとに残った古いフラグは、ファイルが外したターゲットを選ばず、終了コード 2 で止まります |
| シナリオディレクトリは、自分で宣言するファイルを拒みます | 自分の targets を持つファイルが、あるターゲットの設定済みディレクトリにあると、実行を始める前に失敗します。エラーはそのファイルを名指しし、--scenario を指し示します。この確認は --tag / --exclude の絞り込みの後に行うので、そのファイルを選択から外したスイートは残りを実行します |
両方の形が混ざったバッチには、なお --target が要ります |
targets を宣言しないファイルは、起動の --target 以外にターゲットを解決する手がかりを持ちません。そのファイルが1つでもバッチにあると、フラグの省略は失敗し、そのファイルを名指しします |
両方の形が混ざっていても、--target を渡せば従来どおり動きます。ターゲットを宣言しないファイルは、
これまでどおりそれを使います。自分で宣言するファイルは、代わりに所属を検査されます。
| オプション | 既定 | 説明 |
|---|---|---|
--target |
(必須。ただし --scenario のファイルがすべて自分の targets を宣言していれば省略可) |
対象アプリ(config の targets.<name>)。--target を省略できる場合を参照 |
--scenario |
config の paths.scenarios ディレクトリ |
アプリのシナリオディレクトリ全体ではなく指定した *.yaml を実行。フラグを繰り返すと、複数ファイルを1つの warm な runner を共有しながら1プロセスで実行 |
--backend |
ターゲットの platform |
ターゲットの platform に対する検査。platform、その actuator 名、fake のいずれか(共通を参照) |
--tag |
"" | カンマ区切り。これらの tag のいずれかを持つシナリオのみ実行 |
--exclude |
"" | カンマ区切り。これらの tag のいずれかを持つシナリオをスキップ |
--udid |
booted |
対象 Simulator(カンマ区切り = --workers 用のデバイスプール)。URL は終了コード 2 |
--erase / --no-erase |
シナリオ › config › clean |
すべてのシナリオについて、実効の subject.reinstall を段階(overwrite < clean < erase)に沿って動かします。--erase は値を erase(シム全体を wipe)にし、--no-erase は erase を clean に下げ、overwrite と clean はそのままにします。どちらも省略すると、各シナリオの preconditions.subject.reinstall、次にターゲットの subject.reinstall、次に clean の順で解決します(BE-0473)。そのため、erase を指定したターゲットは --no-erase でアプリをアンインストールします。アプリのデータを残したいシナリオは preconditions.subject.reinstall: overwrite と書きます |
--system-alert-handling / --no-system-alert-handling |
ON | すべてのシナリオについてシステムアラートガードを ON / OFF にします。ON のとき、ガードはシナリオの interrupts とターゲットの hooks.interrupts にある systemAlert エントリに答えます。iOS バックエンドから見えないシステムアラートを消すリアクティブなガードで、XCUITest 上ではネイティブに処理します(モデル不使用、BE-0315)。シナリオやターゲットがガード全体を OFF にする手段はありません。プロンプトを自分で処理するシナリオは、そのプロンプトのエントリに choice: leave と書きます(BE-0473)。どのエントリも名指ししないアラートには何もしません。ガード対象の wait は見たものを自身のタイムアウトで必ず名指しし、wait の外のステップは、ネイティブ照会がアラートを列挙できたときだけ名指しします。ネイティブ照会を持たないバックエンドでは名指しする材料がないため、そのステップは従来どおり失敗します(BE-0402)。AI 認証情報は一切不要です(recording) |
--ios-tipkit-handling / --no-ios-tipkit-handling |
シナリオ › config › OFF | 操作をブロックしている Apple TipKit の tip(フレームワークが所有する popover)を閉じるか、残すかを決めます。このフラグは、すべてのシナリオの tipKit の interrupts エントリを dismiss または leave に設定し、シナリオ自身のエントリとターゲットのエントリに優先します。同じ回避策をシナリオごとに手で書かずに済ませるためのガードです。ガードは tip を、閉じるための scrim(PopoverDismissRegion)とその tip 自身のコンテナ(TipView)の両方で判定します。confirmationDialog が同一の scrim を設置するため、そちらには手を触れないようにする必要があるからです。同じ理由で、tip 向けの画面エントリを interrupts(またはターゲットの hooks.interrupts)に手で書く場合は TipView を手がかりにします。iOS 専用(他のバックエンドでは何もしません)で、求められない限り OFF です。tip 自体がアサーションの対象になる場合があるからです。省略時は各シナリオ自身の tipKit エントリ、次にターゲットのエントリ、次に OFF の順で解決します。認証情報は不要です(scenarios) |
--alert-poll-interval |
未設定 | ネイティブのシステムアラート presence 照会の間隔(秒)。シナリオ自身の systemAlert エントリの pollInterval がこのフラグに優先し、このフラグはターゲットの値に優先します。同じ層の中では、いちばん小さい値を使います。エントリそのものにフラグはありません。1 エントリはプロンプトと選択の組であり、フラグの値 1 つでは読みやすく運べないため、宣言はシナリオファイルとターゲット config に置いたままにしています(BE-0406) |
--log-predicate |
"" | deviceLog ストリームを絞る NSPredicate(例 subsystem) |
--log-subsystem |
"" | appTrace 用の os_log subsystem(既定はアプリの subject.id) |
--network / --no-network |
config › ON | request アサーション用にアプリの通信を収集。省略時はターゲットの evidence.collectNetwork config、次に ON の順で解決(BE-0177)。iOS はアプリに BajutsuKit が必要。web は Playwright でネイティブに観測し、シナリオの mocks をその場でスタブします |
--workers |
1 | デバイスプール上で並列実行します。複数のターゲットを宣言するシナリオは、ターゲットごとに1台のデバイスをそのシナリオの全長にわたって保持します。そのため run は、ワーカーが互いのデバイスを奪い合わない範囲までこの値を抑えます。iOS では --udid u1,u2,… が必要で、そのプール数で上限になります。web では --workers N だけで N 本の並列ブラウザコンテキストレーンになります(--udid 不要、BE-0054)。各レーンが自前のネットワークコレクタ、インターバル録画、(iOS では)デバイス制御を持つので、network / 動画 / setLocation / push はシングルデバイス実行と同じく機能します |
--baselines |
config の paths.baselines、次にシナリオ隣の baselines/ |
ターゲットの paths.baselines を上書きします。visual アサーション用のベースライン画像ディレクトリ。baseline: home.png はこの中で解決されます |
--schemas |
config の paths.schemas、次にシナリオ隣の schemas/ |
ターゲットの paths.schemas を上書きします。responseSchema アサーション用の JSON Schema ファイルのディレクトリ。schema: items.json はこの中で解決されます(schema extra が必要です) |
--goldens |
config の paths.goldens、次にシナリオ隣の goldens/ |
ターゲットの paths.goldens を上書きします。golden アサーション用の golden JSON ファイルのディレクトリ。golden: response.json はこの中で解決されます |
--headed / --no-headed |
ターゲットの driver.headless(既定はヘッドレス) |
web backend: ヘッドレスの代わりにブラウザを画面に表示し(低速再生)、実行の各ステップを確認できます(コマンドを実行しているマシン上でウィンドウが開きます)。省略時はターゲットの driver.headless 設定に従います。iOS は無視します |
--browser |
ターゲットの runsOn.browser.kind(既定 chromium) |
web backend: この run で使うブラウザ。chromium / chrome / edge / firefox / webkit から選びます。省略時はターゲットの runsOn.browser.kind config に従います。フラグはこのフィールドを置き換えるので、ターゲットがリストで宣言したブラウザはデバイス条件として数えなくなります。ブラウザをリストで宣言したターゲットでは、そのリストにあるブラウザを指定します。リストにないブラウザを指定すると終了コード 2 で終わります(configuration、BE-0076、BE-0468) |
--browsers |
"" | web backend: クロスブラウザマトリクスを実行します。ブラウザの種類のカンマ区切りリスト(例 chromium,firefox,webkit)を指定すると、各シナリオがブラウザごとに1回ずつ走り、全ブラウザが合格して初めて run 全体が緑になります(configuration)。ブラウザをリストで宣言したターゲットでは、指定するブラウザがすべてリストに含まれている必要があり、含まれないものがあると終了コード 2 で終わります。エンジンを1つだけ指定するのは --browser と同じです |
--kind |
ターゲットの runsOn.ios.kind にあるすべての種類 |
iOS: 指定した種類だけを実行します。simulator、device、または両方のカンマ区切りリストを指定でき、種類ごとに1回ずつ走ります。指定する種類はターゲットが宣言したものに限ります。runsOn.ios.kind のリストにない種類を指定すると、ターゲットの種類を示して終了コード 2 で終わります。種類を1つだけ宣言したターゲットは、その種類だけを受け付けます。指定した種類は座標に残るので、--kind device の run は、リスト全体を実行したときの device の run と同じ履歴にまとまります。このフラグはコマンドの --target に適用するので、シナリオが 2 つ目の iOS ターゲットを宣言する run では終了コード 2 で終わります(BE-0468) |
--progress / --no-progress |
off | シナリオ / ステップごとの進捗を stderr に流します(serve UI が消費します) |
--score / --no-score |
off | アプリの入口画面の規約スコア(doctor の Ready/Partial/Blocked グレード)を、この run 自身の最初の起動から算出して stderr に出力します。2 つめの XCUITest ランナーをコールド起動する別立ての doctor を挟まずに、CI がこの目印を読み取れます。診断専用で、pass/fail には一切影響しません |
--trace-driver |
off | シナリオごとに <sid>/driver_trace.json を書き出します。呼び出されたドライバーのメソッド、ホストとデバイス間の各ラウンドトリップ、Android ではそのうちどれがサブプロセスにフォールバックしたかといった、Python とドライバー間のすべての呼び出しを、開始時刻と所要時間つきで、発生したステップに紐づけて記録します(BE-0415)。診断専用で、pass/fail には一切影響しません |
--step |
off | 1 つのシナリオをデバッグします。各ステップの前で step> プロンプトに停止します(シナリオをステップ実行する)。端末、シナリオ 1 つ、エンジン 1 つ、ワーカー 1 つが必要です |
--break |
— | 指定したステップで停止します。ステップは name、または失敗理由に表示されるインデックス(step 3 (tap): … ならインデックス 3)で指定します。そこまでは止まらず実行します。複数回指定でき、プロンプトを有効にします |
--break-on-fail |
off | ステップが失敗した時点で、その画面が残ったままプロンプトに停止します。プロンプトを有効にします |
--zip |
off | run の後に runs/<id>.zip も書き出します。レポートと証跡をまとめた1つの可搬な成果物で、CI アップロードや共有に使えます。判定の後に走るので pass/fail に影響しません。export 参照 |
--runs-dir |
runs |
run ツリーを書き出すディレクトリ。作業ディレクトリと出力先を分けられる。serve は、アクティブな config が別のツリー(Git チェックアウトやアップロードされたバンドル)からバインドされているとき、そのツリーで走らせつつ run を serve のストアに残すためにこれを使います(BE-0073) |
--evidence-store |
"" (環境変数 BAJUTSU_EVIDENCE_STORE も可) |
run の後に、run ツリー全体をこの URI のオブジェクトストレージへアップロードします。s3://bucket/prefix(AWS / R2 / MinIO)または gs://bucket/prefix(Google Cloud Storage)を指定します。リモートのレイアウトはローカルと同じ構造を prefix 配下に再現するので(<prefix><runId>/…)、アップロード先のパスによってクラウドのライフサイクルポリシーが切り替わります(main ブランチの証跡は保持し、feature ブランチの証跡は短期で失効させる、など)。判定の後に走るので、アップロードが失敗しても警告を出すだけで pass/fail には影響しません。s3 または gcs の extra が必要です(BE-0110) |
--config |
bajutsu.config.yaml |
config ファイル |
--label |
config 自身の名前 | この run の履歴エントリに、短い自由記述のラベルを付けます。2 つの config の run を、run 一覧・Replay・run 統計ダッシュボードで読み分けられるようになります(BE-0404)。ツールにとってラベルは不透明な値で、解析も config との照合も権限判定もしません。120 文字を超える値は、切り詰めずに拒否します |
--config-offline |
off | Git ソースの --config(configuration)向け。ローカルキャッシュだけを使い、ネットワークには一切触れません。ブランチはオフラインで解決できないので、pinned な @<sha> が必要です |
--require-pinned-config |
off | Git ソースの --config 向け。コミット SHA を pin していなければ失敗します。ブランチや tag はゲート下で動きうるので、SHA だけを受け付けます |
--worker-config |
同梱の既定(bajutsu/common/capability/worker.yaml) |
この run の判定に使う worker 能力ファイル。既定の代わりに使い、既定とはマージしません(BE-0450。このマシンで動かせるものを参照)。run は自分のホストか Appium グリッド経由でデバイスを動かすので、ファイルの environment は local か appium です。devicefarm のようなデバイスクラウドの環境は終了コード 2 で終わります。Device Farm のパッケージ内の実行は devicefarm-host を使います。デバイスは Device Farm が起動し、アプリもインストール済みなので、実行は app.path をインストールせずにそのビルドを起動します(BE-0465)。appium のファイルは、グリッドの endpoint と、グリッドが受け持つ 1 つの platform(現在は ios)を名指しします。その platform のターゲットはエンドポイントをデバイスとして使い、シナリオのほかのターゲットはこのホストに残ります。グリッドのターゲットを 2 つ持つシナリオは拒否します(BE-0452)。record、crawl、repl、audit、doctor、bajutsu mcp も同じフラグを受け付けます |
- 証跡は
FileSink(runs/<runId>, udid=..., log_predicate=...)に書きます(evidence)。 runIdはYYYYMMDD-HHMMSS。- 出力:
PASS|FAIL runs/<runId>/manifest.json。終了コードは全シナリオ成功で 0、失敗で 1。 - worker の能力(BE-0450)。
runは target を解決する前に、各シナリオを検査します。 照らし合わせる対象は、worker 能力ファイルとホストの OS です。ファイルは--worker-configで指定し、 指定がなければ同梱の既定を使います。このマシンで動かせない ドライバを必要とするシナリオや、maxTargetsPerJobを超える数の target を宣言するシナリオは、worker-capability-unsupported:で始まる理由で失敗します。この失敗は、ほかの失敗シナリオと同じく run の結果とレポートに記録されます。そのシナリオのためにデバイスは確保せず、残りのシナリオは実行します。 実行できるシナリオが 1 つもなければ、runは理由を列挙して終了コード 2 で終了します。 - デバイス条件から run を作ります(BE-0452)。 ターゲットはデバイス条件を宣言できます。
runsOn.ios.model、runsOn.ios.os、runsOn.ios.family、runsOn.android.avd、runsOn.android.apiLevel、runsOn.browser.version、およびkind、model、avd、browser.kindに書いたリストがデバイス条件です。シナリオは自分では条件を 宣言しません(BE-0469)。runは--udidのプールの すべてのデバイスを読みます。並べた値ごと、範囲のメジャーバージョンごとに run を 1 つ作り、 それぞれを自分の適格なデバイスで実行します(configuration)。 各 run の証跡はruns/<id>/run-NN/に置き、JUnit と CTRF のテスト名には座標が付きます。 合うデバイスがない run は失敗します。片側が開いた範囲でデバイスがなかった run は「not applicable」 (対象外)になり、コンソール、マニフェスト、各レポートが別に並べます(reporting)。 判定の行の直前の行が、成功、失敗、対象外の件数を示します。すべての記録が対象外の ときは、runは終了コード 1 で終わり、no run executedを出します。audit --repeatと MCP の run も同じように run を作ります。record、crawl、replは最初の run だけを使います。doctorは その run を一覧にします(後述)。--backend fakeはどの条件も照合せず、通知を 1 回 出します。browser.versionのような条件が残る状態で--browsersを渡すと終了コード 2 で終わり、 条件が複数の run を作るときの--stepも終了コード 2 で終わります。 - シナリオの preconditions は、デバイスを操作する前に検査します(BE-0452)。
runとauditは、 各シナリオを、そのシナリオが動かすターゲットと照合します。動かすどのターゲットのプラットフォームにも ないsubjectのフィールドや、iOS 専用のtipKitエントリは、フィールド名を示して終了コード 2 で 終わります。実効のsubject.reinstall: eraseを伴わない iOS のseedPhotosも同じです(scenarios)。 AI usage:行は出力しません。runはどのフラグを付けてもトークンを消費しないため(BE-0402)、 使用量台帳を導入せず、報告もしません。record、crawl、triage --aiは従来どおり出力します。
bajutsu run --target showcase-swiftui --udid <UDID> --backend ios --no-erase # アプリのシナリオディレクトリ全体
bajutsu run --scenario demos/showcase/scenarios/smoke.yaml --target showcase-swiftui --no-erase # 単一ファイル
bajutsu run --scenario cross-platform.yaml --config both-targets.yaml # ファイルが自分でターゲットを名指しする
bajutsu run --target showcase-swiftui --worker-config worker.yaml # iOS のターゲットを Appium グリッドで動かす
最後の行の worker.yaml は、appium 環境でグリッドを名指しします。
version: 1
environment: appium
appium:
endpoint: https://grid.example.com/wd/hub
platform: ios # 現在受け付ける値はこれだけ
drivers: [xcuitest, adb, playwright, fake]
シナリオをステップ実行する¶
--step、--break、--break-on-fail を指定すると、ステップループを step> プロンプトで止め、
ステップの合間にアプリの状態を確認できます。プロンプトは stderr に出るため、stdout は従来どおり
PASS|FAIL の 1 行です。--step は最初のステップの前と、その後のすべてのステップの前で止まります。
--break は指定したステップに達するまで止まらず実行します。--break-on-fail は失敗したステップで 1 回だけ止まります。シナリオ単位の expect の不一致では止まりません。
| コマンド | 動作 |
|---|---|
next(n、または空行) |
ステップを実行し、次のステップの前で止まります |
continue(c) |
次のブレークポイントか終端まで止まらず実行します |
quit(q、exit、または入力の終端) |
ここで run を終了します。シナリオは cancelled として報告し、終了コードは 1 です。失敗で止まっているときは、失敗理由をそのまま残します |
| Ctrl-C | quit と同じく run を終了します。終了コードは 130 です(run を参照) |
tree、find、screenshot |
repl と同じく、動作中のアプリを読み取ります |
tap、type、scroll、back、step <yaml> |
repl と同じく、アプリを操作します |
アプリを操作するコマンドを 1 つでも実行すると、その run は手動操作を含むものになります。アサーションの結果にかかわらず、
シナリオは interactive: <動詞> で失敗します。<動詞> は最初に実行した操作コマンドの動詞で、result.json の interactive にも動詞だけが残ります。行の残りは、手で入力した値を含みうるため保存しません。
読み取りとステップ送りだけの run は、通常どおりアサーションで判定します。ただし、セッションのタイムアウトのように時間に反応するアプリでは、長い停止が結果を変えることがあります。interrupts の規則が実行するステップでは、プロンプトに止まりません。プロンプトには stdin と stderr が端末である
ことが必要なため、パイプや CI での実行は終了コード 2 で拒否します。複数のシナリオ、--browsers のマトリックス、
1 を超える --workers も同様に拒否します。
doctor¶
実行可能ゲートと、現在画面の 規約充足度スコア(AI 非依存。configuration)。
bajutsu doctor --target <name> [--udid booted] [--backend ...] [--config ...] [--scenario <file.yaml>] [--environment-only] [--worker-config <worker.yaml>]
- まず env ゲート(
preflight.py): actuator が必要とする CLI(XCUITest ならxcrun/xcodebuild) と起動済みシミュレータを ✓/✗ チェックリストで表示します。不足があれば終了 1(直し方ヒント付きで即失敗)。 --environment-onlyはこのゲート直後で止まります。environment:セクションを表示したら、ゲート通過なら 終了 0、✗があれば終了 1 で終わり、以下の画面プローブ(iOS では、短命な XCUITest ランナーを起動するコスト) をスキップします。実機に対して環境ゲートだけを検証したい CI レーン(BE-0304)は、これでプローブ固有の 失敗要因(ランナー自体の起動の不安定さを含む)を避けられます。--scenario <file.yaml>は端末不要の capability プリフライト(BE-0024)を実行します。画面プローブの前に、選択したバックエンドが実行できない構文をシナリオが使っていないかを検査し、非対応があれば終了 1 とします。--worker-configはrunと同じ worker 能力ファイルを受け付けます。appiumのファイルを 渡すと、グリッドの platform のターゲットに対する画面プローブはグリッドで動きます。- 端末の条件があるとき、
runs:セクションに条件が作る実行を列挙します。条件とは、iOS のkind、family、model、os、Android のavdとapiLevel、web のbrowser.*です。条件はターゲットのrunsOnに 書きます。--scenarioがあればそのファイルの各シナリオについて、なければターゲット自身について、 条件が作る実行を列挙します。doctorはrunと同じ方法で--udidの プールを読み、同じ実行を作ります。そのため各行には、その実行に合う端末が並びます。
runs:
checkout:
✓ iPhone SE (3rd generation) / iOS 17 [kind: simulator]: iOS 17.5 "iPhone SE (3rd generation)" (5A3F...)
✘ iPad Pro 13-inch (M4) / iOS 17 [kind: simulator]: fails: no available device fits this run
– one run [kind: simulator]: not applicable: runsOn.ios.os ">=19" available: ...
✓ は実行と、その実行が使える端末を示します。✘ は端末がないため失敗する実行を、– は対象外
(not applicable)の記録を示します。iOS の行は、実行が使う kind と family のうちラベルに含まれない
ものを角括弧で示します。単一の kind や family は座標にならないので、family: ipad の実行は
one run [kind: simulator, family: ipad] と表示します。列挙した kind と family のリストは
座標になるので、device / ipad のようにラベルに入ります(BE-0468)。このセクションは情報の表示だけで、
終了コードを変えません。
読めるプールがないターゲットでは、宣言された実行だけを • 付きで列挙します。該当するのは、appium
グリッドのターゲット、kind と family 以外の条件を持つ実機、端末を読めないプールです。このとき片側が開いた範囲は
「one run per available major version」(利用できるメジャーバージョンごとに1回)と表示します。
--backend fake は条件を評価しないため、runs: セクションを表示しません。
- それ以外は actuator で query() し、score(elements, subject.idNamespaces) を表示します。端末の条件が
あるときは、ターゲットの最初の実行の端末(record が使う端末)をスコアの対象にします。
grade が Blocked で 1、それ以外 0。
audit¶
シナリオの 静的な決定性スコアです。doctor の規約充足度スコアの、デバイスを使わない対応物にあたります(AI 非依存。selectors、BE-0049)。シナリオファイルを読み込み(trace --explain と同様に components / data を展開)、実行せずに、各シナリオがどれだけ再現可能かを報告します。
bajutsu audit <scenario.yaml> [--json]
- 各セレクタを安定度ラダー(selectors)で採点します。一意な
id/idMatchesは stable、label/labelMatches/traits/valueは moderate(id を伴わない補助的指定)、index(複数一致の n 番目)は fragile です。加えて、座標ジェスチャ(swipe {from,to}。安定した id で置き換えられる)と緩すぎる wait(until: screenChanged/settled。具体的な条件を待たない)も指摘します。さらに、すべての固定の待機(sleep。理由も示す)を指摘します。1 つのシナリオで固定の待機の合計が 10 秒を超えるとModerateと評価します。 - シナリオごとに
grade(Stable/Moderate/Fragile)、安定度の割合、位置付きの findings を出力します。テキスト、または--jsonで機械可読に出せます。 - 助言的かつ read-only です。シナリオを実行も編集もせず、CI ゲートにもなりません。成功した監査は finding があっても終了 0(シナリオファイルが無い/読めないときだけ終了 2)です。finding は直すべき箇所であって判定ではありません。flake を隠す retry-to-pass の逆の発想です。
静的な採点に加えて、観測によって決定性を示すモードが2つあります。
bajutsu audit <scenario.yaml> --repeat K --target <name> # K 回実行して結果を差分する(run と同じく --worker-config を受け付ける)
bajutsu audit --history <runs-dir> # 過去の run からフレーキネスを掘り起こす
--repeat Kは同一の前提条件でシナリオをK回実行し、結果が変動したものを報告します(deterministicかflakyか)。変動は直すべき finding であって、赤を緑に変える retry ではありません。--history <runs-dir>は経時ビューです。各シナリオの蓄積した run を、その run のシナリオフィンガープリント(各manifest.jsonが持つprovenance.scenarioHash)でグルーピングし、シナリオごとに分類します(flaky/deterministic/unproven)。フィンガープリントが一定のまま verdict がブレていれば、それは真のフレーキネスです。シナリオを編集するとハッシュが変わって新しいグループになるため、編集とは区別されます。フィンガープリントに加えてシナリオ名でもキーを引くので、スイートのどのシナリオがブレたのかまで特定できます。フィンガープリントを持たない run(provenance 導入前)はグルーピングできず、skip として報告します。他のモードと同様 read-only で、フレーキネスを検出しても終了 0(runs ディレクトリが無いときだけ終了 2)です。- 履歴は OS バージョンごとに分かれます(BE-0358)。グループのキーには、その run が動いたデバイスの OS バージョンも入ります。値は、各
manifest.jsonがシナリオごとに記録しているdevice_runtimeのラベルを解析したものです。1 つのシナリオを iOS 18.6 と iOS 26.5 で走らせれば、履歴は 2 つに分かれます。それぞれが自分の証跡だけで分類されるので、バージョンが違うから判定が違う場合に報告されるのは、フレーキネスではなく、その OS 上で再現する差異です。同じバージョンの 2 通りの綴り(iOS 18.6とiOS 18.6.1)は同じ OS として扱うため、パッチリリースをまたいで履歴が割れることはありません。ラベルのない run や解釈できない run(web の run と、ラベルを読む前に記録された run)は、どのバージョンの履歴とも合流せず、unknown OSとしてまとまります。出力は、その履歴が何件あるかを述べます。
coverage¶
スイートの 静的な e2e カバレッジマップです。doctor の規約充足度スコアの、read-only な対応物にあたります(AI 非依存。BE-0050)。doctor が1画面の提供する id を採点するのに対し、こちらはスイート全体が行使する id を採点します。アプリの設定済み paths.scenarios ディレクトリの *.yaml をすべて読み込み(components / data を展開)、参照している安定した id を namespace ごとにまとめ、アプリが宣言した subject.idNamespaces(configuration)に対して、実行せずに突き合わせます。
bajutsu coverage --target <name> [--config ...] [--runs <dir>] [--crawl <screenmap>] [--json] [--html <path>]
- カバレッジの割合(スイートが参照する宣言済み namespace 数 / 宣言済み namespace 数)、各 namespace に触れる namespace ごとの id、gap 一覧(どのシナリオも参照しない宣言済み namespace。すなわち未テストの範囲)、off-namespace な id(参照されているが宣言されていない namespace の id)を報告します。テキスト、または
--jsonで機械可読に出せます。 - 参照している id とは、シナリオが指定する
id/idMatchesのすべてです。ステップ、入れ子の制御フロー、withinスコープ、アサーションを横断して集めます。run が後から束縛するプレースホルダは含みません。components(params.*)とデータ行(row.*)はマップを組み立てる前に展開されており、展開後に残る${vars.*}や${secrets.*}のトークンはどの要素も指していないので、マップはトークンの文字列を id として数えず対象から外します。 --runs <dir>を渡すと、run の証跡に基づく次元が2つ加わります。- エンドポイントカバレッジ: runs ディレクトリ配下のすべての
network.json(観測した通信の和集合)を読み、観測したエンドポイント(METHOD path)のうちスイートのネットワークアサーション(request/event/requestSequence)がカバーしている割合を測ります。アサート済みの割合、未アサートの観測エンドポイント(スイートが一度もアサートしないトラフィック)、どの run でも観測されなかった宣言マッチャを報告します。 - 観測 id カバレッジ: runs ディレクトリ配下のステップごとの
elements.jsonをすべて読み、run が実際に描画した安定 id(各要素のidentifier。null や空文字の id は除く)を集め、宣言済みの namespace ごとにまとめます。静的な id マップに対する、run の証跡側の対応物です。namespace ごとの観測 id、どの run でも描画されなかった namespace、宣言されていない namespace に属する観測 id(off-namespace)を報告します。
--runs を省くと従来どおり静的な id-namespace マップのみです。
- --crawl <screenmap>(--runs と併用)を渡すと、自律クロールが発見した面に対する screens-visited
次元が加わります(BE-0038)。
分母はクロールが見つけた画面(screenmap.json のノード。ファイルでもその run ディレクトリでも渡せます)、
分子は run セットが到達した画面です。ステップごとの elements.json を同じ crawl.fingerprint で
指紋化するので、訪問した画面が発見した画面と突き合わせられます。到達した割合と、クロールは発見したのに
どの run も触れなかった unvisited な画面を報告します。訪問の証跡には --runs が必要で、--crawl だけを
渡した場合はこの次元を警告つきでスキップします。
- --html <path> を渡すと、同じ数値を 自己完結した HTML レポートにも書き出します(CSS は埋め込み、JavaScript も外部アセットも無し。ディスクから直接開けます)。次元ごとにカバレッジバーを描き、gap、off-namespace、unvisited の一覧を目立たせます。エンドポイント、観測 id、screens-visited のセクションは --runs(screens は加えて --crawl)を渡したときだけ描画します。テキスト(または --json)の出力は変わらず、書き出し先は標準エラー出力で知らせます。
- 助言的かつ read-only です。シナリオを実行も編集もせず、CI ゲートにもなりません。gap があっても終了 0(config / scenarios ディレクトリが無い、またはシナリオが読めないときだけ終了 2)です。gap は埋めるべき namespace であって判定ではありません。
impact¶
テスト影響分析です。ソースの変更から、その変更がどのシナリオステップに影響しうるかを報告します(AI 非依存。BE-0321)。coverage の逆にあたります。coverage がスイートを前向きに辿って行使するアプリ面を見るのに対し、impact は同じ静的解析を反転し、各安定した id、画面、アサート対象のエンドポイントから、それを参照する (scenario, step) の組への対応表を作ります。そのうえで変更を git の diff として読み、開発者が見直すべきステップを報告します。開発者は push 前に危険なステップだけを把握でき、CI パイプラインは素早いフィードバックのためにそれらを先に流せます。
bajutsu impact --target <name> [--config ...] [--range HEAD~1..HEAD] [--diff <path>|-] [--repo <dir>] [--json]
- 変更は
gitの diff です。--rangeは diff を取るリビジョン範囲を指定します(既定のHEADは作業ツリーをHEADと比較します)。--repoは対象のリポジトリを選びます(既定は現在のディレクトリ)。あるいは--diff <path>はファイルから、--diff -は標準入力から unified diff を読みます。すでに diff を持っている CI パイプラインが渡す形です。作業ツリーモード(..を含まない範囲)では、追跡されていない新規ファイルも取り込みます。参照する id を求めて読み込み、バイナリなら帰属不能として印を付けるので、新しい画面が黙って見落とされません。 - 一致は単純な文字列検索です。 スイートがすでに宣言している安定した id(および画面名やエンドポイントのパス)を対象に、その id のリテラルが diff の追加行または削除行に現れれば、その id は触れられたとみなします。言語ごとの構文解析を必要とせず、アプリ固有の知識も埋め込まないので、Swift でも Kotlin でも TypeScript でも同じように働きます。
- 影響を受ける
(scenario, step)の組を、それを引き当てた触れられたリテラルとともに(どのステップかだけでなくなぜかがわかるように)、テキスト、または CI が消費する--jsonで報告します。 - 健全性には限界があり、その限界を隠さず示します。 走査が保証できない変更は帰属不能です。参照されるリテラルを一つも編集しない変更(ハンドラのロジックや共有ヘルパーなど)と、文字列一致では中身を見られない変更(バイナリファイル)です。変更がそうした部分を含むとき、レポートは不完全と印を付け、帰属不能なファイルを列挙します。CI で絞り込むなら、このシグナルを受けてフルスイートへ退避しなければなりません(
--jsonのcompleteがfalseになります)。過剰選択が安全な方向です。短い id や一般的な id は影響集合を広げうるものの、影響を受けるステップが黙って飛ばされることはありません。 - CI での安全な使い方。 影響集合は仕組みであり、方針はチームが選びます。安全な既定は加算的です。スイート全体は流したまま、影響を受けるステップを先に並べる、あるいは人にフラグとして示します。マージ前の run を影響集合まで絞り込むのは opt-in で、健全なのは2つの安全策があるときに限ります。上記の保守的な退避と、フルスイートの安全 cadence(決定的なスイート全体を、main ブランチへのマージ時、夜間、あるいはリリース時に依然として流すこと)です。これにより、走査が取りこぼしたステップも出荷前に捕まえられます。いずれの場合も合否の判定は決定的なランナーに残ります。
- 助言的かつ read-only です。シナリオを実行も編集もせず、CI ゲートにもなりません。影響集合が何であっても終了 0(config / scenarios ディレクトリが無い、シナリオが読めない、または
git/ diff の読み取りに失敗したときだけ終了 2)です。どの段階でもモデルは使いません。
stats¶
複数の run を横断した傾向を示す、集計 run 統計ダッシュボードです。run ごとの report.html を補完します(AI 非依存。BE-0102)。coverage が「どの面をテストしているか」に、audit が「シナリオは再現可能か」に答えるのに対し、stats は「スイート全体は時間とともにどう推移しているか」に答えます。あるディレクトリ配下のすべての run の manifest.json を集計します。デバイスも AI も判定も使いません。
bajutsu stats --runs <dir> [--json] [--html <path>]
--runs <dir>は集計する過去の run のディレクトリで、各 run のmanifest.jsonを読み込みます(読めない、または壊れたものはスキップします)。ディレクトリが無いときは終了 2 です。- テキスト、または
--jsonで機械可読に、次を報告します。 - 合格率の推移: 全体と日別です(日付は run id のタイムスタンプ接頭辞から取り出します。独自ラベルの run id には日付が無く、
(no date)にまとめます)。 - 所要時間 / 性能: セット全体の合計実時間(各 run の所要時間はそのシナリオの
duration_sを合算したもの)と、平均所要時間で並べた遅いシナリオです。 - 失敗ホットスポット: 最も多く失敗するシナリオ、ステップ(
scenario > action)、アサーション種別を、それぞれ最頻の失敗理由とともに示します。 - flakiness: 各シナリオの分類(
flaky/deterministic/unproven)を、BE-0049 の longitudinal 監査から再利用して取り込みます。 - volume: backend ごとの run 数で、合格率を読む際の分母になります。
- シナリオの系列は BE-0049 の
(scenarioHash, name)という同一性に、その run が動いたデバイスの OS バージョンを加えて束ねます(BE-0358)。1 つの OS 上で指紋が一定のまま判定が反転すれば、真の flaky です。シナリオを編集するか、同じシナリオを別の OS バージョンで走らせれば、新しい系列が始まります。各系列は自分の OS を明示し、所要時間もその系列の中で平均します。2 つの OS バージョンの計測値が、どちらも実際には走っていない 1 つの平均に混ざることはありません。provenance.scenarioHashを持たない run は run レベルの傾向には数えますが、シナリオの系列には加われません(スキップとして報告します)。 --html <path>を渡すと、同じ数値を自己完結した HTML ダッシュボードにも書き出します(CSS は埋め込み、推移は最小限のインライン SVG。JavaScript も外部アセットも無く、ディスクから直接開けます)。テキスト(または--json)の出力は変わらず、書き出し先は標準エラー出力で知らせます。- 助言的かつ read-only です。シナリオを再実行せず、判定を再計算せず、CI ゲートにもなりません。新しいフィールドを欠く古い manifest は「未取得」として描画し、失敗としては扱いません。数値にチームが設けるしきい値は、そのチーム自身の参考用チェックです。
flakiness¶
run 履歴を横断してシナリオをフレーキネス順に並べる、ランク付きのフレーキシナリオ一覧です。audit --history を実際に活かせる形にした対応物にあたります(AI 非依存。BE-0220)。audit --history が各シナリオを flaky / deterministic / unproven に分類するのに対し、flakiness はスイート全体を flaky を先頭に並べ、それぞれがどれだけブレるかを採点します。チームは最も問題のあるシナリオを一目で把握できます。デバイスも AI も判定も使いません。
bajutsu flakiness --history <runs-dir> [--json] [--window N] # run manifest のディレクトリを掘り起こす
bajutsu flakiness [--org <org>] [--json] [--window N] # serve のデータベースを読む(BAJUTSU_DATABASE_URL)
- 入力元は二つ、ランク付けは一つです。
--history <runs-dir>は過去の run のmanifest.jsonを集めたディレクトリを掘り起こします(CI やスクリプト向けの形)。省略するとデータベース(BAJUTSU_DATABASE_URL)を読み、各 run の行に刻まれたprovenance.scenarioHashから直接グルーピングします。runs ディレクトリが無いとき、またはデータベースが未設定のときは終了 2 です。 - run は
provenance.scenarioHashでグルーピングし、各シナリオを判定の反転率(2·min(passed, failed)/runs。一貫していれば 0、五分五分で 1)で採点します。分類は BE-0049 から再利用します。出力は flaky を先頭に、次いで反転率の降順、さらに run 数の降順で並びます。 - グループ化は OS バージョン単位でもあります。 規則は
audit --historyと同じです(BE-0358)。デバイスのマトリックスで 1 つのスイートを走らせる fleet が、そこにある本物の OS 差をフレーキネスとして採点することは、もうありません。この面が束ねる単位は run です(audit --historyはシナリオ単位です)。そのため、複数の OS バージョンにまたがった run はどのバージョンも代表できず、解釈できないラベルと同じunknown OSのグループに入ります。データベースを読むときの OS は、各 run の行が持つ列から得ます。その列より早く記録された run は、serveのパネルがランク付けするたびに、その run の manifest からメモリ上で修復します。データベースには書き戻しません。読み取り経路での書き込みは、運用者が消去した run を挿入し直しかねないためです。manifest が失われている行はunknown OSのまま残し、レポートがその件数を開示します。 - グループ化は、ターゲットと run の座標の単位でもあります(BE-0452)。デバイスの条件がシナリオを複数の run に分けるとき(並べたモデルごとの run など)は、各 run の座標がキーに加わります。そのため、1 つのモデルだけで起きるレイアウトの失敗が、フレーキーなシナリオとして読まれることはありません。ターゲットもキーに加わるので、2 つのターゲットで動かしたシナリオは 2 つの履歴を持ちます。テキストの出力は、OS の後ろに座標を角括弧で示します。条件のない run の座標は空のままなので、BE-0452 より前に記録した履歴はそのまま続きます。1 回の実行は、条件が作ったすべての run を 1 つの run ID で記録するので、結果が 2 つ以上の座標にまたがることがあります。そのような run は
*としてまとめ、ほかのどの履歴とも合流させません。 - 各エントリは最新の合格 run と最新の失敗 run の id を持ちます。
--jsonの利用側や serve パネルは、両側の代表的な証跡へ直接リンクできます。 --window Nは採点前に、各履歴の最新 N run だけを残します。採点する単位が履歴(シナリオ、OS バージョン、ターゲット、run の座標の組)なので、残す単位もそれに揃えます(既定の 0 は履歴全体です)。シナリオ単位で残すと、最新の run がすべて新しい OS に移った時点で古い OS の履歴が落ち、この grouping が浮かび上がらせるはずのバージョン間の所見が隠れます。--org <org>はデータベースを読むときに掘り起こす対象のテナントを選びます。provenance.scenarioHashを持たない run(provenance 導入前)や、判定が記録されていない run はグルーピングできず、audit --historyと同様にスキップとして報告します。- 助言的かつ read-only です。履歴にすでに記録されたフレーキネスを報告するだけで、何も再実行せず、判定を再計算せず、CI ゲートにもなりません。
export¶
完了した run を1つの可搬な .zip にまとめます。report.html に加えて manifest.json、junit.xml、ctrf.json(reporting)、実行した scenario.yaml、すべての証跡(スクリーンショット、動画、network.json …)を含みます(BE-0060)。runs/<id>/ のツリー全体を単一の <id>/ フォルダ直下に収めるので、report.html の相対リンクがオフラインで解決します。ダブルクリックで開け、サーバは要りません。
bajutsu export <run-id | run-dir> [-o out.zip] [--force]
<run>は run id(--runs既定runs/の下で解決)または run ディレクトリのパスです。- 出力は既定で run dir の隣の
<id>.zip。-o/--outputで上書き指定。--forceなしでは既存ファイルを上書きしません(recordが黙って上書きしないのと同じ)。 - run が既に書いたものを詰めるだけで、デバイスも AI も使わず、判定にも影響しません。run dir の中だけを固めます(
.env、config、その上位には一切触れません)。run の secret スクラブをそのまま継承します。bajutsu run --zipは同じアーカイバを判定後にインラインで走らせ、bajutsu serveは埋め込みレポートの隣に Download ボタンとして提供します。
trace¶
完了した run をテキストタイムラインで検査します。シナリオごとに、ステップと観測した通信を
時系列で交互に並べ、続けて expectations、app-trace 区間、証跡サマリを出力します。読み取り専用
(保存済みの manifest.json / network.json / appTrace.json、来歴のための scenario.yaml を読む)。
- 各ステップには、それを記録した元の自然言語フレーズ(
from:来歴、BE-0044)を← "<フレーズ>"の形でインライン表示します。1 つのフレーズを共有する連続ステップはまとめて 1 回だけ ラベル表示します。手書きのシナリオや来歴のない古い run では、単に何も表示されません。
bajutsu trace [<run-dir>] [--scenario <substr>] [--runs runs]
bajutsu trace --explain <scenario.yaml> # 実行前のドライラン(デバイス不要)
<run-dir>省略時はruns/直下の最新 run。--scenarioは名前の部分一致で絞り込み。- run が見つからなければ終了 2。
--explain <scenario.yaml>は実行前版です。完了した run を読むのではなく、そのシナリオのcapturePolicyがどう発火するかを事前に表示します(BE-0028)。action トリガのルールは正確に回数を 数えて該当ステップを列挙し、event/resultルールは実行時依存として報告します。広くマッチする ルールに heavy capture(video/deviceLog/appTrace/network)が付いていれば ⚠ で警告し、 コストを払う前にマッチを絞り込めます。読み取り専用かつ決定的で、デバイスも LLM も不要です (components と data 行は展開しますが、ターゲットのhooks.setupは含みません)。シナリオファイルが 無ければ終了 2。
report¶
完了した run の report.html を保存済みデータから、現行のテンプレで再描画します(junit.xml と ctrf.json〈reporting〉も再出力)。デバイスも LLM も使わず、再実行もしません(BE-0068)。テンプレ改善やレンダリングのバグ修正が、再実行せずに過去の run にも届きます。合否は保存済みモデルから読むだけで、再計算しません。
bajutsu report <run-id | run-dir> # 1 つの run を再描画
bajutsu report --all [--runs runs] # runs/ 配下で manifest.json を持つ run dir をすべて再描画
- レンダリングモデルは
manifest.json(バージョン付きで無損失の render 入力。schemaVersion)と、実行したscenario.yamlです。レンダラは run dir だけを読みます。古い run もエラーにならず描画でき、新しいバージョンにしかないセクションは値を捏造せず「not captured」と表示します。 - 記録済みの outcome を再提示するだけで、assertion を再評価したり verdict を変えたりしません。決定性の契約の内側に収まります。
serveも同じレンダラを表示時に使い、リクエストごとに各 run の保存済みモデルからreport.htmlを都度描画します(モデルを読めない場合は baked ファイルにフォールバック)。これによりserveを上げれば再 bake 不要で全レポートが最新化されます。 - run(
--allの場合は runs ルート)に読めるmanifest.jsonが無ければ終了 2。
triage¶
run 内の最初の失敗シナリオを診断し、最小の修正案を提示します。助言のみで pass/fail は判定しません
(AI 境界)。失敗コンテキスト(落ちたステップと理由、失敗 expectation、失敗時の要素ツリー、シナリオ)
を組み立て TriageAgent に渡します。既定はルールベース(HeuristicTriageAgent、API キー不要)で、失敗を
分類(selector / timing / assertion)し、対象 id が画面に無く似た id があれば「もしかして…?」を提案
します(id リネームの自己修復)。--ai は同じコンテキストに失敗スクリーンショットを加えて推論する Claude 版に差し替えます
(ANTHROPIC_API_KEY が必要)。
エージェントは適用可能な構造化 fix(renameId / addIndex 曖昧一致の一意化 / raiseTimeout)も
返せます。--apply <scenario-file> が dry-run diff を表示、--write が source に適用、--rerun --target
<name> が patched シナリオを再実行(--no-erase)して緑になったか報告します。境界は保たれます: fix はユーザーが
diff をレビューして opt-in した時のみ適用され、断片が source に一致しなければ安全に no-op です。
bajutsu triage [<run-dir>] [--scenario <substr>] [--runs runs] [--ai]
bajutsu triage [<run-dir>] --ai --apply <scenario-file> [--write] \
[--rerun --target <name> [--backend ios] [--udid <udid>]]
- 既定は
runs/直下の最新 run。失敗シナリオが無ければ終了 0。 --rerunは--writeと--targetが必要。--aiのときは、診断後に消費トークン量を示すAI usage:行を stderr に出力します。既定のルール ベースは AI を使わないので何も出力しません。--json <path>は診断結果を JSON でも書き出します(category、summary、suggestions、構造化された 修正)。--applyと併用すると、その修正の unified diff とパッチ適用後のテキストも含めます。--json自体はその JSON ファイルを書くだけで、シナリオのソースには触れません。ソースへのパッチ適用には従来 どおり--writeが必要です。serveの Web UI は、triage をブラウザに出すためにこの--jsonを 使います(BE-0147)。
Run 横断のフラッキートリアージ(--flaky)¶
既定の triage がある 1 つの失敗 run を説明するのに対し、--flaky はパターンを説明します。すなわち、
コンテンツのフィンガープリントが変わっていないのに、1 つのシナリオがなぜ間欠的に成功したり失敗したりするのか
を診断します(BE-0220)。
これは flakiness の修正提案版にあたります。flakiness がどのシナリオがブレるかを順位付けするのに対し、
--flaky はそのうちの 1 つがなぜブレるのかを診断して修正を提案します。対象シナリオの成功 run と失敗 run の
両方の証跡を読み、両者の差分を推論します(ある run では解決したのに別の run では曖昧だったセレクタ、
多くの場合スピナーに勝った wait、内容が揺れたネットワーク応答など)。
bajutsu triage --flaky --scenario <name> --history <runs-dir> --ai [--apply <file> [--write]] [--json <path>]
--aiが必須です。 Run 横断の診断にはルールベースのエージェントがありません。差分の推論は、まさに LLM が担う判断抜きの調査役の仕事だからです。そのため--aiを付けない--flakyは終了 2 になります。 あくまで助言的で、判定は run がすでに下しており、これは説明と提案だけを行い、判定経路には乗りません (第一原則 1)。--scenario <name>がフラッキーなシナリオを選び(run のシナリオ名の部分一致で拾い、1 つの厳密な名前に 解決するので、部分文字列を共有する 2 つのシナリオが混ざりません)、--history <runs-dir>は対比する過去の run(それぞれmanifest.jsonを持つ)のディレクトリです。bajutsu flakiness --historyやaudit --historyが読むものと同じディレクトリ形です。どちらも必須で、欠けると終了 2 になります。- レポートは、成功 / 失敗 run の件数、フィンガープリント、間欠性のカテゴリ(
selector-ambiguity/timing/network-variance/state-leak/unknown)、そして提案された修正を、現在のシナリオに対する レビュー可能な差分として表示します。単独で適用されることはありません。 - 単一 run の triage と同じ構造化 fix とフラグを再利用します。
--apply/--writeがシナリオにパッチを 当て、--jsonが機械可読の結果を書き出します。アサーションを弱める編集は、両方の提示面で inline に 甘くする(laxer)フラグが付きます(BE-0023)。 YAML 全体の書き直しはフォローアップに送っており、現在の fix は的を絞った構造化編集です。 - 履歴に失敗 run または成功 run のどちらかが無いとき(対比する相手がなく、フラッキーとして診断する対象が 無いとき)は終了 0 です。他の読み取り専用モードと同じく助言的です。
record¶
AI でゴールに向けて探索し、記録したシナリオを書き出します(Tier 1、recording)。
既定ではアプリの設定済みシナリオディレクトリ(targets.<name>.paths.scenarios)配下に自動命名の *.yaml を書きます。
特定パスに書くには --out を渡してください。
bajutsu record --target <name> --goal "<自然言語ゴール>" [--out <file.yaml>] [options]
| オプション | 既定 | 説明 |
|---|---|---|
--target |
(必須) | 対象アプリ |
--goal |
(必須) | 著すゴール(自然言語) |
--out |
config の paths.scenarios 配下に自動命名 |
出力パスを明示(アプリのシナリオディレクトリを上書き) |
--name |
(ゴールから) | 自動命名するファイル名(--out 指定時は無視) |
--udid |
booted |
対象 Simulator |
--backend |
ターゲットの platform |
ターゲットの platform に対する検査(共通を参照) |
--erase / --no-erase |
--erase |
起動前に erase(アプリはインストール済みである必要)。--erase は実効の subject.reinstall を erase に引き上げ、--no-erase は erase を clean に下げます。そのため、ここではターゲットの subject.reinstall: erase で wipe するかどうかは決まりません |
--system-alert-handling / --no-system-alert-handling |
on | オーサリング中のプロンプトを片付ける(要 API キー) |
--max-steps |
30 |
オーサリングのターン数(=トークン消費の上限)に上限を設けます(BE-0194) |
--screenshot / --no-screenshot |
--screenshot |
毎ターン、スクリーンショットを送ります。--no-screenshot は要素情報だけを記録し(コストが安い)、id を十分に備えたアプリ向けです(BE-0194) |
--headed / --no-headed |
ターゲットの driver.headless |
web backend: ヘッドレスではなく目に見える(低速再生の)ブラウザでオーサリングします。省略時はターゲットの driver.headless 設定に従います |
--browser |
ターゲットの runsOn.browser.kind(既定 chromium) |
web backend: オーサリングに使うブラウザ。chromium / chrome / edge / firefox / webkit から選びます。省略時はターゲットの runsOn.browser.kind config に従います。ブラウザをリストで宣言したターゲットでは、リストにないブラウザを指定すると終了コード 2 で終わります |
--kind |
ターゲットの runsOn.ios.kind の最初の種類 |
iOS: オーサリングに使う種類を1つ指定します(simulator または device)。ターゲットが宣言していない種類を指定すると終了コード 2 で終わります。このコマンドは1回しか実行しないので、カンマ区切りのリストを指定しても終了コード 2 で終わります(BE-0468) |
--alert-vision-instruction |
"" | プロンプトを片付ける代わりに視覚ガードが読む自由記述 |
--language |
config の ai.language(auto) |
著すプローズ(from: 由来、推論)の AI 出力言語。ja / en / auto から選び ai.language を上書きします。auto はゴールに追従します(BE-0188) |
--config |
bajutsu.config.yaml |
config |
--worker-config |
同梱のデフォルト | run と同じ worker 能力ファイル。appium のファイルを渡すと、グリッドの platform のターゲットをグリッド上でオーサリングします |
- 内部の流れ:
launch_driverの結果をrecord_loop(driver, goal, ClaudeAgent(), ...)に渡し、record_loopの結果をdump_scenariosで書き出す流れ。 - 出力:
recorded <N> steps -> <path>。要ANTHROPIC_API_KEY(ClaudeAgent)。 - Git の
--configは読み取り専用入力です(BE-0063)。recordは config を取得したチェックアウトから読みますが、生成したシナリオはローカルへ書きます。--out省略時は(読み取り専用の SHA キーのキャッシュであるチェックアウト内のpaths.scenariosディレクトリではなく)カレントディレクトリに自動命名し、チェックアウト内を指す--outは拒否します。そのファイルをレビューし、通常の git でリポジトリへコミットしてください。 - 続けて、オーサリング(およびアラートガード)の AI が消費したトークン量を示す
AI usage:行を stderr に出力します。
crawl¶
アプリを幅優先で探索し、到達できる画面と画面間の遷移の画面マップを書き出します
(Tier 1、BE-0038)。record は 目的指向 で、1 つの自然言語ゴールに
向かって AI が探索し、1 本のシナリオを書き出します。これに対し crawl は 体系的な発見 です。
到達できる画面を巡り、見つけたものを報告します。探索エンジンは決定的で(画面の識別子と候補
アクションを試す順序は、どちらも要素ツリーの純粋な関数です)、AI は関与せず、合否ゲートには
決してなりません。
bajutsu crawl --target <name> [--max-screens N] [--max-steps N] [--out <dir>] [options]
| オプション | 既定 | 説明 |
|---|---|---|
--target |
(必須) | 対象アプリ |
--max-screens |
50 |
この数の異なる画面を発見したら停止 |
--max-steps |
200 |
この数のアクションを実行したら停止 |
--prune-global / --no-prune-global |
ON | 複数の画面で使われる共通コントロール(タブ / ナビゲーションなど)を、それを表示するすべての画面からではなく1回だけ探索します。Web UI からは pruned なブランチを後から resume できます(--resume-src/--resume-key 参照) |
--udid |
booted |
対象 Simulator。カンマ区切り(A,B,C)で並列プールも指定できる(--workers 参照) |
--workers |
1 |
同時に動かすワーカー数。1 つの画面マップを共有する。iOS は同数のシミュレータ(BE-0064、--udid のデバイス数で上限)、web は同数のブラウザプロセス(BE-0077)。1 はシングルワーカーのクロール |
--backend |
ターゲットの platform |
ターゲットの platform に対する検査(共通を参照) |
--erase / --no-erase |
--erase |
起動前に erase(アプリはインストール済みである必要)。--erase は実効の subject.reinstall を erase に引き上げ、--no-erase は erase を clean に下げます。そのため、ここではターゲットの subject.reinstall: erase で wipe するかどうかは決まりません |
--system-alert-handling / --no-system-alert-handling |
on | クロール中に予期せぬ OS プロンプトを片付ける(クラッシュ誤判定を防ぐ。設定した AI プロバイダを使用し、ANTHROPIC_API_KEY、Bedrock なら AWS 認証情報) |
--alert-vision-instruction |
"" | プロンプトを片付ける代わりに視覚ガードが読む自由記述 |
--headed / --no-headed |
ターゲットの driver.headless |
web backend: ヘッドレスではなく目に見える(低速再生の)ブラウザでクロールする。省略時はターゲットの driver.headless 設定に従う |
--kind |
ターゲットの runsOn.ios.kind の最初の種類 |
iOS: クロールに使う種類を1つ指定します(simulator または device)。ターゲットが宣言していない種類を指定すると終了コード 2 で終わります。このコマンドは1回しか実行しないので、カンマ区切りのリストを指定しても終了コード 2 で終わります(BE-0468) |
--language |
config の ai.language(auto) |
ガイドの流れる推論の AI 出力言語。ja / en / auto から選び ai.language を上書きします。auto はクロールでは英語のままです(BE-0188) |
--out |
runs/<timestamp> |
画面マップを書き出す run ディレクトリ |
--resume-src / --resume-key |
"" | Web UI の「tap to resume」が指す、pruned な1ブランチだけを resume します。--resume-src は pruned にした画面の fingerprint、--resume-key はその replay key で、どちらも既存の run を指す --out と組み合わせます。--continue とは同時に指定できません |
--continue |
オフ | 過去の run(--out でその run を指します)を続きから探索します。1 つのブランチだけでなく、未試行の操作が残るすべての画面を再探索します。--max-screens/--max-steps を上げるとさらに深く進み、--workers/--udid で continuation を並列に実行します(BE-0181)。--resume-src/--resume-key とは同時に指定できません |
--config |
bajutsu.config.yaml |
config |
--worker-config |
同梱のデフォルト | run と同じ worker 能力ファイル。appium のファイルを渡すと、グリッドの platform のターゲットをグリッド上でクロールします |
- Git の
--configは読み取り専用入力です(BE-0063)。crawlは config を取得したチェックアウトから読みますが、画面マップ/スクリーンショットはローカルの--outrun ディレクトリ(既定runs/<timestamp>)に書き、読み取り専用の SHA キーのキャッシュには書きません。チェックアウト内を指す--outは拒否します。 - 走査は決定的リプレイで行い、その場での後戻りはしません。既知の画面を再訪するには、アプリを
クリーンな状態に再起動し、そこへの最短経路を再生してから次の未試行アクションを取ります。これは
runが任意の状態へ到達するのと同じやり方です。 - 過去のクロールの続きから探索する(BE-0181)。
クロールは
completedよりも--max-screens/--max-stepsで止まることのほうがはるかに多いので、bajutsu crawl --out <既存の run> --continueはその run の画面マップを引き継ぎ、未試行の操作が残る すべての画面、つまり残りのフロンティア全体を再探索します。予算を増やしてエントリー画面からクロール し直すのとは異なります。追加の永続状態は要りません。各画面の記録済み経路(paths)を再生し、まだ試して いない操作を決定的なガイド(candidate_actions)で導出し直し、保存済みのplanと突き合わせます。 再構築は決定的なので、決定的に導出できる操作だけを再構築します。AI-only の操作は意図的に再構築しません。 AI ガイドの run では、モデルが提案した豊かな操作(現実的なfill/type、視覚で特定したtap_point)は 再シードされず、決定的なタップや入力だけが対象です。何も再構築できなかったフロンティアは、completedとは報告せず手を付けないまま残します(保存済みマップのplanと停止理由をそのまま保ちます)。--max-screens/--max-stepsを上げるとさらに深く進み、--workers/--udidは通常のクロールと同じ並列 プールで continuation を実行します。これは Web UI の pruned ブランチの「タップして再開」が起動する単一 ブランチの resume(名前付きの pruned 操作 1 つを再探索します)とは別物で、--continueとその resume は 同時には指定できません。 - 無効化された操作要素(
notEnabled)はタップせず、画面ごとにblockedとして報告します。遷移を洗い出すため、 crawl は操作要素の状態の組合せを探索します。各空テキスト欄を個別に入力し(スイッチは個別にトグル、タブバーは各タブに切り替え)、 空欄が複数あるときは一括入力(compound fill)も試します。一括入力が重要なのは、操作要素が 複数 の欄が 揃って初めて有効化される場合があり、かつ途中の単独入力が不可視(マスクされたパスワードは値を公開しない)な ことが多く、1つずつ埋めても全充足状態へ到達できないためです。クロールは AI 駆動です。 まず画面を決定的に検査し、その操作を Claude に渡して組合せを 考えさせ、有効化条件が自明でない操作要素のために現実的な入力(正しいメール形式、規約を満たすパスワード、 フォーム全欄の一括入力など)や id 無し要素への操作を提案し、その推論を run ログに流します。 AI は個々のタブをツリーで指定できないタブバーにも対応します。iOS のアクセシビリティツリーは SwiftUI の TabView を 「Tab Bar」というラベルの group 1個(タブごとの id 無し)として返すことがあり、その場合はバーは見えてもタブをセレクタで タップできません。そうしたバーがあり(かつ id で指定できるタブが無い)場合に、システムアラートガードと同じ要領で 画像認識(vision)から位置を割り出し、各タブを座標でタップします(タブを優先して切り替えてから先の画面へ進む方針は同じ)。 (UIKit のタブバー、つまりアクセシビリティツリーが各タブを個別要素として返すものは今後の対応予定で、現状は同じ vision 経路にフォールバックします。) AI は「何を試すか」を選ぶだけで、画面同一性、遷移、クラッシュ判定は決定的のままです。よって crawl は合否を下さず、 CI ゲートにもなりません。 - 出力:
<out>/screenmap.json。nodes(画面。fingerprint、種別、id、候補アクション、blocked無効操作要素を持つ)、edges(遷移)、crashes(アプリ UI を崩壊させたアクション経路)、alerts(クロール中にガードが閉じた OS プロンプト。誘発した経路とタップしたボタンを記録する)、plan(探索フロンティア。画面ごとの未試行操作で、クロールの 進行に合わせて更新されるので、読み手は次に何を試すか把握できます)、stop_reason(completed/max_screens/max_steps)からなる JSON グラフです。あわせて<out>/screens/<fingerprint>.png、すなわち発見した各画面の スクリーンショット(その画面にいる間に撮影)も出力します。クロールの進行に合わせて書き直されるので、読み手 (serveの Crawl タブ)はマップをリアルタイムに描けます。各画面はラベルと情報のノードで表示され、同じ UI で 状態だけ違う画面(フォーム未入力と入力済みなど)は 1 つのノードにまとめられ、その場で展開できます。--max-screens/--max-stepsのいずれか早い方で停止します。 - 完了時には
<out>/screenmap.htmlも書き出します。これは自己完結したレポート(CSS は埋め込み、JavaScript も 外部アセットも無し)で、ライブの Crawl タブのオフライン版にあたります。発見した画面を幅優先の深さ列に並べて スクリーンショットを添え、遷移を静的なインライン SVG で描き(OS アラートをタップして通過した遷移は 🛡️ マーク付きの アンバー色)、クラッシュと閉じたアラートの経路を下にまとめます。screenmap.jsonやscreens/と同じ場所に置くので run ディレクトリから直接開け、web UI なしで共有や保管ができます。JSON と同じく read-only でモデルも使いません。 - 完了時には、忠実に再現できるクラッシュごとに
<out>/crashes/crash-NNN.yamlも 1 件書き出します。これは クラッシュの記録されたアクション経路から組み立てた再現シナリオで、runがそのまま実行できます。発見した クラッシュは人間のレビューを経て、コミットされた Tier 2 のリグレッションになります。この変換は純粋かつ決定的で モデルを使いません(tap/type/fillはそれぞれ対応するステップに写像します)。正規化座標をタップする経路 (vision で位置を特定したコントロール)は指定できるセレクタを持たないため、欠損のあるシナリオを出すのではなく、 何も出力しません。 - 並列プール(BE-0064):
--udid A,B,Cのプールに--workers Nを組み合わせると、起動済みのシミュレータ N 台で同時にクロールします。 全ワーカーが 1 つの画面マップとフロンティアを共有し、独立した枝が並行して進み、AI ガイドの往復もデバイス間で 重なるので、実時間はおおよそ台数に反比例して減ります。並行になるのはスケジューリングだけです。どのワーカーが 画面に先に到達するかは時間依存なので、アプリ自体に非決定性があると記録されるパスや発見順は実行ごとに変わりえますが、 画面同一性、遷移、クラッシュ判定は要素ツリーの同じ決定的関数のままです(クロールは依然として合否を下しません)。 固まったデバイスは自分の作業を手放し、残りのワーカーが続行します。既定の--workers 1は従来どおりのシングル ワーカーのクロールです。web でも同じ仕組みが働き、シミュレータの代わりに N 個のブラウザプロセスを動かします (BE-0077)。web に端末はない のでワーカー数だけでレーン数が決まり、リセットのたびに新しいブラウザコンテキスト(クリーンな初期状態 =erase相当) を開きます。固まったブラウザは破棄して再起動するので、1 つの不調がクロール全体を沈めることはありません。
画面の同定方法(fingerprint)¶
各画面は fingerprint(再訪と新規画面を区別するための、短く安定した識別子)に還元されます。これは
要素ツリーだけから決まる純粋で決定的な関数であり(AI もスクリーンショットのピクセルも使いません)、これが画面
マップの再現性を支えます。同じ画面は常に同じ値にハッシュされます。各ノードは fingerprint とその種別(kind)を
記録します。
- id fingerprint(
kind: "id"、通常時). 画面上に存在するアクセシビリティ id の集合をソートして ハッシュします。表示テキストではなく「どの id が存在するか」を鍵にするので、ロケールやデータが変わっても同定は 安定します(行の内容が違うリストや、別言語のラベルでも同じ画面)。さらに各 id には、操作上の状態が既定から 外れているときに限ってマーカーを付けます。これにより同じレイアウトでも状態が違えば別のハッシュになり、クロールが 状態の組み合わせを探索できます。 !:無効なコントロール(notEnabled)、=:入力済みのテキスト入力(値が入ったフィールド)、+:選択 / トグルされたコントロール(ON のスイッチ、選択中のタブ)。
有効で空かつ未選択の画面は素の id だけを寄与するので、そうした状態を持たない画面は素の id 集合とまったく同じ値に
ハッシュされます。フォームを入力したりスイッチを切り替えたりすると新しいノードになるのはこのためで、これは別個に
探索できる固有の状態です。前提条件を満たして初めて使えるようになる操作(全フィールド入力後に有効化される送信
ボタンなど)を、クロールはこの仕組みで発見します。
- 構造 fingerprint(kind: "structural"、フォールバック). 画面のアクセシビリティ id が 2 つ未満で同定に
使うには薄すぎる場合、代わりに操作可能要素のトレイトを、画面上の大まかな位置でバケット化してハッシュします。
これはレイアウトの揺れで変わりうるうえ、コントロール構成が似た無関係な画面と衝突しうるため安定度が低く、識別が
近似であることを示す structural が付きます。アクセシビリティ id のカバレッジを上げる(doctor 参照)と、その
画面は安定した id 方式に戻ります。
- 表示上のグループ化は別の、見た目だけの処理です. 上記の fingerprint がマップに保存される状態ごとの厳密な
識別子です。Crawl タブはこれに加えて、同じ画面で一時的な状態だけが違うノード(未入力と入力済みのフォーム、
トグル、要素を少し足すアラート/オーバーレイ)を 1 つの展開可能なユニットにまとめ、グラフを読みやすくします。
このグループ化は fingerprint やクロールの探索内容を一切変えず、描画を畳むだけです。
web backend(--backend web)¶
クロールは Simulator に対するのと同じように web アプリにも走ります。探索エンジンはプラットフォーム非依存
なので、bajutsu crawl --target <web-app> --backend web は同じ screenmap.json、スクリーンショット、クラッシュ
一覧を出力します。web アプリは subject.id ではなく subject.url で指定し、ブラウザは Mac もエミュレータも要らない
ので、web クロールは Linux の make check / CI ゲート内で走ります。iOS と違う点は次の 3 つで、いずれも決定的
です(BE-0066)。
- クリーンな起点 = 再ナビゲート。 再起動するアプリプロセスはありません。クリーンな状態に戻すのは、新しい
ブラウザコンテキストに対する
page.goto(subject.url)(erase相当で、ほぼ無償)です。runが使うのと同じ ライフサイクルの接合点です。 - クラッシュ検出。 iOS の信号(アクセシビリティツリーの崩壊)は web には存在しないため、ブラウザ自身の
決定的な信号を使います。未捕捉の JS 例外(
pageerror)、メインフレームの 4xx/5xx ナビゲーション、空の ドキュメントの 3 つです。どれも機械的な事実(イベント、ステータス番号、空の要素集合)であり、ページが 「壊れて見えるか」をモデルが判断することはありません。 - OS アラートではなくダイアログ。 web に OS プロンプトはなく、JS ダイアログ(
alert/confirm/beforeunload)があります。これらは固定のモデル非依存ポリシー(dismiss)で自動処理し、alertsに記録します。 iOS の vision アラートガードの置き換えです。--system-alert-handlingと vision 経路は iOS 専用で、--headedは web で有効です(可視ブラウザでクロールを見られます)。
repl¶
起動中のアプリに対する手動シェルを開きます(BE-0423)。
いまの画面の要素ツリーを読み、その id の 1 つを操作し、もう一度読む、という繰り返しです。record(ゴール
指向の AI オーサリング)と crawl(自律的な探索)の隣に並び、同じ
driver インタフェースを通ってターゲットに届く 3 つ目の道です。
モデルに何ひとつ尋ねず、シナリオも書かないのは、record / crawl / repl のうち repl だけです。
ふだんなら「実行してレポートを読む」という往復を丸ごと費やす問いに、数秒で答えるために使います。
その問いとは、この画面は実際に何を公開しているのか、そしてその id は解決するのか、という 2 つです。
bajutsu repl --target <name> [options]
| オプション | 既定 | 説明 |
|---|---|---|
--target |
(必須) | 対象アプリ |
--udid |
booted |
対象 Simulator。URL は終了コード 2(Appium グリッドは --worker-config で指定します) |
--backend |
ターゲットの platform |
ターゲットの platform に対する検査(共通を参照) |
--erase / --no-erase |
live 経路以外は erase | 起動前に erase(アプリはインストール済みである必要)。--erase は実効の subject.reinstall を erase に引き上げ、--no-erase は erase を clean に下げます。そのため、ここではターゲットの subject.reinstall: erase で wipe するかどうかは決まりません。appium グリッドへの live 経路は erase を受け付けないため、その経路の既定は off になり、そこで明示的に --erase を指定すると CLI エラーで終了します |
--headed / --no-headed |
ターゲットの driver.headless |
web backend: ヘッドレスではなく目に見える(低速再生の)ブラウザを調べます。省略時はターゲットの driver.headless 設定に従います |
--browser |
ターゲットの runsOn.browser.kind(既定 chromium) |
web backend: 調べる対象のブラウザ。chromium / chrome / edge / firefox / webkit から選びます。省略時はターゲットの runsOn.browser.kind config に従います。ブラウザをリストで宣言したターゲットでは、リストにないブラウザを指定すると終了コード 2 で終わります |
--kind |
ターゲットの runsOn.ios.kind の最初の種類 |
iOS: 調べるときに使う種類を1つ指定します(simulator または device)。ターゲットが宣言していない種類を指定すると終了コード 2 で終わります。このコマンドは1回しか実行しないので、カンマ区切りのリストを指定しても終了コード 2 で終わります(BE-0468) |
--attach |
off | ローカルの iOS Simulator(xcuitest)専用です。起動済みの Simulator で動いているアプリに、そのままの状態で接続します。erase、インストール、再起動はしません(後述の「起動中のアプリへの接続」を参照) |
--config |
bajutsu.config.yaml |
config |
--worker-config |
同梱のデフォルト | run と同じ worker 能力ファイル。appium のファイルを渡すと、グリッドの platform のターゲットに対してグリッド上(live 経路)でシェルを開きます |
アプリが立ち上がると、シェルは bajutsu> のプロンプトを出します。
| コマンド | 何をするか |
|---|---|
tree |
いまの要素ツリーを id / label / traits / value / frame の表として表示します |
tree --json |
同じツリーをそのまま JSON で表示します。パイプ、差分、frame の正確な読み取りに使えます |
find <substring> |
同じツリーを、id または label が <substring> を含む行だけに絞ります(セレクタの照合と同じく、大文字と小文字を区別します) |
tap <target> |
<target> が指す要素をタップします。生の座標を指定することもできます(下の「ターゲットの指定」を参照) |
type <target> <text> |
<target> にフォーカスを当ててから <text> を入力します |
scroll @<x1>,<y1> @<x2>,<y2> |
生の座標同士のあいだで、1回だけドラッグ/スクロールのジェスチャを実行します(Driver.scroll) |
back |
1 階層戻ります。backend ごとにプラットフォームとして正しい方法を使います |
screenshot [path] |
スクリーンショットを書き出します。パスを省略するとカレントディレクトリに repl-<UTC タイムスタンプ>.png の名前で自動命名します |
step <yaml> |
シナリオのステップを1つそのまま実行します。シナリオのステップが受け付ける一発アクションなら何でも(swipe、pinch、rotate、setPickerValue、selectOption など)、専用コマンドのないものを実行できます(下の「ステップの指定」を参照) |
help |
上のコマンド一覧を表示します |
exit / quit |
シェルを抜けます |
clear |
スクロール領域の記録を消去します。ncurses 版のシェル限定の機能で、記録を保持しないプレーンなフォールバックでは clear は未知のコマンドとして扱われます |
ターゲットの指定(tap / type が受け取る値)は、シナリオのセレクタと同じ id / label / index の
語彙に届きます。加えて、tap だけはセレクタを一切経由しない生の座標も受け付けます。さらに --sel を使えば、
下の短縮形では表せない残り全部のセレクタ語彙にも届きます。
| 形式 | 一致する対象 |
|---|---|
<id> |
その id を持つ要素本体。tap では空白を含む残り全体をそのまま id として扱います。type で空白を含む id を使うには、後述の引用符表記が必要です |
<id>#<index> |
同じ id を持つ複数要素のうち <index> 番目(0 始まり。負の値は末尾から数えます) |
label:<text> |
id を持たない要素を、その label の完全一致で指定する形式 |
label:<text>#<index> |
同じ label を持つ複数要素のうち <index> 番目 |
@<x>,<y> |
tap 専用。要素ツリーを経由しない生のピクセル座標(Driver.tap_point) |
"<空白を含むターゲット>" |
type 専用。複数語からなる label: ターゲットを、後続のテキストと区別するための引用符表記 |
--sel <yaml> |
完全なセレクタ。例: --sel {idMatches: row.*, index: 1}、--sel {label: Sign in, within: {id: form.login}}。run が受け付けるのと同じ id / idMatches / label / labelMatches / traits / value / within / index の各フィールドを、シナリオと同じ Selector モデルでそのまま解釈します。flow スタイルの { ... } を1つだけ書く形式に限ります(block スタイルの YAML は改行を必要とし、1行のコマンドには収まりません)。閉じる } が、"<空白を含むターゲット>" における引用符と同じ役割を果たし、type のターゲットとテキストの境界になります |
上の短縮形は、id や label 自体が #<digits> で終わっていたり、@ や label: で始まっていたりする場合には
届きません。また idMatches・labelMatches・traits・value・within のどれにも届きません。これらすべて
の逃げ道が --sel です。短縮形が存在する理由は、よくある単純な場合には tap <id> のほうが
--sel {id: ...} より短く打てるからです。
- 表の列はセレクタが照合する対象のフィールドそのもので、backend が
正規化した形です。プラットフォーム付属のインスペクタが持つ独自の語彙ではありません。
treeの行から読んだ id は、runが解決する id と同じものです。 - 推測はしません。
tapのターゲットがどの要素にも一致しなければElementNotFoundで、複数の要素に一致 すればAmbiguousSelectorで失敗します。いずれも即座に、runが送出するのと同じメッセージで失敗します (#<index>を添えて一意にするか、ツリーを読み直してください)。シェルはその失敗を表示して次の行を読みます。 生の@<x>,<y>座標タップはセレクタを一切解決しないため、この失敗は起こりません。 tapは覆っている要素をスクロールでどかしません。 別の要素が対象を遮っているとき、runはまず範囲を 限ったスクロールで再試行します。replは driver 自身のElementNotTappableをそのまま出し、その例外が 遮っている要素を名指しします。セレクタを調べている最中には、こちらのほうが役に立つ答えだからです。その 結果、覆われた対象についてはrunとreplの判定が食い違うこともあります。スクロールによる回復が必要なら、 シナリオに明示的なscrollステップを書いてください。scrollは生のジェスチャで、「見えるまでスクロール」ではありません。 シナリオ自身のscrollステップは必ずターゲットを指定し、それが画面に見えた時点で止まります。この短縮コマンドにはターゲットや 停止条件、失敗させるセレクタもありません。Driver.scrollそのものの一発ジェスチャです。ターゲットを 探すスクロールにはstepを使ってください。他のジェスチャ(swipe、pinch、rotate)やプラットフォーム 固有のアクション(setPickerValue、selectOption)も同様です。- シェルを抜けてもアプリは動いたままです。 Simulator や実機の上のアプリは抜けた時点の状態で残るので、
そのまま手で調べ続けられます。閉じるのは、このコマンド自身が持っている 2 つのセッションだけです。1 つは
web backend のブラウザ、もう 1 つは
appiumグリッドへの live 経路の WebDriver セッションです。この WebDriver セッションは、閉じないとグリッド上で期限切れまで予約されたままになります。 services.serverを宣言しているターゲットでは、シェルを開く前にサーバを起動し、抜けるときに停止します。これが ないと、web ターゲットは待ち受けていないホストに対してブラウザを開き、treeのたびにエラーページを読むことに なります。
ステップの指定(step <yaml>)は、flow スタイルの { ... } を1つだけ書く形式で、シナリオファイル自身の
ステップが検証されるのと同じ Step モデルです。step {swipe: {on: {id: card}, direction: up}}、
step {pinch: {sel: {id: map}, scale: 0.5}} のように書きます。run の一発アクション用ディスパッチャを
そのまま通るので、対応する動作は tap、type、scroll、swipe、pinch、rotate など、シナリオの
一発アクション全般です。ターゲットの解決に失敗する場合も、tap のターゲットと同じ形で失敗します
(ElementNotFound / AmbiguousSelector)。wait、assert、制御フロー(if / forEach / web /
app)には実行できる一発ハンドラが存在しません。step はそれを試すのではなく、そのギャップを名指しで
報告します。こうしたステップの実行には、シナリオ全体を走らせるループが必要です。
シェルそのものは、標準入力と標準出力の両方が実際の端末であるとき、ncurses 風の画面になります。コマンド
行はつねに画面の一番上に固定され、各コマンドへの応答は下のスクロール可能な領域に積み重なります。各応答の
末尾には -- EOL -- の行が付くので、長い記録のなかでもどこまでが1つのコマンドの出力かが見分けられます。
入力行のすぐ下の行には常にバナーが表示され、現在のモードを示します。入力行とスクロール領域では Tab による
切り替えも併記されるので、この表を確認しなくてもモードの切り替え方が画面上でわかります。マウスホイールは、
端末がそれを報告する場合、どのモードでもこの領域をスクロールします。下の表のキー操作をキーボードなしで
代替する手段です。この領域はどのモードでも描画され続けます。そのため、スクロール領域を上にスクロールしている
あいだや、下端まで Tab で戻らずに次のコマンドを入力しているあいだに、コマンドの応答が表示範囲の外に出ることが
あります。そうなった瞬間にバナーへ [new output ↓] が付き(そのときのモードの文言はそのまま)、表示が下端に
戻ると消えます。
| キー | 入力行での動作 | スクロール領域での動作 |
|---|---|---|
Tab |
スクロール領域に切り替えます | 入力行に戻ります |
↑ / ↓ |
直前や直後に入力したコマンドをヒストリから呼び出します | 出力を 1 行ずつ上下にスクロールします |
k / j |
文字としてそのまま入力されます | 出力を 1 行ずつ上下にスクロールします(vim 風、↑/↓ と同じ動作) |
PgUp / PgDn |
動作しません | 出力を画面 1 枚分ずつ上下にスクロールします |
← / → / t / b |
カーソルを左右に移動します(t / b は文字としてそのまま入力されます) |
最上位・最下位まで一気にジャンプします |
/ |
動作しません | フィルタの入力欄を開きます。Enter で確定すると、大文字小文字を区別しない部分一致でこれまでの出力全体を絞り込みます。空のパターンで確定すると解除され、Esc は編集そのものを取り消します |
Ctrl-C |
打ちかけの行を捨てます | 動作しません |
標準入力または標準出力がパイプされている場合(スクリプトやテストハーネス、bajutsu repl < commands.txt など)
は、1 行ずつ読むプレーンなシェルにフォールバックします。clear を除くうえのコマンドはどちらの形でも同じように
動作し、exit / quit はどちらの形でもシェルを抜けます。Ctrl-D はプレーンなフォールバックでのみ同じ働きを
します。curses
には読み取れる Ctrl-D / EOF の合図がありません。
起動中のアプリへの接続¶
--attach を付けると、起動済みの Simulator 上のアプリに、操作者が残したままの状態でシェルを接続します
(BE-0455)。
フラグなしのシェルは、まずアプリを起動します。その起動は、動いているプロセスを新しいプロセスに置き換えます。
その結果、操作者がたどり着いた画面、ログイン状態、Xcode から接続したデバッガが失われます。
--attach では、XCUITest ランナーが既存のプロセスをそのまま操作します。最初の tree は、すでに前面に
出ていた画面を表示します。セッションの前後で、アプリのプロセス ID は変わりません。
attach での開始は、デバイス全体に及ぶ操作を何もしません。
- デバイスの準備をしません。 デバイスの erase やブート、アプリのインストールをせず、ロケールの固定、
権限の付与、deeplink も飛ばします。
--eraseは強制的に off になり、--attach --eraseは終了コード 2 で終わります。 - readiness を待ちません。 アプリは操作者が残した画面にあるので、ターゲットの
subject.startWhenの画面を 待ちません。 - 再試行しません。 ランナーは 1 回だけ起動し、リカバリの手順も使いません。再試行や修復の経路は、 どれもアプリを終了させるか Simulator を再起動させるためです。ランナーが立ち上がらなければ、ログの末尾を 添えて終了コード 2 で終わります。
- アプリを終了しません。 シェルを抜けるとランナーだけが止まり、アプリは動き続けます。
シェルはランナーを起動する前にデバイスを、ランナーは操作を受け付ける前にアプリを確かめます。
| 状況 | 結果 |
|---|---|
Simulator が 1 台も起動していない、または指定した --udid が停止している |
終了コード 2 で終わります。attach がデバイスを起動することはありません |
| ターゲットの bundle id のプロセスが動いている | ランナーがそのプロセスに接続します |
| アプリは動いているがバックグラウンドにある | ランナーのログの末尾を添えて終了コード 2 で終わります。先にアプリを前面に出してください |
| アプリはインストール済みだが動いていない | シェルが <bundle id> was not running; launching it と表示し、ランナーがターゲットの launch env と引数でアプリを起動します。このときも erase やインストールはしません |
| アプリがインストールされていない | bundle id を示して終了コード 2 で終わります |
それ以外の経路では、--attach はデバイスへ触れる前に終了コード 2 で終わります。対象は、playwright と
adb の backend、appium グリッドへの live 経路、runsOn.ios.kind: device のターゲットです。
bundle id と id の名前空間はターゲットの config から取るので、--target は引き続き必須です。
codegen¶
シナリオから ネイティブテスト を生成します(AI 非依存、構造マッピング、codegen)。出力先は XCUITest(Swift、iOS)、Playwright(TypeScript、web)、または UI Automator(Kotlin、Android)です。
bajutsu codegen <scenario.yaml> --target <name> [--emit xcuitest | playwright | uiautomator] [-o <out>] [--config ...]
| オプション | 既定 | 説明 |
|---|---|---|
--emit |
xcuitest |
出力形式。xcuitest、playwright、または uiautomator(他は終了コード 2) |
-o, --out |
- |
出力ファイル。- で標準出力 |
- config の
subject.launch.envが生成テストに入ります。XCUITest ではapp.launchEnvironment、Playwright ではlocalStorageのシードに反映されます。 --emit playwrightは対象が web ターゲット(platform: webでsubject.urlを持つ)であることを要求します。--emit uiautomatorは対象が Android ターゲット(platform: androidでsubject.idを持つ)であることを要求します。どちらも 満たさない場合は終了コード 2 で終わります。- ファイル出力時は
wrote <N> scenario(s) -> <out>。
approve¶
実行で撮影したスクリーンショットを visual のベースラインへ昇格させます。これはビジュアル
リグレッションのループ(run、確認、approve、再 run)の後半にあたります。manifest.json を読むだけなので
Simulator 不要で CI でもヘッドレスに動作し、WebUI の Approve ボタンの CLI 版です。
bajutsu approve [<run_dir>] --baselines <dir> [--scenario <id>] [--all] [--runs runs]
| オプション | 既定 | 説明 |
|---|---|---|
<run_dir> |
runs/ 配下の最新 |
承認元の実行 |
--baselines |
(必須) | 昇格した PNG を書き出す先 |
--scenario |
"" | この scenario id のみ(実行ディレクトリの 00-home など) |
--all |
off | 既に合格したベースラインも更新(既定: 失敗 / 不在のみ) |
--runs |
runs |
<run_dir> 省略時に使う runs ルート |
- 各 visual チェックの
visual-actual.pngを<dir>/<baseline>へコピーします。1 件以上昇格すれば 終了 0、対象が無ければ 1。
serve¶
オーサリング、実行、探索のためのローカル Web UI です。Tier 1 の利便機能で、CI ゲートには含まれません。
CLI を覆う 4 つのトップレベルタブがあります。Record はゴールからシナリオを著し(python -m bajutsu
record ...)、Replay はシナリオを実行してレポートを表示し(bajutsu run の本体である python -m bajutsu.run.internal ...)、Crawl は
アプリを探索して画面マップをリアルタイムに描き(python -m bajutsu crawl ...)、Stats は run 履歴を
横断した集計 run 統計ダッシュボードを表示します(bajutsu stats)。いずれもアクティブな
config に対して動きます。config はファイルブラウザ、Git リポジトリ、アップロードした .zip バンドルの
いずれかから開きます(後述の「Open config」を参照)。リクエストごとに job をキューに積み、
bajutsu worker がその job を実行します。サーバ自身は job を実行しません(BE-0449)。サーバは job の出力を
ストリームし、生成された runs/<id>/ ツリーを配信します(report の相対アセットリンクと crawl の
screenmap.json が解決します)。バインド先は 127.0.0.1 です。
bajutsu serve [--port 8765] [--config bajutsu.config.yaml] [--root .] [--runs runs] [--baselines <dir>]
[--host 127.0.0.1] [--token <t>] [--max-concurrent-runs 4] [--evidence-store <uri>]
認証とセキュリティヘッダ¶
--token(または$BAJUTSU_SERVE_TOKEN)による認証(BE-0051)。 トークン設定時は全リクエストが認証必須です。 API クライアントはAuthorization: Bearer <token>を送り、ブラウザはPOST /api/loginで一度だけトークンを 交換し(401 で UI が入力を促す)、HttpOnly かつ SameSite のセッション Cookie を受け取ります。トークンは URL に 載せません。非 loopback の--host(例0.0.0.0)への bind はトークン必須で、無認証での公開を防ぎます (無ければ起動を中止)。トークン未設定なら従来どおり全開放で、loopback でのみ安全です。完全なマルチユーザー認証 (OAuth/RBAC)は対象外です(BE-0015)。- CSRF + セキュリティヘッダ(BE-0051)。 トークン設定時、
OriginがHostと一致しない状態変更 POST は 拒否します(SameSite=Strictセッション Cookie に対する多層防御)。Originを送らない非ブラウザ クライアントは影響を受けません。全レスポンスにX-Content-Type-Options: nosniff/X-Frame-Options: DENY/Referrer-Policy: no-referrerを付与します。
config とディレクトリの指定¶
--configは任意です。省略すると UI のファイルブラウザ(「Open config」ボタン)からconfig.ymlを開けます。 ブラウザの走査は--root(既定: カレントディレクトリ)配下に限定されます。--scenarios <dir>は選択アプリの設定済み ディレクトリの上書きとして使えます。- Git リポジトリから(BE-0063)。
--configは Git ソース(github:owner/repo@ref:path)も受け付け、「Open config」ダイアログにも同じ spec を入れる From a Git repository 欄があります。serve はその ref のリポジトリ部分木をキャッシュへ実体化し、その config を bind し、 チェックアウトのルートから serve します。これにより config の相対パス(paths.scenarios/subject.path/subject.build)は取得したツリーを 基準に解決されます。これはセルフホストの狙い(BE-0016 Tier A)そのもので、ファイルを手で同期する代わりにチームのテストリポジトリを serve に向け、ブランチの切り替えを再デプロイではなく UI 上で行えます。ファイルブラウザは--root配下に限定されたままです。チェックアウトは管理された content-addressed キャッシュで、 Git ソースの run は config のパス項目をチェックアウトのルートに閉じ込めます(BE-0063)。 --baselinesでビジュアルリグレッションのベースラインディレクトリを指定します(既定: アプリのシナリオ ディレクトリ配下のbaselines/)。UI から起動した実行はこれを使い、レポートの Approve ボタンがPOST /api/approve経由で撮影スクリーンショットをここへ昇格させます。--themes <dir>は差し込み式のテーマディレクトリです(BE-0191)。 ここに置いた*.cssが 1 つずつ選択可能な UI テーマになります。テーマは宣言的で、bajutsu/templates/serve.themes.cssに明文化されたデザイントークンのブロックに、先頭の/* bajutsu-theme name: … kind: dark|light */という マニフェストコメントを添えたものです。テーマの id はファイル名の語幹で、その[data-theme="<id>"]セレクタは これと一致させます。JavaScript を含まないので、差し込んだテーマはシナリオや config と同じ信頼レベルに収まります。 組み込みのmidnight/daylightは常に提供され、発見したテーマはこれを拡張します。走査は起動時に一度だけ行い、 ライブリロードはしません。config の任意のui.default_themeが初期選択を決めます(未指定なら、利用者が選ぶまでは OS の配色に従います)。- app を選ぶ(そのシナリオがドロップダウンに並ぶ)と、backend / udid / erase /
disable alert-dismissを設定して Run を押します。 出力がライブ表示され、完了でreport.htmlが埋め込まれます。
各タブの機能¶
- Crawl タブは、app、シミュレータのプール(Replay と同様の複数選択。2 台以上選ぶと 1 つの画面マップを
共有して並列にクロールします。詳細は BE-0064)、
予算(max screens / steps)を選び、
POST /api/crawlで crawl を起動します。返ってきた run id で UI がruns/<id>/screenmap.jsonをポーリングし、画面マップを成長に合わせて描きます(画面は幅優先の層に配置し、 遷移は矢印で表示)。Stop ボタンで Replay と同様に中止できます。 - Stats タブは集計 run 統計ダッシュボード(BE-0102)を
描きます。
bajutsu statsと同じ read-only の傾向を、サーバの run 履歴に対してライブで表示します。合格率の推移、 遅い/flaky なシナリオ、失敗ホットスポット、run のボリュームを示します。同じ決定的な集計器を再利用し、各 run のmanifest.jsonを artifact store から読みます(run-id の一覧は、データベースを配線しているときは system of record から org スコープで、そうでなければ artifact store から取得)。デバイスも AI も判定も使いません。GET /statsで配信し、 タブの更新ボタンで再取得します。 - Flaky タブはランク付きのフレーキシナリオ一覧(BE-0220)を
描きます。
bajutsu flakinessと同じ read-only のランク付けを、サーバの run 履歴に対してライブで表示します。判定の反転率で flaky を先頭に並べ、各行は代表的な合格 run と失敗 run の証跡へリンクします。データベースを配線しているときは各 run の行に 刻まれた provenance から直接グルーピングし(org スコープ)、そうでなければ各 run のmanifest.jsonから同じレコードを組み立てます。 各行は run が動いたデバイスの OS バージョンも示し、行はバージョンごとに分かれます (BE-0358)。 デバイスも AI も判定も使いません。GET /flakinessで配信し、タブの更新ボタンで再取得します。
バンドルのアップロードと合成¶
- バンドルのアップロード(BE-0073)。
「Open config」ダイアログには 3 つめのソース Upload a bundle があり、ホストのファイルシステムに触れない
ブラウザ利用者が、ホスト型の
serveに自分のスイートを持ち込めます。レイアウトが動くローカル checkout そのものの.zip、つまりbajutsu.config.yaml、そのpaths.scenariosツリー、config のsubject.pathが指すビルド済み アプリバイナリ(.appディレクトリ、zip 化した.app、.ipa)を投下します。serveはそれを封じ込めた サンドボックス(runs/の兄弟で、--rootではない)へ展開し、ファイルブラウザや Git ソースとまったく同じく アクティブな config としてバインドします。以後 Replay / Record / Crawl タブはその展開先から動きます (config の相対パスsubject.path/paths.scenarios/paths.baselinesはバンドルを基準に解決されます)。run は サンドボックスではなくserve自身のストアに着地するので(--runs-dir)、History に残ります。アップロードの ファイル名と zip の sha256 は各 run のmanifest.json(provenance)に記録するので、「この run は何を実行 したか」を後から辿れます。バインドできるバンドルは同時に一つだけで、別の config(どのソースでも)を開くと サンドボックスは削除されます。バンドルは秘匿情報を運びません。${secrets.*}は通常の run と同じくserveホストの環境から解決し(BE-0032)、 アップロードされた config のsubject.buildコマンドはホスト上で決して実行しません(バンドルはビルド済みバイナリを 同梱します。DESIGN §1)。展開は zip-slip(絶対パス、..、symlink エントリは拒否)と zip-bomb(エントリ数、 展開後の総サイズ、エントリごとの圧縮率の上限)に対して堅牢で、各ターゲットのパス項目はバインド時にバンドル内へ 封じ込められ、config のバインドは他のリクエストと同じトークン認証の裏にある admin ロールの操作です。任意の バイナリを持ち込むことは、認証済みの単一 Mac のserveでのみ公開されます。 - アーティファクトからの合成(BE-0268)。
結合バンドルは、変更頻度がまるで違う 3 つの部品を一つに束ねます。ビルドごとに変わる巨大なバイナリ、編集の
たびに変わる小さな scenario ツリー、めったに変わらない config です。そのため scenario を 1 行直すだけでも
zip 全体を送り直すことになり、変わっていないバイナリの分まで再び支払います。「Open config」ダイアログの
4 つめのソース Compose from artifacts は、バンドルを 3 つの独立してアップロードできる content-addressed
な部品、Config、Scenarios(scenario ツリーの
.zip、または単一の.yaml。内容で判別し、単一 ファイルは config のpaths.scenariosディレクトリへ拡張子を.yamlに正規化して配置します)、Binary(zip 化 した.app、.ipa、または Android の.apk。config のsubject.pathの拡張子で展開するか raw で書き出すかを 決めます)に分割します。 各部品はバイト列の sha256 で保存します(POST /api/artifacts/{config,scenarios,binary})。部品を内容で アドレス指定するので、変わっていない部品はまるごと省けます。ブラウザはファイルをハッシュし、アップロード前にGET /api/artifacts/existsで在庫を問い合わせるため、同じバイナリが 2 度も回線を通ることはありません。 Compose & load(POST /api/compose)は、選んだ(config, scenarios, binary)の三つ組を、結合バンドルが 生むのと同じ封じ込めたツリーに組み立てます。レイアウトの唯一の権威は config で、自身の相対パスpaths.scenarios/subject.pathによって各部品の置き場所を指定します。組み立てたツリーはアクティブな config としてバインドするので、 バンドルのときと同じく Replay / Record / Crawl タブがそこから動きます。config が必要とする部品を渡していない 三つ組は、run に入る前に拒否します(中途半端なツリーで走ることはありません)。1 本の脚だけ差し替えて合成し 直せば、共有する部品を再アップロードせずに新しい組み合わせ(同じ scenario に対するバイナリ A と B、あるいは 一つのバイナリに対する複数の scenario セット)を走らせられます。各 run のmanifest.jsonには、三つ組の来歴をcompositionIdと部品ごとの<kind>Shaとして記録するので、「この run は何を実行したか」を各部品の正確なバイト まで辿れます。アーティファクトのアップロードと合成はいずれも、他と同じトークン認証の裏にある admin ロールの操作で、 結合バンドルと同じ zip-slip / zip-bomb 対策が効いています(3 つのドロップゾーンの UI とこの合成エンドポイントが BE-0268 の UI スライスで、結合POST /api/uploadを分割版と同じ内部表現へ統一する部分は別の follow-up です)。 - オーサリング(Record と Crawl)の AI プロバイダは Settings → AI プロバイダ の一箇所で選びます。
Anthropic API(
ANTHROPIC_API_KEY)、Amazon Bedrock(AWS 認証情報 +BAJUTSU_BEDROCK_MODEL)、 Anthropic CLI(ant。Pro / Max / Console のシートに対するブラウザ経由の OAuth(SSO)サインイン。 BE-0163。専用の/api/ant/loginルートを持ちます)、Claude Code CLI(claude-code。Claude Code の Pro / Max / Console シートに課金します。BE-0176。ヘッダレスなホストで対話的なclaude setup-tokenが実行できない場合に備え、長期間有効な OAuth トークンを write-once でパネルに保持します。 configuration、BE-0215)の 4 択で、serveはこの選択をBAJUTSU_AI_PROVIDERとして起動ジョブに渡します。タブごとの 選択はなく、すべての AI 経路(オーサリング、アラートガード、triage)が同じ 1 つのプロバイダを使います。
シナリオの編集と検証¶
- エディタでのシナリオのインライン検証(BE-0138)。
Author タブの YAML エディタは、保存時だけでなく入力しながら検証します。デバウンスした
POST /api/lintがbajutsu lintと同じチェックを実行し、行に紐づく診断を返します。診断は該当行のガターのマーカーと、 クリックで該当行へ移動できる問題リストに表示されます。YAML のパースエラーは正確な行と列を持ち、スキーマや 検証のエラーは可能な限り行を解決します。ターゲットを選択していると、リクエストにそのターゲットが入ります。 サーバーは、バインド済みの config に対してbajutsu lint --config --targetが出す指摘を、それぞれの行に 付けて加えます(BE-0467)。 ターゲットを選択していなければ、エディタの lint の結果は変わりません。シナリオの JSON Schema(GET /api/schema。bajutsu schemaが出力する ものと同じ)は、軽量なキー補完(Ctrl/⌘+Space)と hover の説明表示にも使われます。決定的で AI を使わず、デバイスも モデルも起動しません。保存は保存自身の検証を保持するので、インライン検証は失敗をより早く見せるだけです。 - アプリのビルド済みバイナリ(config
subject.path)が無い場合は、先にそのアプリのsubject.buildコマンドを 実行します(出力は job ログにストリーム)。ビルド失敗時は run を開始せず中止します。targets.<name>.subject.buildにsubject.pathを生成するシェルコマンド(例:make -C demos/showcase swiftui-build)を設定すると、 手動ビルド無しに UI からオンデマンドでビルドできます。 - 操作 UI の下の History リストに過去の run(新しい順、pass/fail ドット、シナリオ要約)が並び、
クリックでそのレポートを再表示します。
GET /api/runsが裏側です。 - run サブプロセスは worker が起動し、worker の環境(venv の
binをPATH先頭に付与)と、lease が 中継する保存済みのシークレットを受け取ります。ローカルの job は config のディレクトリで動くので、bajutsu.config.yamlが解決します。 /api/runの入力検証。 scenario は選択中アプリの scenarios dir 内に実在する*.yamlでなければ なりません(任意のホストパスや..トラバーサル不可)。backend/udidも既知のトークンに限定され、 自由入力は拒否されます。これにより、リクエストが任意ファイルを実行したり想定外の argv を紛れ込ませたりするのを防ぎます。backendはrun --backendと同じ検査に従い、ターゲットの platform、その actuator 名、fake以外は 400 になります。 これはserveを loopback を越えてホスティングするための前提です (BE-0015 / BE-0016)。 現状は127.0.0.1バインドかつ認証なしなので、信頼できないネットワークにはまだ晒さないでください。-
/api/runから Appium グリッドで動かす(BE-0452)。 リクエストは任意のenvironment: appiumを 受け付けます。この値を付けた job は、worker 能力ファイルにappium環境を持つ worker へ振り分けます。 その job が要求するのはenvironment:appiumだけです。それ以外の値は 400 になります。 -
/api/runでの job 単位のアーティファクト差し替え(BE-0431)。 ホスト型デプロイのPOST /api/runは、binaryArtifactとscenariosArtifactも受け付けます。どちらも、org に保存済みのアーティファクトの sha256 です。 その job だけが、指定したバイナリを target のsubject.pathに置き、指定した scenarios の zip で実行します。 org のアクティブな config は、バインドされたまま変わりません。run のmanifest.jsonは、差し替えた sha256 をprovenanceの下に記録します。job のキューを持たないサーバは、どちらのフィールドも拒否します。 詳しくは self-hosting を参照してください。
同時実行数、証跡、ホスティング¶
--max-concurrent-runs(既定 4) は同時実行できる run/record ジョブ数の上限です。1 呼び出し元が 希少なデバイスを独占しないようにします(BE-0051)。上限超過の dispatch は 429 を返します。0で無制限。--evidence-store <uri>(または$BAJUTSU_EVIDENCE_STORE)。各 run の証跡をアップロードします(BE-0110)。s3://bucket/prefixまたはgs://bucket/prefixを指定すると、完了した run のツリーがそこへアップロードされます。キーは<prefix><evidence_prefix><runId>/…の形になるので、パスによってクラウドのライフサイクルポリシーが切り替わります。スタンドアロンのrun --evidence-store(Runner 自身の認証情報で直接アップロードする)と違い、serveは認証情報を保持し、Worker には渡しません。コントロールプレーンがファイルごとに presigned PUT URL を発行し、Worker はクラウド SDK も認証情報も持たずに平文 HTTP でアップロードします。呼び出し元はPOST /api/runのボディにevidence_prefix(安全な相対セグメントとして検証されます)を渡して run ごとのパスを選びます。サーバが自分のバケットとベースプレフィックスを前置するので、run ID が必ずキーに含まれ、run 同士が衝突しません。アップロードは判定の後に走るため、失敗しても警告のみです。サーバ側にs3またはgcsextra が必要です(Worker には不要)。トポロジは self-hosting を参照してください。- すべての job を worker が実行します(BE-0449)。
serveはbajutsu workerに渡す job のキューを持ち、すべての job をキューに積みます。対象は、ビルド段階を含む各 run、Device Farm への展開、triage、record、crawl です。serveのプロセスは、どの job も実行しません。キューの job は worker を待ちます。その job を実行できる稼働中の worker がないあいだ、job には使える worker がないという通知が付きます。make serveはサーバの横で worker を起動します。bajutsu serveを直接起動したときは、横でbajutsu workerを起動する必要があります。lease は、その job の org に保存されたシークレットを worker に渡します。1台のマシンでBAJUTSU_SERVER_STOREを設定しなければ、サーバに環境変数は要りません。キューは runs ディレクトリの隣の.bajutsu/queue.db(SQLite)に置きます。キーも同じ場所に0600の権限で生成します。1つは署名付き URL 用で、もう1つは保存するシークレット用です(BAJUTSU_SECRETS_KEYを設定したときは生成しません)。アーティファクトのストアは default org の run を runs のツリーから直接、サーバが署名した URL で読み、それ以外のオブジェクトは.bajutsu/objects/に置きます。起動時には、すでにruns/の下にある run を履歴に登録します。その後の run は、admin がPOST /api/runs/rescanを呼ぶと登録されます。BAJUTSU_DATABASE_URL、BAJUTSU_SECRETS_KEY、BAJUTSU_SERVER_STORE、BAJUTSU_HOSTEDを設定すると、これらの既定値を上書きします。バケットのないサーバは、--asgiと同じく FastAPI のトランスポートを使います。また、--port 0ではなく固定のポートが必要です。バケットを指定したサーバは、BAJUTSU_DATABASE_URLも設定する必要があります。設定しなければ、キューを持たないので起動を拒否します。詳しくは self-hosting の「1台のマシンで動かすサーバ backend」を参照してください。 --backend(非推奨)。 以前このフラグは、2つの backend を選んでいました。localbackend はserveのプロセス内で job を実行し、serverbackend は job をキューに積みました。今はどちらの値でも同じサーバが起動します。serveはlocalとserverを受け付けて警告を表示し、値を無視します。未知の値を渡すと、これまでどおり終了コード 2 で終わります。次のリリースでフラグを取り除くので、コマンドラインから外してください。- ホスティング向けフラグ(応用)。
--emit-launchagentはserveを単一 Mac 上でトークン認証付きの LaunchAgent として動かす launchd plist を出力します。--upload-exec(または環境変数BAJUTSU_UPLOAD_EXEC)は、アップロードされたバンドルのservices.serverコマンドを実行してよいかを決めます(deny/reuse/sandbox、既定はsandbox)。--allow-remote-build(または環境変数BAJUTSU_ALLOW_REMOTE_BUILD)は、UI で bind した Git ソースの config のsubject.buildとdriver.runner.buildコマンドをホスト上で実行することを許可します(既定はオフ)。いずれも self-hosting で扱います。
mcp¶
エージェント(Claude Desktop や Claude Code)がシナリオを実行し、run の証跡を読めるように MCP(Model Context Protocol)サーバを起動します。オプションの bajutsu[mcp] extra(fastmcp)が必要です。
bajutsu mcp [--config bajutsu.config.yaml] [--runs runs] [--transport stdio] [--worker-config <worker.yaml>]
| オプション | 既定 | 説明 |
|---|---|---|
--config |
bajutsu.config.yaml |
ツールがアプリを解決する config |
--runs |
runs |
リソースとして公開する runs ディレクトリ |
--transport |
stdio |
stdio(ローカルエージェント)または sse(HTTP) |
--worker-config |
同梱のデフォルト | ツールが従う worker 能力ファイル(run と同じ)。appium のファイルを渡すと、グリッドの platform のターゲットに対する bajutsu_run と bajutsu_doctor はグリッドで動きます |
- ツール:
bajutsu_run(決定的 run)とbajutsu_doctor(規約スコア)。どちらも CLI と同じで、合否に AI は入りません。 - リソース: 完了した run の
manifest.json/report.html/junit.xmlと任意の入れ子の artifact(bajutsu://runs/<id>/…)、およびruns/latest。
worker¶
コントロールプレーン(bajutsu serve)にキュー済みの job をポーリングし、実行します。1台のマシンでも
ホスティング用サーバ backend でも、すべてのデプロイの実行側です(BE-0015、self-hosting)。
/api/worker/lease を単純な HTTP でポーリングして job をリースします。Redis や RQ には頼りません(BE-0106)。リースした job はそのまま run_job で実行し、結果を /api/worker/result に返します。worker は cloud の資格情報を一切持ちません。run 前のベースラインのダウンロードも、run 後の run ツリーのアップロードも、コントロールプレーンが発行する署名付き URL(presigned URL)を経由します(BE-0160)。そのため worker に必要なのは HTTP クライアントだけです。
実行する job がなければ、lease は 204 を返します。スロットを複数持つのは、maxJobConcurrency が 1 より大きい worker だけです。これは Device Farm を含む device-cloud の worker にあたります。そうした worker は、空きスロットの数を maxJobs として 1 から 100 の範囲で送るので、応答はリストになります。スロットが 1 つの worker は maxJobs を送らず、応答は 1 件のままです。扱えるもっとも古い job が run-set のグループに属していれば、リストにはそのグループの次の job も、サーバの同時実行の上限の範囲で加わります。こうして、スロットどうしがグループのアップロードを共有できます。run-set の job は、コマンドの代わりに実行意図(run intent)を持ちます。リースした worker が、その意図を自分の形の実行に変換します。ローカルの worker なら bajutsu run のコマンドに、Device Farm の worker ならプロバイダーのバッチに変換します(BE-0484)。
ローカルの bajutsu serve も run をすべてキューに積むので、worker が要ります(BE-0449)。make serve は worker を1つ起動します。lease の応答は、worker にさらに2つのフィールドを渡します。
secret_envは、lease した job の org に保存されたシークレットを持ちます。AI のキーと、ユーザーが UI で設定した${secrets.X}の値がこれにあたります。サーバはこれらを lease の時点で読み、キューには保存しません。worker はこれらを run の環境変数に重ね、引数には載せません。共有トークンで取った lease はこれらを受け取ります。トークンのないループバックでの起動でも、lease は受け取ります。ブラウザのログインは受け取りません。- 仕様の
cwdは、自前のファイルを送らない job のために、bind した config のディレクトリを示します。ローカル起動での run はこの種の job で、config、シナリオ、runs、ベースラインをパスで指定します。worker は、そのディレクトリで job をビルドして実行します。これで config の相対的なsubject.pathとsubject.buildが、サーバのプロセスの中と同じように解決します。別のマシンの worker はそのディレクトリを持たないので、サーバのマシンの worker が必要だと伝えて job を失敗にします。
SIGINT や SIGTERM を受けた worker は、サーバからのキャンセルと同じように止まります。lease した job をキャンセルし(run なら穏やかに止めます)、キャンセルした結果を送ってから、128 にシグナル番号を足した終了コードで終わります。キューはその job をキャンセル済みとして記録し、再び実行しません。2 回目の SIGINT は、--once と同じく job のプロセスグループをすぐに終わらせます。
maxJobConcurrency が 1 を超えるデバイスクラウドの worker は、停止シグナルを別のように扱います(BE-0448)。リースをやめ、何も取り消さず、結果も送りません。処理中のリースはそれぞれ期限切れになり、再起動した worker が実行を再開します。2 回目の SIGINT を受けると、スロットを待たずに終了します。各実行がどうなるかは AWS Device Farm で実行する で説明しています。
bajutsu worker [--server-url <url>] [--token <t>] [--platform ios] [--capabilities <tokens>]
[--poll-interval 2.0] [--heartbeat-interval 30.0] [--worker-id <id>]
[--worker-config <worker.yaml>] [--workdir <dir>]
[--machine-id <id> | --server-state-dir <dir>]
bajutsu worker --once <spec.json> [--worker-config <worker.yaml>]
| オプション | 既定 | 説明 |
|---|---|---|
--once |
オフ | この JSON ファイルの job 仕様を 1 つ、サーバーなしでこのマシン上で実行し、job の終了コードで終了します。詳しくは下記を参照してください |
--server-url |
$BAJUTSU_SERVER_URL または http://localhost:8765 |
コントロールプレーンの URL |
--token |
"" | 認証用の operator トークン(コントロールプレーン側の --token / $BAJUTSU_SERVE_TOKEN) |
--platform |
ios |
この worker が動かせる backend のカンマ区切りリスト(ios / web / android)。コントロールプレーンが job を振り分ける軸です。ローカルの worker は、worker 能力ファイルが含まないドライバや、ホストで動かせないドライバのプラットフォームを指定されると、ドライバを名指しして起動時に終了します。そのため、Linux の worker は --platform ios で止まります(BE-0450)。device cloud の worker と appium の worker は指定を受け付けません |
--capabilities |
"" ($BAJUTSU_WORKER_CAPABILITIES も可) |
非推奨(BE-0450)。platform、ホスト、Simulator の在庫情報に加えて広告する追加の capability トークン(例: ios18,ipad)です。今回のリリースでは 1 回だけの通知とともに引き続き効き、次のリリースで削除します。これらのトークンは、在庫情報と worker 能力ファイルがすでに提供しています。予約済みの接頭辞 environment:、host:、machine:、device:、cap:、setting:、job:、platform:、kind: を持つトークンを渡すと、worker は起動時に止まります |
--poll-interval |
2.0 |
空き時間にリースを試みる間隔(秒) |
--heartbeat-interval |
30.0 |
run 中にリースのハートビートを送る間隔(秒)。コントロールプレーンのリースタイムアウトより短く保つことで、長時間の run を停止した worker と誤認して回収されないようにしています |
--machine-id |
"" ($BAJUTSU_WORKER_MACHINE_ID も可) |
サーバのマシンの識別子です。サーバの .bajutsu/machine-id に保存されています。worker はこれを machine:<id> として広告し、サーバのマシン上のパスでファイルを指定する job を受け取ります。対象は、ローカルで起動したサーバの run、triage、record、crawl です(self-hosting)。そのパスを読める worker にだけ渡します。デバイスクラウドの worker は受け付けません |
--server-state-dir |
なし | --machine-id を読むサーバの状態ディレクトリ(runs ディレクトリの隣の .bajutsu)です。サーバと同じマシンの worker に使い、make serve はこれを渡します。ディレクトリにまだ識別子がなければ、worker は起動時に終了します。このフラグと --machine-id は、どちらか一方だけを渡します。$BAJUTSU_WORKER_MACHINE_ID は --machine-id の代わりにだけ使うので、このフラグを渡したときは読みません |
--workdir |
新しい一時ディレクトリ | lease した job を実行する場所です。job の materials、取得したバンドル、アップロード前の run のツリーを置きます。既定のディレクトリは worker の停止時に削除するので、プロジェクトの中で起動した worker がプロジェクトに書き込むことはありません |
--worker-id |
"" (自動生成) | worker の識別子 |
--worker-config |
同梱の既定 | この worker が従う worker 能力ファイル(BE-0450。drivers を参照)。worker は起動時にファイルを検証し、不正なら job をリースする前に終了します。environment に device cloud を指定したファイルでは、worker はそのプロバイダを登録し、environment:<name> を広告します(Device Farm)。appium のファイルでは、worker は environment:appium を広告し、--platform を受け付けません。各 job は、グリッドを動かすローカルの bajutsu run として実行します(BE-0452)。どの worker も、run-set の job を実行できることを示す job:run-intent を広告します(BE-0484)。worker は起動するすべての bajutsu run にファイルの絶対パスを渡すので、リースした run はどれも同じファイルで検査されます。サーバーはこのファイルを読みません |
--once は job 仕様を 1 つ、サーバーなしで実行します(BE-0449)。
job 仕様はキューが保存する形と同じで、cmd のリストと、キュー済みの job が持つ任意のフィールドからなります。
worker はまず --worker-config を検証し、リースした job と同じく、起動する run にその絶対パスを渡します。
そのあとの job は、リースした job と同じコードで動きます。違いは次のとおりです。
- 子プロセスは端末の標準入力、標準出力、標準エラーを引き継ぎます。
- ダウンロードとアップロードをしないので、run ツリーは run が書いた場所に残ります。
- worker は run ID を
PASS|FAILの行ではなく run ツリーから読み取ります。 - SIGINT、SIGTERM、SIGHUP は、ハートビートによるキャンセルと同じく job をキャンセルします。終了コードは 128 にシグナル番号を足した値になります。
--once は次の仕様を、何も実行する前に拒否し、終了コード 2 で終了します。
- アップロードされたバンドル、成果物の差し替え、ビジュアルベースラインの取得を指定する仕様。これらは署名付き URL で届きますが、1 回実行の job には URL に署名するサーバーがありません。ベースラインは、ディスク上のディレクトリを
--baselinesで指定してください。 --worker-configの環境が実行しない仕様。localかappiumのファイルでの Device Farm のバッチ仕様と、デバイスクラウドのファイルでの通常の run 仕様がこれにあたります。udidsが文字列のリストでない仕様、またはmaterialsがパスから文字列への対応になっていない仕様- worker が認識しない形で run を指定する
cmd。認識する形はpython -m bajutsu.run.internal …と、以前のpython -m bajutsu run …です。 - 絶対パス、
..を含むパス、シンボリックリンクを通ってカレントディレクトリの外に出るパスを持つmaterials - カレントディレクトリにある別の内容のファイルを上書きしてしまう
materials - Windows 上のすべての仕様(シグナルの中継と生存確認のパイプには macOS か Linux が必要なため)
worker は仕様の materials(サーバーが送るシナリオと config)をカレントディレクトリに書き出します。リースした worker が自分の作業ディレクトリに書き出すのと同じです。
同じ内容のファイルはそのまま使います。内容が異なるファイルは呼び出し側のものなので、--once は上書きせずに拒否します。
そうした仕様は空のディレクトリから実行してください。
捕捉できない形で終了した worker --once に気づくのは run の仕様だけです。worker を kill -9 で終了させても、record、crawl、triage の子プロセスは自分で終わるまで動き続けます。
サーバーなしで Device Farm の job を投入する機能は、BE-0448 で追加します。
ほかのオプションはポーリングする worker のためのもので、--once では無視します。
lint¶
シナリオファイルを 実行せずに 文法に対して検証します(run がロード時に行う厳格な検証と同じ)。正しければ終了コード 0、そうでなければエラーとともに非 0 で終了します。
bajutsu lint <scenario.yaml>
bajutsu lint <scenario.yaml> --config <bajutsu.config.yaml> --target <name>
--config を付けると、lint はシナリオが実際に動くターゲットに対するチェックも行います。run がデバイスを
lease する前に行うのと同じチェックです(BE-0467)。ターゲットは run と同じ方法で解決します。
自分で targets を宣言したシナリオは、宣言したターゲットそれぞれに対してチェックします。宣言していない
シナリオは、--target のターゲットに対してチェックします。展開後のシナリオに対し、ターゲットごとに次の
3 つを行います。
- ステップのチェック:そのターゲットに割り当てたステップが必要とする capability を、ターゲットのルートが 持っているかを調べます。run の capability preflight と同じチェックです。
- 設定のチェック:シナリオが有効にする設定を、ルートが適用できるかを調べます。ターゲットが
runsOn.ignoredSettingsで無視を宣言した設定は対象外です(設定)。 - 前提条件のチェック:
preconditionsの各フィールドが、シナリオの動かすプラットフォームに存在するかを 調べます。
指摘には、ファイル、行、シナリオ、ターゲットが付きます。component が展開したステップの指摘は、その
component を呼び出した use: の行に付きます。どのチェックもデバイスを必要としません。アクチュエータには、
ターゲットの backend が挙げる実装済みのものの先頭を使います。
| 終了コード | 意味 |
|---|---|
| 0 | 指摘なし |
| 1 | スキーマのエラー、または指摘あり |
| 2 | 指定どおりにチェックできない(config がない、未知のターゲット、targets も --target もないシナリオ、--config なしの --target) |
--config を付けない場合、lint は config を読まず、これまでどおりに動きます。
schema¶
シナリオの JSON Schema を stdout に出力します。エディタ連携(補完 / インライン検証)用です。オプションはありません。
bajutsu schema > bajutsu.schema.json
config schema¶
bajutsu.config.yaml の JSON Schema を stdout に出力します。エディタ連携用です。オプションはありません。
bajutsu config schema > bajutsu.config.schema.json
このコマンドは、config のモデルと platform のレジストリからスキーマを生成します。各ターゲットは、
登録された platform ごとに1つの分岐を持つ oneOf で、platform がその判別子(discriminator)です。
そのためスキーマを読むエディタは、書かれた platform の subject、runsOn、driver、run のキーを補完できます。
defaults.platforms も同じ platform をキーに持ち、すべてのフィールドを省略可能にしています。デフォルトが
書かなかった部分は、各ターゲットが補うためです。
スキーマは、defaults を重ねる前の、書かれたままのターゲットを検査します。そのため、デフォルトが
補いうるグループはスキーマ上で省略可能です。{ platform: ios } のようなターゲットはスキーマを通りますが、
subject.id を補うデフォルトがなければ、読み込みの段階で拒否されます。
runner¶
汎用の XCUITest runner をビルドします。
現在のサブコマンドは build --device の 1 つだけで、実機の iPhone や iPad 向けに runner を署名してビルドします。署名はユーザーごとの署名ファイルから取り、ビルド結果はキャッシュに置きます。以後、runsOn.ios.kind: device を指定して driver.runner.testRunner を指定しないターゲットは、そのキャッシュに解決します。このビルドは Xcode のある macOS で行うオーサリングの手順で、bajutsu run の中では動きません。署名ファイル、キャッシュのキー、実行時のエラーは iOS の実機で説明しています。
bajutsu runner build --device [--signing PATH] [--out DIR] [--force]
| オプション | 意味 |
|---|---|
--device |
署名済みの実機用 runner をビルドします。現在は必須です。このフラグは、将来 Simulator 用のビルドを加える余地として残しています。 |
--signing PATH |
署名ファイルです。省略すると BAJUTSU_SIGNING_FILE、次に ~/.config/bajutsu/signing.yaml(XDG_CONFIG_HOME に従います)を使います。 |
--out DIR |
Products ディレクトリ全体を DIR にもコピーします。パッケージング(Device Farm の経路)用です。DIR は空か、存在しないディレクトリにします。 |
--force |
一致するビルドがキャッシュにあっても、ビルドし直します。 |
ビルドに成功すると、キャッシュした runner のパスを表示し、終了コード 0 で終了します。--device を省くと使い方の誤りとして終了コード 2 で終了します。それ以外の場合は終了コード 1 で終了し、原因を示します。原因は、前提条件の不足、署名ファイルの誤り、ビルドの失敗のいずれかです。
環境変数(.env)¶
_bootstrap(@app.callback)が全コマンドの前に .env を読みます(実装: bajutsu/dotenv.py)。
KEY=VALUE形式。#コメント、空行、export接頭、クォートに対応。- 既存の環境変数を上書きしません(実環境の値が常に勝つ)。
.envはフォールバックです。 - 読み先は既定
.env、BAJUTSU_DOTENVで変更可能。.gitignore済み。 - 主な用途:
ANTHROPIC_API_KEY(record、crawlと、既定で動くアラートガード)。 - AI プロバイダ(BE-0053):
BAJUTSU_AI_PROVIDER=bedrockを設定すると、Anthropic API ではなく Amazon Bedrock 経由で Claude を呼びます。認証は標準の AWS 認証情報チェーン(環境変数 / 共有 プロファイル / インスタンスまたはロール)で行うため、このパスではANTHROPIC_API_KEYは不要です。BAJUTSU_BEDROCK_MODELにはプロバイダ接頭辞付きのモデル id(例global.anthropic.claude-opus-4-6-v1。 素の Anthropic id は Bedrock では無効)、AWS_REGIONにはリージョンを設定します。既定は Anthropic です。この選択はrecord、crawl、triage、アラートガードに共通で効きます。 - Anthropic CLI(BE-0163):
BAJUTSU_AI_PROVIDER=ant(またはai.provider: ant)を設定すると、公式のantCLI 経由で Claude を呼びます。ant auth login(ブラウザ経由の OAuth(SSO)サインイン)を実行 すると、API キーの代わりに Claude の Pro / Max / Console のシートに課金されます。ANTHROPIC_PROFILEで名前付きの CLI プロファイルを選べます。ANTHROPIC_API_KEYは不要で、すべての AI 経路で画像も そのまま使えます。 BAJUTSU_SIGNING_FILE(BE-0456): 実機用 runner のユーザーごとの署名ファイルです。runner build --deviceと、実機での実行が読みます。
# .env:Anthropic(既定)
ANTHROPIC_API_KEY=sk-ant-...
# .env:代わりに Amazon Bedrock(AWS 認証情報で認証)
BAJUTSU_AI_PROVIDER=bedrock
BAJUTSU_BEDROCK_MODEL=global.anthropic.claude-opus-4-6-v1
AWS_REGION=us-east-1
# .env:代わりに Anthropic CLI(API キー不要。先に `ant auth login` を実行)
BAJUTSU_AI_PROVIDER=ant
# ANTHROPIC_PROFILE=work # 任意: 名前付きの ant CLI プロファイルを選ぶ
実行時の診断(BAJUTSU_LOG_LEVEL)¶
BAJUTSU_LOG_LEVEL は、実行が自身についてどれだけ語るかを決めます。既定は WARNING で、この
つまみが無かった頃と同じ出力です。診断を有効にするのは常に意図的な操作になります。
BAJUTSU_LOG_LEVEL=DEBUG uv run bajutsu run --scenario …
DEBUG が要るのは、ステップが失敗したのにアサーションの文言では理由が分からないときです。つまり
タイミングの失敗で、問うべきなのはアサーションが何と言ったかではなく、アクチュエータがどのツリー
から解決したかです。adb バックエンドでは、各読み取りとそのデバイスイベントマーク、読み取り遅延の
バリアがいつ張られ何によって閉じたか、ツリーがどう落ち着いたか、各セレクタが解決したフレーム、
そしてジェスチャがデバイスへ渡ったか座標注入へ縮退したかを記録します。これらを並べて読むと、
タップが実際にどこへ落ちたのか、その下の画面が追いついていたのかが分かります。
このうち 2 つは debug ではなく警告です。どちらも、ドライバが保証できない画面に対してアクチュエータ がこれから解決しようとしていることを意味するからです。読み取り遅延のバリアが予算を使い切った場合と、 ツリーが動いたまま settle のポーリングが期限を超えた場合です。どちらも判断の根拠とした値を出力する ので、レーンの失敗は再実行ではなくログから診断できます。
serve だけは例外です。serve は同じ変数を読んで自身の運用ログのレベルを決め、root ロガーに秘密情報を
伏せるシンクを持っています(BE-0055)。その横に伏せない出力をもう 1 つ足さないよう、CLI は serve の
ログ設定に手を触れません。
実装は bajutsu/common/diagnostics.py です。Android の e2e レーンは既定を
WARNING にしています。読み取りごとに 1 行出るとレーンが目に見えて長くなるためです。1 回だけ上げる
には make -C demos/showcase/android e2e E2E_LOG_LEVEL=DEBUG を使います。