子目录自定义pytest插件的pytest_addoption钩子未触发，如何添加命令行选项？

问题背景 #

将自定义pytest插件放在独立子目录tests/bar/中，目录结构如下：

.
├── tests
│   ├── bar
│   │   └── conftest.py
│   ├── conftest.py
│   └── test_main.py

根目录tests/conftest.py通过pytest_plugins = ['bar']显式导入子目录插件，且已确认插件被成功注册，但tests/bar/conftest.py中实现的pytest_addoption()钩子未被调用，导致--bar命令行选项无法生效；而根conftest中定义的--foo选项正常工作。

原因解析 #

pytest_addoption属于pytest的早期初始化钩子，其执行时机在pytest启动的最开始阶段——此时pytest仅加载根目录的conftest.py和全局安装的插件，还未开始扫描子目录中的测试文件和子级conftest.py。

即使通过pytest_plugins显式导入子目录插件，子级conftest.py的加载时机依然晚于命令行参数解析阶段，因此其中的pytest_addoption钩子没有机会被执行。这是pytest插件发现机制的硬性规则，官方文档也明确提示：此函数应仅在测试根目录的插件或conftest.py文件中实现。

可行解决方案 #

方案1：将子目录插件转为可安装的标准pytest插件 #

把bar子目录改造为标准的pytest插件结构，便于pytest在启动阶段加载：

1. 调整目录结构：

tests/
├── bar/
│   ├── __init__.py
│   └── plugin.py
├── conftest.py
└── test_main.py

2. 将tests/bar/conftest.py的内容迁移到plugin.py：

# tests/bar/plugin.py
def pytest_addoption(parser):
    parser.addoption("--bar", action="store_true", help="BAR")

3. 在项目根目录创建pyproject.toml，声明插件信息：

[project]
name = "pytest-bar"
version = "0.1.0"
dependencies = ["pytest>=7.0"]

[project.entry-points."pytest11"]
bar = "bar.plugin"

4. 以可编辑模式安装插件：

pip install -e .

之后pytest启动时会自动识别并加载该插件，--bar选项即可正常生效。

方案2：在根conftest中代理子目录的选项注册 #

如果不想做成可安装插件，可直接在根tests/conftest.py中调用子目录插件的选项注册逻辑：

# tests/conftest.py
from bar.conftest import pytest_addoption as bar_addoption

pytest_plugins = ['bar',]

def pytest_addoption(parser):
    parser.addoption("--foo", action="store_true", help="FOO")
    # 调用子目录插件的选项注册逻辑
    bar_addoption(parser)

这种方式利用根conftest的早期加载时机，间接完成--bar选项的注册，同时子目录插件的其他钩子仍可正常工作。

方案3：手动提前加载子目录插件（不推荐） #

通过pytest内部API手动在初始化阶段加载子目录插件，这种方式依赖pytest内部实现，版本更新后可能失效：

# tests/conftest.py
import importlib.util
import os
import pytest

def pytest_configure(config):
    # 手动加载并注册子目录conftest
    bar_conftest_path = os.path.join(os.path.dirname(__file__), "bar", "conftest.py")
    spec = importlib.util.spec_from_file_location("bar.conftest", bar_conftest_path)
    bar_conftest = importlib.util.module_from_spec(spec)
    spec.loader.exec_module(bar_conftest)
    config.pluginmanager.register(bar_conftest)

pytest_plugins = ['bar',]

def pytest_addoption(parser):
    parser.addoption("--foo", action="store_true", help="FOO")

总结 #

优先选择方案1（标准插件）或方案2（根conftest代理）：方案1符合pytest插件规范，适合复杂插件逻辑的长期维护；方案2实现简单，适合小型自定义场景。方案3仅作为临时 workaround，不建议在生产环境使用。

内容的提问来源于stack exchange，提问作者davidA