mini-mutest

It is a simple demo code written in cuhksz csc4001 software engineering course.

mini-mutest is a lightweight mutation testing tool for small Python projects. It mutates a target source file, reruns a pytest target for each mutant, and generates a Markdown report that highlights killed and survived mutants.

This repository is designed as a compact software engineering project: small enough to understand quickly, but complete enough to publish directly on GitHub and use for demos, coursework, or experimentation.

Features

• AST-based mutation generation for common arithmetic, comparison, and boolean mutations
• Simple CLI for listing mutants and running mutation testing
• Markdown report generation with summary metrics and survived-mutant details
• Optional export of survived mutant files for inspection
• Configurable mutation score threshold for CI
• Example project and tests included

Project Structure

mini-mutest/
├── mini_mutest/              # package source
├── examples/                 # sample target module
├── tests/                    # tests for examples and the tool itself
├── reports/                  # generated mutation reports
└── .github/workflows/ci.yml  # GitHub Actions CI

Installation

python -m pip install -e .

After installation, you can use either:

mini-mutest --help
python -m mini_mutest --help

Quick Start

List available mutation candidates:

mini-mutest list examples/calculator.py

Run mutation testing against the example project:

mini-mutest run examples/calculator.py --tests tests/test_calculator.py

Run against a test directory, fail the command if the mutation score is too low, and save survived mutants:

mini-mutest run examples/calculator.py \
  --tests tests \
  --fail-under 80 \
  --save-survivors reports/survived

The default report path is reports/mutation_report.md.

Example Output

The bundled example is intentionally small and demonstrates a useful mutation-testing pattern:

• arithmetic mutations are usually killed by direct functional tests
• boundary-related mutations need dedicated edge-case tests
• some survived mutants may be equivalent mutants and not practically killable

Mutation Operators

Currently supported mutation operators include:

• + -> -
• - -> +
• * -> /
• / -> *
• == -> !=
• != -> ==
• > -> >=
• >= -> >
• < -> <=
• <= -> <
• True -> False
• False -> True

Development

Run the test suite:

pytest

Run the example mutation test locally:

python -m mini_mutest run examples/calculator.py --tests tests/test_calculator.py --fail-under 80

GitHub Actions

The repository includes a CI workflow that:

• tests the project on Python 3.10, 3.11, and 3.12
• installs the package in editable mode
• runs the full pytest suite
• performs a CLI smoke test

Limitations

• The tool mutates one Python file at a time.
• The current mutation operator set is intentionally small.
• Equivalent mutant detection is not implemented.
• Test execution is performed by rewriting the target file in place, so parallel runs on the same target are not supported.

Future Improvements

• support more mutation operators
• add JSON or SARIF report output
• support excluding lines or operators
• detect equivalent mutants more intelligently
• improve isolation with temporary workspaces

License

MIT