capacitor-testing

Testing Capacitor Apps and Plugins

A Capacitor app has three layers to test: the web app (most logic), the native bridge and plugins (Swift/Kotlin), and the running app on a device. Pick the cheapest layer that can catch the bug.

When to Use

TRIGGER when:

• Adding unit, component or E2E tests to a Capacitor app
• Mocking Capacitor or plugin APIs in Vitest / Jest
• Writing or modernizing native unit tests for a plugin (Swift Testing, XCTest, JUnit)
• Verifying a change on a simulator, emulator or device ("test this", "does it work", "check on device")
• E2E tests that cannot find web elements in the app (WebView context)
• Setting up test jobs in CI

Do not use:

• Reading device or crash logs: ios-android-logs
• Safari Web Inspector / Chrome DevTools debugging: debugging-capacitor
• Build, signing and release pipelines: capacitor-ci-cd
• App Intents tests: capacitor-app-intents (AppIntentsTesting)

Choose the layer

What changed	Test with	Reference
Business logic, state, services that call plugins	Vitest with mocked plugins	references/web-unit-tests.md
Components (React, Vue, Angular, Svelte)	Testing Library on Vitest	references/web-unit-tests.md
Web flows (routing, forms)	Playwright against the dev server or dist	references/e2e.md
Plugin native code (Swift / Kotlin)	Swift Testing or XCTest; JUnit	references/native-plugin-tests.md
Full app on device, native UI, permissions, deep links	Agent verification loop; Appium or Maestro for repeatable suites	references/device-verification-loop.md, references/e2e.md
CI jobs	GitHub Actions matrix	references/ci.md

Only load a reference when its layer is in play.

Facts that save time

• Plugins in jsdom run their web implementation, or throw unimplemented when there is none. Capacitor.isNativePlatform() returns false in tests unless you mock @capacitor/core. Mock at the plugin package boundary, not deep inside the app.
• E2E tools see the WebView as one native element. Appium must switch to the WEBVIEW_* context to find DOM elements. Capacitor makes the WebView inspectable in debug builds; for release builds set ios.webContentsDebuggingEnabled / android.webContentsDebuggingEnabled in capacitor.config. Never ship release builds with it on by accident.
• Detox is not an option. It targets React Native and does not drive Capacitor WebView content.
• Swift Testing cannot replace all XCTest. UI tests (XCUIApplication) and measure {} performance tests stay XCTest. Unit tests can migrate one class at a time; a file can hold both.
• iOS-only plugin packages cannot use swift test because they depend on UIKit and Capacitor. Run xcodebuild test -scheme <Package> -destination 'platform=iOS Simulator,...'.
• Capacitor 9 removed the deprecated Swift APIs. Tests that build calls with the old CAPPluginCall(callbackId:options:success:error:) initializer or CAPPlugin(bridge:pluginId:pluginName:) must move to CAPPluginCall(callbackId:methodName:options:success:error:) and a plain init().
• Live reload flags changed in 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. The Ionic CLI's ionic cap run ios -l --external is a different tool.