pytestmut 0.1.0

Find the bugs your tests would miss.

Documentation · Getting started · Coding agents · CI/CD · Configuration

pytestmut makes small, deliberate mistakes in your code, one at a time, and runs your pytest suite against each of them. If a test fails, the mistake was caught. If every test still passes, you have found a place where a real bug could hide, and pytestmut tells you which test would catch it.

Line coverage tells you which code your tests run. Mutation testing tells you which code your tests check.

$ pytestmut run
pytestmut 0.1.0: 15 mutants in 2 file(s), 3 tests, 12 worker(s), 2.3s

  killed            8
  survived          5
  no coverage       2

  score           53.3%  (8 detected of 15 scored: 5 survived, 2 without coverage)

Survivors (5)
  src/shop/pricing.py:8  cmp.boundary  [7bf19b971895]  in discount
      - if amount > 100 and loyal:
      + if amount >= 100 and loyal:
      Changing `>` -> `>=` at src/shop/pricing.py:8 in `discount` went unnoticed. Tests
      that ran this code and still passed: tests/test_pricing.py::test_discount. No test
      sits on the boundary of `>`. Add a case where both sides are equal and assert the
      result; ...

Highlights

Quick start

uv add --dev pytestmut             # or: pip install pytestmut
pytestmut init --write             # add a starter [tool.pytestmut] to pyproject.toml
pytestmut run                      # mutate, test, report
pytestmut show 7bf19b97            # one mutant, and what test would catch it

# pyproject.toml
[tool.pytestmut]
paths = ["src/mypackage"]

[tool.pytestmut.thresholds]
min_score = 80.0

The getting started guide takes an example project from its first run to every mutant caught.

What you can do with it

Reference: command line · configuration · mutation operators · how it works · troubleshooting

Why the numbers can be trusted

• Every kill is real. Verdicts come from a per-test record written inside pytest, not from exit codes. A must-die mutant proves the pipeline before any real one runs.
• Mutations never touch disk. They are applied in memory at import time, inside subprocesses too, so a crash can't leave mutated code behind.
• Ambiguity is resolved, not guessed. Timeouts are confirmed alone and against an unmutated run. Kills by order-dependent tests are checked. Survivors are re-checked against the whole suite.
• pytestmut tests itself. Its own verdict and policy logic is held to 100% with zero survivors, and the report is published with the docs.

Status

Alpha. Requires Python 3.10+ and pytest 8+. CI runs the full test suite on Linux, macOS and Windows with Python 3.10 to 3.14.

Development

uv sync
uv run nox                        # format, imports, licenses, lint, types, tests
uv run nox -s "Mutation Tests"    # pytestmut on its own core modules
uv run nox -s "Serve Docs"        # the docs, with fresh mutation and license reports

Releasing: bump __version__ in pytestmut/_meta.py and merge to main. Once CI passes, the release workflow builds and checks the package, publishes it to TestPyPI, verifies what TestPyPI serves, then publishes it to PyPI and tags a GitHub release. Pushes that keep the version publish nothing.

License

MIT