企业官网建设流程全解析

做测试的人多半都遇到过这种尴尬：功能逻辑没动过，测试结果却一直是红的，点开一看，用例在 Windows 上跑了 Linux 的资源路径，或者某个第三方 SDK 在当前环境没装全，整个套件被一批“不该跑”的用例拖累，通过率永远上不去。我在维护某跨平台工具的数据同步用例时被这个问题折腾了挺久，后来用 Pytest 的跳过机制把环境不匹配的用例全部按条件摘掉，对暂无法修复的缺陷用预期失败（xfail）统一托管，报告才真正变得可读。这篇文章就围绕“直接跳过、根据条件跳过、预期失败”三条主线，把 Pytest 这套结果状态控制的常用手法讲透，特别适合正在优化测试套件、被无效失败信号困扰的开发者。

1. 先理清楚：跳过和预期失败到底在解决什么问题

1.1 “跑不过的用例”和“不该跑的用例”是两回事

先说一个我屡次踩过的误区：不少人遇到用例跑不过，第一反应是注释掉或者删掉。注释掉意味着这个用例从测试集合里彻底消失，以后功能补全了、环境变了，也完全想不起来这里曾经有一个验证点。删掉更离谱，等于把测试覆盖直接砍掉一块。

跳过（skip）和预期失败（xfail）就是为了解决“这用例现在没法跑/注定会挂，但我还不想丢掉它”的场景。

跳过对应的是“不该跑”：环境不满足、依赖缺失、功能没实现完、某个平台分支不受支持，这些情况下用例即使执行了也没有意义，应该让它从执行队列里摘出去，但保留在收集结果里，让你知道“这里有一个用例，只是这次没跑”。

预期失败对应的是“知道它会挂”：比如某个已知缺陷还没修，某个接口行为已经确认不符合预期但在可接受范围内。这种用例如果标成普通失败，会让真正的回归失败淹没在已知问题里；如果直接跳过，又会掩盖“缺陷是否被修复了”这个信号——因为缺陷一旦修复，预期失败的用例就会变成 unexpected pass，反而能提醒你：可以把这个标记拿掉了。

1.2 四种结果状态：发生了什么才算数

Pytest 一个用例跑完之后，最终落在报告里的状态其实有四种，很多人只盯着 passed 和 failed，另外两种使用场景全被忽略了。

从表格能看出来，skipped 和 xpassed 这两个状态是最容易被误判的。skipped 不是失败，它只是“本次不参与”；xpassed 则是一个很有价值的信号，说明你之前标记的已知缺陷可能已经被修复了，此时应该主动去复核这条用例，如果确认修复，就应该把 xfail 标记移除，让它重新成为普通断言。

有一次我把一堆旧用例全部加了 skip 标记，没写 reason，运行结果一片小写 s，绿油油的很安心。后来才发现，那批用例已经跳过三个月了，功能早就重构完，但由于没写原因，我根本不知道它们为什么被跳过、该不该恢复。所以从一开始就要养成一个习惯：每个 skip 和 xfail 都必须带 reason，这不仅是给未来的自己看，也是让报告输出可追溯。

2. 直接跳过：把不合适的用例从执行队列里摘出去

2.1 装饰器跳过：@pytest.mark.skip 一行搞定

最直接的跳过方式就是给用例函数加装饰器，不需要任何条件判断，只要加上去，这个用例在收集阶段就被标记为跳过，根本不会执行函数体。

import pytest @pytest.mark.skip(reason="登录模块重构中，功能暂未开放") def test_login(): # 这里即使写了复杂的断言也不会执行 assert "ok" == "ok"

这里有个细节值得注意：加了@pytest.mark.skip之后，函数体里的代码是完全不跑的。如果你在模块顶层有变量赋值、数据库连接操作，它们照常执行，但函数内部的逻辑全部绕开。所以它适合用来标记那些“整个用例暂时没有存在必要”的验证点。

还有一种常见用法是把装饰器打在测试类上，后面第 5 章会专门展开。直接跳过虽然“粗暴”，但在敏捷迭代里非常实用：功能拆分了、接口还没就绪，先把新用例写好并标记 skip，等开发提测后再揭开，测试代码不浪费，别人看报告也知道还有哪些没启用。

2.2 运行时跳过：pytest.skip() 让判断发生在函数内部

装饰器在收集阶段就决定了用例的命运，判断逻辑只能写在外层表达式里。但真实业务里很多判断没法靠一个表达式搞定，比如测试数据是否存在、前置接口返回是否符合预期、配置项是否满足当前分支要求。这时候需要把跳过动作放到函数内部，在运行到某个节点时主动终止。

import pytest def test_sync_data(): # 这里是一段前置准备逻辑 prepare_result = check_precondition() if not prepare_result["ready"]: pytest.skip("前置条件不满足，跳过数据同步验证") assert sync_and_compare() == 0

pytest.skip()的效果类似抛异常，函数执行到这一行就停了下来，后续断言不会执行，用例最终状态是 skipped。它和return不同：return之后用例会被算作通过，造成“没测也绿了”的假象；pytest.skip()则明确告诉测试框架，这不是通过也不是失败，而是主动放弃。

使用pytest.skip()时我习惯每次都传reason参数：

pytest.skip("目标环境未配置 access_token", allow_module_level=False)

关于allow_module_level参数，默认是False，只能在函数或测试方法内部调用。如果你在模块顶层直接调用pytest.skip()，Pytest 会报错。真要在模块级别跳过，要把它设为True，或者更稳妥的做法是使用下面要讲的importorskip或模块级变量。

2.3 什么时候该用 skip，什么时候该抛异常

这部分是我给团队做培训时最常被问到的。有些用例前置条件不满足，有人直接抛AssertionError让它失败，也有人抛Exception让它报错。我的判断标准其实很简单：如果这个前置条件是环境或外部因素决定的，用 skip；如果是被测代码本身有 bug 或不满足调用约定，让它失败。

举例来说，接口需要 Token，Token 没配好，这是环境问题，用例应该 skip；接口在缺少 Token 时应该返回 401 却返回了 200，这是功能 bug，用例必须 failed。skip 太多可能掩盖真实问题，failed 太多又会让“预期失败”的用例污染回归信号，所以这两类场景一定要在代码评审的时候说清楚。

3. 条件跳过：把环境、版本、依赖写成判断表达式

3.1 按解释器版本跳过：sys.version_info 是首选

条件跳过最经典的场景就是按 Python 版本控制。装饰器里的条件表达式在收集阶段就会执行，所以要在模块顶部把需要用的模块导入好，然后基于sys.version_info写判断。

import sys import pytest @pytest.mark.skipif( sys.version_info < (3, 10), reason="match 语句需要 Python 3.10 及以上版本" ) def test_match_syntax(): result = match_dispatch("hello") assert result == "greeting"

这里用< (3, 10)而不是sys.version_info[0] < 3 or ...，sys.version_info本身支持元组比较，可以直接拼。同样的思路也适用于判断 PyPy、CPython 等解释器实现，只是把sys.version_info换成platform.python_implementation()之类的判断。

有一个很常见的坑：把变量取错名字，比如在模块里定义了一个version = sys.version_info，然后在装饰器里写version >= (3, 11)，Pytest 在收集阶段会执行模块里的代码，但如果这段代码依赖了某些尚未初始化的配置，就会抛出异常，导致整个模块收集失败。所以条件跳过的表达式要尽量只依赖标准库函数和模块级变量，不要依赖运行时状态。

3.2 按平台类型跳过：sys.platform 的用法与边界

做跨平台测试时，按操作系统分支跳过是刚需。我维护的项目里有一批用例依赖 Linux 特有的/proc文件系统，在 Windows 和 macOS 上跑永远是失败，于是全给他们加了平台条件。

import sys import pytest @pytest.mark.skipif( sys.platform != "linux", reason="/proc 文件系统仅存在于 Linux 环境" ) def test_proc_snapshot(): content = read_proc_snapshot() assert content["uptime"] > 0

sys.platform在不同操作系统上的取值要记准确：linux、win32、darwin。注意 Windows 的返回值不是windows也不是win64，就是win32，这一点很多人第一次写就踩坑。如果你需要更细粒度的判断，可以用platform.system()，它返回的是Linux、Windows、Darwin这类大写名称，两者风格不同，项目里最好统一用一种，避免混用导致读代码时还要来回确认大小写。

3.3 按依赖可用性跳过：importorskip 比 try import 更省事

依赖库没装，import 直接抛ModuleNotFoundError，这种情况用try import包一层也能判断，但 Pytest 给了更优雅的办法：pytest.importorskip。

import pytest # 如果 pandas 导入失败，整个模块的用例都会被跳过 pd = pytest.importorskip("pandas") def test_dataframe_shape(): df = pd.DataFrame({"a": [1, 2, 3]}) assert len(df) == 3

importorskip返回被导入的模块对象，可以直接赋值给变量。它还有一个高阶参数：

pd = pytest.importorskip("pandas", minversion="2.0", reason="需要 pandas 2.x")

如果导入失败或者版本过低，Pytest 会直接跳过当前模块里所有用例，并在报告中显示传入的 reason。这个函数最省心的一点是它天然支持allow_module_level=True，所以在模块顶层调用完全没问题。

对比一下手写try import的方式：

try: import pandas as pd except ImportError: pytest.skip("pandas 未安装，跳过依赖用例", allow_module_level=True)

手写方式也可以，但代码更啰嗦，而且如果你在except里忘记写allow_module_level=True，收集阶段就直接报错，反而不如importorskip直观。这一条在依赖复杂、安装包经常变化的场景里，能省下不少排查时间。

3.4 条件表达式里的优先级与常见坑

skipif的判断表达式用的是普通 Python 语法，所以优先级和日常写法一样，但正因为太“普通”，反而容易出低级错误。

先看一个反面例子：

@pytest.mark.skipif( sys.platform != "linux" and sys.version_info < (3, 11), reason="仅支持 Linux 上的 Python 3.11+" )

这个逻辑是“Linux 且 Python<3.11 才跳过”，还是“非 Linux 或者版本小于 3.11 就跳过”？and的优先级比!=低，所以实际逻辑是(sys.platform != "linux") and (sys.version_info < (3, 11))，也就是说只有”既不是 Linux 又小于 3.11“才跳过，这通常不是作者本意。如果想表达“非 Linux 或低版本都跳过”，应该用or，并且最好加上括号：

@pytest.mark.skipif( sys.platform != "linux" or sys.version_info < (3, 11), reason="仅支持 Linux 上的 Python 3.11+" )

我建议所有skipif的条件都加上括号，哪怕只有一个条件，这样即使后来有人追加条件也不容易改错。另一个坑是布尔值比较，有人写skipif(platform.is_linux() is False)，虽然能用，但可读性远不如not platform.is_linux()。

再补充一个组织上的建议：同一个条件在多个用例里反复出现时，不要到处复制，可以在模块顶部定义一个模块级变量，比如NEEDS_LINUX = sys.platform == "linux"，然后所有装饰器都复用这个布尔值。后续条件变更只需要改一处，排查时也能一眼看到上下文。

4. 预期失败 xfail：给“注定失败”的用例一个正式身份

4.1 xfail 最基础的写法：标记、原因、条件

跳过是把用例摘出去不跑，而预期失败是让用例继续执行，但把失败结果标记成“符合预期的失败”。这是两者最本质的区别，也是 xfail 特有的价值。

import pytest @pytest.mark.xfail(reason="缓存清理接口已知存在 BUG #1024") def test_clear_cache(): assert clear_cache() == True

这段代码加上 xfail 之后，用例会正常执行。断言失败时，报告里不会显示红色 F，而是显示小写的 x；断言通过了，反而会显示大写 X（xpassed），提醒你“这个预期的失败已经不存在了”。

另一种常见写法是按条件判断是否预期失败：

@pytest.mark.xfail( sys.platform == "win32", reason="Windows 下文件锁行为与 Linux 不一致" ) def test_file_lock(): assert acquire_file_lock() is True

当条件为真时才启用预期失败，条件为假则按普通用例跑。这种写法适合平台行为差异、数据库方言差异这类“换环境就换预期”的场景。

4.2 strict 参数：预期失败变成非预期失败时要不要报警

xfail默认的 strict 是 False，也就是用例失败时会显示 x，但用例意外通过时也只显示 X，并不会让整个测试套件报错。很多团队觉得“反正标记了，不重要”，但这样会漏掉缺陷被修复的信号。

把 strict 设为 True 之后，行为就变得严格了：如果标记了 xfail 的用例反而通过了，Pytest 会把这个用例算作失败。也就是说，你预期它失败，它没失败，那就说明预期不准确，需要人工介入。

@pytest.mark.xfail( reason="待灰度配置下发完成后修复", strict=True ) def test_feature_flag_rollout(): assert get_rollout_percent() == 100

我个人的建议是：长期有效的 xfail 全部开启 strict=True。短期过渡的、明确知道马上要修的，可以暂时用默认模式。因为一旦没有 strict，xpassed 只是报告里的一个符号，几乎没人会去盯；开了 strict，CI 就会直接红，你不得不在下次迭代里处理它，这个“不得不”恰恰是质量保障里需要的约束。

4.3 raises 参数与已知缺陷的追踪思路

xfail还有一个容易被忽略的参数是raises，它指定“只有抛出指定异常类型才视为预期失败”，其他失败仍然算失败。

@pytest.mark.xfail( raises=NotImplementedError, reason="旧版驱动尚未实现该接口", strict=True ) def test_driver_connect(): driver = load_driver() driver.connect("localhost")

这段代码如果connect抛出了NotImplementedError，用例显示 x；但如果抛的是ConnectionRefusedError或者断言失败，用例仍然显示 F。这个参数能把“已知问题的范围”圈定得更加精确，避免其他无关失败被预期失败的帽子盖住。追踪缺陷的时候，我习惯于把 BUG 编号写进 reason，例如reason="BUG-2041: 分页参数偏移量计算错误"。报告导出之后，搜索 BUG 编号就能把所有相关预期失败用例找出来，配合看板里的缺陷状态联动维护。

5. 一次设置管住一大批：类级别、模块级别跳过的玩法

5.1 在类上打标记，整类用例统一切换

如果某个测试类的所有用例都受同一个条件控制，没必要给每个方法都加装饰器，直接在类上打标记即可。

import pytest @pytest.mark.skip(reason="Windows 批处理子系统本期不回归") class TestWindowsBatch: def test_create_batch(self): assert create_batch() == 0 def test_cancel_batch(self): assert cancel_batch() == 0 def test_retry_batch(self): assert retry_batch() == 0

类上的装饰器对类内所有测试方法生效，子类继承时也会继承这个标记。如果你需要“父类不跳过，子类跳过”或反向控制，可以在子类重新声明同样的装饰器覆盖，Pytest 会把类上的标记合并到每个方法上，子类再打一层就是叠加，不会自动移除父类的跳过标记，这里容易踩坑，建议优先用条件变量来控制而不是依赖覆盖逻辑。

类级别标记还有一个好处：报告里能看到整批用例都被跳过，数量一目了然，既不会误以为功能已经测过，也不会因为一堆 F 让 CI 长期挂红。

5.2 pytestmark 模块级变量的灵活与限制

要跳过整个模块，Python 文件里最常用的方式是在模块顶层定义pytestmark变量：

import sys import pytest pytestmark = pytest.mark.skipif( sys.platform != "linux", reason="该模块用例仅适用于 Linux 环境" ) def test_process_stats(): assert collect_proc_stats() is not None def test_socket_state(): assert get_socket_state() == "LISTEN"

pytestmark可以是单个标记，也可以是标记列表。需要叠加多个条件时就传多个 marker：

pytestmark = [ pytest.mark.skipif(sys.platform != "linux", reason="仅 Linux"), pytest.mark.skipif(database_is_mysql() is False, reason="仅 MySQL 兼容模式"), ]

但它有个限制：pytestmark是一个模块级变量，没法根据用例动态变化。如果同一个模块里一部分用例在 A 条件下跳过、另一部分在 B 条件下跳过，还是要拆到函数级或类级标记。

5.3 通过收集钩子统一裁剪用例

比模块级变量更进一步的做法是在 conftest.py 里实现pytest_collection_modifyitems，在收集阶段对用例列表统一遍历、按需打标记。这个方式特别适合跨项目统一维护跳过规则，例如按业务线、按测试级别、按环境标签统一过滤。

# conftest.py import sys import pytest def pytest_collection_modifyitems(config, items): for item in items: # 标记了 windows_only 但当前不是 Windows 环境，就跳过 if "windows_only" in item.keywords and not sys.platform.startswith("win"): item.add_marker( pytest.mark.skip(reason="仅 Windows 环境可运行") ) # 冒烟用例默认跳过慢速标记，加快本地反馈 if "smoke" in item.keywords and "slow" in item.keywords: item.add_marker( pytest.mark.skip(reason="冒烟模式跳过慢速用例") )

这个钩子最方便的地方在于它是集中式管理：不在测试代码里到处散布skipif，而是在收集阶段根据 marker、路径或节点 id 动态决策。规则一旦变化，只改 conftest 一个文件，所有关联模块同步生效。代价是规则对新人来说没有直接在测试函数上看标记那么直观，所以我会在 conftest 顶部写清楚注释，说明这里统一处理了哪些跳过逻辑。

6. 命令行参数与报告解读：跳过和 xfail 不能“无声无息”

6.1 让报告显示跳过原因：-rs 和 -rx

很多人第一次用跳过会困惑：明明写了reason，为什么报告里只看到s符号，看不到任何文字说明？因为 Pytest 默认在汇总里不展开跳过原因。要显示这些信息，得显式打开-rs和-rx。

pytest -rs -rx

-rs展示所有跳过用例及其 reason，-rx展示所有预期失败用例及其 mark 信息。还可以精细控制：

我曾经接手过一个测试套件，几百条用例被跳过，CI 全绿，但没有开-rs，谁也说不清跳过的原因是什么。后来把-rs加到 CI 命令里，每次构建都输出跳过原因列表，才发现其中三分之一是“历史遗留标记”，早就该清理掉。这个习惯也让后续维护省了很多时间：每次跑测试，不只是看绿不绿，还要看s符号后面跟着的 reason 是否仍然站得住脚。

6.2 --runxfail：临时把预期失败转为普通执行

有一种特殊场景：一个大版本发布前夕，你需要确认所有标记为预期失败的用例在当前代码上的真实表现，比如想统计到底还有多少已知缺陷没有修复。此时可以加--runxfail参数，Pytest 会忽略所有的 xfail 标记，把预期失败用例当作普通用例执行。原本 xfail 的用例如果失败，会显示 F；如果意外通过，就是通过，不再显示 X。

pytest --runxfail -rx

我一般在每次迭代评审前跑一次--runxfail，把最新代码上真实暴露的问题全部拉出来，再用-rs对比哪些问题是跳过掩盖掉的。这个命令不会修改测试代码，运行完一切照旧，所以是“临时体检”的好工具，不用为了看真实状态而去批量删 xfail 标记。

6.3 与 parametrize 组合：按参数组合控制跳过

真实项目里，很多用例是通过parametrize生成参数组合的。不是每组参数都适合当前环境，这时候可以在函数内部对特定参数调用pytest.skip()。

import pytest @pytest.mark.parametrize("env", ["dev", "stage", "prod"]) def test_deploy_config(env): if env == "prod": pytest.skip("生产环境配置不纳入自动化断言") config = load_config(env) assert config["cache_enabled"] is True

如果跳过逻辑比较统一，也可以把参数和跳过条件放到一起，例如先过滤参数列表，再传给parametrize：

import pytest ENVIRONMENTS = [env for env in ["dev", "stage", "prod"] if env != "prod"] @pytest.mark.parametrize("env", ENVIRONMENTS) def test_deploy_config(env): pass

两种方式差别在于跳过记录的粒度。第一种在报告里会保留prod这条参数记录的 skipped 条目，后续如果想看“哪些组合没跑”，搜索 reason 就能定位；第二种是直接不收集该参数组合，报告里根本没有这条记录。我更推荐第一种，理由和前面说的一致：保留可见性，比干净的报告要重要。

6.4 我常用的组合拳：冒烟分级与环境自适应

最后分享一个我现在比较稳定的用法，供你参考。测试套件里会区分冒烟用例和全量用例，冒烟用例通过 markersmoke标记，全量用例默认全部收集。本地开发时，我习惯用：

pytest -m "not slow" -rs -rx

这条命令会跳过所有标记了slow的用例，但通过-rs能明确看到“哪些慢速用例没跑”，不会留下含糊的绿色。CI 的不同阶段跑不同层级：提交验证跑-m "smoke"，合并请求验证跑全量，但带上-x --runxfail做一次“已知问题核对”。

我实际遇到的一个典型案例是这样的：某数据的重跑机制在特定版本下有个已知并发问题，开发一直没修，我给它标了@pytest.mark.xfail(strict=True, reason="BUG-2041: 并发重跑计数不准确")。结果某次依赖升级后，这个用例意外通过了，CI 马上报红。我点开报告，看到 xpassed，随后确认修复已经随底层库升级生效。那一刻我意识到，skip 和 xfail 并不是简单地“让用例不失败”，而是把“现在不能测的”和“已经知道有问题的”都变成可跟踪的状态。如果你也在被这个问题困扰，不妨从这两个标记开始，把它们用对、用活，比追求 100% 通过率更接近测试的本意。