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 25 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 25 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
5  
6 25 ▶use Carp qw(carp);
Subroutine BEGIN: called CC=1 SCAR=0.0
7 25 ▶use parent 'App::Test::Generator::Mutation::Base';
Subroutine BEGIN: called CC=1 SCAR=0.0
8 25 ▶use App::Test::Generator::Mutant;
Subroutine BEGIN: called CC=1 SCAR=0.0
9 25 ▶use PPI;
Subroutine BEGIN: called CC=1 SCAR=0.0
10  
11 25 our $VERSION = '0.51';
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.51
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 78 ▶sub applies_to {
Subroutine applies_to: called CC=3 SCAR=11.0
Pod documented
65 78 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 8556 ▶ my $returns = $doc->find(sub {
Subroutine __ANON__: called CC=3 SCAR=11.0
75 8556 my $node = $_[1];
76 8556 ▶ return 0 unless $node->isa('PPI::Statement::Break');
Branch: 1 branch
BranchTrueFalseTotal
unless $node->isa("PPI::Statement::Break") 8351 205 8556
77 205 ▶ my $first = $node->schild(0) or return 0;
Branch: 1 branch
BranchTrueFalseTotal
my $first = $node->schild(0) or return 0 205 0 205
78 205 return $first->content eq 'return';
79 78 ▶ }) || [];
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
717
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 78 ▶ return @{$returns} ? 1 : 0;
Branch: 1 branch
BranchTrueFalseTotal
@{$returns;} ? : 71 7 78
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 113 ▶sub mutate {
Subroutine mutate: called CC=10 SCAR=23.3
Pod documented
167 113 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 9292 ▶ my $returns = $doc->find(sub {
Subroutine __ANON__: called CC=3 SCAR=11.0
173 9292 my $node = $_[1];
174 # Must be a Break statement -- the parent class for return in
175 # newer PPI versions
176 9292 ▶ return 0 unless $node->isa('PPI::Statement::Break');
Branch: 1 branch
BranchTrueFalseTotal
unless $node->isa("PPI::Statement::Break") 9041 251 9292
177 # Distinguish return from last/next/redo by checking the
178 # first significant child token
179 251 ▶ my $first = $node->schild(0) or return 0;
Branch: 1 branch
BranchTrueFalseTotal
my $first = $node->schild(0) or return 0 251 0 251
180 251 return $first->content eq 'return';
181 113 ▶ }) || [];
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
1094
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 113 my @mutants;
184  
185 113 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 251 my @expr = _return_expr_span($ret);
190 251 ▶ next unless @expr;
Branch: 1 branch
BranchTrueFalseTotal
unless @expr 7 244 251
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 244 ▶ next if @expr == 1 && !$expr[0]->isa('PPI::Token');
Branch: 1 branch
BranchTrueFalseTotal
if @expr == 1 and not $expr[0]->isa("PPI::Token") 0 244 244
Condition66%2/3
@expr == 1 and not $expr[0]->isa("PPI::Token")
!ll&&!rl&&r
611830
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 244 my $line = $ret->location->[0];
200 244 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 244 my $id = "BOOL_NEGATE_${line}_${col}";
205  
206 244 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 21 ▶ transform => sub {
Subroutine __ANON__: called CC=8 SCAR=21.2
221 21 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 996 ▶ my $rets = $doc->find(sub {
Subroutine __ANON__: called CC=3 SCAR=11.0
227 996 my $node = $_[1];
228 # Match Break nodes only -- covers return/last/next/redo
229 996 ▶ return 0 unless $node->isa('PPI::Statement::Break');
Branch: 1 branch
BranchTrueFalseTotal
unless $node->isa("PPI::Statement::Break") 968 28 996
230 # Filter to return specifically by inspecting the first token
231 28 ▶ my $first = $node->schild(0) or return 0;
Branch: 1 branch
BranchTrueFalseTotal
my $first = $node->schild(0) or return 0 28 0 28
232 28 return $first->content eq 'return';
233 21 ▶ }) || [];
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
210
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 21 for my $ret (@{$rets}) {
236 # Match by line and column to avoid mutating
237 # the wrong return statement
238 23 ▶ next unless $ret->line_number == $line;
Branch: 1 branch
BranchTrueFalseTotal
unless $ret->line_number == $line 2 21 23
239 21 ▶ next unless $ret->column_number == $col;
Branch: 1 branch
BranchTrueFalseTotal
unless $ret->column_number == $col 0 21 21
240  
241 # Skip bare returns with no expression
242 21 my @expr = _return_expr_span($ret);
243 21 ▶ last unless @expr;
Branch: 1 branch
BranchTrueFalseTotal
unless @expr 0 21 21
244  
245 # Skip a lone structure node
246 21 ▶ last if @expr == 1 && !$expr[0]->isa('PPI::Token');
Branch: 1 branch
BranchTrueFalseTotal
if @expr == 1 and not $expr[0]->isa("PPI::Token") 0 21 21
Condition66%2/3
@expr == 1 and not $expr[0]->isa("PPI::Token")
!ll&&!rl&&r
11100
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 21 $expr[0]->insert_before(PPI::Token::Operator->new('!'));
254 21 $expr[0]->insert_before(PPI::Token::Structure->new('('));
255 21 $expr[-1]->insert_after(PPI::Token::Structure->new(')'));
256 21 last;
257 }
258 },
259 244 ▶ );
Branch: 1 branch
BranchTrueFalseTotal
$self->_in_conditional($ret) ? : 87 157 244
260 };
261  
262 # If the Mutant construction fails, report clearly rather than
263 # silently dropping the mutant from the results
264 244 ▶ if($@ || !$mutant) {
Branch: 1 branch
BranchTrueFalseTotal
if ($@ or not $mutant) 1 243 244
Condition66%2/3
$@ or not $mutant
l!l&&r!l&&!r
10243
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 243 push @mutants, $mutant;
270 }
271  
272 113 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 274 ▶sub _return_expr_span {
Subroutine _return_expr_span: called CC=7 SCAR=19.5
289 274 my ($ret) = @_;
290  
291 274 my @children = $ret->schildren;
292 274 shift @children;
293  
294 274 ▶ 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 ";") 249 25 274
Condition66%4/6
@children and $children[-1]->isa("PPI::Token::Structure") and $children[-1]->content eq ";"
!ll&&!rl&&r
250249
@children and $children[-1]->isa("PPI::Token::Structure")
!ll&&!rl&&r
025249
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 249 pop @children;
296 }
297  
298 274 for my $i (0 .. $#children) {
299 549 my $child = $children[$i];
300 549 ▶ next unless $child->isa('PPI::Token::Word');
Branch: 1 branch
BranchTrueFalseTotal
unless $child->isa("PPI::Token::Word") 525 24 549
301 24 ▶ next unless $child->content =~ /^(?:if|unless|while|until|for|foreach)$/;
Branch: 1 branch
BranchTrueFalseTotal
unless $child->content =~ /^(?:if|unless|while|until|for|foreach)$/ 13 11 24
302 11 @children = @children[0 .. $i - 1];
303 11 last;
304 }
305  
306 274 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 25 1;
« blib/lib/App/Test/Generator/Analyzer/Return.pm ↑ Summary lib/App/Test/Generator/Planner/Fixture.pm »