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. 退出码说明

测试框架的退出码分为两层：任务级退出码与用例级退出码。

6.1 任务级退出码（`report_info.exit_code`）

表达整个测试任务的最终结果，只区分「成功 / 失败 / 安装失败 / 手机掉线」四类，不带任何具体用例属性：

退出码	含义	说明
0	成功	所有测试用例执行完成，无失败
2	失败	存在失败用例（断言失败/脚本异常/崩溃/ANR 等均归为失败）
3	安装失败	应用安装阶段失败
10	手机掉线	设备离线/初始化失败

6.2 用例级退出码（`test_results[].exit_code`）

表达单个测试用例的具体结果，用于精确定位每个用例的失败原因：

退出码	含义	说明
0	成功	用例通过
2	脚本异常	用例执行过程中抛出非断言的异常
5	脚本断言失败	用例中的断言失败
17	应用崩溃	该用例执行期间检测到应用崩溃
18	应用无响应(ANR)	该用例执行期间检测到应用无响应

退出码显示位置：

任务级：Excel"测试概览"工作表的"退出码"字段、JSON 的 report_info.exit_code
用例级：JSON 的 test_results[].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.5

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.5
File	Size	Uploaded
utest_auto_core-0.3.5.tar.gz	198.4 kB	Sep 10, 2026	Details

Built distribution (wheel)

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

Total release size: 295.6 kB

Release files / utest_auto_core-0.3.5.tar.gz

Download URL	utest_auto_core-0.3.5.tar.gz
Size	198.4 kB
Tags	Source
SHA-256 checksum How to use checksums	`1f0797605dc2e79b1dab628bec2fcf86a0ae15c96b4e3299eb4ae800ae8005f1`
BLAKE2b-256 checksum How to use checksums	`4651841f45fbc0306b4493dc6ff6a9ab13c2cd10ceb9fb0221b3805c9eb0b3af`
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.5-py3-none-any.whl

Download URL	utest_auto_core-0.3.5-py3-none-any.whl
Size	97.2 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`4b1c98cfb5fa8b0cf54fa6f9d36739e3191c12cebe15e97e3621565fcd69e406`
BLAKE2b-256 checksum How to use checksums	`767a4455d25bd3d4cfd01a74c1f8f041d1cfb45e2b6f85cee0dc4373d56dab4f`
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}`