Skip to the content
Know your tech before you buy it. Makers: get listed from $49/mo

pytest-gremlins

github.com

  • Free plan
  • Linux
7.2 Club score Visit github.com

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.

pytest-gremlins

Free

Open source

Getting started

  1. Install Python 3.11 or later and pytest 7.0 or later
  2. Ensure the project has an existing pytest test suite
  3. Install with `pip install pytest-gremlins`, or use uv or Poetry
  4. Run `pytest --gremlins`
  5. Optionally configure settings in `pyproject.toml` or command-line flags
  6. 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.