用 pytest 钩子标记未分类测试并在 CI 中强制失败

举报
yd_250998817 发表于 2026/11/12 08:28:12 2026/11/12
【摘要】 借助 pytest_collection_modifyitems 钩子,在收集阶段为没有显式分类标记的用例自动补上 unmarked 标记,再在 CI 中用 -m unmarked 收集并让门禁失败,倒逼团队为慢测试和集成测试补齐标记。

用 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 再用强制失败兜底。

【版权声明】本文为华为云社区用户原创内容,未经允许不得转载,如需转载请自行联系原作者进行授权。如果您发现本社区中有涉嫌抄袭的内容,欢迎发送邮件进行举报,并提供相关证据,一经查实,本社区将立刻删除涉嫌侵权内容,举报邮箱: cloudbbs@huaweicloud.com
  • 点赞
  • 收藏
  • 关注作者

评论(0)

0/1000
抱歉,系统识别当前为高风险访问,暂不支持该操作

全部回复

上滑加载中

设置昵称

在此一键设置昵称,即可参与社区互动!

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。