bin/pod-example-tester

filter: Statementstmt 83.7% 108 / 129 Branchbran 50.0% 26 / 52 Conditioncond 22.2% 2 / 9 MC/DCmcdc 0.0% 0 / 6 Subroutinesub 100% 15 / 15 Podpod n/a totaltotal 71.5% 151 / 211 CC 20 SCAR 19.3
CC
20
Cov
72%
_emit_subtest
18.5
_detect_package
4.6
_stub_undeclared_vars
4.0
CRAP 6.9
« lib/App/Test/Generator/Mutation/NumericBoundary.pm ↑ Summary lib/App/Test/Generator/Mutator.pm »
1 #!/usr/bin/env perl
2  
3 1 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 1 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
5  
6 1 ▶use File::Path qw(make_path);
Subroutine BEGIN: called CC=1 SCAR=0.0
7 1 ▶use File::Spec;
Subroutine BEGIN: called CC=1 SCAR=0.0
8 1 ▶use FindBin;
Subroutine BEGIN: called CC=1 SCAR=0.0
9 1 ▶use Getopt::Long;
Subroutine BEGIN: called CC=1 SCAR=0.0
10 1 ▶use Pod::Usage;
Subroutine BEGIN: called CC=1 SCAR=0.0
11 1 ▶use lib "$FindBin::Bin/../lib";
Subroutine BEGIN: called CC=1 SCAR=0.0
12  
13 1 ▶use App::Test::Generator::PodExampleExtractor;
Subroutine BEGIN: called CC=1 SCAR=0.0
14  
15 =head1 NAME
16  
17 pod-example-tester - Generate round-trip tests from POD code examples
18  
19 =head1 SYNOPSIS
20  
21 pod-example-tester [options] <module.pm>
22  
23 Options:
24 --output FILE Write test file to FILE (default: t/pod_examples.t)
25 --no-annotated Skip annotated single-line examples; only use verbatim blocks
26 --help Show this help message
27 --man Show full documentation
28  
29 Examples:
30 pod-example-tester lib/My/Module.pm
31 pod-example-tester --output t/synopsis.t lib/My/Module.pm
32  
33 =head1 DESCRIPTION
34  
35 Reads a Perl module, extracts code examples from its POD (from
36 C<=head1 SYNOPSIS>, C<=head2 SYNOPSIS>, C<=for example begin>/C<=for example end>
37 blocks, and annotated inline examples), and generates a Test::Most-based
38 C<.t> file that runs every example as a subtest.
39  
40 Each subtest:
41  
42 =over 4
43  
44 =item * Wraps the example code in C<eval { ... }>
45  
46 =item * Asserts the example does not die
47  
48 =item * If the example has a C<# returns value> or C<< # => value >> annotation,
49 additionally asserts the return value with C<is()>
50  
51 =back
52  
53 Running this test suite after any code change ensures that all documented
54 examples still work - the "round-trip" between documentation and code.
55  
56 =head1 ANNOTATION FORMAT
57  
58 Append C<# => value> or C<# returns value> to any indented line in the POD
59 to document the expected return value:
60  
61 my $status = $obj->validate_score(75.5); # returns 'Pass'
62 my $x = add(2, 3); # => 5
63  
64 The generated test will assert C<is($result, 'Pass', ...)> etc.
65  
66 =cut
67  
68 1 my %opts = (
69 output => 't/pod_examples.t',
70 annotated => 1,
71 help => 0,
72 man => 0,
73 );
74  
75 GetOptions(
76 'output|o=s' => \$opts{output},
77 'annotated!' => \$opts{annotated},
78 'help|h' => \$opts{help},
79 'man|m' => \$opts{man},
80 1 ▶) or pod2usage(2);
Branch: 1 branch
BranchTrueFalseTotal
&GetOptions("output|o=s", \$opts{"output"}, "annotated!", \$opts{"annotated"}, "help|h", \$opts{"help"}, "man|m", \$opts{"man"}) or pod2usage(2) 1 0 1
81  
82 1 ▶pod2usage(-exitval => 0, -verbose => 1) if $opts{help};
Branch: 1 branch
BranchTrueFalseTotal
if $opts{"help"} 0 1 1
83 1 ▶pod2usage(-exitval => 0, -verbose => 2) if $opts{man};
Branch: 1 branch
BranchTrueFalseTotal
if $opts{"man"} 0 1 1
84  
85 1 ▶my $input_file = shift @ARGV or pod2usage('Error: No input file specified');
Branch: 1 branch
BranchTrueFalseTotal
my $input_file = shift @ARGV or pod2usage("Error: No input file specified") 1 0 1
86 1 ▶die "Error: File not found: $input_file\n" unless -f $input_file;
Branch: 1 branch
BranchTrueFalseTotal
unless -f $input_file 0 1 1
87  
88 # Derive the package name from the source file
89 1 ▶my $package = _detect_package($input_file)
Branch: 1 branch
BranchTrueFalseTotal
my $package = _detect_package($input_file) or die "Error: Could not determine package name from $input_file\n" 1 0 1
90 or die "Error: Could not determine package name from $input_file\n";
91  
92 1 my $extractor = App::Test::Generator::PodExampleExtractor->new(file => $input_file);
93 1 my $examples = $extractor->extract();
94  
95 1 ▶unless(@$examples) {
Branch: 1 branch
BranchTrueFalseTotal
unless (@$examples) 0 1 1
96 0 warn "No POD examples found in $input_file\n";
97 0 exit 0;
98 }
99  
100 # Apply --no-annotated filter
101 1 ▶if(!$opts{annotated}) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($opts{"annotated"}) 0 1 1
102 0 $examples = [ grep { !defined $_->{annotated_line} } @$examples ];
103 }
104  
105 1 ▶unless(@$examples) {
Branch: 1 branch
BranchTrueFalseTotal
unless (@$examples) 0 1 1
106 0 warn "No examples remaining after filtering\n";
107 0 exit 0;
108 }
109  
110 # Ensure output directory exists
111 1 my $out_dir = (File::Spec->splitpath($opts{output}))[1];
112 1 ▶make_path($out_dir) if $out_dir && !-d $out_dir;
Branch: 1 branch
BranchTrueFalseTotal
if $out_dir and not -d $out_dir 0 1 1
Condition33%1/3
$out_dir and not -d $out_dir
!ll&&!rl&&r
010
MC/DC0%0/2
$out_dir and not -d $out_dir
$out_dir not -d $out_dir
Truth table33%1/3
A and not(B)
A= $out_dirB= not -d $out_dir
ABresult
0X0
100
111
113  
114 open my $fh, '>', $opts{output}
115 1 ▶ or die "Error: Cannot write to $opts{output}: $!\n";
Branch: 1 branch
BranchTrueFalseTotal
open my $fh, ">", $opts{"output"} or die qq[Error: Cannot write to $opts{"output"}: $!\n] 1 0 1
116  
117 1 _emit_test_file($fh, $package, $input_file, $examples);
118  
119 1 close $fh;
120  
121 1 printf "Wrote %d example test(s) to %s\n", scalar(@$examples), $opts{output};
122  
123 # ---------------------------------------------------------------------------
124 # _emit_test_file
125 # ---------------------------------------------------------------------------
126 1 ▶sub _emit_test_file {
Subroutine _emit_test_file: called CC=2 SCAR=6.9
127 1 my ($fh, $package, $source, $examples) = @_;
128  
129 1 print $fh "#!/usr/bin/env perl\n";
130 1 print $fh "#\n";
131 1 print $fh "# POD round-trip tests for $package\n";
132 1 print $fh "# Generated from $source by pod-example-tester\n";
133 1 print $fh "# DO NOT EDIT — regenerate with: pod-example-tester $source\n";
134 1 print $fh "#\n\n";
135 1 print $fh "use strict;\n";
136 1 print $fh "use warnings;\n";
137 1 print $fh "use Test::Most;\n\n";
138 1 print $fh "use_ok('$package') or BAIL_OUT(\"Cannot load $package\");\n\n";
139  
140 1 my $ctor = _detect_constructor($package);
141  
142 1 for my $ex (@$examples) {
143 1 _emit_subtest($fh, $ex, $package, $ctor);
144 }
145  
146 1 print $fh "\ndone_testing();\n";
147 }
148  
149 # ---------------------------------------------------------------------------
150 # _emit_subtest — write one subtest block
151 # ---------------------------------------------------------------------------
152 1 ▶sub _emit_subtest {
Subroutine _emit_subtest: called CC=9 SCAR=29.2
153 1 my ($fh, $ex, $package, $ctor) = @_;
154  
155 1 my $label = $ex->{label};
156 1 my $code = $ex->{code};
157 1 my $expected = $ex->{expected};
158 1 my $is_annotated = defined $ex->{annotated_line};
159  
160 # Escape label for Perl string
161 1 (my $safe_label = $label) =~ s/'/\\'/g;
162  
163 1 print $fh "subtest '$safe_label' => sub {\n";
164  
165 1 ▶ if($is_annotated) {
Branch: 1 branch
BranchTrueFalseTotal
if ($is_annotated) { } 0 1 1
166 # Single annotated call: wrap in eval, capture return value, compare.
167 # Strip 'my $var =' prefix so the eval captures the bare expression
168 # value directly rather than shadowing with an inner variable.
169 0 my $expr = $code;
170 0 $expr =~ s/^\s*my\s+\$\w+\s*=\s*//;
171 0 $expr =~ s/\s*;\s*$//;
172  
173 0 ▶ my $n_tests = defined($expected) ? 2 : 1;
Branch: 1 branch
BranchTrueFalseTotal
defined $expected ? : 0 0 0
174 0 print $fh "\tplan tests => $n_tests;\n";
175  
176 0 ▶ if($ctor && $expr =~ /\$obj\s*->/) {
Branch: 1 branch
BranchTrueFalseTotal
if ($ctor and $expr =~ /\$obj\s*->/) 0 0 0
Condition0%0/3
$ctor and $expr =~ /\$obj\s*->/
!ll&&!rl&&r
000
MC/DC0%0/2
$ctor and $expr =~ /\$obj\s*->/
$ctor $expr =~ /\$obj\s*->/
Truth table0%0/3
A and B
A= $ctorB= $expr =~ /\$obj\s*->/
ABresult
0X0
100
111
177 0 print $fh "\tmy \$obj = $ctor;\n";
178 }
179  
180 0 print $fh "\tmy \$result = eval { $expr };\n";
181 0 print $fh "\tok(!\$\@, 'example runs without error') or diag \$\@;\n";
182  
183 0 ▶ if(defined $expected) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $expected) 0 0 0
184 0 print $fh "\tis(\$result, $expected, 'returns expected value from POD annotation');\n";
185 }
186 } else {
187 # Verbatim block: run whole block in eval, check no exception.
188 # Stub any variables the snippet uses but doesn't declare so the
189 # generated file compiles cleanly under "use strict".
190 1 print $fh "\tplan tests => 1;\n";
191 1 print $fh "\tmy \$ok = eval {\n";
192 1 my @stubs = _stub_undeclared_vars($code);
193 1 ▶ if(@stubs) {
Branch: 1 branch
BranchTrueFalseTotal
if (@stubs) 0 1 1
194 0 print $fh "\t\tmy (", join(', ', @stubs), ");\n";
195 }
196 1 for my $line (split /\n/, $code) {
197 2 ▶ if(my $neutralized = _neutralize_exec($line)) {
Branch: 1 branch
BranchTrueFalseTotal
if (my $neutralized = _neutralize_exec($line)) { } 1 1 2
198 1 print $fh "\t\t$neutralized\n";
199 } else {
200 1 print $fh "\t\t$line\n";
201 }
202 }
203 1 print $fh "\t\t1;\n";
204 1 print $fh "\t};\n";
205 1 print $fh "\tok(\$ok && !\$\@, 'example runs without error') or diag \$\@;\n";
206 }
207  
208 1 print $fh "};\n\n";
209 }
210  
211 # ---------------------------------------------------------------------------
212 # _neutralize_exec — if a line from a verbatim SYNOPSIS block would invoke
213 # a shell command (system, exec, backticks, qx), return a replacement
214 # note() call that describes what would have run instead of executing it.
215 # Returns the empty string (false) for safe lines so the caller can pass
216 # them through unchanged.
217 #
218 # Lines that are already comments are left alone — they can't execute.
219 # ---------------------------------------------------------------------------
220 2 ▶sub _neutralize_exec {
Subroutine _neutralize_exec: called CC=3 SCAR=11.0
221 2 my ($line) = @_;
222 2 ▶ return '' if $line =~ /^\s*#/; # pure comment — harmless
Branch: 1 branch
BranchTrueFalseTotal
if $line =~ /^\s*#/ 0 2 2
223 2 ▶ return '' unless $line =~ /\b(?:system|exec)\s*\(|`|\bqx\s*[{(\[\/|]/;
Branch: 1 branch
BranchTrueFalseTotal
unless $line =~ m<\b(?:system|exec)\s*\(|`|\bqx\s*[{(\[/|]> 1 1 2
224  
225 1 (my $msg = $line) =~ s/^\s+//; # strip leading whitespace for display
226 1 $msg =~ s/'/\\'/g; # escape single quotes for q{}
227 1 $msg =~ s/\s+$//;
228  
229 1 return "note('pod-example-tester: skipped shell call: $msg');";
230 }
231  
232 # ---------------------------------------------------------------------------
233 # _stub_undeclared_vars — return sorted list of sigil+name variables (e.g.
234 # '$dir', '@items') that appear in the code block but are not declared with
235 # my/our/local. Used to inject stub declarations so generated eval blocks
236 # compile cleanly under "use strict" even when SYNOPSIS snippets assume
237 # surrounding context (e.g. a $dir variable set up by the caller).
238 #
239 # Well-known Perl builtins (@_, @INC, @ARGV, %ENV, %INC, %SIG, $_) are
240 # excluded because they exist without explicit declaration.
241 # ---------------------------------------------------------------------------
242 {
243 1 my %PERL_BUILTINS = map { $_ => 1 } qw(
244 $_ @_ @INC @ARGV %ENV %INC %SIG
245 );
246  
247 1 ▶ sub _stub_undeclared_vars {
Subroutine _stub_undeclared_vars: called CC=4 SCAR=13.9
248 1 my ($code) = @_;
249  
250 1 my %declared;
251 # Capture every variable following a my/our/local keyword, including
252 # list forms: my ($a, $b) and foreach my $x(...)
253 1 ▶ while($code =~ /\b(?:my|our|local)\b[^;{]*?([\$\@\%]\w+)/g) {
Branch: 1 branch
BranchTrueFalseTotal
if ($code =~ /\b(?:my|our|local)\b[^;{]*?([\$\@\%]\w+)/g) 1 1 2
254 1 $declared{$1} = 1;
255 }
256  
257 1 my %used;
258 1 ▶ while($code =~ /([\$\@\%])([a-zA-Z_]\w*)/g) {
Branch: 1 branch
BranchTrueFalseTotal
if ($code =~ /([\$\@\%])([a-zA-Z_]\w*)/g) 1 1 2
259 1 $used{"$1$2"} = 1;
260 }
261  
262 1 ▶ return sort grep { !$declared{$_} && !$PERL_BUILTINS{$_} } keys %used;
Condition33%1/3
$declared{$_} || $PERL_BUILTINS{$_}
l!l&&r!l&&!r
100
MC/DC0%0/2
$declared{$_} || $PERL_BUILTINS{$_}
$declared{$_} $PERL_BUILTINS{$_}
Truth table33%1/3
A || B
A= $declared{$_}B= $PERL_BUILTINS{$_}
ABresult
1X1
011
000
263 }
264 }
265  
266 # ---------------------------------------------------------------------------
267 # _detect_package — extract 'package Foo::Bar' from source
268 # ---------------------------------------------------------------------------
269 1 ▶sub _detect_package {
Subroutine _detect_package: called CC=4 SCAR=15.2
270 1 my ($file) = @_;
271 1 ▶ open my $fh, '<', $file or return;
Branch: 1 branch
BranchTrueFalseTotal
open my $fh, "<", $file or return 1 0 1
272 1 ▶ while(<$fh>) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined($_ = readline $fh)) 1 0 1
273 1 ▶ return $1 if /^package\s+([\w:]+)\s*[;{]/;
Branch: 1 branch
BranchTrueFalseTotal
if /^package\s+([\w:]+)\s*[;{]/ 1 0 1
274 }
275 0 return;
276 }
277  
278 # ---------------------------------------------------------------------------
279 # _detect_constructor — return a string like 'Foo::Bar->new()' if the
280 # package has a new() method, else undef
281 # ---------------------------------------------------------------------------
282 1 ▶sub _detect_constructor {
Subroutine _detect_constructor: called CC=3 SCAR=13.5
283 1 my ($package) = @_;
284  
285 # Try loading and querying can()
286 1 eval { (my $mod = $package) =~ s{::}{/}g; require "$mod.pm" };
287 1 ▶ return unless !$@;
Branch: 1 branch
BranchTrueFalseTotal
if $@ 1 0 1
288 0 ▶ return "${package}->new()" if $package->can('new');
Branch: 1 branch
BranchTrueFalseTotal
if $package->can("new") 0 0 0
289 0 return;
290 }
291  
292 __END__
« lib/App/Test/Generator/Mutation/NumericBoundary.pm ↑ Summary lib/App/Test/Generator/Mutator.pm »