NAME

App::Test::Generator::Mutation::Feedback - Turn surviving mutants into boundary cases and schema constraints

VERSION

Version 0.49

SYNOPSIS

use App::Test::Generator::Mutation::Feedback;

my $feedback = App::Test::Generator::Mutation::Feedback->new(
    mutation_results => 'mutation.json',
    module           => 'My::Module',
);

my $applied = $feedback->apply_to_schema($schema);
printf "added %s = %s to %s\n",
    $_->{constraint}, $_->{value}, $_->{field} for @{$applied};

DESCRIPTION

A mutation survivor is a mutant the test suite did not notice. Until now a survivor was only counted and printed; this module reads the survivors from the JSON written by test-generator-mutate --json and proposes concrete inputs that would have killed them.

For a surviving numeric-boundary mutant the source line is read back and the comparison it mutated is recovered, for example $count > 10. That comparison is then translated into a schema constraint:

source comparison     proposed constraint
$x >  N               min => N + 1
$x >= N               min => N
$x <  N               max => N - 1
$x <= N               max => N

Integer literals only. The constraint makes App::Test::Generator::Template generate values on both sides of the boundary, which is what the survivor showed was missing.

Constraints are only applied to a field of the schema's input section whose name matches the variable in the source comparison, after normalising case and punctuation. An existing constraint is never replaced: a bound the POD or the code already declares wins over a proposed one.

Survivors that do not describe a numeric comparison - conditional inversions, boolean negations and so on - produce a manual proposal instead of an automatic change, because no single data value is known to distinguish them. They are still returned by "proposals" so a reviewer can see what survived.

Only survivors belonging to module's own file are used when module is given, so a mutation run over a whole lib directory feeds only the matching module's schema.

new

Construct a feedback object.

my $feedback = App::Test::Generator::Mutation::Feedback->new(
    mutation_results => 'mutation.json',
    module           => 'My::Module',
    source_root      => '.',
);

Arguments

  • mutation_results

    Required. Either the path to a mutation results JSON file or an already decoded hashref with the same shape. The file must contain a survived arrayref whose entries have id, file and line keys; entries with a status other than Survived are ignored.

  • module

    Optional module name, e.g. My::Module. When given, only survivors whose file names that module's file (My/Module.pm) are proposed, so results from a whole-directory mutation run can be fed to one schema safely.

  • source_root

    Optional directory used to resolve the relative file paths in the results. Defaults to the current directory.

Returns

A blessed hashref. Croaks when mutation_results is missing, unreadable or not valid JSON, and when no module file can be matched but module is set.

API SPECIFICATION

input

{
    mutation_results => { type => 'any' },
    module           => { type => 'string', optional => 1 },
    source_root      => { type => 'string', optional => 1 },
}

mutation_results is a file name or a hashref, so no single type is declared for it.

output

{ type => OBJECT, isa => 'App::Test::Generator::Mutation::Feedback' }

survivors

Return the survivors from the results, filtered to the configured module.

my $survivors = $feedback->survivors;

Returns

An arrayref of survivor hashrefs, in the order they appear in the results.

API SPECIFICATION

input

{ self => { type => OBJECT, isa => 'App::Test::Generator::Mutation::Feedback' } }

output

{ type => ARRAYREF, items => { type => HASHREF } }

proposals

Return one proposal per survivor.

my $proposals = $feedback->proposals;

Returns

An arrayref of hashrefs with these keys:

  • kind - constraint for a numeric comparison that yields an automatic schema constraint, or manual when a test has to be written by hand.

  • survivor_id, file, line, description - copied from the survivor, so the proposal can be traced back to the mutation report.

  • parameter - the input field the source comparison constrains, derived from the variable in the comparison. Only present for constraint proposals.

  • values - the boundary values a test should exercise, one either side of the literal. Only present for constraint proposals.

  • constraint - a hashref such as { min => 11 }, suitable for merging into a schema input field. Only present for constraint proposals.

  • hint - human-readable advice for manual proposals.

API SPECIFICATION

input

{ self => { type => OBJECT, isa => 'App::Test::Generator::Mutation::Feedback' } }

output

{ type => ARRAYREF, items => { type => HASHREF } }

apply_to_schema

Merge constraint proposals into a schema.

my $applied = $feedback->apply_to_schema($schema);

Arguments

  • $schema

    A schema hashref as loaded from YAML. Its input section is modified in place.

Returns

An arrayref of change hashrefs, one per constraint added, each with field, constraint, value, survivor_id, file and line. An empty arrayref means nothing could be applied; the proposals are still available for reporting.

Constraints already present on the field are left alone, as are proposals whose parameter has no matching input field.

API SPECIFICATION

input

{
    self   => { type => OBJECT, isa => 'App::Test::Generator::Mutation::Feedback' },
    schema => { type => HASHREF },
}

output

{ type => ARRAYREF, items => { type => HASHREF } }

AUTHOR

Nigel Horne, <njh at nigelhorne.com>

LICENCE AND COPYRIGHT

Copyright 2026 Nigel Horne.

Usage is subject to the terms of GPL2. If you use it, please let me know.