Mutare.Score (mutare v0.4.1)

The mutation score and the CI gates computed over a run's results.

The score is killed / (total − no_coverage − ignored − poisoned − harness_error): a timeout or an atom-table exhaustion counts as a kill, and a mutant that reached no verdict is left out of the denominator. Mutare.Result classifies each status (kill?/1, scored?/1, ran?/1); this module only counts.

The gates (gate_failures/2, harness_errors_exceed?/2) are policy over the same tallies: :no_coverage, :poisoned, and :harness_error stay out of the score, but a CI run can still fail on them. Rendering the tallies as text is Mutare.Report's job.

Summary

Functions

gate_failures(results, opts \\ [])

Human-readable failures for complete-run CI gates.

harness_error_rate(results)

Fraction of launched mutant runs that ended in :harness_error.

harness_errors_exceed?(results, max_rate)

Returns whether harness_error_rate/1 exceeds max_rate.

passes_gate?(results, min_score)

Returns whether results meet a minimum score percentage.

percent(value)

Format a percentage value (already on a 0..100 scale) to one decimal place, without a trailing %.

score(results)

Mutation score as a percentage: killed / (total − no_coverage − ignored − poisoned − harness_error). Returns 100.0 when the denominator is zero (nothing to test).

Functions

gate_failures(results, opts \\ [])

@spec gate_failures([Mutare.Result.t()], keyword() | map()) :: [String.t()]

Human-readable failures for complete-run CI gates.

These gates are separate from score semantics: :no_coverage, :poisoned, and :harness_error stay out of the mutation-score denominator, but a caller can still make them fatal for CI. opts may be a keyword list or an options map carrying:

:min_score — minimum mutation score percentage, or nil
:max_no_coverage — maximum allowed :no_coverage count, or nil
:fail_on_poisoned — fail if any mutant is :poisoned
:fail_on_harness_error — fail if any mutant is :harness_error

harness_error_rate(results)

@spec harness_error_rate([Mutare.Result.t()]) :: float()

Fraction of launched mutant runs that ended in :harness_error.

The denominator includes :killed, :survived, :timeout, :atom_exhausted, and :harness_error. It excludes :no_coverage, :ignored, and :poisoned, which never launch a test run. Returns 0.0 when nothing ran.

iex> results = [
...>   %Mutare.Result{status: :killed},
...>   %Mutare.Result{status: :harness_error},
...>   %Mutare.Result{status: :no_coverage}
...> ]
iex> Mutare.Score.harness_error_rate(results)
0.5

harness_errors_exceed?(results, max_rate)

@spec harness_errors_exceed?([Mutare.Result.t()], number() | nil) :: boolean()

Returns whether harness_error_rate/1 exceeds max_rate.

max_rate is a fraction from 0.0 to 1.0. A nil value disables the check and returns false.

passes_gate?(results, min_score)

@spec passes_gate?([Mutare.Result.t()], number() | nil) :: boolean()

Returns whether results meet a minimum score percentage.

A nil minimum always passes.

iex> results = [%Mutare.Result{status: :killed}, %Mutare.Result{status: :survived}]
iex> Mutare.Score.passes_gate?(results, 60)
false
iex> Mutare.Score.passes_gate?(results, nil)
true

percent(value)

@spec percent(number()) :: String.t()

Format a percentage value (already on a 0..100 scale) to one decimal place, without a trailing %.

iex> Mutare.Score.percent(2 / 3 * 100)
"66.7"

score(results)

@spec score([Mutare.Result.t()]) :: float()

Mutation score as a percentage: killed / (total − no_coverage − ignored − poisoned − harness_error). Returns 100.0 when the denominator is zero (nothing to test).

iex> results = [
...>   %Mutare.Result{status: :killed},
...>   %Mutare.Result{status: :survived},
...>   %Mutare.Result{status: :no_coverage}
...> ]
iex> Mutare.Score.score(results)
50.0