mobile-testing

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.

2. 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.

3. 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.

4. 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.

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

6. 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).

Mobile-Specific Testing Patterns

These scenarios cannot be tested by web frameworks. Treat each as a first-class flow.

• Deep links — cold start (terminate then deep-link), authenticated redirect, and running-app navigation.
• Push notifications — Detox sendUserNotification (iOS) and Appium + FCM test-endpoint / notification-shade patterns (Android).
• Offline / poor network — platform-guarded: Android mobile: shell airplane-mode, device-farm network profiles, iOS conditioner / Detox proxy notes.
• Permission dialogs — autoGrantPermissions (Android), explicit mobile: alert (action: accept/dismiss) and -ios predicate string handling (iOS).
• Biometrics — Detox setBiometricEnrollment(true) then matchBiometric() (enroll before match).
• App lifecycle — background/foreground, cold start, fresh install vs. resume.

See references/mobile-patterns.md for the runnable code, including the platform-guarded airplane-mode snippet and the iOS-vs-Android permission split.

Anti-Patterns

Running all tests on emulators only. Emulators do not reproduce touch latency, camera behavior, GPS drift, or push timing. Use emulators for development velocity; run release suites on real devices via a device farm.

Hardcoded device names in tests. await driver.$('Samsung Galaxy S24 - Home') breaks when the device changes. Use accessibility IDs and platform-agnostic selectors.

Platform-specific commands with no platform check. cmd connectivity airplane-mode only exists on newer Android and not at all on iOS; firing it unguarded fails silently on the other platform. Branch on platformName first (see Appium 3.x).

Ignoring app permissions. Tests that assume permissions are pre-granted fail on first install or when testing denial flows. Handle permissions explicitly per platform.

Matching a biometric without enrolling it. matchBiometric() with no prior setBiometricEnrollment(true) is a no-op; the auth never completes and the test times out on the login screen.

Testing only portrait orientation. Many apps break in landscape. Test critical flows in both orientations, especially on tablets.

Skipping offline scenarios. Mobile users lose connectivity constantly. If the app does not handle offline gracefully, prove it; if it does, verify the behavior.

Using sleep() instead of framework synchronization. Detox auto-waits; Appium has implicit and explicit waits. Sleep-based synchronization is slow and flaky on both.

Ignoring app size and startup time. A 200MB app with a 6-second cold start is a real UX issue. Include non-functional checks for binary size and launch time. (For deep startup/memory/battery profiling, use performance-testing.)

Verification

Run the smallest check for whichever framework you set up; each should exit 0 and print the expected output before you call the suite done.

# Appium: drivers installed and server reachable
appium driver list --installed        # lists uiautomator2 and/or xcuitest
appium --version                       # prints the 3.x version

# Detox: one config builds and a smoke spec passes
detox test --configuration ios.sim.debug --headless   # green run on the iOS simulator

# Maestro: a single flow runs end-to-end
maestro test flows/login.yaml          # prints "Flow Passed"

Done When

• Device matrix defined and committed (e.g. device-matrix.md or a CI matrix block): real devices + emulators per platform, tiered P0/P1/P2 from analytics.
• Test suite runs against both iOS and Android from a single CI configuration (matrix strategy or paired jobs).
• A gesture test (swipe/scroll/long-press) and a deep-link cold-start test (terminate → deep-link → assert target screen) exist as committed test files — list their paths.
• Push notification coverage is either a committed test file path OR a tracked deferral ticket ID (e.g. "JIRA-1234: deferred until FCM test endpoint available") — not a bare code comment.
• appium driver list --installed / detox test --configuration ios.sim.debug / maestro test flows/login.yaml (whichever applies) exits 0 locally.
• CI runs tests on at least one emulator per platform (iOS simulator + Android emulator) on every PR, with real-device-farm runs gated to nightly or release branches.

Reference Files (in references/)

• appium-patterns.md — Appium 3.x install, W3C capabilities, element-location strategies, gesture simulation, and the platform-guard pattern.
• detox-and-maestro.md — Detox .detoxrc.js config, test patterns, device APIs (biometric ordering, push iOS-only note), CI commands; plus Maestro install (brew + curl) and YAML flow.
• device-farm.md — BrowserStack and Sauce Labs capabilities, authenticated app-upload curl, and the GitHub Actions P0/P1/P2 device matrix.
• mobile-patterns.md — Runnable code for deep links, push, platform-guarded network simulation, iOS/Android permission dialogs, and app lifecycle.

Related Skills

• ci-cd-integration — Pipeline configuration for mobile test execution, artifact management, device-farm CI connectors.
• cross-browser-testing — Device-matrix design borrows the browser-matrix methodology; go there for matrix strategy in the abstract, here for the mobile execution.
• performance-testing — Mobile non-functional depth: app startup time, memory usage, battery drain.
• visual-testing — Screenshot/pixel-diff regression, including mobile viewport captures.
• test-data-management — Seed data strategies for mobile apps; backend state setup via API.
• test-reliability — Runtime flaky-test healing for mobile timing, device state, and network conditions.