Pytest从5.x版本开始对自定义标记的管理变得更加严格，未注册的标记在命令行调用时会触发告警，甚至影响CI环境的稳定性。通过合理定义标记并结合命令行参数，我们可以精准控制哪些用例执行、哪些跳过，而不必改动测试代码本身。
为什么需要自定义标记
在真实项目中，测试用例往往混杂着单元测试、接口测试、慢速集成测试等类型。如果每次执行都全量运行，本地调试效率极低，CI流水线也会被不必要的耗时拖慢。Pytest提供的标记（marker）机制，允许我们给每个测试函数打上语义化标签，然后在运行时按标签筛选。
早期版本中，标记可以直接使用而不注册，但Pytest 5.x之后引入了markers注册要求。未注册的标记会在收集阶段产生PytestUnknownMarkWarning，虽然不阻断运行，但在严格模式下或使用了-W error时会直接失败。因此升级后的第一件事，就是规范化标记声明。
在配置文件中注册标记
Pytest支持在pytest.ini、setup.cfg或pyproject.toml中声明标记。以pytest.ini为例，我们需要在文件里添加markers段落，每行写一个标记名和可选描述。
下面是一段典型的配置，我们定义了smoke、slow和api三个标记，分别用于冒烟测试、耗时测试和接口测试。注册之后，使用这些标记就不会再报警告，同时也方便团队成员通过pytest --markers命令查看可用标签。
[pytest]
markers =
smoke: 基础冒烟测试用例
slow: 执行较慢的集成测试
api: 对外接口相关测试
为测试用例添加自定义标记
标记通过装饰器pytest.mark.标记名添加到测试函数上。同一个函数可以叠加多个标记，从而支持多维度筛选。比如一个接口测试用例既属于api又属于slow，就可以同时打两个标签。
以下代码展示了如何书写带标记的测试。注意标记名必须与配置文件中注册的一致，否则依然会触发未知标记警告。这种写法让测试目录结构清晰，也便于后续用命令行做交集或差集运行。
import pytest
@pytest.mark.smoke
def test_login_success():
assert "token" in {"token": "abc"}
@pytest.mark.api
@pytest.mark.slow
def test_batch_export():
# 模拟耗时导出
assert 1 + 1 == 2
命令行条件运行与跳过
升级后最核心的用法是通过-m参数传入表达式。表达式支持and、or、not等逻辑操作。比如只跑冒烟测试用pytest -m smoke；跑接口但排除慢速用例用pytest -m "api and not slow"。
如果想跳过某些标记而不是运行，可以结合not逻辑，或者使用pytest -m "not slow"整体屏蔽耗时用例。在CI中，通常会把慢速测试放到独立阶段，通过不同的-m表达式拆分流水线，显著缩短反馈周期。
# 仅执行冒烟测试 pytest -m smoke # 执行接口测试但跳过慢速 pytest -m "api and not slow" # 跳过所有慢速测试 pytest -m "not slow"
用skipif结合标记动态跳过
除了命令行筛选，我们还可以在代码内根据环境变量或条件，利用skipif配合标记实现动态跳过。例如当环境变量RUN_SLOW未设置时，自动跳过slow标记的用例，这样即使忘记传-m参数也不会卡在慢测试上。
这种写法把跳过逻辑固化在代码里，适合那些本地默认就不希望跑、只有专门指令才执行的场景。它和命令行标记是互补关系：命令行负责临时灵活控制，skipif负责兜底保护。
import os
import pytest
run_slow = os.getenv("RUN_SLOW") == "1"
@pytest.mark.slow
@pytest.mark.skipif(not run_slow, reason="未开启RUN_SLOW环境变量")
def test_heavy_compute():
assert sum(range(10000)) > 0
升级时的常见坑
很多老项目从4.x升到5.x以上后，突然在日志里看到大量标记警告，误以为是测试写错。其实只是缺少注册步骤。统一在配置里补上markers即可消除。另外，如果使用了pytest-xdist等插件，标记表达式在分布式模式下同样生效，但需保证各节点配置一致。
还有一个易错点是表达式引号：在Shell中如果标记表达式包含空格或逻辑词，必须用双引号包裹，否则会被Shell拆解成多个参数，导致Pytest解析失败。掌握这些细节，升级过程就会非常平滑。
| 场景 | 命令示例 | 作用 |
|---|---|---|
| 本地快速验证 | pytest -m smoke | 只跑核心冒烟 |
| 接口回归 | pytest -m "api and not slow" | 接口但跳过耗时 |
| 全量夜间构建 | pytest -m "" 或 RUN_SLOW=1 pytest | 包含所有慢测试 |
小结
通过Pytest 5.x以上版本的标记注册与命令行-m表达式，我们能以极低侵入成本实现测试用例的灵活调度。配合配置文件中的markers声明和代码内的skipif兜底，既消除了版本升级后的警告，又让测试和CI效率明显提升。
建议团队在迁移时先梳理现有标记，统一写入pytest.ini，再逐步将筛选逻辑迁移到流水线脚本中。这样既能享受新版本的稳定性，也能让条件运行真正成为日常开发的习惯。