Detox 安卓自动化测试环境搭建指南：从 Java 到 AOSP 模拟器与 Quick-Boot 快照

测试移动开发质量保障开发工具【免费下载链接】DetoxGray box end-to-end testing and automation framework for mobile apps项目地址https://gitcode.com/gh_mirrors/de/Detox点击查看免费下载本篇指南源自 Detox 仓库中面向 v20.x 的官方文档系统讲解如何搭建一个稳定、可靠、可复现的 Android 自动化 UI 测试环境——涵盖 Java 运行时准备、Android SDK 配置、AOSP 模拟器安装与命令行启动、模拟器快速启动Quick-Boot快照以及 Test Butler 的接入。无论你是在个人电脑本地开发还是在无 GUI 的 CI 机器上运行读完本文都能掌握一套完整的、经过 Detox 项目实践验证的 Android 测试环境搭建方案。核心原则先行运行自动化 UI 测试与开发 Android 应用是两回事。因此本文中的部分建议可能与日常 Android 开发习惯不完全一致——例如我们强烈建议使用 AOSP 模拟器而非带 Google APIs 的默认模拟器——建议读者认真对待这些差异。Java 环境准备这是整个流程中最基础的一步没有合适的 Java SDK任何 Android 相关操作都无法从命令行执行——而命令行执行恰恰是运行 Detox 的硬性前提。结论先行Android 需要安装 Java。如果你的目标是 React Native 73 Android 14 的组合那么 Java 版本至少需要Java 17其他场景下Java 11即可满足要求。检查 Java 版本在命令行终端中执行以下命令确认java是否在 PATH 中、版本是否满足要求java -version期望输出类似java version 17.x.x ...注意不要被浏览器等软件自带的 Java 版本误导。对 Detox 而言命令行实际解析到的版本才作数。常见问题排查java -version报错大概率是java未加入 PATH或压根未安装。可以先通过which java、echo $JAVA_HOME等命令判断属于哪种情况再针对性补齐。版本不对macOS 上 Java 既可能来自系统也可能来自 Homebrew 等第三方安装器两者叠加容易造成混乱。建议优先考虑使用JAVA_HOME环境变量来固定版本在环境相对干净无第三方安装器版本干扰的前提下直接安装 OpenJDK 17 覆盖现有版本若已安装多个版本可采用支持版本切换的安装方式确保命令行解析到的java是指定的那一个。Android SDK 配置绝大多数开发者电脑上装有 Android Studio此时 SDK 通常已存在于本机某处。但对于 CI agent往往无 GUI 运行或是不想安装体积臃肿的 Android Studio 的用户Google 官方也提供纯命令行工具集Command line tools only下载方案二者都可行。无论选择哪种安装方式、无论运行在 Mac / Linux / Windows强烈建议最终完成以下两项配置设置ANDROID_SDK_ROOT环境变量指向 SDK 根目录可通过echo $ANDROID_SDK_ROOT、echo $ANDROID_HOME查看现有值将 SDK 根目录加入全局PATH使adb、emulator、sdkmanager等工具可直接调用。这两个变量在后续所有命令行操作中都会被反复使用例如$ANDROID_HOME/emulator/emulator务必确保其已正确导出。推荐使用 AOSP 模拟器移动应用自动化需要一个 Android 设备来承载运行。如果尚未创建模拟器请先完成创建——但先别急着重装默认那个请先读完本节。Detox 项目长期实践证明自动化测试需要稳定且确定性的运行环境而带 Google APIs 的 Google 官方模拟器并不满足这一需求。原因有二预装的 Google play-services 会占用大量 CPU 资源Google 的 Gboard 键盘功能虽全但过于臃肿。这些都会诱发测试中的偶发性失败flakiness——而这正是自动化最需要避免的。幸运的是Google 提供了相当不错的替代品AOSP 模拟器Android Open-Source Project即;default;镜像。它可能缺少部分扩展的 Google 服务、外观也朴素一些但Detox 强烈建议在自动化 / Detox 测试中严格使用这类镜像且它可以与普通模拟器并存安装。下图直观对比了两者的差异——左侧为 SDK 28Android 9的 AOSP 模拟器右侧为带 Google APIs 的模拟器通过命令行安装 AOSP 镜像虽然用 Android Studio 也能完成但这里聚焦命令行方案因为它同样适用于无界面的 headless CI 机器。定位 Android home 目录通常由ANDROID_HOME或其前身ANDROID_SDK_ROOT环境变量给出。若ANDROID_HOME未设置请先自行设置或cd到 home 目录后再执行后续命令。升级emulator可执行文件到最新版本$ANDROID_HOME/cmdline-tools/latest/bin/sdkmanager --install emulator注模拟器版本与当前安装的 SDK / platform-tools 版本不必完全对齐例如模拟器 30.x.x 搭配 SDK 29 完全没问题。在较老的 Android Studio 版本中SDK-Manager 的路径为$ANDROID_HOME/tools/bin/sdkmanager。强烈建议使用新版工具若旧版环境导致上述命令失败可改试旧路径。若命令报错也可能是命令行工具本身未安装。此时可在 Android Studio 中点击Tools SDK Manager在SDK Tools标签页勾选并应用Android SDK Command-line Tools (latest)。安装不带 Google APIs 的模拟器镜像$ANDROID_HOME/cmdline-tools/latest/bin/sdkmanager system-images;android-28;default;x86_64 $ANDROID_HOME/cmdline-tools/latest/bin/sdkmanager --licenses;android-28;表示 SDK 28其他 API 级别同样支持;default;部分替代了默认的;google_apis;——这正是关键所在若在 M1 芯片的 Mac 上运行必须安装 arm64 架构镜像即system-images;android-28;default;arm64-v8a执行$ANDROID_HOME/cmdline-tools/latest/bin/sdkmanager --list可查看所有可用镜像列表。创建 AVDAndroid Virtual Device$ANDROID_HOME/cmdline-tools/latest/bin/avdmanager create avd -n Pixel_API_28_AOSP -d pixel --package system-images;android-28;default;x86_64Pixel_API_28_AOSP只是建议名称可任取甚至叫Pixel_API_28也行但需先删除已存在的同名非 AOSP 模拟器。无论如何Detox 配置通常在package.json中里使用的名称必须与此一致-d pixel使用 Pixel-1 设备规格也可换成其他规格运行avdmanager list devices可查看全部可用设备规格--package是最重要的参数务必与第 2 步中使用的值保持一致含;default;运行avdmanager create --help可查看完整选项。启动模拟器这一步并非强制但在运行自动化测试前至少手动启动一次总是好的——后续章节会讨论如何优化模拟器启动流程。此时应已能从 Android Studio 或命令行启动模拟器命令行方式见文末 Cheatsheet。通过 Android Studio 安装 AOSP 镜像用sdkmanager安装好正确镜像后AVD 创建对话框中即会出现该选项见下方Target列同时记得把emulator可执行文件升级到最新版若未升级status列会显示 Update Available 而不是 Installed注模拟器版本与当前 SDK / platform-tools 版本不必对齐例如 30.x.x 搭配 SDK 29。命令行启动与 headless 模式从 Detox 源码看模拟器启动参数被封装在 EmulatorAllocDriver.js 中它会将设备配置中的headless与gpuMode透传给 EmulatorLauncher.js从而决定是否追加-no-window等参数。这意味着在 Detox 的devices配置中你可以通过{ type: android.emulator, device: { avdName: Pixel_API_28_AOSP }, headless: true, gpuMode: swiftshader_indirect }直接让 Detox 以无窗口方式启动模拟器而无需手写上述命令——这正是 CI 场景的标准玩法。gpuMode支持auto | host | swiftshader_indirect | angle_indirect | guest等取值详见 devices.mdx 的配置说明。模拟器快速启动Quick-Boot如果系统允许保存状态例如个人电脑或可从预烘焙镜像启动的 CI 系统强烈建议为所有用于测试自动化的模拟器配置快速启动快照quick-boot snapshots。Quick-Boot 能省去模拟器从零冷启动cold-boot的大量时间。在多 Jest worker 并行执行测试即多个模拟器同时运行的场景下这一收益尤为明显——参见 testRunner.mdx 中关于多 worker 并行的说明。虽然更推荐在模拟器 GUI 内操作但这里两种方案都会给出。核心原则如下对已安装 / 正在运行的模拟器开启 auto-save启动它待其稳定后关闭——此时会自动保存一份快照关闭 auto-save避免后续被测试污染过的状态被再次保存。方式一在模拟器 GUI 中配置快照启动一个全新的模拟器等待其稳定。运行状态下打开侧边栏设置右上角三个点SnapshotsSettings标签页。若尚未设置将auto-save选项选为Yes。此时会提示重启——选择Yes。模拟器会重启并保存一份快照。模拟器重新起来后再次进入同一位置将auto-save设为No允许其再次重启这次它会直接引导进入此前保存的快照状态。方式二通过命令行配置快照这种方式稍复杂但同样适用于无 GUI 的机器。先定位 AVD 的config.ini用文本编辑器新增或修改以下键值对fastboot.chosenSnapshotFile fastboot.forceChosenSnapshotBootno fastboot.forceColdBootno fastboot.forceFastBootyes经验上forceFastBootyes与forceColdBootno两者通常已经足够。在 AVD 的 home 目录下新建或编辑另一个名为quickbootChoice.ini的文件写入saveOnExit true一切就绪后通过命令行启动模拟器建议 verbose 模式并等待其完全加载然后关闭它并确认状态已被保存。最后回到quickbootChoice.ini改为saveOnExit false注意事项升级模拟器二进制到新版本后它通常会认为所有既有快照失效。解决办法是按下述流程删除并重建快照或者干脆重建整个 AVD。接入 Test Butler可选但强烈建议如果你按照推荐选择了 AOSP 镜像作为测试目标强烈建议同时集成 [Test Butler]——至少用于抑制崩溃crash和 ANR 对话框。这类对话框是 Android UI 测试的软肋一旦弹出整个 UI 将完全无法交互导致大量测试成批失败。Test Butler 与 Detox 的集成方式与其官方指南略有不同整体分两步将 test-butler-app APK预装到测试设备上将 test-butler-lib 集成进自己的测试 APK并在自定义测试运行器中初始化。其中 lib 部分按官方说明即 Gradle 的androidTestImplementation即可轻松完成初始化亦然。但 APK 部分官方建议的 GradleandroidTestUtil用法在 Detox非原生 instrumentation 测试场景下效果有限请改用以下方案。方案一预烘焙镜像推荐若你能控制模拟器快照按 Test Butler 指南下载并安装其 APK例如adb install -r -t path/to/test-butler-app.apk然后保存一份更新后的快照。这是最优方案。注意未来升级到更新的 Test Butler 版本时需要重复此操作。方案二动态安装假设 APK 已在系统中可用可以在 Detox 配置中利用utilBinaryPaths让 Detox 自动将其安装到所有运行中的目标模拟器上{ devices: { emulator.oss: { type: android.emulator, device: ..., utilBinaryPaths: [relative/path/to/test-butler-app-2.2.1.apk] } } }关于utilBinaryPaths的更多细节可参考 apps.mdx 配置指南。从源码层面看该字段的完整链路如下配置校验位于 composeDeviceConfig.js必须是字符串数组否则抛出malformedDeviceProperty且该属性仅对 Android 设备类型android.attached、android.emulator、android.genycloud合法iOS 设备使用会报unsupportedDeviceProperty见 DetoxConfigErrorComposer.js安装动作发生在 RuntimeDevice.js 的installUtilBinaries()方法中读取配置后交由 device driver 统一安装根据 devices.mdx 的说明这些工具 APK 不受device.launchApp({delete: true})等安装生命周期事件影响不会被重装流程误删——这正是 Test Butler 需要常驻设备的原因。关于如何获得 APK 文件目前没有现成的完美方案官方在推进中可选思路a. 在自定义脚本中直接从 Maven 预下载例如Mac / Linuxcurl -f -o ./temp/test-butler-app.apk https://repo1.maven.org/maven2/com/linkedin/testbutler/test-butler-app/2.2.1/test-butler-app-2.2.1.apk若走这条路建议把./temp/test-butler-app.apk加入.gitignore。b. 不推荐将其作为仓库的一部分提交到源码控制如 git。Cheatsheet以下速查命令适用于 Mac 和 LinuxWindows 上类似。定位 AVD 的 home 目录Android 工具创建的每个 AVD 都有独立的目录存放其关联内容包括配置文件config.ini快照镜像snapshot imagesSD 卡内容等。在 Mac 上AVD 目录通常位于$HOME/.android/avd/AVD Name.avd/例如/Users/root/.android/avd/Pixel_API_28_AOSP.avd/。Linux 上路径类似只是$HOME通常为/home/root而非/Users/root例如/home/root/.android/avd/Pixel_API_28_AOSP.avd/。通过命令行启动模拟器以下示例均假设模拟器名为Pixel_API_28_AOSP如不一致请按实际名称调整。在支持 GUI 的系统上启动带界面的 verbose 模拟器$ANDROID_HOME/emulator/emulator -verbose Pixel_API_28_AOSP 在无 UI 的 Linux 系统上启动 headless 的 verbose 模拟器$ANDROID_HOME/emulator/emulator -verbose -no-window -no-audio -gpu swiftshader_indirect Pixel_API_28_AOSP 若希望 Detox 在启动模拟器时自动套用类似的 headless / GPU 参数可直接在设备配置中使用headless与gpuMode字段参见上文命令行启动与 headless 模式一节。验证快照是否已保存如果你在 shell 中以 verbose 模式运行模拟器可通过日志轻松确认状态是否已保存。特别是关闭模拟器时出现如下日志即表示状态已保存emulator: Saving state on exit with session uptime 9423 ms作为对照当状态未保存时典型输出为emulator: WARNING: Not saving state: RAM not mapped as shared后者通常由配置不当引起也可能是使用了带-read-only参数的启动方式。总结一个稳定可靠的 Detox Android 自动化环境可以概括为四个关键决策Java 版本对齐React Native 73 Android 14 至少 Java 17其余场景 Java 11 起步且务必保证命令行解析到的版本正确SDK 环境变量完整ANDROID_SDK_ROOT/ANDROID_HOME与PATH配置到位为后续所有命令行操作铺路坚持 AOSP 镜像用;default;替代;google_apis;从根源上减少 play-services 与 Gboard 带来的测试抖动并善用headlessgpuMode配置适配 CI快照与 Test Butler 双管齐下Quick-Boot 快照大幅缩短模拟器启动时间Test Butler 则压制 crash / ANR 对话框这一批量杀测试的元凶。按照本文流程在本地或 CI 上完成配置后Detox 测试便有了可预测、低抖动、可并行的 Android 运行底座后续即可专注在测试用例本身的编写与维护上。赞分享测试移动开发质量保障开发工具【免费下载链接】DetoxGray box end-to-end testing and automation framework for mobile apps项目地址https://gitcode.com/gh_mirrors/de/Detox点击查看免费下载相关推荐Detox Android 测试环境搭建指南从 Java 到 AOSP 模拟器与 Quick-Boot 快照Detox Android 测试环境搭建指南从 Java 到 AOSP 模拟器与 Quick Boot 快照 本文档源自仓库 docs/guide/andro测试移动开发质量保障开发工具Uncle Novel核心功能详解如何高效搜索和下载全网小说Uncle Novel核心功能详解如何高效搜索和下载全网小说 Uncle Novel是一款强大的小说搜索下载工具能够帮助用户快速找到并下载全网小说资源支持桌面应用如何理解Illustrious XL v0.1架构Stable Diffusion XL模型原理解析指南 如何理解Illustrious XL v0.1架构Stable Diffusion XL模型原理解析指南 Illustrious XL v0.1 是一个上一篇RedwoodJS 集成 Firebase Authentication 完整指南从环境配置到源码级原理下一篇5分钟让Jupyter Notebook提示音秒变主题风从无声到个性的听觉革命创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考