自定义 pytest 标记直接用 @pytest.mark.标记名 装饰测试函数，标记名需合法且区分大小写；可通过 pytest -m 过滤执行，但为避免 unknown marker 警告，建议在 pytest.ini 或 pyproject.toml 中声明 markers。

直接用 @pytest.mark.标记名 装饰器就行，但标记名不能是 Python 关键字或带点号、空格的字符串，否则运行时报 InvalidMarker 或语法错误。

怎么定义和使用自定义标记

pytest 允许你自由定义标记名（比如 @pytest.mark.smoke、@pytest.mark.asyncio），只要不跟内置标记（如 skip、xfail）冲突，也不用提前注册。标记本身只是元数据，真正起作用靠 pytest -m "标记名" 过滤执行。

• 标记写在测试函数正上方，紧挨着 def 行
• 支持多标记叠加：@pytest.mark.smoke 和 @pytest.mark.regression 可同时用
• 标记名区分大小写，@pytest.mark.SMOKE 和 @pytest.mark.smoke 是两个不同标记
• 带参数的标记（如 @pytest.mark.parametrize）本质也是标记，但它是 pytest 内置的特殊标记，不要自己仿写

为什么 @pytest.mark.xxx 有时不生效

最常见原因是没在 pytest.ini 或 pyproject.toml 中声明为“已知标记”，导致运行时警告 Unknown pytest.mark.xxx —— 这只是警告，不影响标记功能，但如果你用 -W error 或 CI 环境严格报错，就会中断执行。

Forge — Python Developer

Python开发助手 — 自动化脚本、API封装、命令行工具、数据管道、网页爬虫。经过测试的代码，包含错误处理和文档。当你需要...

下载

• 在 pytest.ini 中加：

  [tool:pytest]
  markers =
      smoke: run smoke tests
      slow: run slow tests (deselect with '-m "not slow"')

• 或在 pyproject.toml 中：

  [tool.pytest.ini_options]
  markers = [
      "smoke: run smoke tests",
      "slow: run slow tests"
  ]

• 不声明也能用，但声明后可避免警告，且支持 IDE（如 PyCharm）识别标记语义

如何跳过带特定标记的测试

用 -m 是最常用方式，但注意布尔逻辑写法容易出错：

• pytest -m smoke：只运行带 @pytest.mark.smoke 的测试
• pytest -m "not slow"：运行所有**不带** slow 标记的测试（引号必须，否则 shell 把 not 当命令）
• pytest -m "smoke and not slow"：同时满足两个条件（注意 and/or/not 是 pytest 自己解析的，不是 Python 表达式）
• 误写成 pytest -m smoke and not slow（没引号）会导致只执行 pytest -m smoke，然后 shell 尝试执行 and 命令，报错

标记名拼错、漏引号、忘记在配置里声明——这三个点卡住的人最多。尤其团队协作时，标记名最好统一收口在文档或 conftest.py 注释里，不然很快变成 regression / regresion / reg 并存的局面。

Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！