lib/App/Test/Generator/Mutant.pm

filter: Statementstmt 100% 25 / 25 Branchbran 100% 4 / 4 Conditioncond n/a MC/DCmcdc n/a Subroutinesub 100% 13 / 13 Podpod 100% 10 / 10 totaltotal 100% 52 / 52 CC 4 SCAR 5.6
CC
4
Cov
100%
new
4.0
BEGIN
1.0
BEGIN
1.0
CRAP 1.8
« blib/lib/App/Test/Generator/Exporter/YAML.pm ↑ Summary lib/App/Test/Generator/Template.pm »
1 package App::Test::Generator::Mutant;
2  
3 47 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 47 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
5 47 ▶use Carp qw(croak);
Subroutine BEGIN: called CC=1 SCAR=0.0
6  
7 47 our $VERSION = '0.50';
8  
9 =head1 VERSION
10  
11 Version 0.50
12  
13 =head1 DESCRIPTION
14  
15 Represents a single mutant - a specific transformation of a source file
16 that a test suite should be able to detect. Each mutant carries the
17 metadata needed to identify it, locate it in the source, and apply the
18 transformation to a fresh L<PPI::Document> copy at test time.
19  
20 =head2 new
21  
22 Construct a new mutant object.
23  
24 my $mutant = App::Test::Generator::Mutant->new(
25 id => 'NUM_BOUNDARY_10_5_!=',
26 description => 'Numeric boundary flip == to !=',
27 original => '==',
28 line => 10,
29 type => 'comparison',
30 group => 'NUM_BOUNDARY:10',
31 transform => sub {
32 my ($doc) = @_;
33 # ... modify $doc in place ...
34 },
35 );
36  
37 =head3 Arguments
38  
39 =over 4
40  
41 =item * C<id>
42  
43 A unique string identifying this mutant. Required.
44  
45 =item * C<description>
46  
47 A human-readable description of the mutation. Required.
48  
49 =item * C<original>
50  
51 The original source token or expression being mutated. Required.
52  
53 =item * C<line>
54  
55 The line number in the source file where the mutation occurs. Required.
56  
57 =item * C<transform>
58  
59 A CODE reference that accepts a L<PPI::Document> and applies the
60 mutation to it in place. Required.
61  
62 =item * C<type>
63  
64 An optional string classifying the mutation kind e.g. C<comparison>,
65 C<boolean>.
66  
67 =item * C<group>
68  
69 An optional string grouping related mutants together e.g. all mutations
70 on the same source line.
71  
72 =item * C<context>
73  
74 An optional string classifying the syntactic context the mutation was
75 taken from, e.g. C<conditional> when the mutated code sits inside an
76 C<if>/C<unless>/C<while>/C<until> condition, or C<statement>/C<expression>
77 otherwise. Used by L<App::Test::Generator::Mutator>'s fast-mode dedup to
78 recognise mutations that Perl's own boolean coercion already makes
79 redundant.
80  
81 =item * C<line_content>
82  
83 An optional string holding the raw source text of the line the mutation
84 targets. Used by L<App::Test::Generator::Mutator>'s fast-mode dedup to
85 skip mutations on comment-only lines.
86  
87 =back
88  
89 =head3 Returns
90  
91 A blessed hashref representing the mutant. Croaks if any required
92 attribute is missing or if C<transform> is not a CODE reference.
93  
94 =head3 API specification
95  
96 =head4 input
97  
98 {
99 id => { type => SCALAR },
100 description => { type => 'string' },
101 original => { type => SCALAR },
102 line => { type => SCALAR },
103 transform => { type => CODEREF },
104 type => { type => SCALAR, optional => 1 },
105 group => { type => SCALAR, optional => 1 },
106 context => { type => SCALAR, optional => 1 },
107 line_content => { type => SCALAR, optional => 1 },
108 }
109  
110 =head4 output
111  
112 {
113 type => 'object',
114 isa => 'App::Test::Generator::Mutant',
115 }
116  
117 =cut
118  
119 5147 ▶sub new {
Subroutine new: called CC=4 SCAR=13.9
Pod documented
120 5147 my ($class, %args) = @_;
121  
122 # Validate all required attributes are present
123 5147 for my $required (qw(id description original line transform)) {
124 croak "Missing required attribute: $required"
125 25705 ▶ unless exists $args{$required};
Branch: 1 branch
BranchTrueFalseTotal
unless exists $args{$required} 15 25690 25705
126 }
127  
128 # Ensure transform is actually executable
129 5132 ▶ croak 'transform must be a CODE reference' unless ref($args{transform}) eq 'CODE';
Branch: 1 branch
BranchTrueFalseTotal
unless ref $args{"transform"} eq "CODE" 9 5123 5132
130  
131 5123 return bless \%args, $class;
132 }
133  
134 =head2 id
135  
136 Return the unique identifier for this mutant.
137  
138 my $id = $mutant->id;
139  
140 =head3 API specification
141  
142 =head4 input
143  
144 { self => { type => 'object', isa => 'App::Test::Generator::Mutant' } }
145  
146 =head4 output
147  
148 { type => SCALAR }
149  
150 =cut
151  
152 160 ▶sub id {
Subroutine id: called CC=1 SCAR=0.0
Pod documented
153 160 return $_[0]->{id};
154 }
155  
156 =head2 description
157  
158 Return the human-readable description of the mutation.
159  
160 my $desc = $mutant->description;
161  
162 =head3 API specification
163  
164 =head4 input
165  
166 { self => { type => 'object', isa => 'App::Test::Generator::Mutant' } }
167  
168 =head4 output
169  
170 { type => SCALAR }
171  
172 =cut
173  
174 258 ▶sub description { $_[0]->{description} }
Subroutine description: called CC=1 SCAR=0.0
Pod documented
175  
176 =head2 original
177  
178 Return the original source token or expression that is being mutated.
179  
180 my $orig = $mutant->original;
181  
182 =head3 API specification
183  
184 =head4 input
185  
186 { self => { type => OBJECT, isa => 'App::Test::Generator::Mutant' } }
187  
188 =head4 output
189  
190 { type => SCALAR }
191  
192 =cut
193  
194 432 ▶sub original { $_[0]->{original} }
Subroutine original: called CC=1 SCAR=0.0
Pod documented
195  
196 =head2 line
197  
198 Return the line number in the source file where the mutation occurs.
199  
200 my $line = $mutant->line;
201  
202 =head3 API specification
203  
204 =head4 input
205  
206 { self => { type => OBJECT, isa => 'App::Test::Generator::Mutant' } }
207  
208 =head4 output
209  
210 { type => SCALAR }
211  
212 =cut
213  
214 1074 ▶sub line { $_[0]->{line} }
Subroutine line: called CC=1 SCAR=0.0
Pod documented
215  
216 =head2 transform
217  
218 Return the CODE reference that applies the mutation to a
219 L<PPI::Document> copy.
220  
221 my $xform = $mutant->transform;
222 $xform->($doc_copy);
223  
224 =head3 API specification
225  
226 =head4 input
227  
228 { self => { type => OBJECT, isa => 'App::Test::Generator::Mutant' } }
229  
230 =head4 output
231  
232 { type => CODEREF }
233  
234 =cut
235  
236 85 ▶sub transform { $_[0]->{transform} }
Subroutine transform: called CC=1 SCAR=0.0
Pod documented
237  
238 =head2 type
239  
240 Return the optional mutation type classification string,
241 e.g. C<comparison> or C<boolean>.
242  
243 my $type = $mutant->type;
244  
245 =head3 API specification
246  
247 =head4 input
248  
249 { self => { type => OBJECT, isa => 'App::Test::Generator::Mutant' } }
250  
251 =head4 output
252  
253 { type => SCALAR, optional => 1 }
254  
255 =cut
256  
257 46 ▶sub type { $_[0]->{type} }
Subroutine type: called CC=1 SCAR=0.0
Pod documented
258  
259 =head2 group
260  
261 Return the optional group string that clusters related mutants,
262 e.g. all mutations targeting the same source line.
263  
264 my $group = $mutant->group;
265  
266 =head3 API specification
267  
268 =head4 input
269  
270 { self => { type => OBJECT, isa => 'App::Test::Generator::Mutant' } }
271  
272 =head4 output
273  
274 { type => SCALAR, optional => 1 }
275  
276 =cut
277  
278 31 ▶sub group { $_[0]->{group} }
Subroutine group: called CC=1 SCAR=0.0
Pod documented
279  
280 =head2 context
281  
282 Return the optional syntactic-context classification string,
283 e.g. C<conditional> or C<statement>.
284  
285 my $context = $mutant->context;
286  
287 =head3 API specification
288  
289 =head4 input
290  
291 { self => { type => OBJECT, isa => 'App::Test::Generator::Mutant' } }
292  
293 =head4 output
294  
295 { type => SCALAR, optional => 1 }
296  
297 =cut
298  
299 390 ▶sub context { $_[0]->{context} }
Subroutine context: called CC=1 SCAR=0.0
Pod documented
300  
301 =head2 line_content
302  
303 Return the optional raw source text of the line this mutant targets.
304  
305 my $text = $mutant->line_content;
306  
307 =head3 API specification
308  
309 =head4 input
310  
311 { self => { type => 'object', isa => 'App::Test::Generator::Mutant' } }
312  
313 =head4 output
314  
315 { type => 'string', optional => 1 }
316  
317 =cut
318  
319 401 ▶sub line_content { $_[0]->{line_content} }
Subroutine line_content: called CC=1 SCAR=0.0
Pod documented
320  
321 =head1 AUTHOR
322  
323 Nigel Horne, C<< <njh at nigelhorne.com> >>
324  
325 Portions of this module's initial design and documentation were created
326 with the assistance of AI.
327  
328 =head1 LICENCE AND COPYRIGHT
329  
330 Copyright 2025-2026 Nigel Horne.
331  
332 Usage is subject to the terms of GPL2.
333 If you use it,
334 please let me know.
335  
336 =cut
337  
338 47 1;
« blib/lib/App/Test/Generator/Exporter/YAML.pm ↑ Summary lib/App/Test/Generator/Template.pm »