iOSのホーム画面にウィジェットを追加する操作の実現性調査¶
ステータス: 調査完了(
demos/showcase/scenarios/widget.yamlがbajutsu runで成功) 対象:BajutsuKit/Runner/(XCUITest backend)、bajutsu/common/drivers/xcuitest/、bajutsu/common/orchestrator/actions/handlers/gestures.py関連: ios-cross-app-ui-control-feasibility.md、docs/scenarios.md、docs/dsl-grammar.md
Bajutsuのシナリオから、iOSのホーム画面にウィジェットを追加できるかを調べました。結論として、既存のapp:ステップでSpringBoard(ホーム画面を描くプロセス)を名指しすれば、編集モードへの移行からウィジェットの追加とassertまで、意味付きのセレクタで駆動できます。新しいステップは要りませんでした。ただし途中で3つの不足が見つかり、うち2つはBajutsu側の不具合として修正しました。残る1つ(ギャラリーの検索結果の行がツリーに現れないこと)は、座標タップで補います。
実測は2026-09-29に、iPhone 17 Pro Simulator(iOS 26.5)上で行いました。途中でXcodeが26系から27.0に更新されたため、後半の実測とシナリオの成功はXcode 27.0でビルドしたランナーによるものです。他セッションと衝突しないよう、検証専用のSimulatorをxcrun simctl createで作って使いました。
1. 確かめたこと¶
次の5つを、Simulator上で決定的に再現できるかを確かめました。テスト対象アプリにはshowcaseのSwiftUI版を使いました。
| 目標 | 結果 |
|---|---|
| テスト対象アプリをバックグラウンドにする | background: {}で達成 |
| ホーム画面で編集モードに入り、「ウィジェットを追加」を開く | 意味付きセレクタで達成 |
| ギャラリーでウィジェットを検索し、サイズを選び、追加する | 検索結果の行だけ座標タップ、ほかは意味付きセレクタで達成 |
| 追加したウィジェットがホーム画面にあることをassertする | exists: { id: Calendar, value: Widget }で達成 |
| 追加したウィジェットをタップしてホストアプリを前面に出す | 達成(判定の根拠は4.3節) |
ウィジェットにはCalendarを選びました。どのSimulatorランタイムにも入っていて、データや権限がなくても描画されるからです。Filesのウィジェットも試しましたが、Simulator上で中身が描画されず、タップしてもFilesは開きませんでした。Clockはギャラリーの一覧に現れませんでした。
2. 手順ごとのアクセシビリティツリー¶
SpringBoardのツリーは、app: { bundleId: com.apple.springboard }の中からelements.jsonとして読めました。常駐ランナーは最後まで落ちませんでした。activate()が拒否されることも、ツリーが丸ごと空になることもありませんでした。
各画面で操作に使った要素を次の表に示します。en_USとja_JPの文言は、どちらもpreconditions.device.ios.localeでSimulatorのシステム言語を固定して実測しました(BE-0320の仕組みです)。
| 画面 | 要素 | traits | en_US |
ja_JP |
|---|---|---|---|---|
| ホーム画面 | アイコングリッド全体 | other |
id: Home screen icons |
id: Home screen icons |
| 編集モード | 左上のボタン | button |
Edit |
編集 |
| 編集モード | 右上のボタン | button |
Done |
完了 |
| 編集メニュー | ウィジェット追加 | button |
Add Widget |
ウィジェットを追加 |
| ギャラリー | 検索欄 | searchField |
Search Widgets |
ウィジェットを検索 |
| 詳細シート | サイズごとのプレビュー | button |
Calendar, Up Next/値Widget, Small |
カレンダー, 次はこちら/値ウィジェット, 小 |
| 詳細シート | ページ表示 | pageIndicator |
値page 1 of 6 |
値全6ページ中の1ページ目 |
| 詳細シート | 追加ボタン | button |
Add Widget(先頭に記号) |
ウィジェットを追加(先頭に記号) |
| ホーム画面 | 追加したウィジェット | other |
id: Calendar/値Widget |
id: カレンダー/値ウィジェット |
表から読み取れる注意点が2つあります。
1つ目は、アイコンのidentifierもローカライズされた名前であることです。言語を固定しないシナリオは、idで書いても言語に依存します。
2つ目は、詳細シートの追加ボタンのラベルが、先頭に記号の文字を含むことです。完全一致のlabelでは一致しないので、labelMatches: "Add Widget$"のように末尾で固定します。
3. 見つかった不足と対処¶
3.1 ギャラリーの検索結果の行がツリーに現れない¶
検索欄に文字を入力すると、XCUIApplication.snapshot()は結果一覧のコンテナを子のない要素として返します。結果の行は画面に表示されています。Bajutsuのランナーはツリーを1回のsnapshot()で読むので(BE-0105)、行を選ぶセレクタはどれも一致しません。
XCTestのテストコードで直接確かめた結果を次に示します。
| 読み方 | 検索前 | 検索後 |
|---|---|---|
springboard.snapshot() |
コレクションビューあり | コレクションビューが現れない |
各ウィンドウのsnapshot() |
未測定 | コレクションビューが現れない |
debugDescription |
未測定 | 行が現れる |
collectionViews["add-sheet-collection-view"].snapshot() |
未測定 | Cell "Calendar"が現れる |
cells["Calendar"]のクエリ |
未測定 | 約1秒で見つかる |
欠けるのはスナップショットの深さの制限によるものではありません。子を返さなかったノードは、アプリの根から8段目にありました。キーボードの表示との関係は確かめていません。
外部の報告(agent-device #1296)は、同じ行を「ラベルのないother」として観測しています。この環境で起きたのはラベルの欠落ではありません。要素そのものがツリーにありませんでした。
対処として、tapPointで先頭の行を座標でタップします。先頭の行は、検索欄の下の決まった位置に並びます。iPhone 17 Proの正規化座標では{ x: 0.5, y: 0.29 }で、en_USとja_JPのどちらでも同じ位置でした。座標は画面の大きさに比例させた値です。画面サイズの異なる機種では、行の位置はずれる可能性があります。
検索を取り消したあとの全件一覧は、行がラベル付きのcellとしてツリーに現れました(Ambient Music、Batteries、Calendarなど)。ただし、一覧の中身はギャラリーを開いた時点では空のことがあり、何秒待っても空のままのこともありました。一覧のcellを直接タップする経路は意味付きセレクタで書けますが、一覧が描画されるかどうかに左右されます。そのためwidget.yamlは、描画に左右されない検索と座標タップの経路を採りました。
3.2 tapPointとジェスチャの移動量が画面の3倍にずれる¶
tapPointの正規化座標は、要素ツリーの外接範囲を画面サイズとみなして絶対座標に変換していました。SpringBoardのツリーには、ピクセル単位の大きさ(1206×2622)を持つノードや、画面外にはみ出したポップオーバーの領域があります。そのため{ x: 0.5, y: 0.29 }は(603, 760)に変換され、幅402ポイントの画面の外をタップしていました。dragと方向指定のswipeの移動量(amount)も、同じ理由で3倍にずれていました。
tapPointと方向指定のジェスチャは、ドライバが本当の画面サイズを報告できるとき(ViewportProvider、BE-0326)はその値を使うように直しました。scrollがすでに使っている読み方と同じです。XCUITestではランナーが報告するアプリのウィンドウの大きさ(402×874ポイント)になります。
この問題はすでに修正済みです。
3.3 app:ブロック中のz-order問い合わせがテスト対象アプリを終了させる¶
SpringBoardのブロックを抜けてテスト対象アプリへ戻るとき、app did not reach the foreground while leavingで失敗することがありました。デバイスのログを見ると、テスト対象アプリは前面へ戻る瞬間にSIGPIPEで終了していました。
条件を切り分けた結果を次に示します。
| 条件 | 結果 |
|---|---|
| XCTestのテストコードだけで、テスト対象アプリを190秒バックグラウンドに置いて戻す | 戻る |
| bajutsuで、SpringBoardのブロック内で約25回の待機を行う(約190秒) | SIGPIPEで終了 |
| 同じシナリオを、修正後のドライバで実行する | 戻る(ブロックは38秒で完了) |
原因は、XCUITestドライバがquery()のたびに、テスト対象アプリ内のz-orderレスポンダ(BE-0355)へ問い合わせていたことです。app:ブロックの中では、テスト対象アプリはバックグラウンドで停止しています。問い合わせは2秒でタイムアウトし、停止中のアプリのソケットに溜まります。アプリが再開すると、溜まった問い合わせへの応答を書き込む途中でSIGPIPEが起きたと見られます。どの書き込みがSIGPIPEを起こしたかまでは特定していません。
問い合わせ自体も誤りでした。ブロックの中のツリーは別のアプリのもので、テスト対象アプリの位置情報を当てはめる対象ではありません。そこで、app:ブロックが開いているあいだはz-orderを問い合わせないように直しました。修正の副産物として、SpringBoard上の各ステップは約2秒から約0.2秒に縮みました。すべてのツリー読み取りが、2秒のタイムアウトを払っていたためです。
この問題はすでに修正済みです。
3.4 ホストアプリの初回起動で出るプロンプト¶
eraseの直後にウィジェットをタップすると、Calendarは初回起動で2つの許可プロンプトを出します。1つは位置情報のプロンプト(Allow “Calendar” to use your location?)です。もう1つは通知のプロンプト(“Calendar” Would Like to Send You Notifications)です。3回の実行で、順序は位置情報が先、通知が先、2つが同時、と一定しませんでした。
2つが同時に出ると、handleSystemAlertのDon’t Allowは2つのボタンに一致します。Bajutsuは曖昧なセレクタで「最初に一致したもの」を押さないので、ステップは失敗します。prompt: notificationsの形も、解決すると同じDon’t Allowのラベルになるため、曖昧さは解消しません。
widget.yamlはプロンプトに答えず、そのまま残します。プロンプトはCalendarのものなので、テスト対象アプリが前面に戻ると表示から外れます。ただし残ったプロンプトは、Calendarが次に前面へ出たときと、ホーム画面のツリーを読むときに現れます。widget.yamlは毎回eraseするので、次の実行には持ち越しません。eraseしない別のシナリオを同じデバイスで続けて実行すると、ホーム画面のツリーが読めなくなります。
4. シナリオの制約と注意¶
4.1 前提とする環境¶
- Simulatorでのみ実測しました。 実機とデバイスクラウドは確かめていません。
- iOS 26.5でのみ実測しました。 Xcode 27.0の更新でiOS 27.0のランタイムも使えるようになりましたが、iOS 27.0では確かめていません。版によって文言やツリーの形が変わりうるので、別の版を対象にするときは第2節の表を版ごとに測り直す必要があります。
- iPhone 17 Proの画面で座標を決めました。 検索結果の行を押す
tapPointの座標は、この機種での値です。
4.2 erase後のホーム画面の初期状態¶
widget.yamlはpreconditions.subject.reinstall: eraseを前提にします。理由は2つあります。
- 長押しはアイコングリッド(
Home screen icons)の中心に当たります。そこが空いた壁紙でないと、アイコンやウィジェットの長押しになり、編集メニューではなくコンテキストメニューが開きます。eraseと再インストールのあと、SpringBoardはテスト用アプリをインストールしたページ(全2ページ中の2ページ目)を開きます。このページは下半分が空いています。1ページ目の中心にはウィジェットがあります。XCTestのテストコードから1ページ目の長押しを行ったときは、編集メニューが開きませんでした。 eraseしないと、前の実行が追加したCalendarのウィジェットが残ります。同じidと値を持つウィジェットが2つになり、最後のassertが一意に決まりません。
4.3 ホストアプリが前面に出たことの判定¶
app: { bundleId: com.apple.mobilecal }は、ブロックへ入るときにCalendarをactivate()します。そのため、Calendarのツリーが読めたことだけでは、ウィジェットをタップしてCalendarが開いた証拠になりません。
widget.yamlは、タップの直後にSpringBoardのツリーからHome screen iconsが消えるのを待ちます。アプリが前面に出るとアイコングリッドはSpringBoardのツリーから外れるので、この待機が起動の判定になります。タップの代わりに空いた壁紙をタップするシナリオでは、この待機が10秒でタイムアウトして失敗することを確かめました。
4.4 フレークの注意¶
- ギャラリーの一覧の描画。 3.1節のとおり、ギャラリーを開いた直後の一覧は空のことがあります。検索の経路はこの影響を受けません。
- プロンプトの持ち越し。 3.4節のとおり、
eraseしない実行ではCalendarのプロンプトが残り、ホーム画面のツリーを読めなくします。 simctlの一時的な停止。 実測の途中で一度、simctl privacy resetが60秒でタイムアウトしました。同じ実行をやり直すと成功しました。
5. 実行の記録¶
5.1 シナリオの実行¶
make -C demos/showcase e2e-springboard-widget SIM=<検証専用SimulatorのUDID>
widget.yamlは、SwiftUI版で3回、UIKit版で1回成功しました。1回あたり約2分半で、その大半はeraseとアプリの再インストールです。
5.2 失敗理由の記録¶
依頼にあった3つの失敗理由について、観測した結果を記録します。
| 失敗理由 | 観測 |
|---|---|
activate()の拒否 |
SpringBoard、Calendar、Safariのいずれでも起きませんでした |
| ツリーが空 | 検索結果の一覧だけが欠けました(3.1節)。ホーム画面、編集モード、詳細シートは読めました |
| タイムアウト | ブロックを抜けるときの前面化の失敗は、z-orderの問い合わせが原因でした(3.3節)。修正後は起きていません |
5.3 XCTestのテストコードによる切り分け¶
3.1節と3.3節の切り分けには、BajutsuKit/Runner/Sources/に一時的なテストファイルを置いて使いました。実行の手順はios-cross-app-ui-control-feasibility.mdの4章と同じです。テストファイルは実証後に削除し、xcodegen generateでproject.pbxprojを元に戻しました。検証専用のSimulatorも、実測の後に削除しました。