mutate4py 0.1.0

Mutation testing for Python with an embedded-in-source manifest

mutate4py

Mutation testing for Python. Discovers mutation sites, applies each one, runs your tests, and reports killed, survived, and uncovered mutations — with an embedded-in-source manifest so differential reruns survive a clone with zero CI setup.

A faithful Python port of unclebob/mutate4go, with the user-facing contract cross-checked against unclebob/clj-mutate. Where Python forces a divergence (coverage acquisition, the manifest hash) it is marked [PY] and justified in docs/spec.md.

Install

uvx mutate4py        # run without installing
uv tool install mutate4py

Usage

mutate4py path/to/file.py --test-command "pytest" --lcov lcov.info

Generate lcov.info with coverage.py:

pytest --cov --cov-branch --cov-report=lcov:lcov.info

See mutate4py --help and the spec for the full flag set.

How it differs from mutate4go ([PY])

• --max-workers uses clone-per-worker, not tree-copy+cwd — mutate4go's tree-copy model is unsound under Python editable installs (pip install -e .), so each worker gets its own uv-provisioned venv instead.
• Coverage is acquired explicitly — --lcov / --cov-cmd / --reuse-coverage (Python has no universal -coverprofile equivalent).
• Manifest hash is structural (ast.dump()), so reformatting and comment edits don't trigger a re-test, but any behavior-affecting edit does.
• Operators are localized to Python: adds and/or, True/False, and the identity/membership negation flips is/is not and in/not in.

Develop

Python ≥ 3.10, stdlib ast (zero runtime deps), packaged with hatchling.

uv sync
uv run mutate4py --help
uv run pytest