capacitor-testing

Capacitor アプリとプラグインのテスト

Capacitor アプリには、テスト対象となる 3 つのレイヤーがあります。Web アプリ（大半のロジック）、ネイティブブリッジとプラグイン（Swift/Kotlin）、そしてデバイス上で実行中のアプリです。バグを検出できる最も低コストのレイヤーを選んでください。

使用する場面

次の場合に使用します：

• Capacitor アプリにユニットテスト、コンポーネントテスト、または E2E テストを追加する
• Vitest / Jest で Capacitor またはプラグイン API をモックする
• プラグインのネイティブユニットテスト（Swift Testing、XCTest、JUnit）を作成または最新化する
• シミュレーター、エミュレーター、またはデバイスで変更を検証する（「これをテストして」「動作する？」「デバイスで確認して」）
• E2E テストでアプリ内の Web 要素を検出できない（WebView コンテキスト）
• CI でテストジョブを設定する

次の場合は使用しないでください：

• デバイスログまたはクラッシュログの読み取り：ios-android-logs
• Safari Web Inspector / Chrome DevTools を使ったデバッグ：debugging-capacitor
• ビルド、署名、リリースのパイプライン：capacitor-ci-cd
• App Intents のテスト：capacitor-app-intents（AppIntentsTesting）

レイヤーを選ぶ

変更内容	テスト方法	リファレンス
ビジネスロジック、状態、プラグインを呼び出すサービス	プラグインをモックした Vitest	references/web-unit-tests.md
コンポーネント（React、Vue、Angular、Svelte）	Vitest 上の Testing Library	references/web-unit-tests.md
Web フロー（ルーティング、フォーム）	開発サーバーまたは dist に対する Playwright	references/e2e.md
プラグインのネイティブコード（Swift / Kotlin）	Swift Testing または XCTest、JUnit	references/native-plugin-tests.md
デバイス上のアプリ全体、ネイティブ UI、権限、ディープリンク	エージェントによる検証ループ。繰り返し実行できるテストスイートには Appium または Maestro	references/device-verification-loop.md、references/e2e.md
CI ジョブ	GitHub Actions のマトリックス	references/ci.md

対象レイヤーを使用するときだけ、リファレンスを読み込んでください。

時間を節約するための知識

• jsdom で実行されるプラグインは、Web 実装を使用します。Web 実装がない場合は unimplemented をスローします。テストで @capacitor/core をモックしない限り、Capacitor.isNativePlatform() は false を返します。アプリの奥深くではなく、プラグインパッケージの境界でモックしてください。
• E2E ツールからは、WebView は 1 つのネイティブ要素として認識されます。 DOM 要素を見つけるには、Appium で WEBVIEW_* コンテキストに切り替える必要があります。Capacitor ではデバッグビルドで WebView を検査できます。リリースビルドで検査を有効にするには、capacitor.config で ios.webContentsDebuggingEnabled / android.webContentsDebuggingEnabled を設定します。有効なままリリースビルドを誤って出荷しないでください。
• Detox は使用できません。 React Native を対象としており、Capacitor の WebView コンテンツは操作できません。
• Swift Testing は XCTest のすべてを置き換えられるわけではありません。 UI テスト（XCUIApplication）と measure {} によるパフォーマンステストは XCTest のままです。ユニットテストはクラスごとに移行できます。1 つのファイルに両方を含めることもできます。
• iOS 専用のプラグインパッケージは、UIKit と Capacitor に依存するため swift test を使用できません。 xcodebuild test -scheme <Package> -destination 'platform=iOS Simulator,...' を実行してください。
• Capacitor 9 では、非推奨の Swift API が削除されました。 古い CAPPluginCall(callbackId:options:success:error:) イニシャライザー、または CAPPlugin(bridge:pluginId:pluginName:) を使って呼び出しを構築するテストは、CAPPluginCall(callbackId:methodName:options:success:error:) と通常の init() に移行する必要があります。
• Capacitor 9 では、ライブリロードのフラグが変更されました。 Capacitor 9：npx cap run ios --url http://<lan-ip>:5173。Capacitor 8：npx cap run ios -l --host <lan-ip> --port 5173。Ionic CLI の ionic cap run ios -l --external は別のツールです。

ワークフロー

1. 確認します。 package.json（テストランナー、フレームワーク、@capacitor/* のバージョン）、capacitor.config.*、既存のテスト設定（vitest.config.*、playwright.config.*、wdio.conf.*、.maestro/）を読み、プラグインの場合は Package.swift、podspec、ios/Tests/、android/src/test/ も確認します。
2. リクエストが一般的な内容の場合は、どのレイヤーを対象にするかユーザーに確認します。リスクをカバーできる、最も低コストの方法を提案します。
3. 対応するリファレンスに沿ってテストを作成します。プロジェクトで既に使われているランナーとスタイルに従い、別のランナーは追加しないでください。
4. テストを実行し、出力を示します。一度も実行していないテストは未完了です。
5. UI に影響する変更の場合は、デバイス検証ループ（references/device-verification-loop.md）を実行し、スクリーンショットと確認結果を報告します。

検証

# Web layer
npx vitest run
npx playwright test

# Plugin, iOS (from the plugin repo)
xcodebuild test -scheme <PluginPackageName> \
  -destination "platform=iOS Simulator,name=$(xcrun simctl list devices available | grep -m1 -o 'iPhone [^(]*' | sed 's/ *$//')"

# Plugin, Android (from the plugin repo)
cd android && ./gradlew test

# App native tests, if the app has a test target
xcodebuild test -project ios/App/App.xcodeproj -scheme App -destination 'platform=iOS Simulator,name=<device>'
# CocoaPods projects: -workspace ios/App/App.xcworkspace

報告する内容：追加したテスト、実行したコマンド、成功／失敗の件数、ローカルで実行できなかった項目（シミュレーターやデバイスがない、Android SDK がないなど）。

エラー処理

症状	原因	対処方法
Vitest で "<Plugin>" plugin is not implemented on web が発生する	jsdom で実際のプラグインが実行されている	セットアップファイルで vi.mock('<plugin package>') を使います
モックが無視され、実際のプラグインが呼び出される	モックのパスがインポートパスと異なる、またはインポート後にモックが登録されている	アプリがインポートするものと完全に同じ指定子をモックします。setupFiles またはテストファイルの先頭に vi.mock を記述します
Appium が data-testid 要素を見つけられない	NATIVE_APP コンテキストのままになっている	getContexts() に WEBVIEW_* エントリが含まれるまで待ってから、await driver.switchContext(webviewContext) を実行します
WEBVIEW_* コンテキストがない	WebView を検査できない（リリースビルド）	デバッグビルドを使うか、テストビルドでのみ webContentsDebuggingEnabled を有効にします
Android WebView コンテキストで chromedriver のバージョンエラーが発生する	chromedriver がデバイスの WebView と一致していない	Appium の chromedriver 自動ダウンロード（安全でない機能フラグ）を有効にするか、一致する chromedriver を固定します。Appium UiAutomator2 のドキュメントを確認してください
No such module 'Testing'	古い Xcode	Swift Testing には Xcode 16 以降のツールチェーンが必要です。Capacitor 9 にはいずれにせよ Xcode 27 が必要です
swift test で error: no such module 'UIKit' が発生する	iOS パッケージを macOS ホスト向けにビルドしている	iOS Simulator の宛先を指定して xcodebuild test を使います
'init(callbackId:options:success:error:)' is deprecated／使用できない	古いテストヘルパー	methodName: を追加します
ライブリロードで error: unknown option '-l' が発生する	Capacitor 9 CLI	--url http://<lan-ip>:<port> を使います
ライブリロードしたアプリに何も表示されない	開発サーバーが localhost にバインドされている、または IP が誤っている	0.0.0.0 にバインドし（Vite の場合は --host）、LAN IP を使い、同じ Wi-Fi に接続します

関連スキル

• debugging-capacitor：WebView とネイティブデバッガーを確認します
• ios-android-logs：デバイス実行中にログをストリーミングします
• capacitor-ci-cd：ビルドとリリースのパイプライン
• capacitor-ios-resizability：デバイス実行中にサイズ変更されたウィンドウで確認する項目
• capacitor-plugin-upgrade-v8-to-v9：テストヘルパーに影響するプラグイン API の削除