expo-testing

Expo のテスト

iOS シミュレーターおよび実機で Expo／React Native アプリをビルド、インストール、テストします。

プロジェクト設定の確認

作業を始める前に、プロジェクトの設定を読み、次の項目を確認します。

1. バンドル ID — app.config.js、app.config.ts、または app.json の expo.ios.bundleIdentifier
2. EAS プロファイル — eas.json で利用可能なビルドプロファイル（development、preview、production）
3. Detox の設定 — .detoxrc.js または detox.config.js のテストランナー、ビルドコマンド、デバイス設定
4. ディープリンクのスキーム — app.config.js の expo.scheme
5. パッケージマネージャー — bun.lockb → bun、pnpm-lock.yaml → pnpm、yarn.lock → yarn、それ以外は npm

2 つの方法

方法 1：シミュレーター（デフォルト）

自動テスト、TDD の反復、AFK 実行に使用します。

1. Prebuild (if native code changed)
   npx expo prebuild --platform ios --clean

2. Build for simulator
   xcodebuild -workspace ios/<AppName>.xcworkspace \
     -scheme <AppName> \
     -configuration Debug \
     -sdk iphonesimulator \
     -derivedDataPath ios/build

3. Install on booted simulator
   xcrun simctl install booted ios/build/Build/Products/Debug-iphonesimulator/<AppName>.app

4. Launch
   xcrun simctl launch booted <bundleId>

自動再ビルドの判定：前回のビルド以降に次のいずれかが変更されたか確認します。

• ios/ ディレクトリの内容（ネイティブモジュール）
• package.json またはロックファイル（新しいネイティブ依存関係）
• app.config.js／app.json（設定の変更）
• *.podspec または Podfile に一致するファイル

どれも変更されていない場合は、prebuild と xcodebuild を省略し、再インストールして起動するだけです。

方法 2：実機

手動テスト、他のユーザーとの共有、またはハードウェア固有の機能のテストに使用します。

ローカル（USB 接続）：

npx expo run:ios --device

接続済みデバイスを一覧表示し、直接インストールします。

EAS クラウドビルド（共有可能）：

1. Build
   eas build --profile preview --platform ios

2. Download and install
   # EAS provides a QR code / install link
   # Or download .ipa and install via Finder/Apple Configurator

デバイスの登録（初回のみ）：

eas device:create
# Follow the URL to register the device's UDID

Detox テストの実行

シミュレーターでビルドとインストールを行った後：

# Full suite
npx detox test --configuration ios.sim.debug

# Specific test file
npx detox test --configuration ios.sim.debug e2e/<testFile>.e2e.ts

# With screenshots on failure (default Detox behavior)
# Artifacts saved to artifacts/ directory

Detox を実行する前に、Detox のバイナリを再ビルドする必要があるか確認します。

npx detox build --configuration ios.sim.debug --if-missing

バイナリがすでに存在し、最新の状態であれば、ビルドを省略します。

E2E のベストプラクティス

• インタラクティブな要素には testID プロパティを使用し、安定したセレクターを指定します。
• アニメーションやタイマーのある画面では Detox の同期を無効にします。

  await device.disableSynchronization();
  // interact with animated screen
  await device.enableSynchronization();
  

• テストのエントリーポイントにはディープリンクを使用します。アプリに URL スキームが設定されている場合（アプリ設定の expo.scheme）、画面を直接起動できます。

  await device.openURL({ url: '<scheme>://e2e' });
  

  スキームがなく、E2E のエントリーポイントが必要な場合は、追加を検討してください。オンボーディングをスキップして、テスト対象の画面に直接移動できます。

スクリーンショットのキャプチャ

ドッグフーディングやバグの発見のために、スクリーンショットをキャプチャします。

// In Detox tests
await device.takeScreenshot('descriptive-name');

スクリーンショットは Detox の成果物ディレクトリに保存されます（.detoxrc.js で設定可能）。成果物ディレクトリが .gitignore に含まれていることを確認してください。

シミュレーターで手動でスクリーンショットをキャプチャするには：

xcrun simctl io booted screenshot screenshots/<name>.png

ドッグフーディングの成果物は .dogfooding/ に保存します（gitignore 対象）。

.dogfooding/
  screenshots/
  findings.md
  logs/

失敗時の成果物

テストが失敗した場合は、デバッグに役立つ情報をすべて保持します。

• スクリーンショット — Detox が失敗時に自動でキャプチャします
• デバイスログ — xcrun simctl spawn booted log stream --level error
• コンソール出力 — テストランナーからの出力
• Sentry — Sentry が設定されている場合はクラッシュレポートを確認します

並列シミュレーターの分離

シミュレーターを必要とする複数のスウォーム／エージェントを一晩実行する場合、それぞれが個別に次を使用する必要があります。

# Create a named simulator for this agent
xcrun simctl create "Swarm-1" "iPhone 16"
# Returns a UDID like: 4A2B3C4D-5E6F-7890-ABCD-EF1234567890

# Boot it
xcrun simctl boot <UDID>

# Build and install targeting that specific simulator
xcrun simctl install <UDID> ios/build/Build/Products/Debug-iphonesimulator/<AppName>.app
xcrun simctl launch <UDID> <bundleId>

Detox では、.detoxrc.js でデバイス名を指定して対象デバイスを設定します。

devices: {
  simulator: {
    type: 'ios.simulator',
    device: { type: 'iPhone 16', name: 'Swarm-1' }
  }
}

実行後のクリーンアップ：

xcrun simctl delete <UDID>

トラブルシューティング

問題	対処方法
No bundle URL present	先に別のターミナルで npx expo start を実行します
パッケージ追加後にビルドが失敗する	npx expo prebuild --platform ios --clean を実行してから再ビルドします
シミュレーターが見つからない	xcrun simctl list devices available を実行して、起動済みのデバイスを確認します
Detox がタイムアウトする	.detoxrc.js のタイムアウトを延長し、testID が不足していないか確認します
EAS ビルドキューが遅い	シミュレーターのテストにはローカルビルドを、デバイスでの共有には EAS を使用します
xcrun simctl install が失敗する	.app のパスを確認します。Debug か Release か、シミュレーター用か実機用かを確認してください

注意点

• Detox には開発ビルドが必要です。Expo Go ではありません。 Expo Go は、Detox が必要とするネイティブモジュールやカスタムの開発クライアント設定をサポートしていません。Detox のテストには、必ず npx expo prebuild と xcodebuild を使用してください。
• iPad と iPhone ではシミュレーターのサイズが異なるため、注意が必要です。 iPhone で合格する Detox テストでも、レイアウトの違い（スプリットビューや大きな画面）により、iPad では失敗することがあります。本番環境で対象とするシミュレーターと同じ種類を使って、必ずテストしてください。
• EAS ビルドには時間がかかるため、早めに開始してください。 クラウドビルドには 10〜20 分かかることがあります。CI の完了を待たず、他の作業と並行して EAS ビルドを開始してください。
• EAS の QR コードには有効期限があります。 PR でプレビュービルドの QR コードを共有しても、ビルド成果物がクリーンアップされると期限切れになります。ビルドから数日以上経過している場合は、新しい QR コードを投稿してください。
• npx expo run:ios --device には、デバイスを有線接続する必要があります。 デバイスを USB で物理的に接続し、信頼する必要があります。初回インストールでは、ワイヤレスデバッグは安定しません。
• シミュレーターを起動せずに「合格」した Detox テストは、実際には何もテストしていません。 Detox の結果を信頼する前に、シミュレーターが起動していて、アプリがインストールされていることを必ず確認してください。ログに「No simulators found」と表示されていないか確認してください。
• シミュレーターでは、オーディオやメディア機能が動作しません。 マイク、スピーカー、一部のメディア API は、シミュレーターでは挙動が異なるか、まったく動作しない場合があります。これらは実機でテストしてください。
• 並列スウォームでは、シミュレーターを分離する必要があります。 2 つのエージェントが booted を使うと、同じシミュレーターを奪い合います。エージェントごとに名前付きシミュレーターを作成してください（上記の「Parallel Simulator Isolation」セクションを参照）。
• ローカルビルドと EAS ビルドでは、署名方法が異なります。 xcrun simctl install でインストールするローカルビルドでは、シミュレーター用の署名が使われます。EAS のプレビュービルドでは、プロビジョニングプロファイルを使ったアドホック署名が使われます。混同しないでください。必要なデバイスがそれぞれ異なります。