Mutmut

3.5.0 · active · verified Mon Apr 13

Mutmut is a mutation testing system for Python, currently at version 3.5.0. It helps identify weaknesses in test suites by making small, automated changes (mutations) to your code and running your tests against them. If tests still pass after a mutation, it indicates a potential gap in the test coverage. It primarily operates as a command-line tool with a focus on ease of use and incremental workflow.

Warnings

gotcha Mutmut requires a system with `fork` support. On Windows, it must be run inside WSL (Windows Subsystem for Linux).
Fix: Use WSL for running Mutmut on Windows environments.
breaking Mutmut 3+ has a different execution model compared to Mutmut 2. If you need to mutate code outside of functions (e.g., global scope code), you might need to use Mutmut 2.
Fix: For mutating global scope code, consider using Mutmut 2.x, or restructure your code to be within functions if possible for Mutmut 3.x. Check the official documentation for compatibility.
gotcha When using `mutmut apply <mutant_id>` to write a mutant to disk, *always* ensure your code is under source control and committed before applying, as this modifies your source files.
Fix: Commit your changes before running `mutmut apply` to easily revert if the applied mutation breaks something or is not desired.
gotcha Mutmut may have issues mutating enums, staticmethods, and classmethods in a type-safe way when filtering with type checkers like MyPy or PyreFly. These might be skipped or lead to invalid mutants.
Fix: Be aware that these specific constructs might not be fully covered by mutation testing when type checker filtering is enabled. You may need to manually inspect them or adjust filtering if you suspect gaps.
gotcha Mutmut may not automatically detect your project's source or test directories. It often defaults to 'tests' or 'test' folders and attempts to figure out code to mutate. For complex layouts, explicit configuration is needed.
Fix: Configure `paths_to_mutate` and `tests_dir` in a `setup.cfg` file to explicitly tell Mutmut where your source code and tests are located.

Install

pip install mutmut Install Mutmut

Imports

mutmut CLI
```
mutmut run
```
Mutmut is primarily a command-line interface tool and does not expose a typical public Python API for direct programmatic import and use by end-users. Interaction is via shell commands.

Quickstart

After installation, navigate to your project root. Run `mutmut run` to execute mutation tests. You can then use `mutmut browse` for an interactive review of mutants, `mutmut results` for a summary, or `mutmut show <id>` to inspect a specific mutation. Configuration can be done in `setup.cfg`.

# 1. Install mutmut
# pip install mutmut

# 2. Navigate to your project directory
# cd your_project

# 3. (Optional) Configure mutmut via setup.cfg for specific paths or test runners
# [mutmut]
# paths_to_mutate=src/
# runner=python -m unittest discover tests "*_test.py"
# tests_dir=tests/

# 4. Run mutation tests
print('Running mutmut run (simulated)')
# mutmut run

# 5. Browse results (interactive UI)
print('Running mutmut browse (simulated)')
# mutmut browse

# 6. View a non-interactive summary of results
print('Running mutmut results (simulated)')
# mutmut results

# 7. Show a specific mutation (e.g., mutant ID 4)
print('Running mutmut show 4 (simulated)')
# mutmut show 4

view raw JSON →