lib/App/Test/Generator/Mutation/ReturnUndef.pm

filter: Statementstmt 100% 78 / 78 Branchbran 81.5% 31 / 38 Conditioncond 76.1% 16 / 21 MC/DCmcdc 50.0% 6 / 12 Subroutinesub 100% 13 / 13 Podpod 100% 2 / 2 totaltotal 89.0% 146 / 164 CC 32 SCAR 18.4
CC
32
Cov
91%
mutate
10.2
__ANON__
9.5
_return_expr_span
7.0
CRAP 6.3
« lib/App/Test/Generator/Emitter/Perl.pm ↑ Summary blib/lib/App/Test/Generator/PodExampleExtractor.pm »
1 package App::Test::Generator::Mutation::ReturnUndef;
2  
3 22 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 22 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
5 22 ▶use Carp qw(carp);
Subroutine BEGIN: called CC=1 SCAR=0.0
6 22 ▶use parent 'App::Test::Generator::Mutation::Base';
Subroutine BEGIN: called CC=1 SCAR=0.0
7 22 ▶use App::Test::Generator::Mutant;
Subroutine BEGIN: called CC=1 SCAR=0.0
8 22 ▶use PPI;
Subroutine BEGIN: called CC=1 SCAR=0.0
9  
10 22 our $VERSION = '0.49';
11  
12 =head1 NAME
13  
14 App::Test::Generator::Mutation::ReturnUndef - Replace return expressions
15 with undef to expose missing undef-return checks in the test suite
16  
17 =head1 VERSION
18  
19 Version 0.49
20  
21 =head1 METHODS
22  
23 =head2 applies_to
24  
25 Return true if the given document contains at least one return
26 statement this mutation strategy could mutate. Used by
27 L<App::Test::Generator::Mutator> to pre-filter strategies before
28 calling C<mutate>, so a document with nothing to mutate skips the
29 walk entirely.
30  
31 my $applies = $mutation->applies_to($doc);
32  
33 =head3 Arguments
34  
35 =over 4
36  
37 =item * C<$doc>
38  
39 A L<PPI::Document> object to inspect.
40  
41 =back
42  
43 =head3 Returns
44  
45 True if the document contains a C<return> statement (PPI::Statement::Break
46 whose first token is C<return>), false otherwise.
47  
48 =head3 API specification
49  
50 =head4 input
51  
52 {
53 self => { type => OBJECT, isa => 'App::Test::Generator::Mutation::ReturnUndef' },
54 doc => { type => OBJECT, isa => 'PPI::Document' },
55 }
56  
57 =head4 output
58  
59 { type => SCALAR }
60  
61 =cut
62  
63 73 ▶sub applies_to {
Subroutine applies_to: called CC=3 SCAR=11.0
Pod documented
64 73 my ($self, $doc) = @_;
65  
66 # PPI >= 1.270 classifies return as PPI::Statement::Break rather
67 # than the dedicated PPI::Statement::Return class -- scan the whole
68 # document for at least one qualifying return statement. This must
69 # match the document-level pre-filter contract used by
70 # Mutator::generate_mutants (and documented in Mutation::Base) rather
71 # than testing a single node, otherwise every call from
72 # generate_mutants would see $doc itself, which is never a
73 # PPI::Statement::Break, and mutate() would never run.
74 8292 ▶ my $returns = $doc->find(sub {
Subroutine __ANON__: called CC=3 SCAR=11.0
75 8292 my $node = $_[1];
76 8292 ▶ return 0 unless $node->isa('PPI::Statement::Break');
Branch: 1 branch
BranchTrueFalseTotal
unless $node->isa("PPI::Statement::Break") 8092 200 8292
77 200 ▶ my $first = $node->schild(0) or return 0;
Branch: 1 branch
BranchTrueFalseTotal
my $first = $node->schild(0) or return 0 200 0 200
78 200 return $first->content eq 'return';
79 73 ▶ }) || [];
Condition100%2/2
$doc->find(sub { my $node = $_[1]; return 0 unless $node->isa('PPI::Statement::Break'); my $first = $node->schild(0) or return 0; return $first->content eq 'return'; } ) || []
l!l
676
MC/DC100%1/1
$doc->find(sub { my $node = $_[1]; return 0 unless $node->isa('PPI::Statement::Break'); my $first = $node->schild(0) or return 0; return $first->content eq 'return'; } ) || []
$doc->find(sub { my $node = $_[1]; return 0 unless $node->isa('PPI::Statement::Break'); my $first = $node->schild(0) or return 0; return $first->content eq 'return'; } )
Truth table100%2/2
A
A= $doc->find(sub { my $node = $_[1]; return 0 unless $node->isa('PPI::Statement::Break'); my $first = $node->schild(0) or return 0; return $first->content eq 'return'; } )
Aresult
11
00
80  
81 73 ▶ return @{$returns} ? 1 : 0;
Branch: 1 branch
BranchTrueFalseTotal
@{$returns;} ? : 67 6 73
82 }
83  
84 =head2 mutate
85  
86 Walk a PPI document and generate one mutant for each non-bare return
87 statement, replacing its expression with C<undef>. For example,
88 C<return $result> becomes C<return undef>.
89  
90 Bare C<return;> statements are skipped because they already return
91 undef - mutating them would produce a redundant mutant that can never
92 be killed.
93  
94 my $mutation = App::Test::Generator::Mutation::ReturnUndef->new;
95 my $doc = PPI::Document->new(\$source);
96 my @mutants = $mutation->mutate($doc);
97  
98 for my $m (@mutants) {
99 print $m->id, ': ', $m->description, "\n";
100 }
101  
102 =head3 Arguments
103  
104 =over 4
105  
106 =item * C<$self>
107  
108 An instance of C<App::Test::Generator::Mutation::ReturnUndef>.
109  
110 =item * C<$doc>
111  
112 A L<PPI::Document> object representing the parsed source to mutate.
113 The document is not modified by this method.
114  
115 =back
116  
117 =head3 Returns
118  
119 A list of L<App::Test::Generator::Mutant> objects, one per qualifying
120 return statement found in the document. Returns an empty list if no
121 non-bare return statements are found.
122  
123 Each mutant carries a C<transform> closure that when called with a
124 fresh L<PPI::Document> copy will replace the targeted return expression
125 with the literal C<undef>.
126  
127 =head3 Notes
128  
129 Mutant IDs include both line and column number to ensure uniqueness
130 when multiple return statements appear in the same source file.
131  
132 Only return statements with an expression child are mutated - bare
133 C<return;> statements are skipped as they already return undef.
134  
135 Each mutant's optional C<context> field is set to C<conditional> if
136 the return statement sits inside (or is itself the keyword of) an
137 C<if>/C<unless>/C<while>/C<until> compound statement, or C<statement>
138 otherwise; its C<line_content> field holds the raw source text of the
139 mutated line. Both are consumed by
140 L<App::Test::Generator::Mutator>'s fast-mode dedup.
141  
142 =head3 API specification
143  
144 =head4 input
145  
146 {
147 self => {
148 type => OBJECT,
149 isa => 'App::Test::Generator::Mutation::ReturnUndef',
150 },
151 doc => {
152 type => OBJECT,
153 isa => 'PPI::Document',
154 },
155 }
156  
157 =head4 output
158  
159 {
160 type => ARRAYREF,
161 elements => {
162 type => OBJECT,
163 isa => 'App::Test::Generator::Mutant',
164 },
165 }
166  
167 =cut
168  
169 106 ▶sub mutate {
Subroutine mutate: called CC=10 SCAR=23.2
Pod documented
170 106 my ($self, $doc) = @_;
171  
172 # PPI >= 1.270 classifies return statements as PPI::Statement::Break
173 # rather than PPI::Statement::Return -- use a custom predicate
174 8972 ▶ my $returns = $doc->find(sub {
Subroutine __ANON__: called CC=3 SCAR=11.0
175 8972 my $node = $_[1];
176 # Match Break nodes that are specifically return statements
177 8972 ▶ return 0 unless $node->isa('PPI::Statement::Break');
Branch: 1 branch
BranchTrueFalseTotal
unless $node->isa("PPI::Statement::Break") 8730 242 8972
178 242 ▶ my $first = $node->schild(0) or return 0;
Branch: 1 branch
BranchTrueFalseTotal
my $first = $node->schild(0) or return 0 242 0 242
179 242 return $first->content eq 'return';
180 106 ▶ }) || [];
Condition100%2/2
$doc->find(sub { my $node = $_[1]; return 0 unless $node->isa('PPI::Statement::Break'); my $first = $node->schild(0) or return 0; return $first->content eq 'return'; } ) || []
l!l
1033
MC/DC100%1/1
$doc->find(sub { my $node = $_[1]; return 0 unless $node->isa('PPI::Statement::Break'); my $first = $node->schild(0) or return 0; return $first->content eq 'return'; } ) || []
$doc->find(sub { my $node = $_[1]; return 0 unless $node->isa('PPI::Statement::Break'); my $first = $node->schild(0) or return 0; return $first->content eq 'return'; } )
Truth table100%2/2
A
A= $doc->find(sub { my $node = $_[1]; return 0 unless $node->isa('PPI::Statement::Break'); my $first = $node->schild(0) or return 0; return $first->content eq 'return'; } )
Aresult
11
00
181  
182 106 my @mutants;
183  
184 106 for my $ret (@{$returns}) {
185 # Skip bare return statements — they already return undef
186 # so mutating them would produce a redundant mutant that
187 # can never be killed by any meaningful test. Also skips
188 # bare returns with only a postfix conditional/loop modifier.
189 242 my @expr = _return_expr_span($ret);
190 242 ▶ next unless @expr;
Branch: 1 branch
BranchTrueFalseTotal
unless @expr 6 236 242
191  
192 # Skip a lone structure node (e.g. return ($x, $y) gives a
193 # single PPI::Structure::List child) — nothing simple to splice
194 236 ▶ next if @expr == 1 && !$expr[0]->isa('PPI::Token');
Branch: 1 branch
BranchTrueFalseTotal
if @expr == 1 and not $expr[0]->isa("PPI::Token") 1 235 236
Condition100%3/3
@expr == 1 and not $expr[0]->isa("PPI::Token")
!ll&&!rl&&r
571781
MC/DC100%2/2
@expr == 1 and not $expr[0]->isa("PPI::Token")
@expr == 1 not $expr[0]->isa("PPI::Token")
Truth table100%3/3
A and not(B)
A= @expr == 1B= not $expr[0]->isa("PPI::Token")
ABresult
0X0
100
111
195  
196 # Capture location so the transform closure targets the
197 # exact statement rather than the first match on that line
198 235 my $line = $ret->location->[0];
199 235 my $col = $ret->location->[1];
200  
201 # Build a unique ID from line and column so multiple return
202 # statements in the same file never collide
203 235 my $id = "RETURN_UNDEF_${line}_${col}";
204  
205 235 my $mutant = eval {
206 App::Test::Generator::Mutant->new(
207 id => $id,
208 group => "RETURN_UNDEF:$line",
209 description => 'Replace return expression with undef',
210 original => $ret->content(),
211 line => $line,
212 type => 'return',
213 context => $self->_in_conditional($ret) ? 'conditional' : 'statement',
214 line_content => $self->_line_content($doc, $line),
215  
216 # The transform closure captures line and col so it
217 # targets precisely the right return statement in the
218 # document copy it receives at test time
219 14 ▶ transform => sub {
Subroutine __ANON__: called CC=9 SCAR=22.5
220 14 my $doc = $_[0];
221 # PPI >= 1.270 uses PPI::Statement::Break for return
222 370 ▶ my $rets = $doc->find(sub {
Subroutine __ANON__: called CC=3 SCAR=11.0
223 370 my $node = $_[1];
224 370 ▶ return 0 unless $node->isa('PPI::Statement::Break');
Branch: 1 branch
BranchTrueFalseTotal
unless $node->isa("PPI::Statement::Break") 354 16 370
225 16 ▶ my $first = $node->schild(0) or return 0;
Branch: 1 branch
BranchTrueFalseTotal
my $first = $node->schild(0) or return 0 16 0 16
226 16 return $first->content eq 'return';
227 14 ▶ }) || [];
Condition50%1/2
$doc->find(sub { my $node = $_[1]; return 0 unless $node->isa('PPI::Statement::Break'); my $first = $node->schild(0) or return 0; return $first->content eq 'return'; } ) || []
l!l
140
MC/DC0%0/1
$doc->find(sub { my $node = $_[1]; return 0 unless $node->isa('PPI::Statement::Break'); my $first = $node->schild(0) or return 0; return $first->content eq 'return'; } ) || []
$doc->find(sub { my $node = $_[1]; return 0 unless $node->isa('PPI::Statement::Break'); my $first = $node->schild(0) or return 0; return $first->content eq 'return'; } )
Truth table50%1/2
A
A= $doc->find(sub { my $node = $_[1]; return 0 unless $node->isa('PPI::Statement::Break'); my $first = $node->schild(0) or return 0; return $first->content eq 'return'; } )
Aresult
11
00
228 14 for my $ret (@{$rets}) {
229 15 ▶ next unless $ret->line_number == $line;
Branch: 1 branch
BranchTrueFalseTotal
unless $ret->line_number == $line 1 14 15
230 14 ▶ next unless $ret->column_number == $col;
Branch: 1 branch
BranchTrueFalseTotal
unless $ret->column_number == $col 0 14 14
231  
232 14 my @expr = _return_expr_span($ret);
233 14 ▶ last unless @expr;
Branch: 1 branch
BranchTrueFalseTotal
unless @expr 0 14 14
234 14 ▶ last if @expr == 1 && !$expr[0]->isa('PPI::Token');
Branch: 1 branch
BranchTrueFalseTotal
if @expr == 1 and not $expr[0]->isa("PPI::Token") 0 14 14
Condition66%2/3
@expr == 1 and not $expr[0]->isa("PPI::Token")
!ll&&!rl&&r
590
MC/DC0%0/2
@expr == 1 and not $expr[0]->isa("PPI::Token")
@expr == 1 not $expr[0]->isa("PPI::Token")
Truth table66%2/3
A and not(B)
A= @expr == 1B= not $expr[0]->isa("PPI::Token")
ABresult
0X0
100
111
235  
236 # Replace the whole expression span with a single
237 # 'undef' token rather than just its first token --
238 # $self->{x} is three significant children (Symbol,
239 # Operator, Structure) and replacing only the
240 # leading $self produced the broken mutant
241 # 'return undef->{x};'
242 14 $expr[0]->insert_before(PPI::Token::Word->new('undef'));
243 14 $_->remove for @expr;
244 14 last;
245 }
246 },
247 235 ▶ );
Branch: 1 branch
BranchTrueFalseTotal
$self->_in_conditional($ret) ? : 86 149 235
248 };
249  
250 # If the Mutant construction fails, report clearly rather than
251 # silently dropping the mutant from the results
252 235 ▶ if($@ || !$mutant) {
Branch: 1 branch
BranchTrueFalseTotal
if ($@ or not $mutant) 1 234 235
Condition66%2/3
$@ or not $mutant
l!l&&r!l&&!r
10234
MC/DC50%1/2
$@ or not $mutant
$@ not $mutant
Truth table66%2/3
A or not(B)
A= $@B= not $mutant
ABresult
1X1
011
000
253 1 ▶ carp "Failed to construct mutant $id: $@" if $@;
Branch: 1 branch
BranchTrueFalseTotal
if $@ 1 0 1
254 1 next;
255 }
256  
257 234 push @mutants, $mutant;
258 }
259  
260 106 return @mutants;
261 }
262  
263 # --------------------------------------------------
264 # Purpose: identify the PPI elements making up the expression
265 # being returned by a 'return' statement, excluding
266 # the leading 'return' keyword, the trailing statement
267 # terminator, and any postfix conditional/loop modifier
268 # (if/unless/while/until/for/foreach) and its condition.
269 # Entry: a PPI::Statement::Break node already confirmed to be
270 # a 'return' statement.
271 # Exit: a list of the significant child elements making up
272 # the return expression, or an empty list for a bare
273 # return (with or without a postfix modifier).
274 # Side effects: none.
275 # --------------------------------------------------
276 260 ▶sub _return_expr_span {
Subroutine _return_expr_span: called CC=7 SCAR=19.5
277 260 my ($ret) = @_;
278  
279 260 my @children = $ret->schildren;
280 260 shift @children;
281  
282 260 ▶ if(@children && $children[-1]->isa('PPI::Token::Structure') && $children[-1]->content eq ';') {
Branch: 1 branch
BranchTrueFalseTotal
if (@children and $children[-1]->isa("PPI::Token::Structure") and $children[-1]->content eq ";") 236 24 260
Condition66%4/6
@children and $children[-1]->isa("PPI::Token::Structure") and $children[-1]->content eq ";"
!ll&&!rl&&r
240236
@children and $children[-1]->isa("PPI::Token::Structure")
!ll&&!rl&&r
024236
MC/DC33%1/3
@children and $children[-1]->isa("PPI::Token::Structure") and $children[-1]->content eq ";"
@children $children[-1]->isa("PPI::Token::Structure") $children[-1]->content eq ";"
Truth table50%2/4
A and B and C
A= @childrenB= $children[-1]->isa("PPI::Token::Structure")C= $children[-1]->content eq ";"
ABCresult
0XX0
10X0
1100
1111
283 236 pop @children;
284 }
285  
286 260 for my $i (0 .. $#children) {
287 476 my $child = $children[$i];
288 476 ▶ next unless $child->isa('PPI::Token::Word');
Branch: 1 branch
BranchTrueFalseTotal
unless $child->isa("PPI::Token::Word") 456 20 476
289 20 ▶ next unless $child->content =~ /^(?:if|unless|while|until|for|foreach)$/;
Branch: 1 branch
BranchTrueFalseTotal
unless $child->content =~ /^(?:if|unless|while|until|for|foreach)$/ 9 11 20
290 11 @children = @children[0 .. $i - 1];
291 11 last;
292 }
293  
294 260 return @children;
295 }
296  
297 =head1 AUTHOR
298  
299 Nigel Horne, C<< <njh at nigelhorne.com> >>
300  
301 =head1 LICENCE AND COPYRIGHT
302  
303 Copyright 2026 Nigel Horne.
304  
305 Usage is subject to the terms of GPL2.
306 If you use it,
307 please let me know.
308  
309 =cut
310  
311 22 1;
« lib/App/Test/Generator/Emitter/Perl.pm ↑ Summary blib/lib/App/Test/Generator/PodExampleExtractor.pm »