xcrun simctl status_barは、シミュレータのステータスバーに表示される時刻・電波・バッテリーなどの表示を、任意の固定値で上書きするサブコマンドである。
基本的な使い方
overrideに続けて、上書きしたい項目をオプションで指定する。
$ xcrun simctl status_bar booted override \
--time "9:41" \
--dataNetwork wifi --wifiBars 3 --cellularBars 4 \
--batteryState charged --batteryLevel 100 \
--operatorName ""
実行後にスクリーンショットを撮ると、Appleの製品画像でおなじみの「9:41」表示と、満タンの電波・バッテリー表示になっていることを確認できる。
現在の設定を確認する
listで、現在適用されている上書き設定を確認できる。
$ xcrun simctl status_bar booted list
Current Status Bar Overrides:
=============================
Time: 9:41
DataNetworkType: 11
WiFi Mode: 3, WiFi Bars: 3
Cell Mode: 3, Cell Bars: 4
Operator Name:
Battery State: 2, Battery Level: 100, Not Charging: 0
実際に試したところ、override実行時に指定したwifiやchargedといった文字列の値は、listではDataNetworkType: 11やBattery State: 2のような内部の数値コードとして表示された。
listの出力から元の文字列指定を逆算するのは難しいため、設定内容を把握しておきたい場合はoverride時に指定した値を別途控えておいた方がよい。
設定を解除する
clearで全ての上書きを解除し、実際の時刻・電波・バッテリー状態の表示に戻せる。
$ xcrun simctl status_bar booted clear
範囲外の値を指定するとエラーになる
--wifiBars（0〜3）や--batteryLevel（0〜100）のように範囲が決まっている項目に範囲外の値を指定すると、具体的な期待範囲を含むエラーになる。
$ xcrun simctl status_bar booted override --wifiBars 5
An error was encountered processing the command (domain=NSPOSIXErrorDomain, code=22):
Simulator device failed to complete the requested operation.
Invalid argument
Underlying error (domain=NSPOSIXErrorDomain, code=22):
Invalid value for wiFiBars: expected 0-3
Invalid argument
一方、--dataNetworkのように決められた文字列以外を指定した場合や、overrideにオプションを1つも指定しなかった場合の挙動は異なる。
wiFiBarsの例のような詳しいエラー説明はなく、簡潔な1行のメッセージに続けてヘルプ全体が再表示される。
$ xcrun simctl status_bar booted override --dataNetwork invalidtype
Invalid dataNetwork: invalidtype
Set or clear status bar overrides
Usage: simctl status_bar <device> [list | clear | override <override arguments>]
...
--timeにISO日付文字列を指定する
ヘルプには「有効なISO日付文字列であれば、対応するデバイスでは日付も設定される」と記載されている。
実際に試したところ、2030-01-01T09:41:00Zのような一般的なISO 8601形式ではいずれもInvalid, non-ISO date/time stringというエラーになった。
$ xcrun simctl status_bar booted override --time "2030-01-01T09:41:00Z"
An error was encountered processing the command (domain=NSPOSIXErrorDomain, code=22):
Simulator device failed to complete the requested operation.
Invalid argument
Underlying error (domain=NSPOSIXErrorDomain, code=22):
Invalid, non-ISO date/time string
Invalid argument
ミリ秒部分（.000）まで含めた形式を指定すると成功した。
$ xcrun simctl status_bar booted override --time "2030-01-01T09:41:00.000Z"
$ xcrun simctl status_bar booted list
Current Status Bar Overrides:
=============================
Time: 18:41
UTCで指定した09:41が、シミュレータのタイムゾーン（JST）に変換されて18:41と表示されており、単なる文字列の上書きではなくタイムゾーンを考慮した時刻として扱われていることが分かる。
末尾がZでもミリ秒部分を省略すると失敗するため、日付を指定する場合はミリ秒まで含めた形式で指定する必要がある。
活用例: マーケティング用スクリーンショットの自動生成
App Storeに掲載するスクリーンショットや、ブログ・ドキュメントに載せる画面画像を撮影する際、実際のバッテリー残量や電波状況によって見た目がばらついてしまう。
撮影前にstatus_bar overrideで時刻やバッテリー表示を固定しておけば、常に同じ見た目のステータスバーでスクリーンショットを撮影できる。
$ xcrun simctl status_bar booted override --time "9:41" --batteryState charged --batteryLevel 100
$ xcrun simctl io booted screenshot screenshot.png
$ xcrun simctl status_bar booted clear
CIでのスクリーンショット自動生成に組み込めば、毎回同じ条件のステータスバーで画面画像を機械的に収集できる。
