pytest灰度测试需在collection阶段用pytest_collection_modifyitems钩子结合@pytest.mark.gray标记和hash抽样剔除用例，避免setup/teardown执行与统计异常，CI中须分支+环境变量双控启用。
pytest如何用-k和--tb=short快速验证灰度逻辑
灰度运行不是让测试“跑一半”，而是有控制地让部分测试用例在特定条件下执行。pytest本身不内置“随机抽样运行测试”的能力，但可以通过标签（markers）+自定义逻辑组合实现。关键在于：**不要依赖pytest原生命令行做随机，而要在收集阶段干预测试项**。
常见错误是试图用pytest -k "test_*" --randomly，但pytest-randomly插件打乱的是执行顺序，不是跳过——它仍会运行全部用例，不符合灰度“只跑5%”的需求。
- 真正有效的做法是在
pytest_collection_modifyitems钩子中，根据标记和抽样率过滤items - 必须配合
@pytest.mark.gray显式标注候选用例，避免污染非灰度测试 - 抽样逻辑建议用
hash(test_id) % 100 而非<code>random.random()，保证同一用例在不同机器/多次运行中结果一致
如何定义@pytest.mark.gray并设置抽样率参数
在conftest.py中注册标记，并通过命令行传入灰度比例：
# conftest.py
import pytest
import os
<p>def pytest_configure(config):
config.addinivalue_line("markers", "gray: mark test as eligible for gray sampling")</p><p>def pytest_collection_modifyitems(config, items):
gray_rate = int(os.getenv("PYTEST_GRAY_RATE", "0"))
if gray_rate <= 0:
return
kept = []
for item in items:
if "gray" in item.keywords:</p><h1>稳定哈希，避免每次运行结果漂移</h1><pre class="brush:php;toolbar:false;"> h = hash(item.nodeid) & 0x7fffffff
if h % 100 < gray_rate:
kept.append(item)
else:
kept.append(item) # 非灰度标记的用例始终保留
items[:] = kept
立即学习“Python免费学习笔记（深入）”；
Claw Code Suite (Python-Only Edition)
下载
仅使用 Python 将 Claw Code 虚拟化框架与 OpenClaw 集成，提供 184 种工具和 200 多条命令，用于安全分析和代码质量...
运行时只需：PYTEST_GRAY_RATE=5 pytest tests/ —— 表示对所有带@pytest.mark.gray的用例按5%概率保留，其余跳过。
- 注意：环境变量名要全大写，且不能含点号（
PYTEST_GRAY.RATE会被忽略） - 如果想按模块粒度灰度，可改用
item.module.__name__做分组哈希，而不是item.nodeid -
items[:] = kept是原地替换，否则pytest仍会尝试运行原始列表中的所有项
为什么不能直接用pytest.skip()在测试函数内做抽样
在测试函数开头加if random.random() > 0.05: pytest.skip("gray skipped")看似简单，但会导致两个严重问题：
- pytest统计时仍会计为“skipped”，CI系统可能误判跳过率异常升高，触发告警
- setup/teardown仍会执行，尤其是带
@pytest.fixture(scope="function")的资源初始化，造成无谓开销 - 更隐蔽的问题：某些fixture依赖于测试是否被收集（例如条件化加载配置），在未收集状态下调用会报
FixtureLookupError
所以必须在collection阶段剔除，而非在runtest阶段跳过。
CI流水线中如何安全启用灰度测试
灰度测试只应在预发或特定分支启用，主干CI必须100%执行。推荐用Git分支名或CI环境变量双控：
- 在
.gitlab-ci.yml或github/workflows/test.yml中，仅当$CI_COMMIT_BRANCH == "pre-release"且$GRAY_ENABLE == "true"时导出PYTEST_GRAY_RATE=2 - 本地开发时默认不启用，避免开发者误以为“测试没跑完是正常的”
- 日志中务必打印实际生效的灰度率：
print(f"[gray] applied rate {gray_rate}% to {len(kept)}/{len(items)} gray-marked tests")，方便排查漏标或过标
真正的难点不在代码怎么写，而在标记边界——哪些用例该打@pytest.mark.gray？高频但低风险的工具函数测试可以，涉及资金、权限、幂等性的核心路径绝对不行。这个决策比技术实现更需要团队对业务的理解。
