Django测试断言查询次数失败：受SQL EXPLAIN查询干扰

核心原因 #

这种现象的本质是pytest全局运行时加载了额外的配置/插件，自动为每个业务查询附加了EXPLAIN分析语句，而单文件运行或原生Django测试器未触发该逻辑。常见触发场景包括：

• 全局pytest配置加载了包含Django Debug Toolbar的测试环境（其SQL面板默认会执行EXPLAIN）
• 项目conftest.py中存在全局生效的测试夹具，自动注入EXPLAIN逻辑
• 安装了自动添加EXPLAIN的pytest第三方插件

解决办法 #

1. 检查并调整pytest全局配置 #

查看项目根目录下的pytest.ini、tox.ini或setup.cfg，确认是否指定了带Debug Toolbar的Django配置：

[pytest]
DJANGO_SETTINGS_MODULE = myproject.settings.test_debug

如果是，改为纯测试用配置；或在测试配置中关闭Debug Toolbar的SQL面板：

# test_settings.py
DEBUG_TOOLBAR_CONFIG = {
    'DISABLE_PANELS': [
        'debug_toolbar.panels.sql.SQLPanel',
    ],
}

2. 排查全局测试夹具 #

检查conftest.py文件，是否存在自动修改数据库游标、注入EXPLAIN的代码，比如：

# 示例：可能存在的恶意代码
from django.db.backends.utils import CursorWrapper

def wrap_execute(func):
    def wrapper(*args, **kwargs):
        res = func(*args, **kwargs)
        args[0].execute(f"EXPLAIN {args[1]}")
        return res
    return wrapper

def pytest_configure():
    CursorWrapper.execute = wrap_execute(CursorWrapper.execute)

这类代码要么直接删除，要么改为通过测试标记按需启用：

import pytest
from django.db.backends.utils import CursorWrapper

@pytest.fixture(autouse=False)
def enable_explain(request):
    if request.node.get_closest_marker('enable_explain'):
        original_execute = CursorWrapper.execute
        CursorWrapper.execute = wrap_execute(original_execute)
        yield
        CursorWrapper.execute = original_execute

需要EXPLAIN的测试添加@pytest.mark.enable_explain标记，其余测试不受影响。

3. 禁用或卸载相关pytest插件 #

执行pip list | grep pytest查看已安装插件，若存在pytest-django-explain这类自动生成EXPLAIN的插件，可直接卸载，或在pytest配置中禁用：

[pytest]
addopts = -p no:pytest-django-explain

4. 测试类内临时屏蔽EXPLAIN #

若以上方法未解决问题，可在测试类中临时覆盖游标执行逻辑，过滤EXPLAIN语句：

from django.test import TestCase
from django.db.backends.utils import CursorWrapper

class MyTestClass(TestCase):
    def setUp(self):
        self._original_execute = CursorWrapper.execute
        def filtered_execute(*args, **kwargs):
            # 跳过EXPLAIN开头的查询
            if args[1].strip().upper().startswith("EXPLAIN"):
                return None
            return self._original_execute(*args, **kwargs)
        CursorWrapper.execute = filtered_execute

    def tearDown(self):
        CursorWrapper.execute = self._original_execute

    def test_query_count(self):
        with self.assertNumQueries(12):
            some_service_call()

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