English · 日本語
アーキテクチャとモジュール関係¶
どのモジュールが何を担当し、どこに依存するか。また 設計(
DESIGN.md)に あるが現状まだ配線されていない機能 を明示します。
関連: concepts · 開発者ガイド(クラス単位の読解案内) · 各機能ページ(下のリンク)
データフローの全体像¶
シナリオは、AI または人手で作成する共有の成果物です。run はシナリオを、ゲートに AI を置かずに決定的にリプレイします。codegen と triage もシナリオを入力として使います。
作業は 2 つの Tier に分かれます。
- Tier 1(AI、図では黄)は、シナリオのオーサリングと失敗の調査を担います。
- Tier 2(決定的、図では青)は、機械アサーションだけで合否を決めます。
決定的な中核全体はプラットフォーム非依存です。プラットフォーム固有の継ぎ目は、orchestrator が駆動する backend だけです。iOS は XCUITest、Android は adb、web は playwright といった実体が、いずれも 1 つの Driver インターフェースの背後にあります。したがって、新しいプラットフォームは新しい backend であって、コアの fork ではありません。
Mermaid ソース
flowchart TB
goal(["🗣️ 自然言語ゴール"])
hand(["✍️ 人手編集"])
scenario[["📄 シナリオ (YAML)"]]
subgraph tier1["Tier 1 · AI — 著者 / 失敗調査役"]
record["record / crawl<br/>探索 + オーサリング"]
agent["Claude エージェント<br/>+ システムアラートガード"]
record <--> agent
end
subgraph tier2["Tier 2 · 決定的 run — CI ゲートに AI なし"]
orch["Orchestrator<br/>observe → act → verify"]
driver["backend 非依存ドライバ API<br/>tap · type · swipe · wait · query · screenshot"]
xcuitest["XCUITest バックエンド<br/>📱 iOS Simulator (常駐 runner)"]
adb["adb バックエンド<br/>🤖 Android"]
pw["playwright バックエンド<br/>🌐 web ブラウザ"]
orch --> driver
driver --> xcuitest
driver --> adb
driver --> pw
end
verdict{"合否<br/>機械アサーションのみ"}
report["📊 Reporter<br/>manifest.json · JUnit · CTRF · HTML"]
codegen["codegen<br/>→ XCUITest / Playwright / UI Automator"]
triage["triage<br/>原因 + 修正案 · 助言のみ"]
goal --> record
record ==> scenario
hand ==> scenario
scenario ==> orch
scenario -.-> codegen
orch --> verdict
orch --> report
verdict -->|失敗| triage
triage -.->|修正案| scenario
classDef ai fill:#fde68a,stroke:#d97706,color:#1f2937;
classDef det fill:#bfdbfe,stroke:#2563eb,color:#1f2937;
class tier1 ai
class tier2 det
下の依存レイヤ図は、同じシステムをデータフローではなくモジュール層として示します。
モジュール一覧と役割¶
bajutsu/ パッケージ(Python 3.13+、pydantic v2 / typer / anthropic / pyyaml / jinja2)。
| モジュール | 役割 | ページ |
|---|---|---|
common/drivers/base |
Driver Protocol、共通型(Element/Selector/Point)、セレクタ解決(決定性の核)を持ちます。 |
selectors / drivers |
common/drivers/actuation |
Actuation/ActuationLog です。各ドライバがステップの結果へ書き足す、具体的なジェスチャーの記録です。座標、経路、プラットフォームが受理したかを持ちます。actionLog 証跡種別を支えます(BE-0345)。 |
evidence |
common/drivers/coordinate_tree.py |
CoordinateTreeDriver です。座標系のバックエンド(adb)が継承する共有基底クラスです(BE-0254)。一時的な空ツリーへのリトライ、安定キーによる settle、_resolve、wait_for を提供します。 |
drivers |
common/drivers/fake |
インメモリの FakeDriver(実機不要テスト用) |
drivers |
common/drivers/xcuitest |
XCUITest バックエンド(iOS)です。BE-0290 で idb を撤去して以来、iOS の唯一の backend です。実機上に常駐する runner が、semantic tap / ネイティブ条件待ち / テキスト選択 / multi-touch を提供します(BE-0019)。 | drivers |
common/drivers/adb |
adb バックエンド(Android)です。tap/long_press/double_tap は、resident server の POST /act で端末側にて解決し、inject します。channel が使えないときは、uiautomator dump による frame 中心の座標 tap にフォールバックします(BE-0339)。 |
drivers |
common/drivers/playwright |
Playwright web バックエンド(ブラウザ)です。第一段で、決定的 run を扱います。 | drivers |
common/drivers/xcuitest_live |
live-route の XCUITest ドライバです。常駐 runner のチャネルの代わりに、予約済みのデバイスクラウド上の iOS デバイスを W3C WebDriver(Appium の XCUITest ドライバ)で駆動します。appium デバイスプロバイダ向けです(BE-0238)。実装済みなのは、セッションのライフサイクル、query/tap/screenshot/readiness、ジェスチャ、テキスト入力です。selectAll/copy は Appium 側に相当機能がなく、明示的に失敗します。paste も、編集メニューを使う組み合わせをこの経路に配線していないため、明示的に失敗します。実デバイスクラウドのグリッドに対する検証は未了です(BE-0303)。 |
— |
common/drivers/elements.py |
正規化済み要素ツリーに対する、プラットフォーム非依存の述語と幾何ヘルパー(screen_size_from_elements、shows_app_ui)です。assertions、crawl、runner パイプライン、record が共有します。 |
drivers |
common/drivers/dom.py |
DOM → Element の正規化です。Playwright バックエンドと WebView ブリッジが共有します。 |
drivers |
common/drivers/web_network.py |
web のネットワーク観測です。Playwright 側の Collector が、requestfinished を iOS 側と同じ NetworkExchange モデルへ橋渡しします。page.route によるプロセス内 mock スタブも持ちます。 |
drivers |
common/drivers/webview |
web: ブロックが WebView の DOM を読む経路です。iOS では BajutsuKit ブリッジのクライアント(WebViewBridge)で、DOM 取得と tap 発行を HTTP 経由で実施します。Android では Chrome DevTools Protocol のソース(CdpDomSource、BE-0482)で、WebView 自身の DevTools ソケットを adb で転送します。 |
drivers |
common/drivers/zorder |
z 順応答クライアントです。BajutsuKit の nativeZ チャネルの Python 側です(BE-0355)。 |
drivers |
common/scenario/ |
シナリオスキーマ(pydantic 厳格検証)と YAML 読込 / 書出です。パッケージの構成は models / load / load_expanded / expand / select / serialize / edit です。 |
scenarios |
common/assertions/ |
機械アサーション評価です。総関数であり、例外を投げません。パッケージの構成は evaluate / network / visual / schema / _common です(BE-0250)。 |
selectors |
common/orchestrator/ |
決定的 Tier 2 run ループ(act → wait → verify)です。パッケージの構成は loop / waits / substitution / evidence_rules / actions / control_channel です。 |
run-loop |
common/cancellation.py |
協調的キャンセル(BE-0370)です。orchestrator の wait ループと runner がポーリングする、読み取り専用の CancelSource を持ちます。あわせて、poll ループが安全な境界まで巻き戻すために投げる RunCancelled 例外と、bajutsu run のエントリポイントが組み込む SIGTERM → イベントのブリッジを持ちます。Bajutsu の他モジュールを一切 import しないため、決定的コア、CLI、serve のいずれからも参照できます。 |
run-loop |
common/evidence/ |
証跡の取得を役割ごとに分けたパッケージです(BE-0257)。core は瞬時 / 区間の取得と Sink を担います。intervals は video / deviceLog の simctl 子プロセスを管理します。media は完了した録画の再生時間をファイルから読み取ります。network は collector とプロトコル内の決定的モックです。visual はビジュアルリグレッションの画像比較です。golden は要素ツリー比較です。redaction は、ラベル / ヘッダ / フィールドとシークレット値を対象にします。 |
evidence |
common/report/ |
manifest.json / JUnit XML / CTRF JSON / インタラクティブ HTML のほか、完了した run の .zip エクスポートと、オフライン再読込(再描画用)を持ちます。構成は format / manifest / ctrf / rows / panels / html / richtext / archive / load です。from_grouping.py は rows.py が使う行グルーピングのヘルパーです。 |
reporting |
common/scenario/interp.py |
${ns.key} 補間プリミティブ(params. / row. / secrets. / vars.) |
scenarios |
common/mailbox.py |
email ステップ(BE-0046)向けの、純粋でネットワークを使わない照合・抽出ロジックです。メールボックスプロバイダのメッセージを正規化し、to/subject/subjectMatches で照合します。ステップ開始後に届いたメッセージだけを選びます。正規表現で値を ${vars.*} に取り出します。 |
scenarios |
common/totp.py |
totp ステップ(BE-0046)向けの RFC 6238 時刻ベースワンタイムパスワード(TOTP)です。共有シークレットと時刻の純粋で決定的な関数なので、ネットワークもデバイスも使わずにコードを導出できます。 |
scenarios |
config/ |
チーム既定 × アプリ別の解決(Effective)です。パッケージの構成は schema / effective / resolve / accessors / preconditions / json_schema です。schema は target のグループごとのモデル(services、hooks、evidence、paths)を持ちます。schema の _merge は、検証の前に defaults を各 target へ畳み込みます。schema の _templates は、target の extends を _merge が defaults に重ねる層の並びへ展開します(BE-0471)。schema の platform/ レジストリは、各プラットフォームの subject / runsOn / driver のモデルを供給します。runsOn は、そのプラットフォームが許す宛先ごとに 1 つのブロックを持ちます(BE-0469)。load_config(text, path=, root=) と load_config_file(path, root=) は config 自身のパスとスイートのルートを受け取ります。hooks の中の use: コンポーネントは、config を読み込むときに解決します。preconditions は、シナリオの preconditions を、そのシナリオが動かす各 target に重ね合わせます。json_schema は、bajutsu config schema のために、モデルとレジストリから config の JSON Schema を組み立てます(BE-0452)。 |
configuration |
common/backends.py |
バックエンド可用性判定、actuator 選択(プラットフォーム対応レジストリ: ios / android / web / fake)、Driver 生成です。 |
drivers |
common/devices/ |
バックエンド間で共有するデバイス識別のヘルパ(パッケージ)です。os.py は、device_runtime ラベルから読む、解析済みのデバイス OS(プラットフォーム/メジャー/マイナー)です(BE-0358)。id.py は、各バックエンドの --udid/config が共有するデバイス id バリデータで、argv オプションインジェクションを防ぎます。errors.py は、simctl/adb が継承するプラットフォーム中立な DeviceError 基底です(BE-0260)。その下に、デバイス操作が失敗ではなく期限の超過で終わったときにどのバックエンドも送出する DeviceTimeout を置きます(BE-0374)。version.py は、runsOn のバージョン範囲を読む、npm の範囲文法の VersionSpec です。facts.py は、runsOn の条件が比べる値を、利用できる各デバイスから読みます。Simulator からは、デバイスタイプ名、ファミリー、ランタイムを読みます。iOS 実機からは、devicectl でファミリーを読みます。両者が混在するプール(BE-0468)も対象です。Android デバイスからは、API レベルと Android Virtual Device(AVD)名を読みます。ブラウザからは、バージョンを読みます。runs.py は、リストと範囲からシナリオの run を作ります。kind に並べた種類ごとにも run を作り、各 run の family の優先順位リストを解決します。そのうえで run をターゲットをまたいで組み合わせ、各 run が使える適格なデバイスを選びます(BE-0452、BE-0468)。browsers.py は、runsOn.browser.kind が指すブラウザの種類と、それぞれを起動する Playwright のエンジンとチャネルです(BE-0468)。 |
drivers |
common/backend_cli/ |
バックエンドのコマンドラインラッパ(パッケージ)です。simctl.py は simctl ラッパで、erase/boot/launch/openurl/io を扱います。adb.py は Android バックエンドのコマンド構築側で、clean-state/launch/deeplink/input/screencap を扱います。simctl の双子です。adb_resident/ は、常駐 UI Automator サーバチャネルの Python 側で、接続 / 待機バジェット / 読み取りタイムアウトのリトライ・再起動リカバリを担います(BE-0245 / BE-0477)。 |
drivers |
common/platform_lifecycle/ |
Environment の seam です(BE-0009)。1 つの RunEnvironment/CrawlEnvironment Protocol が、プラットフォームごとにアプリ起動 / readiness / relaunch / デバイス制御 / teardown を担います。そのため common/runner/ と crawl/cli.py は、actuator 名で分岐せず、iOS/Android/web を同じインターフェースを通じて駆動します。構成は protocols / factories / readiness / relaunchers / device_control / read_session / webview_source です。webview_source は、各プラットフォームの web: ブロックが使う DOM ソースを選びます(BE-0482)。environments/ は ios / xcuitest / xcuitest_live / android / web / fake を持ちます。device_runner/ は、XCUITest runner をユーザーごとに署名して実機向けにビルドするものです(BE-0456)。 |
— |
preflight.py |
バックエンド別の実行可能ゲートです(iOS: 必須 CLI + 起動済みシミュレータ / web: Playwright とその Chromium ブラウザ)。 | configuration |
common/capability/worker_capability.py |
worker 能力ファイル(worker.yaml。同梱の既定が隣に置かれます)を読み込んで検証します。capability_preflight が、このファイルとホストの OS に照らして各シナリオを、デバイスを確保する前に判定します(BE-0450) |
drivers |
requirements.py |
単一の宣言的マッピングです。backend / capability から pip extra + 外部ツールのプローブ + インストール方法へ対応づけます(BE-0164)。preflight と provision が共有します。 |
— |
provision.py |
config 対応の環境インストーラです(BE-0164)。config の backend と AI プロバイダを解決します。必要な extra とツールだけを冪等に導入します(make install)。 |
— |
common/runner/ |
config とシナリオからレポートを作ります。デバイスプールと launch 手順も持ちます。device_provider の seam が、run のデバイスをどこから調達するかを解決します。組み込みの local は pass-through です。appium provider は、予約済みの実機 iOS デバイスを Appium/WebDriver エンドポイント越しにエンドツーエンドで駆動します(BE-0238)。この provider は target のキーではなく、worker.yaml の appium environment で選びます(BE-0452)。他のクラウドベンダ種別は今後の追加課題です。recovery はバックエンドクラッシュのリトライ回数と wall-clock 予算の判定を持ちます。オンデバイスのドライバ適合性スイートもこの判定を共有します(BE-0334)。recovery は、障害を分類する述語も 2 つ持ちます。recovers_by_respawn が再試行を判断し、is_host_fault がホスト側に原因のある失敗を診断します。固まったデバイスは、この 2 つに違う答えを返します(BE-0378)。is_host_fault が名指しするのはプラットフォーム中立な DeviceTimeout なので、この基底を採用したバックエンドはすべて対象に入ります(BE-0374)。後続シナリオを止める run 単位のラッチも recovery にあり、復旧を諦めた理由(予算を使い切ったのか、ホストが固まったのか)を保持します。さらに recovery は、pool の teardown 箇所、launch_driver、オンデバイススイートの lease 破棄が共有する、守られた teardown の方針も持ちます(BE-0342)。mailbox は email ステップの transport を、kind で鍵付けしたレジストリで解決します(出荷済みなのは http の JSON アダプタ、BE-0186)。形は ai/registry.py を踏襲します。パッケージの構成は pipeline / pool / launch / device_provider / recovery / mailbox です。 |
run-loop |
common/run_meta/ |
複数の機能が共有する run メタデータのヘルパ(パッケージ)です。files.py は、runs ルート名と、run ディレクトリのパスを介さない読み取り(一覧、manifest)です。id.py は run id の生成と解析です。root.py は run ディレクトリの書き込みプロバイダです(BE-0331)。後述の import 契約を参照してください。artifact_perms.py は、run の成果物への owner-only な 0700/0600 権限です(BE-0131)。object_store.py は、証跡アップロードとサーバストレージ向けのバックエンド中立な ObjectStore で、local/S3/GCS を扱います(BE-0110/BE-0204)。 |
configuration |
run/notify |
bajutsu run 完了後に送る run 完了通知(Slack など)です。 |
— |
common/doctor/ |
規約充足度スコア(id カバレッジ等) | configuration |
agents/ |
AI / オーサリングエージェントの periphery です(BE-0257)。protocols と factory は、Observation/Proposal/Agent 抽象と、唯一の SDK エージェントの構築を担います。claude はオーサリングエージェントです。claude_backed は共有基底です(BE-0246)。claude_enrich と claude_triage も含みます。ai_config はプロバイダ/モデル/effort/言語を解決します。anthropic_client は SDK クライアントを構築します。availability は資格情報の欠如をメッセージ化します。enrich は enrichment ループです。alerts はシステムアラートガードです。 |
recording |
ai/ |
ベンダー中立な AI バックエンドのシームです(BE-0104)。base は AiBackend プロトコルと、正規化した request/response 型です。registry はプロバイダレジストリで、登録済みのプロバイダは、agents.anthropic_client の上に立つ Anthropic 参照アダプタ(anthropic)による Anthropic API と Amazon Bedrock、Anthropic CLI ant(同じく anthropic アダプタ経由、BE-0163)、Claude Code CLI(claude_code、BE-0176)、そしてファクトリが例外を送出してどの AI 経路にもバックエンドを構築させない none(disabled、BE-0394)です。 |
configuration |
run/ |
bajutsu run の CLI コマンド(cli.py)です。target/backend 解決、デバイスの lease 取得、plan 構築、決定的な run/report ディスパッチを担います。公開コマンドは薄いラッパーです。この本体を子プロセス python -m bajutsu.run.internal(internal.py)として、bajutsu worker --once と同じ 1 回実行の worker 経路で実行します。serve の仕様ビルダーも同じモジュールを出力します(BE-0449)。device_matrix.py は、各シナリオが動かすターゲットの runsOn の条件から、呼び出し全体の run を計画します。同じデバイスを使う run をセルにまとめ、セルは 1 回のパスとして実行します(BE-0452)。 |
cli |
record/ |
record ループ(observe → 提案 → 実行 → 書き出し)です。パッケージの構成は、loop.py、tap/type/swipe のプロキシ actuation をシナリオステップに解決する capture.py、その CLI コマンドの cli.py です。 |
recording |
crawl/ |
自律的な幅優先クロール → スクリーンマップです。構成は、core エンジンと serialize、guide / tabs / report / repro / flows です。CLI コマンドは cli.py です。 |
recording |
repl/ |
AI を使わない手動シェルです(BE-0423)。render.py が要素ツリーを表示します。session.py がコマンド集合(tree / find / tap / type / scroll / back / screenshot / step、さらに完全なセレクタを書けるエスケープハッチ --sel)です。tui.py は、対話的な端末でデフォルトになる ncurses 風シェルです。loop.py は、それ以外の場合に使われる素の bajutsu> プロンプトループです(BE-0429)。cli.py がその CLI コマンドです。cli.py の --attach(BE-0455)は、起動済みの Simulator で動いているアプリを再起動せずに操作します。 |
cli |
codegen/ |
シナリオ → ネイティブテスト生成です。対象は XCUITest(Swift)、Playwright(TypeScript)、UI Automator(Kotlin)です。CLI コマンドは cli.py です。 |
codegen |
triage/ |
M4 自己修復です。ルールベース HeuristicTriageAgent と構造化 fix(renameId/addIndex/raiseTimeout)を持ち、--apply/--write/--rerun を備えます。パッケージの構成は、heuristic.py と、その CLI コマンドの cli.py です。 |
cli |
common/github/ |
GitHub ヘルパです。actions は、CI(継続的インテグレーション)のアノテーションとジョブサマリを扱います。app は、プライベートリポジトリの config source 向けの App インストールトークンです。errors は共有するアクセスエラーです。 |
ci |
common/analytics/ |
役割で分けたトークン/コストの集計です(BE-0257)。usage はプロセスグローバルでインメモリのベストエフォートです。ledger は、帰属付きで永続化する AI 使用量/コスト台帳です(BE-0196)。stats は、serve の使用量ダッシュボード向けに台帳を集計します(BE-0195)。 |
web-ui |
common/cloud/ |
決定的な run/CI の判定パスの外側で、バッチ送信先として利用するクラウドデバイスバックエンドです。devicefarm.py が最初の具体的プロバイダです。 |
devicefarm |
serve/ |
ローカル Web UI(serve コマンド)です。オーサリング / 実行 / レポート / 失敗した run の triage を行います。サーバ自身は job を実行しないので、それぞれを job として bajutsu worker のキューに積みます(BE-0449)。serve/worker/approve の CLI コマンドは cli/(機能ごとに 1 ファイル)にあります。capabilities.py は、キューのジョブを、そのジョブが必要とするトークンをすべて広告するワーカーへ振り分けます。必要とするトークンは、プラットフォームと、ドライバが 1 つの OS でしか動かない場合の host:<os> です。ターゲットの runsOn.ios.family があれば、そのデバイスファミリーのトークンも必要とし、ファミリーの優先順位リストは any-of のグループ 1 つになります。ステップと設定が必要とする環境ルートごとの cap: / setting: トークンも使います(common/capability/route_tokens.py、BE-0467)。ワーカーは自分のマシンの host:<os> を広告します。ファミリーのトークンは Simulator の在庫から、device:<family> は接続中の実機から広告します(BE-0166、BE-0450、BE-0468)。run-set のジョブは job:run-intent と、iOS なら実行する種類ごとに 1 つの kind:<kind> トークンとターゲットのファミリーのトークンを必要とします。host: と environment: のトークンは必要としないので、そのプラットフォームを扱い、条件に合うデバイスを持つワーカーなら、Device Farm のワーカーも含めて受け取れます。ただし、runsOn.ios.family を指定したターゲットは、Device Farm のワーカーには届きません。Device Farm のワーカーはファミリーのトークンを広告しないためです(BE-0484)。 |
cli · self-hosting |
mcp/ |
MCP サーバです。run/doctor をツールとして、実行証跡をリソースとして公開します。CLI コマンドは cli.py です。 |
cli |
common/lint.py |
シナリオ linter と JSON Schema 生成です(lint / schema コマンド)。 |
cli |
common/target_lint.py |
lint --config --target です。run と同じステップ・設定・前提条件のチェックを、デバイスなしでターゲットごとに行います(BE-0467)。 |
cli |
analysis/ |
実機も AI も使わない読み取り専用の助言的分析パッケージです(BE-0257)。CI を止めません。audit は決定性・フレーキネス監査です(BE-0049)。coverage はシナリオの id 名前空間カバレッジです(BE-0050)。impact は、diff から影響ステップを選ぶテスト影響分析です(BE-0321)。stats は集計 run 統計ダッシュボードです(BE-0102)。flakiness はクロスランのフレーキネスランキングです(BE-0220)。trace.py は trace タイムラインで、bajutsu trace コマンドの本体です。それぞれの Typer コマンドは cli/(機能ごとに 1 ファイル)にあります。 |
cli |
cli/ |
Typer アプリの組み立てです。各機能自身の CLI(run/crawl/record/repl/triage/mcp/codegen/serve/analysis)と、機能を持たない commands/(doctor/lint/schema/config/report/runner)、.env ローダ(dotenv.py)をマウントします。 |
cli |
common/screenshots.py |
AI 経路が共有するスクリーンショット取得 + ピクセル座標のヘルパ(screenshot_bytes、png_size、fraction、BE-0246) |
recording |
common/handoff/ |
人手介在ハンドオフの契約です(Tier 1、BE-0179)。transport 中立なリクエスト/レスポンスを定め、record(端末の stdin)と serve(SSE)が同じように実装します。 |
recording |
common/deprecations.py |
改名済みのオーサリング/CLI 表記への一度きりの非推奨通知(warn_once)と、廃止済み表記への明示的な拒否(reject_renamed_key) |
— |
common/diagnostics.py |
プロセス全体のロギング設定。run が自分自身について何をどれだけ語るか | — |
common/stall_diagnostics.py |
バックエンドが stall した瞬間の、範囲を限定したベストエフォートな状態取得(BE-0361/BE-0367) | — |
common/_yaml.py |
on/off/yes/no を文字列のまま読む YAML ローダ |
scenarios |
依存関係とレイヤ¶
下層ほど安定していて、上層が下層に依存します。中核は common/drivers/base(セレクタ解決)で、すべての実行系が中核に依存します。
Mermaid ソース
flowchart TB
cli["cli/<br/>ユーザ接点(Typer): run · doctor · audit · coverage · impact · stats ·<br/>flakiness · export · trace · report · triage · record · crawl · repl · codegen ·<br/>approve · serve · mcp · worker · lint · schema"]
runner["runner/"]
record["record.py / crawl/<br/>(Tier 1 / AI)"]
codegen["codegen/<br/>(構造マッピング)"]
trace["trace.py<br/>(タイムライン)"]
triage["triage.py / agents/claude_triage<br/>(自己修復・助言)"]
orch["orchestrator/"]
agentStuff["agents/<br/>(protocols・factory・claude・alerts 等)"]
serveGh["serve/ · github/<br/>(Web UI・CI)"]
assertions["assertions/"]
evidence["evidence/<br/>(core + intervals・network・visual・golden・redaction)"]
scenario["scenario/<br/>(interp.py)"]
report["report/"]
config["config/ · preflight.py"]
backends["backends.py"]
simctl["simctl.py"]
base["drivers/base<br/>決定性の核(Element / Selector / resolve_unique)"]
fake["drivers/fake"]
ios["drivers/xcuitest・adb"]
pw["drivers/playwright"]
cli --> runner
cli --> record
cli --> codegen
cli --> trace
cli --> triage
runner --> orch
record --> agentStuff
triage --> serveGh
orch --> assertions
orch --> evidence
agentStuff --> assertions
assertions --> scenario
evidence --> report
orch --> config
orch --> backends
orch --> simctl
scenario --> base
report --> base
config --> base
backends --> base
simctl --> base
base --> fake
base --> ios
base --> pw
common/orchestrator/はbase.Driverにのみ依存し、どの具象ドライバとも結合しません。そのためFakeDriverで実機なしにテストでき、本番では同じループが XCUITest(iOS)や playwright(web)を駆動します。common/runner/はアプリを起動して準備済みドライバを返す factory を提供し、ループを実機から分離します。scenario/(オーサリング表現の pydantic モデル)とcommon/drivers/base(実行時の TypedDict)は別物です。Selector.as_selector()が前者を後者へ変換します。
強制されるレイヤ境界(BE-0112)¶
上のレイヤ分けは規約にとどまらず、ゲートで実行可能な契約として強制します。make lint-imports(make check の一部であり、CI のステップでもあります)は、宣言したレイヤに対して import-linter を実行します。禁止された import は、誰かが気付くまで残らず、その場でゲートを落とします。設定は pyproject.toml の [tool.importlinter] にあり、3 つのレイヤを宣言します。
- 決定性コア:モデルにも periphery のスタックにも触れずに、判定と証跡を導く経路です。
common/orchestrator/、common/runner/、common/drivers/base、assertions/、evidence/、report/、config/、scenario/、preflight.py/capability_preflight.py/capabilities.py/worker_capability.py、common/doctor/、common/lint.py/common/target_lint.pyが含まれます。コアは prime directive を担います。 - 契約(contract):利用者が依存する安定した界面です。シナリオスキーマ(
scenario/)とDriverProtocol(common/drivers/base)が当たります。 - periphery:契約の利用側で、いずれもオプションの extra の背後に切り離せます。
serve/、mcp/、codegen のエミッタ。- AI / エージェント経路:
agents/以下のprotocols、ai_config、anthropic_client、enrich、alertsなど、加えてrecord/、triage/、crawl/guide。 github/actions.pyとrun/notifyのヘルパ。github/の残り(appとerrors)は決定的コアからも参照できるので、config_sourceは periphery を巻き込まずに利用します。
強制する契約は 3 つです。
- 決定性コアは periphery を import してはいけません。 この契約は、prime directive 1 と 3 を静的に強制します。判定と証跡の経路は serve / AI / codegen のスタックから切り離されたままで、それらへの依存が黙って増えることはありません。
- コアのモジュールが必要とする純粋な要素ツリーのヘルパ(
screen_size_from_elements、shows_app_uiなど)は、record/のような periphery のモジュールではなく、コア(bajutsu/common/drivers/elements.py)に置きます。 - 同様に、解決済みの
aiブロック(AiConfig)はconfig/に置きます。コアは AI クライアントを import せずに、このブロックを読みます。 - コアはホスト非依存に保ちます(BE-0129)。 マルチテナントなホスティングの関心事は、
bajutsu/serve/だけが持ちます。関心事とは、組織、ロール、テナンシーと、db(SQLAlchemy、Alembic、psycopg、cryptography)やoauth(Authlib、joserfc)の extra です。 - 組織モデル(
OrgConfig、org_for_*、targets_for_org、load_serve_config)は、config/ではなくbajutsu/serve/orgs.pyにあります。 Configはorgsフィールドを持ちません。コアのローダーは検証の前にトップレベルのorgs:を取り除きます。そのため、組織情報を含む config を読むホスト型構成の run はそのまま動き、コアは組織を一切モデル化しません。- 同じ仕組みが、トップレベルの
ui:キー(BE-0191)も除去します。serve UI のプレゼンテーション設定(ui.default_theme)は serve の関心事です。この設定はbajutsu/serve/themes/で読み取られ、Configではモデル化しません。 - import-linter の forbidden 契約が、
config/、common/drivers/、common/runner/、scenario/をこれらの extra から遠ざけます。include_external_packagesにより、外部 import も検出します。この契約は、同じパッケージをbajutsu.serveから遠ざける periphery 契約の上に重ねたものです。 - シナリオスキーマと
DriverProtocol は、可搬なインナー契約に保ちます。 periphery だけでなく、runtime のコア(common/orchestrator/、common/runner/、config/など)からも独立させます。この独立により、契約は、利用者が runtime を引き込まずに依存できる安定したレイヤになります。バージョンをまたいだスキーマの読み取り(BE-0119)と、将来 periphery をコアから分離する余地も、この独立が下支えします。
このチェックは import グラフに対する静的解析です。モデルは介在せず、決定的な合否以上のものは run / CI の判定経路に載りません。新しいモジュールを追加するときは、そのレイヤが置き場所を決めます。
- 判定と証跡の経路上にあるモジュールはコアであり、periphery に到達してはいけません。
- 契約を利用するモジュールは periphery であり、extra の背後に置きます。
テスト構成¶
tests/ に ユニットテスト一式(uv run pytest -q)があります。どのテストも実機 Simulator を必要としません。コマンドビルダは純関数として検証し、実行系は FakeDriver と注入ランナー(RunFn、Spawn、Clock)で検証します。showcase アプリに対する実機 E2E は、make -C demos/showcase run-swiftui または make -C demos/showcase ui-test で実行します(showcase)。
driver conformance suite(BE-0114)¶
prime directive 3 は、どの backend も 1 つの Driver 界面の背後に置くことを求めます。したがって、決定性の中核となる不変条件は、すべての backend で同一に成り立たなければなりません。backend ごとのテストだけでは、これを保証できません。曖昧なセレクタで最初の一致を tap する backend や、0 件の query に成功を返す backend があっても、自身のテストは通ります。落とす共通テストがないからです。
driver conformance suite は、この隙間を埋めます。1 つの実行可能な契約(technology compatibility kit(TCK)に相当します)が、同じテスト本体をすべての backend に対して走らせます。このスイートは、共通の base だけでなく、実際のドライバのインスタンス(common/drivers/base を迂回するコードを含みます)を駆動します。
契約(tests/driver_conformance.py)は、新しい backend が満たすべき「完了」の定義です。
- 曖昧なセレクタ(2 件以上の一致)は、最初の一致に作用せず失敗します。
- 0 件のセレクタは、成功を報告せず失敗します。
- セレクタの失敗は 1 つのエラー型(
SelectorError)を共有し、backend をまたいで一様です。 - 一意の一致はエラーなく作用し、
query()は画面上の要素を報告します。 capabilities()は観測される挙動と一致します(そうでなければ、該当の呼び出しはそれぞれUnsupportedActionを送出します。BE-0280、BE-0464、BE-0466)。QUERY/ELEMENTSの baseline を申告します。- multi-touch のジェスチャは、
MULTI_TOUCHを申告したときに限り動作します。 - 全選択、クリップボードへのコピー、ペーストは、
TEXT_SELECTIONを申告したときに限り動作します。デバイスのクリップボードを読める harness では、コピーしたテキストがクリップボードに入ったことも確かめます。何もしないコピーはここで失敗します(#2390)。フィールドのvalueを報告するバックエンドでは、空にしたフィールドへのペーストでコピーしたテキストが戻ることも確かめます。 - ネイティブな
<select>を値で設定する操作は、SELECT_OPTIONを申告したときに限り動作します。 - URL の読み込みは、
URL_NAVIGATIONを申告したときに限り動作します。 read_attributesは、ELEMENT_ATTRIBUTEを申告したときに限り、タップと同じ規則で各セレクタを解決して属性を読みます。- フォーカス中のフィールドで、テキスト編集が往復します。入力してから削除すると、報告される文字数が減ります。
tap_pointは生の座標タップで、アラート消去の経路です。フィールドの中心を狙うと、そのフィールドをフォーカスし、semantic tap と同じ観測可能な効果を持ちます(BE-0280)。 wait_forは現在の画面を 1 回だけ判定します。共有のwait_untilループが、それを固定 sleep なしの条件待ちに変えます。scrollの 1 ステップは、連続するビューポートを重ねたまま残します。ステップの前後の読み取りが、領域の枠に切り取られていない要素を少なくとも 1 つ共有する、という形です(BE-0329)。- この契約は、各 backend が非慣性と文書化しているジェスチャを、ツリーが示せる唯一の言葉に言い直したものです。
scrollループの正しさがこの重なりに乗っているため、契約はDriver契約の一部です。- 勢いを残すジェスチャは何も共有しないので、スイートで落ちます。そうでなければ、実行時に対象が、ループの 2 回の query のあいだを読まれないまま通り過ぎます。
scrollの 1 ステップは、その終点が求めた距離だけ進みます。許容差の内側に収まることを、3 つの歩幅で確かめます。既定の歩幅、ループのリカバリが取る最小の歩幅、そして書き手がamountで要求できる、その下限より小さい歩幅です。- 重なりが残ることは、この距離を意味しません。ビューポートが重なったまま、求めた距離よりはるかに先まで進むステップがありうるからです。
- BE-0400 まで、iOS のジェスチャがそうでした。どのドラッグも同じ速さで走査していたため、指を離した後もコンテンツが終点の先へ運ばれ、求めた距離の最大 6 倍まで進みました。どれだけ小さく求めても、画面のおよそ 3 分の 1 より短くは動きませんでした。
- この下限があるために、
scrollアクションで書き手が選ぶamountと、BE-0329 の半減の両方が、どのジェスチャでも実現できない歩幅を名指すことになります。この性質が 1 つのバックエンドのテストではなくDriver契約に属するのは、そのためです。
backend をこのスイートに加えるには、ConformanceHarness(画面を渡すと、それを表示するドライバを返すもの)を実装し、DriverConformanceContract を継承します。すると pytest が、継承した契約をその backend に対して走らせます。契約は同じで、第 2 の仕様はありません。
FakeDriverは、高速な Linux ゲート(make check)で走ります。- Playwright は、web CI ジョブで走ります。
- XCUITest は、iOS のオンデバイス E2E 経路(
ios-e2e.yml)で走ります。 - adb backend は、起動済みの Android エミュレータ(
android-e2e.ymlのconformance (adb)ジョブ、BE-0270)で走ります。
各 harness は、画面をそれぞれの方法で実体化します。
FakeDriverは、要素をそのまま受け取ります。- Playwright は、要素を HTML として描画します。
- オンデバイスの harness は、
SHOWCASE_CONFORMANCEで showcase アプリを一度だけ conformance モードで起動し、以降は画面ごとに再シードします。これにより、共有の base だけでなく、実際の backend の query と操作のコードを駆動します。 - iOS の harness は、アプリがポーリングする spec ファイル(Documents ディレクトリの
conformance-spec.txt)を書き換えて再シードします。画面ごとの再起動や deeplink ではなくファイル書き込みにするのは、simctl openurlが iOS の「アプリで開きますか?」ダイアログを出し、画面ごとの再起動は数回のapp.launch()で常駐 XCUITest ランナーをクラッシュさせるためです。 - adb の harness は、その代わりに、新しい
SHOWCASE_CONFORMANCEの intent extra を載せてアプリのsingleTaskActivity を起動し直し、onNewIntentで届けます。adb pushはアプリのサンドボックスに届きません。インテントなら、subject.launch.envを intent extras として渡す規約(BE-0007)に乗れます。 - adb の harness は、Compose ツールキットに限定します。spec 駆動で任意の id を描く画面を表現できるのは Compose だけです。
testTagは実行時の任意の文字列を受け取りますが、Views のresource-idはコンパイル時のRエントリでなければなりません。
このスイートには ondevice の pytest マーカーが付いています。ゲートの既定ではこのマーカーを除外するので、スイートは make check では決して走りません。共有する 1 台のデバイスを 1 つのチャネルで再シードするため、並列ワーカーどうしが衝突しないよう、直列で実行します。
障害注入レーン(BE-0305)¶
ドライバには、実際のデバイス障害のためだけに存在する機構が 2 つあります。ここまでのスイートは、そのどちらの条件にも出会いません。conformance スイートは読み取りの前に必ず画面の準備完了を待ち、ランナーを意図的に壊すジョブもないからです。
CoordinateTreeDriverの transient-empty リトライ(BE-0254)は、デバイスが遷移途中に返すほぼ空の要素ツリーを乗り越えるために存在します。- XCUITest チャネルの一過性リトライ(BE-0207)と crash-recovery(BE-0287)は、応答しなくなったランナーを乗り越えるために存在します。
これらの機構に対する高速スイートのテストは、要素数を組み立て、合成した例外を送出します。制御フローに対する実質的なカバレッジにはなりますが、実際の条件がそこに到達するかどうかの証拠にはなりません。実際のデバイスは Python の例外を送出しませんし、要素数を見る検出ヒューリスティクスは、組み立てた要素数なら通るまま壊れうるからです。
障害注入レーンは、代わりに実際の条件を注入します。
fault-injection (adb)(android-e2e.yml)は、エミュレータのディスプレイをスリープさせます。すると、実際の読み取り元(常駐 UI Automator チャネルと、その背後のuiautomator dumpフォールバック)が本当に空のツリーを返します。レーンは、リトライがそこを、誤った「要素が見つからない」を出さずに乗り越えることを検証します。2 つ目のケースはディスプレイを落としたまま保ってリトライ予算を使い切らせ、その結末が静かな失敗ではなく明示的なElementNotFoundになることを固定します。3 つ目と 4 つ目のケースは、アクセシビリティイベントを意図的に出さない画面を使います。settle 後の resident の読み取りが変化後の値を返すこと、静止した対象が今までどおり 2 回のダンプで settle することを確かめます(BE-0490)。fault-injection (xcuitest)(ios-e2e.yml)は、ランナー自身のホストプロセスにシグナルを送ります。SIGSTOPは、ソケットを accept できる状態に保ったまま応答を止めます。ホストから見れば、まさに固まったランナーの姿です。短い凍結は一過性リトライが吸収し、リトライ予算を超える凍結は crash-recovery が乗り越えます。SIGKILLでは、無関係なタイムアウトではなく、実行中のランナー障害を名指しするクラッシュ診断で、実行が終わらなければなりません。
どちらのレーンも、障害をどれだけ保つかを推測しません。各ケースは、検証対象の層に到達したというドライバ自身のログ記録(tests/fault_injection.py)を合図に、障害を解除します。したがって、あるケースがどの機構を駆動したかは、sleep の長さではなく、観測された挙動が決めます。
両レーンは現在、それぞれのレーンの必須集約チェックに入っています。着地した時点では、必須チェックの外に置いてありました。BE-0282 が確立した「まずシグナル、のちに必須」の道筋に乗せたためです。意図的にデバイスを壊すレーンは、健全なデバイスを駆動するレーンより、本質的にフレーキーになるリスクが高いからです。その慎重さには根拠がありました。最初の 10 日間で fault-injection (xcuitest) は、52 回の成功に対して 78 回失敗しています。
慎重さを解いたのは、失敗の率が下がったことではなく、原因が判明したことです。
- 78 回の失敗はすべて、ある修正より前に起きています。その修正は、応答を待たずに去った相手へ返信すると SIGPIPE で XCTest のホストプロセスが落ちるという、runner の HTTP サーバの欠陥を直したものです。
- このレーンは runner を
SIGSTOPで止めたまま保ちます。相手が去った接続は、まさにそこから生まれます。したがってレーンは、健全な runner を駆動するどのスイートよりも高い頻度で、その欠陥を踏んでいました。レーンが runner チャネルの実際の不具合を見つけていたわけで、それこそがレーンの存在理由です。 - この修正の後、レーンは 64 回実行して 1 回も失敗していません。同じ期間の
conformance (xcuitest)は、58 回成功して 2 回失敗しています。 fault-injection (adb)は、同じ期間に 73 回実行して失敗は 1 回です。その 1 回は、レーンが検証している内容ではなく、エミュレータが起動しなかったことによるものです。同じ期間のconformance (adb)は、67 回中 4 回失敗しています。- 両レーンはいま、ずっとゲートに乗っているスイートと同等か、それよりよい水準にあります。
_is_transient_empty の閾値やクラッシュ分類器のマッチングに回帰が入れば、それは両レーンが捕まえるために存在する失敗そのものです。シグナルであれば、マージはそれを無視できてしまいます。したがって、必須化こそがこのカバレッジに意味を持たせます。tests/test_e2e_gate_needs.py が、高速スイートで必須化を 3 つの層に分けて固定します。
- 各ゲートがどのジョブに依存するか。
- そのすべてのジョブについて、結果が読まれているか。
- verdict のスクリプト自体を実行して、それぞれの結果が本当にチェックを赤にするか。
これらがなければ、ゲートを狭めることも、永久に green のまま放置することも、どのテストにも気付かれずにできてしまいます。
並行デバイスレーン(BE-0298)¶
ここまでのジョブはどれもデバイスを 1 台しか起動しません。そのため、common/runner/pool.py の device_pool が並列実行に対して主張する保証を、どのジョブも観測できません。その保証とは、--workers N のもとで各ワーカーが固有のデバイスを借り受けることです。さらに各ワーカーは、共有された 1 つの run ディレクトリの下にある固有の run_dir/<sid> サブディレクトリにだけ、証跡を書きます。モックのポートや索引も、ほかのワーカーのシナリオとは共有しません。DESIGN.md §3.3 が述べる「状態を共有しない」不変条件です。
高速スイートが証明できるのは、プール自身の記帳についてだけです。tests/runner/test_pool.py は make_driver を monkeypatch し、FakeDriver インスタンスに "UDID-A" のような架空の udid を渡します。これで示せるのは、プールが管理するデータ構造のなかでワーカー A のリソースがワーカー B のものと分離されていることまでです。そのデータ構造の外側にある、OS とサブプロセスのレベルの競合については、何も語りません。そうした競合には、次のものがあります。
- 起動ロックで競合する、2 つの実際の
simctlやadbの呼び出し。 - デバイスごとに確保されるホストポート。
- ワーカーのサブディレクトリが存在する前に計算される成果物パス。
並行デバイスレーンは、代わりに実際のデバイスを 2 台起動します。pool (adb)(android-e2e.yml)はエミュレータを 2 台起動し、状態に依存しない showcase のシナリオファイル 4 本を、1 回の bajutsu run --workers 2 で走らせます。プールは作業を 2 台へ振り分け、両方のワーカーを同時にビジーに保たなければなりません。
結果を判定に変えるのは scripts/assert_pool_isolation.py です。このスクリプトは、終了した run の manifest.json と、run ディレクトリのサブディレクトリ一覧を読みます。次のいずれかを見つけたら、失敗します。
- ほかのワーカーの slug の下に記録された成果物。
- 1 つの slug を共有する 2 つの結果。
- どの結果にも属さないサブディレクトリ。
- 結果が記録したのに、run が書いていない証跡ディレクトリ。
- 片方のデバイスが、黙ってすべてのシナリオを引き受けたこと。
- 異なるデバイス上の 2 本のシナリオが、実時間で重ならなかったこと。
この検査はファイルの読み取りと集合の比較にすぎません。bajutsu run が自身の判定を返した後に走るので、run の成果物を観測するだけで、どのシナリオの合否にも入力されません。
このジョブは、専用の変更フィルタ(scripts/e2e_changes.py の touches_pool)で発火します。ほかのすべてのジョブが読む、レーン全体を対象としたシグナルより狭いフィルタです。Android レーンのほかのジョブの 2 倍のデバイスを起動するからです。このジョブは PR ごとのシグナルであり、Android レーンの必須集約チェックからは外してあります。BE-0282 の「まずシグナル、のちに必須」の道筋に乗せる点は、障害注入レーンと同じです。外してある理由は、このジョブ固有のものです。1 つの runner でエミュレータを 2 台動かす作業は、このレーンでもっともホストの資源に左右されるからです。
iOS 側の対になるジョブ pool (xcuitest) は、Simulator を 2 台起動して macOS レーンで走っていましたが、BE-0298 で取り下げました。このジョブが分離の判定を返せたのは 5 回のうち 1 回だけです。残る 4 回は、プールの検査ではなくホストで崩れました。
SimRenderServerが、自身のディスパッチキューでクラッシュしました。simctl uninstallが、固まった CoreSimulator に対してタイムアウトしました。- runner のチャネルが、run の途中で到達不能になりました。
しかも赤くなるたびに、10 倍課金の runner を 30 分ほど使いました。BE-0361 は、その runner を 3 コア・7 GiB と実測しています。Simulator を 1 台起動しただけでゲストプロセスが 257 個立ち上がり、物理メモリの未使用分は 189 MB しか残りません。2 台目の Simulator は、すでに飽和した天井に対してゲストの数を倍にします。動画記録、タッチマーカー、シナリオの半分を削っても、崩れる位置が早まっただけで、崩れること自体は変わりませんでした。そのため、実際の並行デバイスに対する分離の検証は Android レーンだけが担い、iOS 側は高速スイートによる記帳の証明だけが残ります。
実装状況¶
設計(
DESIGN.md)には将来像も含まれます。現状のコードが実際に動かすものと まだ配線されていないものを区別します。
実装済み(テストあり、経路が通っている)¶
ドライバとバックエンド選択¶
- セレクタ解決と曖昧検出(決定性の核)。
- プラットフォーム対応の backend レジストリ(
common/backends.py):target の必須キーplatform(ios/android/web/fake)が actuator を決めます。 iosはxcuitestに解決します。BE-0290 で idb を撤去して以来、XCUITest が iOS の唯一の actuator です。--backendはフォールバックのリストではなく検査です。受け付けるのは、target のプラットフォーム、その actuator、fakeのいずれかです。それ以外の値では終了コード 2 で終了します(BE-0452)。- actuator を複数持つプラットフォームであれば、シナリオごとにコスト順で解決します(BE-0240)。iOS が単一 actuator になった今、どのプラットフォームもコスト順と安定度順が食い違いません。
- XCUITest バックエンド(
common/drivers/xcuitest)は、iOS の唯一の actuator です(BE-0290)。実機上に常駐する runner(BajutsuKit)を loopback HTTP 経由で駆動します。 - runner は、semantic(identifier)tap、ネイティブの条件待ち、テキスト選択、
pinch/rotateの multi-touch ジェスチャを提供します。 - runner は XCTest のオートメーションスナップショットを読み取ります。このスナップショットはグループコンテナの内側まで降りるので、座標系 backend と違って完全に展開された要素ツリーを描き出します。
- 汎用の runner(
XCUIApplication(bundleIdentifier:))は、アプリ側の統合なしに任意のアプリを bundle id で駆動します。Xcode のxcodebuildを必要とします(BE-0019)。 - Simulator を対象にした target は、runner の設定を必要としません。
driver.runner.testRunnerとdriver.runner.buildのどちらも指定しないときは、wheel にパッケージデータとして同梱された Simulator 用 runner に解決します。初回利用時に、コンテンツハッシュ鍵の書き込み可能なキャッシュへ展開します。明示的なtestRunnerやbuildは、この既定より優先します(BE-0292)。 - 実機(
runsOn.ios.kind: device)でtestRunnerがないときは、ユーザーごとの署名済みビルドに解決します(environments/device_runner/、BE-0456)。このビルドはbajutsu runner build --deviceがキャッシュしたものです。ビルドがなければ、ビルドコマンドを示して失敗します。実行中に署名済み runner をビルドすることはありません。 - 実機はホストとループバックを共有しません。そのため runner、
nativeZ、WebView のポートは usbmuxd で橋渡しします(environments/xcuitest/_usbmux.py)。環境のreach_device_portがこの橋渡しを開きます。ホストの127.0.0.1で待ち受け、各接続を実機上のポートへトンネルします。Android の常駐チャネルが使うadb forwardに相当する仕組みです。 - ネットワークの collector は逆向きの通信です。実機では collector がすべてのインタフェースで待ち受けます(
collector_host)。アプリにはホストのアドレスの候補を渡します(environments/xcuitest/_host_address.py)。アプリは各候補へ署名付きのGET /pingを送り、collector の署名付きで最初に応答した候補を使います。 - ループバックの外では、トークンを送りません。アプリは、各要求のメソッド、パス、nonce、本文に、HMAC(Keyed-Hash Message Authentication Code)で署名します。collector は、使用済みの nonce を 409 で拒否し、Bearer ヘッダーを 401 で拒否します。collector は各応答にも、要求の nonce に対する署名を付けます(
common/evidence/network/_hmac_auth.py、BE-0459)。 - プールは
BAJUTSU_COLLECTOR_AUTH=hmacで署名方式を知らせます。ループバックの collector は、Android と古い BajutsuKit で作ったアプリのために、Bearer ヘッダーも受け付けます。 BajutsuKit/自身のソースを持つチェックアウトでは、ソースがバンドルより新しくなった時点で、このバンドルは自動で再ビルドされます。make serveに限らず、bundled tier のあらゆる入口が同じ関数で再ビルドします。詳細はdocs/specs/xcuitest-bundled-runner-auto-refresh.mdを参照してください。SFSafariViewControllerの要素ツリーを、それを描画しているプロセスcom.apple.SafariViewServiceから読み取ります(BE-0396)。iOS 26 では、アプリ自身の XCTest スナップショットがこのプロセス境界で止まってしまいます。- XCUITest バックエンドは、このサービスがフォアグラウンドにあるときに限り、サービス自身のハンドルから取得した第 2 のスナップショットを合成します。アプリ側が同じサブツリーを重複して映し出す部分は剪定し、二重報告を避けます。
tap、doubleTap、press(forDuration:)は、要素の live な frame 中心を対象に actuation します。ブラウザの chrome が黙って無視してしまう、XCUIElement自身の呼び出しは使いません。- 閉じるボタンに identifier を与えない iOS のバージョンでは、iOS 26 が使う
Closeを補って報告します。 - これにより、プロトコルを変更せずに、シナリオは
/elementsを通じて in-app ブラウザを他の画面と同じように操作できます。 - Playwright web バックエンド(
common/drivers/playwright)は、ブラウザに対する決定的runを Linux のゲート上で動かせます(demos/web)。リッチ寄りの能力モデルまで引き上げ済みです(BE-0054)。 page.route()によるネイティブなnetworkの観測とスタブ。- 共有の
driver_intervalseam を通した、videoとdeviceLog相当(console / page-error)の区間証跡。 multiTouch(ピンチ / 回転)のエミュレーション。- N 個の
BrowserContextレーンにまたがる並列実行。 - ターゲット単位の
runsOn.browser.emulate。既定はデスクトップで、Playwright のデバイスプリセットを指定するとモバイルをエミュレーションします(BE-0228)。 navigateステップ(Driver.goto)を支えるURL_NAVIGATION能力。driver が相対参照をターゲットのbaseUrlを基準に解決します(BE-0464)。このURL_NAVIGATIONを申告する実バックエンドは Playwright だけです。- web には
appTraceがありません。流すアプリのログがないためです。iOS はos_logを、Android はタグで絞ったlogcatを流します(BE-0478)。 - Playwright の
query()は、valueを各タグ自身の値の出所から埋めます。<a>にはhref、<img>にはsrc、<time>にはdatetimeを使います。- フォームコントロール、
<meter>、value属性を持つ<progress>は、roleを帯びていても live なvalueを報告します。 - それ以外の
role付き要素は、aria-valuetextかaria-valuenowのどちらかがあればそれを報告します。どちらも無ければ、自身のvalueプロパティを報告します。 value属性を持たない不定状態の<progress>は、aria-valuetextかaria-valuenowだけを報告します。- 他のどの規則にも一致しないものの、自身のテキストを持つ要素も読み取ります。iOS がラベルに使う
staticTextトレイトを付けて報告します。
- 同じ Playwright の走査は、iframe(入れ子と cross-origin を含む)の内部にも入り込み、メインページの CSS ピクセルへオフセットします。
- 例外は、平行移動以外の CSS transform の下にある iframe です。この iframe は読み取りません。タップが、エラーも出さずに意図しない場所へ着地する事態を避けるためです。
- cross-origin の iframe から読んだ要素は、
crossOriginFrame: trueを帯びて選択可能なままです。ただしdoctorのスコアと crawl の画面モデルからは除外します。埋め込まれたサードパーティのページは、アプリ自身が計測したり探索したりできる対象ではないからです。
- Android adb バックエンド(
common/drivers/adb+common/backend_cli/adb)は、次の範囲を実装済みです。 - tap の actuation。
tap、long_press、double_tapは、解決した要素の identity を resident server のPOST /actへ送ります。server が自身の live なツリーに対して再解決して inject するため、ジェスチャは inject する瞬間にデバイスが持つ bounds へ着地します。リトライを使い切るか、channel に/actエンドポイントがないときは、host 側で計算した frame 中心の座標 tap にフォールバックします(BE-0339)。 - resident の読み取りリカバリ。 resident server の読み取りがタイムアウトした場合は、新しい接続で 1 回だけ再試行します。それでも失敗すれば、server を再起動してから
uiautomator dumpにフォールバックします。再試行回数と再起動の許可はdriver.residentRecovery(readRetries/restart)で制御し、ステップ単位・シナリオ単位でmanifest.jsonに記録されます(BE-0477)。 - resident の settle の鮮度。 プラットフォームは、resident server の接続ごとにアクセシビリティのノードをキャッシュします。Android 14 以降では、server が settle のダンプのあいだでこのキャッシュを捨てます。そのため一致した 2 回のダンプは取り直したツリーであり、アクセシビリティイベントで無効化されなかったキャッシュの写しではありません。Android 13 以前は従来の settle のままです(BE-0490)。
- テキスト入力。
typeは、ASCII のみadb shell input textを使います。日本語や絵文字などそれ以外は、resident server 自身の/typeエンドポイントを経由します(BE-0476)。 - 起動、報告、証跡。
AndroidEnvironmentの起動シーケンス、doctorの報告、interval 証跡です。interval 証跡はいずれも driver 供給のdriver_intervalseam を通します。videoはscreenrecord、deviceLogはlogcat、appTraceはタグで絞ったlogcatを使います(BE-0478)。 - ネットワーク捕捉。 アプリ内の OkHttp インターセプタ(
BajutsuAndroid)がホストのコレクタへ報告し、そのコレクタをadb reverseでエミュレータへ橋渡しするrequestアサーションです(BE-0283)。mocksは追随の課題です。 - テスト。 取得済み XML フィクスチャに対する fast ゲートのユニットテストがあります。
- 実機上での actuation fidelity。 システム
back、deeplink、単一ラウンドトリップのdoubleTap、スクロールによる要素解決、実行時パーミッションの事前付与を含みます(BE-0210)。 - アプリの言語。 起動のたびに、
runsOn.android.localeがcmd localeでアプリ自身の言語を設定し、読み戻します(BE-0478)。API レベル 33 が必要です。未指定なら、再利用するエミュレーターに以前の run が残した設定を消します。 - 写真の投入。
runsOn.android.seedPhotosは、共有ストレージにある Bajutsu 専用のディレクトリを空にし、並べた画像を更新時刻の昇順で送り、メディアスキャナで再スキャンします。これで、デバイス全体を wipe しなくても、写真ピッカーが既知の画像を表示します。 - デバイス制御。
setLocationとクリップボードの読み書き / クリアの部分集合を、操作ごとの capability トークンで管理する形で実装済みです(BE-0211 / BE-0212)。setLocationがエミュレータコンソール(emu geo fix)を使うのは、emulator-<port>というシリアルと、エミュレータイメージを示すプロパティ(ro.boot.qemu/ro.kernel.qemu)の両方が揃うローカルエミュレータだけです。シリアルだけでは実機と区別できず、プロパティだけではadb connect越しのエミュレータを除外できないため、どちらか一方では判定できません。実機、またはadb connectで接続したエミュレータでは、クリップボードと同じアプリ内レシーバ経由のルートを使います(BE-0481)。クリップボードは Android 10 以降シェルプロセスから到達できないため、アプリ内のレシーバ(BajutsuAndroid、BE-0233)を経由します。foregroundも実装済みで(BE-0447)、アプリの状態を消さずにランチャーアクティビティを開始します。backgroundは Home キーを押し、アプリが resumed activity から外れるまで待ちます(BE-0478)。ステータスバーの上書きとクリアには、System UI のデモモードを使います。一方、pushはアプリのプロセス内にレシーバが必要なため、未対応のままです。Android にはキーチェーンがないので、clearKeychainは対象外です。 - パーミッション。 シナリオ単位の
permissionsフィールド(pm grant/pm revoke、BE-0276)は、権限の語彙全体に対応しています。API 33 以降のPOST_NOTIFICATIONSを含むnotificationsも同様です。対応する TCC(Transparency, Consent, and Control)サービスを持たない iOS のsimctl privacyとは異なります。 - マルチタッチ。
pinch/rotateの 2 本指マルチタッチは、まず常駐サーバーのPOST /gestureを試します。これはUiAutomationを通じて両方の指を注入するので root は不要です。タッチスクリーンを検出できる rooted device では、注入が何も起きなかったとき(サーバーがない、エンドポイントを持たない、リクエスト送信前にサーバーへ到達できなかった)に、protocol-B のsendeventスイープへフォールバックします。どちらの経路も使えない端末では、単一タッチへのフォールバックなしにステップが失敗します(BE-0232)。 - codegen。 UI Automator(Kotlin)ターゲットを実装済みです(BE-0209)。
- CI レーン。 Android の e2e CI レーン(KVM 上のエミュレータ、
android-e2e.yml。BE-0208)は実装済みで、モックネットワーク系を除く共有シナリオ一式を実行します。adb ドライバは、iOS と同じ横断バックエンドのセレクタでネイティブのタブバーを操作し、あらゆるタブに到達できます。クリック可能なNavigationBarItemがbuttonトレイトを持ち、子要素のテキストをlabelとして派生させます(BE-0223)。タブバー操作の欠落こそが、タブに紐づくシナリオをレーンから除外していた唯一の移植性の課題でした。 - id の照合。 id の照合は、ドライバ内で厳密一致のままです。native な id 構文が SPEC の id を再現できない場合があります(Android Views の
android:idはstable.refreshをstable_refreshに写します)。その場合は、シナリオのセレクタが id を両方の形で列挙し、共有リゾルバが OR としてどちらにも一致します。ドライバ側の.↔_書き換えではなく、シナリオ側の明示的な規約です(BE-0221)。 - 識別子の仕込み。 両方の形の id を支えるアプリ側の仕込みは、独立したライブラリ
IdentifierTool(BE-0405)として出荷しています。Compose のtestTagsAsResourceIdと Views のandroid:id解決を担い、BajutsuAndroidへの依存は持ちません。 - 既存の XCUITest / adb backend をそのまま使う Flutter アプリ(BE-0008)。Flutter は新しい backend を追加しません。
Semantics(identifier: …)(Flutter 3.19 以降)が、XCUITest と adb がすでに読んでいるのと同じ OS のアクセシビリティツリーへ写ります。そのため、プラットフォーム中立なidセレクタは、ネイティブアプリと同じように解決・actuation できます。Flutter 版 showcase の双子アプリで実機確認済みです。- drivers.md#flutterネイティブバックエンド経由 に、id 規約、semantics が遅延構築されるという前提、確認済みの制約があります。制約とは、
network/mocksを観測できないことと、プラグインなしを保つ Flutter アプリがリンクしない in-app receiver を、Android のクリップボードが必要とすることです。
シナリオ、アサーション、run ループ¶
- シナリオスキーマ(厳格検証)と YAML ラウンドトリップ。
id/idMatchesは、プラットフォーム別の id 形に対応する OR 候補のリストを受け付けます(BE-0221)。 - アサーション評価:
exists、value、label、count、enabled、disabled、selected、request、requestSequence、event、responseSchema、visual、clipboard、golden、attribute。 - Tier 2 run ループ(act → wait → verify)。
FakeDriverで検証しています。 - 複数ターゲットにまたがるシナリオ実行(BE-0428)。シナリオのトップレベル
targets: list[str]とステップ単位のtarget: strにより、複数の宣言済みターゲット(たとえば iOS ターゲットと web ターゲット)へ、ステップを自由に織り交ぜて振り分けられます。1 回のbajutsu run呼び出しとして 1 つの合否判定にまとまります。 ${vars.*}はすべてのターゲットで共有されます。あるターゲットのextractステップが取り込んだ値を、同じ run 内の別ターゲットに対するアサーションから読み取れます。- 宣言済みのターゲットは、すべて最初のステップの前にまとめて起動し、最後のステップの後にまとめて終了します。
- ステップや
if/forEachの条件、expectのエントリがtargetを省略した場合、シナリオが宣言するターゲットが 0 個または 1 個であれば、今までどおり動作します。2 個以上になると、targetの指定が必須になります。 - ただし、シナリオが
primaryTarget(BE-0436、targets[0]に固定)を宣言していれば、省略したtargetは公開プロパティStep.resolved_targetを通じて主ターゲットに解決されます。このプロパティの裏にある非公開の属性は、model_dump()にもステップの再シリアライズ結果にも現れません。 - シナリオがこの形で自己宣言していれば、
--targetは省略可能になります(代わりに--scenarioが必須になります)。--targetを明示した場合は、scenario.targetsに含まれているかを検査し、黙って上書きされることはありません。 RunResult.target_devicesとStepOutcome.targetが、各ステップを実行したデバイスとターゲットを報告します。単一ターゲット向けの既存フィールドは空のままなので、既存の JUnit/CTRF リーダーは単一ターゲットの run をこれまでどおり解釈できます。bajutsu crawl/recordとserve自身のディスパッチ UI は、いずれも従来どおり単一のターゲットしか解決しません。targets/targetをそこまで通すのはこの項目の対象外で、今後の課題です。- ターゲットグループ(BE-0437)は、BE-0428 のステップ単位
targetの上に乗る、純粋な記法上の糖衣構文です。ステップの新しいフィールドsteps: list[Step]を使うと、入れ子になった一連のステップに対してターゲットを一度だけ名指しでき、各ステップにtarget:を繰り返す必要がなくなります。 - ロード時の変換パス(
_expand_target_groups)が、ステップ単位のtarget規則による検証の前に、すべてのグループをスタンプ済みのフラットな子ステップへ置き換えます。 - ステップを実行する側は、この新しい形を一切知りません。
bajutsu runがターゲットグループそのものを目にすることはなく、BE-0428 がすでに実行しているステップ単位のtargetの形だけを見ます。 - このパスは、
_check_target_requirementsと同じ 3 か所で走ります。Scenario自身のバリデーターと、Pydantic がバリデーターを再実行しない 2 つの後段の差し込み(expand_components、パイプラインでの target のhooks.setup/hooks.cleanupの折り込み)です。 - グループの展開は
Scenarioのバリデーターの中、つまり CLI が自前のスナップショットを取れるより前に起きます。そのためbajutsu runの CLI は、ステップ行番号の突き合わせを、自前のスナップショットではなく、生の YAML の 1 項目 1 エントリの個数に対して行います。 - 複数ターゲットシナリオでのコンポーネント(BE-0446)。
use:/group:ステップはtargetを持てます。 expand_componentsは、展開で生じたステップのうちtargetを省略したものすべてへ、その値を刻印します。刻印はif/forEachの本体と入れ子のuse呼び出しへ降り、web:/app:ブロックで止まります。- 異なるターゲットを名指しするステップはロードを失敗させ、メッセージにはコンポーネントの連鎖が入ります。
- 呼び出し側が
targetを省略した場合、生じた各ステップは手書きのステップと同じように解決します。 - ロード時の
_check_target_requirementsは、use:/group:ステップのtargetについて、所属だけを検査します。groupステップの子ステップについては、そのgroupステップのtargetを呼び出し側のターゲットとして検査します。targetを省略した子ステップはそのまま通り、異なるターゲットを名指しする子ステップはロードを失敗させます。 expand()自体も、if/else、forEach、web:、app:のすべての本体へ再帰するようになりました。ターゲット数にかかわらず、未展開のuseステップが実行ループへ届くことはありません。- runner、レポート、CLI が見るのは、従来どおりステップ単位の平坦な
target:形式だけです。 - レポート上のステップグルーピング(BE-0439)。ステップ自身が持つ
group: { name, steps }フィールドは、連続するステップの並びを 1 つのセクションとしてまとめます。これはreport.html専用の機構です。 expand_componentsがgroupステップをそのstepsへ展開し、各ステップにグループのnameと、run 全体を通じて一意なgroup_idを付けます。展開後のステップ上ではreport_group/report_group_idです。rows.pyの_fold_groupsがこれを使って、同じgroup_idを持つステップの並びごとに 1 つの見出し行を挿入します。runはgroupそのものを一切見ません。これはuse(BE-0030)がすでに受けているのと同じ、ロード時限定の扱いです。- グループを別のグループ、
if、forEach、web、appのいずれかの内側に直接入れ子にした場合は、ロード時に拒否されます。グループの内側から呼び出したuseを通じて到達した場合や、コンポーネントがそうした本体へ持ち込んだ場合も同様です。 groupステップ自身のtargetは、useステップと同じく展開後のステップへ刻印されます(BE-0446)。- 失敗したステップを含む並びは、セクションが既定で開いた状態になります。失敗のない並びは、読者が開くまで折りたたまれたまま表示されます。既存の「すべて展開」/「すべて折りたたむ」コントロールも、各シナリオのグループをまとめて切り替えます。
- デバイスグループと
installApp/setPrimaryTarget(BE-0447)。targetsの 1 エントリは、2 つ以上の名前を入れ子の配列にしたデバイスグループにもできます。グループのメンバーは 1 台のデバイスを共有します。それぞれが自分専用のデバイスを持つ従来の形とは異なります。裸の名前はメンバー 1 人のグループのままなので、グループを書かないシナリオは従来どおりです。 - トップレベルの
installsリストは、プライマリ以外のどのメンバーが最初にインストールして起動するかを名指しします。 - それ以外のメンバーは「後続メンバー」のままです。
installApp: { from, keepData }ステップがインストールし、foregroundが立ち上げます。この項目はforegroundを Android へも移植します(従来は iOS 限定でした)。両プラットフォームとも、実行中のアプリを前面に出すだけでなく、まだ起動していないメンバーを新たに起動できるよう拡張します。 - トップレベル限定の
setPrimaryTarget: { target }ステップは、targetを省略したときの解決先を、その時点以降、切り替えます。interruptsエントリやトップレベルのexpectブロックも含みます。シナリオモデルはステップ列を順に歩いて現在のプライマリを追跡し、省略されたtargetとinstallApp.fromのすべてを静的に検査します。 - グループのメンバーは、ネイティブバックエンドのプラットフォーム、デバイスの経路、実効
localeを、それぞれ一致させる必要があります。runの preflight が、デバイスを取得する前に拒否します。2 人以上のグループに属する web ターゲットや、開始メンバー同士でのバンドル識別子の重複も、同じ preflight が拒否します。 - 各メンバーのドライバは、操作の前に自分のアプリが前面にあるかを確認し、そうでなければ
AppNotInFrontという名前のエラーを送出します。1 台のデバイスは、一度に 1 つのアプリしか映さないためです。 - XCUITest は、リースが持つ 1 つの常駐 runner をグループのメンバー間で共有します(
/app/targetがアプリスタックの土台となるバンドルを差し替えます)。adb は、1 つの常駐チャンネル上で、メンバーごとに別々のドライバを割り当てます。 - web ターゲット、アプリをプリインストール済みで渡すデバイスクラウドのリース、コード生成は、いずれもこの 2 つの新しいステップを拒否します。コード生成は XCUITest、UI Automator、Playwright で、いずれもラベル付きの
// TODOを出力します。 - run パイプラインでのバックエンドクラッシュ復旧。シナリオ途中でバックエンドがクラッシュした場合(
base.BackendCrashError、バックエンドに依存しない)、死んだリースを破棄し、新規に再生成したリースでシナリオ全体をやり直します。 - 上限は 2 つあります。リトライ回数(
crash_retries、既定 1)と、再生成に費やす合計時間の任意の wall-clock 上限(crash_recovery_budget、既定は無制限)です。クラッシュし続けるシナリオや復旧しないランナーを、黙って合格扱いにしたりジョブをハングさせたりせず、はっきりと失敗させます。 - 再試行は
preconditions.subject.reinstall: eraseを強制します。シナリオがこの値を宣言したときにすでに得られるのと同じ、デバイスのリセットです。XCUITest バックエンドでは Simulator 自体の再起動(simctl shutdown → erase → boot)、adb バックエンドではアプリレベルのクリーンな状態化です。直前にクラッシュしたそのデバイスへの、その場での respawn ではありません。 - 次の場合は、この強制をスキップします。
- マージ後の reinstall が
overwriteで、リースをまたいでアプリのデータを残す場合。組み込みのデフォルトであるマージ後のcleanでは、スキップしません。cleanもデータを残さないので、その値を見るガードでは、この仕組みがまさに対象としている経路そのもので、強制再試行が無効になってしまいます。 - run に
--no-eraseが付いている場合(BE-0473)。 eraseの precondition をそもそも受け付けない 2 つの XCUITest 経路の場合。実機(runsOn.ios.kind: device)と、live WebDriver エンドポイントです。そこで強制すれば、1 シナリオの失敗では済まず、run 自体が中断してしまいます。
- マージ後の reinstall が
- 強制 erase 用のリース自体が、デバイスレベルの不具合で失敗したときは、同じその場での respawn に切り替えます。不具合とは
simctl.DeviceError/adb.DeviceErrorで、BackendCrashErrorとは別系統の型です(その派生ではありません)。切り替えなければ、この不具合がループの外まで伝播し、run 全体を中断させます。 - ただし、不具合がタイムアウト(
device_errors.DeviceTimeout)であるときは切り替えず、シナリオを失敗させて run をラッチします(BE-0374)。拒否したデバイスは 1 つの操作についての証拠を出しています。まったく応答しなかったデバイスが示すのは、あらゆる操作の背後にあるサービスが応答をやめたことだけです。そこへ再試行するのは、タイムアウトが否定したことをそのまま前提に置く行為です。 - もう 1 つの run 単位の wall-clock 予算(
run_crash_recovery_budget、こちらも既定は無制限)は、クラッシュ復旧に使う時間を、シナリオ単位でリセットせず run 全体を通して制限します。劣化し続けるデバイスは、run 自体をはっきりと失敗させます。各シナリオが自分の予算を静かに使い切り、外部の CI タイムアウトがジョブを打ち切るのを待つことにはなりません。 - 最終的に成功する復旧に、この run 単位の予算を使い切っただけでは、何もラッチされません。それはデバイスがまだ機能していることを示しているにすぎないからです。あるシナリオ自身のクラッシュ再試行ループが、この予算を主因として実際に失敗した後に、初めてラッチが立ちます。以降のどのシナリオも、自身の最初のリースを試す前の時点で、即座に失敗します。この確認は、クラッシュ再試行ループの中だけでなく、各シナリオの先頭でも行われます。すでに復旧できないと分かっているデバイスに対して、残る全シナリオが同じ打ち切りに至るまでにコールド起動の試行を 1 回ずつ余計に払わずに済みます。
- デバイスの準備がタイムアウトした場合も、同じ限定を要さずに同じラッチを立てます(BE-0374)。ラッチはどちらの原因で立ったかを保持します。そのため、飛ばされたシナリオは、予算ではなく固まったホストを報告します。
- オンデバイスのドライバ適合性スイートは、シナリオ単位の判定を共有しています(
common/runner/recovery)。Simulator のインフラ障害が起きても、無関係な PR で必須チェックを赤くすることなく、同じように復旧します(BE-0334)。 - Simulator の XCUITest 経路では、再試行は erase より強い段としてデバイスの置き換えを持ちます(BE-0354)。消えたデバイスを置き換えるときと同じ手順で新しいデバイスを作り、劣化したデバイスはシャットダウンしてプールから外します。
- erase が消すのはデバイスのデータであって、固まった画面キャプチャの機構ではありません。そのため、強制 erase 付きの再試行がまたクラッシュした場合は、この段へ進みます。
- 映像の録画が書き込みを始めたことを確認できないまま終わった試行は、最初のクラッシュから、この段へ直接進みます。その兆候は、erase の効かない劣化を言い当てているからです。
- 置き換えの試行では、強制 erase を外します。これから作成するデバイスには、消すものがないからです。
- この段が働くのは、udid を固定しておらず
subject.pathを持つ run に限ります。--udidで名指しした run は、そのデバイス上の erase による再試行を保ちます。 - 置き換えが消すものは erase より多いため、erase の段が尊重する 2 つの除外、
reinstall: overwriteとbajutsu run --no-eraseも、同じように尊重します。
- iOS クラッシュレポートのシナリオ単位での取得(BE-0421)。XCUITest のクラッシュ再試行を使い切って失敗したシナリオは、そのシナリオ自身の証跡ディレクトリ
runs/<run_id>/<sid>/の下に、crash-diagnostics/サブディレクトリを持ちます。 - サブディレクトリには、ランナー自身が出力したログの末尾(上限あり)が入ります。クラッシュした
xcodebuildプロセスに対して macOS が.ipsクラッシュレポートを書いていれば、それも入ります。 - 取得はリースの解放時点で行い、同じ warm な environment を後続シナリオが再利用して上書きする前に済ませます。
- シナリオ自身の失敗文字列も、このサブディレクトリを直接名指しします。
- アプリクラッシュのシナリオ単位での取得(BE-0424)は、直前の項目のアプリ側の対応物であり、意図して再試行しません。
- バックエンドがクラッシュするとシナリオには救い出せるものが残らないので、パイプラインはリースを捨てて再実行します。一方、テスト対象アプリのクラッシュでは、ドライバ、バックエンドプロセス、実行中の動画記録がそのまま残ります。そのためステップループの内側で分類します。事象を観測したステップを失敗させ、通常の
RunResultの組み立てが、その周りで最後まで進みます。 - 検知は事後的です。ステップがすでに失敗した後にだけドライバへ問い合わせるため、緑の run は何も払いません。証跡は、直前の項目の隣の
app-crash/サブディレクトリに入ります。 - ここで再試行すると、同じ形で失敗する見込みの高いシナリオが、クラッシュリカバリの予算を使い切ります。アプリの本物のリグレッションを、明示的な失敗として扱う代わりに flakiness として吸収してしまう危険もあります(BE-0049)。
- 対象は iOS シミュレータと Android API 30 以上、つまり各プラットフォーム自身のシグナルが事象を実際に確認できる範囲に限ります。それ以外では推測せず、「確認できない」と答えます(
docs/ja/evidence.md)。
DSL のオーサリング、制御フロー、データ取得¶
- DSL(ドメイン固有言語)の基本:
withinセレクタ(幾何スコープ)。relaunchステップ(実機検証済み)。- target の
hooks.setup。以前の前段はuse:のコンポーネントとして呼びます(BE-0452)。 - 起動時の
locale適用。 - デバイスプール上の並列実行(
--workers)。 - DSL のオーサリング再利用:
- 再利用可能なパラメータ化コンポーネント(
use/${params.*})。/を含む参照や.yaml/.ymlで終わる参照は、ファイル横断のコンポーネントファイル(BE-0030)として解決します。どちらでもない名前だけの参照は、同じシナリオファイルにインライン宣言したcomponents:ブロック(BE-0422)を参照します。 - データ駆動シナリオ(
data/dataFileと${row.*})。 - シークレット変数(
${secrets.X}、値マスク)。 - シナリオタグと
--tag/--exclude選択。 setLocation/pushデバイスステップ。- 起動前の
permissionsフィールド(simctl privacy/pm grant|pm revoke、BE-0276)。 doubleTapアクション。- ファイル単位とシナリオ単位の
description。 - DSL の制御フローとデータ取得:
- 条件分岐
ifとループforEach。どちらも決定的で、条件は機械アサーションです。 extract。要素の value / label / identifier を${vars.*}に取り込みます。- DSL の
totpとemailステップ(BE-0046): totpは、共有シークレット(多くは${secrets.*})から RFC 6238 のワンタイムパスワードを生成して${vars.*}に書き込みます。ネットワークもモデルも使わず、ローカルで決定的です。nameを持つtotpステップは、シークレットをシナリオ実行のバインディングにも登録します。キーには}を含めるので、どの${...}トークンからも届きません。後続のotpステップはfromでそのジェネレータを指定し、そのステップの時点で有効なコードを${vars.*}に書き込みます。登録されていない名前はステップの失敗になります。totpとotpの省略可能なminRemaining(BE-0474)を指定すると、現在の 30 秒ウィンドウの残りが足りないとき、run ループが handler の前に次のウィンドウまで待ちます。待機は境界で終わり、上限は 1 ウィンドウとキャンセル確認の 1 刻み(0.25 秒)です。待機中に壁時計が飛んだときは、判定に影響しない警告をStepOutcome.warningsに残します。emailは、メールボックス(config のtargets.<name>.services.mailbox。レジストリ方式の transport で、出荷済みなのはhttpアダプタ、BE-0186)をポーリングします。to/subject/subjectMatchesに一致するメッセージが、ステップ開始後に届くまで待ちます。- 届いたら、
bodyMatchesの正規表現で値を${vars.*}に抽出します。timeoutで上限を定めた条件待ちであり、固定 sleep ではありません。 - DSL の
generateステップ(BE-0377)は、値を計算して${vars.*}に書き込みます。ランナー側で生成器から値を引くか、クロックを読むだけで、ネットワークとモデルのいずれにも触れません。 - 乱数は、選んだ文字集合による文字列、整数、任意の精度を持つ小数、バージョン 4 の UUID のいずれかです。
- 現在日時は、任意の
strftimeのformat、加算される符号付きオフセット、任意の IANAtimezone(既定は UTC)を取ります。 - 描画できない
formatと未知のtimezoneは、シナリオのロード時に拒否されます。そのため、受理されたステップは常に実行され、常に成功します。 - 生成した値はステップの manifest エントリに記録されてレポートに表示されます。どの codegen ターゲットも、ラベル付きの
// TODOを出力します。 - DSL の
evalステップ(BE-0472)は、固定の操作群から選んだ ops を、fromの値に順番に適用するパイプラインとして実行し、結果を${vars.*}に書き込みます。 - 操作群は、
split/join/filter/pick/count/sort/unique/reverse/json/regex/replace/substring/trim/caseです。 - 結果を 1 つの変数に入れるときは
into: { var }を使い、リストの結果を複数の変数へ順番に分けるときはinto: { vars: [...] }を使います。 - ローダーは、実行前にパイプラインの型をステップごとに追跡し、型に合わない操作を拒否します。
- リストの結果は、
extractBodyと同じjson_textのレンダリングで、コンパクトな JSON 配列テキストとして保存されます。 - 入力のいずれかが
${secrets.*}であるか、それ以前のステップがシークレットだと印を付けた変数に遡れるとき、ステップはその結果を記録前に新しいシークレット値として登録します。以後のすべての証跡で、その値をマスクします。countの結果は入力の文字を持ち越さないため、この登録から除かれます。 - このマスクはシナリオ単位で閉じています。
--workers > 1で動かしても、一方のシナリオが導いた値で、他方の証跡の同じ文字列をマスクしてしまうことはありません。 evalは XCUITest / Playwright / UI Automator のいずれにも対応がなく、どの codegen ターゲットもラベル付きの// TODOを出力します。- DSL の
sleepステップ(BE-0451)は、条件待ちのみという原則に対する唯一の正式な例外です。画面にも、ツリーにも、ネットワークログにも、どの条件も観測できない待ちのための固定の一時停止です。サーバー側のスロットルや、until: settledより長く続くアニメーションが当たります。 seconds(strict、0 < seconds ≤ 30)と、空でないreasonの両方が必須です。これより長い、あるいは理由のない一時停止はローダーが拒否し、代わりにwaitを使うよう示します。- run ループは、
waitと並べてこのステップを実行します。注入されたClockを 0.25 秒刻みで呼ぶため、キャンセルされた run は 1 刻み以内で抜けます。fake clock を使うテストは、実際の待ち時間なしに時刻を進められます。ドライバには一切触れず、capability トークンも要りません。 - 例外であることは、数えられる形を保ちます。
- 進捗ラベルと
report.htmlは、sleep Ns — reasonを表示します。 - 決定性監査(BE-0049)は、
setup/cleanup/interrupts/web/appも歩いたうえで、書かれたすべてのsleepをfixed-sleepの finding として列挙します。固定の一時停止の合計が 10 秒を超えたシナリオは、Moderate と採点します。 triageの緩さガードは、sleepを追加する修正に警告します。- どの codegen エミッタも、理由をコメントとして翻訳します。
record/crawlは、このステップをモデルに一切提示しません。
- 進捗ラベルと
- DSL の
interrupts(BE-0314)は、config レベル(hooks.interrupts、アプリ全体の既定)とシナリオレベル(追記)の、{ condition, steps }エントリのリストです。 ifが使うのと同じアサーション DSL のconditionを再利用して、機会をとらえてチェックします。- 対象は、予測できないタイミングで現れる画面です。オンボーディング画面や、アクセシビリティツリーから見えるパーミッションプロンプトが当たります。ステップ列の決まった一箇所は対象ではありません。
- この判定が追加コストなしで済むのは、そのステップのために読んだばかりのツリーに乗れる場合だけです。
waitのポーリングと、持ち越したツリーがないときにscreenChangedポリシー付きステップが読むbeforeが、これにあたります。残りのwait以外のステップは、driver.query()を 1 回余分に呼びます。前のステップから持ち越したprev_after(BE-0234)を使うステップも、古い可能性があるものとして読み直すため、ここに含まれます。 - 条件が一致すると、そのエントリの
stepsを実行してから、中断していたステップを再開します。waitは元の deadline を維持し、act ステップは 1 回だけ再試行します。再入をキャップし、上限に達するとそのステップ本来の結果にフォールバックします。 - 2 つ以上のターゲットを宣言したシナリオ(BE-0428)では、エントリ自身の
targetフィールドが、どのターゲットを監視するかを指定します。通常のステップのtargetと異なり、この指定はターゲットが 2 つ以上でも任意のままで、省略したエントリはプライマリターゲットを監視します。 - エントリの
stepsにあるリカバリ用ステップのtargetも、同じく任意です。省略した場合は、プライマリではなくそのエントリのターゲットで実行します(BE-0438)。 - DSL の
setup/cleanup(BE-0392)は、シナリオのセットアップとティアダウンを、stepsへ連結するのではなく独立したフェーズとして扱います。2 つのフェーズの BE-0452 までの名前は、before/afterです。 setupは最初に走る順序付きのステップ列で、失敗するとシナリオを打ち切ります。cleanupは{ on, steps }ルールのリストです。run 自身のマシンチェックされた判定(always/success/failure)に紐づき、stepsを抜けるすべての経路で到達します。末尾の後片付けのステップでは到達できない失敗経路も、キャンセルされた経路も含みます。キャンセルされた経路では、ラッチされたキャンセル用のソースではなく、キャンセルの猶予時間の一部を期限としてフェーズを縛ります。- target config 側は、同じ 2 つのフェーズを
hooks.setupとhooks.cleanupとして持ちます(BE-0452)。setupは config が先でシナリオが後、cleanupはシナリオが先で config が後という順に重なります。 - シナリオの
preconditions.inheritSetup: falseは、そのシナリオの target のhooks.setupを飛ばします。 - 2 つのフェーズはレポートで独立したブロックになり、すべてのエクスポートに載ります。
DSL のジェスチャ、テキスト入力、デバイス操作¶
- DSL の
scrollアクション(BE-0326)は、画面全体、またはwithinで指定したコンテナを、対象セレクタのフレーム中心がビューポート内に収まるまでスクロールします。maxScrolls(既定 15)の上限に達するか、連続する 2 回の読み取りが領域の静止を示した時点(end-of-content)で、決定的に失敗します。 - 各ステップは、既定でビューポートの一定割合だけ進みます。既定のステップ幅が行き過ぎたり届かなかったりする画面向けに、ステップごとの任意指定
amount(0 < amount ≤ 1、swipe/dragと同じ単位)で上書きできます。 - BE-0400 は、実際に進む距離を要求どおりに一致させました。それ以前は、iOS のジェスチャがどの要求距離に対しても最大 6 倍まで行き過ぎ、どのステップも画面の約 3 分の 1 未満には進めませんでした。そのため、
amountの小さい側の値は実現できませんでした。 - 何をもって静止を示したとするかは、BE-0329 の主題です。次の 3 つのいずれかを満たせば足ります。
- ループが動くのを見た要素が、切り取られずにそこへ残って止まっており、しかもスクロールする領域の外のクロームでないこと。折りたたむアプリバーは一度動いてから固定されるので、背後でリストがスクロールし続けていても止まったままになります。
- 領域の枠が何も切っていないので、動きを隠せる frame がないこと。画面全体を覆うウィンドウや root view を報告するツリーは、これを満たしません。
- ツリーがそのどちらも示せない場合。画面より高い要素を画面に切り取って報告するバックエンドでは、背後で内容がスクロールしていても同じ frame を報告します。この場合は、画面のチェックサムも、ステップの前後で変化していないこと。チェックサムは、そうしたステップに限って撮影し、連続する 2 枚が一致してから信頼します。
- ステップの前に視野にあったものが、その後どれも画面に残らなかったステップは、行き過ぎの可能性として読みます(一部だけ残っている場合は残ったと数えます)。ループはステップの割合を半分にし(下限 0.125)、通り抜けた範囲を読むために 1 ステップ戻ります。下限では、行き過ぎを名指して失敗します。
- 再読み取りによる確認があるのは、問い合わせたツリーが、すでに内容を動かしたジェスチャより遅れうるからです。
- Android は、スクロールで内容を動かした後にアクセシビリティ更新を公開します。公開までに読み取ったツリーはスクロール前の画面を表すため、1 回の読み取りでは末尾に達した領域と区別できません。
- 読み取りが遅れうると申告するバックエンドには、ステップの結果が届くまでの猶予を持たせます(
ReadLagProvider)。現時点で申告するのは adb だけです。 - 猶予を申告しないバックエンドは、上記の証拠を伴う最初の変化なしの読み取りで失敗します。同期的なバックエンドは、従来どおりの速さで失敗します。
- この同じ予算は、そうしたバックエンドでさらに 2 つの読み取りを支配します(BE-0332)。これにより、
gesturesの長押しフレークとextract.yamlの古い値フレークを解消します。- 内容を動かす
tap/longPress/doubleTapの後の座標解決は(pan の後だけでなく)そのアクチュエーションより後になるまで、ツリーを信用しません。 - シナリオ途中の
extractは、写し取る値がそれを生んだアクションより後になるまで待ちます。
- 内容を動かす
- デバイス側の読み取りマークが、この上限を早期に解放される待ちへ変えます。
- 常駐する Android リーダーは、読み取りごとに、そのダンプ時点で観測した最新のアクセシビリティイベントのデバイス時刻を刻印します。ドライバは、アクチュエーションに先立ってデバイス時刻のマークを取ります。
- 読み取りのマークがアクションより後になった瞬間に、その読み取りを信用します。予算いっぱいまで待つ代わりに、即座に解放されます。
- 予算が残るのは、マークを持たない一発の
uiautomator dumpのフォールバックだけです(BE-0332 作業単位 3〜4。drivers を参照)。
- resident server が inject するジェスチャでは、待ちをさらに絞ります(BE-0339 作業単位 5)。
- server は、自身のアクセシビリティイベントの流れを見て、その inject が publish されるのを確かめ、確かめたイベントを host へ返します。確認が取れたジェスチャにはバリアをまったく張りません。デバイスが確認できなかったジェスチャには、座標での inject とまったく同じようにバリアを張ります。
- 確認が取れたジェスチャは、publish が届いた時点でデバイスが取ったツリーも併せて返します。次の settle が冒頭で行うはずだった読み取りは、これで済んでいることになります(BE-0407 の作業単位 19)。
- ドライバがそのツリーを採用するのは、ツリー自身のマークがジェスチャを後追いしていることを確かめたあとです。ヘッダを 1 つ取り違えたサーバーが、ジェスチャ前の画面を種として渡すことはできません。
- 各ステップは非慣性(勢いを残さない有界な移動)で、
Driver.scrollとViewportProviderの背後で、バックエンドごとに実現しています。web と fake は実際のビューポートを直接報告し、ネイティブバックエンドは画面内要素のみを返すツリーがそのままビューポートに相当します。adb だけがオフスクリーンのtapを復旧していた、BE-0210 の非対称性を解消するものです。 - codegen は、Playwright の
scrollIntoViewIfNeeded()と UI Automator のUiScrollable.scrollIntoViewにネイティブなまま対応付けます。単一の堅牢な scroll-to-element プリミティブを持たない XCUITest には、TODOラベルを出力します。 - タップ対象の到達可能性チェックと、有界なスクロール安全網(BE-0349)。
tap/double_tap/long_press(およびtype/clear/delete/select内部のフォーカスタップ)が操作する前に、各バックエンドが自分にもっとも自然な手段で、解決済みの要素が実際にその点で到達可能かを確認します。 - ローカルの XCUITest ルートは、ネイティブの
isHittableを使います。ただし要素の中心が画面の端より外にあれば、isHittableを問わずに拒否します。そうした対象には、XCUITest 自身のスクロールではなく、後述のスクロールで届かせます。 - web は、
document.elementFromPointによる祖先要素チェーンのヒットテストを使います。 - adb と、Appium 経由では
isHittableを読めない live-route の XCUITest ドライバは、ドキュメント順による幾何学的な近似topmost_at_pointを使います。この近似は Compose のzIndexには正しく対応しますが、View のelevationや、Compose の軽量な offset モディファイアによる frame の陳腐化には既知の死角があります。 - この確認に失敗したときの復旧は、次のとおりです。
- オーケストレータは、小さく回数を区切ったスクロール(まず
down、それでも届かなければ上端に固定された遮蔽物向けに範囲を広げたupフォールバック)を試したうえで再確認し、操作をもう一度だけ再試行します。 - それでも対象へ到達できない場合は、誤解を招く
ElementNotFoundの代わりに、専用のElementNotTappableエラーでステップが失敗します。 - XCUITest バックエンドでは、中心が画面内にある対象への tap が拒否された場合に限り、スクロールの前にドライバが動きます。たとえば iOS が、コンテナの accessibility 要素を、そのコンテナが包む control の上に膨らませて報告する場合です。ドライバは対象の名前付き子要素を探索します。到達可能な要素がちょうど 1 つであれば、それをタップして
substitution: soleHittableDescendantを記録します。0 個または複数であれば、どちらを選ぶかは決めずに候補を名指ししたうえで失敗します(BE-0373)。 - DSL のテキスト編集ステップ(BE-0265):
clear/delete/select/copyが、typeだけでは埋まらない部分を補います。adb・Playwright・XCUITest・fake の各バックエンドに実装済みです。pasteはこの組を補い、フィールドにフォーカスしてクリップボードの内容を入れます。 - web コンテキストは、
select/copy/pasteでUnsupportedActionを送出します(codegen 側は代わりに XCUITest へ誘導します)。clear/deleteでも同様に非対応です。 - ステップをまたぐ
SelectionStateが、「copyの前にselectが必要」という前提条件を担保します。どのバックエンドも選択状態を照会可能な形で公開しないため、検証は既存のclipboard読み戻しだけで行います。 - DSL の
navigateステップ(BE-0464、web 限定)は、シナリオの途中で URL を読み込みます。どの control からもリンクされていないページ(メールのリンク、共有アイテムの URL)、UI を歩かないと届かない深いページ、リダイレクトの検証などに使います。 - 値は単純な文字列で、ブラウザがリンクを解決する方法(
urljoin)と同じ形で、ターゲットのbaseUrlに対して解決します。 http/https以外のスキームは拒否されます。リテラル値ならロード時に、${...}トークンを含む値なら実行時に失敗します。- ステップは、ページの
loadイベントが発火した時点で戻ります。レスポンスのステータスは読まないため、cookie とストレージはそのまま引き継がれます。 - 新設の
Driver.goto(url)メソッドに乗り、urlNavigationcapability でゲートされています。これを宣言するのは Playwright バックエンドだけなので、web:ブロックの中に入れ子にしたnavigateを含め、デバイス側の作業に入る前に preflight で iOS や Android を拒否します。 - DSL の
openUrlステップ(BE-0487、iOS と Android)は、シナリオの途中で URL を OS へ渡します。サインインの後ろにある画面のように、起動時のディープリンクでは届かない画面に移れます。 - 値は単純な文字列で、
javascript:、data:、file:以外の任意のスキームを持つ絶対 URL です。リテラル値ならロード時に、${...}トークンを含む値なら実行時に、この規則で検査します。web:ブロックの中のopenUrlは、ファイルの読み込み時にシナリオのモデルが拒否します。 - URL を受け取るのは、driver がその時点で操作しているアプリ(テスト対象のアプリか、囲んでいる
app:ブロックが指定したアプリ)です。ステップはその後、app:ブロックと同じ上限で、そのアプリが前面に来るまで待ちます。 - 新設の
Driver.open_url(url)メソッドに乗り、openUrlcapability でゲートされています。これを宣言するのは XCUITest と adb のバックエンドなので、app:ブロックの中のopenUrlを含め、web バックエンドでは preflight で拒否します。 - iOS では、ランナーの
POST /app/openUrlがXCUIApplication.open(_:)(iOS 16.4 以降)を呼びます。例外や XCTest の失敗の記録は、そのメッセージを理由にしたnot-openedとして返します。 - Android では、adb driver がパッケージを指定した
VIEWintent をam start -W --activity-single-topで送ります。コマンドはshlexでクォートした 1 行のシェルコマンドです。判定はam startの終了ステータスではなく出力から読みます。終了ステータスは、解決できなかった intent も成功として報告するためです。起動時のディープリンクも同じ出力を読むので、開かなかったディープリンクは起動の失敗になります。 - DSL の
attributeアサーション(BE-0466、web 限定)は、1 つの要素の HTML 属性(href、alt、状態を表すdata-*やaria-*)を、equals/contains/matchesかabsent: trueで検証します。 - runner は、ブロックを評価するクエリの直後に、
Driver.read_attributes(reads)で属性をそのつど読み取ります。ブロック全体を 1 回の呼び出しで読むので、ブロック内のアサーションは同じ時点の値で判定されます。 - ステップの
assertでは、条件待機の各ティックで読み直します。レポートに載る属性は、アサーションが名前を挙げたものだけです。 elementAttributecapability でゲートされています。この capability を宣言するのは Playwright バックエンドだけなので、デバイス側の作業に入る前に、preflight で iOS や Android(iOS の WebView コンテキストを含みます)を拒否します。- DSL のデバイス / システムアクション(iOS):
background、clearKeychain、clearClipboard。overrideStatusBar/clearStatusBar(決定的なステータスバー)。- テストデータ準備 / Webhook 用の
httpアクション。saveBodyはレスポンスボディ全体を保存します。extractBody(BE-0440)は、固定のキー/インデックスpath文法で JSON ボディから 1 つ以上の指定フィールドを取り出し、${vars.*}へ直接格納します。 - DSL の
setPickerValue(BE-0356)は、ホイール式のピッカーを指定した行へ動かします。iOS のピッカーはUIPickerView、またはホイールのみのモードに切り替えたUIDatePickerです。解決済みのホイールに対して、XCUITest 自身のadjust(toPickerWheelValue:)を呼び出します。 - Android(BE-0480)のピッカーは
android.widget.NumberPickerで、スピナー表示のDatePickerやTimePickerも含みます。adb ドライバは、タップ対象と同じ手順でホイールを解決し、その識別情報を常駐サーバーの/setPickerValueエンドポイントへ送ります。サーバーはNumberPickerのアクセシビリティのスクロール操作でホイールを 1 行ずつ進め、1 行ごとに行を読み直します。回す行数は 400 行を上限とし、期限も設けています。座標によるフォールバックはありません。 tapと同じくハンドルベースの操作であり、swipe/drag/scrollのような座標ベースではありません。ホイールの行は、座標ドラッグで確実に止められる個別の要素ではないからです。- ホイールが持たない値を指定した場合は、ホイールを止まった場所に残したまま、その値を名指ししてステップを失敗させます。
- 複数コンポーネントのピッカー(年のホイールと月のホイールが並ぶような場合)は、セレクタの既存の
within/traits/indexフィールドで、コンポーネントごとに 1 ステップずつアドレス指定します。 PICKER_WHEELcapability でゲートされています。これを宣言するのは、常駐 runner を持つ XCUITest バックエンド、adb バックエンド、FakeDriverです。web バックエンドは、作業に入る前に preflight で拒否されます。- DSL の
selectPhotos(BE-0433)は、開いているPHPickerViewControllerのグリッドから、序数のindicesで 1 枚以上の画像を選び、ピッカーの確定コントロールをタップします。adb では Android 13 以降の写真ピッカーを同じように操作し、セルと追加ボタンをピッカー自身のパッケージ内の resource id で探します。 - 確定コントロールは自身の identifier を持たないため、ピッカーのナビゲーションバー内で、消去法により構造的に解決します。
- グリッドの各セルは 1 つの identifier(
PXGGridLayout-Info)を共有しています。handleSystemAlertがラベルのない SpringBoard のボタンを扱うのと同じ方法で、既存のindexセレクタフィールドによって個々のセルを区別します。 - actuation は、解決したセルの正確なフレーム中心への生の座標タップです。この再利用型のコレクションビューに対しては、同じセルへのハンドルベースのタップが失敗する(
element vanished/ElementNotTappable)ことが確認されているためです。 seedPhotosprecondition(Preconditions.seed_photos)は、simctl addmediaを介して Simulator の写真ライブラリにフィクスチャ画像をシードし、グリッドの内容を再現可能にします。seedPhotosは、実効のsubject.reinstall: eraseを要求し、ロード時に検査します。実効値は、シナリオの値、なければターゲットの値に、--erase/--no-eraseを反映したものです。再利用中のライブラリでは、何もシードされないまま黙って通ってしまうためです。SELECT_PHOTOScapability でゲートされています。これを宣言するのは XCUITest と adb のバックエンドで、adb は API 33 未満のデバイスをステップの実行時に断ります。web は preflight で拒否されます。
DSL のシステムアラートと tip の処理¶
- DSL の
handleSystemAlert(BE-0316)は、SpringBoard の権限プロンプトのボタンを、ネイティブなアクセシビリティ照会(ランナーの 2 つ目のオンデマンドな SpringBoard ハンドル)で tap する、決定的で iOS 専用のステップです。 - 解決は Python 側の
resolve_uniqueに残ります。この能力を宣言するのは XCUITest バックエンドだけなので、Android と web は preflight で失敗します。 - label が決定的になるのは、XCUITest のライフサイクルが cold spawn のたびに Simulator 自身のシステム言語を run の
localeに固定するからです。SpringBoard はアプリの launch 引数が届かない別プロセスなので、固定はグローバル設定ドメインへの書き込みと再起動 1 回で行います。warm な runner の再利用は、その locale が一致していることを条件にします。 permissionsで先回りできないプロンプトがあります。通知の許可、ATT、そしてプロセスをまたぐペーストの同意(BE-0369)です。これらについては、selの代わりにpromptとchoiceも指定できます。固定した locale が描画する label を、run が解決します(BE-0320)。- label の対応表にない言語では、ステップは
promptとchoiceを持ったまま、ボタンの位置で答えます(BE-0445)。3 つのプロンプトのどれでも SpringBoard は拒否側を 1 番目、許可側を 2 番目に並べることを、右から左に書く言語を含む複数の言語で測って確かめています。位置はアラートを読むたびにその場で解決し、ボタンの数が違うアラートには決して当てはめません。 - プロンプトを待つ待機を持っているのは、ドライバではなくオーケストレータです(BE-0406)。
- ドライバは SpringBoard を 1 回照会して tap するだけです。
wait_for_system_alertが、ステップ自身の期限までポーリングします。毎ポーリングで、まずステップの対象を読み、そのあとに次項のリアクティブなガードを回します。 - 待機をここに置いたからこそ、ステップが待っているあいだに、ガードが割り込みを片付けられます。ドライバ自身のループの中では他の何も動けず、宣言済みのプロンプトがステップの
timeoutのあいだ画面を覆ったままでした。 - BE-0461 以降、ステップ自身のツリー読み取りはツリー内の処理だけを行うので、SpringBoard のアラートはステップに残ります。
- ステップが自分のものではないと判断したアラートは、
POST /systemAlert/resolveへ送ります。このエンドポイントは、そのアラートがステップの読んだボタンをそのまま示している間だけ答えます。そのため、両者が同じプロンプトに答えることはありません。
- ドライバは SpringBoard を 1 回照会して tap するだけです。
- そのリアクティブな対極である DSL の
systemAlertの interrupts エントリ(BE-0315)は、アラートガードです。BE-0473 まではsystemAlertHandlingキーでした。 - シナリオの
interruptsとターゲットのhooks.interruptsにあるsystemAlertエントリが名指しするプロンプトに、モデルを呼ばずに答えます。エントリ 1 件が規則 1 つにあたります。 - BE-0461 以降、XCUITest バックエンドは、Python 側の監視ではなく、画面を読むリクエストの中でプロンプトに答えます。
- 対象のガードのもとでは、wait の各ポーリングと、アクションが対象を解決するための読み取りが、
GET /elements?resolveAlerts=trueを送ります。runner はそのリクエストの中で、次の 3 段階を実行します。- ネイティブの規則が名指しする SpringBoard アラートのボタンを押します。SpringBoard の確認は
pollInterval(既定 1 秒。wait 自身のポーリング周期とは別です)につき 1 回までです。 - スナップショットを取ります。
- 新たな確認で SpringBoard アラートがないとわかった場合に限り、ツリー内の規則が名指しするアプリ内プロンプトをタップします。
- ネイティブの規則が名指しする SpringBoard アラートのボタンを押します。SpringBoard の確認は
- 応答はツリーと、答えた記録を運びます。記録はそれを消費する drain を通ってレポートに届くため、1 つの応答は 1 回だけ報告されます。
- runner は表示 1 回ごとのメモを持ち、押すすべての経路がこのメモを共有します。メモは再押下の間隔を空け、3 回押しても消えない表示には gave up を記録します。
- アサーション(
assert、expect、extract、if)と証跡は、通常の読み取りのままです。チェックが自分の見ている画面を変えることはなく、スクリーンショットは実際の画面を写します。 - ほかのバックエンドは、Python 側の collapsed-tree proxy だけを使います。
- BE-0402 以降、このガードは全経路が決定的です。何も対処できないときは何もせず、見たものを注記として失敗に添えます。注記は次の 3 つの形のいずれかです。
- どの規則も同定しない SpringBoard アラートは、ボタン名で示します(
… — an unhandled system alert is blocking the screen (buttons: Allow, Don't Allow))。 - 押しても消えなかったプロンプトは、規則が選んだボタンで示します。
- 記録で説明のつかない崩れたツリーには、ボタン名を挙げない曖昧な形の注記が付きます。
- どの規則も同定しない SpringBoard アラートは、ボタン名で示します(
- ガードの宣言の経緯は、次のとおりです。
- BE-0402 より前は、最後のケースでスクリーンショットをモデルに読ませる AI 視覚ガードへフォールバックしていました。
visionInstructionが操作していたのはそのフォールバックだけなので、runはどのシナリオも実行する前にこれを拒否します。 - 続く BE-0406 は、
rulesをガードの宣言のすべてとし、labelsを削除しました。ボタンのラベルが名指ししていたのはボタンであってアラートではなく、シナリオが記述していない画面へのタップまで許してしまっていたからです。
- BE-0402 より前は、最後のケースでスクリーンショットをモデルに読ませる AI 視覚ガードへフォールバックしていました。
- 宣言の重ね方は、次のとおりです。
rulesは 2 つの層(シナリオ、次にターゲット)を、内側から連結します。- 2 つのスカラーである
pollIntervalとfrozenScreenTimeoutは、それぞれ値を持つもっとも内側の層を取ります。 - プロンプトと選択の組をフラグの値 1 つで読みやすく運べないため、コマンドラインが与えられるのは
pollIntervalだけです。
- XCUITest バックエンドでは、
frozenScreenTimeout(既定 10 秒、0で無効化)が、もう 1 つの停止も制御します。- 読み取り自身の SpringBoard 確認ではアラートなしと出たまま、アプリケーション配下のどの要素もラベルや識別子を持たない状態が続くことがあります。その状態がこの秒数続くと、
forやscreenChangedの wait は期限を待たずに諦めます。 - シナリオ側は、
rulesにsavePasswordのようなアプリ内プロンプトを宣言することで、この停止にオプトインします。 gone/settledの wait は、画面が固まった状態そのものがすでに条件を満たすため、この形では停止しません。
- 読み取り自身の SpringBoard 確認ではアラートなしと出たまま、アプリケーション配下のどの要素もラベルや識別子を持たない状態が続くことがあります。その状態がこの秒数続くと、
- ラベル表は、プロンプトごとに、3 つの応答面(
handleSystemAlertステップ、runner の SpringBoard 確認、ツリー内の処理)のどれに届くかを記録します。- iOS がアプリ自身のプロセスに出す
savePasswordは、規則としては宣言でき、答えられるのはツリー内の処理だけです。 - ステップのほうは、空のボタン一覧を期限までポーリングする代わりに、解析時にこれを拒否します。
- iOS がアプリ自身のプロセスに出す
- 1 つのステップが行うアラート再試行は、1 回までです。
- 再試行を受けるステップの失敗は 4 種類です。拒否された操作、セレクタの読み取りで見つからなかった対象、失敗した
assert、失敗した位置で答えるhandleSystemAlertステップ(BE-0445)です。最後のステップはゲートなしで待機します。失敗したexpectも同じです。 - 再試行では、強制の読み取り(
forceCheck=true)を 1 回送り、SpringBoard 確認の間隔制限を越えます。 - 2 回目の実行を許すのは、応答があった場合、メモが押下を保留した場合、ステップ自身の読み取りが答えていた場合です。そのときは画面が落ち着くのを待ってから、ステップ(または
expect)をもう一度だけ実行します。 - この待ちは、ツリーが動かなくなるまでの条件待ちで、上限は 1 秒のベストエフォートです。tap されたプロンプトは、まだ消えたプロンプトではありません。
waitは、ポーリングのたびに処理済みなので、この再試行を受けません。handleSystemAlertステップ自身のツリー読み取りはツリー内の処理だけを行い、ステップ自身の SpringBoard アラートはステップに任せます。ステップが読んで自分のものではないと判断したアラートは、ガードの周期でPOST /systemAlert/resolveへ送ります。runner は、そのアラートがステップの読んだラベルをそのまま示している間だけ答えます。そのため、入れ替わりに現れたステップ自身のプロンプトに、ポリシーが答えることはありません。
- 再試行を受けるステップの失敗は 4 種類です。拒否された操作、セレクタの読み取りで見つからなかった対象、失敗した
- 進行中の操作に割り込むアラートは、どの読み取りが答えるよりも前に、XCUITest 自身が処理します。何もしなければ、XCUITest はアラート自身の既定ボタンで応答してしまい、シナリオのポリシーをレポートに何も残さないまま黙って上書きします。
- そこでランナーは割り込みモニタを組み込みます。リアクティブなガードと同じく、規則が名指すボタンを押したうえで、押したボタンを通常の
AlertEventとして記録します。 - ボタンのラベルはオーケストレータが解決し、シナリオごとに 1 回
POST /interruptionPolicyで送り込みます。ガードがシナリオを対象にしているかどうかも、このとき同じ 1 回で送ります。 - 規則はそれぞれ表示面を持ち、モニタが照合するのは native の規則だけです。プロセス内のプロンプトは、別プロセスの操作に割り込みません。
- in-tree の規則は、ランナーが画面を読む要求の中でそのプロンプトに答えられるように、ガードのペース制御の値と一緒に送ります(BE-0461)。
- そこでランナーは割り込みモニタを組み込みます。リアクティブなガードと同じく、規則が名指すボタンを押したうえで、押したボタンを通常の
handleSystemAlertステップ自身が使う prompt/choice の形は、この rules に含まれるとは限りません。ステップという形があるのは、systemAlertエントリとして宣言しない選択を認めるためです。- オーケストレータは、そのステップが待っている間だけ、シナリオ自身の規則に加えて、ステップ自身の対象を 1 つ追加で送ります。
- ステップが答え終わる、失敗する、あるいは待機自体が例外で終わるいずれの場合も、シナリオ本来の方針に戻します。
- 追加の規則がないと、先行する操作の割り込みが同じプロンプトと先に出会い、一致する規則がなく、このステップがまさに正しく答えようとしていたアラートのせいで失敗することがあります。
- ポリシーがボタンを名指ししないプロンプトは、従来どおり XCUITest 自身の既定ハンドラに委ねられます(BE-0399)。この tap 自体は変えられません。
- 変わるのは沈黙のほうです。BE-0406 以降、対象になっているガードは、辞退する前に、規則が同定しなかったボタンの一覧を記録しておきます。
- その割り込みに遭遇したステップや
expectは、シナリオに代わって何かが答えたかのように続けるのではなく、ボタン名を添えて失敗します。
- フォアグラウンドの通知バナーも同じモニタに届きますが、ポリシーを見るより前に別の分岐へ入ります(BE-0416)。バナーは規則が同定できるボタンを持たず、唯一タップできる領域を押すと通知元のアプリが開いてしまうからです。
- モニタは、バナーが画面内で静止するのを待ってから、バナー自身の実測フレームを起点に上方向へスワイプします。
- 消えたことを確認してから割り込みを引き受けます。スワイプで消えなかった場合は、バナーが自動的に消えるのを待ちます。iOS 26.5 では XCUITest 自身のハンドラはバナーを無視し、その照会の失敗が runner を止めてしまうからです。
- 引き受けたバナーは、
notificationBanner種別のAlertEventとして記録に残ります。並ぶ文字列はボタンではなく通知本文だからです。 - この分岐が
governsの判定より前にあるのは、アラート側のどちらの結末もバナーには合わないためです。対象になっているポリシーは、バナーを未宣言の割り込みとして記録し、本来通るはずのステップを落としていました。対象外のポリシーは、バナーを XCUITest が待ち切るまで放置し、割り込まれた操作 1 回あたり約 9 秒かかっていました(割り込みがなければ約 0.6 秒です)。 - ガード自体は既定で有効で、
--no-system-alert-handlingですべてのシナリオについて無効化できます。バナーの分岐は、ガードの有効・無効にかかわらず動きます。
- このモニタにバナーが届くのは、何かに割り込んでいるときだけです。ただの問い合わせでは監視は起動しないため、何もタップしていない画面に居座るバナーは、ここでは消えません(BE-0416 の作業単位 2・3・8)。この隙間を塞ぐのが、もう 1 つの能動的な経路です。
Driver.notification_banner_frame()は、同じ SpringBoard の要素を待ち合わせずに一度だけ読みます。これを許可する能力トークンはHANDLE_NOTIFICATION_BANNERで、宣言するのは XCUITest バックエンドだけです。照会先はalertsではなく、SpringBoard の全ツリーに対する識別子NotificationShortLookViewです。- ステップループは、ステップごとに 1 回、
after.pngの撮影直前でこれを呼びます。この経路が塞ぐのは、その撮影と、そこから作るビジュアルリグレッションの比較画像です。 - バナーが見つかると、割り込みモニタと同じ上方向へのスワイプ先を
notification_banner_swipe_pointsが計算します。専用のジェスチャを足さずに、通常のswipeアクションで消します。 - ただし消すのは、その結果が、割り込みモニタ自身のスワイプがバナーの上端を越える 20 ポイント以上を進む場合だけです。まだ描画途中のバナーを基準に計算すると、上限に張り付いた終点が始点に近すぎて、極端な場合は始点より下になり、下方向へ反転して、実際の dismiss には足りない長さになることがあります。そのような枠には手を出しません。
- ジェスチャそのものを送る直前にも、あらためて存在を確認します。確認した瞬間と実際にスワイプする瞬間のあいだにバナーが自動的に消えていれば、その場に残っているものへスワイプを送ってしまうからです。
- スワイプの直後には、消えたことを上限付きで再確認します。割り込みモニタ自身が、消えたことを確認してから割り込みを引き受けるのと同じ流儀です。
- この照会は、ガード自身が解決した
pollInterval(ガード無効時は BE-0315 が定めた値)でレート制限します。通るシナリオが払うコストは、ステップごとではなく間隔ごとに 1 回です。 expectフェーズのビジュアル撮影の直前も同様に確認しますが、対象はvisualアサーションがある場合だけです。ステップ自身のassertが持つvisualエントリの撮影の直前も、同じく確認します。上記のレート制限付きスイープはステップ本体のあとで動くため、本体の中で撮るこの撮影には間に合わないからです。- シナリオや CLI 側のトグルは持ちません。バナーはシナリオから観測できないため、消してもシナリオが壊れる心配はありません。この「トグルに使い道がない」という判断は、上記の割り込み経路がすでに下したものと同じです。
- iOS の TipKit tip に対する opt-in ガードが、DSL の
- tipKit: dismissの interrupts エントリです(BE-0389)。BE-0452 まではトップレベルのiosTipKitHandling、BE-0473 まではtipKitHandlingでした。 - TipKit の提示は、覆う内容をアクセシビリティから隠すのであって、単に重ねて表示するのではありません。そのため、ブロックされた tap は
ElementNotTappableだけでなくElementNotFoundとしても失敗しえます。 - XCUITest バックエンドだけが
Capability.HANDLE_TIPKIT_TIPを宣言し、PopoverDismissRegionscrim を解決してDriver.dismiss_blocking_tip()を実装します。ガードはこの scrim を、tip 自身のコンテナTipViewと組み合わせて要求します。アプリ自身の popover(confirmationDialogが同一の scrim を設置します)には、手を触れないためです。 - tip はすでに、どの wait のポーリングも tap の解決もフェッチする同じアクセシビリティツリーに現れるため、Swift ランナー側の変更は不要です。
- ステップループは、dismiss が実際に tip を見つけて片付けたときだけ、ステップを 1 回リトライします。このリトライは、アラートガード自身のステップ末尾の分岐の隣に置かれます。dismiss は BE-0314 の
on_interrupt_pollフックにも合成されるため、tip 1 つのために wait がタイムアウトいっぱいまで保持されることもありません。 - アラートガードと異なり、既定は無効です。シナリオが tip 自体をアサーションの対象にすることがあるためで、そのシナリオは
- tipKit: leaveと書いて、ターゲットのdismissを打ち消します。 - 解決の順序は flag > scenario > target で、どれも指定しなければ無効です(BE-0177)。
--ios-tipkit-handling/--no-ios-tipkit-handlingは、すべてのシナリオのエントリをdismiss/leaveに設定します。 systemAlertエントリのほうは、プロンプトごとに重ねます(BE-0401、BE-0473)。
DSL のクロスアプリ操作¶
- 決定的な DSL
appは iOS(XCUITest)と Android(adb)で使えます。このステップは、テスト対象アプリが一度も起動していないアプリを、バンドル ID でアプリ側の協力なしに activate します。そして入れ子のstepsを、そのアプリ自身のアクセシビリティツリーに対して実行します。 XcuitestElementProviderは、固定の単一ハンドルの代わりに、XCUIApplicationハンドルのスタックを持ちます。ブロックへ入ると新しいハンドルを push して.activate()し、抜けると 1 つ下へ pop します。appブロックを別のappブロックの中に入れ子にした場合、戻る先は直近の親です。- Python のドライバは、テスト対象アプリ自身の
XcuitestDriverインスタンスをそのまま再利用します。webステップは専用のWebContextDriverを使いますが、appはネイティブの操作面(tap、type、ジェスチャ、picker wheel)をそのまま必要とするため、同じインスタンスを再利用するほうが得るものが大きいからです。 - Android では、adb ドライバが runner なしで同じことを行います。まず
cmd package resolve-activity --briefでパッケージの launcher activity を解決し、am start -W -nで起動します。続いて、そのパッケージが resumed activity を持つまでdumpsys activity activitiesを上限付きでポーリングします。時間切れならElementNotFoundを送出します。leave_appはドライバ側の app スタックを使い、1 つ下のアプリを前面へ戻します。 APP_CONTEXTcapability でゲートします。宣言するのは常駐 runner の XCUITest backend、adb backend、FakeDriverです。そのため preflight で弾かれるのは web だけで、デバイス側の作業より前の段階で弾かれます。webの WebView bridge の可否は、固定の backend capability ではなく実行ごとの事実であり、実行時に失敗するのとは対照的です。- この設計に先立って、実現可能性のスパイクが、
activate()が協力しないアプリ(Safari・Maps・Contacts)を Simulator 上で確実に前面化することを確かめました(docs/specs/ios-cross-app-ui-control-feasibility.md)。
証跡、ネットワーク観測、レポート¶
- 証跡には、次の種類があります。
- 瞬時の証跡:
screenshot、elements、actionLog、rawTree。actionLogは、ステップごとの具体的な actuation、つまり送った座標、ジェスチャの形状、それを運んだ経路を持ちます。rawTreeはelementsの元になった生ダンプで、opt-in、adb と XCUITest が対応します。 - 区間の証跡:
video、deviceLog、appTrace。 - ネットワーク collector(
network.json)。 - ビジュアルリグレッション:baseline に対する
visual。approveコマンドで baseline を昇格します。 capturePolicy発火。- 書き出し前の、ログ、要素ツリー、ネットワーク exchange への redaction 適用。
bajutsu run --touch-markers(BE-0371、iOS 限定、BajutsuKitをリンクするアプリが必要)は、アプリのUIEventキューが実際に配送した各タッチを、マーカーとして描画します。- マーカーは、ジェスチャが実際に届いた証跡です。録画と各ステップのスクリーンショットへ描画します。
- 既定では無効で、リポジトリ自身の iOS CI レーンでは有効です。
visualアサーションが比較する 1 回の撮影のあいだだけ、アプリ内制御チャネル(BE-0365)でマーカーを非表示にします。- ネットワーク観測と決定的モック(シナリオ
mocksがプロトコル内スタブになる。実機検証済み)は、requestアサーション、wait: { until: request }、オフラインのスタブ応答を含みます。 request/eventのqueryとbodyフィールドは、正規表現の代わりにキーと値の辞書を受け取ります。この辞書はrequestSequenceとresponseSchema.requestでも共通して使えます。- 順序に依存しないのは、クエリパラメータと JSON のキーです。
$matches/$exists演算子も使えます。bodyでは入れ子の map とリストも扱え、リストは同じ長さの配列を要素ごとに比べます。 mocksはこの 2 つのフィールドを受け付けず、従来のmatchの文法のままです。完全一致のmethod/url/pathと、urlMatches/pathMatches/bodyMatchesの正規表現です(BE-0463)。- iOS では、
setMocksステップが、アプリ内制御チャネル(BE-0365)を通して、シナリオの途中でアプリのスタブテーブルを置き換えます。 - 画面遷移シグナル(BE-0310、iOS):
BajutsuKitのオプトインのBajutsuScreenがUIViewController.viewDidAppear(_:)を swizzle し、完了したビューコントローラの出現をそれぞれコレクタの/transitionsエンドポイントへ報告します。 NavigationStackの push、シートの提示、タブの切り替えはいずれもUIHostingControllerに支えられているため、UIKit と SwiftUI のどちらも同じように覆います。同じプロセスにあるネットワーク通信のストアとは独立しています。- 起動直後の readiness ゲート(
await_ready)は、BE-0218 の namespace/要素数のヒューリスティックの上に新設した段として、このシグナルを参照します。ただし明示的なsubject.startWhenはそれより上位で、base 画面の遷移がsubject.startWhenの待つモーダルを先取りすることはありません。 settled待ちは、ツリー差分のポーリングに代えて、このシグナルを静止の窓によるデバウンスとして参照します。- observer を組み込まない(あるいはまだ遷移していない)ターゲットでは、どちらもツリー差分の挙動のまま変わりません。
- フェイクのシグナル源で高速ゲートのテストは済んでいます。UIKit と SwiftUI の双方でのオンデバイス確認は、この項目自身のゲートであり、
demos/showcase/BE-0310-screen-transition-verification.ja.mdで追っています。 bajutsu run --trace-driver(BE-0415、既定では無効)は、シナリオごとの driver 呼び出しトレースを、そのシナリオの他の証跡と並べてdriver_trace.jsonに書き出します。- Python↔driver の呼び出し(
driver)と、その内側の各ホスト・デバイス間往復(transport。Android のサブプロセスへのフォールバックを含む)を、タイミングとステップ/試行(attempt)の帰属つきで記録します。 --score/--zipと同じく、診断専用です。transport/subprocessの往復の記録は XCUITest と adb だけが対象ですが、フラグ自体はバックエンドで切り替わらないため、web(Playwright)のランでもdriver階層のレコードは書き出されます。bajutsu run --step/--break/--break-on-fail(デフォルトでは無効)は、ステップループを止める step gate です。gate は、キャンセル判定の隣にあるステップの境界(_StepRunner.exec_steps)で呼ばれます。- 止めているあいだ、オペレーターは
replと同じコマンド群で、動作中のアプリを読み取れます。 - gate が行うのは、実行を続けさせることと、
quitでRunCancelledを送出することです。判定は決めません。 - アプリを操作するコマンドを実行すると、
RunResult.interactiveに記録してシナリオを失敗にします。手動操作を含む実行は、成功として通りません。 - 対象は、シナリオ 1 つ、エンジン 1 つ、ワーカー 1 つ、対話端末の実行です。
- シナリオごとの
result.json:ランナーは各シナリオが終わった時点で、その判定を<sid>/result.jsonに書き出します。 - 中身は
manifest.jsonがそのシナリオについて持つものと同じエントリです。途中で強制終了された実行でも、完了したシナリオの判定は残ります。 - 書き出しに失敗したときは、警告して実行を続けます。
manifest.jsonが引き続き唯一の情報源です。 - レポート(
manifest.json/junit.xml/ctrf.json/report.html)。 - config 解決(defaults × templates × targets、redact マージ)と actuator 選択。
simctlコマンド層、XCUITest のオートメーションスナップショットのパーサ、doctorスコアとバックエンド別の実行可能ゲート(preflight.py)。iOS は必須 CLI と起動済みシミュレータを要し、web は Playwright とその Chromium ブラウザを要します。traceコマンド(trace.py):保存済み run のテキストタイムライン(steps、network、appTrace)。- M4 自己修復トリアージ(
triage/heuristic+agents/claude_triage)は、失敗 run のコンテキストを組み立て、TriageAgentの診断を得ます。 - 診断は、ルールベースの
HeuristicTriageAgent、または失敗スクリーンショット込みの--aiの Claude が行います。 - エージェントは構造化 fix(
renameId/addIndex/raiseTimeout)を提案できます。 --apply/--writeでシナリオ source に適用し(diff プレビュー、opt-in)、--rerunで再実行して検証します。
CLI、serve、codegen¶
- CLI:
run/doctor/audit/coverage/impact/stats/flakiness/export/trace/report/triage/record/crawl/repl/codegen/approve/serve/mcp/worker/lint/schema/config/runner。 recordとcrawlが Tier 1 の AI オーサリング経路で、alert guard を伴います。replは、その隣に並ぶ、AI を使わない手動シェルです(BE-0423)。repl --attach(BE-0455、ローカルの iOS Simulator 限定)は、この手動シェルを、すでに動いている target アプリへ erase もインストールも再起動もせずに接続します。オペレータは、すでに見ていたその画面をそのまま調べられます。動いていないアプリは起動しますが、そのときも erase やインストールはしません。- 解析済みのデバイス OS(
common/devices/os.py、BE-0358)は、デバイスの OS バージョンを、プラットフォーム、メジャー、マイナーからなる小さな解析済みの事実として持ちます。値は、run がシナリオごとにすでに記録しているdevice_runtimeのラベルから読みます。 - ラベルがないか解釈できないときは、推測したバージョンではなく「不明」として解析します。
- 2 つのフレーキネス面は、この値をグループ化のキーに持ちます。シナリオの判定履歴は OS バージョンごとに分かれ、バージョン間で再現する差異が、フレーキネスとして採点されることはなくなります。
- XCUITest ドライバは、
make_driverのキーワード引数として受け取ります。Driverのメンバーにすると、すべてのバックエンドとテストダブルが宣言し直すことになるためです。これにより、ドライバ層の失敗は、どの OS で起きたかを名乗れます。 - OS を読めることは、OS で分岐してよいという許可ではありません。 挙動の OS 差はバージョンに依存しない形で直す、というのがこのリポジトリの立場です。OS ごとの分岐は、その代案に対して、それ自身のロードマップ項目で論証する必要があります。
- 実機も AI も使わない読み取り専用の助言的な分析コマンドは、CI を止めません。入力が欠けている、読めないときだけ非ゼロで終了します。コマンドは、次のとおりです。
- 静的、repeat-and-diff、longitudinal の 3 モードを持つ決定性・フレーキネス監査(
audit、BE-0049)。 - シナリオの id 名前空間カバレッジマップ(
coverage、BE-0050)。 - カバレッジ索引を反転して、
gitの diff から影響するシナリオステップを選ぶテスト影響分析(impact、BE-0321)。 - CLI / HTML 出力の集計 run 統計ダッシュボード(
stats、BE-0102)。 - runs ディレクトリまたは
serveのデータベースから見る、クロスランのフレーキネスランキング(flakiness、BE-0220)。 - 完了した run を持ち運び可能な
.zipにまとめる export(export、BE-0060)。 - 保存済みの run データから、再実行なしに
report.html/junit.xml/ctrf.jsonを再生成する report(report、BE-0068)。 - run 履歴のラベルと target の刻印(BE-0404):run は、実行した config と、実行した target を記録します。
runs.labelは、config 自身の名前か、明示したrun --labelの値です。runs.targetは、manifest から写します。- 別の config で
serveを起動し直しても、1 つに混ざった履歴ではなく 2 つの読み分けられる履歴になります。target 単位の比較が、保存済みのデータから計算できます。 - org の行は、その org が最後に bind した config ソースを 1 つ保持します。アップロードされたバンドルを受け取っていない別のレプリカが、そこから復元します。展開済みのバンドルを手元に持つレプリカは、オブジェクトストアを要求する前にそのキャッシュを解決するので、取得せずに bind し直せます(BE-0393 の作業単位 5)。今日 config の記憶を持つデプロイはいずれもストアを持つので、これは作業単位 6 と 7 が開くデプロイ形態への地ならしです。
- この変更は、BE-0225 の名前付きプロジェクトレジストリを置き換えたもので、テーブル、エンドポイント、CLI コマンド、Web の画面はいずれも無くなりました。
- ログインセッションごとの config バインディング(BE-0393 の作業単位 1、2、6、7)。バインドされた config を構成していた 6 つのフィールドは、config のパス、相対パスの解決基準となるディレクトリ、Git の来歴、バインド中のバンドル、API 経由で bind した Git かどうかの信頼フラグ、bind した org です。これらを 1 つの不変値にまとめ、ログインセッションと acting org の組で引きます。
- bind は、それを行ったセッションにだけ見えます。1 つの org の 2 人が同時に作業でき、片方の切り替えが同僚の run を差し替えることはありません。2 つ目の org でサインインしても、1 つ目の org から config を奪いません。
- 何も bind していないセッションは、デプロイ自身のバインディングを読みます。これは
serveが起動した config で、そのorgs:ブロックがオペレータの書いたとおりに target を分割します。共有が既定のままで、単一テナントのserveは挙動が変わりません。 - 3 つの読み出しは、意図的にデプロイ全体の答えを保ちます。サインインの org モデル(セッションで bind した config が、サインインできる人を決めてはなりません)、AI の鍵を保持する環境変数、そして usage ledger です。
- 自分のバインディングを持たないセッションは、その org が最後に bind した config を、そのセッションの最初のリクエストで復元して引き継ぎます。best-effort なので、ファイルが移動していたりリポジトリに到達できなかったりすれば fallback のままとし、再試行はしません。遅延させるのは、サインインを fetch で待たせないためと、セッションの acting org はサインインなしに変わりうるためです。
- この記憶は、すべての bind が書きます。アップロードされたバンドルだけでなく、ファイルブラウザで選んだものも Git spec も含みます。
- ヘッダーは、そのセッションが 3 つのうちどれを読んでいるかを示します。メンバー自身が bind したものか、org が最後に bind したものを引き継いだものか、デプロイ自身のものか、という区別です。bind のダイアログは、ここで bind したものが同僚の次のセッションの出発点にもなることを、bind するその場で伝えます。復元は、それが代行している bind と同じように監査ログへ記録します。
- job は受理された時点で作業ディレクトリを固定します。dispatch から spawn までの間に rebind されても、受理済みの run が別の場所を向くことはありません。
- データベースを出どころとする org のライフサイクルとメンバーシップ(BE-0375):データベースを繋ぐと、org の
members/githubOrgs/githubTeams/editorTeamsは、config ファイルのorgs:ブロックではなくorgsテーブルに置かれます。起動時と config の再 bind のたびに、そのブロックから org ごとに一度だけ書き写し、以後はデータベースが持ちます。 serveは、admin 専用の/api/orgs…エンドポイントを 4 つと Orgs ページを持ちます。再デプロイなしで、テナントの作成、メンバーシップの置き換え、soft delete ができます。- サインインの解決はテーブルだけを見ます。config が読めなくても全ユーザを拒否することはなくなり、データベースが読めないときは、ストアを名指しする 5xx で答えます。
- target の識別子は
(org, target)になり、同じ名前を 2 つの org がそれぞれ要求できます。 - target の所有そのものは config に残ります(prime directive 3)。データベースを繋がないデプロイは、従来どおり
orgs:を読みます。 - サインイン時のアクティブ org 選択(BE-0395):GitHub のメンバーシップが複数の org に一致するログインは、従来はランキングが先に置いた org へ固定され、ヘッダーのバッジには他の org が存在することを示す手掛かりがありませんでした。
- サインインは、そのログインが振る舞えるすべての org を、それぞれで持つロールとともに記録します。ヘッダーは、それらを単純なバッジの代わりにセレクタとして提示します。
- ただし admin Team によって受け入れられた admin は例外です。サインイン時に保存した集合ではなく、生存しているすべての org を、その都度読み直して提示します。サインイン後に Orgs ページで作った org も、再サインインなしにそのまま現れます。
- アクティブな org は依然として単一のカラムであり、
ServeState.org_ofが読む先も変わらないため、org スコープの読み書きは以前と同じ経路を通ります。 users.org_selected_atの印が、ユーザ自身が選んだ org と、単に解決されただけの org を区別します。サインインは、選択がなお適格であるかぎりそれを維持し、適格でなくなった場合は解決し直します。選んでいた org から外されたユーザは、新しい適格リストの先頭に着地します。- 単一 org のデプロイでは、バッジの見え方は変わりません。
- CI ジョブ自身の識別情報(BE-0414):
permissions: id-token: writeを宣言した GitHub Actions のワークフローは、GitHub が発行する OpenID Connect(OIDC)トークンをPOST /api/oidc/exchangeへ一度だけ提示します。 - serve は、発行者、JWKS(JSON Web Key Set)、デプロイが設定した
aud(未設定なら OIDC 経路そのものを無効化)を検証します。そして、以後の呼び出しが使う短命なマシンセッションを発行します。 - どの org として振る舞うかは、リクエスト自身が指定します。org の指定は選択であって、権限の付与ではありません。1 つのリポジトリを複数の org が列挙できるため、指定された org の
allowedRepositoriesが受け入れたときにだけ、セッションを発行します。判定は、トークンのrepositoryクレームへの完全一致で行います(subはパースしません)。エントリごとに、environment/ref/workflowRefで絞り込めます。 - マシンセッションは、人間の OAuth セッション、worker の共有トークンに次ぐ 3 つ目の呼び出し元です。ロールではなく、
gate.pyの明示的なエンドポイント許可リストで権限が決まります。許可リストは、GET /api/artifacts/existsによるアーティファクトの有無の確認、3 種類のアーティファクトのアップロード、POST /api/run、POST /api/run-setとGET /api/run-set/<groupId>(BE-0484)、自 org の run と発行したジョブの読み取りです。 - リポジトリ単位で失効できます。データベースなしのデプロイや、セッションの有効期限を守れないストアでは拒否されます。
- 有効な config の binding とは独立した、job 単位のアーティファクト差し替え(BE-0431)。ホスト型デプロイでは、
POST /api/runがbinaryArtifactとscenariosArtifactを受け付けます。どちらも、保存済みのアーティファクトの sha256 です(BE-0268)。 - 指定した方の脚は、そのアーティファクトだけを解決先とします。binary はその job 自身の target の
subject.pathに配置し、scenariosの zip はその target の scenarios ディレクトリを置き換えます。 - 指定しなかった脚は、従来どおり org の有効な config の binding を解決先とするため、そちらは変更されません。この結果、1 つのデプロイに対する 2 つの同時 CI ディスパッチが、デプロイのフォールバック binding を奪い合ったり、org の記憶済み設定を書き換えたりすることがなくなります。
- worker は、ジョブのワークスペースを override の識別子でキー付けするため、同じ worker 上の後続ジョブが汚染されることはありません。bundle のキャッシュ木も、再取得せずに再利用します。
- job のキューがない状態(
UnqueuedExecutor。BE-0449)では、拒否されます。run-setのファンアウトでも拒否されます。ファンアウトの job は Device Farm worker(BE-0448)もリースでき、この worker は差し替えをリクエストへ対応づけないためです。 - 差し替えた sha256 は、それぞれ run の manifest の provenance に記録されます。
- target を横断する比較ダッシュボード(BE-0226。BE-0404 で軸を target に付け替え)は、
serveの Comparison タブです。bind している config の target を、pass 率、flaky 率、p50/p95 の run 所要時間、そして target ごとのトレンドスパークラインで、横並びに順位付けします。 - BE-0102 の config 単位の集計を、target ごとに 1 回ずつ実行して再利用します(
GET /api/metrics/targets)。BE-0102 と同じく、読み取り専用でアドバイザリです。 - 行を選ぶと、その target の run 履歴が読み取り専用で開きます。ポインタでもキーボードでも到達できます。
- この画面は何も書き換えません。target は binding ではないので、有効にするものが存在しないからです。
- AI crawl(
crawl/):アプリを自律的に幅優先で探索し、スクリーンマップ(screenmap.json)を作ります。 - サーバ自身は job を実行しません(BE-0449)。
serveは、すべての job をbajutsu workerのキューに積みます。対象はrun、run-set、triage、record、crawlです。 - 1 台のマシンでは、キューを
.bajutsu/の下の SQLite に置きます。 - バケットを指定したデプロイは
BAJUTSU_DATABASE_URLを設定する必要があり、設定しなければサーバは起動を拒否します。 - 非推奨の
--backendフラグは無視します。 - job のグループ(BE-0484)。
POST /api/run-setは、job_groupsの行と、シナリオごとに 1 つの job を 1 つのトランザクションで書き込みます。そのため、リクエストはすべてのシナリオを積むか、1 つも積まないかのどちらかです。- 各 job は、コマンドではなく実行意図(シナリオ、ターゲット、設定、プラットフォーム、アプリケーションのパス)を持ちます。リースした worker が、それをローカルの
bajutsu runかプロバイダーのバッチに変換します。worker は、実行した場所を run の provenance にworkerEnvironmentとして記録します。 - 各 job は、グループ、互換性、ルート、ベースの各キーを保存します。
maxJobsを付けた lease はバンドルを返します。バンドルに入るのは、扱えるもっとも古い job と、同じグループのうちルートキーが同じキュー上の job です(ルートを調べない worker では、ベースキーが同じ job です)。lease は、グループとルートキーの組ごとに候補を 1 つだけ調べます。 - グループの job には、同時実行の上限を登録時ではなく lease の時点でかけます。そのため、グループが途中で切られることはありません。
- Device Farm の worker は、同時に処理中の job どうしでアップロードを使い回します。アプリケーションは互換性キーごとに、パッケージはグループごとに保持します。処理中の job がそのキーを持たなくなると、アップロードを手放します。
- 各 job は、コマンドではなく実行意図(シナリオ、ターゲット、設定、プラットフォーム、アプリケーションのパス)を持ちます。リースした worker が、それをローカルの
serveローカル Web UI(Tier 1)は、次の範囲を備えます。- オーサリングと実行。 ブラウザからシナリオをオーサリング(
record/crawl)、編集、実行します。 - バンドルを開く。 config、シナリオ、ビルド済みアプリバイナリの
.zipバンドルをアクティブな config として開いて、各タブをそこから動かします(BE-0073)。 - Compose & load。 サーバは、この 3 つをそれぞれ独立した content-addressed な成果物としても受け付け、バインド時にそのツリーへ合成します(
POST /api/artifacts/{config,scenarios,binary}、BE-0268)。UI にも Compose & load パネルを備え、成果物ごとのドロップゾーンでブラウザ側でハッシュ化します。サーバがまだ持たないバイト列だけをアップロードしたうえで、要求に応じてバインド済みの config へ合成します。パネルを開き直すと、現在バインド中の合成内容から各ゾーンを事前入力します(ゾーンごとの Clear 操作つき)。変更のあった成果物だけを再アップロードすれば済み、POST /api/composeはリクエストボディだけで決まる純粋な処理のままです(GET /api/compose/current、BE-0325)。 - レポートと証跡。 レポートと証跡を閲覧できます。
- ファンアウト。 Replay フォームの Fan out to workers にチェックを入れると、Run フォームがファンアウトに変わります。複数のシナリオを選び Run を押すと、1 回の run ではなくシナリオごとの job を発行します(
POST /api/run-set、BE-0336)。リクエストは実行環境を指定しません。サーバは各 job を、ターゲットのプラットフォームを扱う worker へ振り分けます。ローカルの worker でも Device Farm の worker でもかまいません(BE-0484)。run-set パネルが、各シナリオの job を一覧で追います(BE-0465)。 - ゴミ箱。 Replay の履歴タブでも crawl でも、行ごとまたは一括で削除すると、実行は共有のゴミ箱へ移動するだけで、保持期間内であれば復元できます(BE-0239)。
- crawl の再開。 過去の crawl のスクリーンマップは、再開できます。残りのフロンティアを同じ予算とワーカー設定のまま続けて探索するか、剪定済みの 1 つの分岐だけを同じ予算で再探索します(BE-0181)。
- run 統計ダッシュボード。 集計 run 統計ダッシュボードの各軸(日付、backend、シナリオ、step/assertion のホットスポット)から、履歴一覧の該当する run へ直接ジャンプできます(BE-0241)。
- Flaky タブ。 クロスラン単位のフレーキネスランキングを表示する Flaky タブも備え、各行から代表的な成功・失敗それぞれの run の証跡へリンクします(BE-0220)。
- Usage ダッシュボード。 AI の利用状況・コストを帰属付きで記録する ledger を集計する、読み取り専用の Usage ダッシュボードも備えます。プロバイダ、モデル、コマンド、シナリオ別のトークン数と金額の合計を示します(BE-0195、BE-0196)。
- Coverage マップ。 ターゲットごとの Coverage マップも備えます。宣言済み
idNamespacesに対する名前空間別カバレッジ、ギャップ一覧、名前空間外の id を示します。run を選択するとエンドポイント/観測 id の各次元を、その run と併せて crawl も選ぶと画面到達状況の次元を追加します(BE-0146)。 - 単独ページ。 Stats・Flaky・Usage・Coverage の 4 つは、それぞれ単独でリンク可能なページとしても開けます(
GET /stats、/flakiness、/usage、そして対象を指定する必要がある/coverage?target=<name>)。 - 準備状況パネル。 Record と Replay のフォームでは、実行前の準備状況パネル(
doctor: 環境の runnability と現在画面の規約スコア)を確認できます(BE-0148)。 - シナリオビューア。 Replay のフォームでは、実行前に選択中のシナリオの生の YAML とランナー解析による構造化ステップを、読み取り専用で表示します(BE-0273)。config ビューアのシナリオ版で、実行の判定には関与せず、AI も使いません。
- シナリオのアップロード。 同じフォームには、シナリオのアップロード操作も備えます(BE-0340)。ローカルの
.yaml1 本は、既存のPOST /api/scenario経由で追加できます。複数本を束ねた.zipは、新設のPOST /api/scenarios/upload経由で追加できます。どちらも config の再バインドなしに、バインド済みの config のターゲットスコープへ直接反映されます。同名のファイルは、サイレントに置き換わるのではなく、上書きされたことがレスポンスで報告されます。zip の各エントリは書き込みの前にすべて解析され、1 件でも解析に失敗すると何も書き込まずアップロード全体を中止するため、不完全なバッチが部分的に残ることはありません。 - シークレットのパネル。 バインド済みの config が宣言する
${secrets.X}の名前を一覧する Scenario secrets パネルも備えます。値をブラウザから書き込み専用で設定でき、そこから起動する Record / Replay / Crawl の run に引き継がれます(BE-0274)。 - Server タブ。 実行中のサーバの解決済み設定を示す、読み取り専用の Server 設定タブも備えます(
GET /api/server、BE-0318)。デプロイモード、バインド済み config の来歴、backend、run の保存先・保持期間・並行数の設定を示します。加えて、このビルドが同梱の iOS XCUITest Simulator runner を出荷しているか、出荷しているならどのツールチェーンでビルドしたかも示します。 - テーマ。 プラグイン可能なテーマシステムを備えます。ドロップイン方式のビジュアルトークンと差し替え可能なトランジション、ヘッダーのピッカー、ライブプレビュー付きの UI 内エディタとローカル下書き / サーバアップロードの永続化です(BE-0191)。
- バージョンバッジ。 このページを配信している bajutsu 自身のビルドをヘッダーに示すバージョンバッジを持ちます(BE-0272、BE-0277)。
- バージョン文字列は常に表示します。Git チェックアウトから起動しているときは、短縮コミット SHA、ブランチ名、dirty 判定も添えます。
.gitを持たないセルフホストの Docker イメージでは、ビルド時に埋め込んだコミットにフォールバックします(BAJUTSU_BUILD_COMMIT。source: "build-arg"として示します)。- ブランチ名は作業中のトピックを含みうるため、チェックアウトの詳細は admin に制限します。
GET /api/versionは公開、GET /api/version/checkoutは admin です。どちらもリクエストのたびにgitの plumbing コマンドで最新を読み取り(環境変数へのフォールバックつき)、LLM は介しません。
- baseline とストリーミング。 ビジュアル baseline を承認し、ジョブをライブ配信します(CI 用ではありません)。
- MCP サーバ(
bajutsu mcp):bajutsu_runとbajutsu_doctorを MCP ツールとして、実行証跡をリソースとして公開します。Claude Desktop / Code との連携用です(オプション依存fastmcp)。 - シナリオ linter(
bajutsu lint/bajutsu schema):実行せずにシナリオを検証します。エディタ連携用に JSON Schema も出力します。 - codegen:シナリオからネイティブテストを生成します。共有のシナリオ走査(BE-0083)の上に、XCUITest(Swift、iOS)、Playwright(TypeScript、web)、UI Automator(Kotlin、Android。BE-0209)の 3 ターゲットがあります。
iPhone 17 Pro と近年の iOS の Simulator で検証済みの範囲¶
- XCUITest バックエンドの常駐 runner(
BajutsuKit)を実機で検証しています。Xcode のxcodebuildに対して確認したのは、次の項目です。XCTest のオートメーションスナップショットの読み取り、スナップショットハンドルによる要素解決、semantic(identifier)tap、text / swipe、simctllaunch 手順、simctl ioスクリーンショットです。 - showcase シナリオの実行、証跡の取得、triage 自己修復ループを、実機で走らせています(
make -C demos/showcase run-swiftui)。ios-e2e.ymlCI も smoke 経路を実行します。 - BE-0290 で idb を撤去して以来、この経路の iOS backend は XCUITest だけです。
- XCUITest バックエンドの
backとデバイス制御(setLocation/ クリップボード /push)を、実機上で実行しています。ios-e2e.ymlが PR ごとに検証します(BE-0281)。 pinch/rotateの multi-touch ジェスチャを、ios-e2e.ymlのrun (xcuitest)ジョブ(demos/showcase/scenarios/gestures_multitouch.yaml、--backend ios)で確認済みです。setPickerValueを、ios-e2e.ymlのrun (xcuitest)ジョブ(demos/showcase/scenarios/picker_wheel.yaml、BE-0356)で、実機で確認しています。対象はUIPickerViewとホイール表示のUIDatePickerの両方で、複数コンポーネントのwithin/traits/indexによるアドレス指定も含みます。android-e2e.ymlのスモークジョブは、同じシナリオを Compose と Views のショーケースアプリで実行し、NumberPickerとスピナー表示のDatePickerを確認します(BE-0480)。- シナリオ作成機能を実機上で実行しています。
ios-e2e.ymlのactuation (xcuitest)ジョブが PR ごとに検証するので、どの機能も adb と Playwright だけに依存しなくなりました(BE-0285)。機能は、extract、反復のあいだにツリーが変化するリストに対するforEach、data-driven の行、relaunchです。 - ネットワークの実経路を実機上で動かしています。
ios-e2e.ymlのnetwork (xcuitest)ジョブ(make -C demos/showcase e2e-network。BE-0282)が PR ごとに検証します。この経路では、BajutsuKitのアプリ内URLProtocolがモックされたリクエストに自前のスタブで応答し、各 exchange をループバック上の collector へ報告します。 - ジョブは
network_mock.yamlを実行します。スタブが 201 で応答するPOST /postで、実サーバなら 200 を返します。 - ジョブは
network_live.yamlを実行します。スタブを介さないカタログのGETで、観測されたという事実だけをアサートします。 - 続いて、永続化された
network.jsonをdemos/showcase/network/assert_network_evidence.pyでアサートします。モックされた exchange にmockedが立ち、そのAuthorizationヘッダとpasswordのフィールドがマスクされていて、生の秘密情報がファイルのどこにも残っていないことを確かめます。スタブを介さない exchange がmockedを false として記録されていることも確かめます。マッチ範囲の広すぎるモックが、何もスタブしていない通信を自分のものだと主張できない、ということです。 - ジョブは続けて
network_echo.yamlを実行します。専用のecho/サブディレクトリに記録するのは、上記の redaction チェックに 2 つ目の/postexchange を加えないためです。 network_echo.yamlは、secret を含むボディを外部の echo サーバへ POST し、アプリがその echo 値を表示することをアサートします。BajutsuURLProtocolが傍受したリクエストのボディを、空にせずそのまま転送しているかどうかを検査します。- 実際にキャプチャした資格情報が、出荷される証跡でマスクされるかを、iOS 上で観測できるのはこのジョブだけです。純粋な redaction のテストは、すべて手で組み立てた exchange をアルゴリズムに渡すからです。
- このジョブはゲート対象外です。実機の新しいカバレッジは、まずシグナルとして着地させます。下記の web 版が
E2E (web)に加わる前にたどったのと同じ道筋です。
Linux のブラウザで検証済みの範囲(Mac 不要)¶
- Playwright web バックエンドは、
demos/webのシナリオを、CI と同じmake checkゲートの中(ci.ymlのweb-e2eジョブ)で決定的に実行します。決定的コアがプラットフォーム非依存であることの裏付けです。 - リッチ寄りの web 取得(ネットワーク / 動画 / マルチタッチ)は、BE-0054 で実装済みです。
- N 個のブラウザプロセスにまたがる並列 web クロール(BE-0077)は、この同じゲートの上で動きます。
network (playwright)ジョブ(web-e2e.yml。BE-0282)が、実ネットワーク経路を実ブラウザに対して動かします。経路とは、page.routeの介入、requestfinishedのキャプチャ、mockedの来歴フラグ、実際にキャプチャした証拠の redaction です。- ジョブは
demos/web/scenarios/network.yamlを network を有効にして 実行し、続いて、永続化されたnetwork.jsonがキャプチャした秘密情報をマスクしていることをアサートします。 - このジョブはまずシグナルとして着地させましたが、CI で安定を確認できたので、現在は必須の
E2E (web)ゲートに組み込んでいます。 - iOS 側は、上記「iPhone 17 Pro と近年の iOS の Simulator で検証済みの範囲」で述べた
network (xcuitest)ジョブです。これで 3 つの backend すべてが、自分が実装しているネットワークの実行経路を動かすようになりました。 - Android は現在、アプリ側のネットワークキャプチャ(BE-0283)に対応しています。BajutsuAndroid の OkHttp インターセプタが、各リクエストを
adb reverseトンネル経由でホストの collector へ報告します。iOS でBajutsuKitが使うのと同じ、アプリ側連携の形です。- adb ドライバ自体は、アクチュエーションの対象になるネイティブのネットワークモニタがないため、引き続きネイティブな
NETWORKcapability を宣言しません。 - そのため
network (adb)ジョブ(android-e2e.yml)は、ドライバの capability を介さず、このアプリ側の経路を直接検証します。
- adb ドライバ自体は、アクチュエーションの対象になるネイティブのネットワークモニタがないため、引き続きネイティブな
Linux の Android エミュレータで検証済みの範囲(Mac 不要)¶
- adb バックエンドの subprocess 実行を、KVM 上で起動した x86_64 API 34 AVD に対して確認しています(
android-e2e.yml、BE-0208)。確認した項目は、次のとおりです。 uiautomator dumpパース。- resident server の
POST /actによる identity 指定の tap と、その frame 中心座標へのフォールバック(BE-0339)。 AndroidEnvironmentの起動シーケンス。- on-device の actuation fidelity。
pinch/rotateのマルチタッチとデバイス制御のスライス。- このレーンは、iOS が走らせるのと同じ共有シナリオを、Compose と Views 両方の showcase ビルドで駆動します。Compose カタログの golden 要素ツリー検査とピクセル単位のビジュアルリグレッション baseline も併せて確認しています。
- このレーンは、常駐 UI Automator サーバ(BE-0245)もビルドします。
- そのため、これらの読み取りは既定で常駐チャネルを通ります。常駐チャネルは
adb forward越しのGET /sourceで、1 回約 2.4 秒のuiautomator dump起動を置き換えます。 uiautomator dump経路は、ダンプへフォールバックさせた golden の実行で守ります。
Linux の実 Postgres で検証済みの範囲(Mac 不要)¶
serve db (postgres)ジョブ(serve-db.yml、BE-0309)は、次の項目を一時的なpostgres:16サービスコンテナに対して実行します。- serve の DB 層の Alembic migration。migration 0010 の
dialect.name == "postgresql"による foreign-key 分岐や、models.pyといくつかの migration が Postgres でのみ選ぶJSONBカラムのバリアントを含みます。 tests/serve/全体の、DB に触れる広いテストスイート(models・repository・OAuth の永続化など)。共有のserve_engineフィクスチャにオプトインするファイルが対象です。- これらのテストはすべて、共有の
serve_engineフィクスチャ(tests/conftest.py)を通じて、両方の方言でパラメータ化されています。高速なcheckゲートは SQLite を、このレーンはpostgresマーカーの裏で Postgres を検証します(pytest tests/serve -m postgres -n0)。 - このレーンは、migration 0010 の方言固有のコードと、その上位の ORM/repository 層に、ホスト型の運用環境が実際に対象とする方言での初めてのカバレッジを与えます。
- BE-0282 の前例に従い、まずシグナルとして着地させ、その後必須チェックに昇格しました。コードの変更ではなく、リポジトリのルールセット設定によるものです。Postgres での回帰は、
checkやE2E (…)の集約ジョブと同じようにマージをブロックするようになりました。
未配線(スキーマ/フラグはあるが実行時に効かない)¶
| 機能 | 現状 | 場所 |
|---|---|---|
services.mockServer(外部モックコマンド) |
config スキーマのみです。cmd/port の外部サーバは未実装で、シナリオ mocks(宣言的なプロトコル内スタブ、実装済み)で代替します。 |
common/config/schema/mock_server.py MockServer |
web バックエンドでの appTrace 区間証跡 |
appTrace はアプリ自身のログを流します(iOS は os_log、Android はタグで絞った logcat、BE-0478)。Playwright バックエンドは代わりに video と deviceLog 相当(console / page-error)の区間証跡を実装しています(BE-0054)が、appTrace に相当するものは持ちません。 |
evidence/intervals · common/drivers/playwright |
SwiftUI と Jetpack Compose の画面での nativeZ |
報告経路は両方とも実装済みですが(BE-0355)、宣言的な UI ツールキットはどちらも自身でアクセシビリティ要素を生成し、位置の測定元となる実体を外に出しません。SwiftUI は支援技術がプロセスに接続したときに初めて要素を実体化するため、アプリ自身のビューツリーに識別子が現れません。Compose はアプリが宣言した追加データキーを自身のノード生成に通しません。opt-in したアプリの UIKit と Android の View による画面は値を報告し、SwiftUI と Compose の画面は null になります。診断専用のフィールドで、セレクタも重なり判定もこれを読みません。 |
BajutsuKit/Sources/BajutsuKit/BajutsuZOrder.swift・BajutsuAndroid/…/BajutsuZOrder.kt |
これらはいずれも各機能ページで該当箇所に注記しています。