File: lib/App/Test/Generator/Mutator.pm

lib/App/Test/Generator/Mutator.pm

Structural Coverage (Approximate)

TER1 (Statement): 100.00%
TER2 (Branch): 90.38%
TER3 (LCSAJ): 100.0% (4/4)
Approximate LCSAJ segments: 53

LCSAJ Legend

● Covered — this LCSAJ path was executed during testing.

● Not covered — this LCSAJ path was never executed. These are the paths to focus on.

Multiple dots on a line indicate that multiple control-flow paths begin at that line. Hovering over any dot shows:

        start → end → jump

start – first line of the linear sequence
end – last line before control flow changes
jump – line execution jumps to next

Uncovered paths show [NOT COVERED] in the tooltip.

Mutant Testing Legend

Survived (tests missed this) Killed (tests detected this) No mutation

1: package App::Test::Generator::Mutator; 2: 3: use 5.036; 4: use autodie qw(:io); # covers open/close/read/write; excludes system (which legitimately fails) 5: use Carp qw(croak); 6: use Config; 7: use File::Copy::Recursive qw(dircopy); 8: use File::Spec; 9: use File::Temp qw(tempdir); 10: use PPI; 11: use Readonly; 12: 13: use App::Test::Generator::Mutation::BooleanNegation; 14: use App::Test::Generator::Mutation::ConditionalInversion; 15: use App::Test::Generator::Mutation::NumericBoundary; 16: use App::Test::Generator::Mutation::ReturnUndef; 17: 18: # -------------------------------------------------- 19: # Valid mutation level values 20: # -------------------------------------------------- 21: Readonly my $LEVEL_FULL => 'full'; 22: Readonly my $LEVEL_FAST => 'fast'; 23: 24: # -------------------------------------------------- 25: # Default values for optional constructor arguments 26: # -------------------------------------------------- 27: Readonly my $DEFAULT_LIB_DIR => 'lib'; 28: Readonly my $DEFAULT_MUTATION_LEVEL => $LEVEL_FULL; 29: 30: # -------------------------------------------------- 31: # Error message constants â€” named so test code can 32: # match against them without duplicating the literal 33: # -------------------------------------------------- 34: Readonly my $ERR_FILE_REQUIRED => 'file required'; 35: Readonly my $ERR_WORKSPACE_NOT_SET => 'Workspace not prepared -- call prepare_workspace first'; 36: Readonly my $ERR_RELATIVE_NOT_SET => 'Relative path not set -- call prepare_workspace first'; 37: 38: our $VERSION = '0.46'; 39: 40: =head1 NAME 41: 42: App::Test::Generator::Mutator - Generate and apply mutation tests 43: 44: =head1 VERSION 45: 46: Version 0.46 47: 48: =head1 SYNOPSIS 49: 50: use App::Test::Generator::Mutator; 51: 52: my $mutator = App::Test::Generator::Mutator->new( 53: file => 'lib/My/Module.pm', 54: lib_dir => 'lib', 55: mutation_level => 'fast', 56: ); 57: 58: my $mutants = $mutator->generate_mutants(); 59: printf "Generated %d mutants\n", scalar @{$mutants}; 60: 61: my $workspace = $mutator->prepare_workspace(); 62: 63: for my $m (@{$mutants}) { 64: $mutator->apply_mutant($m); 65: if($mutator->run_tests()) { 66: print "SURVIVED: ${\$m->description}\n"; 67: } else { 68: print "KILLED: ${\$m->description}\n"; 69: } 70: } 71: 72: =head1 DESCRIPTION 73: 74: B<App::Test::Generator::Mutator> is a mutation engine that programmatically 75: alters Perl source files to evaluate the effectiveness of a project's test 76: suite. It analyses modules, generates systematic code mutations (such as 77: conditional inversions, logical operator changes, and numeric boundary 78: flips), and applies them within an isolated workspace so tests can be 79: executed safely against each modified variant. 80: 81: By tracking which mutants are killed (cause tests to fail) versus those that 82: survive (tests still pass), the module enables calculation of a mutation 83: score, providing a quantitative measure of how well the test suite detects 84: unintended behavioural changes. 85: 86: =head2 new 87: 88: Construct a new Mutator for a given source file. 89: 90: my $mutator = App::Test::Generator::Mutator->new( 91: file => 'lib/My/Module.pm', 92: lib_dir => 'lib', 93: mutation_level => 'full', 94: ); 95: 96: =head3 Arguments 97: 98: =over 4 99: 100: =item * C<file> 101: 102: Path to the Perl source file to mutate. Required. Must exist on disk. 103: 104: =item * C<lib_dir> 105: 106: Root library directory. Optional - defaults to C<lib>. 107: 108: =item * C<mutation_level> 109: 110: Controls the breadth of mutation. C<full> applies all mutations; 111: C<fast> deduplicates and removes redundant mutants first. 112: Optional - defaults to C<full>. 113: 114: =back 115: 116: =head3 Returns 117: 118: A blessed hashref. Croaks if C<file> is missing or does not exist. 119: 120: =head3 API specification 121: 122: =head4 input 123: 124: { 125: file => { type => SCALAR }, 126: lib_dir => { type => SCALAR, optional => 1 }, 127: mutation_level => { type => SCALAR, optional => 1 }, 128: } 129: 130: =head4 output 131: 132: { 133: type => OBJECT, 134: isa => 'App::Test::Generator::Mutator', 135: } 136: 137: =head3 EXAMPLE 138: 139: my $m = App::Test::Generator::Mutator->new( 140: file => 'lib/Acme/Widget.pm', 141: mutation_level => 'fast', 142: ); 143: 144: =head3 MESSAGES 145: 146: =over 4 147: 148: =item C<file required> 149: 150: C<file> was not supplied. 151: 152: =item C<< file not found: PATH >> 153: 154: C<file> was supplied but does not exist on disk. 155: 156: =back 157: 158: =head3 FORMAL SPECIFICATION 159: 160: Pre: C<file> is defined âˆ§ C<-f file> 161: 162: Post: C<ref(result) eq 'App::Test::Generator::Mutator'> 163: âˆ§ C<result-E<gt>{file} eq file> 164: âˆ§ C<result-E<gt>{mutation_level} âˆˆ {full, fast}> 165: 166: =cut 167: 168: sub new { 169: my ($class, %args) = @_; 170: 171: # file is required and must exist on disk 172: croak $ERR_FILE_REQUIRED unless defined $args{file}; 173: croak "file not found: $args{file}" unless -f $args{file}; 174: