- Home
- Mutation Testing Tools
- pytest-gremlins
pytest-gremlins
What it is
pytest-gremlins is a pytest plugin for mutation testing: it makes small changes to code and checks whether an existing test suite catches them. It is designed for Python projects and requires Python 3.11 or later, pytest 7.0 or later, and existing tests. The project describes a quick start using `pip install pytest-gremlins` and `pytest --gremlins`, with installation also documented through uv and Poetry. To manage runtime, it uses mutation switching, coverage-guided test selection, incremental analysis, and parallel execution. It works with pytest-xdist, including `-n auto`, and offers a GitHub Action that can fail a workflow when a mutation score falls below a chosen threshold. CI guidance also covers GitLab CI, CircleCI, and Dagger. Results can be printed or saved as HTML and JSON, including multiple formats in one run. Configuration can live in `pyproject.toml` or command-line flags, and inline pragmas can pardon mutations. The guide warns that a first run may take 10–100 times as long as a normal test run; caching may shorten later runs. The package is MIT-licensed and classified as Alpha.
For and against
For
- Supports pytest-xdist and parallel execution.
- Provides console, HTML, and JSON reports.
- Includes a GitHub Action score threshold.
- Offers incremental analysis and coverage-guided selection.
- Licensed under MIT.
Against
- Requires Python 3.11 or later.
- Requires pytest 7.0 or later and existing tests.
- A first run may take 10–100 times longer.
- Alpha development status.
The verdict
pytest-gremlins adds mutation testing to an existing pytest workflow, with reporting, configuration, and CI options. Expect a potentially much longer initial run, and treat a perfect mutation score as an unsuitable goal where equivalent mutations exist.
Who it suits
It suits Python teams with existing pytest suites who want to assess tests around business logic, security-critical code, or financial calculations. It is also relevant to teams that want mutation testing in CI.
Plans and prices
pytest-gremlins
MIT-licensed Python package · requires Python 3.11+
Read 7 Oct 2026 · github.com
On the record
- Audience
- The package metadata lists developers as its intended audience.pypi.org · read 7 Oct 2026
- CI integrations
- The GitHub Action documentation points to manual CI workflow examples for GitHub Actions, GitLab CI, CircleCI, and Dagger.pytest-gremlins.readthedocs.io · read 7 Oct 2026
- CI options
- The CI integration guide covers GitHub Actions, GitLab CI, CircleCI, and Dagger.pytest-gremlins.readthedocs.io · read 7 Oct 2026
- Configuration
- Options can be configured through `pyproject.toml` or command-line flags, and mutations can be pardoned with an inline pragma.pytest-gremlins.readthedocs.io · read 7 Oct 2026
- Development status
- The package metadata classifies its development status as Alpha.pypi.org · read 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.pytest-gremlins.readthedocs.io · read 7 Oct 2026
- Installation
- The project documents installation with pip, uv, and Poetry.github.com · read 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.pytest-gremlins.readthedocs.io · read 7 Oct 2026
- Integrations
- The documentation describes compatibility with pytest-xdist and a GitHub Action for running mutation tests and enforcing a score threshold.pytest-gremlins.readthedocs.io · read 7 Oct 2026
- License
- The project is MIT licensed.github.com · read 7 Oct 2026
- Limits
- The guide says equivalent mutations can make a 100% mutation score impossible and not worth pursuing.pytest-gremlins.readthedocs.io · read 7 Oct 2026
- Mutation control
- Users can suppress equivalent or untestable mutations inline with `# gremlin: pardon[reason]`.pytest-gremlins.readthedocs.io · read 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.pypi.org · read 7 Oct 2026
- Purpose
- pytest-gremlins is a pytest plugin that injects small code mutations and checks whether tests catch them.pytest-gremlins.readthedocs.io · read 7 Oct 2026
- pytest integration
- The plugin works with existing pytest test suites and pytest-xdist, including `-n auto`.pytest-gremlins.readthedocs.io · read 7 Oct 2026
- Python requirement
- The package requires Python 3.11 or later.pypi.org · read 7 Oct 2026
- Reports
- It supports console, HTML, and JSON reports, including multiple report formats in one run.pytest-gremlins.readthedocs.io · read 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.pytest-gremlins.readthedocs.io · read 7 Oct 2026
