使用xdist+django_coverage_plugin运行pytest并行覆盖率报告问题排查

核心根因 #

仅生成1个覆盖率文件、统计值偏低的直接原因是：pytest-xdist 启动的 worker 子进程未加载项目根目录下的sitecustomize.py，子进程未启动覆盖率采集逻辑，只有主进程的采集数据被纳入统计，最终结果远低于单线程运行的真实值。

coverage.py 的多进程采集逻辑依赖子进程启动时自动加载sitecustomize.py、执行coverage.process_startup()钩子完成采集初始化，子进程找不到该文件时就不会产生独立的覆盖率数据文件。

分步修复操作 #

• 补全环境变量，保证子进程能加载初始化脚本
  执行命令时新增PYTHONPATH=./配置，将项目根目录加入Python导入搜索路径，确保worker进程启动时能优先找到根目录下的sitecustomize.py。如果子进程存在工作目录切换的场景，可将COVERAGE_PROCESS_START替换为.coveragerc的绝对路径，避免配置文件查找失败。
• 精简执行命令，移除冗余参数
  你已经在.coveragerc中配置了parallel = True和concurrency = multiprocessing，命令行无需重复传入--parallel-mode、--concurrency=multiprocessing参数，避免参数优先级冲突。修正后的完整执行命令如下：

  coverage erase
  PYTHONPATH=./ COVERAGE_PROCESS_START=$(pwd)/.coveragerc coverage run -m pytest -n 8
  coverage combine
  coverage report
  

• 结果校验
  执行完coverage run步骤后、执行coverage combine前，检查项目根目录：正常情况下会生成9个左右后缀带随机字符串/进程ID的.coverage.*格式文件（8个worker进程+1个主进程各生成1个），如果文件数量符合预期，说明所有进程都已正常启动覆盖率采集，combine后的统计结果会和单线程结果一致。

额外排查项 #

如果完成上述操作后结果仍有偏差，可逐一排查以下配置问题：

• 确认sitecustomize.py存放在项目根目录，不要放在lettergun等业务包目录下，否则Python启动时不会自动加载该文件。
• 确认django_coverage_plugin版本与当前使用的coverage.py、Django版本匹配，版本不兼容会导致模板、视图层代码漏统计。
• 移除pytest.ini中所有与coverage相关的启动参数，不要混用pytest-cov插件和原生coverage命令，避免采集逻辑冲突导致数据丢失。
• 检查.coveragerc的omit规则，确认没有误排除实际需要统计的业务代码路径。

注意：执行combine命令前不要手动删除任何.coverage开头的临时文件，否则会丢失对应进程的采集数据。

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