# pytest-gremlins

[![PyPI version](https://img.shields.io/pypi/v/pytest-gremlins.svg)](https://pypi.org/project/pytest-gremlins/)
[![Python versions](https://img.shields.io/pypi/pyversions/pytest-gremlins.svg)](https://pypi.org/project/pytest-gremlins/)
[![CI](https://github.com/mikelane/pytest-gremlins/actions/workflows/ci.yml/badge.svg)](https://github.com/mikelane/pytest-gremlins/actions/workflows/ci.yml)
[![codecov](https://codecov.io/gh/mikelane/pytest-gremlins/branch/main/graph/badge.svg)](https://codecov.io/gh/mikelane/pytest-gremlins)
[![Documentation](https://readthedocs.org/projects/pytest-gremlins/badge/?version=latest)](https://pytest-gremlins.readthedocs.io)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

> 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
================== 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`](cookbook/github-action.md)

## 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

- [Getting Started](guide/getting-started.md) - Installation and first run
- [Configuration](guide/configuration.md) - Customize pytest-gremlins
- [Operators](guide/operators.md) - Available mutation operators
