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_resultsRequired. Either the path to a mutation results JSON file or an already decoded hashref with the same shape. The file must contain a
survivedarrayref whose entries haveid,fileandlinekeys; entries with astatusother thanSurvivedare ignored.moduleOptional module name, e.g.
My::Module. When given, only survivors whosefilenames 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_rootOptional directory used to resolve the relative
filepaths 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-constraintfor a numeric comparison that yields an automatic schema constraint, ormanualwhen 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 forconstraintproposals.values- the boundary values a test should exercise, one either side of the literal. Only present forconstraintproposals.constraint- a hashref such as{ min => 11 }, suitable for merging into a schema input field. Only present forconstraintproposals.hint- human-readable advice formanualproposals.
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
$schemaA schema hashref as loaded from YAML. Its
inputsection 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.