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

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