Skip to content

pytest-gremlins

PyPI version Python versions CI codecov Documentation License: MIT

Let the gremlins loose. See which ones survive.

pytest-gremlins is a fast-first mutation testing plugin for pytest. It helps you evaluate the quality of your test suite by injecting small changes (gremlins) into your code and checking if your tests catch them.

Why Mutation Testing?

Code coverage tells you what code your tests execute, but not whether your tests would catch bugs. Mutation testing answers a harder question: if I introduce a bug, will my tests fail?

pytest-gremlins creates "gremlins" (small code mutations like changing >= to >) and runs your tests against each one. If your tests pass despite the gremlin, you've found a weakness in your test suite.

Quick Start

Install pytest-gremlins:

Bash
pip install pytest-gremlins

Run mutation testing:

Bash
pytest --gremlins

See It In Action

Text Only
================== pytest-gremlins mutation report ==================

Zapped: 8 gremlins (80%)
Survived: 2 gremlins (20%)

Top surviving gremlins:
  src/auth.py:42              >= to >              (comparison)
  src/utils.py:17             + to -               (arithmetic)

Run with --gremlin-report=html for detailed report.
=====================================================================

Features

  • Fast -- Mutation switching, coverage-guided selection, incremental analysis, parallel execution
  • Native pytest integration -- Works with your existing test suite, including pytest-xdist (-n auto)
  • Inline pardoning -- Suppress equivalent or untestable mutations with # gremlin: pardon[reason]
  • Configurable -- Full pyproject.toml support for all options, plus CLI flags
  • Great reports -- Console, HTML (with trend charts), and JSON output; multiple formats in one run
  • GitHub Action -- One-step CI with pytest-gremlins-action

The Gremlins Theme

We use Gremlins movie references as our domain language:

Traditional Term Gremlin Term Meaning
Original code Mogwai Your clean, untouched source code
Start mutation testing Feed after midnight Begin the mutation process
Mutant Gremlin A mutation injected into your code
Kill mutant Zap Your test caught the mutation
Surviving mutant Survivor Mutation your tests missed

Next Steps