Mobile Testing

<objective> A login test that passes on the iOS simulator but hangs forever on a real device because a location-permission dialog it never accounted for is sitting on top of the screen — that is the mobile failure mode this skill prevents. It delivers a runnable suite across native, React Native, hybrid, and Flutter apps with the right framework per app type, real-device-vs-emulator tiers, and first-class handling for the scenarios web frameworks cannot reach: deep links, push, biometrics, offline, and permission dialogs. </objective>

Quick Route

Discovery Questions

Check .agents/qa-project-context.md in the project root first — if it exists, use it and skip any question it already answers.

1. App type: Native iOS/Android, React Native, Flutter, or hybrid (Cordova/Capacitor)? This picks the framework (see Framework Decision).
2. Real devices or emulators? Real devices for release validation and performance; emulators/simulators for development speed. Most teams need both.
3. Device farm: BrowserStack App Automate, Sauce Labs, AWS Device Farm, or self-hosted? Budget and CI integration decide.
4. OS coverage: Minimum iOS and Android versions? Read analytics for actual user distribution before building the matrix — do not target the newest hardware by default.
5. Existing CI pipeline: Where do mobile tests run — local machines, CI runners with emulators, or cloud device farms?
6. App distribution: How are test builds distributed — TestFlight, Firebase App Distribution, direct APK/IPA? This determines how the farm gets the binary.

Core Principles

1. Real devices for release, emulators for speed. Emulators miss touch latency, GPS drift, camera quirks, push notification timing, and battery behavior. Use emulators in development and PR checks; reserve real device farms for nightly and release pipelines.

1. Gesture simulation is framework-specific. Appium W3C Actions, Detox device APIs, and platform-native gesture recognizers each handle swipes, pinches, and long-presses differently. Do not assume cross-framework portability.

1. Deep links and push notifications are unique to mobile. Web testing frameworks cannot reach them. Dedicated patterns exist for each — treat them as first-class scenarios, not afterthoughts.

1. Permission dialogs break assumptions. iOS and Android handle runtime permissions differently. Camera, location, contacts, and notification permissions need explicit handling in setup or the test hangs waiting for a dialog it cannot dismiss.

1. Network conditions matter more on mobile. Users switch between WiFi, LTE, 3G, and offline. Test degraded and absent connectivity — not just happy-path WiFi.

1. Anything platform-specific needs a platform guard. A shell command, selector, or device API that works on Android may not exist on iOS (and vice versa). Branch on platformName before issuing platform-specific commands, or the test fails silently on the other platform.

Framework Decision

Appium 3.x

Appium 3.x (current stable line, 2026) keeps the driver-based plugin architecture introduced in 2.0 — the server is a thin shell; drivers provide platform-specific automation. Upgrade from 2.x is mostly a Node-version bump and dependency cleanup; most capabilities carry over, but Appium 3 dropped several long-deprecated commands and changed plugin/driver handling, so check the 3.x migration notes for removed legacy commands.

Selector priority: Accessibility ID > platform-specific selector (iOS class chain / Android UIAutomator) > XPath (last resort — slow, brittle).

Guard platform-specific commands. Branch on platformName before any platform-only shell command, selector strategy, or device API:

if (driver.capabilities.platformName === 'Android') {
  // UIAutomator selectors, `mobile: shell` network toggles
} else {
  // iOS class chain / predicate selectors, `mobile: alert`, device-farm network profiles
}

See references/appium-patterns.md for install/driver commands, W3C Android/iOS capabilities, the four element-location strategies, and the full gesture set (scroll, swipe, pinch, long-press, double-tap).

Detox for React Native

Detox is a gray-box framework. It synchronizes with the React Native bridge, waiting for animations, network requests, and timers to settle before acting — this eliminates most timing flakiness.

Detox supports React Native 0.77–0.84, including the New Architecture. Use by.id/by.text matchers as the default; reach for by.type() only to relax a brittle exact-class assertion.

Biometric ordering rule: enroll the biometric with device.setBiometricEnrollment(true) before calling device.matchBiometric(). Matching without prior enrollment is a no-op and the auth flow never advances.

Push notifications are iOS-only via `sendUserNotification`. On Android, Detox push handling is limited and sendUserNotification behavior differs — drive Android push through FCM/the notification shade (Appium pattern) instead of assuming parity.

See references/detox-and-maestro.md for the .detoxrc.js config, login-flow test patterns, device APIs (biometric, shake, orientation, location, deep link, notifications), and CI build/test commands.

Maestro (Cross-Platform YAML)

Maestro CLI 2.5.x (Apr 2026) is the lowest-friction option for cross-platform mobile e2e — declarative YAML flows, native AI-assisted commands (assertVisible: 'login button' works without selectors), running against simulators, real devices, and Maestro Cloud. Best for teams that don't want Appium's Java/JS stack or RN-only Detox tooling.

# macOS (preferred — lower friction, brew-managed):
brew tap mobile-dev-inc/tap && brew install mobile-dev-inc/tap/maestro
# Or the cross-platform curl one-liner:
curl -Ls "https://get.maestro.mobile.dev" | bash

When to choose Maestro: cross-platform suite, mixed-skill team, fast iteration. When not: deep native gesture or biometric coverage (Appium/Detox win), or when you need fine-grained programmatic control.

See references/detox-and-maestro.md for an annotated login flow YAML (with ${MAESTRO_TEST_PASSWORD} env-var injection).

Device Farm Integration

Provision a tiered device matrix from analytics, not from the newest hardware. Typical split: 60% of tests on P0 devices, 30% on P1, 10% on P2. Test apps are uploaded to the farm and referenced by capability (app URL / storage:filename).

See references/device-farm.md for BrowserStack and Sauce Labs capability objects, the authenticated app-upload curl, and the GitHub Actions device-matrix strategy (P0/P1/P2 across iOS and Android).