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

filter: Statementstmt 100% 79 / 79 Branchbran 78.9% 30 / 38 Conditioncond 71.4% 15 / 21 MC/DCmcdc 33.3% 4 / 12 Subroutinesub 100% 13 / 13 Podpod 100% 2 / 2 totaltotal 86.6% 143 / 165 CC 31 SCAR 18.0
CC
31
Cov
90%
mutate
10.3
__ANON__
8.4
_return_expr_span
7.0
CRAP 6.1
« blib/lib/App/Test/Generator/Analyzer/Return.pm ↑ Summary lib/App/Test/Generator/Planner/Fixture.pm »
1 package App::Test::Generator::Mutation::BooleanNegation;
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  
6 22 ▶use Carp qw(carp);
Subroutine BEGIN: called CC=1 SCAR=0.0
7 22 ▶use parent 'App::Test::Generator::Mutation::Base';
Subroutine BEGIN: called CC=1 SCAR=0.0
8 22 ▶use App::Test::Generator::Mutant;
Subroutine BEGIN: called CC=1 SCAR=0.0
9 22 ▶use PPI;
Subroutine BEGIN: called CC=1 SCAR=0.0
10  
11 22 our $VERSION = '0.50';
12  
13 =head1 NAME
14  
15 App::Test::Generator::Mutation::BooleanNegation - Negate boolean return
16 expressions to expose missing assertion coverage
17  
18 =head1 VERSION
19  
20 Version 0.50
21  
22 =head1 METHODS
23  
24 =head2 applies_to
25  
26 Return true if the given document contains at least one return
27 statement this mutation strategy could mutate. Used by
28 L<App::Test::Generator::Mutator> to pre-filter strategies before
29 calling C<mutate>, so a document with nothing to mutate skips the
30 walk entirely.
31  
32 my $applies = $mutation->applies_to($doc);
33  
34 =head3 Arguments
35  
36 =over 4
37  
38 =item * C<$doc>
39  
40 A L<PPI::Document> object to inspect.
41  
42 =back
43  
44 =head3 Returns
45  
46 True if the document contains a C<return> statement (PPI::Statement::Break
47 whose first token is C<return>), false otherwise.
48  
49 =head3 API specification
50  
51 =head4 input
52  
53 {
54 self => { type => OBJECT, isa => 'App::Test::Generator::Mutation::BooleanNegation' },
55 doc => { type => OBJECT, isa => 'PPI::Document' },
56 }
57  
58 =head4 output
59  
60 { type => SCALAR }
61  
62 =cut
63  
64 74 ▶sub applies_to {
Subroutine applies_to: called CC=3 SCAR=11.0
Pod documented
65 74 my ($self, $doc) = @_;
66  
67 # PPI >= 1.270 classifies return as PPI::Statement::Break rather
68 # than PPI::Statement::Return -- scan the whole document for at
69 # least one qualifying return statement. This must match the
70 # document-level pre-filter contract used by Mutator::generate_mutants
71 # (and documented in Mutation::Base) rather than testing a single node,
72 # otherwise every call from generate_mutants would see $doc itself,
73 # which is never a PPI::Statement::Break, and mutate() would never run.
74 8325 ▶ my $returns = $doc->find(sub {
Subroutine __ANON__: called CC=3 SCAR=11.0
75 8325 my $node = $_[1];
76 8325 ▶ return 0 unless $node->isa('PPI::Statement::Break');
Branch: 1 branch
BranchTrueFalseTotal
unless $node->isa("PPI::Statement::Break") 8124 201 8325
77 201 ▶ my $first = $node->schild(0) or return 0;
Branch: 1 branch
BranchTrueFalseTotal
my $first = $node->schild(0) or return 0 201 0 201
78 201 return $first->content eq 'return';
79 74 ▶ }) || [];
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
677
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 74 ▶ return @{$returns} ? 1 : 0;
Branch: 1 branch
BranchTrueFalseTotal
@{$returns;} ? : 67 7 74
82 }
83  
84 =head2 mutate
85  
86 Walk a PPI document and generate one mutant for each return statement
87 whose expression can be negated. For example, C<return $ok> becomes
88 C<return !($ok)>.
89  
90 my $mutation = App::Test::Generator::Mutation::BooleanNegation->new;
91 my $doc = PPI::Document->new(\$source);
92 my @mutants = $mutation->mutate($doc);
93  
94 for my $m (@mutants) {
95 print $m->id, ': ', $m->description, "\n";
96 }
97  
98 =head3 Arguments
99  
100 =over 4
101  
102 =item * C<$self>
103  
104 An instance of C<App::Test::Generator::Mutation::BooleanNegation>.
105  
106 =item * C<$doc>
107  
108 A L<PPI::Document> object representing the parsed source to mutate.
109 The document is not modified by this method.
110  
111 =back
112  
113 =head3 Returns
114  
115 A list of L<App::Test::Generator::Mutant> objects, one per qualifying
116 return statement found in the document. Returns an empty list if no
117 return statements with expressions are found.
118  
119 Each mutant carries a C<transform> closure that when called with a
120 fresh L<PPI::Document> copy will wrap the targeted return expression
121 in C<!( )>, negating its boolean value.
122  
123 =head3 Notes
124  
125 Mutant IDs include both line and column number to ensure uniqueness
126 when multiple return statements appear on different lines of the same
127 source file.
128  
129 Only return statements that have an expression child (i.e. not bare
130 C<return;> statements) are mutated.
131  
132 Each mutant's optional C<context> field is set to C<conditional> if
133 the return statement sits inside (or is itself the keyword of) an
134 C<if>/C<unless>/C<while>/C<until> compound statement, or C<statement>
135 otherwise; its C<line_content> field holds the raw source text of the
136 mutated line. Both are consumed by
137 L<App::Test::Generator::Mutator>'s fast-mode dedup.
138  
139 =head3 API specification
140  
141 =head4 input
142  
143 {
144 self => {
145 type => OBJECT,
146 isa => 'App::Test::Generator::Mutation::BooleanNegation',
147 },
148 doc => {
149 type => OBJECT,
150 isa => 'PPI::Document',
151 },
152 }
153  
154 =head4 output
155  
156 {
157 type => ARRAYREF,
158 elements => {
159 type => OBJECT,
160 isa => 'App::Test::Generator::Mutant',
161 },
162 }
163  
164 =cut
165  
166 109 ▶sub mutate {
Subroutine mutate: called CC=10 SCAR=23.3
Pod documented
167 109 my ($self, $doc) = @_;
168  
169 # PPI >= 1.270 classifies return statements as PPI::Statement::Break
170 # (alongside last/next/redo) rather than PPI::Statement::Return.
171 # Use a custom predicate to match only 'return' Break nodes.
172 9061 ▶ my $returns = $doc->find(sub {
Subroutine __ANON__: called CC=3 SCAR=11.0
173 9061 my $node = $_[1];
174 # Must be a Break statement -- the parent class for return in
175 # newer PPI versions
176 9061 ▶ return 0 unless $node->isa('PPI::Statement::Break');
Branch: 1 branch
BranchTrueFalseTotal
unless $node->isa("PPI::Statement::Break") 8814 247 9061
177 # Distinguish return from last/next/redo by checking the
178 # first significant child token
179 247 ▶ my $first = $node->schild(0) or return 0;
Branch: 1 branch
BranchTrueFalseTotal
my $first = $node->schild(0) or return 0 247 0 247
180 247 return $first->content eq 'return';
181 109 ▶ }) || [];
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
1054
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
182  
183 109 my @mutants;
184  
185 109 for my $ret (@{$returns}) {
186 # Skip bare return statements with no expression to negate,
187 # and bare returns with only a postfix conditional/loop
188 # modifier (return if $cond; has nothing to negate)
189 247 my @expr = _return_expr_span($ret);
190 247 ▶ next unless @expr;
Branch: 1 branch
BranchTrueFalseTotal
unless @expr 7 240 247
191  
192 # Skip a lone structure node (e.g. return ($x, $y) gives a
193 # single PPI::Structure::List child) — wrapping it is not
194 # useful and there is nothing simple to splice around
195 240 ▶ next if @expr == 1 && !$expr[0]->isa('PPI::Token');
Branch: 1 branch
BranchTrueFalseTotal
if @expr == 1 and not $expr[0]->isa("PPI::Token") 0 240 240
Condition66%2/3
@expr == 1 and not $expr[0]->isa("PPI::Token")
!ll&&!rl&&r
571830
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
196  
197 # Capture location so the transform closure targets the
198 # exact statement rather than the first match on that line
199 240 my $line = $ret->location->[0];
200 240 my $col = $ret->location->[1];
201  
202 # Build a unique ID from line and column so multiple return
203 # statements in the same file never collide
204 240 my $id = "BOOL_NEGATE_${line}_${col}";
205  
206 240 my $mutant = eval {
207 App::Test::Generator::Mutant->new(
208 id => $id,
209 group => "BOOL_NEGATE:$line",
210 description => 'Negate boolean return expression',
211 original => $ret->content,
212 line => $line,
213 type => 'boolean',
214 context => $self->_in_conditional($ret) ? 'conditional' : 'statement',
215 line_content => $self->_line_content($doc, $line),
216  
217 # The transform closure captures line and col so it
218 # targets precisely the right return statement in the
219 # document copy it receives at test time
220 17 ▶ transform => sub {
Subroutine __ANON__: called CC=8 SCAR=21.2
221 17 my $doc = $_[0];
222  
223 # Locate all return statements in the fresh document copy using
224 # the same PPI::Statement::Break predicate as the outer find --
225 # PPI >= 1.270 no longer uses PPI::Statement::Return
226 765 ▶ my $rets = $doc->find(sub {
Subroutine __ANON__: called CC=3 SCAR=11.0
227 765 my $node = $_[1];
228 # Match Break nodes only -- covers return/last/next/redo
229 765 ▶ return 0 unless $node->isa('PPI::Statement::Break');
Branch: 1 branch
BranchTrueFalseTotal
unless $node->isa("PPI::Statement::Break") 741 24 765
230 # Filter to return specifically by inspecting the first token
231 24 ▶ my $first = $node->schild(0) or return 0;
Branch: 1 branch
BranchTrueFalseTotal
my $first = $node->schild(0) or return 0 24 0 24
232 24 return $first->content eq 'return';
233 17 ▶ }) || [];
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
170
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
234  
235 17 for my $ret (@{$rets}) {
236 # Match by line and column to avoid mutating
237 # the wrong return statement
238 19 ▶ next unless $ret->line_number == $line;
Branch: 1 branch
BranchTrueFalseTotal
unless $ret->line_number == $line 2 17 19
239 17 ▶ next unless $ret->column_number == $col;
Branch: 1 branch
BranchTrueFalseTotal
unless $ret->column_number == $col 0 17 17
240  
241 # Skip bare returns with no expression
242 17 my @expr = _return_expr_span($ret);
243 17 ▶ last unless @expr;
Branch: 1 branch
BranchTrueFalseTotal
unless @expr 0 17 17
244  
245 # Skip a lone structure node
246 17 ▶ last if @expr == 1 && !$expr[0]->isa('PPI::Token');
Branch: 1 branch
BranchTrueFalseTotal
if @expr == 1 and not $expr[0]->isa("PPI::Token") 0 17 17
Condition66%2/3
@expr == 1 and not $expr[0]->isa("PPI::Token")
!ll&&!rl&&r
7100
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
247  
248 # Wrap the whole expression span in !(...) rather
249 # than just its first token -- $self->{x} is three
250 # significant children (Symbol, Operator, Structure)
251 # and wrapping only the leading $self produced the
252 # broken mutant 'return !($self)->{x};'
253 17 $expr[0]->insert_before(PPI::Token::Operator->new('!'));
254 17 $expr[0]->insert_before(PPI::Token::Structure->new('('));
255 17 $expr[-1]->insert_after(PPI::Token::Structure->new(')'));
256 17 last;
257 }
258 },
259 240 ▶ );
Branch: 1 branch
BranchTrueFalseTotal
$self->_in_conditional($ret) ? : 87 153 240
260 };
261  
262 # If the Mutant construction fails, report clearly rather than
263 # silently dropping the mutant from the results
264 240 ▶ if($@ || !$mutant) {
Branch: 1 branch
BranchTrueFalseTotal
if ($@ or not $mutant) 1 239 240
Condition66%2/3
$@ or not $mutant
l!l&&r!l&&!r
10239
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
265 1 ▶ carp "Failed to construct mutant $id: $@" if $@;
Branch: 1 branch
BranchTrueFalseTotal
if $@ 1 0 1
266 1 next;
267 }
268  
269 239 push @mutants, $mutant;
270 }
271  
272 109 return @mutants;
273 }
274  
275 # --------------------------------------------------
276 # Purpose: identify the PPI elements making up the expression
277 # being returned by a 'return' statement, excluding
278 # the leading 'return' keyword, the trailing statement
279 # terminator, and any postfix conditional/loop modifier
280 # (if/unless/while/until/for/foreach) and its condition.
281 # Entry: a PPI::Statement::Break node already confirmed to be
282 # a 'return' statement.
283 # Exit: a list of the significant child elements making up
284 # the return expression, or an empty list for a bare
285 # return (with or without a postfix modifier).
286 # Side effects: none.
287 # --------------------------------------------------
288 266 ▶sub _return_expr_span {
Subroutine _return_expr_span: called CC=7 SCAR=19.5
289 266 my ($ret) = @_;
290  
291 266 my @children = $ret->schildren;
292 266 shift @children;
293  
294 266 ▶ 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 ";") 241 25 266
Condition66%4/6
@children and $children[-1]->isa("PPI::Token::Structure") and $children[-1]->content eq ";"
!ll&&!rl&&r
250241
@children and $children[-1]->isa("PPI::Token::Structure")
!ll&&!rl&&r
025241
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
295 241 pop @children;
296 }
297  
298 266 for my $i (0 .. $#children) {
299 491 my $child = $children[$i];
300 491 ▶ next unless $child->isa('PPI::Token::Word');
Branch: 1 branch
BranchTrueFalseTotal
unless $child->isa("PPI::Token::Word") 469 22 491
301 22 ▶ next unless $child->content =~ /^(?:if|unless|while|until|for|foreach)$/;
Branch: 1 branch
BranchTrueFalseTotal
unless $child->content =~ /^(?:if|unless|while|until|for|foreach)$/ 11 11 22
302 11 @children = @children[0 .. $i - 1];
303 11 last;
304 }
305  
306 266 return @children;
307 }
308  
309 =head1 AUTHOR
310  
311 Nigel Horne, C<< <njh at nigelhorne.com> >>
312  
313 =head1 LICENCE AND COPYRIGHT
314  
315 Copyright 2026 Nigel Horne.
316  
317 Usage is subject to licence terms.
318  
319 The licence terms of this software are as follows:
320  
321 =over 4
322  
323 =item * Personal single user, single computer use: GPL2
324  
325 =item * All other users (including Commercial, Charity, Educational,
326 Government) must apply in writing for a licence for use from Nigel Horne
327 at the above e-mail.
328  
329 =back
330  
331 =cut
332  
333 22 1;
« blib/lib/App/Test/Generator/Analyzer/Return.pm ↑ Summary lib/App/Test/Generator/Planner/Fixture.pm »