Back to Details

mobile-testing

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
<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>
<objective> 某个登录测试在iOS模拟器上能通过，但在真机上却一直卡住，原因是屏幕上存在一个未被处理的位置权限弹窗——这正是本技能要避免的移动测试失败场景。本技能针对原生、React Native、混合及Flutter应用，根据应用类型选择合适的框架，区分真机与模拟器层级，为Web框架无法覆盖的场景提供一流的处理方案：深度链接、推送通知、生物识别、离线状态及权限弹窗。 </objective>

Quick Route

快速指引

SituationGo to
Picking a framework for an app typeFramework Decision
Native/hybrid Appium setup + selectors + gesturesAppium 3.x → 
references/appium-patterns.md
React Native suiteDetox → 
references/detox-and-maestro.md
Low-friction cross-platform YAMLMaestro → 
references/detox-and-maestro.md
Cloud device matrix (P0/P1/P2)Device Farm → 
references/device-farm.md
Deep links, push, biometrics, offline, permissionsMobile-Specific Patterns → 
references/mobile-patterns.md
场景跳转至
为应用类型选择框架框架选择
原生/混合应用的Appium配置 + 选择器 + 手势Appium 3.x → 
references/appium-patterns.md
React Native测试套件Detox → 
references/detox-and-maestro.md
低门槛跨平台YAML方案Maestro → 
references/detox-and-maestro.md
云端设备矩阵（P0/P1/P2）设备农场 → 
references/device-farm.md
深度链接、推送、生物识别、离线、权限弹窗移动端专属测试模式 → 
references/mobile-patterns.md

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.
先查看项目根目录下的
.agents/qa-project-context.md
——如果存在，使用该文件并跳过已回答的问题。
  1. 应用类型：原生iOS/Android、React Native、Flutter还是混合应用（Cordova/Capacitor）？这将决定框架选择（见框架选择）。
  2. 使用真机还是模拟器？ 真机用于发布验证和性能测试；模拟器/模拟器用于提升开发速度。大多数团队需要两者兼顾。
  3. 设备农场：BrowserStack App Automate、Sauce Labs、AWS Device Farm还是自托管？预算和CI集成方式决定选择。
  4. 系统版本覆盖：最低支持的iOS和Android版本是多少？在构建设备矩阵前先分析实际用户分布数据——不要默认只针对最新硬件。
  5. 现有CI流水线：移动测试运行在何处——本地机器、带模拟器的CI runner还是云端设备农场？
  6. 应用分发方式：测试包如何分发——TestFlight、Firebase App Distribution、直接APK/IPA？这决定了设备农场获取安装包的方式。

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.
  1. 真机用于发布验证，模拟器用于开发提速。模拟器无法模拟触摸延迟、GPS漂移、相机异常、推送通知时序及电池行为。开发阶段和PR检查使用模拟器；夜间构建和发布流水线保留真机农场。
  2. 手势模拟因框架而异。Appium W3C Actions、Detox设备API及平台原生手势识别器对滑动、捏合、长按的处理方式各不相同。不要假设跨框架可移植性。
  3. 深度链接与推送通知是移动端独有特性。Web测试框架无法覆盖这些场景。每种场景都有专门的测试模式——将它们视为一等测试场景，而非事后补充。
  4. 权限弹窗会打破测试假设。iOS和Android对运行时权限的处理方式不同。相机、位置、通讯录及通知权限需要在配置中显式处理，否则测试会因等待无法关闭的弹窗而卡住。
  5. 网络条件对移动端影响更大。用户会在WiFi、LTE、3G及离线状态间切换。测试降级网络和无网络场景——不要只测试理想的WiFi环境。
  6. 任何平台专属操作都需要平台判断。在Android上可用的shell命令、选择器或设备API可能在iOS上不存在（反之亦然）。执行平台专属命令前需基于
    platformName
    分支处理，否则测试会在另一平台静默失败。

Framework Decision

框架选择

App typePrimary choiceWhy
Native iOS/Android, hybridAppium 3.xDriver-based, mature ecosystem, deepest native + gesture coverage
React NativeDetoxGray-box, synchronizes with the RN bridge, fastest feedback, least flake
Cross-platform, mixed-skill teamMaestroDeclarative YAML, native AI commands, lowest authoring friction
FlutterPatrol 4.xFlutter-native integration testing; 4.0 added web support (via Playwright) and richer native interaction APIs
应用类型首选框架原因
原生iOS/Android、混合应用Appium 3.x基于驱动的架构，生态成熟，对原生功能和手势的覆盖最全面
React NativeDetox灰盒测试框架，与RN桥同步，反馈速度最快，测试最稳定
跨平台、多技能团队Maestro声明式YAML流程，原生AI辅助命令（无需选择器即可实现
assertVisible: 'login button'
），支持模拟器、真机及Maestro Cloud
FlutterPatrol 4.xFlutter原生集成测试；4.0版本新增Web支持（基于Playwright）及更丰富的原生交互API

Appium 3.x

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:
typescript
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).
Appium 3.x（当前稳定版本，2026年）保留了2.0版本引入的基于驱动的插件架构——服务器是轻量化外壳，驱动提供平台专属自动化能力。从2.x升级主要是Node版本升级和依赖清理；大多数配置项可兼容，但Appium 3.x移除了多个长期废弃的命令并修改了插件/驱动的处理方式，因此请查看3.x迁移说明以了解已移除的旧命令。
选择器优先级：Accessibility ID > 平台专属选择器（iOS类链/Android UIAutomator） > XPath（最后选择——速度慢、易失效）。
平台专属命令需加判断。执行任何平台专属的shell命令、选择器策略或设备API前，需基于
platformName
分支处理：
typescript
if (driver.capabilities.platformName === 'Android') {
  // UIAutomator选择器、`mobile: shell`网络切换
} else {
  // iOS类链/谓词选择器、`mobile: alert`、设备农场网络配置
}
查看
references/appium-patterns.md
获取安装/驱动命令、W3C Android/iOS配置项、四种元素定位策略及完整手势集合（滚动、滑动、捏合、长按、双击）。

Detox for React Native

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.
Detox是一款灰盒测试框架。它与React Native桥同步，等待动画、网络请求和定时器完成后再执行操作——这消除了大多数时序相关的不稳定问题。
Detox支持React Native 0.77–0.84版本，包括新架构。默认使用
by.id
/
by.text
匹配器；仅在需要放松严格的类断言时使用
by.type()
。
生物识别操作顺序规则：调用
device.matchBiometric()
之前，需先通过
device.setBiometricEnrollment(true)
录入生物识别信息。未录入直接匹配不会生效，认证流程无法推进。
推送通知仅iOS支持
sendUserNotification
。在Android上，Detox的推送处理能力有限，
sendUserNotification
行为与iOS不同——请通过FCM/通知栏（Appium模式）处理Android推送，不要假设跨平台一致性。
查看
references/detox-and-maestro.md
获取
.detoxrc.js
配置、登录流测试模式、设备API（生物识别、摇一摇、屏幕旋转、定位、深度链接、通知）及CI构建/测试命令。

Maestro (Cross-Platform YAML)

Maestro（跨平台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.
bash
undefined
Maestro CLI 2.5.x（2026年4月）是跨平台移动端端到端测试的低门槛选择——声明式YAML流程、原生AI辅助命令（无需选择器即可实现
assertVisible: 'login button'
），支持模拟器、真机及Maestro Cloud。最适合不想使用Appium的Java/JS栈或仅支持RN的Detox工具的团队。
bash
undefined

macOS (preferred — lower friction, brew-managed):

macOS（推荐——门槛低，由brew管理）:

brew tap mobile-dev-inc/tap && brew install mobile-dev-inc/tap/maestro
brew tap mobile-dev-inc/tap && brew install mobile-dev-inc/tap/maestro

Or the cross-platform curl one-liner:

或跨平台curl一键安装:

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

---
curl -Ls "https://get.maestro.mobile.dev" | bash

选择Maestro的场景：跨平台测试套件、多技能团队、快速迭代。不选择的场景：需要深度原生手势或生物识别覆盖（Appium/Detox更优），或需要细粒度的编程控制。

查看`references/detox-and-maestro.md`获取带注释的登录流YAML（支持`${MAESTRO_TEST_PASSWORD}`环境变量注入）。

---

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).
基于用户分析数据而非最新硬件来构建分层设备矩阵。典型比例：60%的测试在P0设备上，30%在P1设备，10%在P2设备。测试应用上传至设备农场后，通过配置项（
app
URL / 
storage:filename
）引用。
查看
references/device-farm.md
获取BrowserStack和Sauce Labs的配置对象、带认证的应用上传curl命令，以及GitHub Actions的设备矩阵策略（iOS和Android的P0/P1/P2分层）。

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.
这些场景无法通过Web框架测试。将每个场景视为一等测试流程。
  • 深度链接——冷启动（终止应用后打开深度链接）、认证重定向及运行中应用导航。
  • 推送通知——Detox的
    sendUserNotification
    （iOS）和Appium + FCM测试端点/通知栏模式（Android）。
  • 离线/弱网——平台专属处理：Android使用
    mobile: shell
    开启飞行模式、设备农场网络配置；iOS使用调试工具/Detox代理。
  • 权限弹窗——Android使用
    autoGrantPermissions
    ，iOS显式处理
    mobile: alert
    （
    action: accept
    /
    dismiss
    ）和
    -ios predicate string
    。
  • 生物识别——Detox先执行
    setBiometricEnrollment(true)
    再执行
    matchBiometric()
    （先录入再匹配）。
  • 应用生命周期——后台/前台切换、冷启动、全新安装与恢复运行。
查看
references/mobile-patterns.md
获取可运行代码，包括平台专属的飞行模式代码片段及iOS与Android权限处理的差异。

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
.)
所有测试仅在模拟器上运行。模拟器无法复现触摸延迟、相机行为、GPS漂移或推送时序。模拟器用于提升开发速度；发布测试套件需通过设备农场在真机上运行。
测试中硬编码设备名称。
await driver.$('Samsung Galaxy S24 - Home')
会在设备更换时失效。使用Accessibility ID和平台无关的选择器。
执行平台专属命令但未做平台判断。
cmd connectivity airplane-mode
仅在较新的Android版本上可用，在iOS上完全不存在；无判断执行会在另一平台静默失败。需先基于
platformName
分支处理（见Appium 3.x）。
忽略应用权限。假设权限已预先授予的测试会在首次安装或测试拒绝流程时失败。需按平台显式处理权限。
未录入生物识别信息就直接匹配。未执行
setBiometricEnrollment(true)
就调用
matchBiometric()
不会生效；认证无法完成，测试会在登录页面超时。
仅测试竖屏方向。许多应用在横屏模式下会出现问题。测试关键流程的横竖屏两种模式，尤其是平板设备。
跳过离线场景测试。移动用户经常会失去网络连接。如果应用无法优雅处理离线状态，需验证该问题；如果可以处理，也需验证其行为。
使用
sleep()
而非框架同步机制。Detox会自动等待；Appium有隐式和显式等待。基于sleep的同步机制速度慢且不稳定。
忽略应用大小和启动时间。200MB的应用冷启动需要6秒是真实的UX问题。需包含应用包大小和启动时间的非功能性检查。（如需深度的启动/内存/电池分析，请使用
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.
bash
undefined
针对你所配置的框架运行最小化检查；在完成测试套件前，每个检查都应返回0并打印预期输出。
bash
undefined

Appium: drivers installed and server reachable

Appium：驱动已安装且服务器可访问

appium driver list --installed # lists uiautomator2 and/or xcuitest appium --version # prints the 3.x version
appium driver list --installed # 列出uiautomator2和/或xcuitest appium --version # 打印3.x版本号

Detox: one config builds and a smoke spec passes

Detox：配置可构建且冒烟测试通过

detox test --configuration ios.sim.debug --headless # green run on the iOS simulator
detox test --configuration ios.sim.debug --headless # iOS模拟器上运行成功

Maestro: a single flow runs end-to-end

Maestro：单个流程可完整运行

maestro test flows/login.yaml # prints "Flow Passed"

---
maestro test flows/login.yaml # 打印"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.
  • 设备矩阵已定义并提交（例如
    device-matrix.md
    或CI矩阵块）：每个平台包含真机+模拟器，基于用户分析分为P0/P1/P2层级。
  • 测试套件可通过单一CI配置同时运行在iOS和Android上（矩阵策略或配对任务）。
  • 已提交手势测试（滑动/滚动/长按）和深度链接冷启动测试（终止应用→打开深度链接→断言目标页面）的测试文件——列出文件路径。
  • 推送通知覆盖已提交测试文件路径或跟踪的延迟工单ID（例如"JIRA-1234：延迟至FCM测试端点可用"）——并非仅代码注释。
  • 本地执行
    appium driver list --installed
    / 
    detox test --configuration ios.sim.debug
    / 
    maestro test flows/login.yaml
    （对应所使用的框架）返回0。
  • CI在每个PR上至少运行一个平台的模拟器测试（iOS模拟器+Android模拟器），真机农场测试仅在夜间构建或发布分支触发。

Reference Files (in 
references/
)

参考文件（位于
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.
  • appium-patterns.md —— Appium 3.x安装、W3C配置项、元素定位策略、手势模拟及平台判断模式。
  • detox-and-maestro.md —— Detox的
    .detoxrc.js
    配置、测试模式、设备API（生物识别顺序、iOS专属推送说明）、CI命令；以及Maestro的安装（brew+curl）和YAML流程。
  • device-farm.md —— BrowserStack和Sauce Labs的配置项、带认证的应用上传curl命令，以及GitHub Actions的P0/P1/P2设备矩阵。
  • mobile-patterns.md —— 深度链接、推送通知、平台专属网络模拟、iOS/Android权限弹窗及应用生命周期的可运行代码。

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.
  • ci-cd-integration —— 移动测试执行的流水线配置、制品管理、设备农场CI连接器。
  • cross-browser-testing —— 设备矩阵设计借鉴浏览器矩阵方法论；如需抽象的矩阵策略请使用该技能，本技能专注于移动端执行。
  • performance-testing —— 移动端非功能性深度测试：应用启动时间、内存占用、电池消耗。
  • visual-testing —— 截图/像素对比回归测试，包括移动端视口捕获。
  • test-data-management —— 移动应用的测试数据填充策略；通过API设置后端状态。
  • test-reliability —— 移动端时序、设备状态及网络条件相关的不稳定测试修复。