API Reference

This section documents the complete public API of pytest-gremlins, a fast-first mutation testing plugin for pytest.

Architecture Overview

pytest-gremlins achieves speed through four architectural pillars:

Pillar	Module	Description
Mutation Switching	instrumentation	Instrument code once, toggle mutations via environment variable
Coverage-Guided Selection	coverage	Run only tests that cover the mutated code
Incremental Analysis	cache	Skip unchanged code/tests on subsequent runs
Parallel Execution	parallel	Distribute gremlins across worker processes

Module Map

Text Only

pytest_gremlins/
├── __init__.py           # Package info, version
├── config.py             # Configuration loading
├── plugin.py             # pytest plugin hooks
│
├── operators/            # Mutation operators
│   ├── protocol.py       # GremlinOperator protocol
│   ├── registry.py       # Operator registration
│   ├── arithmetic.py     # +, -, *, / mutations
│   ├── boolean.py        # and/or, True/False mutations
│   ├── boundary.py       # Off-by-one mutations
│   ├── comparison.py     # <, <=, >, >= mutations
│   └── return_value.py   # Return statement mutations
│
├── instrumentation/      # AST transformation
│   ├── gremlin.py        # Gremlin dataclass
│   ├── transformer.py    # AST transformer
│   ├── switcher.py       # Environment-based switching
│   ├── finder.py         # Mutation point finder
│   ├── import_hooks.py   # Import interception
│   └── pragma.py         # Pardon pragma parsing
│
├── coverage/             # Coverage-guided selection
│   ├── mapper.py         # Line-to-test mapping
│   ├── collector.py      # Coverage data collection
│   ├── context_plugin.py # Coverage.py dynamic context plugin
│   ├── selector.py       # Test selection
│   ├── prioritized_selector.py  # Prioritized selection
│   └── types.py          # Coverage type definitions
│
├── cache/                # Incremental analysis
│   ├── hasher.py         # Content hashing
│   ├── store.py          # SQLite result cache
│   ├── incremental.py    # Cache coordinator
│   └── types.py          # Cache type definitions
│
├── parallel/             # Parallel execution
│   ├── pool.py           # Worker pool
│   ├── pool_config.py    # Pool configuration
│   ├── persistent_pool.py # Persistent workers
│   ├── batch_executor.py # Batch execution
│   ├── distribution.py   # Work distribution
│   └── aggregator.py     # Result aggregation
│
└── reporting/            # Result reporting
    ├── results.py        # GremlinResult dataclass
    ├── score.py          # MutationScore aggregation
    ├── console.py        # Terminal output
    ├── html.py           # HTML reports
    ├── json_reporter.py  # JSON reports
    ├── diff.py           # Source diff generation
    ├── history.py        # Run history tracking
    ├── sonarqube_export.py  # SonarQube export
    ├── stryker_export.py    # Stryker Dashboard export
    └── types.py          # Reporting type definitions

Quick Navigation

Core Plugin

• Plugin Module - pytest hooks and session management
• Configuration - Loading config from pyproject.toml

Mutation Operators

• Operators Module - All mutation operators
• GremlinOperator Protocol
• OperatorRegistry
• Built-in Operators

Instrumentation

• Instrumentation Module - AST transformation and switching
• Gremlin Dataclass
• Source Transformation
• Import Hooks

Coverage

• Coverage Module - Coverage-guided test selection
• CoverageMap
• TestSelector
• PrioritizedSelector

Cache

• Cache Module - Incremental analysis caching
• ContentHasher
• ResultStore
• IncrementalCache

Parallel Execution

• Parallel Module - Worker pools and distribution
• WorkerPool
• PersistentWorkerPool
• BatchExecutor

Reporting

• Reporting Module - Result presentation
• GremlinResult
• MutationScore
• Reporters

Domain Language

pytest-gremlins uses a playful "gremlins" theme throughout its API:

Traditional Term	Gremlin Term	Description
Original code	Mogwai	The innocent, unmutated code
Mutant	Gremlin	A mutation injected into code
Kill mutant	Zap	Test catches the mutation
Surviving mutant	Survivor	Test gap found
Start mutation testing	Feed after midnight	Enable with --gremlins

Quick Start Example

Python

# Run mutation testing from command line
# pytest --gremlins

# Programmatic access to operators
from pytest_gremlins.operators import OperatorRegistry, ComparisonOperator

registry = OperatorRegistry()
registry.register(ComparisonOperator)

# Transform source code
from pytest_gremlins.instrumentation import transform_source

source = '''
def is_adult(age):
    return age >= 18
'''
gremlins, tree = transform_source(source, 'example.py')
print(f'Found {len(gremlins)} gremlins')

# Work with results
from pytest_gremlins.reporting import MutationScore, GremlinResultStatus

# score = MutationScore.from_results(results)
# print(f'Mutation score: {score.percentage:.1f}%')

Package Info

pytest_gremlins

pytest-gremlins: Fast-first mutation testing for pytest.

Let the gremlins loose. See which ones survive.

pytest-gremlins is a mutation testing plugin that helps you evaluate the quality of your test suite by injecting small changes (gremlins) into your code and checking if your tests catch them.

Example

Run mutation testing on your project::

Text Only

$ pytest --gremlins

Run with specific operators only::

Text Only

$ pytest --gremlins --gremlin-operators=comparison,boolean

Generate an HTML report::

Text Only

$ pytest --gremlins --gremlin-report=html

For more information, see https://pytest-gremlins.readthedocs.io

__version__ module-attribute

Python

__version__ = '1.8.1'