OmniLab ATS is a testing tool that Android developers and test engineers can use to employ a user interface for running standard Android test suites, such as the Android Compatibility Test Suite (CTS). This tool acts as a web interface for various test frameworks, such as Trade Federation (TF) and Google Mobly, allowing you to run CTS and multi-device tests on a set of test devices with minimal setup, as well as establish a schedule to continuously run tests.
Set up OmniLab ATS
This section explains how to install and set up OmniLab ATS.
OmniLab ATS uses source code from these locations
- OmniLab ATS 源代码
- TradeFed Cluster 源代码
Install OmniLab ATS
请遵循您运行的测试套件的任何硬件和软件要求。
CTS 的要求请见 source.android.com。
OmniLab ATS 没有额外的硬件要求，但我们建议使用 CTS 主机要求 作为起点。
安装 OmniLab ATS 有两种方法
使用安装程序安装
在 Ubuntu 20.04+ 上，安装程序会安装和配置运行 OmniLab ATS 所需的所有程序和资源。
要使用安装程序
运行安装程序
curl https://storage.googleapis.com/android-mtt.appspot.com/prod/install.sh | bash
运行
mtt version以检查 OmniLab ATS CLI 的已安装版本。
手动安装
安装 Docker
按照 安装后步骤以非 root 用户身份管理 Docker 进行操作。
您可能需要重启终端窗口或注销并重新登录，权限更改才能生效。
安装 Python 3
OmniLab ATS CLI 已针对 Python 3.7 到 3.11 版本进行验证。
对于 Ubuntu 16.04 或更早版本，请先通过执行以下操作之一来添加 Python 3 的存储库
运行此命令
sudo add-apt-repository ppa:deadsnakes/ppa
从 源代码 构建并安装存储库。
要安装 Python 3，请运行以下命令
sudo apt-get updatesudo apt install python3 python3-distutils
要安装特定的 Python 3 版本（例如 3.10），请改为运行以下命令
sudo apt-get updatesudo apt install python3.10 python3.10-distutils
获取 OmniLab ATS CLI
启动 OmniLab ATS
使用以下命令启动 OmniLab ATS
mtt start
首次启动 UI 时，可能需要几分钟才能出现。CLI 会显示一个 Web URL，用于在浏览器中访问 UI。默认情况下，Web URL 为 localhost:8000。如果需要，您可以使用 --port 标志在启动时更改默认端口。
如果有更新的版本可用，您可以更新到当前版本。您可以查看 发行说明 以获取最新版本。
要更新到当前版本，请运行
mtt start --force_update
要停止应用，请运行
mtt stop
要查看其他命令列表，请使用
mtt --help
备份和恢复数据库
要备份 OmniLab ATS 数据库，请停止应用并运行以下命令，该命令会将当前数据库备份到您主目录中名为 mtt-backup.tar 的 TAR 文件中
docker run --rm --mount source=mtt-data,target=/data -v ~:/out ubuntu bash -c "cd /data && tar cvf /out/mtt-backup.tar ."
要恢复，请在启动应用之前运行以下命令
docker run --rm --mount source=mtt-data,target=/data -v ~:/out ubuntu bash -c "cd /data && tar xvf /out/mtt-backup.tar"
设置向导
首次安装并运行 OmniLab ATS 后，设置向导将引导您完成几个步骤，以帮助您为您的环境自定义该工具。您在此处所做的任何更改都可以在以后通过“设置”页面重新配置。
恢复配置备份
如果您有从另一个 OmniLab ATS 主机备份的配置文件，您可以上传该文件以复制从该主机修改的任何配置，方法是单击上传文件按钮。
图 1. 恢复配置备份。
设置默认服务帐号
您可以设置一个 服务帐号，OmniLab ATS 在访问您的资源（例如，Google Cloud Storage、Google Drive）时默认使用该帐号。要验证您的服务帐号，请单击上传服务帐号密钥，然后选择您的服务帐号的 JSON 密钥文件。
图 2. 设置服务帐号。
服务帐号成功验证后，帐号电子邮件地址将显示在页面右上角。要更改服务帐号，请单击帐号名称，删除当前的默认帐号，然后上传新的服务帐号密钥。
图 3. 更改服务帐号。
导入配置集
配置集是用于运行测试套件的配置捆绑包，包括相关的设备操作和构建渠道。配置集托管在特定的 Google Cloud Storage (GCS) 存储桶中。使用您的 Google 帐号验证 GCS 构建渠道后，您将看到所有可供您使用的配置集列表。
选择您要添加到 Test Station 主机的任何配置集，然后单击导入所选。
图 4. 导入配置集。
包括 Wi-Fi 设置
某些 CTS 测试需要您的设备连接到 Wi-Fi 热点。要选择您的 Wi-Fi 网络，请输入WiFi SSID 和可选的 WiFi PSK。
图 5. Wi-Fi 热点设置。
完成设置向导后，页面将重新加载并应用新设置。
连接设备
必须启用 USB 调试才能使用设备进行测试。要启用调试
请按照 启用开发者选项和调试 中的说明进行操作。
如果您计划使用预加载了自定义 ADB 密钥的测试 Android 版本，请将自定义
.adb_key文件放在~/.android/目录下。这些文件会自动加载并传递给 ADB，以便在为运行这些版本的设备刷机后自动启用 USB 调试。
使用 USB 将设备连接到主机。
设备将在刷新 Web 界面后一分钟内出现在 OmniLab ATS 设备选项卡中。您还可以在此选项卡上查看设备的状态。
图 6. 连接设备。
不同的设备状态为
- 可用 - 设备已连接并准备好运行测试。
- 已分配 - 设备已连接并且正在运行测试。每个设备一次只能运行一个测试，因此设备必须完成当前测试才能运行新测试。
运行测试
选择测试
OmniLab ATS 随附一组预捆绑的 CTS 配置。要运行其中一项测试，请转到“测试套件”选项卡，然后单击所选测试的运行测试。
图 7. 选择测试。
要编辑或添加新测试，请参阅添加测试。
配置测试运行
编辑用于此特定测试运行的参数。大多数参数都预先填充了在所选测试配置中定义的值。
此步骤可以使用默认值完成，但您可以更改任何参数，例如最大重试次数和命令，以满足您的需求。
图 8. 配置测试运行。
测试运行参数为
- 名称 - 您要运行的测试套件的名称。
- 运行计数 - 计划运行时应执行此测试运行的次数。测试运行使用 Trade Federation 进行计划，如果容量允许，它可以并行运行最多 20 个测试运行。
- 最大重试次数 - 如果至少一个测试失败，则重试测试运行的最大次数。对于完整的 CTS 运行，这通常设置为 4-6 次重试，以处理不稳定的测试。
- 队列超时 - 如果测试运行在已排队状态中停留时间过长，它将自动取消。在此处指定取消前等待的时间量。默认值为 24 小时。
命令 - 运行测试套件的命令。您可以在此处输入其他命令行参数。例如，在 CTS 8.1 中运行特定模块，使用
cts-suite -m ShortModuleName重试命令 - 用于重试测试套件的命令。您可以在此处添加其他命令行参数。例如，要仅重试 CTS 8.1 中的特定模块，请使用
cts --retry 0 -m ShortModuleName重试参数可能与初始命令可用的参数不同，因此请查看官方网站上所选测试套件的受支持参数。
之前的测试运行 - 如果您想重新运行之前的测试运行
本地 - 如果运行是在当前主机上启动的，请输入查看测试运行详细信息时看到的测试运行 ID。
图 9. 本地之前的测试运行。
远程 - 如果运行是在不同的主机上启动的，请通过选择远程、单击上传测试结果文件并从本地存储中选择文件来上传测试结果文件。
图 10. 远程之前的测试运行。
选择设备
单击复选框以选择要分配用于运行测试套件的设备。分片计数应自动更改以匹配所选设备的数量。
图 11. 选择设备。
要通过设备序列号以外的属性选择设备，您可以手动输入“设备规格”。例如，要选择 3 个产品名称为“bramble”的设备，请输入以下内容
product:bramble;product:bramble;product:bramble
受支持的属性为
- build_id
- device_serial
- device_type
- hostname
- product
- product_variant
- sim_state
所有选定的设备都必须处于可用状态才能执行测试运行，并且当测试运行执行时，它们都会切换到已分配状态。测试运行在等待设备变为可用状态时处于已排队状态。
添加设备操作
设备操作是在每次测试运行之前可以执行的脚本。某些设备操作已配置，例如刷机和重启。要创建新的设备操作，请参阅创建新的设备操作。
图 12. 设备操作。
要将设备操作添加到测试运行，请单击添加新操作，选中要添加的操作的复选框，然后单击添加操作。设备操作按顺序执行。您可以通过拖动操作来重新排序。
图 13. 重新排序操作。
设置测试资源
测试资源是执行测试运行所需的文件。例如，运行 CTS 需要 android-cts*.zip 文件，而刷机设备需要您提供构建映像。
测试套件 zip 文件的下载 URL 应默认为提供给合作伙伴的 Google Drive 链接。您可以通过单击浏览来选择其他文件。在弹出窗口中，您可以输入文件下载链接，使用来自已验证构建渠道的文件，或上传文件以从本地存储中使用。
图 14. 测试资源。
以下是通过 Web URL 选择测试资源的弹出窗口。您可以输入下载 URL 链接，然后单击选择按钮以确认选择。
图 15. 测试资源选择器 - Web URL。
如果您已将资源上传到 Google Drive、Google Cloud Storage (GCS) 或其他渠道，您也可以导航到特定渠道的选项卡并在那里选择资源。以下是从 Google Drive 选择资源的示例。
图 16. 测试资源选择器 - Google Drive。
除了仅选择文件外，文件名字段还支持通配符。文档可以在 此处 找到。
图 17. 测试资源选择器 - 通配符模式支持。
您还可以从 OmniLab ATS 的本地文件存储中选择文件。您可以将文件上传到此存储中，或直接使用本地文件和目录。
图 18. 测试资源选择器 - 本地文件存储。
添加重新运行配置
您可以计划在主运行完成后启动并加载其结果的重新运行，但可以使用不同的设备、操作或资源。
图 19. 添加重新运行配置。
开始测试运行
在您输入测试运行所需的信息后，单击开始测试运行。如果所有信息都有效，则测试运行开始，并且您将被重定向到一个页面以查看测试运行的详细信息和进度。
图 20. 开始测试运行。
创建测试计划
测试计划用于创建定期计划的测试运行。例如，每天下午 5 点运行 CTS 9.0。要创建新的测试计划，请单击创建新的测试计划。
图 21. 创建测试计划。
配置测试计划
输入测试计划的名称以及您要添加的任何标签。然后选择要使用的计划。
- 手动 - 测试计划仅在用户在测试计划列表页面中单击运行测试计划时才创建测试运行。
- 定期 - 测试计划根据所选的定期计划自动计划测试运行。例如，计划每天下午 5:00 运行测试。
- 自定义 - 测试计划根据输入的 cron 表达式 自动计划测试运行。例如，要计划每天下午 5:00 运行测试，cron 表达式为
0 17 * * *。
图 22. 配置测试计划。
添加测试套件
通过单击+ 添加测试运行配置，添加您希望由测试计划计划的测试套件。从名称下拉列表中选择一个测试套件，然后单击下一步。然后选择您想要在其上运行测试的设备，然后单击添加配置。您可以为每个测试计划添加多个配置。
图 23. 配置测试运行。
添加设备操作
添加您希望在每次测试运行之前执行的设备操作。有关更多详细信息，请参阅添加设备操作。
图 24. 添加设备操作。
设置测试资源
将测试资源添加到测试计划与将其添加到单个测试运行相同。有关更多详细信息，请参阅设置测试资源。
图 25. 设置测试资源。
查看测试运行
测试运行列表
在“测试运行”页面上查看计划的测试运行列表。单击查看以查看有关测试运行的更多详细信息。
您还可以通过在过滤器栏中输入字符串并按 Enter 键来过滤列表。您可以使用多个过滤器，方法是用逗号分隔它们。过滤器返回在任何列（不包括状态和创建时间）中包含完全文本（无子字符串匹配）的所有行。
空过滤器返回所有行。目前没有办法过滤具有空值的行。
图 26. 测试运行列表。
测试运行详细信息
您可以在此处查看测试运行的详细信息，例如状态、日志和结果。
图 27. 测试运行详细信息。
测试运行状态
测试运行的进度显示在“状态”部分中。如果存在相关消息，例如下载进度、取消原因或错误消息，也会在此处显示。
图 28. 测试运行状态。
测试运行状态为
- 待处理 - 正在下载所需的资源。
- 已排队 - 当设备变为可用时，测试已准备好运行。
- 正在运行 - 测试正在已分配的设备上运行。
- 已完成 - 测试已完成并报告了其结果。
- 已取消 - 测试已被用户取消或在尝试查找可用设备时超时。
- 错误 - 发生错误，阻止了测试运行。
取消测试运行
如果测试运行尚未完成，您可以通过单击取消，然后在确认对话框中单击是来取消它。如果测试运行在已排队状态中停留的时间超过 queue_timeout_seconds 字段，也会自动取消。取消正在运行状态下的测试运行可能需要几分钟才能生效。
图 29. 取消测试运行。
测试运行结果
测试运行完成后，将收集并显示结果。您可以通过单击每次运行的箭头来查看更多详细信息。单击查看输出文件以查看收集的测试工件，例如 test_result.xml 和 test_result_failures.html。
图 30. 测试运行结果。
您可以在“日志”选项卡中查看实时主机和 Tradefed 日志。
图 31. “日志”选项卡。
各个模块的结果位于“测试结果”选项卡上。
图 32. “测试结果”选项卡。
您可以通过单击“测试资源”选项卡中的打开来下载用作测试资源的文件。
图 33. “测试资源”选项卡。
要查看测试运行的详细信息（例如create_time），请转到“配置”选项卡。
图 34. “配置”选项卡。
高级功能
管理配置文件
OmniLab ATS 使用以 YAML 编写的配置文件来加载预定义的选项，例如测试、构建渠道和设备操作。这是一个配置文件示例
// example_file.yaml
tests:
- id : android.cts.9_0.arm
name: CTS 9.0 (ARM)
test_resource_defs:
- name: android-cts.zip
default_download_url: https://dl.google.com/dl/android/cts/android-cts-9.0_r7-linux_x86-arm.zip
test_resource_type: TEST_PACKAGE
command: cts
env_vars:
- name: TF_PATH
value: ${TF_WORK_DIR}/android-cts/tools:${TF_WORK_DIR}/android-cts/testcases
- name: LD_LIBRARY_PATH
value: ${TF_WORK_DIR}/android-cts/lib:${TF_WORK_DIR}/android-cts/lib64
setup_scripts:
output_file_patterns:
- android-cts/logs/latest/.*
- android-cts/results/latest/.*\.html
- android-cts/results/latest/compatibility_result\..*
- android-cts/results/latest/logo.png
- android-cts/results/latest/test_result.xml
result_file: test_result.xml
java_properties:
- name: CTS_ROOT
value: ${TF_WORK_DIR}
context_file_dir: android-cts/results/
context_file_pattern: '[\d_\.]+\.zip'
retry_command_line: retry --retry 0
runner_sharding_args: --shard-count ${TF_SHARD_COUNT}
build_channels:
- id: google_drive
name: Google Drive
provider_name: Google Drive
device_actions:
- id: flash
name: Flash
test_resource_defs:
- name: bootloader.img
test_resource_type: DEVICE_IMAGE
- name: radio.img
test_resource_type: DEVICE_IMAGE
- name: img.zip
test_resource_type: DEVICE_IMAGE
tradefed_target_preparers:
- class_name: com.android.tradefed.targetprep.RunHostCommandTargetPreparer
option_values:
- name: work-dir
values:
- ${TF_WORK_DIR}
- name: host-setup-command
values:
- adb -s $SERIAL reboot-bootloader
- fastboot -s $SERIAL flash bootloader bootloader.img
- fastboot -s $SERIAL flash radio radio.img
- fastboot -s $SERIAL reboot-bootloader
- fastboot -s $SERIAL -w update img.zip
- adb -s $SERIAL wait-for-device
- name: host-cmd-timeout
values:
- 10m
当您设置 OmniLab ATS 实例时，您可以通过将其导出为文件来与其他用户共享您的配置。为此，请转到“设置”页面，然后单击右上角的导出。
图 35. 配置文件管理。
下载配置文件后，与其他用户共享该文件。他们可以通过单击导入并选择配置文件，将配置文件添加到他们的 OmniLab ATS 实例。
创建新的设备操作
设备操作用于自动化设备设置过程。操作是在每次测试运行之前，包括重试之前，在测试运行的每个设备上执行的脚本。要查看可用设备操作的列表，请转到“设置”页面，然后单击“设备操作”选项卡。一些设备操作已配置，例如重启和刷机。
图 36. “设备操作”选项卡。
添加新的设备操作
单击新建设备操作。
图 37. “新建设备操作”按钮。
输入名称和描述。
图 38. 设备操作名称。
单击添加目标准备器。
输入 Trade Federation 目标准备器的完整类名，例如
com.android.tradefed.targetprep.RunHostCommandTargetPreparer。
图 39. 添加目标准备器。
可在 com.android.tradefed.targetprep 参考中找到可用目标准备器的列表。
图 40. 目标准备器列表。
添加任何要与目标准备器一起使用的选项。要查看可用选项，请查看 AOSP 中每个目标准备器的源代码 targetprep
图 41. 操作选项示例。
要添加选项，请单击添加目标准备器选项并输入所需的值。
图 42. 操作命令示例。
定义执行设备操作所需的测试资源，例如，用于刷机的构建映像。要添加资源定义，请单击添加测试资源并填写必填字段。如果您知道文件的位置，您可以通过单击浏览来提供默认下载 URL。如果目标准备器接受目录作为测试资源，请选择解压缩。然后指定临时工作目录下的相对目标目录和要解压缩的文件名。如果未给出文件名，则将从测试资源中解压缩所有文件。
图 43. 操作测试资源。
单击更新。
图 44. 操作保存更改。
管理测试
编辑测试
要编辑已保存的测试，请转到“测试”页面，然后单击要修改的测试行上的编辑。更改测试配置后，单击更新。
图 45. 编辑测试。
添加新测试
要添加新测试，请转到“测试”页面，然后单击创建新测试。输入相应的信息，然后单击创建。
图 46. 创建测试。
图 47. 复制测试。
导出主机配置
配置主机后，您可以将主机的配置导出到文件。您可以将此文件上传到其他主机以复制已保存的配置。
要导出主机的配置，请转到“设置”页面，然后单击右上角的导出。
图 48. 导出主机配置。
要导入主机配置文件，请转到“设置”页面，然后单击右上角的导入。
图 49. 导入主机配置。
使用本地文件和目录
从 R11 版本开始，$HOME/.ats_storage 目录中的文件在 OmniLab ATS 中自动可访问。将文件复制或移动到该目录中，然后您可以在计划测试运行时从本地文件选项卡中选择它。
cp /path/to/file $HOME/.ats_storage
图 50. 从 $HOME/.ats_storage 目录中选择文件。
您可以使用 --mount_local_path 标志将其他目录挂载到本地文件存储中。
mtt start --mount_local_path=/path/to/dir1 --mount_local_path=/path/to/dir2:renamed_dir2
图 51. 本地文件存储中挂载的其他目录。
启用多主机模式
使用多主机模式，用户可以使用单个 ATS 控制器主机来管理多个 ATS 工作器主机上的设备和测试。
图 52. 多主机模式架构。
要启动 ATS 控制器，请使用以下命令
mtt start --operation_mode=ON_PREMISE检查控制器是否可通过
http://${CONTROLLER_HOSTNAME}:8000访问。要启动工作器，请使用以下命令
mtt start --control_server_url=http://CONTROLLER_HOSTNAME:8000 --operation_mode=ON_PREMISE
如果您的网络不允许主机彼此通信，您需要在 ATS 工作器上按照下面更高级的设置说明进行操作。
使用 SSH 隧道连接两个主机。选择主端口和文件服务器端口，例如 9000 和 9006。
ssh -L ATS_PORT:localhost:8000 -L FS_PORT:localhost:8006 CONTROLLER_HOSTNAME配置并启动 ATS。
DOCKER_GATEWAY_IP_ADDRESS=$(ip -4 addr show dev docker0 | grep -Eo 'inet [.0-9]+/' | grep -Eo '[.0-9]+')socat tcp-listen:ATS_PORT,bind="${DOCKER_GATEWAY_IP_ADDRESS}",reuseaddr,fork tcp-connect:127.0.0.1:ATS_PORT &socat tcp-listen:FS_PORT,bind="${DOCKER_GATEWAY_IP_ADDRESS}",reuseaddr,fork tcp-connect:127.0.0.1:FS_PORT &mtt start --control_server_url=http://${DOCKER_GATEWAY_IP_ADDRESS}:ATS_PORT \ --control_file_server_url=http://${DOCKER_GATEWAY_IP_ADDRESS}:FS_PORT \ --operation_mode=ON_PREMISE
文件清理器
文件清理器是一个 cron 作业，每小时运行一次，以根据用户定义的配置清理文件。ATS 有两个默认配置来存档测试运行结果和删除临时文件。本指南介绍如何自定义策略和配置以有效地管理您的文件。
策略
策略定义要对文件或目录执行的操作，以及选择目标的条件。下表显示了可用的操作
| 操作类型 | 参数 |
|---|---|
存档 | remove_file：如果为 true，则在存档后删除文件。 |
删除 |
条件基于文件属性和系统信息。下表显示了可用的条件
| 条件类型 | 描述 | 参数 |
|---|---|---|
LAST_MODIFIED_TIME | 根据文件的上次修改日期和时间过滤文件。 | ttl：支持各种类型的时间表达式，例如 10m、2h、7 days、4w。有关支持的格式，请参阅 pytimeparse。 |
LAST_ACCESS_TIME | 根据文件的上次访问日期和时间过滤文件。 | 与 LAST_MODIFIED_TIME 相同。 |
NAME_MATCH | 使用正则表达式根据文件名过滤文件。 | pattern：正则表达式，例如，[a-f0-9]{8}-([a-f0-9]{4}-){3}[a-f0-9]{12}\.zip 以匹配结果 zip 文件。 |
SYSTEM_AVAILABLE_SPACE | 根据系统上的可用空间触发操作。 | threshold：当可用空间低于阈值时触发操作，例如 200(B)、200KB、200MB、200GB、2TB。 |
图 53. 添加新的文件清理器策略。
配置
配置将一个或多个策略与特定目录组合在一起。指定目录中的文件和目录将根据定义的策略进行处理。策略按照它们在配置中出现的顺序应用。
所有目标目录都必须位于 /data 目录下。如果您的配置将目标目录指定为 logs，则它将被解释为 /data/logs。
图 54. 编辑文件清理器配置。
重置
单击重置设置会将文件清理器配置恢复为其默认状态。此操作会清除所有自定义项目。
图 55. 重置文件清理器设置。
支持
错误报告
您对 OmniLab ATS 的贡献有助于改进该工具的开发，我们希望听到您的意见！请参阅 OmniLab ATS 发行说明，了解有关最新版本的详细信息。要报告错误或提供建议，请提交错误报告。合作伙伴应使用其合作伙伴渠道报告错误或建议。