qa-testing-mobile

QA 测试（移动端）

为 iOS 和 Android（原生 + 跨平台）设计并执行可靠且注重成本效益的移动端测试。

快速参考

从工作流开始；使用专家判断权衡框架和自动化方案，并通过资源了解详情。

快速入门

• 填写 assets/mobile-test-plan.md，明确风险、测试层级和门禁。
• 根据分析数据填写 assets/device-matrix.md，确定 Tier 1/2/3 覆盖范围。
• 使用 references/framework-comparison.md 选择自动化框架。
• 使用 references/release-and-rollout.md 制定 Beta、发布前、分阶段推出和回滚检查。
• 使用 references/accessibility-testing.md 补充 iOS 和 Android 无障碍测试覆盖。
• 使用 references/flake-management.md 设置不稳定测试预算、重跑次数和隔离规则。

范围

• 制定覆盖 iOS 和 Android 的移动端测试策略。
• 规划设备矩阵、操作系统覆盖范围和风险等级。
• 选择自动化框架，并设置 CI 和设备实验室。
• 处理性能、网络/离线、后台运行和权限。
• 定义发布前门禁、分阶段推出和应用商店就绪检查。

不适用场景

• 特定于 iOS 平台的测试命令详情 -> qa-testing-ios
• 特定于 Android 平台的测试命令详情 -> qa-testing-android

需要收集的输入

• 平台、支持的操作系统版本和目标设备。
• 应用类型（原生、跨平台、混合/WebView）。
• 关键用户流程和风险领域。
• 分发渠道和发布频率。
• Beta/发布渠道（TestFlight、Play 内部/封闭测试，如适用还包括企业分发）。
• 现有测试工具、CI 和设备实验室访问权限（Firebase Test Lab、BrowserStack、AWS Device Farm）。
• 可观测性和发布控制（Crashlytics/Sentry、性能/RUM、功能标志、分阶段推出）。
• 测试数据策略（种子数据/重置、测试账号、环境一致性）。

工作流

1. 明确质量风险和 SLI（无崩溃率、ANR、启动时间、关键流程成功率）。
2. 根据分析数据构建设备矩阵；PR 门禁优先使用模拟器。
3. 选择框架（默认：XCUITest + Espresso/Compose；仅在能降低总成本时才添加特定于应用的跨平台方案）。
4. 当选择器维护成为瓶颈时，评估 AI 原生工具能否用于自愈、自然语言编写或基于视觉的测试。
5. 构建测试层级：单元测试、集成/契约测试、UI 冒烟测试，以及针对真实设备的定向 E2E 测试。
6. 补充移动端特有的测试覆盖：权限、后台/前台切换、深层链接、离线/弱网。
7. 添加性能检查（启动、滚动/卡顿、内存）和无障碍审计。
8. 设置不稳定测试预算、重跑次数上限、隔离策略和故障分诊流程（产物 + 可复现性）。
9. 定义发布门禁和应用商店就绪条件；运行 Beta 检查（TestFlight、适用时的 Play 发布前报告），并通过分阶段推出发布，同时监控并准备回滚。

产出

• 移动端测试策略和设备矩阵。
• 自动化计划和框架选择。
• 带优先级的测试用例清单。
• 发布就绪检查清单。
• CI 流水线和报告计划。

质量检查

• 让 UI 测试聚焦关键流程；保持测试套件精简、快速。
• 将设备特定问题与逻辑回归分开处理。
• 按测试和设备跟踪不稳定率；隔离并修复问题最严重的测试。
• 验证权限、通知和后台行为。
• 在隔离的测试后端和预置账号上运行 CI，确保测试不会修改生产数据。
• 如果应用依赖无障碍功能、地区设置／时区或升级路径，请纳入相应覆盖。
• 优先使用稳定的选择器（无障碍 ID／测试标签），而非本地化文本。对于基于视觉的工具，请使用具体可见的标签。
• 使用 AI 原生工具时，应先检查自动生成的测试是否正确，再将其作为门禁。基于视觉或具有非确定性的检查应与确定性测试配合使用；不得将其作为唯一的 PR 门禁。
• 如果视觉报告引用的临时截图路径不存在，请重新捕获当前屏幕或检查 UI 层级。不要仅因临时文件已过期就忽略报告。
• 将供应商定价、设备供应情况和应用商店政策详情视为实时信息：定稿前请通过官方文档核实。
• 如果平台特定的已知陷阱很重要，请对照一手资料核实当前的 bug 行为，并在平台特定测试套件中加入回归测试，而不要依赖跨平台冒烟测试覆盖。
• 添加全新克隆 CI 门禁（从干净的 git clone 构建／归档，不使用开发端的再生成工具）；对于 iOS，必须确保归档通过，而不只是构建通过。详情见 references/release-and-rollout.md 和 qa-testing-ios ios-ci-general.md（“Build 操作 ≠ Archive 操作”）。
• 根据当前应用商店政策（Play 目标 API、App Store SDK 最低版本）以及 Android vitals 不良行为阈值来控制发布分支；将这些阈值设为停止推送的标准。参见 references/release-and-rollout.md。

分发渠道验证

• 移动端发布就绪性应涵盖真实分发路径，而不只是本地或 CI 编译成功。
• 对于 iOS，应在与生产行为一致的渠道上验证归档／签名、TestFlight 就绪情况，以及 APNs 或 StoreKit 等仅在生产环境中发生的行为。
• 对于 Android，如果应用商店侧行为很重要，请纳入 Play 测试轨道或等效的应用商店／设备实验室证据。
• 对于每个门禁，请记录 built、installed、launched、journey-verified、channel-verified 或 monitored-rollout，并注明来源／构建标识、平台、OS／设备、地区设置、后端、渠道、制品和观察时段。
• 不要将模拟器、设备实验室、Beta 渠道和生产环境的证据合并为一次通过。后续阶段仅可继承完全相同构建和配置的前序证据。
• 将产品特定的推送顺序、元数据清单、审核者账号和内部冒烟测试脚本保留在项目文档中。可移植的基线要求见 references/release-and-rollout.md。

本地化覆盖

对于具有本地化 UI 或由后端提供本地化内容的应用，需要制定分层测试计划：

• 快速检查目录／键值覆盖，尽早发现缺失资源
• 检查内容质量，避免非英语地区设置悄然使用英语默认内容
• 针对少数高信号地区设置进行定向布局冒烟测试
• 在适用时，对后端提供的本地化文案进行集成检查
• 遵循选择器规范，避免使用依赖地区设置的元素定位方式

本地化 UI 正确性也包括布局一致性：同级容器宽度相同、换行标签不会截断重要术语、不存在遮挡主要内容的覆盖层，并且在支持的最窄手机上控件仍可用。AI 原生或视觉测试有助于发现这些问题，但确定性的目录一致性检查和定向地区布局冒烟测试仍然是门禁。

详细模式和权衡请参阅 references/localization-testing.md。

专家判断

以下决策无法仅靠清单替你完成——它们需要结合具体团队、应用和业务背景来判断。

原生与跨平台：元决策

框架决策矩阵（references/framework-comparison.md）会告诉你哪种工具适合哪类应用，但不会告诉你是否应该一开始就构建跨平台应用，也不会告诉你现有的跨平台应用是否应该继续使用跨平台测试套件。请权衡以下因素：

• 团队构成比应用形态影响更大。 对于只有一个共用工程团队、没有专职 iOS/Android 专家的团队，即使会付出一些测试不稳定和维护成本，使用 Detox/Patrol/Maestro 也能发挥更大优势（一套测试套件、一套技能）。而拥有独立 iOS 和 Android 小组、具备深厚原生开发专长的团队，则可以选择同时运行 XCUITest + Espresso。在决定重复编写平台测试是否比共用抽象层成本更低之前，请先在有代表性的用户旅程上比较实测的不稳定率、执行时间和维护投入。
• 维护成本会不断累积，编写成本则不会。 跨平台框架（尤其是 Appium）在第一天看起来成本更低（编写一项测试即可覆盖两个平台），但测试套件整个生命周期的总拥有成本主要取决于不稳定测试的排查和选择器维护，而非最初的编写时间。对于原生（非 RN/Flutter）应用，在决定采用共用的跨平台 E2E 层之前，请将预期测试套件生命周期内的维护成本与试点项目的编写成本进行比较。
• 应用自身的架构通常足以做出决定。 如果应用已经采用 React Native 或 Flutter，为了「保持一致」而放弃该框架自己的原生测试工具（Detox / Patrol），转而使用 Appium，通常得不偿失——你不仅要承担 Appium 的测试不稳定问题，还会失去框架原生测试工具免费提供的、更紧密的 JS 桥接或 widget 树同步能力。
• 应在规模跨越临界点时重新评估，而非按固定周期评估。 重新审视这一决策的正确时机，是团队结构发生变化（组建或解散专业小组）或测试套件规模翻倍时（维护成本与编写成本的增长方式不同），而不是某个日历日期。

不适合自动化移动端 E2E 的情况

自动化并非没有成本。以下情况应优先考虑手动测试，而不是默认选择自动化：

• 界面或流程的变化速度快于测试稳定下来的速度。 正在重新设计的界面、包含多个线上变体的 A/B 测试引导流程，或很可能在一个季度内被砍掉的产品市场契合度（PMF）验证前功能，都不适合作为自动化目标——测试还没发挥作用，维护成本就已经产生。对此类情况进行手动探索性测试，待 UI 稳定后再考虑自动化。
• 流程流量低，影响范围也小。 内部管理工具、不常使用的设置子页面，或后果有限的低流量流程，可能不值得专门编写 E2E 测试。评估时应考虑严重程度和数据丢失风险；仅靠崩溃报告无法发现静默失败。将 E2E 自动化留给 ## Inputs to Gather 中确定的关键路径流程（身份验证、结账、核心价值主张）。
• 团队无法承诺修复不稳定测试。 无人分类处理的 UI 测试套件会逐渐变成被忽视的噪声，随后被绕过，最终遭到主动质疑——此时它带来的价值就会变成负值（虚假的信心），还不如没有测试套件。如果没有负责人，也没有不稳定测试服务级别协议（SLA），就不要增加更多 E2E 覆盖；应先修复现有测试套件的可信度。
• 已有成本更低的测试层覆盖相同风险。 业务逻辑、验证规则和 API 契约，几乎总是更适合在单元或集成测试层覆盖，因为这种方式更快、更确定，维护成本也更低。只有确实需要设备/OS/UI 层验证的内容才使用 E2E：渲染、手势、权限、切换到后台、深度链接和跨屏导航。
• 产品市场契合度验证前或原型阶段。 在达到产品市场契合度之前，如果 UI 预计会根据用户反馈每周变化，简短的手动冒烟测试清单加上完善的崩溃报告，通常比投入 E2E 自动化更划算，因为后者往往还没收回编写成本就得重写。

不稳定测试的成本与发布列车节奏

请参阅 references/flake-management.md#flake-economics-real-device-vs-simulator，了解同样的不稳定率为何在真实设备和模拟器上会产生不同成本（重跑延迟、根因构成和信号价值都不相同）；另请参阅 references/release-and-rollout.md#release-train-cadence-and-testing-scope，了解如何根据发布节奏匹配测试范围——包括应用已有真实用户后，为何必须提供热修复路径，以及功能标志如何让“构建已安全发布”与“功能已通过验证”彼此解耦。

模板

• assets/device-matrix.md：OS 和设备覆盖范围。
• assets/mobile-test-plan.md：测试范围和自动化。
• assets/release-readiness-checklist.md：发布门槛。

资源

• references/framework-comparison.md，用于在 XCUITest、Espresso/Compose、Appium 3（仅支持 W3C；请检查 npm engines 中支持的 Node 范围，并在受维护的 Node LTS 版本线上运行 CI）、Detox（兼容新架构）、Maestro（docs.maestro.dev）、Drizz、TestSprite 和 Flutter 测试（Patrol）之间进行选择。
• references/ai-native-testing.md，介绍 AI 原生移动测试：基于 VLM 的测试、MCP 集成、自愈、自然语言编写和决策框架。
• references/flake-management.md，提供不稳定测试控制指南。
• references/device-farm-strategies.md，介绍云设备农场的选择、采购问题和成本优化。
• references/mobile-performance-testing.md，介绍启动、卡顿、内存和电池测试。
• references/cross-platform-test-patterns.md，介绍 React Native、Flutter 和 KMP 测试模式。
• references/release-and-rollout.md，介绍 TestFlight、Play 预发布报告、分阶段推出和回滚计划。
• references/localization-testing.md，介绍分层区域覆盖和选择器规范。
• references/accessibility-testing.md，介绍跨平台无障碍发布门禁问题，以及指向 qa-testing-accessibility 中 iOS/Android 审计 API 的参考。
• references/visual-regression-mobile.md，介绍黄金图像策略、视觉差异工具（Percy、Applitools、Chromatic、Sauce Visual）、指向 qa-testing-android / qa-testing-ios 中原生快照工具的参考、像素容差与感知差异、基线轮换频率，以及 CI 工件上传模式。
• references/test-layers-and-suite-anti-patterns.md，介绍单元/集成/E2E 测试的成本概况、深度链接和离线测试入口，以及测试套件层面的反模式。
• data/sources.json，包含精选文档和设备实验室链接。

导航

使用 模板 查看计划输出，使用 资源 深入了解具体问题；平台命令详情请参阅 相关技能。

相关技能

技能	用途
qa-testing-ios	深入了解 iOS：XCTest、Swift Testing、simctl
qa-testing-android	深入了解 Android：Espresso、Compose Testing、UI Automator
qa-testing-playwright	Web 和 WebView 测试
software-mobile	移动架构指南

经验总结循环

当先前的决策或问题教训与当前情况相关时，如果存在，请查阅 learnings.consolidated.md；仅在需要了解历史或将其作为可用的备用资料时，才使用 learnings.md。否则跳过这两个文件。

应用后，如果遇到了值得记住的模式、值得避免的错误，或令你意外的领域知识，请通过 agents-skills-feedback-loop/scripts/append_learning.py 向 learnings.md 追加一条带日期的项目。不要修改 SKILL.md 本身。