pytest测试标记:怎么跳过或预期特定测试失败

木白
木白
发布时间:2026-11-18| 7人浏览过
原创

详细讲解在 pytest 中使用 @pytest.mark.skip、@pytest.mark.skipif 以及 @pytest.mark.xfail 标记跳过测试或处理预期失败的完整指南与实践规范。

在大型自动化测试项目中,某些用例可能因外部依赖不可用、操作系统兼容性限制或尚未修复的已知缺陷而无法正常通过。pytest 提供了内置的测试标记机制,核心通过 @pytest.mark.skip、@pytest.mark.skipif 和 @pytest.mark.xfail 精确控制用例的执行状态。本文详细梳理这三种标记的适用边界、代码配置、执行逻辑与维护规范,帮助你构建既严谨又灵活的自动化测试套件。

测试标记的核心定位与执行流转

自动化测试最忌讳的是误报与静默忽略。如果为了不让测试套件报错而随意注释掉代码,用例就会彻底脱离版本监管;如果放任已知未修的缺陷导致测试套件全线飘红,又会掩盖新引入的问题。pytest 的标记系统正是在这两者之间建立的标准通道。

当 pytest 启动测试时,它会先扫描用例元数据并根据标记规则进行判定。根据标记种类的不同,用例会走向不同的执行分支:完全跳过执行、条件求值后再跳过,或是照常执行但按预期失败对结果进行重命名分类。

pytest测试标记:怎么跳过或预期特定测试失败

图 1:pytest 测试用例收集、标记求值与最终执行状态流转

一、无条件跳过:@pytest.mark.skip 与运行时跳过

当你明确知道某个用例目前无法运行且没有继续执行的必要时,可以使用无条件跳过。被跳过的测试完全不会执行函数体中的语句,也不会造成任何副作用。

1. 函数级与类级静态标记

通过给测试函数或测试类添加 @pytest.mark.skip 装饰器即可。任何时候使用跳过标记,都应当显式提供 reason 说明参数,明确记录跳过原因或对应的缺陷工单链接。

import pytest

# 单个测试函数跳过
@pytest.mark.skip(reason="登录接口正在进行重构升级,暂不可用")
def test_user_login():
    response = call_login_api("admin", "secret")
    assert response.status_code == 200

# 整个测试类全部跳过
@pytest.mark.skip(reason="支付网关沙箱环境维护中")
class TestPaymentService:
    def test_wechat_pay(self):
        assert process_pay("wechat") is True

    def test_alipay_pay(self):
        assert process_pay("alipay") is True

2. 模块级批量跳过

如果整个测试文件针对的是尚未就绪的独立子系统,在每个函数上方逐一添加装饰器显得重复且易遗漏。可以在模块全局声明 pytestmark 变量:

import pytest

# 该变量会对当前 .py 文件中所有的测试函数和测试类统一生效
pytestmark = pytest.mark.skip(reason="外部依赖服务微服务未就绪,整模块跳过")

def test_inventory_sync():
    assert sync_stock() is True

def test_inventory_query():
    assert query_stock(1001) > 0

3. 运行时动态跳过:pytest.skip()

静态装饰器在模块导入或收集期就已固定。但很多时候,我们必须进入执行阶段,才能知道环境是否满足条件(例如夹具 fixture 初始化时发现数据库连接失败、文件下载超时等)。此时可以使用 pytest.skip() 函数直接中断执行:

import pytest
import os

def test_database_backup():
    db_host = os.getenv("DB_HOST")
    if not db_host:
        pytest.skip("环境变量 DB_HOST 未设置,跳过依赖真实数据库的备份测试")
    
    status = execute_backup(db_host)
    assert status == "SUCCESS"
执行机制提示

pytest.skip() 的底层实现是通过抛出一个内部专用的 Skipped 异常来立即终止当前函数的执行。因此,它后面的代码行均不会被触发。

二、条件跳过:@pytest.mark.skipif 的环境与配置隔离

大多数情况下,测试用例本身逻辑完整有效,只是对操作系统、Python 解释器版本或外部三方库存在强依赖。这时应使用 @pytest.mark.skipif,根据布尔表达式的结果决定是否跳过。

1. 平台与版本环境判定

skipif 的第一个位置参数是求值为布尔类型的条件(condition),第二个参数同样是必填的 reason:

import sys
import pytest

# 仅在 Python 3.11 以下版本跳过
@pytest.mark.skipif(
    sys.version_info < (3, 11),
    reason="使用了 Python 3.11 新增的 ExceptionGroup 特性"
)
def test_exception_group_handling():
    with pytest.raises(ExceptionGroup):
        handle_concurrent_tasks()

# 仅在非 Windows 系统上执行(Windows 上跳过)
@pytest.mark.skipif(
    sys.platform == "win32",
    reason="Windows 环境不支持 POSIX 信号量通信"
)
def test_unix_signal_listener():
    import signal
    assert register_posix_handler(signal.SIGUSR1) is True

2. 第三方依赖可用性检查

针对可选插件或非通用包,可以使用 importlib.util.find_spec 判定包是否已安装,避免因 ModuleNotFoundError 导致测试整体崩溃:

import importlib.util
import pytest

has_numpy = importlib.util.find_spec("numpy") is not None

@pytest.mark.skipif(not has_numpy, reason="运行该矩阵运算测试必须安装 numpy")
def test_matrix_multiplication():
    import numpy as np
    a = np.array([[1, 2], [3, 4]])
    assert a.shape == (2, 2)
pytest测试标记:怎么跳过或预期特定测试失败

图 2:跳过测试与预期失败标记的选择决策模型

三、预期测试失败:@pytest.mark.xfail 的深层机制与状态判定

xfail(Expected Failure)是自动化测试中极富价值但常被误用的标记。与 skip 的根本区别在于:标记为 xfail 的测试依然会被真实执行。

它的典型场景是:研发团队确认了一个缺陷,测试人员已经编写好了能够重现该缺陷的测试用例并提交入库。为了不阻塞持续集成的绿灯通行,我们将该用例标记为预期失败。当后续开发人员修复了该缺陷,测试系统应当敏锐察觉。

1. 基础用法与状态输出

默认情况下,如果一个标记了 xfail 的测试发生了断言失败或抛出异常,pytest 会将其判定为 XFAIL(终端显示为黄色小写 x),测试套件整体仍然视为通过;如果测试竟然通过了(即未发生预期失败),pytest 会将其标记为 XPASS(终端显示为黄色大写 X),套件依然通过。

import pytest

@pytest.mark.xfail(reason="缺陷 ISSUE-8921:特定特殊字符会导致解析器崩溃")
def test_parse_special_unicode():
    payload = "用户测试\x00\x1f输入"
    # 当前系统会在此处抛出 ValueError,符合预期失败
    result = robust_parser(payload)
    assert result is not None

2. strict 严格模式:消除“失效的预期失败”

默认配置下 XPASS 不会导致构建失败,这往往会带来隐患:当缺陷被无意间修复,或者测试断言写法有误导致测试始终“被动通过”时,团队会忘记移除 xfail 标记,使得该测试长期滞留在异常管理列表中。

通过设置 strict=True,可以强制要求:一旦标记为 xfail 的测试通过了,立即判定整个测试任务 FAILED! 这能够强力倒逼团队及时审查代码并移除标记。

@pytest.mark.xfail(strict=True, reason="缺陷 ISSUE-9002:修复后必须立即移去标记并恢复常态校验")
def test_order_refund_race_condition():
    status = process_concurrent_refund(order_id="10098")
    assert status == "REFUND_SUCCESS"

如果希望在整个项目中全局启用该规则,可以在 pytest.ini 配置文件中添加:

[pytest]
xfail_strict = true

3. 限制预期异常类型:raises 参数

在编写 xfail 时,如果代码因未捕获的拼写错误(如 NameError)或内存错误崩溃,它也会被笼统地吞噬为预期失败。为了防止掩盖不相干的崩溃,建议通过 raises 参数限定预期的异常类型:

# 只有当测试抛出 TimeoutError 时才视为预期的 xfail
# 如果抛出了 KeyError 或 AssertionError,将被直接判为 FAILED
@pytest.mark.xfail(raises=TimeoutError, reason="第三方风控接口偶发超时,暂未增加重试机制")
def test_risk_control_evaluation():
    evaluate_risk_profile(user_id=8848)
pytest测试标记:怎么跳过或预期特定测试失败

图 3:默认模式与严格模式(strict=True)下的状态判定对比

四、命令行控制与执行报告呈现

在日常开发与持续集成控制台中,清晰查看被跳过和标记用例的原因至关重要。

1. 显示原因明细:-rs, -rx, -ra

默认执行 pytest 时,跳过和预期失败通常只输出一个简短的字符标志(s、x、X)。如果需要打印出用例中填写的 reason,可以使用 -r 命令行选项:

  • pytest -rs:在测试摘要中完整列出所有被 SKIPPED 的用例及原因。
  • pytest -rxX:列出所有 XFAIL 与 XPASS 的用例详情。
  • pytest -ra:打印所有非通过用例的完整汇总(包含 failed、skipped、xfailed、xpassed)。
# 运行命令示例
pytest -ra tests/test_orders.py

# 终端输出结果示例
============================= test session starts ==============================
collected 4 items

tests/test_orders.py .sxX                                                [100%]

=========================== short test summary info ============================
SKIPPED [1] tests/test_orders.py:12: 登录接口正在进行重构升级,暂不可用
XFAIL [1] tests/test_orders.py:25: 缺陷 ISSUE-8921:特定特殊字符会导致解析器崩溃
XPASS tests/test_orders.py:38 缺陷 ISSUE-9002 已解决
================== 1 passed, 1 skipped, 1 xfailed, 1 xpassed in 0.12s ==================

2. 强制忽略 xfail 标记:--runxfail

如果你想验证当前测试集中所有已标记的缺陷是否依然存在,或者做回归扫描,可以追加 --runxfail 参数。该参数会完全剥除 xfail 的特殊保护壳,让所有被标记的测试按普通用例运行。此时凡是依然报错的测试将直接变为真正的 FAILED,用于全量缺陷清查。

pytest --runxfail

五、工程化最佳实践与治理策略

合理运用测试标记能够提升工程效率,但若缺乏制度约束,团队很容易把 skip 和 xfail 当成掩盖问题的垃圾箱。为了保持测试集的健康度,推荐遵循以下工程落地准则:

标记类型 主要目的 适用场景 禁止与警告
skip 绝不执行 功能彻底废弃、依赖完全下线、不可恢复环境 禁止不写 reason;禁止长期放置不清理
skipif 按条件动态忽略 跨操作系统、Python解释器版本差异、可选扩展包缺失 条件表达式应简明纯粹,避免在 condition 中产生高耗时 I/O
xfail 按预期执行并检验 确认存在的已知 Bug、正在开发中的 TDD 用例 推荐搭配 strict=True,防止缺陷修复后用例失修
pytest测试标记:怎么跳过或预期特定测试失败

图 4:测试标记治理体系与工程质量闭环流程

通过合理结合 skip、skipif 与 xfail,并配以严格的标记原因记录和持续集成校验,可以在保障主干分支稳定交付的同时,使测试集忠实反映业务代码的真实运行状态,让自动化测试真正成为质量守卫的坚实基石。

相关专题:

免责声明:本文内容仅供参考,不代表本站观点。转载或引用请注明出处。

Python 相关产品和应用

全部下载
Selenium

Selenium

4.51.0 · Windows

用于浏览器自动化和 Web 测试的 Python 工具。

scikit-learn

scikit-learn

1.9.1 · Windows

常用 Python 机器学习算法与模型评估工具库。

Black

Black

26.10.1 · Windows

强调一致性的 Python 自动代码格式化工具。

Ruff

Ruff

0.17.1 · macOS

由 Rust 编写的高速 Python 代码检查和格式化工具。

pytest

pytest

9.1.1 · Windows

简洁而强大的 Python 自动化测试框架。

FastAPI

FastAPI

0.146.0 · Windows

高性能 Python API 框架,支持类型提示和自动接口文档。

Flask

Flask

3.1.3 · Windows

轻量灵活的 Python Web 应用框架。

Django

Django

6.1.2 · Windows

成熟的 Python Web 框架,适合构建内容站点和业务系统。

Spyder

Spyder

6.1.7 · Windows

面向科学计算与数据分析的 Python 集成开发环境。

SciPy

SciPy

1.18.1 · Windows

面向科学、工程和技术计算的 Python 算法库。