UTest 自动化测试框架 - 快速上手
本框架基于 ubox-py-sdk，提供简洁的测试用例编写与执行能力：步骤与断言、截图、录制、logcat 采集、性能采集与报告导出等。
1. 环境与安装
- Python 3.9+（推荐按 run.sh 中方式创建虚拟环境）
- 依赖通过 requirements.txt 安装
安装依赖（清华源示例）：
uv pip install -U -r requirements.txt --index-url https://pypi.tuna.tsinghua.edu.cn/simple
2. 基础配置（config.yml）
关键项：
- task.serial_num：设备序列号
- task.os_type：android | ios | hm
- task.app_name：被测应用包名或安装包
- test.selected_tests：要执行的用例名称列表（为空执行全部）
- test.selected_dir：要执行的测试用例目录路径（相对于test_cases目录，如"test-a"或"test-a/b"，为空执行全部）
用例选择优先级：resource参数 > test.selected_tests > test.selected_dir（高优先级覆盖低优先级）
3. 运行测试
- 更改配置文件后直接运行（读取 config.yml）：
uv run start_test.py
执行后输出目录：
- test_result/log/<用例名>/：用例日志（perf.json、logcat.txt 等）
- test_result/case/<用例名>/pic/：截图
- Excel 报告：在 test_result/log 根目录生成
4. 如何编写用例
参考：
- 真实业务：test_cases/user_tests_0.py（腾讯视频小游戏）
- Demo：test_cases/user_tests_1.py（框架能力演示）
示例骨架：
from core.test_case import TestCase, StepStatus, FailureStrategy
from ubox_py_sdk import Device
class MyTest(TestCase):
def __init__(self, device: Device):
super().__init__(name="我的用例", description="用例描述", device=device)
self.failure_strategy = FailureStrategy.STOP_ON_FAILURE
def setup(self):
# （可选）启动被测应用
pkg = self.get_package_name()
if pkg:
self.start_step("启动应用", f"启动: {pkg}")
ok = self.device.start_app(pkg)
self.assert_true("应用应成功启动", ok)
self.end_step(StepStatus.PASSED if ok else StepStatus.FAILED)
# 录制（路径自动记录到结果）
self.start_record()
# logcat（仅记录文件路径，不需要手动停止）
self.start_logcat()
def run_test(self):
# 步骤与断言
self.start_step("准备场景", "示例")
self.assert_true("环境应就绪", True)
self.end_step(StepStatus.PASSED)
# 关键阶段开启性能采集
self.start_step("开启性能采集", "开始perf")
started = self.start_perf()
self.assert_true("性能采集应成功启动", started)
self.end_step(StepStatus.PASSED if started else StepStatus.FAILED)
# 业务操作...
# ...
# 停止性能采集：停止后自动解析 get_log_dir()/perf.json
self.stop_perf()
def teardown(self):
# 停止录制
self.stop_record()
# （可选）关闭应用并回到桌面
pkg = self.get_package_name()
if pkg:
self.device.stop_app(pkg)
self.device.press("HOME")
要点与要求：
- 用例名称/描述：在 init 的 name、description 设置。
- 步骤管理：start_step/end_step；在步骤内断言失败会自动标记结果，end_step 不是必须显式调用，但建议在成功路径显式结束以便报告更清晰。
- 断言：assert_true、assert_equal、assert_contains 等；失败按策略决定是否中断。
- 截图：失败/通过（可配置）时自动截图，也可随时 take_screenshot("name")。
- 录制：start_record()/stop_record()；只记录文件路径，报告展示。
- logcat：start_logcat()；记录输出文件路径（logcat.txt），报告展示。
- 性能：start_perf()/stop_perf()；设备端在停止时写入 get_log_dir()/perf.json，框架自动解析并汇总 FPS/Jank/CPU/GPU/温度/功耗/内存/网络等指标到报告。
5. 报告
- 自动生成 Excel 报告，包含：
- 用例信息与状态
- 步骤详情与截图
- 录制与 logcat 文件路径
- 性能监控关键指标（从 perf.json 解析的汇总）
- 整体退出码（用于判断测试执行结果）
6. 退出码说明
测试框架执行完成后会返回特定的退出码，用于判断测试执行的具体结果：
| 退出码 | 含义 | 说明 |
|---|---|---|
| 0 | 成功 | 所有测试用例执行完成，无异常 |
| 2 | 其他脚本异常 | 测试执行过程中发生未预期的异常 |
| 3 | 安装失败 | 应用安装阶段失败 |
| 5 | 脚本断言失败 | 测试用例中的断言失败 |
| 17 | 应用崩溃 | 检测到应用崩溃事件 |
| 18 | 应用无响应(ANR) | 检测到应用无响应事件 |
退出码会在以下位置显示：
- Excel报告的"测试概览"工作表中的"退出码"字段
- JSON报告的
report_info.exit_code字段
7. 建议
- 步骤小而清晰、断言贴近业务、仅在关键路径采集性能、出错即截图便于复盘。
编译
uv build
发布包
uv publish --publish-url https://mirrors.tencent.com/repository/pypi/tencent_pypi/simple
uv publish
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
utest_auto_core-0.3.2.tar.gz
(194.5 kB
view details)
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file utest_auto_core-0.3.2.tar.gz.
File metadata
- Download URL: utest_auto_core-0.3.2.tar.gz
- Upload date:
- Size: 194.5 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via:
uv/0.11.2 {"installer":{"name":"uv","version":"0.11.2","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
2c255cf454a12c88734d326175ccf1a97c18e40005988c7500dd53581cb6ef5b
|
|
| MD5 |
bc32dfd87bb3207ef19be1d17304daee
|
|
| BLAKE2b-256 |
a5ae3fc329ec2051029e597c07b7b371f80291810b23622fa9cbe8a8e3ac478b
|
File details
Details for the file utest_auto_core-0.3.2-py3-none-any.whl.
File metadata
- Download URL: utest_auto_core-0.3.2-py3-none-any.whl
- Upload date:
- Size: 94.2 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via:
uv/0.11.2 {"installer":{"name":"uv","version":"0.11.2","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
0da5b4a8ff4b7edcdf83d59ae69705cc72a78e85bd0a3d9c5e518211e52e7cf8
|
|
| MD5 |
03ddd49cc29a8c1e78c58710bc58f610
|
|
| BLAKE2b-256 |
c5c414743b8c6f454f6e3f03d6129133d948db2c329ba4a6e1d6c9088c18b667
|
