pytest-gremlins
github.com
- Free plan
- Linux
What pytest-gremlins is
pytest-gremlins is a pytest plugin for checking whether an existing test suite catches small code mutations. It is aimed at Python projects and requires Python 3.11 or later, pytest 7.0 or later, and existing tests. The documented quick start is `pip install pytest-gremlins` followed by `pytest --gremlins`; installation is also available through uv and Poetry. To manage the workload, it uses mutation switching, coverage-guided test selection, incremental analysis, and parallel execution, and it supports pytest-xdist, including `-n auto`. Results can be reported in the console, HTML, or JSON, with multiple formats in one run. Set options in `pyproject.toml` or on the command line, and use an inline pragma to pardon a mutation. A GitHub Action can run mutation tests and fail a workflow below a score threshold; CI examples also cover GitLab CI, CircleCI, and Dagger. The first run may take 10–100 times as long as a normal test run, though caching can speed later runs. The project recommends focusing on business logic, security-critical code, and financial calculations. It is a free, MIT-licensed package classified as Alpha.
Who it suits
It suits Python teams with existing pytest suites that want to assess tests for business logic, security-critical code, or financial calculations. Teams should be prepared for a potentially much longer initial run.
Good to know, and what to watch
- Works with pytest and pytest-xdist.
- Offers incremental analysis and parallel execution.
- Provides console, HTML, and JSON reports.
- GitHub Action can enforce a score threshold.
- Free, MIT-licensed package.
- Requires Python 3.11 or later.
- Requires pytest 7.0 or later and existing tests.
- Initial run may take 10–100 times as long.
- Package metadata classifies development status as Alpha.
Plans
Every plan and pricepytest-gremlins
Open source
Getting started
- Install Python 3.11 or later and pytest 7.0 or later
- Ensure the project has an existing pytest test suite
- Install with `pip install pytest-gremlins`, or use uv or Poetry
- Run `pytest --gremlins`
- Optionally configure settings in `pyproject.toml` or command-line flags
- Add the GitHub Action or documented CI workflow if needed
Limits to check
A first mutation-testing run may take 10–100 times as long as a normal test run, although caching can speed later runs. Equivalent mutations can make a 100% mutation score impossible or not worthwhile.
The verdict
pytest-gremlins adds mutation testing to existing pytest projects, with several ways to manage runs and inspect results. Its Python and pytest requirements, Alpha status, and potentially long first run are worth weighing before adding it to a workflow.
Questions people ask
What does pytest-gremlins cost?
It is free and open source under the MIT license.
Which language and test framework does it support?
The package targets Python projects using pytest.
What versions are required?
The project requires Python 3.11 or later, pytest 7.0 or later and an existing test suite.
Can it run in CI?
Its GitHub Action runs mutation tests and can fail a workflow below a score threshold. Guidance also covers GitHub Actions, GitLab CI, CircleCI and Dagger.
Which report formats are available?
Reports can be written to the console, HTML and JSON, including multiple formats in one run.
Can individual mutations be ignored?
Yes. Inline pragmas such as `# gremlin: pardon[reason]` can suppress equivalent or untestable mutations.
What the maker publishes
- Audience
- The guide recommends focusing mutation testing on business logic, security-critical code, and financial calculations. source
- Audience
- The package metadata lists developers as its intended audience. source
- CI integrations
- The GitHub Action documentation points to manual CI workflow examples for GitHub Actions, GitLab CI, CircleCI, and Dagger. source
- CI options
- The CI integration guide covers GitHub Actions, GitLab CI, CircleCI, and Dagger. source
- Configuration
- Options can be configured through `pyproject.toml` or command-line flags, and mutations can be pardoned with an inline pragma. source
- Development status
- The package metadata classifies its development status as Alpha. source
- 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. source
- Installation
- The project documents installation with pip, uv, and Poetry. source
- Installation requirements
- The getting started guide requires Python 3.11 or later, pytest 7.0 or later, and a project with existing tests. source
- Integrations
- The documentation describes compatibility with pytest-xdist and a GitHub Action for running mutation tests and enforcing a score threshold. source
- License
- The project is MIT licensed. source
- Limits
- The guide says equivalent mutations can make a 100% mutation score impossible and not worth pursuing. source
- Mutation control
- Users can suppress equivalent or untestable mutations inline with `# gremlin: pardon[reason]`. source
- Publishing provenance
- PyPI reports that the October 6, 2026 release was uploaded using Trusted Publishing and has a verified attestation signed by GitHub Actions. source
- Purpose
- pytest-gremlins is a pytest plugin that injects small code mutations and checks whether tests catch them. source
- pytest integration
- The plugin works with existing pytest test suites and pytest-xdist, including `-n auto`. source
- Python requirement
- The package requires Python 3.11 or later. source
- Reports
- It supports console, HTML, and JSON reports, including multiple report formats in one run. source
- 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. source
- Security and license
- The repository identifies the project as MIT-licensed; the license text provides the software “AS IS” without warranty. source
- Setup
- The project says mutation testing can be started with `pip install pytest-gremlins` and `pytest --gremlins`. source
- Speed
- Its speed features include mutation switching, coverage-guided test selection, incremental analysis, and parallel execution. source
- Speed features
- It uses mutation switching, coverage-guided test selection, incremental analysis, and parallel execution. source
Checked against the maker's pages on 7 Oct 2026.