Detox CLI 命令完全指南安装、配置与端到端测试工作流【免费下载链接】DetoxGray box end-to-end testing and automation framework for mobile apps项目地址: https://gitcode.com/gh_mirrors/de/DetoxDetox 是面向移动应用的灰盒端到端测试与自动化框架而 Detox CLI 是其所有命令行操作的统一入口。本文基于 Detox 20.x 文档体系中的 CLI 概览website/versioned_docs/version-20.x/cli/overview.md及其各子命令文档整理而成并辅以仓库源码佐证。读完本文你将掌握detox命令的安装方式、全局参数以及init、build、test、run-server、框架缓存维护、锁文件管理等全部子命令的用法与实战细节能够独立完成从项目初始化到 CI 上稳定运行的完整 CLI 工作流。安装与基本用法Detox CLI 是独立发布的 npm 包仓库中的实现位于 detox-cli/cli.js对应包元数据见 detox-cli/package.json其 bin 字段将全局detox命令映射到该入口文件。推荐以全局方式安装npm install detox-cli --global安装后即可在任意项目目录中使用统一调用格式detox command [options]两个全局选项对所有子命令通用OptionsDescription--versionShow version number--helpShow help从实现上看全局安装的detox-cli是一个轻量包装器wrapper它主要做两件事——在 macOS 上拦截recorder命令并转发给项目内安装的detox-recorder其余命令则转发到当前项目node_modules/.bin下的真实detox可执行文件若找不到会给出清晰的排错提示建议检查当前目录、执行npm install或安装detox开发依赖。也就是说CLI 的实际命令解析逻辑位于项目本地安装的detox包内其入口为 detox/local-cli/cli.js它基于 yargs 框架通过.commandDir(./)自动注册local-cli目录下的全部子命令并开启了boolean-negation、camel-case-expansion等解析配置。命令总览下表列出了 Detox CLI 提供的全部命令与官方概览一致CommandDescriptioninitCreate initial E2E tests folder for Detox.buildRun the command defined in build property of the specified configuration.testInitiating your test suite.recorderStarts a Detox Recorder recording.build-framework-cacheMacOS only.Builds or rebuilds a cached Detox framework and/or XCUITest-runner in ~/Library/Detox. The cache is specific for each combination of Xcode and Detox versions.clean-framework-cacheMacOS only.Deletes all compiled framework and XCUITest-runner binaries from ~/Library/Detox, they will be rebuilt on npm install or when running build-framework-cache.rebuild-framework-cacheMacOS only.Cleans and builds a cached Detox framework and XCUITest-runner in ~/Library/Detox. The cache is specific for each combination of Xcode and Detox versions.reset-lock-fileResets Detox lock file completely - all devices are marked as available after that.run-serverStarts a standalone Detox server.下面逐一展开每个命令的完整参数与使用场景。detox init一键搭建 E2E 测试骨架detox init该命令会在当前项目目录下创建几个模板文件帮助你快速完成 Detox 项目初始化.detoxrc.js—— Detox 配置文件e2e/jest.config.js—— Jest 测试运行器配置e2e/starter.test.js—— 一个最简单的测试套件示例。模板的实际内容可在仓库中查看detox init所需的配置模板与启动测试模板位于 detox/local-cli/templates其中firstTestContent.js就是生成到e2e目录的起始用例模板。生成目录结构可参考仓库内真实示例项目 examples/demo-react-native/detox.config.js 与 examples/demo-react-native/e2e。detox build构建被测应用detox build [options]该命令会执行指定 configuration 中每个 app 配置的build命令属性。支持的参数如下OptionDescription-c, --configurationdevice configSelect a device configuration from your defined configurations, if not supplied, and there’s only one configuration, detox will default to it-C, --config-pathconfigPathSpecify Detox config file path. If not supplied, detox searches for .detoxrc[.js] or detox section in package.json-i, --if-missingExecute the build command only if the app binary is missing.-s, --silentDo not fail with error if an app config has no build command.--helpShow help典型用法示例# 只有一个配置时直接构建 detox build # 指定具体配置 detox build --configuration yourConfiguration # 跳过已构建的应用 detox build --configuration yourConfiguration --if-missingdetox test启动测试套件核心命令detox test [options] ...testFilePathsdetox test在大多数情况下是一个便捷包装方法它把 CLI 参数转换为环境变量然后运行第三方测试运行器默认是 Jest如果配置了--retries还可能多次重启运行器。所有未知的 flags 都会原样透传给底层的测试运行器。例如detox test -c ios.debug --showConfig会被翻译成DETOX_CONFIGURATIONios.debug jest --showConfigCLI 打印出的这条命令你可以直接复制并独立运行不需要借助 Detox CLI。如果某个选项名在测试运行器与detox test之间发生冲突两者都有同名参数可以在保留的--序列之后显式传入detox test -c ios.debug -- --help ↓ DETOX_CONFIGURATIONios.debug jest --help完整参数表OptionDescription-C, --config-pathconfigPathSpecify Detox config file path. If not supplied, detox searches for .detoxrc[.js] or detox section in package.json-c, --configurationdevice configSelect a device configuration from your defined configurations, if not supplied, and there’s only one configuration, detox will default to it-n, --device-name [name]Override the device name specified in a configuration. Useful for running a single build configuration on multiple devices.-l, --loglevel [value]Log level: fatal, error, warn, info, verbose, trace-d, --debug-synchronizationvalueCustomize how long an action/expectation can take to complete before Detox starts querying the app why it is busy. By default, the app status will be printed if the action takes more than 10s to complete.-a, --artifacts-locationpathArtifacts (logs, screenshots, etc) root directory. 行为细节见下方注释1--record-logs [failing/all/none]Save logs during each test to artifacts directory. Pass failing to save logs of failing tests only. The default value isnone.--take-screenshots [manual/failing/all/none]Save screenshots before and after each test to artifacts directory. Pass failing to save screenshots of failing tests only. The default value ismanual.--record-videos [failing/all/none]Save screen recordings of each test to artifacts directory. Pass failing to save recordings of failing tests only. The default value isnone.--record-performance [all/none][iOS Only] Save Detox Instruments performance recordings of each test to artifacts directory. The default value isnone.--capture-view-hierarchy [enabled/disabled][iOS Only] Capture*.uihierarchysnapshots on view action errors anddevice.captureViewHierarchy()calls. The default value isdisabled.-R, --retriesRe-spawn the test runner for individual failing suite files until they pass, orNtimes at most.-r, --reuseReuse existing installed app (do not delete reinstall) for a faster run.-u, --cleanupShutdown simulator when test is over, useful for CI scripts, to make sure detox exists cleanly with no residue--jest-report-specs[Jest Only] Whether to output logs per each running spec, in real-time. By default, disabled with multiple workers.-H, --headlessLaunch device in headless mode. Useful when running on CI.--device-boot-argsA list of passthrough-arguments to use when (if) devices (Android emulator / iOS simulator) are launched by Detox.注意值必须写在等号之后并用引号包裹。用法示例--device-boot-args-http-proxy http://1.1.1.1:8000 -no-snapshot-load--app-launch-argsCustom arguments to pass (through) onto the app every time it is launched. 与--device-boot-args有同样的写法限制。完整信息见 launch arguments guide。--startControl execution of start commands in the app configs. By default, they run right before the test runner. Pass--startforceto ignore the errors coming from the start commands, and run the test runner anyway. Pass--no-startto skip the start commands altogether.--no-colorDisable colors in log output--use-custom-loggerUse Detox custom console-logging implementation, for logging Detox (non-device) logs. Disabling will fallback to node.js / test runner’s implementation (e.g. Jest).默认值true--gpu[Android Only] Launch Emulator with the specific -gpu [gpu mode] parameter.--force-adb-install[Android Only] Due to problems with theadb installcommand on Android, Detox resorts to a different scheme for installing APKs. Setting true will disable that and force usage ofadb install, instead. 该 flag 在 Detox 自身的安装方案稳定之前属于临时方案。默认值false--inspect-brkUses node’s --inspect-brk flag to let users debug the test runner。默认值false--replLaunch REPL (Read-Eval-Print Loop) mode for interactive debugging. Use--replautoto enter REPL mode automatically on test failures.默认值false--helpShow helpDETOX_ARGV_OVERRIDE故障现场的逃生舱当你在复杂脚本或失败的 CI 构建例如 TeamCity、Jenkins中排查 Detox 测试问题时可以通过设置DETOX_ARGV_OVERRIDE环境变量在不修改任何配置文件的情况下为 Detox 注入额外的 CLI 参数再重跑 export DETOX_ARGV_OVERRIDE--forceExit -w 1 --testNamePatternthat hanging test e2e/sanity/login.test.js bash scripts/ci.e2e.sh # ... some output ... detox test -c ios.sim.release -l verbose --maxWorkers 3 # ... configurationios.sim.release ... jest --maxWorkers 1 --forceExit --testNamePatternthat hanging test e2e/sanity/login.test.js上述示例中DETOX_ARGV_OVERRIDE强制 Detox 以单 worker 模式运行 Jest并在指定测试文件里只执行某个选定用例、1 秒后强制退出。从源码看该机制实现在 detox/local-cli/testCommand/middlewares.js 的applyEnvironmentVariableAddendum中一旦检测到环境变量存在就会打印DETOX_ARGV_OVERRIDE_NOTICE警告然后用 yargs 解析该变量的内容把其中的命名参数与位置参数追加到最终生成的测试运行器命令中。对应行为有测试用例覆盖见 detox/local-cli/test.test.js包括--透传部分也会被正确追加。DETOX_ARGV_OVERRIDE的思路与 NODE_OPTIONS 类似区别在于它不是用于常规流程而是用于对失败的 Detox 配置做强制的一次性临时修补以节省排查时间。请避免在常规流程中使用它——首选方案仍然是 Detox 配置文件.detoxrc.js。detox recorder录制测试脚本已废弃:::danger WarningDetox Recorder 工具因 Detox 团队人力资源不足已废弃。:::如果你在项目中安装了 Detox Recorder可以使用该命令开始一次新的录制。需要说明的是它依赖独立的detox-recorder包从 detox-cli/cli.js 的实现可见仅在 macOS 平台上该命令会被转发到node_modules/detox-recorder/DetoxRecorderCLI可执行文件若未安装会直接报错提示。框架缓存命令仅 macOSbuild / clean / rebuild-framework-cache这类命令用于管理~/Library/Detox下的框架缓存缓存按Xcode 版本 × Detox 版本的组合区分。detox build-framework-cache构建或重建缓存的 Detox 框架与/或 XCUITest-runner。缓存对每种 Xcode 与 Detox 版本组合是专用的。对应脚本可参考 detox/scripts/build_framework.ios.sh 与 detox/scripts/build_xcuitest.ios.sh。detox clean-framework-cache仅 macOS。清理缓存的 Detox 框架与 XCUITest-runner 编译产物。支持两个选择性参数--detox—— 只清理 Detox 注入框架。默认 false两者都清理。--xcuitest—— 只清理 XCUITest runner。默认 false两者都清理。清理后这些二进制会在下次npm install或执行build-framework-cache时被重建。detox rebuild-framework-cache仅 macOS。等价于先 clean 再 build重建缓存的 Detox 框架与 XCUITest-runner。参数与 clean 相同--detox—— 只重建 Detox 注入框架。默认 false两者都重建。--xcuitest—— 只重建 XCUITest runner。默认 false两者都重建。detox reset-lock-file彻底重置设备锁detox reset-lock-file重置 Detox 锁文件。锁文件中记录了设备的忙闲状态以此保证同一台设备不会被多个 Detox 测试会话同时占用。默认情况下detox test启动时会清理锁文件但它只针对已分配给已死进程或不存在的进程的设备条目而reset-lock-file则是彻底清空整个锁文件将所有设备标记为可用。这在设备状态异常残留例如测试进程被强杀后设备仍显示占用时非常有用。detox run-server启动独立 Detox 服务器:::note该工具主要用于 Detox 原生代码库的贡献开发而非外部常规使用。:::detox run-server [options]OptionDescription-p, --port [port]Port number (default: 8099)-l, --loglevel [value]Log level: fatal, error, warn, info, verbose, trace--no-colorDisable colorful logs--helpShow help对应实现位于 detox/local-cli/run-server.js端口参数在 165535 之外会抛出DetoxRuntimeError随后基于 CLI 参数组合 logger 配置并以standalone: true模式打开 DetoxServer 实例。小结与实战建议围绕 Detox CLI 的日常工作流可以概括为一条主线detox init生成骨架 → 编辑.detoxrc.js定义 app 与设备的 configuration →detox build -c 配置构建被测应用 →detox test -c 配置运行测试。CI 场景下常用-Hheadless、-u结束后关闭模拟器、--record-logs/--take-screenshots等产物收集参数而遇到疑难故障时--repl失败自动进入交互调试与DETOX_ARGV_OVERRIDE临时注入参数是两个高效的排障手段。多设备并行的锁异常则交给reset-lock-file兜底。理解CLI 参数 → 环境变量 → 第三方测试运行器的转发链路是熟练驾驭detox test的关键。如果--artifacts-location路径不以/或\结尾detox CLI 会在该路径下追加一个包含配置名和时间戳的子目录例如artifacts/android.emu.release.2018-06-12 05:52:43Z。换句话说以斜杠结尾的路径表示你不需要额外的子目录。更多细节参见 Enabling artifacts。默认值是artifacts外加子目录。↩【免费下载链接】DetoxGray box end-to-end testing and automation framework for mobile apps项目地址: https://gitcode.com/gh_mirrors/de/Detox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考