argent-settings-permissions

このツールの用途

settings-permissions は、プラットフォームの権限ストアを直接編集します。iOS シミュレーターの TCC データベース、または Android のパッケージマネージャーの権限フラグが対象です。テストのセットアップ時に手動で行っていた 設定 → プライバシー の操作を置き換えます。サービスを事前に許可してアプリからの確認を不要にしたり、あらかじめ拒否して拒否時の動作をテストしたり、リセットして次回の起動時に初回起動時のダイアログを再表示したりできます。

これはテストセットアップ用／アプリ外部から操作するツールであり、一般的な権限切り替えツールではありません。権限を変更する通常の方法は、引き続きアプリから操作することです。このツールは、アプリから操作できないケースに限って使う例外です。

使用する場合と使用しない場合

次の順序で判断してください。最初に一致した行を適用します。

状況	対応	理由
アプリに権限を設定するアプリ内コントロール（アプリ独自の設定画面にある切り替えスイッチ）がある場合	アプリ内でタップします（describe → gesture-tap）。このツールは使用しないでください	実際のユーザーの操作であり、テスト対象のフローを実行できます。argent-device-interact を参照してください。
アプリが権限を要求しようとしている（または要求した直後で）、システムの権限ダイアログが画面に表示されている場合	ダイアログをタップします（Allow／Don't Allow／Allow While Using App）。このツールは使用しないでください	アプリが表示したプロンプトに応答するのが自然な手順であり、ユーザーが行う操作です。describe でダイアログのボタンを確認できます。確認できない場合に限り、screenshot に切り替えてください。
アプリの実行前に権限をすでに許可または拒否しておきたいため、フローをダイアログで中断させたくない場合	launch-app の前にこのツールを使用します（grant／deny）	アプリが自身の権限を事前に設定することはできません。実際のユーザーなら設定アプリで操作します。これが主なユースケースです。（deny でプロンプトを抑制できるのは iOS のみです。注意事項を参照してください。）
ユーザーが権限をすでに拒否しており、再び有効にしたい場合	このツールを使用します（grant）	iOS では一度拒否した権限のダイアログは再表示されません。デバイス内での唯一の方法は設定アプリです。このツールを使えば手早く変更できます。
初回起動時のダイアログを再び表示したい（プロンプト自体をテストする、または変更された状態をリセットする）場合	このツールを使用します（reset）	権限を「まだ要求していない」状態に戻すため、次回アプリを使用したときにプロンプトが表示されます。
対象プラットフォームで、このツールがサポートしていない権限の場合（サポート表を参照）	このツールは使用しないでください	「unsupported」エラーが返されます。アプリがダイアログを表示する場合はそのダイアログを使うか、実際の設定アプリを操作してください。
Wi-Fi、モバイルデータ通信、ダークモード、VPN、集中モードなど、以下の11 種類のランタイム権限に含まれない設定の場合	このツールは使用しないでください	対象外です。代わりに設定アプリまたはアプリ独自の UI を操作してください。

**判断の目安：**人間のテスターが アプリ内で 切り替えられる設定なら、アプリ内で操作してください。人間が通常なら システム設定アプリで変更する設定に限り、settings-permissions を使用してください。

対応する権限とプラットフォーム

permission	iOS シミュレーター（TCC サービス）	Android（android.permission.*）
camera	camera - 対象シミュレーターのランタイムでモデル化されている場合のみ（インストール済み Xcode ではなく simruntime によって異なります。シミュレーターにはカメラハードウェアがありません）	CAMERA
microphone	microphone	RECORD_AUDIO
photos	photos + photos-add（追加のみのアクセスは独立した TCC サービスです。photos-add はベストエフォートです。両方が変更されたかどうかは applied を確認してください）	READ_MEDIA_IMAGES + READ_MEDIA_VIDEO + READ_MEDIA_VISUAL_USER_SELECTED + READ_EXTERNAL_STORAGE
contacts	contacts	READ_CONTACTS + WRITE_CONTACTS
notifications	非対応 - iOS に相当するものはありません。アプリのダイアログに応答してください	POST_NOTIFICATIONS
calendar	calendar	READ_CALENDAR + WRITE_CALENDAR
location	location	ACCESS_FINE_LOCATION + ACCESS_COARSE_LOCATION
location-always	location-always	ACCESS_BACKGROUND_LOCATION（許可すると fine + coarse も追加されます。バックグラウンド権限だけでは位置情報を読み取れません）
media-library	media-library	READ_MEDIA_AUDIO + READ_EXTERNAL_STORAGE
motion	motion	ACTIVITY_RECOGNITION
reminders	reminders	非対応 - Android のランタイム権限はありません

1 つの抽象権限が複数の具体的な Android 権限に対応する場合があります。実際に存在する権限は、アプリのマニフェストとデバイスの API レベルによって異なります（例：API 33 以降では READ_MEDIA_*、それより前では READ_EXTERNAL_STORAGE）。

アクション

• grant - 権限を事前に許可します。bundleId が必要です。
• deny - 権限を拒否します。bundleId が必要です。アプリの「権限拒否」時の処理をテストする場合に使用します。
• reset - まだ確認されていない状態に戻し、次回の使用時にダイアログを再表示します。必ずアプリ単位で指定します（bundleId が必要です）。
  • iOS：そのアプリの TCC 行を削除します。デバイス全体のリセット（bundleId なし）は提供していません。最近の iOS ランタイムでは、成功と報告されても既存のアプリごとの許可がそのまま残るため、実際には変更されていないのに変更があったと報告されてしまいます。
  • Android：許可を取り消した後、可能な範囲でユーザー設定／ユーザー固定フラグをクリアします（フラグのクリアが導入されたのは Android 13／API 33 以降です。成功判定の対象となるのは許可の取り消しです）。API 33 未満（つまり API 23～32。ユーザー固定状態が存在するすべての環境）ではフラグをクリアできません。そのため、その環境で reset を実行すると許可は取り消されますが、「次回から確認しない」（ユーザー固定）状態はクリアできず、古いデバイスではダイアログが引き続き表示されない場合があります。

パラメーター

{
  "udid": "<UDID-or-serial>",
  "action": "grant",
  "permission": "camera",
  "bundleId": "com.example.app"
}

• udid - list-devices の対象（iOS シミュレーターの UDID、または Android のシリアル番号）。取得方法については argent-ios-simulator-setup ／ argent-android-emulator-setup を参照してください。
• action - grant | deny | reset。
• permission - 上記の 11 個の名前のいずれか。
• bundleId - iOS のバンドル ID または Android のパッケージ名。すべてのアクションで必須です。

プラットフォームごとの動作

iOS シミュレーターのみ。 シミュレーターの TCC ストアを編集します。必ずアプリ単位で指定します（bundleId が必要です）。物理 iPhone にはホスト側の TCC 切り替え機能がないため、このツールは実機の iOS デバイスには適用されません。シミュレーターは事前に 起動 しておく必要があります（boot-device）。起動していない場合、ツールは「current state: Shutdown」エラーで失敗し、起動方法のヒントを表示します。

Android エミュレーターおよび実機。 adb 経由でアプリの android.permission.* ランタイム権限を変更します（reset の場合は、可能な範囲でユーザー設定／ユーザー固定フラグもクリアします。成功を決めるのは許可の取り消しです。フラグのクリアには Android 13／API 33 以降が必要です）。要件：

• アプリが インストール済み である必要があります。ツールは最初にパッケージの有無を確認し、見つからない場合は明確なエラーを返します（通信／タイムアウトの失敗では、「インストールされていない」という誤ったメッセージではなく、adb の実際の原因が表示されます）。
• アプリのマニフェストで権限を 宣言 している必要があります。マニフェストで要求されていない、対応する権限はパッケージマネージャーによって拒否され、結果の skipped リストに追加されます。対応する権限が 少なくとも 1 つ 適用されればアクションは成功し、すべて 拒否された場合にのみエラーになります。

注意点

• 権限を変更すると、実行中のアプリが終了することがあります（両プラットフォームのシステム動作です）。権限は launch-app の前に設定してください。アプリの実行中に変更した場合は、その後 restart-app を実行してください。
• リセットは両プラットフォームともアプリ単位です。bundleId を渡してください。デバイス全体を確実にリセットする方法はありません。
• Android で部分的な結果になるのは通常の動作です。 applied には実際に変更された項目が、skipped にはパッケージマネージャーが拒否したマッピング済みの権限（通常はマニフェストに記載がないか、API レベルの制限があるもの）が表示されます。両方を確認すると、何が起きたかが分かります。
• 起動前の deny でプロンプトが抑制されるのは iOS のみです。 iOS では、TCC による拒否がアプリからの要求への応答となるため、ダイアログは表示されません。Android では、deny によって許可が取り消されますが、「ユーザーが固定した」フラグは設定されないため、アプリが次に要求したときもシステムダイアログが表示されます。つまり Android で起動前に deny を指定すると、プロンプトを抑制するのではなく、取り消された 状態 をテストします。
• iOS の camera は、そのサービスをモデル化していないシミュレーターの ランタイム に拒否されることがあります（これはインストール済み Xcode ではなく simruntime によって異なります。プラットフォーム独自のサービス一覧に camera がなくても、ランタイムが受け付ける場合があります）。拒否は汎用的な CoreSimulator エラーとして表面化するため、camera の失敗（ブートのヒントが表示されるシミュレーターのシャットダウン時を除く）には、ランタイムがサポートするサービスに関するヒントが表示されます。
• grant location を使うには、アプリを先にインストールする必要があります（iOS）。 位置情報の認証状態は TCC に保存されず、アプリが存在するまでバンドル ID に適用されないため、インストール前の grant location／grant location-always は何も記録しません。ローカルシミュレーターでは、ツールがインストール状態を確認し、誤った成功を報告せずに明確なエラーを返します。リモートシミュレーターではインストール状態を確認できないため、インストール前に許可を付与すると、何も記録されていないのに成功と報告されます。リモートで位置情報の許可を付与する前に、アプリがインストールされていることを確認してください。（camera／photos など、TCC によって管理されるサービスはインストール前でも許可を付与でき、状態は保持されてインストール時に適用されます。）

結果

{ action, permission, bundleId, applied, skipped? } を返します。

• applied - 実際に変更されたプラットフォームレベルのサービス／権限（iOS では TCC サービス、Android では android.permission.* の名前）。
• skipped - Android のみ。一部のマッピング済み権限が拒否された一方で、ほかの権限は適用された場合に表示されます。

何も適用できなかった場合、呼び出しは失敗します。エラーに理由が記載されています。プラットフォームでサポートされていない権限（iOS の notifications、Android の reminders）、アプリが未インストール（iOS でインストール前に grant location を指定した場合を含む）、シミュレーターのシャットダウン（iOS）、またはマッピングされた権限がすべて拒否された場合（通常はマニフェストに記載がない場合）です。シャットダウン以外の camera の失敗には、シミュレーターランタイムがサポートするサービスに関するヒントも表示されます（シミュレーターのシャットダウンによる失敗の場合は、代わりにブートのヒントが表示されます）。

例

起動前にカメラの許可を付与し、アプリにプロンプトを表示させないようにします。

{ "udid": "<UDID>", "action": "grant", "permission": "camera", "bundleId": "com.example.app" }

拒否される場合の動作をテストします。位置情報を拒否してから起動し、フォールバックを確認します。

{ "udid": "<serial>", "action": "deny", "permission": "location", "bundleId": "com.example.app" }

Android の通知をリセットし、次回の起動時に初回起動時のプロンプトが再び表示されるようにします。

{
  "udid": "<serial>",
  "action": "reset",
  "permission": "notifications",
  "bundleId": "com.example.app"
}

Android で常時位置情報へのアクセスを許可します（バックグラウンドとフォアグラウンドの両方に自動的に適用されます）。

{
  "udid": "<serial>",
  "action": "grant",
  "permission": "location-always",
  "bundleId": "com.example.app"
}