披露:

该项目与Claude Code有着显著的协助。完整的测试用例、CI 矩阵和审阅过程在仓库中可见。

  • 源码: https://github.com/mikelane/pytest-gremlins
  • PyPI: https://pypi.org/project/pytest-gremlins/
  • 文档: https://pytest-gremlins.readthedocs.io/
  • GitHub Action: https://github.com/marketplace/actions/pytest-gremlins

项目功能

pytest-gremlins 是一个pytest 插件，于你的 Python 代码执行变异性测试。它将小的变化（“鬼怪”）注入你的源代码（将 “+” 替换为 “-” 、将 “＆gt;” 替换为 “＆gt;=“ 、将 “True” 替换为 “False” 等），然后再次运行你的测试。如果你的测试仍然通过了变异后，说明你的测试套件中存在空白，那么单纯的代码覆盖率无法揭示。

该核心速度机制是变异切换：不需要在文件系统中重写文件以便于每个变异，而是对 AST 层面进行一次编译，然后将所有变异嵌入到环境变量的切换下。无需文件I/O以便于每个变异，也无需重载模块。代码覆盖率用来确定哪些测试执行了每个变异，从而只执行相关的测试。

pip install pytest-gremlins
pytest --gremlins -n auto --gremlin-report=html

1.5.0 版本更新内容:

  • 多线程评估：xdist
    pytest --gremlins -n auto 可以兼容test分布和变异并行。一个标志，无需单独的工作者配置。
  • 在线免杀： # gremlin: pardon[equivalent] 可以免杀变异，并且可以用“ -- max-pardons-pct” 来设置免杀百分比的上限，以避免免杀降低得分。
  • 全面的 pyproject.toml 配置：每个 CLI 标志都有一个 [tool.pytest-gremlins] 等效值。
  • HTML 报告：有趋势图可以跟踪变异得分。色彩和对比度配置遵循WCAG 2.1AA。
  • 增量缓存：结果是通过内容哈希来键值对的。无效的代码和测试在后续执行时可以全速跳过。

1.5.1 版本更新内容（发布一天后）：多重格式报告： “--gremlin-report=json,html” 可以同时生成JSON 和 HTML报告。

pytest-gremlins-action 现在可以在 GitHub 市场上下载：

- uses: mikelane/pytest-gremlins-action@v1
  with:
    threshold:80
    parallel: 'true'
    cache: 'true'

这样可以在 GitHub Actions 中并发执行变异性测试，并且在得分降低到你设置的阈值时就失败执行。

目标受众

为Python代码编写测试并希望知道那些测试是否能够捕捉到错误的Python开发者。如果你已经使用了pytest，并且想要在测试质量方面获得比代码覆盖率更多的反馈，目前在PyPI中可用，持续集成在12个支持的平台和版本上测试并且（Python 3.11至3.14的Linux、macOS和Windows）。

对比

与 mutmut 对比

mutmut 是最活跃的替代方案之一（v3.5.0，2026年2月）。它是一个可以单独执行的命令 (mutmut run），而不是 pytest 插件，所以它不会与你的 pytest 配置、fixture 和 xdist 设置集成。（两种都支持基于测试覆盖率的测试选择和增量缓存。 pytest-gremlins 将所有变异嵌入到在环境变量切换中生成的单一instrumented copy（在AST 层面），而mutmut 每执行一个变异都会生成和测试一个。而在 pytest-gremlins 中，还可以通过HTML 趋势图和WCAG可访问的报告来获取报告。

与 cosmic-ray 对比

cosmic-ray 利用import hook注