androidtestrunner 工具

简介

androidtestrunner 工具可在Android设备和模拟器上运行Qt Test。它可自动化执行测试所需的各项步骤，包括管理APK安装、执行测试以及获取结果。

在使用androidtestrunner 之前，请确保已使用 CMake 或 qmake 配置好您的 Qt Test 项目。

工作原理

1. 首先，它会执行 APK 构建命令，以生成测试所需的 APK。
2. 随后，它将测试应用安装到目标设备上并启动测试应用，从而启动测试流程。
3. 测试结果将写入设备上应用的数据目录，以确保捕获全面的测试输出。
4. 测试结束后，运行器会在结果文件旁边写入一个退出代码文件。
5. 在此阶段，androidtestrunner 会从设备中检索这些结果文件，并检查退出代码以查找失败情况。
6. 如果检测到问题，它会立即打印应用的 logcat 日志，包括任何潜在的崩溃堆栈跟踪，这些日志经过美化处理，以显示每个帧的文件名和行号。此外，如果测试执行期间发生“应用程序无响应”（ANR）事件，它还会捕获并报告相关日志。

为了提升集成体验，测试运行器会将 QT 或 Qt Test 环境变量从测试运行器进程的主机环境传递给应用程序，从而确保一致性并实现无缝的测试工作流。

使用测试封装器运行测试

Qt 会为每个 Android 测试生成一个针对特定目标的封装脚本（以测试目标命名），该脚本会使用正确的路径调用 `androidtestrunner `，并将任何额外参数转发给测试二进制文件。下面的示例在特定的模拟器上运行 `tst_android `，转发一个 Qt 环境变量，并仅执行 `testAssets ` 测试用例：

ANDROID_SERIAL=emulator-5554 QT_DEBUG_PLUGINS=1 ./tst_android testAssets

获取结果

默认情况下，如果未显式禁用测试的标准输出（stdout），测试结果会在测试执行过程中打印到主机上。测试运行完成后，任何显式请求的测试文件都会以相应的格式下载到指定的输出路径中。

有关Qt Test 框架的详细信息，请参阅《Qt Test 概述》。

如何使用

运行androidtestrunner 的基本语法如下：

androidtestrunner [ARGUMENTS] -- [TESTARGS]

要在特定设备/模拟器上运行测试，请传入--serial <serial> 参数，或设置adb 环境变量ANDROID_SERIAL 或ANDROID_DEVICE_SERIAL 。显式指定的选项具有优先级。

必填参数

测试运行器始终期望传递以下参数：

• --path <build-path>: Android Gradle 包的构建路径，通常为<build-dir>/android-build-<target> 。
• --make <build-command>: 用于构建测试 APK 的命令，例如cmake --build <build-dir> --target <target>_make_apk 。

  注意：请将 此参数用引号括起来传递 ，这样它才不会被视为测试运行器的多个参数，而是作为--make 参数的值。

• 以下选项之一：
  • --apk <apk-path>: 由构建命令生成并安装在设备上的测试 APK 的路径。
  • --aab <aab-path>：测试 AAB 的路径；需要--bundletool 。这两个选项不能同时设置，且任何一个选项都不得指定多次。

可选参数

您还可以传递以下可选参数：

• --bundletool <path>: Androidbundletool jar 文件的路径。在使用--aab 时为必填项。
• --manifest <path>: 自定义的AndroidManifest.xml 路径。默认使用构建路径或其app/ 子目录下找到的文件。
• --adb <adb-path>: 指定自定义的 ADB 命令路径。默认使用系统$PATH 目录中找到的adb 路径。
• --serial <serial>: 目标 Android 设备的序列号。将覆盖ANDROID_SERIAL 和ANDROID_DEVICE_SERIAL 中的设置。
• --activity <activity-name>: 指定要运行的自定义 Activity。默认为AndroidManifest.xml 中定义的第一个 Activity。
• --timeout <seconds>: 设置测试运行的超时时间。默认值为 600 秒（10 分钟）。
• --pre-test-adb-command <command>: 在安装完成后、测试运行前调用 adb<command> 。可多次传递。
• --skip-install-root: 抑制在构建命令为make-family 工具（make 、gmake 、nmake 、mingw32-make 、jom ；不区分大小写）时，自动在--make 后附加的INSTALL_ROOT=<path> install 后缀。对于cmake 、ninja 或其他构建驱动程序，该后缀永远不会被附加，因此此选项仅对列出的工具有效。
• --ndk-stack <command-path>: 指定用于为崩溃堆栈跟踪添加符号的ndk-stack工具的路径。默认使用位于$ANDROID_NDK_ROOT 下的工具路径。
• --show-logcat: 无论测试是否失败，均将 logcat 输出打印到标准输出（stdout）。读取主缓冲区、系统缓冲区和崩溃缓冲区，并在检测到 ANR 时包含system_server 中的行。
• --verbose: 输出详细日志。
• -- <arguments>: 将破折号后的所有内容作为测试参数传递。
• --help: 显示帮助信息。

使用示例

以下是一个运行tst_android 测试的示例，仅执行testAssets 测试用例：

androidtestrunner \
    --path ~/tst_android/build/android-build-tst_openssl \
    --make "cmake --build ~/tst_android/build --target apk" \
    --apk ~/tst_android/build/android-build-tst_openssl/tst_openssl.apk \
    testAssets