tox testr 单元测试工作流程详解从环境隔离到并行执行在 OpenStack 等大型 Python 项目中,tox和testr是一对经典组合:tox 负责环境隔离,testr 负责测试仓库 并行执行 历史结果管理。本文系统讲解两者协作的完整工作流程。一、两个工具各做什么工具全称核心职责toxtox标准化的虚拟环境管理 测试编排testrtestrepository测试仓库管理、并行执行、结果持久化一句话概括:tox解决的是「在干净的虚拟环境里跑测试,避免依赖污染」。testr解决的是「几十万测试怎么并行跑、跑完的结果如何归档复用」。tox ↓ 创建/复用虚拟环境 ↓ 执行 commands python setup.py testr --slowest --coverage --testr-args--subunit ↓ 调用 pbr 的 testr 入口 testr run ↓ 读取 .testr.conf ↓ 根据 test_command 启动测试进程 python -m subunit.run discover -t ./ ./tests/unit ↓ 执行测试用例输出 subunit v1 流 ↓ testr 捕获流 ↓ 写入 .testrepository/{next_number} ↓ 合并历史结果 testr last --subunit ↓ 输出最新一次运行的 subunit 流 subunit-trace --no-failure-debug -f ↓ 转换为人类可读的实时输出两者解耦 —— tox 可以单独跑 pytest/nose,testr 也可以独立于 tox 使用。组合起来就形成「环境隔离 高性能并行 结果仓库」的完整闭环。二、tox 工作原理2.1 核心机制tox 读取tox.ini(或pyproject.toml中的[tool.tox]),按其中定义的testenv创建虚拟环境、安装依赖、执行命令。tox.ini ├── [tox] 全局配置 ├── [testenv] 默认环境模板 ├── [testenv:py311] 具名环境:Python 3.11 ├── [testenv:pep8] 具名环境:代码风格检查 └── [testenv:cover] 具名环境:覆盖率2.2 执行步骤1. 解析 tox.ini,确定要运行的 env(默认 [testenv],或 -e 指定) 2. 在 .tox/envname/ 下创建 venv 3. 安装 deps ... 列出的依赖 4. 安装项目本身(pip install .) 5. 执行 commands ... 中的命令 6. 收集退出码,汇总结果2.3 典型 tox.ini[tox] envlist py39,py311,pep8,cover skipsdist False [testenv] usedevelop True setenv VIRTUAL_ENV{envdir} LANGen_US.UTF-8 deps -r{toxinidir}/requirements.txt -r{toxinidir}/test-requirements.txt commands python -m testr run {posargs} [testenv:pep8] deps flake8 commands flake8 {toxinidir}/myproject [testenv:cover] setenv {[testenv]setenv} PYTHONcoverage run --source myproject -m testr run commands coverage erase {env:PYTHON} coverage report coverage html注意commands python -m testr run—— 这就是 tox 把测试执行权交给 testr 的关键。[tox] envlist py27,cover skipsdist False [testenv] deps -r{toxinidir}/requirements.txt -r{toxinidir}/test-requirements.txt testrepository subunit [testenv:cover] setenv VIRTUAL_ENV{envdir} NOSE_WITH_COVERAGE1 commands python setup.py testr --slowest --coverage \ --testr-args--subunittox -ecover --sitepackages -v 各参数含义参数含义-e cover选择执行 cover 环境–sitepackages复用系统已安装的包不重新虚拟化所有依赖-v详细输出三、testr 工作原理3.1 核心概念:testrepositorytestr 在项目根目录维护一个.testr/目录,里面存放:.testr/ ├── config # testr 配置 ├── last # 上次运行的 subunit 流 ├── slowest # 最慢测试列表 ├── failing # 最近失败的测试 └── history # 历史运行记录这是一个持久化的测试仓库,不只是一次性的执行框架。3.2 subunit 协议testr 的核心数据格式是subunit—— 一种二进制/文本混合的测试结果流协议,兼容 xUnit 但更丰富。test: mypackage.tests.test_foo.TestFoo.test_bar success: mypackage.tests.test_foo.TestFoo.test_bar (1.234s)特点:流式传输,边跑边出结果支持多进程汇流(并行测试的多个 worker 写入同一流)兼容 Pythonunittest、pytest、nose等主流框架3.3 .testr.conf[DEFAULT] test_command python -m subunit.run discover -t . $TESTS_DIR test_list_command python -m subunit.run discover -t . $TESTS_DIR --list group_regex ([^\.]\.) test_run_concurrency 1test_command:实际执行测试的命令,subunit.run 是 subrun 的入口,负责输出 subunit 流test_list_command:列出所有可用测试 ID(用于过滤、并行分片)group_regex:把测试按前缀分组,用于并行调度test_run_concurrency并行度3.4 核心参数详解python setup.py testr --slowest --coverage --testr-args--subunit参数含义–slowest测试结束后显示最慢的 10 个用例–coverage自动启用 coverage生成 .coverage 文件–testr-args“–subunit”透传给 testr run让 testr 输出 subunit 流--coverage的工作机制testr 在执行前向 test_command 注入 coverage 包装等价于 python -m coverage run --source -m subunit.run discover …每个测试进程会写自己的 .coverage.{pid} 文件后续脚本 coverage combine 合并所有进程的覆盖率数据四、完整工作流程把 tox 和 testr 串起来,一次tox -e py311的内部流程:┌─────────────────────────────────────────────────────────────┐ │ Step 1: tox 解析 tox.ini,确定运行 envpy311 │ └─────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ Step 2: tox 在 .tox/py311/ 创建虚拟环境 │ │ (若已存在且无 skip-install,直接复用) │ └─────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ Step 3: pip install -r requirements.txt │ │ pip install -r test-requirements.txt │ │ pip install -e . (项目本身,usedevelopTrue) │ └─────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ Step 4: 执行 commands: python -m testr run │ │ 此刻控制权从 tox 转交给 testr │ └─────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ Step 5: testr 读取 .testr/config 获取 test_command │ │ 读取 .testr/history 准备 failing-first 调度 │ └─────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ Step 6: testr 调用 test_list_command 列出全部测试 ID │ │ 按 group_regex 切分,分发给 N 个并行 worker │ └─────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ Step 7: 每个 worker 执行: │ │ python -m subunit.run discover -t . $TESTS_DIR test_ids │ │ 输出 subunit 流到 stdout │ └─────────────────────────────────────────────────────┬───────┘ │ ┌───────────────────────────────────────────────┘ │ (多个 worker 的 subunit 流汇入) ▼ ┌─────────────────────────────────────────────────────────────┐ │ Step 8: testr 把 subunit 流 tee 到: │ │ - .testr/last (上次完整流) │ │ - .testr/history (累积历史,供下次调度) │ │ - 实时渲染到终端 (subunit2py 或 subunit2html) │ └─────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ Step 9: testr 统计 pass/fail/skip,以 exit code 返回 │ └─────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ Step 10: tox 接收到 exit code, │ │ 非 0 则标记 env 失败,汇总到最终结果 │ └─────────────────────────────────────────────────────────────┘五、testr 常用命令# 初始化测试仓库(项目根目录)testr init# 运行全部测试testr run# 运行指定测试(支持正则)testr run mypackage.tests.test_foo# 只跑上次失败的测试(failing-first,加速回归)testr run--failing# 查看上次运行结果testr last# 查看 N 次运行中最慢的测试testr slowest# 列出上次失败的测试testr failing# 在上次失败的基础上再次跑testr run--subunit|subunit-filter --no-success|subunit2pyunit# 把上次的 subunit 流转成 HTML 报告testr last--subunit|subunit2html output.html六、并行执行机制testr 的并行能力是其最大价值之一。流程:1. testr 调用 test_list_command 获取全部 test ID 2. 按 group_regex 把测试分成若干「组」(同组测试不会拆到不同 worker,避免共享 fixture 冲突) 3. 启动 N 个 worker 进程(默认 CPU 核数) 4. 每个 worker 拿到自己的测试子集,通过 test_command 执行 5. 各 worker 的 subunit 流汇入 testr 的总流 6. testr 实时把汇总流写入 .testr/last 和终端配置并发数:# 通过环境变量TESTRUN_CONCURRENCY8testr run# 或在 .testr.conf 中指定[DEFAULT]test_concurrency8注意:并行要求测试之间无共享状态/全局 fixture。如果用setUpClass/setUpModule做数据库初始化,多 worker会各自跑一次,可能造成连接数爆炸。七、subunit 流的处理subunit 是 testr 体系的「血液」。常用管道命令:# 把上次结果中失败的测试抽出来再跑testr last--subunit|subunit-filter --no-success|subunit-run# 实时把 subunit 流转换成人类可读输出testr run--subunit|subunit2pyunit# 转 HTMLtestr run--subunit|subunit2html report.html# 转 JUnit XML(兼容 CI)testr run--subunit|subunit2junitxml junit.xml# 过滤出只跑某个 packagetestr run--subunit|subunit-filter --name-patternmypackage.tests.test_db|subunit-run这是 testr 区别于 pytest 的关键:测试结果是一段可流动的数据,不是固定的报告文件。你可以任意接管道处理。八、最小可运行示例8.1 项目结构myproject/ ├── myproject/ │ ├── __init__.py │ └── foo.py ├── myproject/tests/ │ ├── __init__.py │ ├── test_foo.py ├── tox.ini ├── .testr.conf ├── requirements.txt └── test-requirements.txt8.2 test-requirements.txttestrepository subunit fixtures testtools8.3 .testr.conf[DEFAULT] test_command python -m subunit.run discover -t . myproject/tests $LISTOPT test_list_command python -m subunit.run discover -t . myproject/tests --list8.4 tox.ini│ Step 5 : testr 读取 .testr/config 获取 test_command │ │ 读取 .testr/history 准备 failing-first 调度 │ └─────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ Step 6 : testr 调用 test_list_command 列出全部测试 ID │ │ 按 group_regex 切分,分发给 N 个并行 worker │ └─────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ Step 7 : 每个 worker 执行: │ │ python -m subunit.run discover -t . $TESTS_DIR test_ids │ │ 输出 subunit 流到 stdout │ └─────────────────────────────────────────────────────┬───────┘ │ ┌───────────────────────────────────────────────┘ │ (多个 worker 的 subunit 流汇入) ▼ ┌─────────────────────────────────────────────────────────────┐ │ Step 8 : testr 把 subunit 流 tee 到: │ │ - .testr/last (上次完整流) │ │ - .testr/history (累积历史,供下次调度) │ │ - 实时渲染到终端 (subunit2py 或 subunit2html) │ └─────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ Step 9 : testr 统计 pass/fail/skip,以 exit code 返回 │ └─────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ Step 10 : tox 接收到 exit code, │ │ 非 0 则标记 env 失败,汇总到最终结果 │ └─────────────────────────────────────────────────────────────┘九、failing-first:核心加速技巧testr 的.testr/history记录了每个测试最近的通过/失败状态。下次跑时:testr run --failing会优先调度上次失败的测试,先跑、先报错。如果开发者在改动的就是那部分代码,几秒就能看到红;如果之前的失败已经修好,剩余测试再继续跑。这相当于把「全量回归」的反馈时间从「全部跑完才看到失败」变成「失败先暴露」,在大型项目里收益巨大。十、常见坑坑 1:testr init未执行第一次跑testr run会报No testrepository found。# 解决testr inittox.ini里可以加一行自动初始化:commands testr init testr run {posargs}坑 2:并行下 fixture 冲突例如setUpClass里建表,多个 worker 同时建,数据库报错。解决:把不可并行的 fixture 改成模块级单例 锁或降低test_concurrency1退回串行或用group_regex把相关测试归到同一 worker坑 3:subunit.run找不到测试subunit.run discover默认从当前目录发现,如果TESTS_DIR没设对,会跑空。[DEFAULT] test_command python -m subunit.run discover -t . myproject/tests $LISTOPT # ^^^^^^^^^^^^^^^^^ 明确指定目录坑 4:覆盖率和 testr 一起跑不能直接coverage run testr run,因为 testr 会 fork 子进程,coverage 抓不到。正确做法:[testenv:cover] setenv PYTHONcoverage run --source myproject -m testr run commands coverage erase {env:PYTHON} coverage report把 coverage 作为python 解释器前缀注入,让每个 worker 都在 coverage 下跑。坑 5:Windows 兼容性testr 在 Windows 上偶发问题(并行进程、路径分隔符)。如果必须在 Windows 跑,建议:[testenv] setenv TESTRUN_CONCURRENCY1退回串行,稳定性优先。十一、和 pytest 的对比维度tox testrpytest pytest-xdist环境隔离tox 原生支持需配合 tox 或 nox并行testr 调度,基于 subunitpytest-xdist,worker 进程结果持久化.testr/history,可 failing-first需 pytest-cache 或 --lf流式协议subunit,可流式管道处理原生流式但不可管道组合生态OpenStack 系,偏传统现代主流配置复杂度高(tox.ini .testr.conf)低(pyproject.toml 一处)学习曲线陡平建议:老项目、OpenStack 系、需要 subunit 流生态 → 继续 tox testr新项目、Python 3.10、追求简洁 →tox pytest或nox pytest十二、最佳实践清单.testr/加入.gitignore,但.testr.conf提交CI 中先testr init再tox,避免空仓库报错本地用--failing做快速回归,CI 用全量跑group_regex一定要设,否则并行下共享 fixture 测试会炸覆盖率和并行分开跑,coverage 走单独 envsubunit2html产物归档,方便回溯历史失败不要在 test_command 里写死 worker 数,用环境变量注入,方便 CI 调定期清理.testr/history,长期累积会变慢CI 用testr last --subunit | subunit2junitxml生成 JUnit 报告,Jenkins/GitLab 原生解析大型项目把单元/集成测拆成不同 env,testr 只管单测,集成测用别的工具十三、速查表# 项目初始化 testr init # 全量跑 tox -e py311 # 只跑失败 tox -e py311 -- --failing # 跑指定测试 tox -e py311 -- mypackage.tests.test_foo.TestBar.test_baz # 看上次结果 testr last # 看最慢的 20 个 testr slowest # 转 HTML testr last --subunit | subunit2html report.html # 转 JUnit XML testr last --subunit | subunit2junitxml junit.xml # 重置仓库 rm -rf .testr testr init十四、结语tox testr 的组合,核心是三层解耦:工具优势tox隔离测试环境避免污染系统 Python–sitepackages 复用预装包加速testr支持测试并行按 group_regex 分组自动重跑失败用例subunit 流归档可复现subunit与语言无关的标准测试流格式能被多种工具trace/junitxml/html二次加工这套组合是 OpenStack 生态的标准实践脚本能复用现成的 subunit2junitxml、subunit2html、xunitmerge 工具链。理解了这三层,后续无论是接入 CI、做覆盖率、生成 HTML 报告,都是「在管道上接插件」的事。testr 在新项目里被 pytest取代是大势所趋,但读懂它的设计,对理解大型 Python 项目的测试架构仍有价值。
