第3章 CTS命令行执行与参数详解：运行 cts-tradefed、常用参数与日志配置

本章聚焦 CTS 测试的核心执行引擎 cts-tradefed，深入讲解其命令行启动方式、关键运行参数（--plan、--shard、--retry）的工作原理、日志输出配置方法以及常见调试与稳定性调优技巧。掌握本章内容后，读者应能独立完成 CTS 测试计划的启动、分片执行、失败重试和日志采集工作。

3.1 cts-tradefed 运行原理

cts-tradefed 是 CTS 测试框架的命令行启动器，本质是一个 Java 进程，负责加载测试配置、调度测试模块、收集结果并输出日志。其核心组件包括：

• 配置加载器（Config Loader）——解析 XML 测试计划（--plan），确定需要执行的模块列表。
• 调度引擎（Tradefed Scheduler）——管理测试任务的并行执行、依赖关系和重试逻辑。
• 结果报告器（Result Reporter）——将测试结果写入 test_result.xml 并生成摘要。
• 日志采集器（Log Collector）——抓取设备 logcat、bugreport 和测试过程日志。

3.2 基本命令格式

在 AOSP 编译环境中，进入 out/host/linux-x86/cts/android-cts/tools/ 目录，执行以下命令启动测试：

./cts-tradefed

进入交互式控制台后，可输入子命令；也可以通过单行模式直接执行：

./cts-tradefed run cts --plan CTS

常用子命令 run cts 表示启动 CTS 测试计划。下表列出了三种执行模式的区别：

3.3 核心参数详解

3.3.1 --plan：指定测试计划

--plan 参数用于选择 CTS 测试计划，决定了哪些测试模块会被执行。AOSP 预置了多种计划：

3.3.2 --shard：测试分片与并行

--shard 参数将测试计划拆分为多个子集，分发到多台设备并行执行，显著缩短总耗时。其工作原理如下：

• 调度器按照模块粒度进行分片，每个 shard 包含约均等的测试模块数。
• 每台设备同时只能运行一个 shard，多台设备并行处理不同 shard。
• 所有 shard 执行完毕后，自动合并结果并生成统一报告。

使用示例：

# 在 4 台设备上并行执行 CTS 计划
./cts-tradefed run cts --plan CTS --shard 4

分片数量建议与可用设备数量保持一致。若设备数少于 shard 数，多余的 shard 会排队等待。

3.3.3 --retry：失败模块自动重试

--retry 参数用于对上一轮失败的测试模块进行重新执行，避免因环境抖动导致假阳性结果。重试逻辑如下：

1. 读取上一轮测试生成的 test_result.xml，提取所有 FAIL 和 MODULE_ERROR 的模块。
2. 仅针对这些失败模块执行测试，不重复运行已通过的模块。
3. 重试结果追加到原报告中，更新最终 verdict。

执行命令：

# 重试上一轮测试中失败的模块
./cts-tradefed run cts --retry

也可指定重试次数（通过 --retry-count）：

./cts-tradefed run cts --plan CTS --retry --retry-count 3

3.4 日志输出配置

CTS 的日志体系包含三个层级，理解它们有助于快速定位问题：

可通过以下方式控制日志输出级别：

# 调整 Tradefed 日志级别为 VERBOSE
./cts-tradefed run cts --plan CTS --log-level VERBOSE

# 同时保存 logcat 到指定文件
./cts-tradefed run cts --plan CTS --logcat-on-failure

3.5 常见错误与快速定位

• Error: "No devices found" —— 检查 adb devices 输出，确认 USB 连接或 TCP/IP 连接正常。重新插拔或执行 adb kill-server; adb start-server。
• Error: "Plan not found: xxx" —— 确认 --plan 参数名称正确，且对应的 XML 文件存在于 android-cts/testcases/ 目录。
• Error: "Shard count exceeds available devices" —— 减少 --shard 数值，使其不超过在线设备总数。
• Error: "Retry failed: no previous result" —— 确认 logs/

3.6 稳定性与性能优化建议

1. 内存预算：cts-tradefed 进程默认堆内存为 2GB，大规模测试时可调整为 4GB：export JAVA_OPTS="-Xmx4096m"。
2. 设备温控：长时间高负载测试会导致设备过热降频，建议使用散热底座或风扇，并将测试环境温度控制在 25±3°C。
3. 日志轮转：在 tradefed.log 中增加按天/大小轮转配置，避免单个日志文件过大导致磁盘写满。
4. 结果归档：每次测试后使用脚本将 logs/ 目录压缩归档，命名规则：CTS_YYYYMMDD_HHMMSS_<build_id>.zip，便于历史回溯。