utest-auto-core

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

Metadata

Release files for utest-auto-core 0.3.4

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for utest-auto-core 0.3.4
File	Size	Uploaded
utest_auto_core-0.3.4.tar.gz	196.9 kB	Sep 10, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for utest-auto-core 0.3.4
File	Interpreter	ABI	Platform	Reset
utest_auto_core-0.3.4-py3-none-any.whl 95.9 kB Sep 10, 2026	Python 3	none	any	Details

Total release size: 292.8 kB

Release files / utest_auto_core-0.3.4.tar.gz

Download URL	utest_auto_core-0.3.4.tar.gz
Size	196.9 kB
Tags	Source
SHA-256 checksum How to use checksums	`e5f2938fd445f30e16a07fdaafb22bb01e810f6ad4a57e508930bbfc6e0c3eb9`
BLAKE2b-256 checksum How to use checksums	`be2cc58d86b7a4b76e90c0269a22e8043ca933d6d5bf4e4c34e4143d9d3cff06`
Upload date	Sep 10, 2026
Uploaded using Trusted Publishing? What is 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}`

Release files / utest_auto_core-0.3.4-py3-none-any.whl

Download URL	utest_auto_core-0.3.4-py3-none-any.whl
Size	95.9 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`ecf2842cd42cd1fd15742d294a0eddb990cba7028a4d3f3d2645afaa784b9b29`
BLAKE2b-256 checksum How to use checksums	`23aa01d355f5d53744530140b9c39047ac6237e6fed237f30c6ad0481a2ce5e7`
Upload date	Sep 10, 2026
Uploaded using Trusted Publishing? What is 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}`