lib/App/Test/Generator/Mutator.pm

Structural Coverage (Approximate)

TER1 (Statement): 95.70%
TER2 (Branch): 79.41%
TER3 (LCSAJ): 100.0% (11/11)
Approximate LCSAJ segments: 35

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 strict; 4: use warnings; 5: use Carp qw(croak); 6: use Config; 7: use File::Copy qw(copy); 8: use File::Copy::Recursive qw(dircopy); 9: use File::Spec; 10: use File::Temp qw(tempdir); 11: use PPI; 12: use Readonly; 13: 14: use App::Test::Generator::Mutation::BooleanNegation; 15: use App::Test::Generator::Mutation::ConditionalInversion; 16: use App::Test::Generator::Mutation::NumericBoundary; 17: use App::Test::Generator::Mutation::ReturnUndef; 18: 19: # -------------------------------------------------- 20: # Valid mutation level values 21: # -------------------------------------------------- 22: Readonly my $LEVEL_FULL => 'full'; 23: Readonly my $LEVEL_FAST => 'fast'; 24: 25: # -------------------------------------------------- 26: # Default values for optional constructor arguments 27: # -------------------------------------------------- 28: Readonly my $DEFAULT_LIB_DIR => 'lib'; 29: Readonly my $DEFAULT_MUTATION_LEVEL => $LEVEL_FULL; 30: 31: our $VERSION = '0.36'; 32: 33: =head1 NAME 34: 35: App::Test::Generator::Mutator - Generate and apply mutation tests 36: 37: =head1 VERSION 38: 39: Version 0.36 40: 41: =head1 DESCRIPTION 42: 43: B<App::Test::Generator::Mutator> is a mutation engine that programmatically 44: alters Perl source files to evaluate the effectiveness of a project's test 45: suite. It analyses modules, generates systematic code mutations (such as 46: conditional inversions, logical operator changes, and numeric boundary 47: flips), and applies them within an isolated workspace so tests can be 48: executed safely against each modified variant. 49: 50: By tracking which mutants are killed (cause tests to fail) versus those that 51: survive (tests still pass), the module enables calculation of a mutation 52: score, providing a quantitative measure of how well the test suite detects 53: unintended behavioural changes. 54: 55: =head2 new 56: 57: Construct a new Mutator for a given source file. 58: 59: my $mutator = App::Test::Generator::Mutator->new( 60: file => 'lib/My/Module.pm', 61: lib_dir => 'lib', 62: mutation_level => 'full', 63: ); 64: 65: =head3 Arguments 66: 67: =over 4 68: 69: =item * C<file> 70: 71: Path to the Perl source file to mutate. Required. Must exist on disk. 72: 73: =item * C<lib_dir> 74: 75: Root library directory. Optional â€” defaults to C<lib>. 76: 77: =item * C<mutation_level> 78: 79: Controls the breadth of mutation. C<full> applies all mutations; 80: C<fast> deduplicates and removes redundant mutants first. 81: Optional â€” defaults to C<full>. 82: 83: =back 84: 85: =head3 Returns 86: 87: A blessed hashref. Croaks if C<file> is missing or does not exist. 88: 89: =head3 API specification 90: 91: =head4 input 92: 93: { 94: file => { type => SCALAR }, 95: lib_dir => { type => SCALAR, optional => 1 }, 96: mutation_level => { type => SCALAR, optional => 1 }, 97: } 98: 99: =head4 output 100: 101: { 102: type => OBJECT, 103: isa => 'App::Test::Generator::Mutator', 104: } 105: 106: =cut 107: 108: sub new { 109: my ($class, %args) = @_; 110: 111: # file is required and must exist on disk 112: croak 'file required' unless defined $args{file}; 113: croak "file not found: $args{file}" unless -f $args{file}; 114: 115: return bless { 116: file => $args{file}, 117: lib_dir => $args{lib_dir} || $DEFAULT_LIB_DIR, 118: mutation_level => $args{mutation_level} || $DEFAULT_MUTATION_LEVEL, 119: 120: # Instantiate all registered mutation strategies 121: mutations => [ 122: App::Test::Generator::Mutation::BooleanNegation->new(), 123: App::Test::Generator::Mutation::ReturnUndef->new(), 124: App::Test::Generator::Mutation::NumericBoundary->new(), 125: App::Test::Generator::Mutation::ConditionalInversion->new(), 126: ], 127: }, $class; 128: } 129: 130: =head2 generate_mutants 131: 132: Parse the target file and generate all mutants by running each registered 133: mutation strategy against the PPI document. 134: 135: my @mutants = $mutator->generate_mutants(); 136: 137: =head3 Arguments 138: 139: None beyond C<$self>. 140: 141: =head3 Returns 142: 143: A list of L<App::Test::Generator::Mutant> objects. In C<fast> mode, 144: redundant and duplicate mutants are removed before returning. 145: 146: =head3 API specification 147: 148: =head4 input 149: 150: { 151: self => { type => OBJECT, isa => 'App::Test::Generator::Mutator' }, 152: } 153: 154: =head4 output 155: 156: { 157: type => ARRAYREF, 158: elements => { type => OBJECT, isa => 'App::Test::Generator::Mutant' }, 159: } 160: 161: =cut 162: 163: sub generate_mutants { ●164 → 172 → 177●164 → 172 → 0 164: my $self = $_[0]; 165: 166: # Parse the target file into a PPI document 167: my $doc = PPI::Document->new($self->{file}) or croak "Unable to parse $self->{file}"; 168: 169: my @mutants; 170: 171: # Run each registered mutation strategy against the document 172: for my $mutation (@{ $self->{mutations} }) { 173: push @mutants, $mutation->mutate($doc); 174: } 175: 176: # In fast mode deduplicate and remove redundant mutants

Mutants (Total: 1, Killed: 0, Survived: 1)

COND_INV_177_2: Invert condition if to unless
MEDIUM: Add tests asserting both true and false outcomes

178: return @{ _dedup_mutants(\@mutants) }; 179: } 180: