コンテンツにスキップ

English · 日本語

設定、ターゲットのオンボーディング、doctor

ツール本体はアプリ非依存です。アプリ固有の差分はすべて config に置くので、同じバイナリと同じドライバで複数のターゲットを実行できます。ターゲットを追加するときは targets.<name> を 1 つ加えるだけです。

実装: bajutsu/common/config/resolve.py(解決) · bajutsu/common/doctor.py(規約充足度スコア)。config はリポジトリのルートには同梱されていません。--config(既定のファイル名は bajutsu.config.yaml)で渡します。デモにはすぐ動くものが同梱されています(例: demos/showcase/showcase.config.yaml(iOS)、demos/web/demo.config.yaml(web))。

関連: concepts のアプリ非依存 · drivers · scenarios


設定の階層(defaults × targets)

bajutsu.config.yaml は 3 層で構成されています。値の解決順は 既定 < テンプレート < ターゲット < シナリオ で、テストに近い方が優先されます。テンプレートは省略でき、ターゲットが名前を挙げたときだけ間に入ります(後述)。

ターゲットが受け付けるキーは 9 個です。各キーは 1 つの目的の設定をまとめます(BE-0452)。platform はすべてのターゲットで必須です。ローダは 9 個以外のキーをエラーにし、ターゲットが受け付けるキーを列挙します。以前のリリースの平坦なキー(bundleId や appPath など)は読まずに拒否します。

run グループは BE-0473 で廃止されました。ターゲット、defaults、defaults.platforms.<platform> のいずれにも書けません。各フィールドは、同じ問いにすでに答えているグループへ移りました。まだ run と書いた config は読み込みに失敗し、エラーメッセージが含まれる各フィールドの移行先を示します。

旧キー 移行先
run.erase: true subject.reinstall: erase
run.network、run.visualCompare、run.secrets evidence.collectNetwork、evidence.visualCompare、evidence.secrets
run.systemAlertHandling hooks.interrupts に、ルールごとに choice を付けた - systemAlert: <prompt> のエントリを 1 つずつ書きます(後述)
run.tipKitHandling: true hooks.interrupts の - tipKit: dismiss
run.ignoredSettings runsOn.ignoredSettings(後述)

subject グループは、BE-0470 までは app という名前でした。ターゲット、テンプレート、defaults.platforms.<platform> のどこかにまだ app と書いた config は、読み込みに失敗し、エラーメッセージが移行先の subject を示します。グループの中のフィールド名は変わらないので、キーの名前を書き換えるだけで移行できます。

キー 目的 形が platform で変わるか
platform ターゲットを駆動する backend。ios、android、web、fake のいずれかです —
subject テスト対象(アプリまたはサイト)。識別子、ビルドと起動の方法、準備完了の判定、id の規約を持ちます 変わります
runsOn ターゲットを動かす場所。宛先ごとのブロックに、デバイスの条件とデバイスの状態を持ちます 変わります
driver Bajutsu がターゲットを駆動する方法 変わります
services run が依存するサービス。run が起動するものと、run が接続するものの両方を含みます 変わりません
hooks すべてのシナリオを包むステップと、途中で現れたときに run が自動で片付けるもの 変わりません
evidence run が残すもの、その比較方法、マスクするもの 変わりません
paths ファイルの置き場所 変わりません
ai AI 経路を担うプロバイダ 変わりません

bajutsu config schema は、このファイルの JavaScript Object Notation(JSON)Schema を出力します(cli)。スキーマの各ターゲットは、platform をキーにした oneOf です。そのため、エディタはターゲットが指定したプラットフォームのキーを補完できます。

defaults:                         # 全ターゲット共通の既定
  evidence:
    capture: [screenshot.after, elements, actionLog]
    redact:  { headers: [Authorization, Cookie], fields: [token, password] }
    secrets: [LOGIN_PASSWORD]     # ${secrets.X} に使える環境変数名(実値は証跡でマスク)
  ai:      { provider: api-key, keyEnv: ANTHROPIC_API_KEY }   # AI 経路のプロバイダ / モデル / エンドポイント / キー(下記)
  platforms:                      # プラットフォームで形の変わるグループを、プラットフォームごとに置く
    ios:
      runsOn: { ios: { locale: en_US } }
reservedNamespaces: [auth, nav]   # チーム共通: 共有フロー / コンポーネントの id 契約(情報用)

targets:
  showcase-swiftui:               # ← --target showcase-swiftui で選択
    platform: ios
    subject:
      id: com.bajutsu.showcase.ios.swiftui
      path: ios/swiftui/build/Showcase.app     # 存在すれば各シナリオの前にインストール
      build: make swiftui-build                # path を必要なときにビルドするコマンド
      launch: { env: { SHOWCASE_UITEST: "1" } }
      startWhen: { exists: { id: [stable.row.1, stable_row_1] } }
      idNamespaces: [stable, horse, search, log, notice, perm, sys, net]
    driver:
      runner: { testRunner: ../../BajutsuKit/Runner/build/dd/Build/Products/BajutsuRunner.xctestrun }
    hooks:
      interrupts:
        - systemAlert: notifications           # 通知のプロンプトに答える。--no-system-alert-handling でガードごとオフ
          choice: grant
        - tipKit: dismiss                      # iOS 専用: 操作をブロックする TipKit の tip を閉じる(ビルトイン既定はオフ)
    paths: { scenarios: scenarios }            # このターゲットのシナリオディレクトリ(run が読み、record が書く)

  web:                            # web ターゲット(Playwright backend)は URL で指定する
    platform: web
    subject: { url: "http://127.0.0.1:8787/index.html" }
    runsOn:
      browser:
        kind: chromium                         # chromium / chrome / edge / firefox / webkit。--browser が実行ごとに上書き
        emulate: iPhone 13                     # 省略するとデスクトップのコンテキスト。それ以外は Playwright のデバイスプリセット
    driver: { headless: true }                 # false でブラウザを画面に表示。--headed が実行ごとに上書き
    services:
      server: { cmd: "python -m http.server 8787", readyUrl: "http://127.0.0.1:8787/" }
    paths: { scenarios: demos/web/scenarios }

4 つのグループは、形がプラットフォームで変わります。各プラットフォームがこれらのグループのモデルを登録するので、別のプラットフォームが受け付けるキーは未知のキーとしてエラーになり、エラーは受け付けるフィールドを列挙します。

グループ iOS Android Web
subject id、path、build、reinstall、launch.env、launch.args、launch.deeplink、startWhen、idNamespaces id、path、build、reinstall、launch.env、launch.deeplink、grantPermissions、startWhen、idNamespaces url、launch.env、startWhen、idNamespaces
runsOn ios.model、ios.os、ios.kind、ios.family、ios.locale、ios.seedPhotos android.avd、android.apiLevel、android.locale、android.seedPhotos browser.kind、browser.version、browser.emulate
driver runner.testRunner、runner.build、runner.hostAddress nativeZ、residentRecovery.readRetries、residentRecovery.restart headless

runsOn は、どのプラットフォームでも ignoredSettings も受け付けます。このキーは宛先を表しません。ターゲットの環境が適用できない設定を列挙します(後述)。

テスト専用の fake プラットフォームは、任意の subject.id、subject.startWhen、subject.idNamespaces だけを受け付け、runsOn と driver にはフィールドを持ちません。fake のターゲットは iOS の形の sub-config に解決します。

どのプラットフォームでも同じフィールドを持つグループは次のとおりです。

グループ フィールド
services server(run のためにアプリ自身のホストを起動します。後述)、mockServer、mailbox(run がポーリングするだけで起動はしない外部の受信箱です。後述)
hooks setup、cleanup、interrupts(画面、システムアラート、TipKit。後述)
evidence capture、redact、collectNetwork、visualCompare、secrets
paths scenarios、baselines、schemas、goldens

デフォルト値(defaults)

defaults は、共通のグループを直下に持ちます。プラットフォームで形の変わるグループは defaults.platforms.<platform> の下に置き、そのプラットフォームのターゲットだけに効きます。そのため、1 つのファイルで複数のプラットフォームのデフォルト値を扱えます。ローダはターゲットを検証する前に defaults をマージします。subject.id のようにプラットフォームが必須とするフィールドも、デフォルト値から与えられます。マージは次の 5 つの規則に従います。

  • 辞書はキーごとにマージし、ターゲットの値が勝ちます。
  • ターゲットは null を書いて、継承した値を消せます。
  • リストは継承した値を置き換えます。ただし evidence.secrets と evidence.redact の各リストは和集合を取ります。置き換えにすると、シークレットを 1 つ足したターゲットが、チーム共通のシークレットをすべてマスクしなくなるためです。hooks.interrupts は 1 つのリストに 3 つの形式が入るので、形式ごとにマージします。画面のエントリは、ターゲットが 1 つでも書けば継承したものを置き換えます。systemAlert のエントリは、同じプロンプトの継承したエントリを置き換えます。tipKit のエントリは、継承したものを置き換えます。そのため、画面のハンドラを 1 つ足したターゲットでも、defaults が答えるプロンプトはそのまま残ります。空の hooks.interrupts: [] を書けば、継承したエントリをすべて消せます。
  • ターゲットは、和集合を取るこれらのリストにも、evidence と evidence.redact にも null を書けません。読み込みはそのパスを示して失敗するので、ターゲットがチームのマスクを消すことはありません。
  • ai は、後述のとおりフィールドごとにマージします。

reservedNamespaces と doctor はターゲットごとの設定ではなくチーム共通の設定なので、ファイルのトップレベルに置きます。notify もトップレベルに置きます。ターゲットは自分の notify を持たないので、結果の送り先はトップレベルのリストだけが決めます(後述)。

ターゲット間でブロックを共有する(x- キー)

defaults は、全ターゲット、または 1 つのプラットフォームの全ターゲットが共有する値を扱います。1 つのアプリの派生ターゲット同士は、subject ブロックの大半のように、それ以上を共有することがよくあります。この場合は YAML のアンカーを使います。ローダは名前が x- で始まるトップレベルのキーを無視するので、そのキーにアンカーを置けます。ターゲットは YAML の << キーでアンカーをマージします。

x-swiftui-app: &swiftui-app
  launch: { env: { SHOWCASE_UITEST: "1" } }
  idNamespaces: [stable, horse, search, log, notice, perm, sys, net]

targets:
  showcase-swiftui-noax:
    platform: ios
    subject:
      <<: *swiftui-app
      id: com.bajutsu.showcase.ios.swiftui.noax
      idNamespaces: []                  # ここに書いたキーがアンカーの値に勝つ

<< キーのマージは 1 階層だけです。ターゲットに launch のような入れ子のブロックを書くと、アンカーの launch ブロックにマージされず、丸ごと置き換わります。そのため、アンカーはターゲット全体ではなく、違いのあるブロック(この例では subject)の階層に置きます。x- という接頭辞は、Docker Compose ファイルの拡張フィールドの慣例にならったものです。それ以外の未知のトップレベルキーは、これまでどおり読み込みに失敗します。

テンプレート(templates:、BE-0471)

テンプレートは、名前の付いた部分的なターゲットブロックです。ターゲットは extends でテンプレートを取り込み、複数のターゲットに共通する設定を 1 か所にまとめられます。defaults はすべてのターゲットに、defaults.platforms.<platform> はあるプラットフォームのすべてのターゲットに効きます。テンプレートは、この 2 つの層と個々のターゲットのあいだを埋めます。たとえば、1 つのアプリを別々の方法でビルドするターゲットに共通する設定です。

templates:
  showcase-ios:                    # ターゲットのどのキーも書け、必須のキーはない
    platform: ios
    subject:
      launch: { env: { SHOWCASE_UITEST: "1" } }
  masked-password:
    evidence: { redact: { fields: [password] } }

targets:
  showcase-swiftui:
    extends: [showcase-ios, masked-password]     # 後ろの要素が前の要素に勝つ
    subject: { id: com.bajutsu.showcase.ios.swiftui }
  showcase-uikit:
    extends: ./templates/uikit.template.yaml     # 別ファイルに置いたテンプレート
    subject: { id: com.bajutsu.showcase.ios.uikit }

テンプレートはトップレベルの専用キー templates: の下に置き、targets: の下には置きません。そのため --target もサーバーのどのエンドポイントも、テンプレートの名前を受け付けません。--target と多くのエンドポイントは、その名前がテンプレートであることを示します。run、run_set、record、triage は、ターゲットのシナリオのディレクトリを調べる段階で先に断ります。この 4 つのエラーは target '<name>' has no scenarios dir です。CLI はターゲットの一覧も添えます。サーバーのエラーには一覧を載せません。1 つの config に複数の組織のターゲットが入りうるためです。extends はテンプレートだけを探すので、テンプレートとターゲットが同じ名前でも構いません。

層は、弱いものから強いものへ次の順に重なります。

  1. defaults
  2. defaults.platforms.<platform>
  3. extends の各要素(書いた順)
  4. ターゲット自身

テンプレートは、ほかのテンプレートを extends で取り込めます。取り込まれる側(基底)が先に重なるので、取り込む側のテンプレートが基底に勝ちます。共通の基底のように 2 つの要素から届くテンプレートは、深さ優先でたどって最初に現れた位置で 1 回だけ重なります。このため基底は、基底を取り込むどのテンプレートよりも常に弱くなります。

各層は、デフォルト値の 5 つの規則に従ってマージします。テンプレートは、defaults が与える値を null で消せます。evidence.secrets と evidence.redact の各リストは、すべての層をまたいで和集合を取ります。テンプレートの ai はまずターゲットの ai に重なり、その結果が defaults.ai とフィールドごとにマージされます。

platform はテンプレートから与えられるので、ターゲットはこのキーを省略できます。platform を書いた層は、ターゲット自身も含めてすべて一致している必要があります。ターゲットの platform で、テンプレートの platform は上書きできません。platform は subject、runsOn、driver の形を決めるため、上書きを許すと iOS 向けの形をしたテンプレートのブロックが Web のターゲットに渡ってしまいます。2 つの層の platform が食い違うと、読み込みは両方の層の名前を示して失敗します。

extends の要素は、/ を含むか、.yaml か .yml で終わるならファイルを指します。それ以外の要素は templates: の下のテンプレート名です。名前とパスの見分け方は、コンポーネントを呼ぶ use ステップと同じです(シナリオ)。テンプレートファイルには 1 つのテンプレートブロックを書き、その規則はコンポーネントファイルにならいます。

  • パスは、その extends を書いたファイルのディレクトリを基準に解決します。
  • ファイルはスイートのルートの内側になければなりません。
  • ファイル内の相対的な値は、そのファイル自身のディレクトリを基準に解決します。対象は、入れ子の extends の要素、パスのフィールド、hooks が use で呼ぶコンポーネントです。パスのフィールドは subject.path、runsOn.ios.seedPhotos、driver.runner.testRunner、paths.* です。
  • ビルドのコマンド(subject.build、driver.runner.build)は書き換えません。ターゲット自身のコマンドと同じく、config ファイルのディレクトリで実行します。ビルドのコマンドと、それが作るパスは同じ場所に書いてください。分けると、ビルドの出力先とパスの指す先が食い違います。
  • テンプレートファイルは自前の templates: を持たないので、ファイルの extends にはファイルだけを書けます。

ファイルを持たない文書から読み込んだ設定では、同じ設定の中に書いたテンプレートだけを名前で指せます。

読み込みは、未知のテンプレート名で失敗し、既知の名前を一覧で示します。循環でも失敗し、循環の経路(a → b → a)を表示します。ターゲットの 11 個のキーと extends 以外のキーも、どのターゲットも取り込まないテンプレートを含めて失敗します。ローダは、テンプレートの入れ子のフィールドを、そのテンプレートを取り込むターゲットを通じて検証します。どのターゲットも取り込まないテンプレートは、入れ子のフィールドが未検証のまま残ります。bajutsu config schema は、エディタ向けにこの隙間を狭めます。platform を書いたテンプレートは、そのプラットフォームの部分的なターゲットとして表されます。platform を省いたテンプレートには、どのプラットフォームの部分形も当てはまります。

デバイスの条件(runsOn)

ターゲットの runsOn は、そのターゲットを動かす場所を表します。フィールドは、宛先の名前を付けた 1 つのブロックに置きます。宛先は runsOn.ios、runsOn.android、runsOn.browser のいずれかです(BE-0469)。そのため、各フィールドが何を制限するのかがパスから読み取れます。たとえば runsOn.ios.os は iOS のバージョンを表します。

プラットフォーム 宛先のブロック フィールド
iOS runsOn.ios model、os、kind、family、locale、seedPhotos
Android runsOn.android avd、apiLevel、locale、seedPhotos
Web runsOn.browser kind、version、emulate
fake なし なし

platform と runsOn は別のことを表します。platform はテスト対象のアプリの種類を表し、subject と driver の形を決めます。runsOn は、そのアプリを動かす場所を制限します。そこでローダは、2 つの名前が一致するかではなく、組み合わせが上の表で許されているかを検査します。たとえば runsOn.browser を書いた platform: ios のターゲットは失敗し、iOS が許す宛先を示します。fake のターゲットには宛先がないので、runsOn の下にキーを書くと失敗します。チームの既定値も、同じブロックを defaults.platforms.<platform>.runsOn の下に書きます。

targets:
  app-sim:                     # Simulator
    platform: ios
    subject: { id: com.example.app }
    runsOn:
      ios: { model: "iPhone 16", os: "18" }

  app-device:                  # --udid で指定した実機
    platform: ios
    subject: { id: com.example.app }
    runsOn:
      ios: { kind: device }

  site:                        # ブラウザ
    platform: web
    subject: { url: https://example.com }
    runsOn:
      browser: { kind: firefox, emulate: "iPhone 15" }

以前のリリースでは、これらのフィールドを runsOn の直下に書いていました。ローダは直下の書き方を読みません。直下に書いたキーは読み込みに失敗し、移動先のパスを示します。

以前のキー 新しいキー
runsOn.model、os、kind、locale、seedPhotos runsOn.ios.<同じフィールド>
runsOn.avd、apiLevel runsOn.android.<同じフィールド>
runsOn.emulate runsOn.browser.emulate

runsOn.browser.engine は runsOn.browser.kind に置き換わりました(BE-0468)。engine を書くと読み込みが失敗し、メッセージが kind を示します。フィールド名を書き換えても run は減りません。kind のリストは、engine のリストと同じく、並べたブラウザごとに 1 回ずつ実行します。

runsOn のいくつかのフィールドは、デバイスの条件です。

プラットフォーム 条件
iOS ios.model、ios.os、ios.family と、ios.kind に書いたリスト
Android android.avd、android.apiLevel
Web browser.version と、browser.kind に書いたリスト

model と avd に書いたリストも条件になります。バージョンの範囲は npm の node-semver の範囲の文法で書きます(">=17 <19" など)。形が誤った範囲は、ローダが拒否します。YAML は 18.10 を 18.1 として読むので、小数のバージョンは引用符で囲みます。

Bajutsu は、run の前に利用できる各デバイスを読み、これらの条件と照合します(BE-0452)。何を読むかはプラットフォームで決まります。

条件 読み取り元 比較
iOS の model udid の simctl のデバイスタイプ名 完全一致
iOS の os Simulator のランタイムのバージョン バージョンの範囲
iOS の family Simulator ならデバイスタイプの productFamily、実機なら devicectl が返す deviceType iphone か ipad。run のデバイスが持つ、並べた順で最初のファミリーを選びます
Android の avd エミュレータの Android Virtual Device(AVD)名。ro.boot.qemu.avd_name、ro.kernel.qemu.avd_name、adb emu avd name の順に読みます 完全一致。物理デバイスは一致しません
Android の apiLevel ro.build.version.sdk 整数に対するバージョンの範囲
Web の browser.version Playwright が起動するブラウザのバージョン バージョンの範囲

プールは --udid に並べたすべての udid です。AVD 名を返さないエミュレータは run を失敗させます。そのため、avd の条件がメッセージなしにデバイスを取り逃すことはありません。

run は、1 つのシナリオを 1 組の座標で実行する単位です。run を増やす条件は 2 種類あります。

フィールド run の数 合うデバイスがないとき
kind、model、avd、browser.kind に書いたリスト 値ごとに 1 つ その run は値を示して失敗します
両側が閉じた範囲(">=17 <19"、"18"、"33 - 35" など) 範囲が含むメジャーバージョンごとに 1 つ その run はメジャーバージョンを示して失敗します
片側が開いた範囲(">=18" など) 範囲内で利用できるデバイスが持つメジャーバージョンごとに 1 つ 対象外(not applicable)の記録を 1 件残します
単一の model や avd run は増えません その run は失敗します
family(単一の値でもリストでも) run は増えません その run はファミリーを示して失敗します

Android では API レベル 1 つを 1 つのメジャーバージョンと数えます。browser.version の範囲は run を増やさず、起動したブラウザを絞り込みます。対象外の記録は、それ自体では判定を持ちません。どの出力も、対象外の記録を成功や失敗とは別に並べます(reporting)。

  • コンソールとマニフェスト
  • HTML レポートの run のマトリックス
  • JUnit と Common Test Report Format(CTRF)のスキップしたテスト
  • Webhook のペイロード

すべての記録が対象外になった呼び出しは、終了コード 1 で終わり、no run executed を出します。複数のターゲットを持つシナリオは、各ターゲットの run のすべての組み合わせを実行します。

たとえば、次のターゲットは 2 つのモデルと両側が閉じた範囲を書いています。このターゲットの各シナリオは、4 つの run を作ります。各モデルについて、iOS 17 と iOS 18 で 1 つずつです。

targets:
  app:
    platform: ios
    subject: { id: com.example.app }
    runsOn:
      ios:
        model: ["iPhone SE (3rd generation)", "iPad Pro 13-inch (M4)"]
        os: ">=17 <19"

シナリオは自分では条件を宣言しません。iPad を必要とするシナリオは、targets: [app-ipad] のように iPad で動くターゲットを指定します(シナリオ)。そのため、ターゲットに書いた範囲は、そのターゲットのすべてのシナリオの run を増やします。iOS 17 と iOS 18 を持つプールでは、os: ">=17" はすべてのシナリオを 2 回ずつ実行します。シナリオごとに run を 1 つにしたいターゲットは、os: "18" のようにメジャーバージョンを 1 つだけ指定するか、os を省きます。

各 run は、自分の適格な集合からデバイスを取ります。適格な集合には、run の条件を満たすデバイスが残ります。run がモデルを固定しないときは、1 つのリリースで必要な台数がそろう最初のモデルをプールの順に選びます。そのモデルの中では、台数がそろういちばん新しいリリースを選びます。集合のデバイスはどれも同じモデルとリリースを持つので、--workers は同一のデバイスに run を振り分けます。

ターゲットは、モデルの代わりにデバイスのファミリーを指定できます。Apple は Xcode のリリースごとにデバイスタイプの名前を変えます。そのため、model に書いた正確な名前は、そのデバイスタイプを持たない Xcode のホストで一致しなくなります。family には iphone、ipad、または両方を並べた優先順位のリストを書きます。リストを書いても run は増えません。各 run は、自分のデバイスが持つファミリーのうち、並べた順で最初のものを選びます。勝つファミリーを決めるのはリストの順序だけなので、同じプールはいつも同じ結果になります。適格な集合は、勝ったファミリーのデバイスに絞られます。勝ったファミリーの台数が run に足りないときは、次のファミリーに移らず、その run は失敗します。

2 つ以上のファミリーを並べると、勝ったファミリーが run の座標に加わります(family=ipad)。run のラベル、manifest、フレーキーさの履歴は、これによってファミリーごとの run を区別します。family と model はどちらも run が取るデバイスを指すので、両方を宣言すると読み込みが失敗します。

kind にリストを書くと、各シナリオを並べた種類ごとに 1 回ずつ実行します。kind: [simulator, device] は、Simulator と実機でそれぞれ 1 回実行します。各 run は自分の種類を座標に加え(kind=device)、その種類の XCUITest の接続先を使います。このとき、プールは両方の種類のデバイスを含む必要があります。Bajutsu は、--udid の各 udid を、その udid を表示する一覧から読みます。

  • Simulator は simctl から読みます
  • 実機は devicectl から読みます

どちらの一覧にも表示されない udid は、読み取りを失敗させます。並べた種類のデバイスがプールにないとき、その run は種類を示して失敗します。run が黙って飛ばされることはありません。

targets:
  app:
    platform: ios
    subject: { id: com.example.app }
    runsOn:
      ios:
        kind: [simulator, device]   # それぞれで 1 回ずつ実行
        family: [ipad, iphone]      # 各 run は、プールに iPad があれば iPad を取る

record、crawl、repl は run を増やしません。最初に並べた値と、合うデバイスが持つ最初のファミリーを使います。メジャーバージョンは、範囲内でプールが持ついちばん新しいものを使います。合うデバイスがなければ終了コード 2 で終わります。doctor はターゲット自身の run を一覧にし、--scenario でファイルを指定したときは各シナリオの run を一覧にします。どちらも、それぞれに合うデバイスを添えます(doctor の出力)。画面のプローブは、最初の run のデバイスを採点します。--backend fake はどの条件も照合せず、そのことを 1 回だけ知らせます。runsOn.ios.kind に device を含むターゲットは、model と os を宣言できません。Bajutsu は実機のモデルとリリースを照合しないからです。実機もファミリーは返すので、family は宣言できます。appium のグリッドが受け持つターゲットや Device Farm のジョブには、読み取るプールがありません。そこに書いた条件は、デバイスを操作する前に失敗し、フィールドを示します。

runsOn.ios の 3 つのフィールドは、条件ではなくデバイスの状態です。単一の kind(simulator か device)は XCUITest の接続先を選びます。locale は run が適用する言語を固定します。locale が未指定なら、iOS はビルトインの en_US を使います。seedPhotos は写真ライブラリに投入する画像を並べます。シナリオは preconditions.device.ios の下で locale と seedPhotos を置き換えられます。Android の runsOn.android.locale と runsOn.android.seedPhotos も、同じくデバイスの状態です。シナリオは preconditions.device.android の下でどちらも置き換えられます。web のブロックの emulate も、デバイスを照合するのではなく、デバイスモードを選びます。

Android アプリの言語

runsOn.android.locale は、テスト対象アプリの言語を設定します(BE-0478)。書き方は runsOn.ios.locale と同じで、ja_JP のように書きます。run はこの値を Best Current Practice 47(BCP 47)の言語タグ(ja-JP)に変換します。起動のたびに、run は cmd locale set-app-locales でタグを設定し、読み戻します。読み戻した値が違えば起動は失敗し、パッケージ名と言語を示します。

targets:
  shop-android:
    platform: android
    subject: { id: com.example.shop }
    runsOn:
      android: { apiLevel: ">=33", locale: ja_JP }

アプリごとの言語設定は、iOS の locale と3つの点で違います。

  • 未指定ならデバイスの言語のままです。 iOS はビルトインの en_US を使いますが、Android は何も設定しません。再利用するエミュレーターには、以前の run が残したアプリごとの言語設定が残っている場合があります。API レベル 33 以降では run がその設定を消すので、アプリはデバイス自身の言語に従います。
  • API レベル 33 が必要です。 cmd locale は API レベル 33 から使えます。次の2段階で確かめます。
  • runsOn.android.apiLevel が 33 より前のレベルを許すなら、デバイスを操作する前に run が失敗します。メッセージは apiLevel を狭めるよう促します。
  • apiLevel が未指定なら、run は起動時にデバイスのレベルを読み、そこで失敗します。

言語を指定しない run は、レベルを読めなくても警告を記録するだけです。 - システムダイアログはエミュレーターの言語です。 言語設定が届くのはアプリだけです。実行時の権限ダイアログは、エミュレーターのイメージの言語で表示されます。iOS は Simulator のシステム言語も固定する点が異なります。システムダイアログのボタンは、文言がイメージに従うので id セレクタで指定します。

解決(resolve → Effective)

resolve(config, target) が 1 ターゲット分の有効値 Effective(frozen dataclass)を構築します。ターゲットが未定義の場合は KeyError となり、CLI は終了コード 2 で終了します。下記の一部のフィールド(各プラットフォーム自身の識別子、および web 限定の headless / browser / device_mode)は Effective の平坦なフィールドではありません。Effective.platform_config が、ターゲットの platform に応じて、互いに排他的なプラットフォームごとの 3 つの config(IosConfig / WebConfig / AndroidConfig)のいずれかに絞り込みます(BE-0126)。読み取るときは bajutsu/common/config/accessors.py の絞り込み用ヘルパーを使います。1 つのプラットフォームに決まっているコードは require_ios / require_web / require_android を使い、プラットフォームをまたいで値を安全に読みたいコードは「soft」な ios_bundle_id / web_base_url / web_engine / android_package を使います。Effective に bundle_id のようなフィールドは存在しません。

Effective フィールド 由来 備考
platform platform ターゲットのプラットフォーム(ios/android/web)です。fake のターゲットは iOS の形の sub-config に解決するので、ios として読めます
backend platform ターゲットのプラットフォームを 1 要素のリストにしたもので、actuator はここから選びます(drivers)。--backend で置き換えられるのは、同じプラットフォーム、その actuator、fake のいずれかに限ります
platform_config.bundle_id(IosConfig) subject.id iOS のターゲット識別子です
platform_config.base_url(WebConfig) subject.url web のターゲット URL(Playwright backend)です
platform_config.package(AndroidConfig) subject.id Android のターゲット識別子です
platform_config.app_path / .build(IosConfig、AndroidConfig) subject.path / subject.build run が各シナリオの前に(未インストールなら)インストールするビルド済みアプリと、それを必要なときにビルドするシェルコマンドです
platform_config.xcuitest(IosConfig) driver.runner と runsOn.ios.kind XCUITest の runner です。testRunner(ビルド済みの .xctestrun)、build(それをビルドするコマンド)、hostAddress(後述)、接続先の kind を持ちます
platform_config.grant_permissions(AndroidConfig) subject.grantPermissions Android のみ: 起動前に付与する実行時の権限です(pm grant)。権限のプロンプトがシナリオを止めないようにします
platform_config.native_z(AndroidConfig) driver.nativeZ Android のみ: nativeZ: true は、opt-in した各ビュー自身の View.getZ() を端末に要求します。elements.json は診断用フィールド nativeZ として報告します(BE-0355)。指定しなければ off です。値を返すノード走査は画面の読み取りごとに走り、20 ミリ秒から 100 ミリ秒かかるうえ、テスト対象のアプリが BajutsuAndroid をリンクしてビューを opt-in していなければ何も報告しないためです。on にしたターゲットは、確認が取れたジェスチャの応答が省いてくれるはずだった往復も手放します。その応答は nativeZ の値を運べないため、位置がすべて未計測になるツリーを受け取る代わりに、そもそも作らないよう端末へ要求します(BE-0407 の作業単位 18〜19)。iOS に対応するフラグはありません。レスポンダは BajutsuKit をリンクしたアプリにだけ応答するためです
platform_config.resident_read_retries、platform_config.resident_restart(AndroidConfig) driver.residentRecovery.readRetries、driver.residentRecovery.restart Android のみ: 常駐 UI Automator サーバーからの読み取りが時間切れになったとき、リースが uiautomator dump に切り替える前に試すことを決めます。readRetries(0 から 5、既定は 1)は、新しい接続で読み直す回数です。restart(既定は true)は、そのあとにサーバーを再起動するかどうかを決めます。チャネルを失ったあとの非 ASCII の type ステップがサーバーを立ち上げ直せるかどうかも、この設定で決まります。接続の拒否や切断ではどちらも行いません。サーバーが応答できないことを示しているためです
platform_config.headless(WebConfig) driver.headless web のみ: true(既定)はヘッドレス、false はブラウザを画面に表示し低速再生します。bajutsu run --headed / --no-headed と Web UI の「show browser」トグルが実行ごとに上書きします
platform_config.browser(WebConfig) runsOn.browser.kind web のみ: 駆動するブラウザです。chromium(既定)、chrome、edge、firefox、webkit から選びます。chrome と edge は、ホストにインストールされた Google Chrome と Microsoft Edge を、Playwright の chromium エンジンのチャネルとして起動します。webkit は、Playwright が駆動できない Safari の代わりです。bajutsu run/record --browser <kind> が実行ごとに上書きし(フラグ > config > 既定)、bajutsu run --browsers <list> はクロスブラウザマトリクスを実行します(後述)。Playwright のエンジンが無ければ実行時に取得します。Chrome や Edge が無いときは、その run が失敗します。取得するとホスト自身のブラウザが変わってしまうからです。未知の値は config 読み込み時に拒否されます(BE-0468)
platform_config.device_mode(WebConfig) runsOn.browser.emulate web のみ: ブラウザコンテキストを生成するときのデバイスモードです。省略するとデスクトップのコンテキストになり、Playwright のデバイスプリセット名(例 iPhone 13)を指定すると、viewport / device_scale_factor / is_mobile / has_touch / user_agent をエミュレートし、web ターゲットをそのモバイル端末として駆動します。これはデスクトップ級ブラウザでのエミュレーション(Chrome DevTools のデバイスツールバー)であり、実機ではありません(drivers → Playwright)。ドライバーの中で playwright.devices に対して遅延して解決するため、config 読み込みが Playwright を import することはありません。不明なプリセットは config 読み込み時ではなくドライバー起動時に明示的なエラーで失敗します(BE-0228)
conditions runsOn ターゲットが宣言するデバイスの条件です(前述)。範囲は書いたままの文字列で持ちます。run はここから run を作り、doctor はその run を一覧にします
device_provider --worker-config このターゲットのデバイスの取得元です。config はこれを指定しなくなりました。コマンドが従う worker.yaml の appium environment が、グリッドのエンドポイントを、グリッドのプラットフォームのターゲットに渡します(マシンが実行できるもの)。ほかのターゲットはビルトインの local provider(--udid の経路)を使います。このエンドポイントは live の W3C WebDriver トランスポートで端から端まで駆動します(iOS デバイスクラウド、BE-0236、BE-0238)
launch_server services.server 任意の {cmd, readyUrl, readyTimeout, cwd, env} です。run のためにアプリのホストを起動し、終わったら停止します。readyUrl(既定は subject.url)をプローブし、すでに応答すれば再利用、しなければ cmd を起動して準備が整うまで待ちます(固定 sleep ではなく条件待ち)。subject.build の web 版です(BE-0059)。serve 上のアップロードされたバンドルでは、ホストが cmd を直接実行することはなく、serve --upload-exec が統制します(セルフホスティングを参照)。sandbox での実行には、追加フィールドとして dockerImage(Docker イメージ参照。例 node:20-slim)か dockerfile(バンドル相対のパスで、docker build でビルドします)のどちらか一方、加えて port(コンテナ内の待ち受けポート。ループバックのホストポートへ publish します)が必要です(BE-0090)
run_defaults.system_alerts / .ios_tip_kit_handling hooks.interrupts の systemAlert と tipKit のエントリ システムアラートガードと TipKit ガードに、アプリ単位の既定値を与えます。シナリオ自身の interrupts がこの上に重なります(BE-0177、BE-0473)。systemAlert のエントリは、別のプロンプトについてエントリを書いているシナリオの中でも、自分の名指すプロンプトには答えます。答えるときは run が通知を出し、シナリオ側は同じプロンプトのエントリを書けば上書きできます。重ね方の規則は後述のとおりで、シナリオでも説明しています。tipKit: dismiss は TipKit ガードの既定値になります(iOS 専用、ビルトイン既定はオフ)。--ios-tipkit-handling/--no-ios-tipkit-handling は、すべてのシナリオについてこの値を上書きします
run_defaults.setup / .cleanup / .interrupts hooks.setup / hooks.cleanup / hooks.interrupts ターゲットのすべてのシナリオを包むステップです。setup はシナリオ自身の setup より先に、cleanup はシナリオ自身の cleanup より後に動き(規則は、シナリオの cleanup の規則と同じ on: always、success、failure を取ります)、interrupts はシナリオのものより先に確認します。hook のステップは use: { component: <file>, with: … } でコンポーネントを呼べます。ローダは config を読み込むときに、config ファイルのディレクトリを基準にコンポーネントを解決し、スイートのルートの外を指す参照を拒否します(BE-0174)。group: と setMocks は引き続き hook では使えません。シナリオは preconditions.inheritSetup: false で、宣言したすべてのターゲットの hooks.setup を飛ばせます。cleanup はその場合も動きます。hooks.interrupts の systemAlert と tipKit のエントリは前の行の 2 つのフィールドに解決するので、.interrupts は画面のエントリだけを持ちます
locale runsOn.ios.locale iOS: launch 時に適用されます(simctl の launch 引数)。ビルトイン既定は en_US です。XCUITest バックエンドでは、cold spawn のたびに Simulator 自身のシステム言語も固定します。デバイスのグローバル設定ドメインに書き込み、SpringBoard がその言語で描画するよう再起動します。そのため、プロセス外の権限プロンプトのボタンのテキストは、Simulator がたまたま持っていた言語ではなく、この locale が予測するものになります。preconditions.device.ios.locale が固定済みの値と異なるシナリオは、warm な runner を再利用せず cold respawn を強制します(BE-0320)。label の対応表(英語と日本語)にない言語では、handleSystemAlert ステップはボタンの位置で答えます。同じ言語の interrupts にある systemAlert のエントリは、デバイスを操作する前にシナリオを失敗させます(BE-0445)
launch_env / launch_args subject.launch.env / subject.launch.args シナリオの preconditions.subject.launch.env は環境変数にキーごとにマージし、.args は引数の後ろに追記します。launch.args は iOS 専用です
reinstall subject.reinstall iOS と Android: 各シナリオの前にどこまで状態を戻すかを、弱いものから順の 1 本の段階で決めます。overwrite はアプリの上に install してデータを残します。clean は uninstall してから install します。erase はデバイス全体を wipe してから install します(デバイス全体の wipe がない Android では clean と同じです)。install には subject.path が必要です。シナリオの preconditions.subject.reinstall が優先し、どちらも未設定なら組み込みの clean を使います(BE-0452)。bajutsu run --erase はすべてのシナリオを erase に引き上げ、--no-erase は erase を clean に下げます。erase は廃止した run.erase: true の後継です。run.erase を書くと、このキーを示してロード時に失敗します。subject グループを持たない defaults では defaults.platforms.<platform>.subject.reinstall: erase と書きます(BE-0473)
deeplink subject.launch.deeplink iOS と Android: 起動後にアプリが開く URL です。シナリオの preconditions.subject.launch.deeplink がこれを置き換えます
seed_photos runsOn.ios.seedPhotos / runsOn.android.seedPhotos 起動前に順に投入する画像です。これで写真ピッカーが既知の画像を表示します。パスは config ファイルを基準に解決します。シナリオの preconditions.device.<platform>.seedPhotos がリストを置き換えます。iOS は erase の経路で Simulator の写真ライブラリに投入し、selectPhotos が既知のライブラリを指せるようにします。重ね合わせたあとのリストが空でなければ、実効の subject.reinstall: erase(シナリオの値、なければターゲットの値に、--erase / --no-erase を反映したもの)が必要で、なければデバイスを操作する前に終了コード 2 で終わります。Android にはデバイス全体の wipe がないため、Bajutsu 専用のディレクトリ(/storage/emulated/0/Pictures/Bajutsu)に投入します。シナリオごとにこのディレクトリを空にし、2037-01-01 から始まる更新時刻を昇順に付けて(これで投入した画像がデバイス自身の画像より前に並びます)画像を送り、メディアスキャナに再スキャンを依頼します。そのため Android では erase が要らず、デバイス上のほかの画像にも触れません。リストが空でも、以前の投入が作ったディレクトリは空にします。メディアストアは更新時刻より EXIF の撮影日時を優先するので、この並び順が成り立つのは撮影日時を持たない画像です。スキャンは起動後に終わるので、シナリオは投入した画像が現れるのを待ってから選びます
start_when subject.startWhen 任意の startWhen: { exists: { id: … } } です。run を始める前に launch が出現を待つセレクタで、既定の「アプリが 2 要素以上を描画した」判定の代わりになります。interrupts のエントリが condition に使う形で書き、negate は付けません。最初の操作画面が常時表示のクロームの上に出るモーダルであるアプリ向けです(要素数の判定はモーダル提示前に返ってしまうことがあります)。id / idMatches はシナリオのセレクタと同様に OR 候補のリストを受け付けるので(startWhen: { exists: { id: [stable.row.1, stable_row_1] } }。BE-0221)、native な id 構文が異なる target も 1 つの startWhen で扱えます。固定 sleep ではなく条件待ちです。指定するのは、その target のすべてのシナリオが同じ画面から始まるときに限ります。シナリオごとに最初の画面が異なる場合は、各シナリオの先頭に wait ステップを置いてください。readiness の最も強いシグナルは引き続き startWhen です。iOS では、BajutsuKit の画面遷移 observer(BE-0310)を組み込んだ target が、namespace/要素数のヒューリスティックの上に、起動以降に報告された画面遷移という段を設定不要で得ます。ただし明示的な startWhen はそれより上位です。observer のシグナルが判定を担うのは、startWhen が設定されていないときだけです
id_namespaces subject.idNamespaces doctor が参照します
reserved_namespaces トップレベルの reservedNamespaces 情報用です(doctor は app の idNamespaces のみで採点します)
mock_server services.mockServer ⚠️ スキーマのみ · 未配線
evidence_dirs.scenarios paths.scenarios このターゲットのシナリオディレクトリです。run --target は配下の *.yaml を全件読み、record は新規をここへ書きます。config ファイル自身のディレクトリ基準の相対パス(subject.path や兄弟の paths.baselines / .schemas / .goldens も同様)で、bajutsu をどこから実行しても config は同じ挙動になります(BE-0242)。run --scenario / record --out で上書きします
capture evidence.capture 既定証跡です(evidence の注記)
redact evidence.redact(defaults ∪ ターゲット) マージします(下記)
run_defaults.network evidence.collectNetwork run が request アサーションのためにアプリの通信を収集するかどうかです。--network/--no-network > これ > ビルトイン既定のオンの順で解決します
visual_compare evidence.visualCompare visual アサーションが自分の compare を書かないときの比較方法です。exact か pixelmatch を取り、ビルトイン既定は exact です
secrets evidence.secrets(defaults ∪ ターゲット) ${secrets.X} を宣言する環境変数名です。実値は証跡でマスクします(evidence)
ai ai(defaults < ターゲット、フィールドごと) AI 経路のプロバイダ / モデル / エンドポイント / キー(下記)です。省略(None)なら環境だけで決まります
doctor_thresholds トップレベルの doctor.idCoverageOk / doctor.idCoverageFail doctor のグレード判定に使う id カバレッジのしきい値(下記)です。既定は 0.9 / 0.7 です

redact のマージ

defaults.evidence.redact と targets.<name>.evidence.redact は、リストごとに union されます。labels、headers、fields、unmaskHeaders のそれぞれで和集合を取ります。さらにシナリオの redact(evidence)が重なります。

シークレット(evidence.secrets)

evidence.secrets は 環境変数名のリストで(defaults.evidence と targets.<name>.evidence の両方で宣言でき、ローダがマージするときに和集合にします)、シナリオが入力に使える ${secrets.X} 変数の宣言元です。bajutsu run は実行時に、宣言された各名前を環境から解決し、その値を action に展開(${secrets.X})したうえで、証跡に現れる箇所すべてでその実値をマスクします(evidence)。シナリオ source には ${secrets.X} トークンだけが残り、実値は残りません。

システムアラートと TipKit(hooks.interrupts)

hooks.interrupts には、シナリオの途中で現れたときに run が自動で片付けるものを並べます。1 つのリストが 3 つの形のエントリを持ちます(BE-0473)。エントリの形は、そのエントリが書くキーで決まります。そのため、読み手が値の型から形を推測する必要はありません。

形 必須のキー 任意のキー 片付ける対象
画面 condition steps アプリ自身の要素ツリーに現れる差し込み画面(シナリオ)
システムアラート systemAlert、choice pollInterval、frozenScreenTimeout OS のプロンプト。システムアラートガードが答えます(シナリオ)
TipKit tipKit なし Apple の TipKit のポップオーバー。iOS のターゲットだけが対象です(シナリオ)
targets:
  showcase-swiftui:
    platform: ios
    subject: { id: com.bajutsu.showcase.ios.swiftui }
    hooks:
      interrupts:
        - condition: { exists: { id: [aerr_wait] } }   # アプリ内の画面
          steps:
            - tap: { id: [aerr_close] }
        - systemAlert: notifications                   # OS のプロンプト
          choice: grant
        - systemAlert: savePassword
          choice: deny
          frozenScreenTimeout: 20                      # このプロンプトだけに属する調整値
        - tipKit: dismiss                              # Apple の TipKit のポップオーバー

各キーが取る値は次のとおりです。

  • systemAlert はプロンプトの名前です。notifications、tracking、paste、savePassword、localNetwork のいずれかを書きます。
  • choice は grant、deny、leave のいずれかです。leave は、そのプロンプトに何も答えません。
  • pollInterval は、待機中にガードが SpringBoard を確認する間隔(秒)です。ビルトイン既定は 1 秒です。
  • frozenScreenTimeout は、ガード付きの待機が止まるまでに、固まった画面を許容する時間(秒)です。0 はこの停止をオフにし、ビルトイン既定は 10 秒です。アプリ自身の要素ツリーに出るプロンプト(現在は savePassword)にだけ書けます。それ以外のプロンプトに書くと、値を読むものがないので読み込みに失敗します。
  • tipKit は dismiss か leave です。プラットフォームが iOS でないターゲットに tipKit のエントリを書くと、読み込みに失敗します。

ローダは次の 3 つの誤りを拒否し、それぞれエラーメッセージで誤りを示します。2 つの形のキーを混ぜたエントリは失敗し、エラーは両方の形を示します。1 つのリストに同じプロンプトのエントリが 2 つある場合と、tipKit のエントリが 2 つある場合も失敗します。ターゲットに書くエントリは target を指定できず、その steps では group と setMocks を使えません。

config には、ガード全体をオンやオフにするキーがありません。bajutsu run に --no-system-alert-handling を渡さない限り、ガードは動きます。以前 systemAlertHandling: false と書いていたターゲットは、代わりに、答えないプロンプトごとに choice: leave を書きます。visionInstruction もなくなりました。run はモデルを一切読まず、record と crawl はコマンドラインの --alert-vision-instruction で指示を受け取ります。

シナリオ自身の interrupts も同じ 3 つの形を受け付け、ターゲットのエントリの上に重なります。

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

pollInterval は層ごとに決まります。シナリオ、--alert-poll-interval、ターゲットの順に見て、最初に値を持つ層が勝ちます。1 つの層の中では最小の値が勝ちます。短い間隔は、より長い間隔を求めたエントリの要求も満たすからです。固まった画面の上限はガード全体で 1 つです。その値は、プロンプトに答えるエントリのうちもっとも寛容なもの、つまり最大の値で、0(停止オフ)はどの値よりも優先します。各規則の詳しい説明はシナリオにあります。

環境ごとの設定(runsOn.ignoredSettings、BE-0467)

最初のステップより前にデバイスへ届く設定には、環境によって適用できないものもあります。iOS Simulator は simctl erase でデバイスを消去しますが、実機の iPhone や WebDriver のエンドポイントではこのコマンドを実行できません。ブラウザにはアプリの起動がないので、subject.launch.env を渡す先もありません。各設定の扱いは、環境のルート(iOS Simulator、iOS 実機、ライブ WebDriver、Android、Web)ごとに 1 つある表で決まります。

サポート 意味 実行時の動作
supported ルートがその設定を適用する 適用します
satisfied 設定が求める状態を、ルートがすでに保証している(Web の実行は毎回新しいブラウザコンテキストで始まるので、消去済みである) 何もしません
unsupported ルートがその設定を適用できない ターゲットが無視を宣言していない限り、デバイスに触る前に失敗します

対象の設定と、それぞれの元になるフィールドは次のとおりです。

  • erase:subject.reinstall: erase
  • install:subject.path のインストール(subject.reinstall はその方式)
  • permissions.<service>:シナリオの permissions の各サービス
  • seedPhotos:runsOn.ios.seedPhotos または runsOn.android.seedPhotos
  • locale:runsOn.ios.locale または runsOn.android.locale
  • launchEnv、launchArgs、deeplink:subject.launch.env、subject.launch.args、subject.launch.deeplink

ルートが適用できない設定は、run の preflight でシナリオを失敗させます。失敗のメッセージは、その設定、ターゲット、無視するための宣言を示します。各環境は起動時にも、適用できない設定をもう一度拒否します。そのため、record や crawl のように直接リースする場合も、適用できない設定は通りません。

唯一の逃げ道は、ターゲットの runsOn.ignoredSettings です。設定のキーに、その設定なしで実行する理由を書きます。このマップは同じ環境を表すので、runsOn の中で宛先のブロックと並べて置きます。BE-0473 が run グループを廃止するまでは、run.ignoredSettings という名前でした。

targets:
  iphone-device:
    platform: ios
    subject: { id: com.example.app }
    runsOn:
      ios: { kind: device }
      ignoredSettings:
        erase: "A real device keeps app data; this lane accepts state from earlier runs"

無視を宣言した設定は適用されません。run のレポートには、その設定がターゲット名と理由とともに載ります。manifest.json では各シナリオの ignored_settings に、HTML レポートでは Environment パネルの「ignored settings」表に載ります。JUnit では testcase の bajutsu.ignoredSettings プロパティに、CTRF ではテストの extra の ignoredSettings に入ります(レポート)。どれも判定の横に添える情報で、判定には影響しません。起動時にも、その設定を示す警告がログに出ます。record や crawl のようにレポートを書かない lease では、この警告で無視された設定を確認できます。この宣言は config の読み込み時に検証され、未知のキーや空の理由はエラーになります。無視する設定は 1 つの環境に属するものなので、defaults.platforms.<platform>.runsOn には書けません。ターゲットのルートがサポートまたは保証している設定を宣言すると、run の preflight で失敗します。ルートがその設定へ対応したとき、古くなった宣言が退行を隠すのを防ぐためです。シナリオ側では設定の無視を宣言できません。シナリオは、どの環境でも同じテストの定義であり続けます。

同じ表は、デバイスを使う前のさらに 2 か所でも判定に使います。--config と --target を付けた bajutsu lint は、ステップのチェックと並べて設定のチェックを行い、デバイスを必要としません(cli)。 serve は、ジョブが有効にする設定をもとにジョブを振り分けます。そのため、ジョブはその設定を適用できる ルートのワーカーにしか渡りません(self-hosting)。

実機用 runner の署名(設定の外、BE-0456)

iOS の実機では、ユーザー自身の Apple Developer チームで署名した XCUITest runner が必要です。ターゲットの設定には、この署名に関する値を意図して入れていません。設定はリポジトリとともに共有されるので、そこに書いた Team ID がほかのすべてのユーザーに届いてしまうためです。代わりに、リポジトリの外に置くユーザーごとの署名ファイルが、bundle identifier、チーム、署名方式を持ちます。

bajutsu runner build --device がこのファイルを読みます。以後、runsOn.ios.kind: device を指定して driver.runner.testRunner を指定しないターゲットは、そのビルドに解決します。ファイルの形式と探索順は iOS の実機で説明しています。

マシンが実行できるもの(設定の外、BE-0450)

設定ファイルはターゲットを記述し、アプリケーションのチームが書きます。1 台のマシンで何を実行できるかは別の事実で、それを知っているのはマシンの運用者です。そこで、別のファイル worker.yaml がこの事実を記述します。内容は、ワーカーの environment、ワーカーが提供するドライバ、1 つのシナリオが持てるターゲットの数です。設定ファイルはこれらのキーを持ちません。サーバのワーカーは、ジョブをリースしてから設定ファイルを読みます。それでは、どのジョブのために何を広告するかを決めるのに間に合いません。ファイルは bajutsu run --worker-config <path> と bajutsu worker --worker-config <path> で指定します。指定しなければ、同梱の既定のファイルを使います。ファイルの形式と検査は、このマシンで何を実行できるかで説明しています。

run をどこで実行するかも同じ種類の事実なので、ターゲットの外へ移りました(BE-0452)。1 つのプラットフォームのデバイスを提供する Appium のグリッドは、worker.yaml の appium environment として書きます。

version: 1
environment: appium
appium:
  endpoint: https://grid.example.com/wd/hub   # グリッドの Appium / WebDriver のアドレス
  platform: ios                               # 現時点で取れる値はこれだけ
drivers: [xcuitest, adb, playwright, fake]

デバイスを駆動するコマンドは、いずれも --worker-config でこのファイルを受け付けます。run、record、crawl、repl、audit、doctor、bajutsu mcp です。グリッドのプラットフォームのターゲットは、エンドポイントをデバイスとして使います。同じシナリオのほかのターゲットは、このマシンに残ります。エンドポイントは 1 台のデバイスとして数えるので、グリッドのターゲットを 2 つ持つシナリオを run は拒否します。--udid は URL を受け付けなくなりました。Device Farm のファンアウトは、バッチの provider を指定しません。ターゲットの旧 cloudBatch もありません。サーバは、ファンアウトの各ジョブをターゲットのプラットフォームで振り分けます(Device Farm)。

実機のホストアドレス(driver.runner.hostAddress)

実機の iOS デバイスは、ホストとループバックを共有しません。そのため実機上のアプリは、ホストのアドレスを使ってネットワークの collector に接続します。デフォルトでは、実行のたびに、ホストの有効なインタフェースが持つ経路のあるアドレスをすべてアプリに渡します。アプリは、最初に応答したアドレスを使います。ホストのインタフェースには、実機から届かないものも含まれる場合があります。driver.runner.hostAddress は、渡すアドレスを指定したもの(カンマ区切り)に絞ります。

targets:
  my-app:
    platform: ios
    subject: { id: com.example.app }
    runsOn: { ios: { kind: device } }
    driver:
      runner: { hostAddress: 192.168.1.20 }

環境変数 BAJUTSU_HOST_ADDRESS は、この設定より優先します。ジョブごとにアドレスが変わるホストでは、設定を書き換えず、実行ごとに環境変数で指定できます。シミュレータでは、この設定は何もしません。取り決めの仕組みは iOS を実機とデバイスクラウドで動かす で説明しています。

AI プロバイダ(ai:、BE-0047)

AI 経路、すなわち record、crawl、triage --ai は、任意の ai ブロックで設定した一つのプロバイダを通じてモデルへ到達します。このブロックは defaults と targets.<name> の両方で宣言でき、フィールドごとにマージされます(同じフィールドはターゲット側の値が勝ちます)。解決結果は Effective.ai に入るので、CLI と serve が一つの真実を共有します。これが「あなたの AI、あなたのキー、あなたのデータ」を支える仕組みです。どの AI 経路も、あなたが設定したキーとエンドポイントの下で動き、決定的な run ゲートはモデルをまったく呼びません(BE-0047)。

defaults:
  ai:
    provider: api-key                        # 登録済みのプロバイダ名。現状は api-key(既定)/ bedrock / ant / claude-code / none(AI 経路をすべて無効化)
    model:    claude-opus-4-8                 # 任意: その経路の既定モデルを上書き(環境変数 BAJUTSU_AI_MODEL でも可)
    effort:   high                            # 任意: 推論エフォート low/medium/high/xhigh/max(BAJUTSU_AI_EFFORT でも可)。claude-code
    language: auto                            # 任意: AI が生成する文章の出力言語 ja/en/auto(BAJUTSU_AI_LANGUAGE でも可)
    baseUrl:  https://ai-gateway.internal/v1  # 任意: 自己ホストのゲートウェイ / 社内プロキシ(api-key プロバイダ)
    keyEnv:   ANTHROPIC_API_KEY               # キーを保持する環境変数の「名前」。キーの値そのものは置かない
  • プロバイダは単一のインターフェースの背後に置かれたバックエンドです(BE-0104)。AI 経路は、プラットフォームが Driver インターフェースの背後のバックエンドであるのと同じように、ベンダー中立なシーム(bajutsu/ai)を通じてのみモデルへ到達します。そのため provider は固定された集合ではなく、レジストリで検証される開放型の値です。現在は api-key、bedrock、ant、claude-code のアダプタが同梱されています。前の三つは Anthropic アダプタを共有し、名前は認証手段を表します(直接の API キー、Bedrock の AWS 資格情報、ant CLI の OAuth トークンです。BE-0163。旧称 anthropic は今も api-key として解決されます)。claude-code(BE-0176)はローカルの claude CLI をサブプロセス起動する別個のアダプタです。未知の名前は AI 経路が最初にプロバイダを解決する時点で明確なエラーとともに fail closed になります。この検証は config の読み込み時ではなく AI 層で行います。決定的なコアは AI プロバイダのスタックを import してはならないため(BE-0112)、config は名前をそのまま受け取り、正当な名前を保持するレジストリが未登録の名前を拒否します。モデルファミリ(たとえば OpenAI 互換エンドポイント)の追加はアダプタの登録にあたり、下記の秘匿化とフェイルクローズの保証を構造上そのまま受け継ぎます。もう1つ none という名前も登録されています。これはベンダーではなくスイッチで、続く2つの項目で説明します。
  • none は「このリポジトリでは AI 経路を一切走らせない」という表明です(BE-0394)。none プロバイダのアダプタは何もしません。provider: none と書くだけで、あらゆる AI 経路が同時に無効になります。record、crawl、triage --ai は設定名を告げて終了コード 2 で終わります。プロバイダのファクトリはバックエンドを返さずに例外を送出するため、どのコード経路も AI バックエンドを構築できません。run はどちらの向きにも無関係です。BE-0402 以降、無効にすべき AI 経路をそもそも持ちません。

プロバイダのキーを環境に置かないだけでも、ほぼ同じ挙動は得られます。この設定が足すのは、レビュアーが読める形の方針です。キーの不在はリポジトリのどこにも意図を残しません。record でシナリオを書くために export したキーは、以後のどのシェルでもオーサリング経路をモデルに接続したままにします。設定は環境変数より優先されます。コミットした provider: none は、環境を誰も管理していない継続的インテグレーション(CI)のランナーでも BAJUTSU_AI_PROVIDER に覆されません。プロバイダを何も指定していないマシンで 1 度だけ実行したい場合は、BAJUTSU_AI_PROVIDER=none を従来どおり使えます。

defaults と targets.<name> のマージ規則は変わりません。defaults で AI を無効にしたうえで、特定のターゲットだけ有効に戻すこともできます。有効に戻す行は、誰の目にも触れない環境変数ではなく、同じファイルのなかでレビュアーが読む一行になります。 - serve の Settings のドロップダウンは none を提示しません。 プロバイダは登録されていますが選択可能ではないため、/api/provider は HTTP 400 で拒否します。組織の Settings での選択は BAJUTSU_AI_PROVIDER としてのみ起動するジョブへ渡り、プロジェクト自身の ai.provider がそれより優先されるからです。config でプロバイダを指定しているリポジトリでドロップダウンの none を選んでも効果はまったくなく、オフと書かれたスイッチの裏でジョブはモデルを呼び続けることになります。ここから1つの制限が生じますが、この項目は制限を解消せずに受け入れています。設定エンドポイントは Claude への到達可能性を、ターゲットの ai ブロックではなく組織が保存した選択から解決します。そのため provider: none を設定したリポジトリでも claudeAvailable: true を報告し、Web UI は record と crawl のタブを有効なままにします。スイッチ自体は効いています。これらのタブから始まるジョブはコマンドラインの起動です。リポジトリの config を自身で解決したうえ、モデルへ届く前に終了コード 2 で終わります。欠けているのは、タブを先にグレーアウトさせる事前の合図だけです。 - キーは設定ファイルに置きません。 keyEnv は環境変数の名前を指すだけで、値は呼び出し時に環境から読みます。これにより秘密がリポジトリやアップロードされたバンドルに入りません。baseUrl は Anthropic SDK を自己ホストのゲートウェイやプロキシへ向けます(Anthropic(base_url=…, api_key=os.environ[keyEnv]))。スクリーンショットや要素ツリーは、ベンダーの既定先ではなく、設定したエンドポイントにだけ届きます。Bedrock は標準の AWS 資格情報チェーン(AWS_REGION と、環境変数 / 共有プロファイル / インスタンスまたはタスクロール)のままで、プロバイダ接頭辞付きの model を必要とします。 - ant は API キー無しでサブスクリプション(SSO)のシートに課金します(BE-0163)。 ant プロバイダは公式の Anthropic CLI 経由でモデルへ到達します。CLI を導入し、ant auth login(Claude Console に対するブラウザ経由の OAuth(SSO)サインイン)を実行してください。Bajutsu は呼び出し時に CLI からベアラートークンを読み、API キーではなく auth_token として SDK に渡すため、Claude の Pro / Max / Console のシートに課金されます。ANTHROPIC_PROFILE で名前付きの CLI プロファイルを選べます。API キーは不要で、すべての AI 経路(オーサリング、アラートガード、triage --ai)で画像もそのまま使えます。ant はユーザー自身が導入する外部バイナリで、Bajutsu が同梱・インストールすることはありません。 - claude-code はローカル CLI 経由で Claude Code のサブスクリプションに課金します(BE-0176)。 claude-code プロバイダは Anthropic SDK ではなく claude CLI(claude -p、print モード)をサブプロセス起動するため、オーサリングや調査は、すでにサインイン済みの Claude Code の Pro / Max / Console のシート(claude setup-token、または対話ログイン)を使います。すべての AI 経路で画像もそのまま使えます。各スクリーンショットは呼び出しごとのスクラッチファイルに書き出し、そのパスをプロンプトで示したうえで、CLI にはそのディレクトリに限定した Read だけを許可して読ませます。画面上のテキストは信頼できない入力なので(BE-0125)、それ以外のツールはすべて拒否し、権限の確認は fail closed にします。ANTHROPIC_API_KEY があっても CLI の呼び出しからは取り除き、API ではなくサブスクリプションに課金されるようにします。claude はユーザー自身が導入する外部バイナリで、Bajutsu が同梱・インストールすることはありません。CI ランナーやコンテナ、リモートの serve のように、claude setup-token の対話的なブラウザ認証を実行できないヘッドレスなホストでは、それが可能な別のマシンで長寿命トークンを一度発行し、CLAUDE_CODE_OAUTH_TOKEN に設定します(シェル、.env、または serve の Settings パネルのいずれかで指定できます。パネルは API キーと並べてこのトークンを write-once で保持します。BE-0215)。claude CLI はこのトークンを環境変数から読むので、ヘッドレスなホストでも対話ログインは要りません。 - 設定が先、環境変数はフォールバック。 省略したフィールドは現状の環境変数(BAJUTSU_AI_PROVIDER、ANTHROPIC_API_KEY、BAJUTSU_BEDROCK_MODEL。ant プロバイダは ANTHROPIC_PROFILE を尊重しつつ CLI から資格情報を読みます)へフォールバックするので、ai ブロックの無い config はこれまでどおり動きます。 - モデルとエフォートも設定が先で、環境変数がフォールバックです。 model(または BAJUTSU_AI_MODEL)はどのプロバイダでも既定モデルを上書きします。effort(または BAJUTSU_AI_EFFORT)は推論エフォートを low/medium/high/xhigh/max から指定します。claude-code プロバイダがこれを CLI の --effort として反映します。config や環境変数から解決した未知の値はモデルの既定へフォールバックします。serve の Settings パネルは入力を検証し、未知の値はフォールバックせず拒否します(HTTP 400)。パネルは両方を変更できます。

ローカルの serve では、保存したプロバイダ、モデル、エフォートが serve 所有のファイルに永続化され、次回の起動時に復元されます(BE-0184)。再起動しても起動時の環境変数へ戻ることはなくなりました。config の ai: ブロックは復元された値よりも優先されます。

ホスト型のマルチテナントの serve では、この選択が組織ごとに解決・永続化されます(BE-0229)。そのため、各組織の record/triage/ドラフトの各経路は、その組織自身が保存した選択を使います。選択は共有のプロセス環境ではなく、ジョブごとの環境オーバーレイとしてジョブへ渡るので、ある組織の保存が別の組織の AI 実行を変えることはありません。

record は解決結果を冒頭に表示します(🤖 AI: <プロバイダ> · model <モデル> · effort <エフォート>)。 - 出力言語も設定が先の、もう一つの設定項目です(BE-0188)。language(または BAJUTSU_AI_LANGUAGE)は、AI が自分で生成する文章(散文)、すなわち record の from: 由来と crawl の流れる推論を、どの言語で書くかを固定します。値は ja / en / auto のいずれかで、auto(既定)は現状の挙動を保ちます。record はゴールの言語に追従し、crawl は英語のままです。実行ごとに record / crawl の --language で上書きでき(フラグ > config > auto)、serve の Settings パネルの「出力言語」プルダウンからも設定できます。未知の値は auto へフォールバックします(パネルは HTTP 400 で拒否します)。この設定が制御するのは記述と調査の文章だけで、決定論的な run の判定には触れません。下記のデバイス locale(アプリや UI の言語を設定するもの)とは別物です。 - フェイルクローズ。 record、crawl、triage --ai は、選択したプロバイダに使える資格情報が無いとき、プロバイダ別の明確なエラーで終了します。ホストされた既定先へ黙ってフォールバックするクライアントは決して構築しません。run は資格情報を一切参照しません(BE-0402)。 - テキスト系入力は秘匿化しますが、スクリーンショットは秘匿化できません。 モデルへ送る要素ツリー、失敗のテキスト、(ユーザー指定もありうる)アラート指示は、証跡の書き出しと同じ run スコープの秘匿化(対象の redact キーと解決済みの秘密値)で隠します。スクリーンショットは画像であり、秘匿化はテキストを隠せても画素は隠せません。そこで二つ目の保証がスクリーンショットを受け持ちます。スクリーンショットを含むすべての入力は、あなたが設定したプロバイダ/エンドポイントにのみ送られます。 - 画面に表示された秘密は画素に残ります(BE-0151)。 画像はマスクできないため、アプリが画面に表示する秘密(入力したパスワード、OTP、画面上の個人情報など)は、AI が見るスクリーンショットの画素にそのまま残ります。record は毎ターンのライブ画面を、triage --ai は run の runs/ 証跡に保存された失敗時点のスクリーンショット(あれば)を送ります。この画像は設定から解決した AI プロバイダへ送られます。秘匿化が覆うのはテキスト(ネットワーク、要素ツリー、ログ)に現れる ${secrets.X} の値であって、アプリが画面に描画した内容ではありません。これが不意打ちにならないよう、対象が secrets: をバインドしているとき、record と triage --ai は一度だけ警告を出します。これは緩和策ではなく告知です(視覚的な証跡こそが目的だからです)。この露出を完全に避けたいなら、秘密を含むフローで AI による作成を使わないか、テスト対象アプリで秘密を画面に出さないようにします。 - 使用量とコストは属性付きの台帳に記録します(BE-0196)。 すべての AI 呼び出しは、そのトークンが何に使われたか(コマンド、プロバイダ、モデル、シナリオ)を付けた 1 行を JSON Lines(JSONL)台帳に追記し、プロバイダにトークン単価があればドル換算のコストも付けます。これは記録のみで、ベストエフォートで書き出し、決定的な run の判定には一切触れません。ai の下の 2 つの任意フィールドで調整します。

defaults:
  ai:
    usageLedger: runs/usage.jsonl              # 任意: 台帳のパス(既定は runs/usage.jsonl、"" で無効化)
    pricing:                                   # 任意: 同梱のトークン単価を上書き(100 万トークンあたりのドル)
      api-key/sonnet: { input: 3.0, output: 15.0, cacheWrite: 3.75, cacheRead: 0.3 }

usageLedger は JSONL のパスを指定します。既定は(gitignore された runs/ ツリー下の)runs/usage.jsonl で、明示的に空文字列にすると永続化を無効にします。pricing は同梱のデフォルト単価表を上書きするもので、"プロバイダ/モデル" をキーにします(モデル部分はモデル id にファミリで一致します。たとえば api-key/sonnet は任意の claude-sonnet-* に適用します)。トークン単価を持たないサブスクリプションプロバイダ(ant、claude-code)は、捏造したドルの値ではなく null のコストとともにトークン数を記録します。上のテキスト入力と同じく、台帳が保存するのは件数、単価、ラベルだけで、プロンプトや応答の内容は保存しません。

mailbox(email ステップ)

targets.<name>.services.mailbox は、email ステップが 2FA / 検証コードを取得するためにポーリングする汎用 HTTP メールボックスを設定します。エンドポイントと認証情報をシナリオではなく config に置くためのものです。

targets:
  myapp:
    platform: ios
    subject: { id: com.example.myapp }
    services:
      mailbox:
        kind: http                                        # トランスポートアダプタ。省略時は http
        url: "${secrets.MAILBOX_URL}"                     # 受信箱エンドポイント(GET)。${secrets.*} は実行時に解決
        headers: { Authorization: "Bearer ${secrets.MAILBOX_TOKEN}" }
        # 任意のレスポンスマッピング。プロバイダ固有コードなしで任意の JSON を読むため:
        messages: "items"                                 # メッセージ配列へのドット区切りパス(既定: レスポンス自体が配列)
        fields: { to: to, subject: subject, body: text, receivedAt: receivedAt, id: id }

既定値はよくある形(to / subject / body / receivedAt / id を持つメッセージの配列)に合わせるので、準拠 API では messages / fields のマッピングは不要です。email ステップは受信箱を HTTP で読み、ステップ開始より新しいメッセージ(id で判定)だけを残し、一致するものを待ってコードを取り出します。決定的で LLM 非依存です(BE-0046)。

kind は、メールボックスの背後にあるトランスポートアダプタを選びます。メールボックスは 1 つのインターフェースの背後にある backend であり、ベンダーではなくトランスポート(http、将来は imap)でキーを引くので、トランスポートを増やすことは runner を分岐させることではなくアダプタを登録することになります(BE-0186)。kind は任意で、省略時は http になるので既存の mailbox: ブロックはそのまま動きます。未知の kind はフォールバックせず、きれいな config エラーで run を落とします。現在出荷しているのは http だけです。ベンダーではなくトランスポートでキーを引くのは、ベンダー間の違いが JSON のフィールド名だけで、それは fields が吸収するからです。

Webhook 通知(notify:、BE-0099)

notify: はトップレベルの Webhook エンドポイントのリストで、bajutsu run が判定後の副作用として POST します。LLM を一切使わず、決定的な判定に影響することもない Slack 優先の配信経路です(BE-0099)。

notify:
  - format: slack                              # レンダラ。現状出荷しているのは slack だけ
    url: "${secrets.SLACK_WEBHOOK_URL}"         # webhook URL。${secrets.*} は実行時に解決
    on: [failure]                               # failure(既定)/change/recovery/always/start
    targets: []                                 # 任意: このシナリオ名だけに絞る。空なら run 全体が対象
  • on は、このエンドポイントを発火させるイベントを選びます。failure(いずれかのシナリオが失敗、既定)、 always(すべての run)、change / recovery(run 全体の判定が、同じ config ソースの直前の run から 反転した場合。判定は runs ディレクトリ配下のその run の manifest.json から読みます)、start(run 開始前に、専用のメッセージで 1 回だけ発火。on が [start] だけのエンドポイントはそこでしか発火せず、 判定後には発火しません)。
  • targets(トップレベルの config の targets.<name> マップとは無関係です)は、リストにある名前の シナリオだけに通知を絞ります。空(既定)なら run 内のすべてのシナリオが対象です。
  • ターゲットは自分の notify を持ちません(BE-0473)。 どのターゲットの run もトップレベルのリストに送ります。targets.<name>.notify は読み込みに 失敗し、エラーがトップレベルのリストを示します。
  • 配信はベストエフォートです。タイムアウトに上限を設け、数回リトライし、失敗しても警告をログに出す だけです。判定や終了コードを変えることは決してなく、--zip や --evidence-store と同じ、判定後 専用の規律に従います。現状レンダリングされるのは format: slack だけです(失敗したシナリオを最大 5 件挙げ、残りは「…and N more」でまとめる Block Kit メッセージ)。未知の format、または url に 未解決の ${secrets.*} トークンが残っている場合は、壊れたペイロードを送る代わりに警告をログに出して スキップします。

org(orgs:、マルチテナントのサーバ backend)

orgs: は、ホスト型サーバ backend のテナントを宣言します(BE-0015)。各 org は、所属メンバーと、書き込みを許す GitHub Team(editorTeams)、その org が持つ targets を列挙します。所属メンバーの指定は3通りで、明示の GitHub login(members)、GitHub org 全体(githubOrgs)、単一の GitHub Team(githubTeams)です。

orgs:
  acme:
    members: [alice, bob]                   # 明示の GitHub login
    githubOrgs: [acme-gh]                    # この GitHub org の全員(read:org の OAuth scope が必要)
    githubTeams: [acme-gh/qa]                # この Team の直接メンバー(GitHub org 全体は含めない)
    editorTeams: [acme-gh/scenario-maintainers] # これらの Team の直接メンバーは editor になり、サインインもできる
    allowedRepositories: [acme/app]          # これらのリポジトリの CI ジョブがこの org として振る舞える
    targets: [demo, checkout]

allowedRepositories は、人間の名簿の隣に並ぶ org の機械の名簿です(BE-0414)。継続的インテグレーション(CI)のジョブが OpenID Connect(OIDC)トークンを交換して、この org として振る舞う短命のセッションを得られるリポジトリを挙げます。ロールは一切付きません。パイプラインを律するのは endpoint の許可リストであって、viewer/editor/admin ではありません。エントリには "<owner>/<repo>" という名前だけを書くか、その名前に environment、ref、workflowRef のいずれかの絞り込みを添えたオブジェクトを書きます。設定の手順、operator が指定しなければならない audience、交換の endpoint、名前の再利用とフォークにまつわる注意点は、セルフホスティングにあります。

OAuth ログイン時にユーザは自分の org に割り当てられます。順に、明示の members、GitHub org メンバーシップからの githubOrgs 一致、直接の Team メンバーシップからの githubTeams または editorTeams 一致を見ます。Team を最後に見るのは、org に Team を足したときに既存の login の所属先を動かさないためです。以後はその org の targets だけが見え、run の artifacts/scenarios/baselines はその org 専用のオブジェクトストレージ prefix の下に置かれます。どの org にも挙げられていない target は単一の default org に入るので、orgs: ブロックの無い config はシングルテナントです。CLI とローカルの serve は orgs: を一切参照しません。

GitHub OAuth を構成すると、org メンバーシップがアクセスも決めます(BE-0313)。サインインには構成済みの org への所属が必要です。members、githubOrgs、githubTeams、editorTeams のいずれかで所属すると、viewer ロールが付きます。viewer より上のロールは、Team のメンバーシップで決まります。

  • org の editorTeams のいずれかの直接メンバーは、editor に昇格します。
  • サーバ全体で 1 つ以上の admin Team(BAJUTSU_OAUTH_ADMIN_TEAMS。セルフホスティングを参照)のいずれかのメンバーは、admin になります。

editorTeams は昇格させるだけでなく、サインインも許します。書き込みを許した Team を githubTeams に重ねて書く必要はありません。editorTeams がリストなのは、githubOrgs と githubTeams がリストなのと同じ理由です。1つの org が複数の GitHub organization にまたがることがあり、枠が1つでは organization ごとの書き込み Team を挙げられません。旧来の単数形 editorTeam を書いた config もそのまま動きます。serve がそのキーを editorTeams に畳み込み、名前の変更が中途半端で単数形が複数形の隣に残っている場合は両方を畳み込みます。ただし、文書に載るのは複数形だけなので、名前は変更してください。

githubTeams の各エントリ、editorTeams の各エントリ、BAJUTSU_OAUTH_ADMIN_TEAMS の各エントリは、いずれも 1 つのフラットな Team で、"<github-org>/<team-slug>" の形で書きます。どれについても、その下にネストした Team は一致しません。比較は 3 つとも大文字小文字を区別しません。GitHub 自身が org login と Team slug をそう解決するからです。Team だけを名簿とする org は、GitHub の Teams API が答えることに依存します。/user/teams は fail closed で、Team を勝手に作り出しません。そのため API がエラーを返している間は、所属が Team だけの login は受け入れられるのではなく拒否されます。

OAuth を使う構成では、orgs: ブロックの宣言が必須です。ただし、構成済みの admin Team のメンバーだけは、構成済みの org への所属がなくてもサインインできます。GitHub の Teams API 自体がエラーを返している間を除きます。そのため、orgs: ブロックが壊れている、あるいは存在しない状態だけでは、admin 全員が締め出されることはありません。Team だけで許可された admin は、orgs: のどのエントリにも属さないため default org に置かれます。この復旧経路に頼るデプロイは、default という名前の実際の org を宣言しないでください。宣言すると、復旧した admin のユーザ行、audit の記録、オブジェクトストレージの prefix が、中立な catch-all ではなくそのテナントの中に入ってしまいます。

データベースを繋いだデプロイでは、この6つのフィールドのうち5つを読むのは一度きりです(BE-0375)。orgs テーブルがまだ空だった1回の起動時に、serve は各 org のメンバーシップを、この serve を起動したときの config からデータベースへ写します。対象は members、githubOrgs、githubTeams、editorTeams、allowedRepositories です。以後のサインインはデータベースだけを見て解決します。この書き写しはデプロイの一生に一度だけです。org が1つでも入っている状態で起動すれば、廃止済みのものが1つあるだけでも何も写さないので、後から config を書き換えても、その config を積んだまま再起動しても、admin の与り知らないところでテナントが増えたり形を変えたりすることはありません。起動後に Web UI や POST /api/config で bind した config は、orgs: に何が書かれていても、そもそも一切書き写しません。

メンバーシップの編集は、以後この config ファイルではなく Orgs ページから行います。この5つのフィールドをここで書き換えても効果はありません。ただし5つのうち allowedRepositories だけは Orgs ページに項目がなく、POST /api/orgs/<slug>/membership から編集します。Orgs ページから保存しても、この値は消えずに残ります。serve は、まだこの5つを宣言しているエントリの org 名を挙げて警告を記録するので、operator は編集が消えたと戸惑う代わりに、ファイルが決定権を持たなくなったことに気付けます。ここで引き続き効くのは targets です。したがって、そうしたデプロイでは targets: だけに削ぎ落としたエントリが本来の姿になります。書き写しの起きる起動より前に削ぎ落としても安全なので、順序を誤る余地はありません。targets だけを宣言したエントリは書き写しの対象から外れるため、その org が「誰も受け入れない」状態で固定されることはありません。

同じ名前の target を2つの org がそれぞれ要求してもよく、どちらの org もその target に対して認可されます。bind している config が1つである以上、その名前が解決する targets: の定義は両者で共有されます。

API 経由で bind した config――アップロードした bundle、compose した組、Git ソース――は、target の所有について orgs: ブロックを一切参照しません。 その config はある org として bind されたので、宣言されている target はすべてその org のものであり、ほかのどの org のものでもありません。ブロックに何が書かれていても変わりません。デプロイが管理していないファイルから所有を読むことは、そのファイルにメンバーシップを書かせないのと同じ信頼の問題であり、しかも黙って失敗していました。bundle の orgs: が唯一の target を自分の所属しない org のものだと主張していると、target の一覧が空になり、理由は何も示されませんでした。アップロードする bundle からは orgs: を外してください。そこでは何も決めません。データベースを繋いでいないデプロイは、以上のいずれとも無関係で、引き続きすべてのフィールドをこのファイルから読みます。

CLI からの選択

CLI(コマンドラインインターフェース)のすべてのコマンドは、--target <name> で 1 つのターゲットを選択し、--config(既定 bajutsu.config.yaml)で config を指定します。--backend はターゲットのプラットフォームを上書きせず、確認します。受け付けるのは、そのプラットフォーム、その actuator(xcuitest など)、fake のいずれかで、それ以外の値やカンマ区切りのリストは終了コード 2 で終了します(cli)。ターゲットが 1 つのプラットフォームを指定するようになったので、BE-0452 は順序付きのフォールバックのリストを取り除きました。

クロスブラウザマトリクス(--browsers、BE-0076)

bajutsu run --browsers chromium,firefox,webkit は、選んだシナリオをエンジンごとに 1 回ずつ実行し、エンジン × シナリオの合否マトリクスを 1 つ出力します。これは --browser と同じエンジン軸を複数指定する書き方で(web backend のみ。--browsers chromium は --browser chromium と同じであり、エンジンが 1 つなら通常の単一エンジン経路を通ります)、指定したすべてのエンジンがすべてのシナリオに合格したときだけ緑になります(all-must-pass)。Chromium と Firefox では緑なのに WebKit では赤になるシナリオは、描画エンジンの非互換が機械的に検出された箇所です。「Chrome では動くが Safari では壊れる」という、単一エンジンのテストでは決して見えない不具合がこれにあたります。判定はエンジンごとの既存の決定的な run の結果を集約したものに過ぎず、AI は判定に入りません。

各エンジンは専用のブラウザプールに対する独立した 1 パスなので、その証跡は runs/<id>/<engine>/<NN-scenario>/ の下に置かれ、エンジン間で衝突しません。実行後は run のルートに manifest.json、junit.xml、report.html を 1 組だけまとめます。manifest はエンジンごとの判定を集約した matrix ブロックを持ち、report はエンジン × シナリオのグリッドを描画し、JUnit は各ケースにエンジンを織り込むので(classname="bajutsu.<engine>")、CI からは chromium.login と webkit.login が別々のケースに見えます(reporting)。リストに未知のエンジンがあれば、--browser と同じく、どのブラウザも起動する前に終了コード 2 で終わります。3 つのエンジンはいずれも Linux 上でヘッドレス実行できるため、マトリクスは Mac もデバイスファームも要らず通常のゲート内で走ります。firefox/webkit のバイナリは実行時に取得します。

Git リポジトリからの config(BE-0063)

--config は Git ソースも受け付けます。ローカルにチェックアウトせずに、テストリポジトリのスイートを実行できます(例:bajutsu run --config github:acme/mobile-tests@v1.4.0:e2e/bajutsu.config.yaml --target checkout)。

github:<owner>/<repo>[@<ref>][:<path>]                          # GitHub ショートハンド
git+https://<host>/<owner>/<repo>.git[@<ref>][#<path>]          # 一般形(ホストは将来用に予約)
  • 現状で実装済みのホストは GitHub だけです。 一般形 git+https://<host>/… は解析します(GitHub Enterprise / GitLab などへの拡張の余地を残すため)が、github.com 以外のホストは今のところ、黙って github.com を叩くのではなく明確なエラーで失敗します。
  • Git ソースから実行した run は、解決したコミットを manifest.json の provenance(configSource: { host, owner, repo, ref, sha })に記録します。ブランチ指定の run でも、実際に実行した正確なコミットが分かり、後から再現できます(reporting)。
  • <ref> はブランチ、タグ、コミット SHA(既定はリポジトリのデフォルトブランチ)、<path> はリポジトリ内の config パス(既定はルートの bajutsu.config.yaml)です。スキームを認識できない値は、従来どおりローカルパスとして扱います。
  • ref を不変のコミット SHA に解決し、その部分木を content-addressed なキャッシュ(~/.cache/bajutsu/gitsrc/<host>/<owner>/<repo>/<sha>/)に展開して、そこから config を読みます。config の paths.scenarios / paths.baselines / paths.schemas / subject.path は相対パスで、チェックアウトのルートを基準に解決します。これはローカル config が自身のディレクトリを基準にするのと同じ「config の置き場所を基準にする」ルールで、基準点が取得したツリーのルートになるだけです。YAML だけでなくツリー全体が付いてきます。取得してきた config は信頼できないので、パスはチェックアウト配下に閉じ込めます。絶対パスや ../ による逸脱は拒否します。一方、operator が信頼できるローカルファイルは config ファイル自身のディレクトリを基準に解決し、閉じ込めません(兄弟ディレクトリを指してよい)。
  • 取得したばかりのチェックアウトにはビルド済みバイナリが無く、手元で先にビルドする「最初の一回」もありません。そこで Git ソースの run はアプリをオンデマンドでビルドします。subject.path が設定されていてバイナリが無いとき、config の subject.build コマンドをチェックアウトのルートから実行し(make -C demos/showcase swiftui-build のようなコマンドの相対パスはそこを基準にします)、その後に実行を続けます。ビルドが失敗すれば明快に終了します。ローカルパスの run は従来どおりで、ビルドはせず、バイナリが無ければエラーになります。
  • 固定コミット SHA(@<sha>)は再現可能で、初回取得後はオフラインで動きます。ブランチ(やタグ)は毎回解決し直します。
  • 非公開リポジトリには資格情報が要ります(BE-0224)。トークンは取得のたびに解決するので、ローテーションした秘密も再起動なしで反映されます。解決の順序は、設定済みの GitHub App installation(BAJUTSU_GITHUB_APP_ID と秘密鍵)、次に serve で入力した資格情報(BAJUTSU_GIT_CONFIG_TOKEN)、次に GITHUB_TOKEN / GH_TOKEN、次に gh auth token、それも無ければ匿名です。トークンはログに出しません。付与は最小権限にしてください。すべての非公開リポジトリに読み書きを与えてしまう classic の広い repo スコープの個人アクセストークン(PAT)ではなく、対象のリポジトリだけに Contents: read 権限で絞った細粒度(fine-grained)の PAT、または App installation を選びます。無人で動く self-hosted の serve は、人ではなくサービスに紐づく短命な installation トークンである GitHub App で認証してください(self-hosting の非公開リポジトリへのアクセスを参照)。アクセスが無いときの取得失敗は、素の 404 ではなく、レート制限、組織のシングルサインオン(SSO)の認可不足、トークンの拒否、あるいは「<owner>/<repo> に Contents: read を持つ資格情報を用意してください」といった、本当の原因を名指すメッセージで報告します。
  • bajutsu run にはゲート向けスイッチが 2 つあります。--config-offline はキャッシュを使いネットワークに触れません(オフラインでは解決できないので固定 @<sha> が必要)。--require-pinned-config は Git config がコミット SHA を固定していなければ失敗します。ゲートではブランチもタグも動きうるので、SHA だけを認めます。
  • serve の UI も Git ソースを bind します。起動時の serve --config github:…、または「Open config」ダイアログの 「From a Git repository」欄でチェックアウトを実体化し、そのルートから serve します(cli → serve)。非公開リポジトリ向けには、このダイアログに資格情報の入力欄があります(BE-0224)。細粒度の PAT や App トークンを入力すると、serve の秘密ストアを通じて write-once で保存します。値はマスクして表示し、二度と読み出しません(ローカルの serve ではプロセスの環境変数に保持し、ホスト型バックエンドでは組織ごとに暗号化して保存します)。アクセス不足の診断はダイアログ内にその場で表示します。
  • 残りの後続: record / crawl の読み取り専用入力(生成物は SHA キーのキャッシュではなくローカルの --out に書く)です。

新しいターゲットのオンボーディング

新しいターゲットを追加するには、アプリ側の準備と config への 1 エントリ追加を行います。ツール本体への変更は不要です。

  1. 実装規約を適用する。主要要素に accessibilityIdentifier を(アプリの名前空間で)付け、状態を label / traits / value に露出させ、launch hook を用意し、アニメーションを無効化します。
  2. targets.<name> を追加する。platform と subject.id(どちらも必須で、web のターゲットでは subject.url)に加え、必要に応じて subject.launch.env や subject.idNamespaces などを書きます。
  3. (任意)共通のセットアップを用意する。ログインなどをコンポーネントのファイルに切り出し、ターゲットの hooks.setup から use: { component: <file> } で呼びます。すると、各シナリオ自身のステップより前に実行されます。シナリオは preconditions.inheritSetup: false でこれを外せます。
  4. bajutsu doctor --target <name> で検証する。規約充足度スコアを見ます(下記)。
  5. シナリオを配置する。識別子はそのアプリの名前空間で書きます。

識別子の命名規約

accessibilityIdentifier は <namespace>.<element> のドット区切りです。すべて小文字で、各セグメントは [a-z0-9-] です。先頭セグメントが名前空間で、idNamespaces に宣言した集合のいずれかである必要があります。

settings.reindex            # <namespace=settings>.<element=reindex>
home.search
list.row.<id>               # 動的行: 末尾は「データ由来の安定キー」(index 由来は禁止)

3 つの不変条件:

  1. 画面内で一意。同一画面に同じ id を 2 つ置きません(selectors の曖昧検出)。 繰り返し要素はデータ由来キーで一意化し(list.row.3)、集合操作には idMatches + count を使います。
  2. 非ローカライズかつデータ由来。id に表示文言を使いません(翻訳で壊れるため)。
  3. 名前空間で前置。すべての id を宣言済みの名前空間で始めます。

showcase の id カタログは showcase(全体は demos/showcase/SPEC.md)にあります。

doctor(規約充足度スコア)

実装: bajutsu/common/doctor.py。AI 非依存で決定的です。1 画面の query()(CLI は actuator で取得した現在画面)を解析してスコアを出します。

doctor はまず実行可能ゲート(preflight.py)を確認し、その後でスコアを出します。ゲートが確認する内容は、選んだバックエンドが必要とするものです。iOS(XCUITest)バックエンドなら xcodebuild / xcrun、および起動済みシミュレータ。web(Playwright)バックエンドなら Playwright パッケージとその Chromium ブラウザ(uv sync --extra web と playwright install chromium)です。続いて現在画面を採点します。web ターゲットでは新しいブラウザをターゲットの subject.url に遷移させてそのページを採点し、iOS では起動済みシミュレータの画面を採点します。スコアの対象は、依然として現在表示されている画面だけです(入口や現在画面のみで、全画面は網羅しません)。

指標(Score)

操作可能要素(trait ∈ ACTIONABLE_TRAITS = button / link / textField / searchField / textView / switch / slider / tab / cell)を母数として測定します。

web バックエンドでは、クロスオリジンの iframe から読んだ要素を除きます。埋め込んだ動画プレイヤーやチャットのコントロールには、アプリの開発者が id を付けられないからです。そのため、それらが idCoverage を下げることも、id の重複として数えられることもありません。同一オリジンの iframe はアプリ自身の画面なので、採点に含めます。

指標 定義 しきい値(既定)
idCoverage id を持つ操作可能要素の割合 ✓ ≥ 0.9 / warn 0.7–0.9 / fail < 0.7
namespaceConformance id の先頭が idNamespaces に一致する割合 規約外を off_namespace に列挙
duplicateIds 1 画面内の id 重複数 1 件でも Blocked

グレード判定

  • Blocked: 画面に actionable な要素が 1 つも無い(多くは空画面、まだ読み込まれていない、または想定外の画面で、render がその旨を示します)、id 重複あり、または idCoverage < idCoverageFail(既定 0.7)。
  • Ready: idCoverage ≥ idCoverageOk(既定 0.9)かつ namespaceConformance == 1.0。
  • Partial: それ以外(実行はできるが、座標フォールバックやフレーキーの予告)。

しきい値の設定(doctor、BE-0024)

グレード判定に使う id カバレッジのしきい値は、トップレベルの doctor ブロックで変更できます。テスト用 id を付ける必要のない装飾的要素が多いアプリでは、しきい値を下げる(idCoverageOk や idCoverageFail を低めに設定する)ことで、ツール本体を変更せずに判定を緩められます。

doctor:
  idCoverageOk:   0.85   # 既定 0.9。カバレッジがこの値以上で "Ready" の候補になります
  idCoverageFail: 0.6    # 既定 0.7。カバレッジがこの値未満で "Blocked" になります

両方とも [0, 1] の範囲で指定し、idCoverageOk は idCoverageFail 以上でなければなりません。範囲外の値は config 読み込み時に拒否されます。省略すると既定値(0.9 / 0.7)が適用されるため、既存の config はそのまま動きます。

出力

render(score) が人間向けのサマリを返します。不足している要素は 具体的に列挙するので、id をどこに追加すればよいかがそのまま分かります。

grade: Partial
idCoverage: 0.83 (5/6)
namespaceConformance: 1.00
duplicateIds: 0
  missing id: label='Close' traits=['button'] frame=(...)

CLI の doctor は Blocked のとき終了コード 1 で終了します(cli)。

デバイスの条件があるときは、CLI が runs: セクションを加えます。run と同じように --udid のプールを読んで同じ run を作り、各 run に合うデバイスを並べます。--scenario がなければターゲット自身の run を、シナリオのファイルを指定すれば各シナリオの run を並べます。読み取るプールがないターゲットは、宣言した run だけを並べます。物理デバイスとグリッドのターゲットには、どちらもプールがありません。このセクションは情報の表示だけで、終了コードを変えません。スコア自体は、ターゲットの最初の run のデバイス(record が使うデバイス)を対象にします。