企业官网建设流程全解析

从实际遇到的一个诡异问题说起：某天我运行 pytest 时发现，测试用例明明写了assert result == expected，失败信息却只显示两个对象不相等，完全没有中间变量的上下文。当时我第一反应是“这框架是不是坏了”，直到我翻开_pytest/assertion/rewrite.py的源码才明白，pytest 的断言增强其实是一套完整的字节码改写机制，而不是简单的字符串拼接。

这事之后我就养成了一个习惯：不管用哪个框架，先花时间把底层源码通读一遍。pytest 作为目前 Python 生态里最主流的测试框架，它的源码值得深入解析，因为它不只是“跑用例的工具”，更是一个设计精巧的插件系统，一个自带字节码改写能力的元编程框架，一个把fixture做到极致的依赖注入容器。本文就把我阅读 pytest 源码的核心收获整理出来，从启动入口、收集机制、fixture 设计、断言重写、钩子系统到运行协议，一层层拆开看，不回避细节，尽量让每个结论都能对应到实际代码。

这篇内容适合两类读者：一类是已经写了大量 pytest 用例、想搞清楚“为什么 fixture 作用域是这样”“为什么断言失败能显示那么细”的进阶用户；另一类是准备基于 pytest 写插件、做二次开发的框架开发者。看完你会知道 pytest 真正的边界在哪里，以及它的优雅和复杂分别藏在哪些地方。

1. 从入口出发：pytest 命令是如何一步步接管整个测试流程的

1.1 入口文件与 main 函数的工作逻辑

大多数人都知道在命令行敲一个pytest就能跑测试，但几乎不会有人去问：这个命令对应的 Python 代码到底长什么样。实际上，pytest 安装后会生成一个 console_scripts 入口，指向pytest/__main__.py，核心内容是：

# pytest/__main__.py import pytest import sys sys.exit(pytest.console_main())

pytest.console_main()定义在_pytest/config/__init__.py，它内部调用了main()。而main()才是整个 pytest 的神经中枢：

# _pytest/config/__init__.py（简化还原） def main(args=None, plugins=None): config = _prepareconfig(args, plugins) ... return config.hook.pytest_cmdline_main(config=config)

关键点就在这里：main()做了两件事。第一，通过_prepareconfig初始化一个全局唯一的Config对象；第二，通过config.hook.pytest_cmdline_main(config=config)把“接下来该干什么”的决定权交给钩子系统。

注意这个设计思路，main()本身不负责收集用例，不负责执行用例，它只负责把配置对象准备好，然后往外抛一个钩子事件。谁响应这个钩子，谁就控制流程。pytest 默认的pytest_cmdline_main实现是_pytest.main.wrap_session，这个wrap_session会先创建一个Session对象，然后调用session.exit()进入主循环。

从这里就能看出 pytest 的第一个底层原则：控制流不是硬编码的，而是通过事件分发驱动的。所有核心流程，收集、运行、报告，都是钩子函数的响应结果。这也是 pytest 能支持无数第三方插件的根本原因。

1.2 Config 对象与插件初始化之间的秘密关系

_prepareconfig这条链路值得单独拿出来讲，因为它是 pytest 启动时最容易被忽略却又最重要的部分。简化后的调用链是：

def _prepareconfig(args, plugins): # 1. 解析命令行参数 # 2. 读取配置文件（pytest.ini、pyproject.toml 等） # 3. 注册内置插件 # 4. 注册外部插件 # 5. 执行 pytest_configure 钩子 ...

其中有个细节：pytest 会先解析命令行参数，再读取配置文件，然后用这些信息决定加载哪些插件。也就是说，你在命令行加的-p no:cacheprovider这类参数，确实是在插件加载之前就被解析并生效了的。

我最早读源码在这里卡了很久，因为我想不明白conftest.py到底什么时候被加载。后来才搞清楚：conftest.py不是启动时一次性加载的，而是在收集阶段按目录层级逐步导入的。启动阶段加载的只是“初始插件”，包括 pytest 自带的所有内置插件（如_pytest.fixtures、_pytest.assertion、_pytest.capture等）和你通过-p指定或 entry_points 注册的第三方插件。

这个加载顺序直接决定了你在conftest.py里定义的 hook 无法覆盖内置插件的某些行为，因为内置插件早就注册完了。如果确实需要全局覆盖，就必须通过-p参数在更早的阶段把插件注册进去。

还有一点很关键：Config对象是 pytest 里几乎所有组件都持有的共享上下文。无论是Session、Item、FixtureManager还是Reporter，最终都能通过.config拿到这个全局对象。所以你在写插件时，尽量不要自己建全局变量，直接挂在config上反而更干净，这也符合 pytest 内部的使用范式。

2. 收集机制与节点树：pytest 如何把一个目录变成一棵用例树

2.1 Collector、Session、Item 的角色划分与完整链条

你运行pytest tests/时，pytest 不会“遍历所有文件然后找出所有 test 函数”这么简单，它是按照一套严格的对象模型来构建测试集合的。这套模型的核心是Collector和Item。

先看_pytest/main.py里的Session类。Session是一个特殊的Collector，它的collect()方法会遍历起始路径，遇到目录就创建Package收集器，遇到.py文件就创建Module收集器。Module.collect()会扫描模块内的所有对象，发现满足测试命名规则的类就创建Class收集器，发现满足测试命名规则的函数就创建Function项。

Item和Collector的区别在于：Item是可执行的测试用例，它知道“怎么运行自己”；Collector是容器，它知道“怎么找到下一层的东西”。整个流程可以理解为一种递归下降：从Session这个根节点开始，逐层调用collect()，最终生成一棵节点树。

这里有个容易误解的地方：Function在 pytest 里通常指的是Function这个Item类型，而不是 Python 函数本身。每个测试用例最终会被包装成一个Function实例，这个实例既持有原始的 Python 函数对象，也持有模块、类等路径信息。Function.__init__时还会解析这个用例的参数化信息、fixture 依赖等。

2.2 模块、类、函数各层级的收集细节

我们实际看_pytest/python.py里的几个关键类。首先是Module：

class Module(PyCollector): def collect(self): # 使用 importmode 导入模块 self.session._fixturemanager.parsefactories(self.obj) ... for name, obj in self.obj.__dict__.items(): if isinstance(obj, staticmethod): obj = obj.__func__ ... if self.isinitpath(obj): continue if isclass(obj): # 类收集器 elif isfunction(obj): # 函数收集器

Module.collect()有个重要动作：遍历模块的__dict__，根据对象类型分派到不同的收集器。若遇到类，就检查类名是否匹配python_classes；若遇到函数，就检查函数名是否匹配python_functions。这两个配置项默认分别是"Test"*和"test"*，但你要搞清楚它们匹配的是“名字”而不是“类型”，这就是为什么你写class MyTest:而方法叫check_something时，pytest 不会收集它。

Class.collect()更灵活，它会通过collect_members遍历类的属性，把方法名匹配python_functions的方法变成Function项。但是只有当类的__init__方法不接收额外参数时，pytest 才会允许收集这个类里的测试方法，否则会报initfailure。这个细节在实际项目中非常常见，特别是当你给测试类写了带参数的__init__时。

再说Function。Item的父类Function在收集阶段并不直接执行函数，它只负责把调用所需的信息存下来。真正执行发生在运行阶段，两者分离是 pytest 设计里很重要的一点：收集阶段要快、要安全，不能因为某个用例导入出错就拖垮整个测试集合，所以 pytest 提供了--continue-on-collection-errors这样的选项让收集阶段的异常不会阻断整个流程。

2.3 节点 ID、路径与 parametrize 参数的内存表示

每个节点（无论是Collector还是Item）都有唯一的nodeid，这是 pytest 定位用例的“坐标系统”。nodeid通常由文件路径和参数化参数组成，比如：

tests/test_demo.py::test_add[1+2-3]

这个nodeid是执行、筛选、报告的基础。你单独跑某条用例时pytest tests/test_demo.py::test_add[1+2-3]，实际上就是用这个nodeid去匹配收集到的节点。

参数化在内存里的表示方式很有意思。当你在测试函数上标记@pytest.mark.parametrize("a", [1, 2])时，pytest 会在收集阶段调用Function里的_initaxistrans和方法_getobj，把参数列表展开成多个“虚拟函数对象”，每个虚拟函数对应一个Function实例，它们的nodeid会带上参数化片段。

这意味着下面两行代码其实创建了多个测试用例：

@pytest.mark.parametrize("num", [1, 2, 3]) def test_num(num): assert num > 0

test_num会被拆成test_num[1]、test_num[2]、test_num[3]三个Item。展开时 pytest 会先把参数值转换成字符串表示，再做合法性清洗（去掉文件名不安全字符），所以你会在nodeid里看到很多奇怪的转义符号，比如参数里包含/会被编码成%2F之类。

理解节点树和nodeid的生成规则，对排查“为什么我只想跑一条用例却执行了五条”“为什么筛选表达式不生效”这类问题帮助极大。也只有在理解了nodeid之后，你才能真正用好-k表达式的匹配逻辑，因为它的底层实现就是在遍历节点树、对每个节点的nodeid做正则或表达式匹配。

3. Fixture 体系的底层逻辑：看似“魔法”的依赖注入是如何实现的

3.1 FixtureDef 与 FixtureManager 的核心结构

pytest 的 fixture 机制是我认为整个框架最精彩的部分，没有之一。从使用者的角度看，你只需要写：

@pytest.fixture def db(): return create_db()

然后在测试函数里加一个同名参数db，pytest 就会自动把返回值注入进来。但在源码层面，这个过程的复杂度远超大多数人认知。

核心有两个类：FixtureManager和FixtureDef。FixtureManager负责管理和解析所有 fixture 定义，它维护了三个关键字典：

• _name2fixturedefs：fixture 名字到定义列表的映射
• _arg2fixturedefs：参数名到 fixture 定义列表的映射
• _holder：节点与 fixture 的持有关系

当Module.collect()被调用时，会同步调用fixturemanager.parsefactories(self.obj)，这个函数会扫描模块里所有被@pytest.fixture装饰的对象，把每个 fixture 注册成FixtureDef。FixtureDef里保存了：

• fixture 函数本身
• scope：作用域
• params：参数化数据
• autouse：是否自动使用
• 以及其他配置信息

FixtureDef的内存结构决定了 pytest 在运行用例前就能静态分析出每个用例依赖哪些 fixture，而不需要等到执行时才发现问题。

3.2 fixture 实例化流程的完整路径

当Function需要执行时，pytest 会调用fixturemanager.getfixtureclosure获取这个用例所需的全部 fixture 依赖，形成一张依赖图。这张图会按依赖顺序排序，确保父级 fixture 先于子级 fixture 被实例化。

实际实例化发生在FixtureManager的_getautousefixtures和getfixtureinfo配合之下。getfixtureinfo会根据函数签名中的参数名，去_arg2fixturedefs里查找匹配的 fixture。找到后，pytest 会创建一个FixtureDef实例，这个实例内部有cached_result字段，用于存缓存值。

实例化流程的核心是FixtureDef.cached_result和finish()方法：

class FixtureDef: def __init__(self, ...): self.cached_result = None self._finalizer = [] ...

当一个 fixture 被请求时，pytest 会先检查当前作用域内是否已有缓存结果。如果有就直接返回缓存；如果没有，就调用 fixture 函数，拿到返回值后存入缓存，并注册 finalizer。scope的作用本质上就是决定这个cached_result挂在哪个节点上：function时挂在用例节点，class时挂在类节点，module时挂在模块节点，session时挂在 session 节点。

所以我常说，fixture 的scope不是“执行几次”的概念，而是“缓存放在哪一层”的概念。当你把scope="session"的 fixture 用在多个文件时，它只被创建一次，因为它的缓存放到了Session节点上；但你把它改成scope="function"，它就变成每个用例都创建一次，因为缓存跟着用例节点走。

3.3 yield fixture 与 teardown 的真实调用链

yield fixture 是个非常典型的语法糖，但如果你只停留在“yield 前半段是 setup，后半段是 teardown”的认知，那你还没真正理解它。源码层面，yield fixture 的处理逻辑在FixtureDef.execute和_pytest.fixtures.py的_FixtureManager中。

当 pytest 执行一个 yield fixture 时，它实际上把 fixture 函数封装成一个生成器调用。第一次next()获取 yield 出的值，将其作为 fixture 结果缓存；当整个测试层级结束后，pytest 才会继续驱动这个生成器，执行 yield 之后的代码，也就是 teardown 逻辑。

这个“推迟执行”是通过finalizer机制实现的。FixtureDef内部维护了一个_finalizer列表，调用生成器的close()或next()让生成器走到最后时，所有注册的 finalizer 都会被一一调用。

一个实际中的问题：如果你在 yield fixture 里写了 try/finally，那么 finally 里的代码仍然会执行，但如果你在 yield 之后写普通代码，它只在 teardown 阶段执行。这里的先后顺序和异常处理逻辑是：setup 阶段抛异常，测试用例不会执行，teardown 依然会执行。这一点在源码里的处理非常精细，是_pytest.fixtures.py里几百行代码专门处理的场景。

从我踩过的经验看，有一条建议特别值得说：不要在一个 fixture 里堆太多 teardown 逻辑，严格用request.addfinalizer或yield的后半段。因为 pytest 在执行 teardown 时是“反向顺序”的，后创建的 fixture 先销毁，这和 Python 的with语句嵌套展开是同一个顺序。你如果靠记忆去推断销毁顺序，非常容易出错，不如把每个资源销毁写清楚，再用request.addfinalizer明确注册。

3.4 动态 fixture 与 fixture 工厂模式

源码里还有个容易被忽略的场景：fixture 的“动态请求”。你可以在测试函数内部通过request.getfixturevalue("some_fixture")来动态获取一个 fixture，而不是在函数签名里静态声明。

这个 API 在_pytest.fixtures.py的FixtureRequest类里是这样实现的：

def getfixturevalue(self, argname): fixturedef = self._get_active_fixturedef(argname) return fixturedef.cached_result[0]

它会先检查当前请求上下文中是否有激活的 fixture 定义，如果没有，就尝试动态创建。动态创建和静态声明的唯一区别是“依赖分析阶段不同”：静态声明会在收集阶段就构建依赖图，动态请求则是到了执行阶段才临时去解析。所以你在动态请求时如果写错 fixture 名字，只有运行到那个用例时才会报错，而不是在收集阶段就失败。这个差异对排查“为什么我动态获取 fixture 时报 fixture not found”很有帮助。

fixture 工厂模式也很常见：你定义一个有返回函数的 fixture，外界通过调用这个函数来创建数据。比如：

@pytest.fixture def make_user(db): def _make_user(name): return User(name=name) return _make_user

本质上没有特殊的底层逻辑，只是测 fixture 可以返回任意对象，包括函数。但从经验上讲，这种模式有利于在用例内动态创建多份数据，同时又能共享外部资源（比如 db），非常推荐在接口自动化项目里使用。

4. 断言重写机制：pytest 凭什么能让断言失败信息那么详细

4.1 基于 AST 的断言改写过程

普通 Python 里，assert a == b失败后只会抛出AssertionError，没有更多信息。但 pytest 能把断言失败信息填充得极其丰富，比如：

assert 1 == 2 E assert 1 == 2 E + where 1 = func_a() E + and 2 = func_b()

这个能力来自 pytest 的断言重写（assertion rewriting）。原理一句话就能说清：pytest 会在导入测试模块时，先用ast模块解析源码，找出所有assert语句，把它们改写成一段能收集中间表达式的代码，然后再编译执行。

这个改写动作发生在_pytest/assertion/rewrite.py的AssertionRewriter类里。核心方法是：

def visit_Assert(self, assert_): # 计算断言表达式，并将中间结果保存到临时变量 ... self.statements.append(ast.fix_missing_locations(...))

它会将assert expr改写成类似这样的逻辑：

__assertion_expr = expr if not __assertion_expr: __assert_fail(...)

为了收集中间值，AssertionRewriter会递归遍历断言表达式，把每个子表达式赋值给一个新的临时变量，并生成对应的说明文字。这就是你在失败信息里能看到where 1 = func_a()的原因，因为原表达式里func_a()被单独提取成了一个中间变量。

4.2 字节码层面到底发生了什么

很多人以为断言重写只是“改一改源字符串”，实际上不是，它是在更底层的字节码编译阶段做手脚。

pytest 的导入钩子（PytestAssertRewriteHook）挂载在sys.meta_path上，当 Python 导入一个模块时，会先经过这个钩子。钩子判断模块路径是否匹配需要重写的规则（默认测试文件都会重写），如果匹配，就读取源码文件，用ast.parse得到 AST，然后由AssertionRewriter遍历并改写 AST，最后用compile()编译成 code object。

相比源字符串替换，AST 改写有两个突出优势：一是能把断言表达式和中间收集逻辑精确映射到代码块，不易出错；二是可以利用ast的位置信息，生成更精确的失败定位。

这里有个非常有意思的技术细节：为了减小性能损耗，pytest 只会重写测试模块，不会重写标准库和第三方库。判断标准在_pytest/assertion/rewrite.py里写得很清楚，但如果在配置里设置了--assert=plain，那就会完全禁用重写，断言就退回 Python 原生行为。--assert=reinterp是旧版的重新解释模式，性能较差，现在基本没人用。

4.3 自写断言辅助函数时需要注意的“改写陷阱”

断言重写不是万能的，它有几个明显的禁忌。第一个就是在conftest.py里定义断言辅助函数时，如果这个函数写的是：

def assert_foo(obj): assert obj.foo == 1 assert obj.bar == 2

这些assert也是会被重写的，但要确保这个模块本身被 pytest 判定为“需要重写”。pytest 对conftest.py的断言重写默认是开启的，所以一般没问题。

但有一个真实的坑是：如果你在非测试目录下定义了一个工具模块，它内部用了很多assert做参数校验，然后在测试代码里调用它，如果断言失败，pytest 并不会对这个模块做重写（因为它不属于测试模块），所以失败信息依然很稀薄。想要它也有详细输出，需要在pytest.ini或pyproject.toml里配置：

[tool:pytest] python_files = test_*.py assert = rewrite

python_files决定哪些文件在导入时会被重写。如果你希望某个公共工具模块也进入重写名单，可以直接在文件顶部加：

import pytest pytest.register_assert_rewrite("my_utils.assert_helpers")

调用这个函数必须在模块导入之前完成，通常放在conftest.py顶部。这个方法我实际用过，适合那些深度依赖assert的工具模块。

另外还要注意：AST 改写也不是完全没有成本的。它的性能开销主要在导入阶段，因为要额外解析和编译一份代码。对于测试文件数量很大的项目，这个时间会客观存在。好在 pytest 会缓存编译产物到__pycache__，源码没变时不会重复解析，所以大多数情况下可以接受。

5. 钩子机制与插件系统：一切皆可插拔的灵魂设计

5.1 pluggy 的 Hookspec 与 Hookimpl 约定

pytest 的插件系统并不是自己实现的，而是依赖一个独立的库叫pluggy。pluggy非常轻量，但设计极精妙。它的核心思想是：定义好“钩子规范”（Hookspec），然后让多个“插件实现”（Hookimpl）注册到同一个钩子上，框架在特定时机调用这个钩子，让所有实现按顺序依次执行。

在 pytest 源码里，你会看到大量这样的用法：

# _pytest/hookspec.py @hookspec(firstresult=True) def pytest_collection_modifyitems(session, config, items): ...

# 某个插件里 @pytest.hookimpl(tryfirst=True) def pytest_collection_modifyitems(session, config, items): ...

hookspec定义了这个钩子能传入什么参数、返回值怎么处理；hookimpl是具体实现。多个实现之间的执行顺序由tryfirst、trylast、hookwrapper等参数控制。

firstresult=True表示只要有一个实现返回了非None结果，就不继续调用后面的实现了。pytest_cmdline_main就是这样，它需要唯一的结果。

5.2 Hook 的执行顺序与 wrapper 的前后环绕

pluggy的调用顺序不是简单的注册顺序，而是经过排序的。排序参数按“权重”划分：

• tryfirst=True：尽量往前排
• trylast=True：尽量往后排
• 默认：排在中间
• hookwrapper=True：作为包装器执行（可以理解为“包裹住所有其他实现”）

hookwrapper是最难理解也最强大的概念。一个hookwrapper实现写的不是普通函数，而是生成器函数：

@pytest.hookimpl(hookwrapper=True) def pytest_runtest_makereport(item, call): outcome = yield report = outcome.get_result() # 拿到 report 后可以修改 report

yield之前的代码在所有普通实现之前执行；yield之后的代码在所有普通实现执行完后执行。这样就能实现对钩子结果的“前后夹击”：前置逻辑可以做初始化，后置逻辑可以修改结果。这个模式在 pytest 插件里极其常用，比如pytest-html、pytest-sugar都是靠它拿到测试报告再做二次加工的。

搞清楚这个之后，你才算真正解锁了 pytest 插件的玩法：不只是注册一个函数，而是可以让插件“监听”某个阶段、“包裹”某个阶段、“修改”某个阶段的结果。

5.3 如何自己动手写一个最小可用的插件

理解了底层逻辑之后，写一个最小插件其实很简单。一个插件本质上就是包含若干hookimpl的模块，然后被注册到 pytest 的插件系统里。

最简单的注册方式是放到conftest.py里：

# conftest.py import pytest @pytest.hookimpl(tryfirst=True) def pytest_collection_modifyitems(config, items): for item in items: item.add_marker(pytest.mark.slow)

这段代码会在收集完成后执行，给所有用例打上一个slow标记。你可以把它当做一个最简单的插件示例。

真正的独立插件则需要一个入口点（entry point），比如在pyproject.toml里注册：

[project.entry-points.pytest11] myplugin = "myplugin"

这样 pytest 启动时会自动加载myplugin模块。pytest11是 pytest 插件的标准入口点组名，后面跟的名字是插件名，值是对应的模块位置。

写插件的核心挑战其实是理解“在哪个钩子点做最合适”，这需要你对 pytest 的运行阶段有全局认识。我的经验是先花时间看懂_pytest/hookspec.py里所有钩子的注释，再根据需求挑对应的钩子，而不是拿着一堆钩子瞎试。

6. 用例执行协议：从 runtest 到测试报告的完整链路

6.1 pytest_runtest_protocol 与 setup/call/teardown 三段式

收集完成后，pytest 进入执行阶段。执行的最小单位是Item，也就是单个测试用例。pytest 定义了一个标准的“运行协议”，核心钩子是：

def pytest_runtest_protocol(item, nextitem): ...

这个钩子的职责是：给定一个测试项和下一个测试项，安排它的完整执行流程。默认实现中会调用：

• pytest_runtest_setup(item)：执行 setup
• pytest_runtest_call(item)：执行测试函数本身
• pytest_runtest_teardown(item, nextitem)：执行 teardown

也就是说，一个用例的完整生命周期就是这三段。你在用例里看到的setup_module、setup_function、fixture的 setup/teardown 逻辑，最终都会汇聚到这个三层协议里。

nextitem参数很重要，它表示“下一个要执行的用例”。pytest 用它在 teardown 时判断作用域：如果一个 session 级 fixture 在下一条用例还要用，就暂时不销毁；如果在当前用例之后不再需要，就立刻销毁。这是_pytest/runner.py里非常关键的一段逻辑，也是 fixture 能跨用例存活的核心原因。

6.2 CallInfo 与 TestReport 的数据结构

执行阶段会产生大量的运行信息。CallInfo是 pytest 里用来记录“一次调用结果”的数据结构，它包含when（调用时机，setup/call/teardown）、result（调用结果）、exc（异常信息）等。每完成一个阶段，pytest 就会生成一个TestReport，最终汇报给用户。

TestReport的定义大致是：

class TestReport: def __init__(self, nodeid, location, keywords, outcome, longrepr, when, ...): ...

其中：

• outcome：passed、failed、skipped之一
• longrepr：失败时的详细内容，内容类型可能是字符串、异常信息或 traceback
• when：标记这个 report 属于 setup、call 还是 teardown

TestReport不仅用于终端展示，也是生成各种报告（HTML、JUnit XML）的基础数据源。pytest_runtest_makereport这个钩子就是负责在三个不同阶段分别生成TestReport，你可以在hookwrapper里捕获三次报告，然后做汇总判断，很多插件都是这么判断“这个用例是否最终失败”的。

6.3 skipped、xfail、参数化执行时的状态流转

状态流转是执行协议里最容易出 bug 的部分。比如一个用例在 setup 阶段就失败了，还会不会执行 teardown？答案是一般会执行 teardown，但不会执行 call。这个“哪些阶段跑、哪些阶段跳过”由pytest_runtest_makereport根据异常类型和之前的报告结果来决策。

skipped通常发生在 fixture 或 setup 中抛了pytest.skip.Exception。xfail分两种情况：一是声明了@pytest.mark.xfail且实际失败，状态是xfailed（预期失败，但没有真正失败时记xpassed）；二是在测试内部调用pytest.xfail()主动标记。这些状态最终都会反映到报告里，但各自的计数和展示逻辑不同。

参数化对执行协议的影响值得单独提一句：一个参数化的用例在收集阶段会被展开成多个Function实例，所以执行阶段对 pytest 来说就是“按顺序执行 N 个独立用例”，参数化展开发生在收集阶段，跟执行阶段没有耦合。这也是为什么你在参数化用例里用fixture时，每次参数值都会重新走一遍 fixture 的获取逻辑，因为它们是不同的Item。

6.4 从运行协议看--pdb和--lf的实现位置

理解运行协议后，你就能看懂很多常用选项的底层实现。

--pdb（失败进入调试器）是在pytest_runtest_makereport阶段处理的：当 report 的failed为真时，pytest 检查是否有--pdb选项，如果启用就调用pdb.post_mortem进入调试。

--lf（只跑上次失败的用例）是在收集阶段之后、执行之前实现的。pytest_collection_modifyitems钩子里，pytest 会根据上次运行的报告缓存（cacheprovider插件维护的.pytest_cache目录）判断哪些用例上次失败，然后把失败用例重新排到前面或过滤出来。

这也是为什么--lf能立刻生效：它不需要去分析历史日志，只需读取.pytest_cache/v/cache/lastfailed这样一个简单文件。这个文件的内容就是上次失败用例的nodeid集合。明白了这一点，你甚至可以手动修改这个文件来“伪造”历史失败数据，从而精确控制下一次--lf的运行范围。

7. 二次开发与调试：基于源码层面的排错经验

7.1 调试 pytest 源码的实用方法

读源码不光是为了“读懂”，更重要的是能在实际遇到问题时快速定位。我的调试方法一般有三种。

第一种，直接打印 hook 调用链。在conftest.py里加一个 hookwrapper：

@pytest.hookimpl(hookwrapper=True) def pytest_runtest_protocol(item, nextitem): print(f"RUN {item.nodeid}") yield

这样你能看到用例执行的真实顺序，对照节点树是否符合预期。这个方法比看终端输出直观得多，特别是排查 fixture 的 setup/teardown 顺序。

第二种，利用pytest --trace-config。这个选项会打印 pytest 启动时的配置加载过程，包括从哪里读取的配置、加载了哪些插件。排查“我的配置怎么没生效”时非常有用。

第三种是用 Python 的breakpoint()结合--pdb。你可以在自己写的插件代码里埋breakpoint()，pytest 执行到那行时会自动打开pdb，然后你就可以单步跟踪源码了。不过要注意，--pdb通常指的是测试用例失败时进入pdb，跟在自己代码里加breakpoint()是两回事，自己加的不需要--pdb。

7.2 常见源码级问题的排查思路

我整理了几个网上问得非常多的、且确实需要源码知识才能解决的典型问题：

问题 1：为什么 confest.py 里的 fixture 用不到？

大概率原因是conftest.py的作用域只覆盖它所在目录及子目录。这是_pytest/python.py里Package收集器在导入conftest.py时遵循“目录层级最近”原则导致的。解决方案是检查用例文件的目录层级，确定conftest.py与用例文件的相对位置。

问题 2：为什么 session 级 fixture 在同一个测试函数里被调了两次？

这通常不是 fixture 本身的问题，而是你用了request.getfixturevalue()动态获取了几次，但缓存没生效。原因可能是你把 scope 写成了"function"或没有写 scope 默认就是 function。如果是scope="session"还出现多次创建，检查是否在子进程中运行（如pytest-xdist），每个 worker 都有自己的 fixture 缓存空间。

问题 3：为什么删除某个临时文件失败，报错发生在 teardown 阶段？

这是因为 teardown 阶段会执行finalizer，如果你的 fixture 里的 teardown 代码抛了异常，pytest 会把这个异常记录为一个 teardown 错误，并通过pytest_runtest_makereport状态合并到当前用例的结果里。此时测试函数本身可能通过了，但报告里依然会显示失败。排查时看when="teardown"的TestReport就能定位。

7.3 性能优化视角下的源码阅读价值

最后说一个很多人没意识到的点：读懂源码对性能优化帮助巨大。pytest 在大型项目上的执行速度往往被诟病，但其实大部分性能瓶颈都可以通过源码找到依据。

比如--collect-only只是完成了收集阶段，没有执行阶段，所以速度很快。如果一个项目--collect-only都很慢，问题就出在收集阶段的模块导入。而收集阶段会导入每个测试文件，如果这些测试文件顶层做了大量耗时操作（比如创建数据库连接、加载大模型），那收集速度自然慢。

再比如 fixture 的作用域选择。把scope="session"的 fixture 用在每个测试函数里，并不意味着所有测试函数都共享同一个实例，因为缓存是在Session节点上，但如果你的测试是分布式执行，每个 worker 依然会创建一份。这也就是pytest-xdist存在的必要性，同时你在写 session 级 fixture 时要清楚它只能保证“单进程内共享”，不是“跨进程全局共享”。

从源码角度看性能优化，思路就会清晰很多：收集慢就优化导入，执行慢就分析夹具缓存，报告慢就看终端插件是否做了过多格式化。这些都能从源码中找到对应实现。

8. 写在最后的几个技巧

根据我长期使用和阅读 pytest 源码的经验，有几个小技巧值得分享。

第一个技巧：善用pytest_fixture_setup和pytest_fixture_post_finalizer这两个钩子做 fixture 的全局监控。如果你想知道项目里哪些 fixture 是性能瓶颈，可以在这两个钩子里记录时间差。

第二个技巧：直接改PYTEST_DISABLE_PLUGIN_AUTOLOAD=1环境变量可以禁用所有第三方插件自动加载。当怀疑某个插件导致测试行为异常时，用这个变量做对照实验，能在不卸载插件的情况下快速定位问题。

第三个技巧：通过nodeid的精确筛选，可以规避参数化用例之间的相互干扰。例如只跑某个参数化分支，直接用pytest "test_demo.py::test_add[1+2-3]"，带引号是因为命令行里[、]会被 shell 解释，加引号能避免匹配错误。

读源码的最终意义不在于“背出每一行的实现”，而在于建立一种“对框架行为有预判”的直觉。我见过太多测试工程师在遇到奇怪问题时，第一反应是“pytest 有 bug”或者“一定是我的运气不好”，但大多时候回到源码里排查一遍，都能找出真实原因。养成这种习惯之后，你再写 pytest 用 pytest，心态会完全不同。你不再是“调用这个框架”，而是“和这个框架协同工作”，这种感受是我最想通过这篇源码解析传达给读者的。