当测试因已知Bug预期失败且暂不修复时用pytest.xfail，而非skip；xfail会执行测试并标记XPASS提醒修复，skip则完全跳过。
什么时候该用 pytest.xfail 而不是跳过测试？
当你确认某个测试本该通过、但因代码中已知 Bug 导致失败，且短期内不打算修复时，才用 pytest.xfail。它和 pytest.skip 本质不同：skip 是“不测”，xfail 是“测但预期失败”。如果只是环境不支持（比如缺依赖、平台限制），用 skip；如果功能逻辑有缺陷但已记录为 issue，xfail 更合适。
-
xfail的测试仍会执行，失败不算错误，成功反而会报XPASS（意外通过），提醒你 Bug 可能已被悄悄修复 - CI 中看到
xfail失败是正常现象，但XPASS需人工核查——别让修复漏掉 - 别在 CI 脚本里加
--strict-markers或全局strict=True，否则xfail成功会直接导致构建失败
pytest.xfail 的三种写法及适用场景
最常用的是装饰器形式，但函数内提前标记、命令行临时标记也有不可替代的用途：
- 装饰器（推荐）：
@pytest.mark.xfail(reason="API v2 返回字段名不一致，见 ISSUE#123")
适合长期稳定的已知问题，理由必须写清楚，方便后续追踪 - 函数内调用：
def test_user_profile():<br> if not has_api_v2():<br> pytest.xfail("v2 API 未上线，跳过验证")适合动态判断条件（如版本检测、配置开关） - 命令行临时标记：
pytest test_api.py -m "xfail and slow"
配合自定义 marker 使用，便于临时禁用某类不稳定测试，不影响代码
为什么 raises 参数容易被误用？
@pytest.mark.xfail(raises=ValueError) 并不是“只要抛 ValueError 就算通过”，而是“**必须抛出且仅抛出指定异常**”——如果实际抛了 TypeError，或抛了 ValueError 但还附带其他副作用（比如修改了全局状态），测试仍会失败并标记为 FAIL 而非 XFAIL。
- 只在异常类型是判断核心逻辑成败的唯一依据时才用
raises - 多数业务 Bug 不是“抛错异常”，而是“返回值错误”“状态未更新”，这时直接用
reason即可，别硬套raises - 若想验证异常消息，得配合
match参数：@pytest.mark.xfail(raises=ValueError, match="invalid token")
，但要注意正则匹配失败也会导致FAIL
CI 和团队协作中最容易忽略的细节
xfail 测试在本地跑和 CI 跑结果可能不一致，尤其涉及时间、并发、第三方服务时：
立即学习“Python免费学习笔记（深入）”；
- 别把
reason写成“待修复”，必须指向具体 issue 编号或 PR 链接，否则半年后没人知道指哪个 Bug - 如果测试因网络超时偶尔失败，不要用
xfail掩盖——这是 flaky test，该重写或加重试，不是已知 Bug - 团队约定：所有
xfail必须关联 Jira/GitHub Issue，且该 issue 状态不能是 “closed” 或 “wontfix”，否则标记失去意义
真正难的不是加标记，而是定期清理：每季度扫一遍 xfail 测试，运行它们，删掉已修复的，更新 still-failing 的 reason。没人维护的 xfail 最终会变成噪声。
