mobile-testing

一项在 iOS 模拟器上通过、却在真实设备上无限卡住的登录测试，原因是屏幕上弹出了它从未考虑过的位置权限对话框——这正是本技能要防止的移动端故障模式。它会根据应用类型选用合适的框架，为原生、React Native、混合式和 Flutter 应用提供可运行的测试套件，涵盖真实设备与模拟器测试层级，并优先支持 Web 框架无法触及的场景：深层链接、推送、生物识别、离线和权限对话框。

---

快速导航

情况	前往
为应用类型选择框架	框架选择
原生／混合式 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

---

探索问题

先检查项目根目录中的 .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 运行器，还是云端设备云平台？
6. 应用分发： 测试版本如何分发——TestFlight、Firebase App Distribution，还是直接分发 APK/IPA？这决定设备云平台如何获取二进制文件。

---

核心原则

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 分支处理，否则测试可能在另一平台上静默失败。

---

框架选择

应用类型	首选方案	原因
原生 iOS/Android、混合应用	Appium 3.x	基于驱动，生态成熟，对原生功能和手势的覆盖最全面
React Native	Detox	灰盒测试，与 RN 桥接层同步，反馈最快，最不易出现不稳定问题
跨平台、技能背景多样的团队	Maestro	声明式 YAML、原生 AI 命令、编写门槛最低
Flutter	Patrol 4.x	Flutter 原生集成测试；4.0 新增了 Web 支持（通过 Playwright）和更丰富的原生交互 API

---

Appium 3.x

Appium 3.x（当前稳定版本系列，2026 年）沿用了 2.0 引入的基于驱动的插件架构——服务本身只是一个轻量外壳；驱动负责提供特定平台的自动化能力。从 2.x 升级主要涉及升级 Node 版本和清理依赖；大多数 capabilities 都可以沿用，但 Appium 3 移除了若干长期弃用的命令，并更改了插件和驱动的处理方式，因此请查看 3.x 迁移说明，了解已移除的旧版命令。

选择器优先级： Accessibility ID > 平台专用选择器（iOS class chain / Android UIAutomator）> XPath（最后选择——速度慢且脆弱）。

对平台专用命令进行保护。 在执行任何平台专用 shell 命令、选择器策略或设备 API 前，根据 platformName 进行分支判断：

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

请参阅 references/appium-patterns.md，了解安装和驱动命令、W3C Android/iOS capabilities、四种元素定位策略，以及完整的手势集合（滚动、滑动、捏合、长按、双击）。

---

用于 React Native 的 Detox

Detox 是一个灰盒框架。它会与 React Native 桥接层同步，在执行操作前等待动画、网络请求和计时器稳定下来——这消除了大多数时序不稳定问题。

Detox 支持 React Native 0.77–0.84，包括新架构。默认使用 by.id/by.text 匹配器；只有在需要放宽脆弱的精确类断言时，才使用 by.type()。

生物识别顺序规则： 调用 device.matchBiometric() 之前，先通过 device.setBiometricEnrollment(true) 注册生物识别信息。未先注册就进行匹配将不起作用，身份验证流程也不会继续。

推送通知只能通过 sendUserNotification 在 iOS 上使用。 在 Android 上，Detox 的推送处理能力有限，且 sendUserNotification 的行为有所不同——应通过 FCM/通知栏（Appium 模式）驱动 Android 推送，而不要假定两者行为一致。

请参阅 references/detox-and-maestro.md，了解 .detoxrc.js 配置、登录流程测试模式、设备 API（生物识别、摇晃、方向、位置、深层链接、通知），以及 CI 构建和测试命令。

---

Maestro（跨平台 YAML）

Maestro CLI 2.5.x（2026 年 4 月）是跨平台移动端端到端测试中上手门槛最低的方案——提供声明式 YAML 工作流、原生 AI 辅助命令（无需选择器即可使用 assertVisible: 'login button'），并可在模拟器、真机和 Maestro Cloud 上运行。最适合不想使用 Appium 的 Java/JS 技术栈或仅适用于 RN 的 Detox 工具链的团队。

# 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

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

请参阅 references/detox-and-maestro.md，了解带注释的登录流程 YAML（通过 ${MAESTRO_TEST_PASSWORD} 环境变量注入密码）。

---

设备云集成

根据分析数据配置分层设备矩阵，而不是只选最新硬件。典型分配：60% 的测试在 P0 设备上运行，30% 在 P1 设备上运行，10% 在 P2 设备上运行。将测试应用上传到设备云，并通过 capability（app URL / storage:filename）引用。

请参阅 references/device-farm.md，了解 BrowserStack 和 Sauce Labs capability 对象、经过身份验证的应用上传 curl 命令，以及 GitHub Actions 设备矩阵策略（覆盖 iOS 和 Android 的 P0/P1/P2）。

---

移动端专属测试模式

这些场景无法通过 Web 框架测试。应将每个场景都视为一级流程。

• 深层链接 — 冷启动（终止应用后再打开深层链接）、已认证用户的重定向，以及运行中应用的导航。
• 推送通知 — Detox sendUserNotification（iOS），以及 Appium + FCM 测试端点／通知栏模式（Android）。
• 离线／网络不佳 — 按平台进行保护：Android mobile: shell 飞行模式、设备云网络配置文件，以及 iOS 网络调节器／Detox 代理说明。
• 权限对话框 — autoGrantPermissions（Android）、显式 mobile: alert（action: accept／dismiss）和 -ios predicate string 处理（iOS）。
• 生物识别 — 先执行 Detox setBiometricEnrollment(true)，再执行 matchBiometric()（匹配前先注册）。
• 应用生命周期 — 后台／前台、冷启动、新安装与恢复运行。

可在 references/mobile-patterns.md 中查看可运行代码，包括按平台进行保护的飞行模式代码片段，以及 iOS 与 Android 权限处理的区别。

---

反模式

只在模拟器上运行所有测试。 模拟器无法复现触控延迟、相机行为、GPS 漂移或推送时序。使用模拟器提高开发效率；通过设备云在真机上运行发布套件。

在测试中硬编码设备名称。 await driver.$('Samsung Galaxy S24 - Home') 会在设备更换时失效。请使用无障碍 ID 和跨平台选择器。

执行平台专属命令时不检查平台。 cmd connectivity airplane-mode 仅适用于较新版本的 Android，在 iOS 上则完全不可用；不加检查地执行会在其他平台上静默失败。应先根据 platformName 分支处理（参见 Appium 3.x）。

忽略应用权限。 假设权限已预先授予的测试，会在首次安装或测试拒绝权限的流程中失败。应针对各个平台显式处理权限。

未注册生物识别就进行匹配。 未先调用 setBiometricEnrollment(true) 就执行 matchBiometric() 会导致操作无效；身份验证始终无法完成，测试最终会在登录屏幕超时。

只测试纵向屏幕方向。 许多应用在横屏时会出问题。请在纵横两种方向测试关键流程，尤其是在平板电脑上。

跳过离线场景。 移动用户经常会失去网络连接。如果应用无法妥善处理离线情况，请证明这一点；如果可以，则应验证其行为。

用 sleep() 代替框架同步机制。 Detox 会自动等待；Appium 提供隐式等待和显式等待。基于 sleep 的同步方式在两者中都速度慢且不稳定。

忽略应用体积和启动时间。 一个体积为 200MB、冷启动需要 6 秒的应用是实际的用户体验问题。应加入针对二进制体积和启动时间的非功能检查。（如需深入分析启动、内存和电池性能，请使用 performance-testing。）

---

验证

运行所配置框架中最小范围的检查；在确认测试套件完成前，每项检查都应以退出码 0 结束，并输出预期内容。

# 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"

---

完成标准

• 已定义并提交设备矩阵（例如 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。
• 每次 PR 的 CI 都会在每个平台至少一台模拟器上运行测试（iOS 模拟器 + Android 模拟器）；真机云运行则仅在夜间或发布分支上触发。

参考文件（位于 references/）

• appium-patterns.md — Appium 3.x 安装、W3C capabilities、元素定位策略、手势模拟和平台保护模式。
• detox-and-maestro.md — Detox .detoxrc.js 配置、测试模式、设备 API（生物识别顺序、仅适用于 iOS 的推送说明）、CI 命令；以及 Maestro 安装（brew + curl）和 YAML 流程。
• device-farm.md — BrowserStack 和 Sauce Labs capabilities、经过身份验证的应用上传 curl 命令，以及 GitHub Actions P0/P1/P2 设备矩阵。
• mobile-patterns.md — 深度链接、推送、平台保护的网络模拟、iOS/Android 权限对话框和应用生命周期的可运行代码。

相关技能

• ci-cd-integration — 移动测试执行的流水线配置、构建产物管理、设备云 CI 连接器。
• cross-browser-testing — 设备矩阵设计借鉴了浏览器矩阵方法；矩阵策略的抽象介绍请参阅该技能，移动端执行请参阅本文。
• performance-testing — 移动端非功能测试深度：应用启动时间、内存使用和电池耗电。
• visual-testing — 截图/像素差异回归测试，包括移动端视口捕获。
• test-data-management — 移动应用的种子数据策略；通过 API 设置后端状态。
• test-reliability — 针对移动端计时、设备状态和网络条件的运行时不稳定测试修复。