用 pytest 钩子标记未分类测试并在 CI 中强制失败
用 pytest 钩子标记未分类测试并在 CI 中强制失败
问题场景
测试集规模变大之后,慢测试和集成测试往往和普通单元测试混在一起。团队约定用 @pytest.mark.slow、@pytest.mark.integration 做分类,但新写的用例经常忘记加标记。代码评审靠人眼看,漏掉一两个很常见;一旦漏掉,本地跑全量测试就会被动拉长反馈时间。
更麻烦的是,这类问题不会报错,只会悄悄拖慢流水线。需要一个自动化的门禁:只要存在没有显式分类标记的用例,CI 就直接失败,并把清单打印出来。
解决思路
pytest 在收集完成后会调用 pytest_collection_modifyitems 钩子,此时可以拿到本次收集到的全部 Item。在钩子里检查每个用例的 own_markers,如果除了 skip、parametrize 这类内置标记之外没有任何显式分类标记,就给它补一个自定义的 unmarked 标记。
CI 中再执行 pytest -m unmarked,配合一个环境变量开关,让钩子在发现未标记用例时调用 pytest.exit() 直接退出并返回非零退出码。这样既不需要额外写检查脚本,也能在输出中列出具体是哪些用例需要补标记。
最小可运行示例
目录结构:
project/
├── conftest.py
└── tests/
└── test_sample.py
conftest.py:
import os
import pytest
# 这些是 pytest 内置或与分类无关的标记,不计入“显式分类标记”
BUILTIN_MARKERS = {
"skip",
"skipif",
"xfail",
"parametrize",
"usefixtures",
"filterwarnings",
}
def pytest_configure(config):
config.addinivalue_line(
"markers", "unmarked: 由钩子自动添加,表示用例没有显式分类标记"
)
config.addinivalue_line("markers", "slow: 慢测试")
config.addinivalue_line("markers", "integration: 集成测试")
def pytest_collection_modifyitems(config, items):
unmarked = []
for item in items:
explicit = [
marker
for marker in item.own_markers
if marker.name not in BUILTIN_MARKERS
]
if not explicit:
item.add_marker(pytest.mark.unmarked)
unmarked.append(item.nodeid)
if unmarked and os.environ.get("PYTEST_FAIL_ON_UNMARKED") == "1":
detail = "\n".join(f" - {nodeid}" for nodeid in unmarked)
pytest.exit(
"以下测试没有显式分类标记,请补充 @pytest.mark.slow "
"或 @pytest.mark.integration:\n" + detail,
returncode=1,
)
tests/test_sample.py:
import pytest
def test_plain():
assert 1 + 1 == 2
@pytest.mark.slow
def test_heavy():
assert True
@pytest.mark.integration
class TestAPI:
def test_health(self):
assert True
这里 test_plain 没有任何分类标记,会被自动加上 unmarked;test_heavy 和 TestAPI.test_health 已经显式声明,不会被误判。
运行方法
先安装 pytest:
pip install pytest
只查看未标记的用例(用于本地自查):
pytest -m unmarked -q
触发强制失败模式:
PYTEST_FAIL_ON_UNMARKED=1 pytest -m unmarked -q
此时 pytest 会在收集阶段退出,退出码为 1,并打印出 tests/test_sample.py::test_plain。补上标记后再次执行,就不会再触发退出。
接入 CI 门禁
直接在 CI 中执行 PYTEST_FAIL_ON_UNMARKED=1 pytest -m unmarked -q 即可。需要注意一个细节:当所有用例都已有标记时,-m unmarked 收集不到任何用例,pytest 会返回退出码 5(no tests ran),不能把它当成失败。可以用下面的脚本兼容:
#!/usr/bin/env bash
set -u
PYTEST_FAIL_ON_UNMARKED=1 pytest -m unmarked -q
code=$?
if [ "$code" -eq 5 ]; then
echo "没有未标记的测试,检查通过"
exit 0
fi
exit "$code"
把这个脚本作为 CI 的一个独立步骤,与真正跑测试的步骤分开。这样即使门禁失败,也只会输出需要补标记的用例清单,不会去执行慢测试。
边界与限制
- 钩子只检查本次实际收集到的用例。被
-k、路径参数或--ignore过滤掉的用例不会出现在items中,也就不会被检查。 - 这里使用
own_markers而不是iter_markers。iter_markers会把父节点和插件注入的标记也算进去,容易漏检;own_markers更接近“用例自身是否显式声明”。 - 模块级
pytestmark = pytest.mark.integration会让该模块下所有用例被视为已标记。如果团队要求精确到函数,需要调整判断逻辑,改为只检查函数自身的标记。 unmarked必须在pytest_configure中注册。若启用了--strict-markers,未注册的标记会直接报错。- 不同 pytest 版本对
own_markers的细节行为可能有差异,建议在依赖中锁定 pytest 版本范围,并保留一条最小自测用例验证钩子行为。 - 使用
pytest-xdist时钩子会在 worker 中执行,门禁任务建议不加-n,避免输出重复。
这套做法把“记得加标记”从人的自觉变成流水线约束:本地可以先用 -m unmarked 快速发现遗漏,CI 再用强制失败兜底。
- 点赞
- 收藏
- 关注作者
评论(0)