📚 课程目录第3章测试工具链搭建

3. 测试工具链搭建：安装 FrameStats、dumpsys gfxinfo、Systrace、Perfetto，配置 ADB 环境与权限

3.1 适用场景

需要在 AOSP 原生系统或定制 ROM 上执行帧率抖动回归测试。
依赖系统级工具采集 GPU 渲染耗时、vsync 分布、SurfaceFlinger 同步信息。
要求测试前统一各设备工具版本与权限配置，消除环境差异导致的测量噪声。

3.2 前置条件

一台已解锁 Bootloader 的 Pixel / 参考设备，Android 版本 ≥ 10（推荐 12+）。
主机安装 Python 3.8+ 与 adb 命令行（可执行）。
设备已开启“开发者选项”中的 USB 调试、不锁定屏幕、停用 HW overlays（可选）。
系统镜像包含 frameworks/base/core/java/android/view/FrameStats.java 相关服务（AOSP 原生即包含）。

3.3 操作步骤

安装 ADB 并配置环境变量

# macOS / Linux
export PATH=$HOME/platform-tools:$PATH
adb version

# Windows 将 platform-tools 目录加入 PATH

确认设备连接与权限

adb devices -l
adb root          # 仅在 eng/userdebug 版本有效
adb remount       # 挂载 /system 为可写（如需要安装系统级 APK）

安装 FrameStats（使用系统自带的 dumpsys gfxinfo 获取，无需额外 APK）
说明： FrameStats 是 Android 框架层接口，通过 ActivityManager 获取 Window 的帧统计信息。只需保证被测包存在即可。
验证 dumpsys gfxinfo
```
adb shell dumpsys gfxinfo com.example.testapp
```
输出中应有 Total frames、Jank frames、90th percentile 等字段。
启用 Systrace（Android 10 后推荐 Perfetto，但保留 Systrace 作为快速诊断）
```
python systrace.py --time=5 -o trace.html gfx input view sched freq
```
确保主机上已下载 systrace.py（位于 SDK/platform-tools/systrace/）。

安装并验证 Perfetto

# 将 Perfetto 二进制推送到设备
adb push perfetto /data/local/tmp/
adb shell chmod 755 /data/local/tmp/perfetto

# 运行 3 秒测试 trace
adb shell 'cat /data/misc/perfetto-traces/test.pb | /data/local/tmp/perfetto --txt -c - -o /data/misc/perfetto-traces/trace.perfetto-trace'

推荐使用 Perfetto UI 在线解析。

配置权限与固件锁
- 授予 android.permission.READ_FRAME_BUFFER 和 android.permission.ACCESS_SURFACE_FLINGER（需 root 或系统签名）。
- 锁定 CPU/GPU 频率：adb shell echo performance > /sys/devices/system/cpu/cpu0/cpufreq/scaling_governor

3.4 输入输出物

输入物	输出物
设备驱动、USB 数据线	`adb devices` 确认序列号
被测 APK（debug 版本）	`dumpsys gfxinfo [pkg]` 原始日志
Perfetto 命令行配置	`*.perfetto-trace` 二进制 trace 文件
Systrace 配置参数	`trace.html` 可交互时间线

3.5 责任边界

测试工程师： 负责工具安装、权限配置、环境验证；输出工具链就绪检查清单。
系统开发： 提供带 debug 权限的 system image，确保 gfxinfo 服务可用。
QA 负责人： 审核工具版本一致性，处理因厂商定制导致的 API 差异。

3.6 记录材料

记录项	格式	示例
设备序列号与 Android 版本	文本	`ZE2222G8SX / Android 13`
ADB 版本信息	文本	`adb version 1.0.41`
Perfetto 二进制 MD5	哈希	`a3b2c1f4...`
各工具验证截图/日志	TXT/PNG	`v3_tool_verif_log.txt`

3.7 异常处理

异常： adb devices 显示 unauthorized

原因： 未确认 RSA 指纹授权。
解决： 设备上弹窗点击“允许 USB 调试”，重新插拔 USB。

异常： dumpsys gfxinfo 输出为空或 No window stats

原因： 被测应用未开启硬件加速或未处于前台。
解决： 在 Manifest 添加 android:hardwareAccelerated="true"；重新启动 activity。

异常： Perfetto 提示 permission denied for /data/misc/perfetto-traces/

原因： perfetto 进程缺少目录写权限。
解决： adb shell chmod 777 /data/misc/perfetto-traces/ 或使用 /data/local/tmp/ 替代。

异常： Systrace 生成空白 trace

原因： 未启用 atrace 内核模块或未指定正确 category。
解决： 使用 adb shell atrace --list_categories 检查支持项；改用 Perfetto 作为主力。

3.8 验收标准

执行 adb shell dumpsys gfxinfo com.android.chrome 返回 Total frames > 0，无错误输出。
Systrace 生成的 HTML 能在 Chrome 中正常打开，显示 vsync 与 GPU 渲染时间线。
Perfetto trace 文件可通过 ui.perfetto.dev 加载，解析出 gpu_render、surfaceflinger 切片。
所有权限配置一次性通过，无需反复授权。