mutation

Documentation

Overview

Package mutation orchestrates mutation testing across a diff's changed files. The AST-level work (generating mutants, applying them, scanning annotations, running tests) is provided by the language back-end via lang.MutantGenerator / lang.MutantApplier / lang.AnnotationScanner / lang.TestRunner. This package owns the scheduling, tiering, and report formatting — pieces that don't depend on any particular language.

Index

• func Analyze(repoPath string, d *diff.Result, l lang.Language, opts Options) (report.Section, error)
• type Mutant
• type Options
• type Tier
  • func (t Tier) String() string
• type TierStats

Functions

func Analyze

func Analyze(repoPath string, d *diff.Result, l lang.Language, opts Options) (report.Section, error)

Analyze applies mutation operators to changed code (via the language's MutantGenerator/Applier) and runs the language's TestRunner against each mutant.

Parallelism is controlled by Options.Workers; concurrency safety is the TestRunner's responsibility (Go's overlay-based runner is safe to call concurrently; temp-copy runners for other languages must serialize per-file internally).

Types

type Mutant

type Mutant struct {
	File        string
	Line        int
	Description string
	Operator    string
	Killed      bool
	TestOutput  string
}

Mutant represents a single mutation applied to the source code.

type Options

type Options struct {
	// SampleRate is the percentage (0-100) of generated mutants to actually test.
	SampleRate float64
	// TestTimeout is the per-mutant timeout.
	// Zero means use the default (30s).
	TestTimeout time.Duration
	// TestPattern, if non-empty, is passed to the language's test runner to
	// scope tests.
	TestPattern string
	// Tier1Threshold is the minimum killed-percentage for Tier 1 operators
	// below which the section is reported as FAIL. Zero falls back to
	// defaultTier1Threshold.
	Tier1Threshold float64
	// Tier2Threshold is the minimum killed-percentage for Tier 2 operators
	// below which the section is reported as WARN. Zero falls back to
	// defaultTier2Threshold.
	Tier2Threshold float64
	// Workers caps the number of mutants processed concurrently. Zero or
	// negative means use runtime.NumCPU().
	Workers int
}

Options configures a mutation testing run.

type Tier

type Tier int

Tier classifies mutation operators by how much signal a surviving mutant carries.

The raw "score" metric across all operators is misleading on Go codebases because observability-heavy code (log.*, metrics.*) generates many statement_deletion and branch_removal survivors that tests cannot observe by design. Tiering lets CI gate strictly on the operators that almost always indicate a real test gap, while reporting the noisier operators separately.

const (
	// TierLogic (1) covers operators where a surviving mutant almost always
	// indicates a real test gap: negated comparisons, flipped conditional
	// boundaries, zeroed return values, and arithmetic swaps.
	TierLogic Tier = 1

	// TierSemantic (2) covers operators that usually indicate a gap but
	// have legitimate equivalent-mutant cases (e.g. bool substitutions on
	// default values, inc/dec on cosmetic counters). Unknown operators
	// default here so a newly-added operator doesn't silently land in the
	// noise-prone observability tier.
	TierSemantic Tier = 2

	// TierObservability (3) covers operators dominated by untestable
	// side-effect removal (log/metric calls, log-only branches). Surfaced
	// for manual review but not meant to gate CI.
	TierObservability Tier = 3
)

func (Tier) String

func (t Tier) String() string

String returns a short human label for the tier.

type TierStats

type TierStats struct {
	Tier     Tier `json:"tier"`
	Total    int  `json:"total"`
	Killed   int  `json:"killed"`
	Survived int  `json:"survived"`
	// Score is killed / total * 100; 0 when total == 0.
	Score float64 `json:"score"`
}

TierStats aggregates mutant counts for a single tier.