lib/App/Test/Generator/CoverageGuidedFuzzer.pm

filter: Statementstmt 98.0% 403 / 411 Branchbran 89.5% 188 / 210 Conditioncond 82.2% 88 / 107 MC/DCmcdc 66.1% 43 / 65 Subroutinesub 98.0% 50 / 51 Podpod 100% 7 / 7 totaltotal 91.5% 779 / 851 CC 162 SCAR 23.7
CC
162
Cov
93%
_validate_value
33.7
_generate_for_schema
13.1
minimize_corpus
12.0
CRAP 10.7
« blib/lib/Devel/App/Test/Generator/LCSAJ/Runtime.pm ↑ Summary lib/App/Test/Generator/Mutation/Feedback.pm »
1 package App::Test::Generator::CoverageGuidedFuzzer;
2  
3 20 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 20 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
5 20 ▶use Carp qw(croak);
Subroutine BEGIN: called CC=1 SCAR=0.0
6 20 ▶use feature 'state';
Subroutine BEGIN: called CC=1 SCAR=0.0
7 20 ▶use Readonly;
Subroutine BEGIN: called CC=1 SCAR=0.0
8  
9 # --------------------------------------------------
10 # Fuzzing loop parameters
11 # --------------------------------------------------
12 20 Readonly my $DEFAULT_ITERATIONS => 100;
13 20 Readonly my $DEFAULT_TIMEOUT_SECS => 5; # per-call alarm() timeout; 0 disables
14 20 Readonly my $CORPUS_MUTATE_RATIO => 0.70; # 70% mutate, 30% explore
15 20 Readonly my $RANDOM_KEEP_RATIO => 0.20; # keep 20% random when no coverage
16 20 Readonly my $EDGE_CASE_RATIO => 0.40; # 40% chance to use declared edge case
17 20 Readonly my $INT_BOUNDARY_RATIO => 0.30; # 30% chance to use boundary int
18 20 Readonly my $STR_BOUNDARY_RATIO => 0.30; # 30% chance to use boundary length
19 20 Readonly my $SEED_CORPUS_SIZE => 5; # initial random inputs to seed corpus
20 20 Readonly my $DEFAULT_MAX_STR_LEN => 64;
21 20 Readonly my $MATCHES_REGEX_TIMEOUT_SECS => 1; # ReDoS guard for schema 'matches' patterns
22 20 Readonly my $DEFAULT_MAX_ARRAY => 4; # max elements in random array (0..N)
23 20 Readonly my $INT32_MAX => 2**31 - 1;
24 20 Readonly my $INT32_MIN => -(2**31);
25  
26 # --------------------------------------------------
27 # Character set and interesting-string constants —
28 # computed once at load time rather than rebuilt on
29 # every _rand_string / _mutate_string call.
30 # --------------------------------------------------
31 20 Readonly my @RAND_CHARS => ('a'..'z', 'A'..'Z', '0'..'9', ' ', "\t", "\n", "\0");
32 20 Readonly my @INTERESTING_STRINGS => (
33 '', ' ', "\0", "\n", "\t",
34 'a' x 256,
35 'null', 'undefined',
36 "'; DROP TABLE foo; --",
37 '<script>alert(1)</script>',
38 );
39  
40 # --------------------------------------------------
41 # Type name constants — used in schema dispatch
42 # --------------------------------------------------
43 20 Readonly my $TYPE_INTEGER => 'integer';
44 20 Readonly my $TYPE_NUMBER => 'number';
45 20 Readonly my $TYPE_BOOLEAN => 'boolean';
46 20 Readonly my $TYPE_ARRAY => 'arrayref';
47 20 Readonly my $TYPE_HASH => 'hashref';
48 20 Readonly my $TYPE_STRING => 'string';
49  
50 # --------------------------------------------------
51 # JSON module preference order
52 # --------------------------------------------------
53 20 Readonly my @JSON_MODULES => qw(JSON::MaybeXS JSON);
54  
55 # Devel::Cover files a branch with no else/elsif, and every && / ||,
56 # under 'condition' rather than 'branch', so both must be read.
57 20 Readonly my @COVER_CRITERIA => qw(branch condition);
58  
59 20 Readonly my $SOFT_BUG_WARNING_RE => qr/uninitialized|undefined|blessed|invalid/i;
60  
61 20 our $VERSION = '0.50';
62  
63 =encoding utf8
64  
65 =head1 NAME
66  
67 App::Test::Generator::CoverageGuidedFuzzer - AFL-style coverage-guided fuzzing for App::Test::Generator
68  
69 =head1 VERSION
70  
71 Version 0.50
72  
73 =head1 SYNOPSIS
74  
75 "Fuzzing" means calling a function many times with machine-made input,
76 to find input that makes it fail. The "corpus" is the list of inputs
77 that the fuzzer decided to keep.
78  
79 Pattern 1: fuzz a function that takes one number, then show the failures.
80 The C<input> key of the schema describes the one argument.
81  
82 use App::Test::Generator::CoverageGuidedFuzzer;
83  
84 my $fuzzer = App::Test::Generator::CoverageGuidedFuzzer->new(
85 schema => { input => { type => 'integer', min => 0, max => 100 } },
86 target_sub => \&My::Module::validate,
87 iterations => 200,
88 seed => 42,
89 );
90  
91 my $report = $fuzzer->run();
92 printf "%d failures in %d calls\n",
93 $report->{bugs_found}, $report->{total_iterations};
94 print " failed with: $_->{error}" for @{ $report->{bugs} };
95  
96 Pattern 2: keep what was learned between two runs of your program.
97  
98 my $file = 't/corpus/validate.json';
99 $fuzzer->load_corpus($file) if -e $file; # start from the last run
100 $fuzzer->run();
101  
102 # Optional: trim corpus to minimum branch-covering subset before saving
103 my $stats = $fuzzer->minimize_corpus();
104 printf "corpus %d -> %d entries\n", $stats->{before}, $stats->{after};
105  
106 $fuzzer->save_corpus($file);
107  
108 Pattern 3: fuzz a method of an object. The object is passed first and
109 the generated input second.
110  
111 my $fuzzer = App::Test::Generator::CoverageGuidedFuzzer->new(
112 schema => { input => { type => 'string', max => 20 } },
113 target_sub => \&My::Parser::parse,
114 instance => My::Parser->new(),
115 );
116 $fuzzer->run();
117  
118 Pattern 4: test with your own special values, here with non-ASCII text.
119 About 4 in 10 new inputs are taken from C<edge_case_array>.
120  
121 use utf8;
122 my $fuzzer = App::Test::Generator::CoverageGuidedFuzzer->new(
123 schema => {
124 input => {
125 type => 'string',
126 edge_case_array => [ '', 'na\x{EF}ve', "\x{1F600}" ],
127 },
128 },
129 target_sub => sub { length $_[0] },
130 timeout => 2,
131 );
132 $fuzzer->run();
133  
134 =head1 DESCRIPTION
135  
136 Implements coverage-guided fuzzing on top of App::Test::Generator's
137 existing schema-driven input generation. Instead of purely random
138 generation it:
139  
140 =over 4
141  
142 =item 1. Generates or mutates a structured input
143  
144 =item 2. Runs the target sub under Devel::Cover to capture branch hits
145  
146 =item 3. Keeps inputs that discover new branches in a corpus
147  
148 =item 4. Preferentially mutates corpus entries in future iterations
149  
150 =back
151  
152 This is the Perl equivalent of what AFL/libFuzzer do at the byte level,
153 but operating on typed, schema-validated Perl data structures.
154  
155 =head1 METHODS
156  
157 =head2 new
158  
159 Construct a new coverage-guided fuzzer.
160  
161 my $fuzzer = App::Test::Generator::CoverageGuidedFuzzer->new(
162 schema => $yaml_schema,
163 target_sub => \&My::Module::validate,
164 iterations => 200,
165 seed => 42,
166 instance => $obj, # optional pre-built object for method calls
167 );
168  
169 =head3 Arguments
170  
171 =over 4
172  
173 =item * C<schema>
174  
175 A hashref representing the parsed YAML schema for the target function.
176 Required. Only two keys are used: C<input>, which describes the single
177 argument that will be generated, and C<input_style>. Inside C<input> the
178 keys C<type>, C<min>, C<max>, C<matches>, C<items>, C<properties>,
179 C<optional> and C<edge_case_array> are used. For a string, C<min> and
180 C<max> are lengths counted in characters.
181  
182 =item * C<target_sub>
183  
184 A CODE reference to the function under test. Required.
185  
186 =item * C<iterations>
187  
188 Number of fuzzing iterations to run. Optional - defaults to 100.
189  
190 =item * C<seed>
191  
192 Random seed for reproducible runs. Optional - defaults to C<time()>.
193  
194 =item * C<instance>
195  
196 An optional pre-built object to use as the invocant when calling the
197 target sub as a method.
198  
199 =item * C<timeout>
200  
201 Seconds to allow each C<target_sub> call before it is aborted via
202 C<alarm()> and recorded as a bug. Optional - defaults to 5. Set to 0
203 to disable the timeout (e.g. for target subs that legitimately block).
204  
205 =back
206  
207 =head3 Returns
208  
209 A blessed hashref. Croaks if C<schema> or C<target_sub> is missing.
210  
211 =head3 Side effects
212  
213 Calls Perl's C<srand> with the seed. This restarts the random number
214 sequence for the whole program, not only for this object.
215 Prints one warning per program if L<Devel::Cover> cannot be loaded.
216  
217 =head3 API SPECIFICATION
218  
219 =head4 input
220  
221 {
222 schema => { type => HASHREF },
223 target_sub => { type => CODEREF },
224 iterations => { type => SCALAR, optional => 1 },
225 seed => { type => SCALAR, optional => 1 },
226 instance => { type => OBJECT, optional => 1 },
227 timeout => { type => SCALAR, optional => 1 },
228 }
229  
230 =head4 output
231  
232 {
233 type => OBJECT,
234 isa => 'App::Test::Generator::CoverageGuidedFuzzer',
235 }
236  
237 =head3 EXAMPLE
238  
239 my $fuzzer = App::Test::Generator::CoverageGuidedFuzzer->new(
240 schema => { input => { type => 'string' } },
241 target_sub => sub { length($_[0]) },
242 iterations => 50,
243 seed => 1234,
244 );
245  
246 =head3 MESSAGES
247  
248 =over 4
249  
250 =item C<schema required>
251  
252 C<schema> was not supplied or was falsy (e.g. C<undef> or C<0>).
253  
254 =item C<target_sub required>
255  
256 C<target_sub> was not supplied or was falsy.
257  
258 =back
259  
260 The mathematical description is in L</FORMAL SPECIFICATION>.
261  
262 =cut
263  
264 1920 ▶sub new {
Subroutine new: called CC=9 SCAR=22.3
Pod documented
265 1920 my ($class, %args) = @_;
266  
267 1920 ▶ croak 'schema required' unless $args{schema};
Branch: 1 branch
BranchTrueFalseTotal
unless $args{"schema"} 5 1915 1920
268 1915 ▶ croak 'target_sub required' unless $args{target_sub};
Branch: 1 branch
BranchTrueFalseTotal
unless $args{"target_sub"} 5 1910 1915
269  
270 my $self = bless {
271 schema => $args{schema},
272 target_sub => $args{target_sub},
273 instance => $args{instance},
274 iterations => $args{iterations} // $DEFAULT_ITERATIONS,
275 seed => $args{seed} // time(),
276 1910 ▶ timeout => $args{timeout} // $DEFAULT_TIMEOUT_SECS,
Condition100%8/8
$args{"iterations"} // $DEFAULT_ITERATIONS
l!l&&r!l&&!r
66312416
$args{"seed"} // time
l!l
6451265
$args{"timeout"} // $DEFAULT_TIMEOUT_SECS
l!l&&r!l&&!r
495140015
MC/DC100%2/2
$args{"iterations"} // $DEFAULT_ITERATIONS
$args{"iterations"} $DEFAULT_ITERATIONS
MC/DC100%1/1
$args{"seed"} // time
$args{"seed"}
MC/DC100%2/2
$args{"timeout"} // $DEFAULT_TIMEOUT_SECS
$args{"timeout"} $DEFAULT_TIMEOUT_SECS
Truth table100%3/3
A // B
A= $args{"iterations"}B= $DEFAULT_ITERATIONS
ABresult
1X1
011
000
Truth table100%2/2
A
A= $args{"seed"}
Aresult
11
00
Truth table100%3/3
A // B
A= $args{"timeout"}B= $DEFAULT_TIMEOUT_SECS
ABresult
1X1
011
000
277 corpus => [], # [{input => ..., coverage => {...}}]
278 covered => {}, # "file:line:branch" => 1
279 bugs => [], # [{input => ..., error => ...}]
280 stats => {
281 total => 0,
282 interesting => 0,
283 bugs => 0,
284 coverage => 0,
285 },
286 _cover_available => undef,
287 }, $class;
288  
289 1910 srand($self->{seed});
290  
291 # Probe for Devel::Cover availability once at construction time
292 1910 ▶ $self->{_cover_available} = eval { require Devel::Cover; 1 } ? 1 : 0;
Branch: 1 branch
BranchTrueFalseTotal
eval { do { require Devel::Cover; 1 } } ? : 1910 0 1910
293  
294 # Warn once per process if coverage guidance is unavailable
295 1910 state $cover_warned = 0;
296 1910 ▶ if(!$self->{_cover_available} && !$cover_warned++) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($self->{"_cover_available"} or $cover_warned++) 0 1910 1910
Condition33%1/3
$self->{"_cover_available"} or $cover_warned++
l!l&&r!l&&!r
191000
MC/DC0%0/2
$self->{"_cover_available"} or $cover_warned++
$self->{"_cover_available"} $cover_warned++
Truth table33%1/3
A or B
A= $self->{"_cover_available"}B= $cover_warned++
ABresult
1X1
011
000
297 0 warn 'Devel::Cover not available; fuzzing without coverage guidance.';
298 }
299  
300 1910 return $self;
301 }
302  
303 =head2 run
304  
305 Run the coverage-guided fuzzing loop and return a summary report.
306  
307 my $report = $fuzzer->run();
308 printf "Branches covered: %d\n", $report->{branches_covered};
309 printf "Bugs found: %d\n", $report->{bugs_found};
310  
311 =head3 Arguments
312  
313 None beyond C<$self>.
314  
315 =head3 Returns
316  
317 A hashref with keys C<total_iterations>, C<interesting_inputs>,
318 C<corpus_size>, C<branches_covered>, C<bugs_found>, and C<bugs>.
319  
320 The numbers are totals for the life of the object. If you call C<run>
321 twice, C<total_iterations> is twice the C<iterations> value.
322  
323 =head3 Side effects
324  
325 Calls C<target_sub> once per iteration. Adds five new random inputs to
326 the corpus at the start of every call. Uses C<alarm> and the C<ALRM>
327 signal for the timeout, so any alarm that your own program had set is
328 cancelled.
329  
330 =head3 Notes
331  
332 A call that takes longer than C<timeout> seconds is stopped and recorded
333 as a bug with the error C<target_sub timed out after Ns>.
334  
335 The same failing input can be recorded more than once. The C<bugs> list
336 is not checked for duplicates.
337  
338 A C<target_sub> call that dies is only recorded in C<bugs> when the
339 input that triggered it is valid per C<schema>. A die triggered by an
340 input the schema itself marks invalid (e.g. out of the declared
341 C<min>/C<max> range) is expected behaviour, not a bug, and is silently
342 discarded.
343  
344 =head3 API SPECIFICATION
345  
346 =head4 input
347  
348 {
349 self => { type => OBJECT, isa => 'App::Test::Generator::CoverageGuidedFuzzer' },
350 }
351  
352 =head4 output
353  
354 {
355 type => HASHREF,
356 keys => {
357 total_iterations => { type => SCALAR },
358 interesting_inputs => { type => SCALAR },
359 corpus_size => { type => SCALAR },
360 branches_covered => { type => SCALAR },
361 bugs_found => { type => SCALAR },
362 bugs => { type => ARRAYREF },
363 },
364 }
365  
366 =head3 EXAMPLE
367  
368 my $report = $fuzzer->run();
369 printf "Iterations: %d\n", $report->{total_iterations};
370 printf "Corpus size: %d\n", $report->{corpus_size};
371 printf "Bugs found: %d\n", $report->{bugs_found};
372 for my $bug (@{ $report->{bugs} }) {
373 printf " input=%s error=%s\n", $bug->{input}, $bug->{error};
374 }
375  
376 The mathematical description is in L</FORMAL SPECIFICATION>.
377  
378 =head3 PSEUDOCODE
379  
380 seed corpus with SEED_CORPUS_SIZE random inputs
381 for i in 1..iterations:
382 if corpus non-empty and rand < CORPUS_MUTATE_RATIO:
383 input = mutate(random corpus entry)
384 else:
385 input = generate_random()
386 run target_sub(input), record coverage and bugs
387 return report hashref
388  
389 =cut
390  
391 76 ▶sub run {
Subroutine run: called CC=4 SCAR=13.9
Pod documented
392 76 my ($self) = @_;
393  
394 # Phase 1: seed the corpus with a small set of random inputs
395 76 $self->_seed_corpus();
396  
397 # Phase 2: main fuzzing loop — alternate between mutation and exploration
398 76 for my $i (1 .. $self->{iterations}) {
399 727 my $input;
400  
401 727 ▶ if(@{ $self->{corpus} } && rand() < $CORPUS_MUTATE_RATIO) {
Branch: 1 branch
BranchTrueFalseTotal
if (@{$self->{'corpus'};} and rand() < $CORPUS_MUTATE_RATIO) { } 513 214 727
Condition66%2/3
@{$self->{"corpus"};} and rand() < $CORPUS_MUTATE_RATIO
!ll&&!rl&&r
0214513
MC/DC50%1/2
@{$self->{"corpus"};} and rand() < $CORPUS_MUTATE_RATIO
@{$self->{"corpus"};} rand() < $CORPUS_MUTATE_RATIO
Truth table66%2/3
A and B
A= @{$self->{"corpus"};}B= rand() < $CORPUS_MUTATE_RATIO
ABresult
0X0
100
111
402 # Mutate a randomly chosen corpus entry
403 513 my $parent = $self->{corpus}[ int(rand(@{ $self->{corpus} })) ];
404 513 $input = $self->_mutate($parent->{input});
405 } else {
406 # Fresh random generation for exploration
407 214 $input = $self->_generate_random();
408 }
409  
410 727 $self->_run_one($input);
411 727 $self->{stats}{total}++;
412 }
413  
414 76 $self->{stats}{coverage} = scalar keys %{ $self->{covered} };
415 76 return $self->_build_report();
416 }
417  
418 =head2 corpus
419  
420 Return the accumulated corpus as an arrayref of hashrefs with keys
421 C<input> and C<coverage>.
422  
423 my $corpus = $fuzzer->corpus();
424  
425 The arrayref is the fuzzer's own list, not a copy. Do not change it.
426 The list is empty until C<run> or C<load_corpus> has been called.
427  
428 =head3 API SPECIFICATION
429  
430 =head4 input
431  
432 { self => { type => OBJECT, isa => 'App::Test::Generator::CoverageGuidedFuzzer' } }
433  
434 =head4 output
435  
436 { type => ARRAYREF }
437  
438 =head3 EXAMPLE
439  
440 my $corpus = $fuzzer->corpus();
441 printf "%d entries in corpus\n", scalar @{$corpus};
442 # Each entry: { input => ..., coverage => { 'file:line:branch' => 1, ... } }
443  
444 =cut
445  
446 52 ▶sub corpus { $_[0]->{corpus} }
Subroutine corpus: called CC=1 SCAR=0.0
Pod documented
447  
448 =head2 bugs
449  
450 Return bugs found as an arrayref of hashrefs with keys C<input> and
451 C<error>.
452  
453 my $bugs = $fuzzer->bugs();
454  
455 The arrayref is the fuzzer's own list, not a copy. Do not change it.
456 C<error> is always text. C<input> can be C<undef>.
457  
458 =head3 API SPECIFICATION
459  
460 =head4 input
461  
462 { self => { type => OBJECT, isa => 'App::Test::Generator::CoverageGuidedFuzzer' } }
463  
464 =head4 output
465  
466 { type => ARRAYREF }
467  
468 =head3 EXAMPLE
469  
470 my $bugs = $fuzzer->bugs();
471 for my $b (@{$bugs}) {
472 printf "Bug: input=%s error=%s\n", $b->{input}, $b->{error};
473 }
474  
475 =cut
476  
477 19 ▶sub bugs { $_[0]->{bugs} }
Subroutine bugs: called CC=1 SCAR=0.0
Pod documented
478  
479 =head2 save_corpus
480  
481 Serialise the corpus to a JSON file for replay or extension on future
482 runs.
483  
484 $fuzzer->save_corpus('t/corpus/validate.json');
485  
486 =head3 Arguments
487  
488 =over 4
489  
490 =item * C<$path>
491  
492 Path to write the JSON corpus file. Required.
493  
494 =back
495  
496 =head3 Returns
497  
498 Nothing useful. Croaks if the file cannot be written or no JSON module is
499 available.
500  
501 =head3 Side effects
502  
503 Writes a JSON file to C<$path>. An existing file is replaced.
504 The file holds the seed, the corpus inputs and the bugs.
505 Branch data is not saved. The file is UTF-8.
506  
507 =head3 API SPECIFICATION
508  
509 =head4 input
510  
511 {
512 self => { type => OBJECT, isa => 'App::Test::Generator::CoverageGuidedFuzzer' },
513 path => { type => SCALAR },
514 }
515  
516 =head4 output
517  
518 { type => UNDEF }
519  
520 =head3 EXAMPLE
521  
522 $fuzzer->run();
523 $fuzzer->minimize_corpus();
524 $fuzzer->save_corpus('t/corpus/my_func.json');
525  
526 =head3 MESSAGES
527  
528 =over 4
529  
530 =item C<path required>
531  
532 No path argument was supplied.
533  
534 =item C<Cannot write corpus to $path: $!>
535  
536 The file could not be opened for writing (permissions, missing directory, etc.).
537  
538 =item C<No JSON module available; install JSON or JSON::MaybeXS>
539  
540 Neither C<JSON::MaybeXS> nor C<JSON> is installed.
541  
542 =item C<encountered object ...> or C<encountered CODE ...>
543  
544 Raised by the JSON module. A corpus input or bug input holds an object
545 or a code reference, which JSON cannot store. This check happens after
546 the file has been opened, so the file is left empty.
547  
548 =back
549  
550 The mathematical description is in L</FORMAL SPECIFICATION>.
551  
552 =cut
553  
554 26 ▶sub save_corpus {
Subroutine save_corpus: called CC=3 SCAR=11.0
Pod documented
555 26 my ($self, $path) = @_;
556  
557 26 ▶ croak 'path required' unless defined $path;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $path 3 23 26
558  
559 23 my $json = _load_json_module();
560  
561 23 ▶ open my $fh, '>:raw', $path
Branch: 1 branch
BranchTrueFalseTotal
open my $fh, ">:raw", $path or croak("Cannot write corpus to ${path}: $!") 19 4 23
562 or croak "Cannot write corpus to $path: $!";
563  
564 print $fh $json->new->utf8->pretty->encode({
565 seed => $self->{seed},
566 194 corpus => [ map { { input => $_->{input} } } @{ $self->{corpus} } ],
567 bugs => $self->{bugs},
568 19 });
569  
570 19 close $fh;
571 }
572  
573 =head2 load_corpus
574  
575 Load a previously saved corpus JSON file, pre-seeding the fuzzer so
576 it continues from where it left off.
577  
578 $fuzzer->load_corpus('t/corpus/validate.json');
579  
580 =head3 Arguments
581  
582 =over 4
583  
584 =item * C<$path>
585  
586 Path to the JSON corpus file to load. Required.
587  
588 =back
589  
590 =head3 Returns
591  
592 Nothing useful. Croaks if the file cannot be read or no JSON module is
593 available.
594  
595 =head3 Side effects
596  
597 Appends loaded entries to C<< $self->{corpus} >>. Entries already in the
598 corpus are kept, so loading the same file twice gives every entry twice.
599 C<minimize_corpus> removes such copies.
600  
601 =head3 API SPECIFICATION
602  
603 =head4 input
604  
605 {
606 self => { type => OBJECT, isa => 'App::Test::Generator::CoverageGuidedFuzzer' },
607 path => { type => SCALAR },
608 }
609  
610 =head4 output
611  
612 { type => UNDEF }
613  
614 =head3 EXAMPLE
615  
616 my $fuzzer2 = App::Test::Generator::CoverageGuidedFuzzer->new(
617 schema => $schema,
618 target_sub => \&My::Module::validate,
619 );
620 $fuzzer2->load_corpus('t/corpus/my_func.json');
621 my $report = $fuzzer2->run();
622  
623 =head3 MESSAGES
624  
625 =over 4
626  
627 =item C<path required>
628  
629 No path argument was supplied.
630  
631 =item C<Cannot read corpus from $path: $!>
632  
633 The file could not be opened for reading (missing file, permissions, etc.).
634  
635 =item C<malformed JSON string ...> and similar
636  
637 Raised by the JSON module. The file is not valid JSON.
638  
639 =back
640  
641 =head3 Notes
642  
643 C<load_corpus> does B<not> restore C<bugs> from the JSON file.
644 The C<bugs> array in the JSON is written by C<save_corpus> but ignored on load.
645 The loaded fuzzer starts with an empty C<bugs> list. Seed values are also not
646 restored; the constructor-supplied seed is retained.
647  
648 The mathematical description is in L</FORMAL SPECIFICATION>.
649  
650 =cut
651  
652 23 ▶sub load_corpus {
Subroutine load_corpus: called CC=6 SCAR=17.9
Pod documented
653 23 my ($self, $path) = @_;
654  
655 23 ▶ croak 'path required' unless defined $path;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $path 3 20 23
656  
657 20 my $json = _load_json_module();
658  
659 20 ▶ open my $fh, '<:raw', $path
Branch: 1 branch
BranchTrueFalseTotal
open my $fh, "<:raw", $path or croak("Cannot read corpus from ${path}: $!") 15 5 20
660 or croak "Cannot read corpus from $path: $!";
661  
662 15 my $text = do { local $/; <$fh> };
663 15 close $fh;
664  
665 # Files written before 0.48 hold Latin-1 bytes rather than UTF-8;
666 # those fail the UTF-8 decode and are read the old way instead.
667 15 ▶ my $data = eval { $json->new->utf8->decode($text) }
Condition100%3/3
eval { do { $json->new->utf8->decode($text) } } // $json->new->decode($text)
l!l&&r!l&&!r
1311
MC/DC0%0/2
eval { do { $json->new->utf8->decode($text) } } // $json->new->decode($text)
eval { do { $json->new->utf8->decode($text) } } $json->new->decode($text)
Truth table66%2/3
A // B
A= eval { do { $json->new->utf8->decode($text) } }B= $json->new->decode($text)
ABresult
1X1
011
000
668 // $json->new->decode($text);
669  
670 # Load corpus entries with empty coverage — coverage state from a
671 # previous process cannot be restored, only the inputs themselves
672 14 ▶ for my $entry (@{ $data->{corpus} // [] }) {
Condition50%1/2
$data->{"corpus"} // []
l!l
140
MC/DC0%0/1
$data->{"corpus"} // []
$data->{"corpus"}
Truth table50%1/2
A
A= $data->{"corpus"}
Aresult
11
00
673 126 push @{ $self->{corpus} }, {
674 input => $entry->{input},
675 126 coverage => {},
676 };
677 }
678 }
679  
680 =head2 minimize_corpus
681  
682 Reduce the corpus to the smallest subset that still covers every
683 branch hit by the full corpus, using a greedy set-cover algorithm.
684  
685 Entries without branch data (loaded from a previous run, or kept by
686 random sampling when Devel::Cover is unavailable) are deduplicated by
687 input fingerprint and retained in full. They cannot be evaluated for
688 coverage contribution without re-running them. Bug-triggering inputs
689 are always kept regardless of coverage contribution.
690  
691 my $stats = $fuzzer->minimize_corpus();
692 printf "Corpus: %d -> %d entries (%d branches covered)\n",
693 $stats->{before}, $stats->{after}, $stats->{branches};
694  
695 =head3 Returns
696  
697 A hashref with keys C<before> (corpus size before), C<after> (corpus
698 size after), and C<branches> (total unique branches still covered).
699  
700 =head3 API SPECIFICATION
701  
702 =head4 input
703  
704 { self => { type => OBJECT, isa => 'App::Test::Generator::CoverageGuidedFuzzer' } }
705  
706 =head4 output
707  
708 {
709 type => HASHREF,
710 constraint => sub { defined $_[0]{before} && defined $_[0]{after} && defined $_[0]{branches} },
711 }
712  
713 =head3 EXAMPLE
714  
715 $fuzzer->run();
716 my $stats = $fuzzer->minimize_corpus();
717 printf "Corpus: %d -> %d entries (%d branches)\n",
718 $stats->{before}, $stats->{after}, $stats->{branches};
719 $fuzzer->save_corpus('t/corpus/my_func.json');
720  
721 The mathematical description is in L</FORMAL SPECIFICATION>.
722  
723 =head3 PSEUDOCODE
724  
725 partition corpus into with-coverage and without-coverage entries
726 greedy set-cover: repeatedly pick entry covering most uncovered branches
727 deduplicate without-coverage entries by JSON fingerprint
728 unconditionally add all bug inputs not already in minimized set
729 replace self.corpus with minimized list
730 return { before, after, branches }
731  
732 =cut
733  
734 24 ▶sub minimize_corpus {
Subroutine minimize_corpus: called CC=12 SCAR=24.9
Pod documented
735 24 my ($self) = @_;
736  
737 24 my @all = @{ $self->{corpus} };
738 24 my $before = scalar @all;
739  
740 24 my @with_cov = grep { %{ $_->{coverage} } } @all;
741 24 my @without_cov = grep { !%{ $_->{coverage} } } @all;
742  
743 # Greedy set-cover: find the smallest subset of with-coverage entries
744 # that still covers every branch seen across the whole corpus.
745 24 my %uncovered;
746 24 $uncovered{$_} = 1 for map { keys %{ $_->{coverage} } } @with_cov;
747 24 my $total_branches = scalar keys %uncovered;
748  
749 24 my @selected;
750 24 ▶ while (%uncovered && @with_cov) {
Branch: 1 branch
BranchTrueFalseTotal
if (%uncovered and @with_cov) 27 24 51
Condition66%2/3
%uncovered and @with_cov
!ll&&!rl&&r
24027
MC/DC50%1/2
%uncovered and @with_cov
%uncovered @with_cov
Truth table66%2/3
A and B
A= %uncoveredB= @with_cov
ABresult
0X0
100
111
751 27 my ($best, $best_idx, $best_n) = (undef, -1, 0);
752 27 for my $i (0 .. $#with_cov) {
753 52 my $n = grep { $uncovered{$_} } keys %{ $with_cov[$i]{coverage} };
754 52 ▶ if ($n > $best_n) {
Branch: 1 branch
BranchTrueFalseTotal
if ($n > $best_n) 28 24 52
755 28 $best_n = $n;
756 28 $best_idx = $i;
757 28 $best = $with_cov[$i];
758 }
759 }
760 27 ▶ last unless $best_n;
Branch: 1 branch
BranchTrueFalseTotal
unless $best_n 0 27 27
761  
762 27 push @selected, $best;
763 27 splice @with_cov, $best_idx, 1;
764 27 delete $uncovered{$_} for keys %{ $best->{coverage} };
765 }
766  
767 # Deduplicate no-coverage entries by input fingerprint so that repeated
768 # loads of the same corpus file do not cause the entry count to grow.
769 24 my %seen;
770 my @deduped;
771 24 for my $entry (@without_cov) {
772 89 my $key = _fingerprint($entry->{input});
773 89 ▶ next if $seen{$key}++;
Branch: 1 branch
BranchTrueFalseTotal
if $seen{$key}++ 11 78 89
774 78 push @deduped, $entry;
775 }
776  
777 24 my @minimized = (@selected, @deduped);
778  
779 # Bug-triggering inputs are always kept — they are the most valuable
780 # findings regardless of whether they add unique branch coverage.
781 24 my %kept = map { _fingerprint($_->{input}) => 1 } @minimized;
782 24 for my $bug (@{ $self->{bugs} }) {
783 59 my $key = _fingerprint($bug->{input});
784 59 ▶ unless ($kept{$key}++) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($kept{$key}++) 29 30 59
785 29 push @minimized, { input => $bug->{input}, coverage => {} };
786 }
787 }
788  
789 24 $self->{corpus} = \@minimized;
790  
791 return {
792 24 before => $before,
793 after => scalar @minimized,
794 branches => $total_branches,
795 };
796 }
797  
798 # --------------------------------------------------
799 # _fingerprint
800 #
801 # Purpose: Produce a stable, canonical string key
802 # for an arbitrary Perl value, for use as
803 # a deduplication key.
804 #
805 # Entry: $val - any Perl value (scalar, ref, undef).
806 # Exit: Returns a deterministic string.
807 # Side effects: None.
808 #
809 # Notes: Uses the JSON module in canonical mode so
810 # hash keys are always sorted. Avoids
811 # Data::Dumper whose output includes blessed
812 # class names that vary across Perl versions.
813 # --------------------------------------------------
814 253 ▶sub _fingerprint {
Subroutine _fingerprint: called CC=4 SCAR=13.9
815 253 my ($val) = @_;
816 253 ▶ return 'null' unless defined $val;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $val 13 240 253
817 240 state $encoder;
818 240 ▶ unless ($encoder) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($encoder) 5 235 240
819 5 my $mod = _load_json_module();
820 5 $encoder = eval { $mod->new->canonical(1) };
821 }
822 240 ▶ return eval { $encoder->encode($val) } // "$val";
Condition50%1/2
eval { do { $encoder->encode($val) } } // "$val"
l!l
2400
MC/DC0%0/1
eval { do { $encoder->encode($val) } } // "$val"
eval { do { $encoder->encode($val) } }
Truth table50%1/2
A
A= eval { do { $encoder->encode($val) } }
Aresult
11
00
823 }
824  
825 # --------------------------------------------------
826 # _load_json_module
827 #
828 # Find and load the first available JSON
829 # module from the preference list.
830 #
831 # Entry: None.
832 # Exit: Returns the name of the loaded module.
833 # Croaks if none are available.
834 #
835 # Side effects: Loads a JSON module into the process.
836 #
837 # Notes: Uses explicit require rather than string
838 # eval for safety. JSON::MaybeXS is
839 # preferred over JSON.
840 # --------------------------------------------------
841 50 ▶sub _load_json_module {
Subroutine _load_json_module: called CC=4 SCAR=14.0
842 50 state $cached;
843 50 ▶ return $cached if defined $cached;
Branch: 1 branch
BranchTrueFalseTotal
if defined $cached 39 11 50
844 11 for my $mod (@JSON_MODULES) {
845 # Convert package name to file path — require $var does not
846 # do the :: -> / conversion that bareword require does
847 11 (my $file = $mod) =~ s{::}{/}g;
848 11 $file .= '.pm';
849 11 ▶ if (eval { require $file; 1 }) {
Branch: 1 branch
BranchTrueFalseTotal
if (eval { do { require $file; 1 } }) 11 0 11
850 11 return $cached = $mod;
851 }
852 }
853 0 croak 'No JSON module available; install JSON or JSON::MaybeXS';
854 }
855  
856 # --------------------------------------------------
857 # _run_one
858 #
859 # Run the target sub with a single input,
860 # record coverage, detect bugs, and update
861 # the corpus if the input is interesting.
862 #
863 # Entry: $input - the value to pass to target_sub.
864 #
865 # Exit: Returns nothing. Updates $self->{corpus},
866 # $self->{bugs}, and $self->{covered}.
867 #
868 # Side effects: Calls target_sub. May update corpus
869 # and covered hashes.
870 #
871 # Notes: When Devel::Cover is available, coverage
872 # is captured via _run_with_cover.
873 # Unexpected warnings are treated as soft
874 # bugs if they match known warning patterns.
875 # --------------------------------------------------
876 728 ▶sub _run_one {
Subroutine _run_one: called CC=5 SCAR=16.1
877 728 my ($self, $input) = @_;
878  
879 728 my ($result, $error, $coverage);
880  
881 728 ▶ if($self->{_cover_available}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->{'_cover_available'}) { } 725 3 728
882 725 $coverage = $self->_run_with_cover($input, \$result, \$error);
883 } else {
884 3 $coverage = {};
885 3 ($result, $error) = $self->_call_target($input);
886 }
887  
888 # Record bugs — only when the input was valid per the schema.
889 # A die on invalid input is correct behaviour, not a bug.
890 728 ▶ if($error && $self->_input_is_valid($input)) {
Branch: 1 branch
BranchTrueFalseTotal
if ($error and $self->_input_is_valid($input)) 189 539 728
Condition100%3/3
$error and $self->_input_is_valid($input)
!ll&&!rl&&r
49544189
MC/DC100%2/2
$error and $self->_input_is_valid($input)
$error $self->_input_is_valid($input)
Truth table100%3/3
A and B
A= $errorB= $self->_input_is_valid($input)
ABresult
0X0
100
111
891 189 push @{ $self->{bugs} }, { input => $input, error => "$error" };
892 189 $self->{stats}{bugs}++;
893 }
894  
895 # Keep the input in the corpus if it exercised new branches
896 728 ▶ if($self->_is_interesting($coverage)) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->_is_interesting($coverage)) 308 420 728
897 308 push @{ $self->{corpus} }, { input => $input, coverage => $coverage };
898 308 $self->_update_covered($coverage);
899 308 $self->{stats}{interesting}++;
900 }
901 }
902  
903 # --------------------------------------------------
904 # _call_target
905 #
906 # Purpose: Call the target sub once with a single
907 # input, bounded by the timeout.
908 #
909 # Entry: $input - value to pass to target_sub.
910 #
911 # Exit: Returns ($result, $error). $error is undef
912 # when the call neither died nor warned in
913 # a way that counts as a soft bug.
914 #
915 # Side effects: Calls target_sub. Uses alarm().
916 #
917 # Notes: A hanging target_sub would otherwise hang
918 # the whole fuzzing run; alarm() bounds it
919 # and surfaces the timeout as an error.
920 # --------------------------------------------------
921 729 ▶sub _call_target {
Subroutine _call_target: called CC=8 SCAR=20.8
922 729 my ($self, $input) = @_;
923  
924 # Include instance as invocant for method calls
925 my @call_args = defined($self->{instance})
926 729 ▶ ? ($self->{instance}, $input)
Branch: 1 branch
BranchTrueFalseTotal
defined $self->{'instance'} ? : 3 726 729
927 : ($input);
928  
929 729 my ($result, $error, @warnings);
930 729 eval {
931 729 ▶ local $SIG{__WARN__} = sub { push @warnings, @_ };
Subroutine __ANON__: called CC=1 SCAR=0.0
932 729 local $SIG{__DIE__};
933 729 ▶ local $SIG{ALRM} = sub { die "target_sub timed out after $self->{timeout}s\n" };
Subroutine __ANON__: called CC=1 SCAR=0.0
934 729 ▶ alarm($self->{timeout}) if $self->{timeout};
Branch: 1 branch
BranchTrueFalseTotal
if $self->{"timeout"} 606 123 729
935 729 $result = $self->{target_sub}->(@call_args);
936 };
937 729 ▶ alarm(0) if $self->{timeout};
Branch: 1 branch
BranchTrueFalseTotal
if $self->{"timeout"} 606 123 729
938 729 ▶ $error = $@ if $@;
Branch: 1 branch
BranchTrueFalseTotal
if $@ 227 502 729
939  
940 729 ▶ if(!defined($error) && @warnings) {
Branch: 1 branch
BranchTrueFalseTotal
if (not defined $error and @warnings) 14 715 729
Condition100%3/3
not defined $error and @warnings
!ll&&!rl&&r
22748814
MC/DC100%2/2
not defined $error and @warnings
not defined $error @warnings
Truth table100%3/3
not(A) and B
A= not defined $errorB= @warnings
ABresult
0X0
100
111
941 14 my $w = join '', @warnings;
942 14 ▶ $error = "warning: $w" if $w =~ $SOFT_BUG_WARNING_RE;
Branch: 1 branch
BranchTrueFalseTotal
if $w =~ /$SOFT_BUG_WARNING_RE/ 6 8 14
943 }
944  
945 729 return ($result, $error);
946 }
947  
948 # --------------------------------------------------
949 # _run_with_cover
950 #
951 # Purpose: Run the target sub with Devel::Cover
952 # active and return the set of newly hit
953 # branches as a hashref.
954 #
955 # Entry: $input - value to pass to target_sub.
956 # $result_ref - scalar ref to store result.
957 # $error_ref - scalar ref to store error.
958 #
959 # Exit: Returns a hashref of newly hit branch
960 # keys ("file:line:branch").
961 #
962 # Side effects: Calls Devel::Cover::start/stop.
963 # Sets $$result_ref and $$error_ref.
964 #
965 # Notes: Snapshot comparison is imprecise for
966 # concurrent use but correct for single-
967 # threaded fuzzing. Instance is passed
968 # as invocant when set. Devel::Cover state
969 # only grows, so this iteration's "before"
970 # is exactly the previous iteration's
971 # "after" -- cached in $self to avoid two
972 # full Devel::Cover walks per iteration.
973 # --------------------------------------------------
974 726 ▶sub _run_with_cover {
Subroutine _run_with_cover: called CC=7 SCAR=19.5
975 726 my ($self, $input, $result_ref, $error_ref) = @_;
976  
977 726 ▶ Devel::Cover::start() if Devel::Cover->can('start');
Branch: 1 branch
BranchTrueFalseTotal
if "Devel::Cover"->can("start") 0 726 726
978  
979 726 ▶ my $before_ref = $self->{_last_cover_snapshot} || {};
Condition100%2/2
$self->{'_last_cover_snapshot'} || {}
l!l
65967
MC/DC100%1/1
$self->{'_last_cover_snapshot'} || {}
$self->{'_last_cover_snapshot'}
Truth table100%2/2
A
A= $self->{'_last_cover_snapshot'}
Aresult
11
00
980 726 my %before = %{$before_ref};
981  
982 726 ($$result_ref, my $error) = $self->_call_target($input);
983 726 ▶ $$error_ref = $error if defined $error;
Branch: 1 branch
BranchTrueFalseTotal
if defined $error 230 496 726
984  
985 726 my $after = $self->_snapshot_cover();
986 726 $self->{_last_cover_snapshot} = $after;
987 726 ▶ Devel::Cover::stop() if Devel::Cover->can('stop');
Branch: 1 branch
BranchTrueFalseTotal
if "Devel::Cover"->can("stop") 0 726 726
988  
989 # Return only branches newly hit in this call
990 726 my %delta;
991 726 for my $key (keys %{$after}) {
992 430279 ▶ $delta{$key} = 1 unless exists $before{$key};
Branch: 1 branch
BranchTrueFalseTotal
unless exists $before{$key} 44255 386024 430279
993 }
994  
995 726 return \%delta;
996 }
997  
998 # --------------------------------------------------
999 # _snapshot_cover
1000 #
1001 # Purpose: Take a lightweight snapshot of the
1002 # currently hit branches from Devel::Cover.
1003 #
1004 # Entry: None beyond $self.
1005 # Exit: Returns a hashref of "criterion:op:slot" keys.
1006 #
1007 # Side effects: Reads Devel::Cover internal state.
1008 #
1009 # Notes: Falls back to empty hash if the
1010 # Devel::Cover API is not accessible.
1011 # All errors are silently swallowed since
1012 # coverage is best-effort.
1013 # --------------------------------------------------
1014 727 ▶sub _snapshot_cover {
Subroutine _snapshot_cover: called CC=9 SCAR=22.3
1015 727 my ($self) = @_;
1016 727 my %snap;
1017  
1018 727 eval {
1019 # coverage() is the XS accessor for the live counters. It only
1020 # exists when the program was started under Devel::Cover; a
1021 # late require leaves it undefined and nothing is collected.
1022 # (get_coverage() returns the criteria names, not the data.)
1023 727 ▶ return unless defined &Devel::Cover::coverage;
Branch: 1 branch
BranchTrueFalseTotal
unless defined &Devel::Cover::coverage 0 727 727
1024 727 ▶ my $cover = Devel::Cover::coverage(0) or return;
Branch: 1 branch
BranchTrueFalseTotal
my $cover = &Devel::Cover::coverage(0) or return 727 0 727
1025  
1026 727 for my $criterion (@COVER_CRITERIA) {
1027 1454 ▶ my $data = $cover->{$criterion} or next;
Branch: 1 branch
BranchTrueFalseTotal
my $data = $cover->{$criterion} or next 1454 0 1454
1028 1454 for my $key (keys %{$data}) {
1029 249381 my $counts = $data->{$key};
1030 249381 ▶ next unless ref($counts) eq 'ARRAY';
Branch: 1 branch
BranchTrueFalseTotal
unless ref $counts eq "ARRAY" 0 249381 249381
1031  
1032 # Keys are packed op addresses; hex keeps them printable
1033 249381 my $id = unpack('H*', $key);
1034 249381 for my $i (0 .. $#{$counts}) {
1035 1295312 ▶ $snap{"$criterion:$id:$i"} = 1 if $counts->[$i];
Branch: 1 branch
BranchTrueFalseTotal
if $counts->[$i] 430281 865031 1295312
1036 }
1037 }
1038 }
1039 };
1040  
1041 727 return \%snap;
1042 }
1043  
1044 # --------------------------------------------------
1045 # _is_interesting
1046 #
1047 # Purpose: Return true if the coverage hashref
1048 # contains any branch not yet in the
1049 # global covered set.
1050 #
1051 # Entry: $coverage - hashref of branch keys.
1052 # Exit: Returns 1 if interesting, 0 otherwise.
1053 #
1054 # Side effects: None.
1055 #
1056 # Notes: When no coverage data is available,
1057 # keeps a random sample of inputs at
1058 # RANDOM_KEEP_RATIO so the corpus still
1059 # grows even without branch feedback.
1060 # --------------------------------------------------
1061 731 ▶sub _is_interesting {
Subroutine _is_interesting: called CC=4 SCAR=13.9
1062 731 my ($self, $coverage) = @_;
1063  
1064 # Check for any newly covered branch
1065 731 for my $key (keys %{$coverage}) {
1066 166 ▶ return 1 unless $self->{covered}{$key};
Branch: 1 branch
BranchTrueFalseTotal
unless $self->{"covered"}{$key} 165 1 166
1067 }
1068  
1069 # No coverage data — keep a random sample to grow the corpus
1070 566 ▶ return rand() < $RANDOM_KEEP_RATIO unless %{$coverage};
Branch: 1 branch
BranchTrueFalseTotal
unless %{$coverage;} 565 1 566
1071  
1072 1 return 0;
1073 }
1074  
1075 # --------------------------------------------------
1076 # _update_covered
1077 #
1078 # Purpose: Merge newly covered branches into the
1079 # global covered set.
1080 #
1081 # Entry: $coverage - hashref of branch keys.
1082 # Exit: Returns nothing. Updates $self->{covered}.
1083 # Side effects: Modifies $self->{covered}.
1084 # --------------------------------------------------
1085 310 ▶sub _update_covered {
Subroutine _update_covered: called CC=2 SCAR=6.9
1086 310 my ($self, $coverage) = @_;
1087 310 $self->{covered}{$_} = 1 for keys %{$coverage};
1088 }
1089  
1090 # --------------------------------------------------
1091 # _generate_random
1092 #
1093 # Purpose: Generate a random input value from the
1094 # top-level schema input specification.
1095 #
1096 # Entry: None beyond $self.
1097 # Exit: Returns a randomly generated value.
1098 # Side effects: None.
1099 # --------------------------------------------------
1100 626 ▶sub _generate_random {
Subroutine _generate_random: called CC=1 SCAR=0.0
1101 626 my ($self) = @_;
1102 626 return $self->_generate_for_schema($self->{schema}{input});
1103 }
1104  
1105 # --------------------------------------------------
1106 # _generate_for_schema
1107 #
1108 # Purpose: Recursively generate a random value
1109 # matching a schema specification hashref.
1110 #
1111 # Entry: $spec - schema spec hashref or scalar
1112 # type hint.
1113 #
1114 # Exit: Returns a generated value appropriate
1115 # for the spec type, or undef if spec is
1116 # absent or 'undef'.
1117 #
1118 # Side effects: None.
1119 #
1120 # Notes: Edge cases declared in edge_case_array
1121 # are selected at EDGE_CASE_RATIO frequency
1122 # to bias toward known interesting values.
1123 # --------------------------------------------------
1124 1071 ▶sub _generate_for_schema {
Subroutine _generate_for_schema: called CC=13 SCAR=25.8
1125 1071 my ($self, $spec) = @_;
1126  
1127 1071 ▶ return undef unless defined $spec;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $spec 26 1045 1071
1128 1045 ▶ return undef if $spec eq 'undef';
Branch: 1 branch
BranchTrueFalseTotal
if $spec eq "undef" 1 1044 1045
1129  
1130 1044 ▶ my $type = ref($spec) ? ($spec->{type} // $TYPE_STRING) : $TYPE_STRING;
Branch: 1 branch
BranchTrueFalseTotal
ref $spec ? : 1044 0 1044
Condition100%3/3
$spec->{"type"} // $TYPE_STRING
l!l&&r!l&&!r
8302095
MC/DC100%2/2
$spec->{"type"} // $TYPE_STRING
$spec->{"type"} $TYPE_STRING
Truth table100%3/3
A // B
A= $spec->{"type"}B= $TYPE_STRING
ABresult
1X1
011
000
1131  
1132 # Bias toward declared edge cases at EDGE_CASE_RATIO frequency
1133 1044 ▶ if(ref($spec) && $spec->{edge_case_array} && rand() < $EDGE_CASE_RATIO) {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $spec and $spec->{"edge_case_array"} and rand() < $EDGE_CASE_RATIO) 6 1038 1044
Condition83%5/6
ref $spec and $spec->{"edge_case_array"} and rand() < $EDGE_CASE_RATIO
!ll&&!rl&&r
1024146
ref $spec and $spec->{"edge_case_array"}
!ll&&!rl&&r
0102420
MC/DC66%2/3
ref $spec and $spec->{"edge_case_array"} and rand() < $EDGE_CASE_RATIO
ref $spec $spec->{"edge_case_array"} rand() < $EDGE_CASE_RATIO
Truth table75%3/4
A and B and C
A= ref $specB= $spec->{"edge_case_array"}C= rand() < $EDGE_CASE_RATIO
ABCresult
0XX0
10X0
1100
1111
1134 6 my @ec = @{ $spec->{edge_case_array} };
1135 6 return $ec[ int(rand(@ec)) ];
1136 }
1137  
1138 # Dispatch to type-specific generator
1139 1038 ▶ if ($type eq $TYPE_INTEGER) { return $self->_rand_int($spec) }
Branch: 5 branches
BranchTrueFalseTotal
if ($type eq $TYPE_INTEGER) { } 451 587 1038
elsif ($type eq $TYPE_NUMBER) { } 0 587 587
elsif ($type eq $TYPE_BOOLEAN) { } 19 568 587
elsif ($type eq $TYPE_ARRAY) { } 7 561 568
elsif ($type eq $TYPE_HASH) { } 28 533 561
1140 0 elsif ($type eq $TYPE_NUMBER) { return $self->_rand_num($spec) }
1141 19 elsif ($type eq $TYPE_BOOLEAN) { return int(rand(2)) }
1142 7 elsif ($type eq $TYPE_ARRAY) { return $self->_rand_array($spec) }
1143 28 elsif ($type eq $TYPE_HASH) { return $self->_rand_hash($spec) }
1144 533 else { return $self->_rand_string($spec) }
1145 }
1146  
1147 # --------------------------------------------------
1148 # _rand_int
1149 #
1150 # Purpose: Generate a random integer within the
1151 # spec's min/max range, biased toward
1152 # boundary values at INT_BOUNDARY_RATIO.
1153 #
1154 # Entry: $spec - schema spec hashref.
1155 # Exit: Returns an integer scalar.
1156 # Side effects: None.
1157 # --------------------------------------------------
1158 491 ▶sub _rand_int {
Subroutine _rand_int: called CC=4 SCAR=13.9
1159 491 my ($self, $spec) = @_;
1160  
1161 491 ▶ my $min = $spec->{min} // $INT32_MIN;
Condition100%3/3
$spec->{"min"} // $INT32_MIN
l!l&&r!l&&!r
933962
MC/DC100%2/2
$spec->{"min"} // $INT32_MIN
$spec->{"min"} $INT32_MIN
Truth table100%3/3
A // B
A= $spec->{"min"}B= $INT32_MIN
ABresult
1X1
011
000
1162 491 ▶ my $max = $spec->{max} // $INT32_MAX;
Condition100%3/3
$spec->{"max"} // $INT32_MAX
l!l&&r!l&&!r
933962
MC/DC100%2/2
$spec->{"max"} // $INT32_MAX
$spec->{"max"} $INT32_MAX
Truth table100%3/3
A // B
A= $spec->{"max"}B= $INT32_MAX
ABresult
1X1
011
000
1163  
1164 # Bias toward boundary values to probe edge conditions
1165 491 ▶ if(rand() < $INT_BOUNDARY_RATIO) {
Branch: 1 branch
BranchTrueFalseTotal
if (rand() < $INT_BOUNDARY_RATIO) 159 332 491
1166 159 my @interesting = ($min, $min + 1, 0, -1, 1, $max - 1, $max);
1167 159 return $interesting[ int(rand(@interesting)) ];
1168 }
1169  
1170 332 return $min + int(rand($max - $min + 1));
1171 }
1172  
1173 # --------------------------------------------------
1174 # _rand_num
1175 #
1176 # Purpose: Generate a random floating point number
1177 # within the spec's min/max range.
1178 #
1179 # Entry: $spec - schema spec hashref.
1180 # Exit: Returns a numeric scalar.
1181 # Side effects: None.
1182 # --------------------------------------------------
1183 10 ▶sub _rand_num {
Subroutine _rand_num: called CC=3 SCAR=11.4
1184 10 my ($self, $spec) = @_;
1185  
1186 10 ▶ my $min = $spec->{min} // -1e9;
Condition50%1/2
$spec->{"min"} // "-1000000000"
l!l
100
MC/DC0%0/1
$spec->{"min"} // "-1000000000"
$spec->{"min"}
Truth table50%1/2
A
A= $spec->{"min"}
Aresult
11
00
1187 10 ▶ my $max = $spec->{max} // 1e9;
Condition50%1/2
$spec->{"max"} // "1000000000"
l!l
100
MC/DC0%0/1
$spec->{"max"} // "1000000000"
$spec->{"max"}
Truth table50%1/2
A
A= $spec->{"max"}
Aresult
11
00
1188  
1189 10 return $min + rand($max - $min);
1190 }
1191  
1192 # --------------------------------------------------
1193 # _rand_string
1194 #
1195 # Purpose: Generate a random string within the
1196 # spec's min/max length range, biased
1197 # toward boundary lengths.
1198 #
1199 # Entry: $spec - schema spec hashref.
1200 # Exit: Returns a string scalar.
1201 # Side effects: None.
1202 #
1203 # Notes: Character set includes control chars
1204 # and NUL to probe boundary handling.
1205 # --------------------------------------------------
1206 534 ▶sub _rand_string {
Subroutine _rand_string: called CC=5 SCAR=16.1
1207 534 my ($self, $spec) = @_;
1208  
1209 534 ▶ my $min_len = $spec->{min} // 0;
Condition100%2/2
$spec->{"min"} // 0
l!l
43491
MC/DC100%1/1
$spec->{"min"} // 0
$spec->{"min"}
Truth table100%2/2
A
A= $spec->{"min"}
Aresult
11
00
1210 534 ▶ my $max_len = $spec->{max} // $DEFAULT_MAX_STR_LEN;
Condition100%3/3
$spec->{"max"} // $DEFAULT_MAX_STR_LEN
l!l&&r!l&&!r
5746710
MC/DC100%2/2
$spec->{"max"} // $DEFAULT_MAX_STR_LEN
$spec->{"max"} $DEFAULT_MAX_STR_LEN
Truth table100%3/3
A // B
A= $spec->{"max"}B= $DEFAULT_MAX_STR_LEN
ABresult
1X1
011
000
1211  
1212 # Bias toward boundary lengths at STR_BOUNDARY_RATIO frequency
1213 534 my $len;
1214 534 ▶ if(rand() < $STR_BOUNDARY_RATIO) {
Branch: 1 branch
BranchTrueFalseTotal
if (rand() < $STR_BOUNDARY_RATIO) { } 83 451 534
1215 83 my @boundary_lens = ($min_len, $min_len + 1, $max_len - 1, $max_len);
1216 83 $len = $boundary_lens[ int(rand(@boundary_lens)) ];
1217 } else {
1218 451 $len = $min_len + int(rand($max_len - $min_len + 1));
1219 }
1220  
1221 # Clamp to non-negative
1222 534 ▶ $len = 0 if $len < 0;
Branch: 1 branch
BranchTrueFalseTotal
if $len < 0 0 534 534
1223  
1224 534 return join '', map { $RAND_CHARS[ int(rand(@RAND_CHARS)) ] } 1 .. $len;
1225 }
1226  
1227 # --------------------------------------------------
1228 # _rand_array
1229 #
1230 # Purpose: Generate a random arrayref with 0 to
1231 # DEFAULT_MAX_ARRAY elements, each
1232 # generated from the items spec.
1233 #
1234 # Entry: $spec - schema spec hashref.
1235 # Exit: Returns an arrayref.
1236 # Side effects: None.
1237 # --------------------------------------------------
1238 207 ▶sub _rand_array {
Subroutine _rand_array: called CC=2 SCAR=6.9
1239 207 my ($self, $spec) = @_;
1240  
1241 207 ▶ my $items = $spec->{items} // {};
Condition100%2/2
$spec->{"items"} // {}
l!l
2007
MC/DC100%1/1
$spec->{"items"} // {}
$spec->{"items"}
Truth table100%2/2
A
A= $spec->{"items"}
Aresult
11
00
1242 207 my $count = int(rand($DEFAULT_MAX_ARRAY + 1));
1243  
1244 207 return [ map { $self->_generate_for_schema($items) } 1 .. $count ];
1245 }
1246  
1247 # --------------------------------------------------
1248 # _rand_hash
1249 #
1250 # Purpose: Generate a random hashref with values
1251 # generated from the properties spec.
1252 #
1253 # Entry: $spec - schema spec hashref.
1254 # Exit: Returns a hashref.
1255 # Side effects: None.
1256 # --------------------------------------------------
1257 28 ▶sub _rand_hash {
Subroutine _rand_hash: called CC=3 SCAR=11.0
1258 28 my ($self, $spec) = @_;
1259  
1260 28 ▶ my $props = $spec->{properties} // {};
Condition100%2/2
$spec->{"properties"} // {}
l!l
199
MC/DC100%1/1
$spec->{"properties"} // {}
$spec->{"properties"}
Truth table100%2/2
A
A= $spec->{"properties"}
Aresult
11
00
1261 28 my %h;
1262  
1263 28 for my $key (keys %{$props}) {
1264 19 $h{$key} = $self->_generate_for_schema($props->{$key});
1265 }
1266  
1267 28 return \%h;
1268 }
1269  
1270 # --------------------------------------------------
1271 # _input_is_valid
1272 #
1273 # Purpose: Return true if the input satisfies all
1274 # constraints in the schema. Used to
1275 # distinguish real bugs (die on valid
1276 # input) from expected failures (die on
1277 # invalid input).
1278 #
1279 # Entry: $input - the value to validate.
1280 # Exit: Returns 1 if valid, 0 if not.
1281 # Returns 1 if no schema is available.
1282 # Side effects: None.
1283 # --------------------------------------------------
1284 246 ▶sub _input_is_valid {
Subroutine _input_is_valid: called CC=9 SCAR=22.0
1285 246 my ($self, $input) = @_;
1286  
1287 246 my $spec = $self->{schema}{input};
1288  
1289 # No schema means we cannot judge validity
1290 246 ▶ return 1 unless defined $spec && ref($spec);
Branch: 1 branch
BranchTrueFalseTotal
unless defined $spec and ref $spec 1 245 246
Condition66%2/3
defined $spec and ref $spec
!ll&&!rl&&r
10245
MC/DC50%1/2
defined $spec and ref $spec
defined $spec ref $spec
Truth table66%2/3
A and B
A= defined $specB= ref $spec
ABresult
0X0
100
111
1291  
1292 # A scalar 'type' makes $spec the description of one value. Without
1293 # it $spec is a map of named parameters, where a parameter may
1294 # itself be called 'type' (its spec is then a hashref).
1295 my $is_value_spec = ref($spec) eq 'HASH'
1296 245 ▶ && defined($spec->{type}) && !ref($spec->{type});
Condition83%5/6
ref $spec eq 'HASH' && defined $spec->{'type'} && !ref($spec->{'type'})
!ll&&!rl&&r
1133129
ref $spec eq "HASH" and defined $spec->{"type"}
!ll&&!rl&&r
0113132
MC/DC66%2/3
ref $spec eq 'HASH' && defined $spec->{'type'} && !ref($spec->{'type'})
ref $spec eq "HASH" defined $spec->{"type"} !ref($spec->{'type'})
Truth table75%3/4
A and B && not(C)
A= ref $spec eq "HASH"B= defined $spec->{"type"}C= !ref($spec->{'type'})
ABCresult
0XX0
10X0
1100
1111
1297  
1298 245 ▶ my $input_style = $self->{schema}{input_style} // '';
Condition100%2/2
$self->{"schema"}{"input_style"} // ""
l!l
2243
MC/DC100%1/1
$self->{"schema"}{"input_style"} // ""
$self->{"schema"}{"input_style"}
Truth table100%2/2
A
A= $self->{"schema"}{"input_style"}
Aresult
11
00
1299  
1300 245 ▶ if(!$is_value_spec && ($input_style eq 'hash' || ref($input) eq 'HASH')) {
Branch: 1 branch
BranchTrueFalseTotal
if (not $is_value_spec and $input_style eq "hash" || ref $input eq "HASH") 5 240 245
Condition100%6/6
not $is_value_spec and $input_style eq "hash" || ref $input eq "HASH"
!ll&&!rl&&r
1291115
$input_style eq "hash" or ref $input eq "HASH"
l!l&&r!l&&!r
23111
MC/DC100%3/3
not $is_value_spec and $input_style eq "hash" || ref $input eq "HASH"
not $is_value_spec $input_style eq "hash" ref $input eq "HASH"
Truth table100%4/4
not(A) and B or C
A= not $is_value_specB= $input_style eq "hash"C= ref $input eq "HASH"
ABCresult
0XX0
1000
11X1
1011
1301 5 return $self->_validate_hash_input($input, $spec);
1302 }
1303  
1304 240 return $self->_validate_value($input, $spec);
1305 }
1306  
1307 # --------------------------------------------------
1308 # _validate_hash_input
1309 #
1310 # Purpose: Validate a hash-style input against the
1311 # schema spec, checking each named field.
1312 #
1313 # Entry: $input - hashref of named parameters.
1314 # $spec - schema spec hashref.
1315 # Exit: Returns 1 if valid, 0 if not.
1316 # Side effects: None.
1317 # --------------------------------------------------
1318 60 ▶sub _validate_hash_input {
Subroutine _validate_hash_input: called CC=10 SCAR=23.1
1319 60 my ($self, $input, $spec) = @_;
1320  
1321 60 ▶ return 0 unless defined $input;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $input 2 58 60
1322  
1323 58 for my $key (keys %{$spec}) {
1324 # Skip internal metadata keys
1325 69 ▶ next if $key =~ /^_/;
Branch: 1 branch
BranchTrueFalseTotal
if $key =~ /^_/ 2 67 69
1326  
1327 67 my $field_spec = $spec->{$key};
1328 67 ▶ next unless ref($field_spec) eq 'HASH';
Branch: 1 branch
BranchTrueFalseTotal
unless ref $field_spec eq "HASH" 0 67 67
1329  
1330 67 ▶ my $value = ref($input) eq 'HASH' ? $input->{$key} : undef;
Branch: 1 branch
BranchTrueFalseTotal
ref $input eq 'HASH' ? : 67 0 67
1331  
1332 # Required field missing is always invalid
1333 67 ▶ if(!defined($value) && !$field_spec->{optional}) {
Branch: 1 branch
BranchTrueFalseTotal
unless (defined $value or $field_spec->{"optional"}) 5 62 67
Condition100%3/3
defined $value or $field_spec->{"optional"}
l!l&&r!l&&!r
5755
MC/DC100%2/2
defined $value or $field_spec->{"optional"}
defined $value $field_spec->{"optional"}
Truth table100%3/3
A or B
A= defined $valueB= $field_spec->{"optional"}
ABresult
1X1
011
000
1334 5 return 0;
1335 }
1336  
1337 62 ▶ next unless defined $value;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $value 5 57 62
1338  
1339 57 ▶ return 0 unless $self->_validate_value($value, $field_spec);
Branch: 1 branch
BranchTrueFalseTotal
unless $self->_validate_value($value, $field_spec) 22 35 57
1340 }
1341  
1342 31 return 1;
1343 }
1344  
1345 # --------------------------------------------------
1346 # _validate_value
1347 #
1348 # Purpose: Validate a single value against a schema
1349 # type spec, checking type and constraints.
1350 #
1351 # Entry: $value - the value to validate.
1352 # $spec - schema spec hashref.
1353 # Exit: Returns 1 if valid, 0 if not.
1354 # Side effects: None.
1355 #
1356 # Notes: Number validation accepts both integer
1357 # and floating point forms including
1358 # scientific notation. Type mismatch
1359 # always returns 0.
1360 # --------------------------------------------------
1361 337 ▶sub _validate_value {
Subroutine _validate_value: called CC=32 SCAR=35.2
1362 337 my ($self, $value, $spec) = @_;
1363  
1364 # Undef is never valid unless optional — caller already checked optional
1365 337 ▶ return 0 unless defined $value;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $value 2 335 337
1366  
1367 335 ▶ my $type = $spec->{type} // $TYPE_STRING;
Condition66%2/3
$spec->{"type"} // $TYPE_STRING
l!l&&r!l&&!r
2241110
MC/DC0%0/2
$spec->{"type"} // $TYPE_STRING
$spec->{"type"} $TYPE_STRING
Truth table66%2/3
A // B
A= $spec->{"type"}B= $TYPE_STRING
ABresult
1X1
011
000
1368  
1369 335 ▶ if($type eq $TYPE_INTEGER) {
Branch: 6 branches
BranchTrueFalseTotal
if ($type eq $TYPE_INTEGER) { } 96 239 335
elsif ($type eq $TYPE_NUMBER) { } 5 234 239
elsif ($type eq $TYPE_STRING) { } 176 58 234
elsif ($type eq $TYPE_BOOLEAN) { } 6 52 58
elsif ($type eq $TYPE_ARRAY or $type eq 'array') { } 4 48 52
elsif ($type eq $TYPE_HASH or $type eq 'hash') { } 48 0 48
1370 96 ▶ return 0 unless $value =~ /^-?\d+$/;
Branch: 1 branch
BranchTrueFalseTotal
unless $value =~ /^-?\d+$/ 4 92 96
1371 92 ▶ return 0 if defined($spec->{min}) && $value < $spec->{min};
Branch: 1 branch
BranchTrueFalseTotal
if defined $spec->{"min"} and $value < $spec->{"min"} 31 61 92
Condition100%3/3
defined $spec->{"min"} and $value < $spec->{"min"}
!ll&&!rl&&r
55631
MC/DC100%2/2
defined $spec->{"min"} and $value < $spec->{"min"}
defined $spec->{"min"} $value < $spec->{"min"}
Truth table100%3/3
A and B
A= defined $spec->{"min"}B= $value < $spec->{"min"}
ABresult
0X0
100
111
1372 61 ▶ return 0 if defined($spec->{max}) && $value > $spec->{max};
Branch: 1 branch
BranchTrueFalseTotal
if defined $spec->{"max"} and $value > $spec->{"max"} 12 49 61
Condition100%3/3
defined $spec->{"max"} and $value > $spec->{"max"}
!ll&&!rl&&r
74212
MC/DC100%2/2
defined $spec->{"max"} and $value > $spec->{"max"}
defined $spec->{"max"} $value > $spec->{"max"}
Truth table100%3/3
A and B
A= defined $spec->{"max"}B= $value > $spec->{"max"}
ABresult
0X0
100
111
1373 }
1374 elsif($type eq $TYPE_NUMBER) {
1375 # Accept integers, decimals, and scientific notation
1376 5 ▶ return 0 unless $value =~ /^-?(?:\d+\.?\d*|\.\d+)(?:[eE][+-]?\d+)?$/;
Branch: 1 branch
BranchTrueFalseTotal
unless $value =~ /^-?(?:\d+\.?\d*|\.\d+)(?:[eE][+-]?\d+)?$/ 1 4 5
1377 4 ▶ return 0 if defined($spec->{min}) && $value < $spec->{min};
Branch: 1 branch
BranchTrueFalseTotal
if defined $spec->{"min"} and $value < $spec->{"min"} 0 4 4
Condition33%1/3
defined $spec->{"min"} and $value < $spec->{"min"}
!ll&&!rl&&r
400
MC/DC0%0/2
defined $spec->{"min"} and $value < $spec->{"min"}
defined $spec->{"min"} $value < $spec->{"min"}
Truth table33%1/3
A and B
A= defined $spec->{"min"}B= $value < $spec->{"min"}
ABresult
0X0
100
111
1378 4 ▶ return 0 if defined($spec->{max}) && $value > $spec->{max};
Branch: 1 branch
BranchTrueFalseTotal
if defined $spec->{"max"} and $value > $spec->{"max"} 0 4 4
Condition33%1/3
defined $spec->{"max"} and $value > $spec->{"max"}
!ll&&!rl&&r
400
MC/DC0%0/2
defined $spec->{"max"} and $value > $spec->{"max"}
defined $spec->{"max"} $value > $spec->{"max"}
Truth table33%1/3
A and B
A= defined $spec->{"max"}B= $value > $spec->{"max"}
ABresult
0X0
100
111
1379 }
1380 elsif($type eq $TYPE_STRING) {
1381 176 my $len = length($value);
1382 176 ▶ return 0 if defined($spec->{min}) && $len < $spec->{min};
Branch: 1 branch
BranchTrueFalseTotal
if defined $spec->{"min"} and $len < $spec->{"min"} 2 174 176
Condition100%3/3
defined $spec->{"min"} and $len < $spec->{"min"}
!ll&&!rl&&r
147272
MC/DC100%2/2
defined $spec->{"min"} and $len < $spec->{"min"}
defined $spec->{"min"} $len < $spec->{"min"}
Truth table100%3/3
A and B
A= defined $spec->{"min"}B= $len < $spec->{"min"}
ABresult
0X0
100
111
1383 174 ▶ return 0 if defined($spec->{max}) && $len > $spec->{max};
Branch: 1 branch
BranchTrueFalseTotal
if defined $spec->{"max"} and $len > $spec->{"max"} 8 166 174
Condition100%3/3
defined $spec->{"max"} and $len > $spec->{"max"}
!ll&&!rl&&r
139278
MC/DC100%2/2
defined $spec->{"max"} and $len > $spec->{"max"}
defined $spec->{"max"} $len > $spec->{"max"}
Truth table100%3/3
A and B
A= defined $spec->{"max"}B= $len > $spec->{"max"}
ABresult
0X0
100
111
1384 166 ▶ if(defined($spec->{matches})) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $spec->{"matches"}) 5 161 166
1385 5 (my $pat = $spec->{matches}) =~ s{^/(.+)/$}{$1};
1386  
1387 # ReDoS guard: a schema-supplied pattern matched against
1388 # fuzzer-generated (attacker-shaped) input could exhibit
1389 # catastrophic backtracking. Bound the match with alarm()
1390 # the same way target_sub calls are bounded elsewhere in
1391 # this module, and treat a timeout as a non-match.
1392 5 my $matched = eval {
1393 0 ▶ local $SIG{ALRM} = sub { die "matches regex timed out\n" };
Subroutine __ANON__: not called CC=1 SCAR=1.2
1394 5 alarm($MATCHES_REGEX_TIMEOUT_SECS);
1395 5 my $m = $value =~ /$pat/;
1396 5 alarm(0);
1397 5 $m;
1398 };
1399 5 alarm(0);
1400 5 ▶ return 0 unless $matched;
Branch: 1 branch
BranchTrueFalseTotal
unless $matched 3 2 5
1401 }
1402 }
1403 elsif($type eq $TYPE_BOOLEAN) {
1404 6 ▶ return 0 unless $value =~ /^[01]$/;
Branch: 1 branch
BranchTrueFalseTotal
unless $value =~ /^[01]$/ 3 3 6
1405 }
1406 ▶ elsif($type eq $TYPE_ARRAY || $type eq 'array') {
Condition66%2/3
$type eq $TYPE_ARRAY or $type eq "array"
l!l&&r!l&&!r
4048
MC/DC50%1/2
$type eq $TYPE_ARRAY or $type eq "array"
$type eq $TYPE_ARRAY $type eq "array"
Truth table66%2/3
A or B
A= $type eq $TYPE_ARRAYB= $type eq "array"
ABresult
1X1
011
000
1407 4 ▶ return 0 unless ref($value) eq 'ARRAY';
Branch: 1 branch
BranchTrueFalseTotal
unless ref $value eq "ARRAY" 2 2 4
1408 }
1409 ▶ elsif($type eq $TYPE_HASH || $type eq 'hash') {
Condition33%1/3
$type eq $TYPE_HASH or $type eq "hash"
l!l&&r!l&&!r
4800
MC/DC0%0/2
$type eq $TYPE_HASH or $type eq "hash"
$type eq $TYPE_HASH $type eq "hash"
Truth table33%1/3
A or B
A= $type eq $TYPE_HASHB= $type eq "hash"
ABresult
1X1
011
000
1410 48 ▶ return 0 unless ref($value) eq 'HASH';
Branch: 1 branch
BranchTrueFalseTotal
unless ref $value eq "HASH" 2 46 48
1411 46 ▶ if(ref($spec->{properties}) eq 'HASH') {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $spec->{"properties"} eq "HASH") 44 2 46
1412 44 ▶ return 0 unless $self->_validate_hash_input($value, $spec->{properties});
Branch: 1 branch
BranchTrueFalseTotal
unless $self->_validate_hash_input($value, $spec->{"properties"}) 20 24 44
1413 }
1414 }
1415  
1416 247 return 1;
1417 }
1418  
1419 # --------------------------------------------------
1420 # _mutate
1421 #
1422 # Purpose: Apply a random mutation to an input
1423 # value, dispatching on its type.
1424 #
1425 # Entry: $input - the value to mutate.
1426 # Exit: Returns a mutated copy of the input.
1427 # Side effects: None.
1428 #
1429 # Notes: Blessed references are passed through
1430 # unchanged. Undef is replaced with a
1431 # freshly generated random value.
1432 # --------------------------------------------------
1433 561 ▶sub _mutate {
Subroutine _mutate: called CC=7 SCAR=19.5
1434 561 my ($self, $input) = @_;
1435  
1436 561 my $type = ref($input);
1437  
1438 561 ▶ if(!defined $input) {
Branch: 4 branches
BranchTrueFalseTotal
if (not defined $input) { } 12 549 561
elsif (not $type) { } 501 48 549
elsif ($type eq 'ARRAY') { } 11 37 48
elsif ($type eq 'HASH') { } 35 2 37
1439 # Replace undef with a fresh random value
1440 12 return $self->_generate_random();
1441 }
1442 elsif(!$type) {
1443 # Dispatch scalar mutation based on apparent type
1444 501 ▶ if($input =~ /^-?\d+$/) {
Branch: 2 branches
BranchTrueFalseTotal
if ($input =~ /^-?\d+$/) { } 83 418 501
elsif ($input =~ /^-?[\d.]+$/) { } 2 416 418
1445 83 return $self->_mutate_int($input);
1446 } elsif($input =~ /^-?[\d.]+$/) {
1447 2 return $self->_mutate_num($input);
1448 } else {
1449 416 return $self->_mutate_string($input);
1450 }
1451 }
1452 elsif($type eq 'ARRAY') {
1453 11 return $self->_mutate_array($input);
1454 }
1455 elsif($type eq 'HASH') {
1456 35 return $self->_mutate_hash($input);
1457 }
1458  
1459 # Blessed refs and other types pass through unchanged
1460 2 return $input;
1461 }
1462  
1463 # --------------------------------------------------
1464 # _mutate_int
1465 #
1466 # Purpose: Apply a random arithmetic mutation to
1467 # an integer value.
1468 #
1469 # Entry: $n - the integer to mutate.
1470 # Exit: Returns a mutated integer.
1471 # Side effects: None.
1472 # --------------------------------------------------
1473 88 ▶sub _mutate_int {
Subroutine _mutate_int: called CC=9 SCAR=22.0
1474 88 my ($self, $n) = @_;
1475 88 my $op = int(rand(8));
1476 88 ▶ return $n + 1 if $op == 0;
Branch: 1 branch
BranchTrueFalseTotal
if $op == 0 12 76 88
1477 76 ▶ return $n - 1 if $op == 1;
Branch: 1 branch
BranchTrueFalseTotal
if $op == 1 8 68 76
1478 68 ▶ return $n * 2 if $op == 2;
Branch: 1 branch
BranchTrueFalseTotal
if $op == 2 15 53 68
1479 53 ▶ return $n == 0 ? 1 : int($n / 2) if $op == 3;
Branch: 2 branches
BranchTrueFalseTotal
if $op == 3 10 43 53
$n == 0 ? : 3 7 10
1480 43 ▶ return -$n if $op == 4;
Branch: 1 branch
BranchTrueFalseTotal
if $op == 4 15 28 43
1481 28 ▶ return 0 if $op == 5;
Branch: 1 branch
BranchTrueFalseTotal
if $op == 5 5 23 28
1482 23 ▶ return $INT32_MAX if $op == 6;
Branch: 1 branch
BranchTrueFalseTotal
if $op == 6 11 12 23
1483 12 return $INT32_MIN;
1484 }
1485  
1486 # --------------------------------------------------
1487 # _mutate_num
1488 #
1489 # Purpose: Apply a random arithmetic mutation to
1490 # a floating point value.
1491 #
1492 # Entry: $n - the number to mutate.
1493 # Exit: Returns a mutated number.
1494 # Side effects: None.
1495 # --------------------------------------------------
1496 5 ▶sub _mutate_num {
Subroutine _mutate_num: called CC=5 SCAR=16.5
1497 5 my ($self, $n) = @_;
1498 5 my $op = int(rand(5));
1499 5 ▶ return $n + rand(10) if $op == 0;
Branch: 1 branch
BranchTrueFalseTotal
if $op == 0 0 5 5
1500 5 ▶ return $n - rand(10) if $op == 1;
Branch: 1 branch
BranchTrueFalseTotal
if $op == 1 2 3 5
1501 3 ▶ return $n * (1 + rand()) if $op == 2;
Branch: 1 branch
BranchTrueFalseTotal
if $op == 2 1 2 3
1502 2 ▶ return 0 if $op == 3;
Branch: 1 branch
BranchTrueFalseTotal
if $op == 3 2 0 2
1503 0 return -$n;
1504 }
1505  
1506 # --------------------------------------------------
1507 # _mutate_string
1508 #
1509 # Purpose: Apply a random structural mutation to
1510 # a string value — bit flip, insert,
1511 # delete, truncate, repeat, or replace
1512 # with an interesting known value.
1513 #
1514 # Entry: $s - the string to mutate.
1515 # Exit: Returns a mutated string.
1516 # Side effects: None.
1517 # --------------------------------------------------
1518 419 ▶sub _mutate_string {
Subroutine _mutate_string: called CC=1 SCAR=0.0
1519 419 my ($self, $s) = @_;
1520  
1521 419 my $len = length($s);
1522  
1523 my @ops = (
1524 # Bit flip a random character
1525 48 ▶ sub {
Subroutine __ANON__: called CC=2 SCAR=6.9
1526 48 ▶ return $s unless $len;
Branch: 1 branch
BranchTrueFalseTotal
unless $len 1 47 48
1527 47 my $pos = int(rand($len));
1528 47 my $char = substr($s, $pos, 1);
1529 47 substr($s, $pos, 1) = chr(ord($char) ^ (1 << int(rand(8))));
1530 47 $s
1531 },
1532 # Insert a random byte
1533 90 ▶ sub {
Subroutine __ANON__: called CC=1 SCAR=0.0
1534 90 my $pos = int(rand($len + 1));
1535 90 my $char = chr(int(rand(256)));
1536 90 substr($s, $pos, 0, $char);
1537 90 $s
1538 },
1539 # Delete a random character
1540 70 ▶ sub {
Subroutine __ANON__: called CC=2 SCAR=6.9
1541 70 ▶ return $s unless $len;
Branch: 1 branch
BranchTrueFalseTotal
unless $len 5 65 70
1542 65 substr($s, int(rand($len)), 1, '');
1543 65 $s
1544 },
1545 # Truncate at a random position
1546 68 ▶ sub { substr($s, 0, int(rand($len + 1))) },
Subroutine __ANON__: called CC=1 SCAR=0.0
1547 # Double the string
1548 81 ▶ sub { $s x 2 },
Subroutine __ANON__: called CC=1 SCAR=0.0
1549 # Replace with a known interesting string
1550 62 ▶ sub { $INTERESTING_STRINGS[ int(rand(@INTERESTING_STRINGS)) ] },
Subroutine __ANON__: called CC=1 SCAR=0.0
1551 419 );
1552  
1553 419 return $ops[ int(rand(@ops)) ]->();
1554 }
1555  
1556 # --------------------------------------------------
1557 # _mutate_array
1558 #
1559 # Purpose: Apply a random structural mutation to
1560 # an arrayref — mutate element, duplicate,
1561 # delete, or empty.
1562 #
1563 # Entry: $arr - the arrayref to mutate.
1564 # Exit: Returns a mutated arrayref copy.
1565 # Side effects: None.
1566 # --------------------------------------------------
1567 13 ▶sub _mutate_array {
Subroutine _mutate_array: called CC=1 SCAR=0.1
1568 13 my ($self, $arr) = @_;
1569  
1570 13 my @copy = @{$arr};
1571  
1572 my @ops = (
1573 # Mutate a random element
1574 2 ▶ sub {
Subroutine __ANON__: called CC=2 SCAR=7.0
1575 2 ▶ return [] unless @copy;
Branch: 1 branch
BranchTrueFalseTotal
unless @copy 0 2 2
1576 2 my $i = int(rand(@copy));
1577 2 $copy[$i] = $self->_mutate($copy[$i]);
1578 \@copy
1579 2 },
1580 # Duplicate a random element
1581 1 ▶ sub {
Subroutine __ANON__: called CC=2 SCAR=11.6
1582 1 ▶ return \@copy unless @copy;
Branch: 1 branch
BranchTrueFalseTotal
unless @copy 1 0 1
1583 0 my $i = int(rand(@copy));
1584 0 splice @copy, $i, 0, $copy[$i];
1585 \@copy
1586 0 },
1587 # Delete a random element
1588 8 ▶ sub {
Subroutine __ANON__: called CC=2 SCAR=6.9
1589 8 ▶ return \@copy unless @copy;
Branch: 1 branch
BranchTrueFalseTotal
unless @copy 1 7 8
1590 7 splice @copy, int(rand(@copy)), 1;
1591 \@copy
1592 7 },
1593 # Return empty array
1594 2 ▶ sub { [] },
Subroutine __ANON__: called CC=1 SCAR=0.0
1595 13 );
1596  
1597 13 return $ops[ int(rand(@ops)) ]->();
1598 }
1599  
1600 # --------------------------------------------------
1601 # _mutate_hash
1602 #
1603 # Purpose: Apply a random mutation to one value
1604 # in a hashref copy.
1605 #
1606 # Entry: $h - the hashref to mutate.
1607 # Exit: Returns a mutated hashref copy.
1608 # Side effects: None.
1609 # --------------------------------------------------
1610 38 ▶sub _mutate_hash {
Subroutine _mutate_hash: called CC=2 SCAR=6.9
1611 38 my ($self, $h) = @_;
1612  
1613 38 my %copy = %{$h};
1614 38 my @keys = keys %copy;
1615  
1616 # Return unchanged if hash is empty
1617 38 ▶ return \%copy unless @keys;
Branch: 1 branch
BranchTrueFalseTotal
unless @keys 7 31 38
1618  
1619 31 my $k = $keys[ int(rand(@keys)) ];
1620 31 $copy{$k} = $self->_mutate($copy{$k});
1621  
1622 31 return \%copy;
1623 }
1624  
1625 # --------------------------------------------------
1626 # _seed_corpus
1627 #
1628 # Purpose: Pre-populate the corpus with a small
1629 # set of randomly generated inputs to
1630 # give the fuzzing loop a starting point.
1631 #
1632 # Entry: None beyond $self.
1633 # Exit: Returns nothing. Appends to $self->{corpus}.
1634 # Side effects: Modifies $self->{corpus}.
1635 # --------------------------------------------------
1636 80 ▶sub _seed_corpus {
Subroutine _seed_corpus: called CC=2 SCAR=6.9
1637 80 my $self = $_[0];
1638  
1639 80 for (1 .. $SEED_CORPUS_SIZE) {
1640 400 push @{ $self->{corpus} }, {
1641 input => $self->_generate_random(),
1642 coverage => {},
1643 };
1644 }
1645 }
1646  
1647 # --------------------------------------------------
1648 # _build_report
1649 #
1650 # Purpose: Construct the summary report hashref
1651 # returned by run().
1652 #
1653 # Entry: None beyond $self.
1654 # Exit: Returns a report hashref.
1655 # Side effects: None.
1656 # --------------------------------------------------
1657 78 ▶sub _build_report {
Subroutine _build_report: called CC=1 SCAR=0.0
1658 78 my $self = $_[0];
1659  
1660 return {
1661 total_iterations => $self->{stats}{total},
1662 interesting_inputs => $self->{stats}{interesting},
1663 78 corpus_size => scalar @{ $self->{corpus} },
1664 branches_covered => $self->{stats}{coverage},
1665 bugs_found => $self->{stats}{bugs},
1666 bugs => $self->{bugs},
1667 78 };
1668 }
1669  
1670 =head1 COMMON PITFALLS
1671  
1672 =over 4
1673  
1674 =item Forgetting that C<load_corpus> does not restore bugs
1675  
1676 The JSON written by C<save_corpus> contains a C<bugs> array, but C<load_corpus>
1677 reads only the C<corpus> key. A freshly loaded fuzzer always starts with an
1678 empty bugs list. If you need to carry bugs across sessions, persist them
1679 separately.
1680  
1681 =item Assuming coverage guidance is always active
1682  
1683 If C<Devel::Cover> is not installed, the fuzzer falls back to random-only mode
1684 and emits a warning. Corpus entries in this mode have C<coverage =E<gt> {}>
1685 and are kept using the C<RANDOM_KEEP_RATIO> (20%) heuristic rather than branch
1686 novelty. Install C<Devel::Cover> (or C<cpanm --with-recommends
1687 App::Test::Generator>) for full coverage-guided behaviour.
1688  
1689 =item Using C<refaddr> on C<corpus()> after C<minimize_corpus>
1690  
1691 C<minimize_corpus> replaces C<$self-E<gt>{corpus}> with a B<new> arrayref.
1692 Any caller that holds a reference to the old arrayref (e.g. from a prior
1693 C<corpus()> call) will see a stale snapshot. Always call C<corpus()> after
1694 C<minimize_corpus> if you need the current list.
1695  
1696 =item Setting C<timeout =E<gt> 0> on blocking targets
1697  
1698 Setting C<timeout> to 0 disables the per-call C<alarm()>. This is correct for
1699 targets that legitimately block (e.g. sleeping, waiting on I/O), but means a
1700 hung target_sub will hang the whole fuzzing run indefinitely. Use a
1701 process-level timeout (e.g. C<Sys::AlarmCall>) if you need a safety net for
1702 blocking code.
1703  
1704 =item A C<timeout> below one second turns the timeout off
1705  
1706 C<timeout> is passed to Perl's C<alarm>, which works in whole seconds.
1707 A value such as C<0.5> becomes C<0>, and C<0> means "no timeout".
1708  
1709 =item A schema without an C<input> key
1710  
1711 The generator reads only C<< $schema->{input} >>. If that key is missing,
1712 every generated input is C<undef>, and C<target_sub> is called with
1713 C<undef> each time. No error is raised.
1714  
1715 schema => { name => { type => 'string' } } # wrong
1716 schema => { input => { type => 'string' } } # right
1717  
1718 =item C<target_sub> always gets exactly one generated argument
1719  
1720 C<input> describes B<one> value. If C<input> is a list of named
1721 parameters without a C<type> key of its own, one random string is
1722 generated, not a hash. To pass a hashref, describe it:
1723  
1724 input => {
1725 type => 'hashref',
1726 properties => { age => { type => 'integer', min => 0 } },
1727 }
1728  
1729 =item How C<undef> and other false values are handled
1730  
1731 =over 4
1732  
1733 =item * C<schema> and C<target_sub> must be B<true> values, not only
1734 defined. An empty hashref C<{}> is true and is accepted.
1735  
1736 =item * C<target_sub> is not checked to be a code reference. A wrong
1737 value is accepted by C<new>, and then every call in C<run> fails.
1738  
1739 =item * C<iterations>, C<seed> and C<timeout> use their default only when
1740 they are missing or C<undef>. The value C<0> is kept: C<< iterations => 0 >>
1741 runs no calls, C<< seed => 0 >> is a valid fixed seed, C<< timeout => 0 >>
1742 means no time limit.
1743  
1744 =item * An C<undef> input can be generated (see above) and can be saved.
1745 It is written to the JSON file as C<null> and comes back as C<undef>.
1746  
1747 =item * An C<undef> value for a required field makes an input invalid.
1748 An C<undef> value for a field marked C<optional> is valid.
1749  
1750 =item * C<save_corpus(undef)> and C<load_corpus(undef)> croak with
1751 C<path required>.
1752  
1753 =back
1754  
1755 =item Nested data is copied only one level deep
1756  
1757 When a hashref or arrayref input is mutated, only the top level is copied.
1758 Deeper hashes and arrays are shared between the old and the new corpus
1759 entry. If your C<target_sub> changes its argument in place, it can
1760 silently change other corpus entries too. Write C<target_sub> so that it
1761 only reads its argument, or make it take a deep copy first.
1762  
1763 =item C<load_corpus> adds entries. It does not merge or replace.
1764  
1765 Loaded entries are put after the entries already in the corpus. Nothing
1766 is compared and nothing is overwritten. Load a file twice and you have
1767 two copies of each entry.
1768  
1769 =item Every C<run> adds five more random seed inputs
1770  
1771 The corpus grows by at least five entries per C<run> call. Call
1772 C<minimize_corpus> before C<save_corpus> if the object is used for many
1773 runs.
1774  
1775 =item Some warnings are recorded as bugs
1776  
1777 A warning from C<target_sub> that contains the word C<uninitialized>,
1778 C<undefined>, C<blessed> or C<invalid> is recorded as a bug, even though
1779 the call did not die. Warnings are caught during the call, so they are
1780 not printed. Other warnings are thrown away.
1781  
1782 =item C<branches_covered> is 0
1783  
1784 This means that no branch data was received. Branch data is only
1785 available when the whole program is started under C<Devel::Cover>, for
1786 example with C<perl -MDevel::Cover script.pl>. Having the module
1787 installed is not enough. Without it the run is random-only. Do not read
1788 a value of 0 as "the target has no branches".
1789  
1790 =item Branch counts include more than your target
1791  
1792 C<Devel::Cover> counts every branch in the program. A few of the
1793 branches counted in C<branches_covered> belong to the fuzzer and to other
1794 modules, not to C<target_sub>. Use the number to compare two runs, not
1795 as an exact size.
1796  
1797 =back
1798  
1799 =head1 ENCODING
1800  
1801 =over 4
1802  
1803 =item * Inputs given to C<target_sub>
1804  
1805 All strings are Perl character strings. Strings made by the fuzzer use
1806 ASCII letters, digits, space, tab, newline and the NUL character.
1807 Mutation can also produce any character from 0 to 255. The fuzzer never
1808 invents characters above 255 (for example emojis) by itself.
1809  
1810 =item * C<edge_case_array> and C<matches> in the schema
1811  
1812 Full Unicode is supported, including non-ASCII letters and emojis. Give
1813 them as decoded character strings (C<use utf8> in your source, or a YAML
1814 file loaded with L<YAML::XS>). Such values are passed to C<target_sub>
1815 unchanged and are mutated one character at a time.
1816  
1817 =item * String C<min> and C<max>
1818  
1819 Lengths are counted in characters, not bytes.
1820  
1821 =item * C<save_corpus> and C<load_corpus>
1822  
1823 Full Unicode is supported. The file is written as UTF-8 JSON, and every
1824 string, including non-ASCII letters and emojis, is loaded back exactly as
1825 it was saved. A corpus file written by version 0.47 or earlier, which
1826 could hold Latin-1 bytes, is still read correctly.
1827  
1828 =item * The C<path> argument
1829  
1830 Passed to the operating system unchanged. ASCII paths always work.
1831  
1832 =item * Error text in C<bugs>
1833  
1834 The C<error> value is whatever C<target_sub> died with, turned into a
1835 string. It is not encoded or decoded.
1836  
1837 =back
1838  
1839 =head1 LIMITATIONS
1840  
1841 =over 4
1842  
1843 =item Single-threaded
1844  
1845 All fuzzing iterations run sequentially in the calling process. For large
1846 iteration counts, wall-clock time scales linearly. Parallelism requires
1847 splitting the iteration budget across multiple fuzzer instances and merging
1848 their corpora.
1849  
1850 =item Coverage granularity is branch-level
1851  
1852 Branch coverage is the finest granularity Devel::Cover exposes via its public
1853 API. Path coverage (distinct sequences of branches) is not tracked. Two
1854 inputs that cover the same branches but exercise different call orders are
1855 treated as equivalent.
1856  
1857 =item No inter-run learning without save/load
1858  
1859 The corpus is entirely in memory. To carry learning across separate
1860 invocations, call C<save_corpus> at the end and C<load_corpus> at the start of
1861 each subsequent run.
1862  
1863 =back
1864  
1865 =head1 SEE ALSO
1866  
1867 =over 4
1868  
1869 =item L<Devel::Cover>
1870  
1871 =item L<App::Test::Generator>
1872  
1873 =item C<bin/extract-schemas> (the C<--minimize-corpus> flag)
1874  
1875 =back
1876  
1877 =head1 AUTHOR
1878  
1879 Nigel Horne, C<< <njh at nigelhorne.com> >>
1880  
1881 Portions of this module's initial design and documentation were created
1882 with the assistance of AI.
1883  
1884 =head1 FORMAL SPECIFICATION
1885  
1886 This section describes each method in Z notation. It is for readers who
1887 want an exact, mathematical statement. You do not need it to use the module.
1888  
1889 How to read it: a name ending in C<?> is an input, a name ending in C<!> is
1890 an output, and a name ending in C<'> is the value after the call.
1891 E<0x0394> before the state name means "this call may change the object".
1892 E<0x039E> means "this call does not change the object".
1893 C<#> is the number of items in a list or set.
1894  
1895 Entry == [ input : VALUE ; coverage : ℙ BRANCH ]
1896 Bug == [ input : VALUE ; error : STRING ]
1897  
1898 ┌─ Fuzzer ──────────────────────────────────────────
1899 │ schema : VALUE
1900 │ target_sub : VALUE
1901 │ instance : VALUE
1902 │ iterations, seed, timeout : NUMBER
1903 │ corpus : seq Entry
1904 │ bugs : seq Bug
1905 │ covered : ℙ BRANCH
1906 │ total, interesting : ℕ
1907 ├───────────────────────────────────────────────────
1908 │ schema and target_sub are true values
1909 │ ⋃ { e : ran corpus • e.coverage } ⊆ covered
1910 │ interesting ≤ #corpus
1911 └───────────────────────────────────────────────────
1912  
1913 =head2 new
1914  
1915 ┌─ New ─────────────────────────────────────────────
1916 │ Fuzzer′
1917 │ schema?, target_sub?, instance? : VALUE
1918 │ iterations?, seed?, timeout? : NUMBER ∪ { undef }
1919 │ result! : Fuzzer
1920 ├───────────────────────────────────────────────────
1921 │ pre schema? is true ∧ target_sub? is true
1922 │ post schema′ = schema? ∧ target_sub′ = target_sub?
1923 │ instance′ = instance?
1924 │ iterations′ = if iterations? = undef then 100 else iterations?
1925 │ seed′ = if seed? = undef then time() else seed?
1926 │ timeout′ = if timeout? = undef then 5 else timeout?
1927 │ corpus′ = ⟨⟩ ∧ bugs′ = ⟨⟩ ∧ covered′ = ∅
1928 │ total′ = 0 ∧ interesting′ = 0
1929 │ srand(seed′) has been called
1930 │ result! = θ Fuzzer′
1931 └───────────────────────────────────────────────────
1932  
1933 schema? is false ⇒ croak 'schema required'
1934 target_sub? is false ⇒ croak 'target_sub required'
1935  
1936 =head2 run
1937  
1938 ┌─ Run ─────────────────────────────────────────────
1939 │ Δ Fuzzer
1940 │ result! : REPORT
1941 ├───────────────────────────────────────────────────
1942 │ post total′ = total + iterations
1943 │ corpus prefix corpus′
1944 │ #corpus′ ≥ #corpus + 5
1945 │ #corpus′ − #corpus − 5 = interesting′ − interesting
1946 │ bugs prefix bugs′
1947 │ covered ⊆ covered′
1948 │ ∀ b : ran bugs′ ∖ ran bugs •
1949 │ b.input is valid for schema.input
1950 │ result!.total_iterations = total′
1951 │ result!.interesting_inputs = interesting′
1952 │ result!.corpus_size = #corpus′
1953 │ result!.branches_covered = #covered′
1954 │ result!.bugs_found = #bugs′
1955 │ result!.bugs = bugs′
1956 │ schema′ = schema ∧ seed′ = seed
1957 └───────────────────────────────────────────────────
1958  
1959 =head2 corpus
1960  
1961 ┌─ Corpus ──────────────────────────────────────────
1962 │ Ξ Fuzzer
1963 │ result! : seq Entry
1964 ├───────────────────────────────────────────────────
1965 │ post result! = corpus (the same list, not a copy)
1966 └───────────────────────────────────────────────────
1967  
1968 =head2 bugs
1969  
1970 ┌─ Bugs ────────────────────────────────────────────
1971 │ Ξ Fuzzer
1972 │ result! : seq Bug
1973 ├───────────────────────────────────────────────────
1974 │ post result! = bugs (the same list, not a copy)
1975 └───────────────────────────────────────────────────
1976  
1977 =head2 save_corpus
1978  
1979 ┌─ SaveCorpus ──────────────────────────────────────
1980 │ Ξ Fuzzer
1981 │ path? : PATH
1982 ├───────────────────────────────────────────────────
1983 │ pre path? ≠ undef ∧ path? can be written
1984 │ every input in corpus and bugs is plain data
1985 │ post content′(path?) = JSON of
1986 │ [ seed ↦ seed,
1987 │ corpus ↦ ⟨ e : corpus • [ input ↦ e.input ] ⟩,
1988 │ bugs ↦ bugs ]
1989 └───────────────────────────────────────────────────
1990  
1991 path? = undef ⇒ croak 'path required'
1992 path? cannot be written ⇒ croak 'Cannot write corpus to ...'
1993  
1994 =head2 load_corpus
1995  
1996 ┌─ LoadCorpus ──────────────────────────────────────
1997 │ Δ Fuzzer
1998 │ path? : PATH
1999 │ loaded : seq VALUE
2000 ├───────────────────────────────────────────────────
2001 │ pre path? ≠ undef ∧ path? holds valid JSON
2002 │ post loaded = the inputs under the 'corpus' key of the file
2003 │ corpus′ = corpus ⁀ ⟨ v : loaded • [ input ↦ v, coverage ↦ ∅ ] ⟩
2004 │ bugs′ = bugs ∧ seed′ = seed ∧ covered′ = covered
2005 │ total′ = total ∧ interesting′ = interesting
2006 └───────────────────────────────────────────────────
2007  
2008 path? = undef ⇒ croak 'path required'
2009 path? cannot be read ⇒ croak 'Cannot read corpus from ...'
2010  
2011 =head2 minimize_corpus
2012  
2013 fp(v) == the canonical JSON text of v (the "fingerprint")
2014  
2015 ┌─ MinimizeCorpus ──────────────────────────────────
2016 │ Δ Fuzzer
2017 │ result! : [ before, after, branches : ℕ ]
2018 │ with, without : seq Entry
2019 ├───────────────────────────────────────────────────
2020 │ post with = corpus filtered to entries with coverage ≠ ∅
2021 │ without = corpus filtered to entries with coverage = ∅
2022 │ result!.before = #corpus
2023 │ result!.after = #corpus′
2024 │ result!.branches = # ⋃ { e : ran with • e.coverage }
2025 │ ⋃ { e : ran corpus′ • e.coverage }
2026 │ = ⋃ { e : ran corpus • e.coverage }
2027 │ ∀ e : ran without • ∃ k : ran corpus′ •
2028 │ fp(k.input) = fp(e.input)
2029 │ ∀ b : ran bugs • ∃ k : ran corpus′ •
2030 │ fp(k.input) = fp(b.input)
2031 │ corpus′ is a new list (old references are stale)
2032 │ bugs′ = bugs ∧ covered′ = covered
2033 │ total′ = total ∧ interesting′ = interesting
2034 └───────────────────────────────────────────────────
2035  
2036 Calling it a second time changes nothing:
2037 result!.before = result!.after on the second call.
2038  
2039 =head1 STATE DIAGRAM
2040  
2041 The state of a fuzzer is the state of its corpus.
2042  
2043 new(schema or target_sub missing or false)
2044 +--------------------------------------------------+
2045 | action: croak, no object |
2046 v |
2047 +-------------+ |
2048 | NO OBJECT |--------------------------------------+
2049 +-------------+
2050 |
2051 | new(schema, target_sub, ...)
2052 | action: store settings, call srand(seed),
2053 | try to load Devel::Cover
2054 v
2055 +---------------------+ minimize_corpus()
2056 | |-----------------------------------------+
2057 | EMPTY | action: returns 0 / 0 / 0 |
2058 | (corpus is empty) |<----------------------------------------+
2059 | |
2060 | | save_corpus(path)
2061 | |-----------------------------------------+
2062 | | action: write a file with no entries |
2063 | |<----------------------------------------+
2064 +---------------------+
2065 |
2066 | run()
2067 | action: add 5 random inputs, call target_sub
2068 | 'iterations' times, keep interesting inputs,
2069 | record bugs, return the report
2070 | load_corpus(path)
2071 | action: add the inputs from the file (no branch data)
2072 v
2073 +---------------------+ run()
2074 | |-----------------------------------------+
2075 | GROWING | action: as above; corpus gets bigger, |
2076 | (corpus may hold | totals are added to the old totals |
2077 | copies and spare |<----------------------------------------+
2078 | entries) |
2079 | | load_corpus(path)
2080 | |-----------------------------------------+
2081 | | action: add the file's inputs again |
2082 | |<----------------------------------------+
2083 | |
2084 | | save_corpus(path)
2085 | |-----------------------------------------+
2086 | | action: write the file, no change |
2087 | |<----------------------------------------+
2088 +---------------------+
2089 | ^
2090 | | run() or load_corpus(path)
2091 | | action: as above
2092 | minimize_corpus()
2093 | action: replace the corpus with a new, smaller list;
2094 | keep every covered branch and every bug input;
2095 | return before / after / branches
2096 v |
2097 +---------------------+ minimize_corpus()
2098 | |-----------------------------------------+
2099 | MINIMIZED | action: nothing changes (before=after) |
2100 | (no spare entries) |<----------------------------------------+
2101 | |
2102 | | save_corpus(path)
2103 | |-----------------------------------------+
2104 | | action: write the smallest file |
2105 | |<----------------------------------------+
2106 +---------------------+
2107  
2108 In every state: corpus() and bugs() return the current lists and
2109 change nothing. A call that croaks (bad path, unwritable file,
2110 unreadable file) changes nothing.
2111  
2112 The usual order of calls in one program run is:
2113  
2114 new -> load_corpus -> run -> minimize_corpus -> save_corpus
2115  
2116 =head1 LICENCE AND COPYRIGHT
2117  
2118 Copyright 2026 Nigel Horne.
2119  
2120 Usage is subject to GPL2 licence terms.
2121 If you use it,
2122 please let me know.
2123  
2124 =cut
2125  
2126 20 1;
« blib/lib/Devel/App/Test/Generator/LCSAJ/Runtime.pm ↑ Summary lib/App/Test/Generator/Mutation/Feedback.pm »