blib/lib/Devel/App/Test/Generator/LCSAJ/Runtime.pm

filter: Statementstmt 67.5% 52 / 77 Branchbran 43.3% 13 / 30 Conditioncond 25.0% 5 / 20 MC/DCmcdc 0.0% 0 / 13 Subroutinesub 78.9% 15 / 19 Podpod 0.0% 0 / 2 totaltotal 52.8% 85 / 161 CC 24 SCAR 24.2
CC
24
Cov
55%
DB
23.6
DB
23.6
BEGIN
9.3
CRAP 11.3
« blib/lib/App/Test/Generator/BenchmarkGenerator.pm ↑ Summary lib/App/Test/Generator/CoverageGuidedFuzzer.pm »
1 package Devel::App::Test::Generator::LCSAJ::Runtime;
2  
3 2 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 2 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
5 2 ▶use autodie qw(open close);
Subroutine BEGIN: called CC=1 SCAR=0.0
6 2 ▶use Carp qw(croak);
Subroutine BEGIN: called CC=1 SCAR=0.0
7 2 ▶use Config;
Subroutine BEGIN: called CC=1 SCAR=0.0
8 2 ▶use Cwd qw(abs_path);
Subroutine BEGIN: called CC=1 SCAR=0.0
9 2 ▶use JSON::MaybeXS;
Subroutine BEGIN: called CC=1 SCAR=0.0
10 2 ▶use File::Path qw(make_path);
Subroutine BEGIN: called CC=1 SCAR=0.0
11 2 ▶use Readonly;
Subroutine BEGIN: called CC=1 SCAR=0.0
12  
13 # --------------------------------------------------
14 # Output directory for per-process hit JSON files.
15 # One file is written per process (PID) so parallel
16 # test runs do not overwrite each other's output.
17 # --------------------------------------------------
18 Readonly my $OUT_DIR => 'cover_html/lcsaj_hits';
19  
20 =head1 NAME
21  
22 Devel::App::Test::Generator::LCSAJ::Runtime - Debugger backend for LCSAJ coverage
23  
24 =head1 VERSION
25  
26 Version 0.50
27  
28 =cut
29  
30 our $VERSION = '0.50';
31  
32 =head1 SYNOPSIS
33  
34 PERL5OPT='-d:App::Test::Generator::LCSAJ::Runtime -Mblib' prove -l t
35  
36 =head1 DESCRIPTION
37  
38 This module is loaded as a Perl debugger backend using the C<-d:Module> flag.
39  
40 When Perl sees C<-d:App::Test::Generator::LCSAJ::Runtime> it prepends C<Devel::>
41 and loads C<Devel/App/Test/Generator/LCSAJ/Runtime.pm> from C<@INC>.
42 The file must therefore live at that path - typically C<lib/Devel/App/Test/Generator/LCSAJ/Runtime.pm>.
43  
44 Perl automatically calls C<DB::DB> before executing each statement while the
45 debugger is active. We record (file, line) pairs to build runtime hit data for
46 later LCSAJ analysis.
47  
48 Results are written to C<cover_html/lcsaj_hits/hits_PID.json> at process exit,
49 one file per process so that parallel test runs do not overwrite each other.
50  
51 =head1 ENVIRONMENT
52  
53 =over 4
54  
55 =item LCSAJ_TARGETS
56  
57 Optional list of B<absolute> paths (as produced by C<realpath>), separated by
58 C<$Config{path_sep}> (C<:> on Unix, C<;> on Windows, as in C<PATH>), to
59 restrict recording to specific source files. When empty or unset every
60 non-internal file is recorded.
61  
62 =back
63  
64 =cut
65  
66 # --------------------------------------------------
67 # %HITS - { normalised_path => { line_number => hit_count } }
68 # %TARGET - set of normalised paths to record (empty means record everything)
69 # %NORM_CACHE - { raw_file => normalised_path }, memoises abs_path()
70 # since DB::DB sees the same $file on every consecutive
71 # statement within a source file
72 #
73 # These must be package globals (our) rather than lexicals because DB::DB
74 # is called by the Perl debugger infrastructure and needs to access them
75 # without a closure. Lexical vars would not be visible in DB::DB.
76 # --------------------------------------------------
77 our %HITS;
78 our %TARGET;
79 our %NORM_CACHE;
80  
81 # --------------------------------------------------
82 # Populate %TARGET from LCSAJ_TARGETS at compile time.
83 # The env var contains absolute realpath() output
84 # separated by $Config{path_sep}; a colon would split
85 # a Windows drive letter off its path. Stray newlines
86 # from broken shell pipelines are stripped defensively.
87 # --------------------------------------------------
88 2 ▶BEGIN {
Subroutine BEGIN: called CC=4 SCAR=22.3
89 2 ▶ my $targets_env = $ENV{LCSAJ_TARGETS} // '';
Condition50%1/2
$ENV{"LCSAJ_TARGETS"} // ""
l!l
02
MC/DC0%0/1
$ENV{"LCSAJ_TARGETS"} // ""
$ENV{"LCSAJ_TARGETS"}
Truth table50%1/2
A
A= $ENV{"LCSAJ_TARGETS"}
Aresult
11
00
90 2 $targets_env =~ s/\n//g;
91  
92 2 for my $t (split /\Q$Config{path_sep}\E/, $targets_env) {
93 0 ▶ next unless length $t;
Branch: 1 branch
BranchTrueFalseTotal
unless length $t 0 0 0
94  
95 # Inline normalisation — cannot call _normalize here since
96 # BEGIN runs before named subs are compiled when BEGIN
97 # appears at the top of the file
98 0 my $f = $t;
99 0 $f =~ tr{\\}{/};
100 0 $f =~ s{^.*/blib/lib/}{lib/};
101 0 $f =~ s{^.*/lib/}{lib/};
102 0 $TARGET{$f} = 1;
103 }
104 }
105  
106 2 ▶END {
Subroutine END: called CC=1 SCAR=1.2
107 0 ▶ _write_results();
Subroutine END: not called CC=1 SCAR=1.2
108 }
109  
110 # --------------------------------------------------
111 # _normalize
112 #
113 # Convert an absolute or build-tree path
114 # to a canonical lib-relative form so that
115 # paths recorded at runtime match the
116 # targets derived from LCSAJ_TARGETS.
117 #
118 # Entry: $path - an absolute or relative file path.
119 #
120 # Exit: Returns a lib-relative path string,
121 # e.g. lib/Foo/Bar.pm
122 #
123 # Notes: Must be defined before the BEGIN block
124 # that calls it, since BEGIN runs at compile
125 # time and later subs may not yet be compiled.
126 #
127 # Examples:
128 # /home/user/proj/blib/lib/Foo/Bar.pm -> lib/Foo/Bar.pm
129 # /home/user/proj/lib/Foo/Bar.pm -> lib/Foo/Bar.pm
130 # D:\a\proj\blib\lib\Foo\Bar.pm -> lib/Foo/Bar.pm
131 # --------------------------------------------------
132 12 ▶sub _normalize {
Subroutine _normalize: called CC=1 SCAR=1.2
133 0 ▶ my $f = $_[0];
Subroutine _normalize: not called CC=1 SCAR=1.2
134  
135 # Windows paths (abs_path, %INC, caller) may use either separator
136 0 $f =~ tr{\\}{/};
137  
138 # Strip everything up to and including blib/lib/ or lib/
139 0 $f =~ s{^.*/blib/lib/}{lib/};
140 0 $f =~ s{^.*/lib/}{lib/};
141 0 return $f;
142 }
143  
144 # --------------------------------------------------
145 # DB::DB
146 #
147 # Called by the Perl debugger before every
148 # statement. Records (file, line) hits for
149 # later LCSAJ coverage analysis.
150 #
151 # Entry: No arguments — caller(0) is used to get
152 # the current file and line number.
153 #
154 # Exit: Returns nothing. Updates %HITS in place.
155 #
156 # Side effects: Increments %HITS{$norm}{$line}.
157 #
158 # Notes: This sub lives in the DB:: package as
159 # required by Perl's debugger protocol.
160 # It is called for every statement executed
161 # while the debugger is active, so it must
162 # be as fast as possible.
163 # Internal files and out-of-target files
164 # are skipped immediately.
165 # abs_path() resolution is memoised in
166 # %NORM_CACHE per raw $file, since the same
167 # file is seen on every consecutive statement.
168 # --------------------------------------------------
169 =head2 DB::DB
170  
171 Perl debugger hook, automatically invoked by the interpreter before every
172 statement while this module is active as a C<-d:> debugger backend.
173 Records a per-(file, line) hit count used later for LCSAJ coverage
174 analysis.
175  
176 =head3 Arguments
177  
178 None. Perl calls this sub directly; the current execution location is
179 obtained internally via C<caller(0)>.
180  
181 =head3 Returns
182  
183 Nothing meaningful - this is a void debugger callback.
184  
185 =head3 Side effects
186  
187 Increments C<%HITS{$norm}{$line}> for the normalised path and line number
188 of the statement about to execute. Resolves each distinct raw filename
189 via C<Cwd::abs_path> once, memoising the result in C<%NORM_CACHE>.
190  
191 =head3 Usage example
192  
193 Not called directly - activated via the Perl debugger flag:
194  
195 PERL5OPT='-d:App::Test::Generator::LCSAJ::Runtime -Mblib' prove -l t
196  
197 =head3 API specification
198  
199 =head4 input
200  
201 { }
202  
203 =head4 output
204  
205 { type => UNDEF }
206  
207 =cut
208  
209 7 ▶sub DB::DB {
Subroutine DB: called CC=8 SCAR=31.6
Pod undocumented
210 0 ▶ my (undef, $file, $line) = caller(0);
Subroutine DB: not called CC=8 SCAR=31.6
Pod undocumented
211  
212 0 ▶ return unless defined $file && defined $line;
Branch: 2 branches
BranchTrueFalseTotal
unless defined $file and defined $line 0 0 0
unless defined $file and defined $line 0 7 7
Condition16%1/6
defined $file and defined $line
!ll&&!rl&&r
000
defined $file and defined $line
!ll&&!rl&&r
007
MC/DC0%0/2
defined $file and defined $line
defined $file defined $line
MC/DC0%0/2
defined $file and defined $line
defined $file defined $line
Truth table0%0/3
A and B
A= defined $fileB= defined $line
ABresult
0X0
100
111
Truth table33%1/3
A and B
A= defined $fileB= defined $line
ABresult
0X0
100
111
213  
214 # Resolve symlinks and relative components to a stable absolute path,
215 # cached per raw $file to avoid a stat() on every statement
216 0 ▶ my $norm = $NORM_CACHE{$file} //= _normalize(abs_path($file) // $file);
Condition25%3/12
$Devel::App::Test::Generator::LCSAJ::Runtime::NORM_CACHE{$file} //= _normalize(abs_path($file) // $file)
l!l&&r!l&&!r
000
abs_path($file) // $file
l!l&&r!l&&!r
000
$Devel::App::Test::Generator::LCSAJ::Runtime::NORM_CACHE{$file} //= _normalize(abs_path($file) // $file)
l!l&&r!l&&!r
520
abs_path($file) // $file
l!l&&r!l&&!r
200
MC/DC0%0/2
$Devel::App::Test::Generator::LCSAJ::Runtime::NORM_CACHE{$file} //= _normalize(abs_path($file) // $file)
$Devel::App::Test::Generator::LCSAJ::Runtime::NORM_CACHE{$file} _normalize(abs_path($file) // $file)
MC/DC0%0/2
abs_path($file) // $file
abs_path($file) $file
MC/DC0%0/2
$Devel::App::Test::Generator::LCSAJ::Runtime::NORM_CACHE{$file} //= _normalize(abs_path($file) // $file)
$Devel::App::Test::Generator::LCSAJ::Runtime::NORM_CACHE{$file} _normalize(abs_path($file) // $file)
MC/DC0%0/2
abs_path($file) // $file
abs_path($file) $file
Truth table0%0/3
A //= B
A= $Devel::App::Test::Generator::LCSAJ::Runtime::NORM_CACHE{$file}B= _normalize(abs_path($file) // $file)
ABresult
1X1
011
000
Truth table0%0/3
A // B
A= abs_path($file)B= $file
ABresult
1X1
011
000
Truth table66%2/3
A //= B
A= $Devel::App::Test::Generator::LCSAJ::Runtime::NORM_CACHE{$file}B= _normalize(abs_path($file) // $file)
ABresult
1X1
011
000
Truth table33%1/3
A // B
A= abs_path($file)B= $file
ABresult
1X1
011
000
217  
218 # Never record hits inside this module itself — suffix match is used
219 # so it works regardless of CWD or install prefix
220 0 ▶ return if $norm =~ m{(?:^|/)Devel/App/Test/Generator/LCSAJ/Runtime\.pm$};
Branch: 2 branches
BranchTrueFalseTotal
if $norm =~ m[(?:^|/)Devel/App/Test/Generator/LCSAJ/Runtime\.pm$] 0 0 0
if $norm =~ m[(?:^|/)Devel/App/Test/Generator/LCSAJ/Runtime\.pm$] 1 6 7
221  
222 # If a target list was provided, skip files not in it
223 0 ▶ if(%TARGET) {
Branch: 2 branches
BranchTrueFalseTotal
if (%Devel::App::Test::Generator::LCSAJ::Runtime::TARGET) 0 0 0
if (%TARGET) 2 4 6
224 0 ▶ return unless $TARGET{$norm};
Branch: 2 branches
BranchTrueFalseTotal
unless $Devel::App::Test::Generator::LCSAJ::Runtime::TARGET{$norm} 0 0 0
unless $TARGET{$norm} 1 1 2
225 }
226  
227 0 $HITS{$norm}{$line}++;
228 }
229  
230 # --------------------------------------------------
231 # _write_results
232 #
233 # Serialise %HITS to a per-process JSON
234 # file in the output directory.
235 #
236 # Entry: None. Reads %HITS and $OUT_DIR.
237 #
238 # Exit: Returns nothing. Writes a JSON file.
239 # Returns immediately if %HITS is empty.
240 #
241 # Side effects: Creates $OUT_DIR if absent.
242 # Writes cover_html/lcsaj_hits/hits_PID.json
243 #
244 # Notes: Called from END so it runs even when
245 # prove exits non-zero — mutation tests
246 # are expected to fail. PID is included
247 # in the filename so parallel test runs
248 # produce separate files without collision.
249 # --------------------------------------------------
250 5 ▶sub _write_results {
Subroutine _write_results: called CC=4 SCAR=16.9
251 0 ▶ return unless %HITS;
Subroutine _write_results: not called CC=4 SCAR=16.9
Branch: 2 branches
BranchTrueFalseTotal
unless %Devel::App::Test::Generator::LCSAJ::Runtime::HITS 0 0 0
unless %Devel::App::Test::Generator::LCSAJ::Runtime::HITS 3 2 5
252  
253 # Include PID in filename to support parallel test runs
254 0 my $out_file = "$OUT_DIR/hits_$$.json";
255  
256 0 ▶ make_path($OUT_DIR) unless -d $OUT_DIR;
Branch: 2 branches
BranchTrueFalseTotal
unless -d $OUT_DIR 0 0 0
unless -d $OUT_DIR 1 1 2
257  
258 # autodie is disabled for this open -- under "use autodie qw(open)"
259 # open() never returns false on failure, it throws its own exception
260 # instead, which would silently make the "or croak" below dead code
261 2 ▶ no autodie qw(open);
Subroutine BEGIN: called CC=1 SCAR=0.0
262 0 ▶ open my $fh, '>', $out_file or croak "Cannot write $out_file: $!";
Branch: 2 branches
BranchTrueFalseTotal
open my $fh, ">", $out_file or croak("Cannot write ${out_file}: $!") 0 0 0
open my $fh, ">", $out_file or croak("Cannot write ${out_file}: $!") 1 1 2
263  
264 0 print $fh encode_json(\%HITS);
265 0 close $fh;
266 }
267  
268 1;
269  
270 __END__
« blib/lib/App/Test/Generator/BenchmarkGenerator.pm ↑ Summary lib/App/Test/Generator/CoverageGuidedFuzzer.pm »