# pytest 插件开发：如何确保非插件模块的 assert 语句被重写
## 摘要
在编写 pytest 插件时，若插件包内包含 `helper.py` 等非核心入口的辅助模块，其中的 `assert` 语句默认不会被 pytest 的重写机制处理。本文依据官方文档说明，解析了如何通过 `register_assert_rewrite()` 显式注册模块名，以及利用 `pytest_plugins` 自动标记的特性，确保所有相关模块在导入前完成断言重写。
## 核心机制：何时需要手动注册
pytest 的断言重写功能依赖于 PEP 302 import hook，该钩子会在 pytest 启动早期安装。其默认行为是仅重写测试文件（由 `python_files` 配置定义）和插件模块本身。
对于通过包入口点（entry points）安装的第三方插件，pytest 会将入口点对应的模块视为插件并进行重写。然而，如果插件是一个包（package），包含多个子模块（如 `pytest_foo/helper.py`），仅注册入口点模块（如 `pytest_foo.plugin`）是不够的。
官方文档明确指出：
> "The import hook only treats conftest.py files and any modules which are listed in the pytest11 entrypoint as plugins."
这意味着，如果 `helper.py` 中包含需要详细报错信息的 `assert` 语句，且该模块未被显式标记，它将不会被重写，导致断言失败时无法看到详细的 traceback。
## 解决方案一：在 __init__.py 中调用 register_assert_rewrite()
这是处理包内辅助模块最推荐的做法。由于 Python 导入机制会先加载 `__init__.py`，此时可以安全地调用 `pytest.register_assert_rewrite()` 来注册包内的所有子模块。
假设插件结构如下：
- `pytest_foo/__init__.py`
- `pytest_foo/plugin.py` (入口点)
- `pytest_foo/helper.py` (包含 assert 语句)
在 `pytest_foo/__init__.py` 中应执行以下操作：
```python
import pytest
# 注册 helper 模块及其子模块（如果存在）
pytest.register_assert_rewrite("pytest_foo.helper")
```
这样做的好处是，当用户导入 `pytest_foo.plugin` 时，`__init__.py` 会先执行，确保 `helper.py` 在后续被导入前已被标记为需要重写。这样既保持了正常的导入流程，又满足了断言重写的要求。
## 解决方案二：利用 pytest_plugins 自动处理
pytest 提供了另一种机制：当测试模块或 `conftest.py` 文件中声明了 `pytest_plugins = ["plugin_name"]` 时，pytest 会自动加载该插件，并且**自动将该插件的所有模块标记为需要断言重写**。
文档中提到：
> "Plugins imported by pytest_plugins will also automatically be marked for assertion rewriting..."
这意味着，如果你通过 `pytest_plugins` 引入一个插件，你不需要手动调用 `register_assert_rewrite()`。只要该插件是通过 `pytest_plugins` 变量加载的（无论是在测试文件中还是根目录的 `conftest.py` 中），其内部所有模块都会被自动处理。
**注意**：此机制仅在模块尚未被导入时生效。如果模块在 `pytest_plugins` 处理前已被导入，则不会触发重写，此时仍需手动调用 `register_assert_rewrite()` 或调整导入顺序。
## 总结与建议
1. **对于包结构插件**：建议在 `__init__.py` 中显式调用 `pytest.register_assert_rewrite("package.submodule")`，以确保所有子模块的断言都能获得详细报错信息。
2. **对于通过 pytest_plugins 引入的插件**：通常无需手动注册，pytest 会自动处理。但需确保在模块导入前完成声明。
3. **避免依赖默认行为**：不要假设所有导入的模块都会被重写，尤其是包内的非入口点模块。
遵循上述规范，可确保你的 pytest 插件在提供扩展功能的同时，也能保持断言失败时的诊断能力。