pytest-gremlins
pytest-gremlins is a free, MIT-licensed pytest plugin that checks whether an existing test suite catches small changes to Python code.
What pytest-gremlins is
pytest-gremlins is a free, MIT-licensed pytest plugin that checks whether an existing test suite catches small changes to Python code. It introduces mutations and runs tests against them; mutations that survive can point to properties the tests do not detect. The project requires Python 3.11 or later, pytest 7.0 or later, and an existing test suite. Its documented quick start installs the package with `pip install pytest-gremlins` and runs `pytest --gremlins`; installation instructions also cover uv and Poetry. To manage execution, it uses mutation switching, coverage-guided test selection, incremental analysis, and parallel runs. It works with pytest-xdist, and a GitHub Action can run mutation tests and fail a workflow when the score falls below a threshold. CI examples also cover GitLab CI, CircleCI, and Dagger. Results can be reported in the console, HTML, or JSON, with multiple formats in one run. Configuration is available in `pyproject.toml` or command-line flags, and inline pragmas can pardon mutations. The guide warns that an initial run may take 10–100 times as long as a normal test run.
Good
- Works with existing pytest test suites.
- Provides console, HTML, and JSON reports.
- Supports parallel execution and incremental analysis.
- GitHub Action can enforce a mutation-score threshold.
- Free and MIT-licensed.
Watch out
- Requires Python 3.11 or later.
- Requires pytest 7.0 or later.
- An initial run may take 10–100 times longer than normal tests.
- The package is classified as Alpha.
Who it suits
pytest-gremlins is for Python developers who already use pytest and want to assess whether their tests catch changes in important code. The guide recommends focusing on business logic, security-critical code, and financial calculations.
Verdict
pytest-gremlins adds mutation testing to an existing pytest workflow, with reporting and CI options. Account for the Python and pytest requirements and the potentially long first run.
Plans and prices
From pytest-gremlins's own pricing page, checked 7 Oct 2026.
| Plan | Price | What it gives you |
|---|---|---|
| pytest-gremlins | Free | MIT-licensed Python package · requires Python 3.11+ |
The facts
Each one read from pytest-gremlins's own pages, with the date it was checked.
What it does
- Audience
- The guide recommends focusing mutation testing on business logic, security-critical code, and financial calculations.checked 7 Oct 2026
- CI integrations
- The GitHub Action documentation points to manual CI workflow examples for GitHub Actions, GitLab CI, CircleCI, and Dagger.checked 7 Oct 2026
- CI options
- The CI integration guide covers GitHub Actions, GitLab CI, CircleCI, and Dagger.checked 7 Oct 2026
- Configuration
- Options can be configured through `pyproject.toml` or command-line flags, and mutations can be pardoned with an inline pragma.checked 7 Oct 2026
- Development status
- The package metadata classifies its development status as Alpha.checked 7 Oct 2026
- GitHub integration
- The composite GitHub Action installs a project, runs mutation testing, and can fail a workflow when the mutation score is below a threshold.checked 7 Oct 2026
- Installation
- The project documents installation with pip, uv, and Poetry.checked 7 Oct 2026
- Installation requirements
- The getting started guide requires Python 3.11 or later, pytest 7.0 or later, and a project with existing tests.checked 7 Oct 2026
- Integrations
- The documentation describes compatibility with pytest-xdist and a GitHub Action for running mutation tests and enforcing a score threshold.checked 7 Oct 2026
- License
- The project is MIT licensed.checked 7 Oct 2026
- Limits
- The guide says equivalent mutations can make a 100% mutation score impossible and not worth pursuing.checked 7 Oct 2026
- Mutation control
- Users can suppress equivalent or untestable mutations inline with `# gremlin: pardon[reason]`.checked 7 Oct 2026
- Publishing provenance
- PyPI reports that the October 6, 2026 release was uploaded using Trusted Publishing and has a verified attestation signed by GitHub Actions.checked 7 Oct 2026
- Purpose
- pytest-gremlins is a pytest plugin that injects small code mutations and checks whether tests catch them.checked 7 Oct 2026
- pytest integration
- The plugin works with existing pytest test suites and pytest-xdist, including `-n auto`.checked 7 Oct 2026
- Python requirement
- The package requires Python 3.11 or later.checked 7 Oct 2026
- Reports
- It supports console, HTML, and JSON reports, including multiple report formats in one run.checked 7 Oct 2026
- Runtime
- The guide says a first mutation-testing run may take 10–100 times as long as a normal test run; caching can make later runs faster.checked 7 Oct 2026
- Security and license
- The repository identifies the project as MIT-licensed; the license text provides the software “AS IS” without warranty.checked 7 Oct 2026
- Setup
- The project says mutation testing can be started with `pip install pytest-gremlins` and `pytest --gremlins`.checked 7 Oct 2026
- Speed
- Its speed features include mutation switching, coverage-guided test selection, incremental analysis, and parallel execution.checked 7 Oct 2026
- Speed features
- It uses mutation switching, coverage-guided test selection, incremental analysis, and parallel execution.checked 7 Oct 2026
Alternatives to pytest-gremlins
- 1
Mutatest
Free planOpen sourceAPILinuxmacOSSelf-hosted7.2Free plan - 2
ArcMutate
Free planLinuxmacOSSelf-hostedWindows6.7From $8 a month - 3
Mutant
Free planLinuxmacOS6.7From $250 a year - 4
MuJava
Free planLinuxmacOSWindows6.3Free plan - 5
pymute
Free planLinux6.3Free plan - 6
go-mutesting
Free planLinuxSelf-hosted6.2Free plan