lib/Test/Pod/Links.pm

filter: Statementstmt 100% 146 / 146 Branchbran 100% 60 / 60 Conditioncond 80.9% 17 / 21 MC/DCmcdc 61.5% 8 / 13 Subroutinesub 100% 17 / 17 Podpod 100% 3 / 3 totaltotal 96.5% 251 / 260 CC 42 SCAR 20.0
CC
42
Cov
98%
pod_file_ok
12.0
new
12.0
_extract_links_from_pod
7.0
CRAP 7.4
↑ Summary
1 # vim: ts=4 sts=4 sw=4 et: syntax=perl
2 #
3 # Copyright (c) 2018-2026 Sven Kirmess
4 #
5 # Permission to use, copy, modify, and distribute this software for any
6 # purpose with or without fee is hereby granted, provided that the above
7 # copyright notice and this permission notice appear in all copies.
8 #
9 # THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
10 # WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11 # MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
12 # ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13 # WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
14 # ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15 # OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
16  
17 12 ▶use 5.006;
Subroutine BEGIN: called CC=1 SCAR=0.0
18 12 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
19 12 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
20  
21 package Test::Pod::Links;
22  
23 12 our $VERSION = '0.004';
24  
25 12 ▶use Carp ();
Subroutine BEGIN: called CC=1 SCAR=0.0
26 12 ▶use HTTP::Tiny 0.014 ();
Subroutine BEGIN: called CC=1 SCAR=0.0
27 12 ▶use Pod::Simple::Search ();
Subroutine BEGIN: called CC=1 SCAR=0.0
28 12 ▶use Pod::Simple::SimpleTree ();
Subroutine BEGIN: called CC=1 SCAR=0.0
29 12 ▶use Scalar::Util ();
Subroutine BEGIN: called CC=1 SCAR=0.0
30 12 ▶use Test::Builder ();
Subroutine BEGIN: called CC=1 SCAR=0.0
31 12 ▶use Test::XTFiles ();
Subroutine BEGIN: called CC=1 SCAR=0.0
32  
33 12 my $TEST = Test::Builder->new();
34  
35 # - Do not use subtests because subtests cannot be tested with
36 # Test::Builder:Tester.
37 # - Do not use a plan because a method that sets a plan cannot be tested
38 # with Test::Builder:Tester.
39 # - Do not call done_testing in a method that should be tested by
40 # Test::Builder::Tester because TBT cannot test them.
41  
42 6 ▶sub all_pod_files_ok {
Subroutine all_pod_files_ok: called CC=6 SCAR=17.9
Pod documented
43 6 my ($self) = @_;
44  
45 6 my @files = Test::XTFiles->new->all_files();
46 6 ▶ if ( !@files ) {
Branch: 1 branch
BranchTrueFalseTotal
unless (@files) 1 5 6
47 1 $TEST->skip_all("No files found\n");
48 1 return 1;
49 }
50  
51 5 my @pod_files = grep { Pod::Simple::Search->new->contains_pod($_) } @files;
52 5 ▶ if ( !@pod_files ) {
Branch: 1 branch
BranchTrueFalseTotal
unless (@pod_files) 2 3 5
53 2 $TEST->skip_all("No files with Pod found\n");
54 2 return 1;
55 }
56  
57 3 my $rc = 1;
58 3 for my $file (@pod_files) {
59 4 ▶ if ( !$self->pod_file_ok($file) ) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($self->pod_file_ok($file)) 1 3 4
60 1 $rc = 0;
61 }
62 }
63  
64 3 $TEST->done_testing;
65  
66 3 ▶ return 1 if $rc;
Branch: 1 branch
BranchTrueFalseTotal
if $rc 2 1 3
67 1 return;
68 }
69  
70 39 ▶sub new {
Subroutine new: called CC=12 SCAR=24.9
Pod documented
71 39 my $class = shift;
72  
73 39 ▶ Carp::croak 'Odd number of arguments' if @_ % 2;
Branch: 1 branch
BranchTrueFalseTotal
if @_ % 2 1 38 39
74 38 my %args = @_;
75  
76 38 my $self = bless {}, $class;
77  
78 #
79 38 $self->{_cache} = {};
80  
81 #
82 38 ▶ $self->_ua( $args{ua} || HTTP::Tiny->new );
Condition66%2/3
$args{'ua'} || 'HTTP::Tiny'->new
l!l&&r!l&&!r
16220
MC/DC0%0/2
$args{'ua'} || 'HTTP::Tiny'->new
$args{'ua'} 'HTTP::Tiny'->new
Truth table66%2/3
A || B
A= $args{'ua'}B= 'HTTP::Tiny'->new
ABresult
1X1
011
000
83  
84 #
85 37 my @ignores;
86 37 ▶ if ( exists $args{ignore} ) {
Branch: 1 branch
BranchTrueFalseTotal
if (exists $args{"ignore"}) 7 30 37
87 7 my $ignore = $args{ignore};
88 7 ▶ if ( ref $ignore eq ref [] ) {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $ignore eq ref []) { } 2 5 7
89 2 @ignores = @{$ignore};
90 }
91 else {
92 5 @ignores = $ignore;
93 }
94 }
95  
96 #
97 37 my @ignores_match;
98 37 ▶ if ( exists $args{ignore_match} ) {
Branch: 1 branch
BranchTrueFalseTotal
if (exists $args{"ignore_match"}) 8 29 37
99 8 my $ignore_match = $args{ignore_match};
100 8 ▶ if ( ref $ignore_match eq ref [] ) {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $ignore_match eq ref []) { } 4 4 8
101 4 @ignores_match = @{$ignore_match};
102 }
103 else {
104 4 @ignores_match = $ignore_match;
105 }
106 }
107  
108 ## no critic (RegularExpressions::RequireDotMatchAnything)
109 ## no critic (RegularExpressions::RequireExtendedFormatting)
110 ## no critic (RegularExpressions::RequireLineBoundaryMatching)
111 37 my $ignore_regex = join q{|}, @ignores_match, map { qr{^\Q$_\E$} } @ignores;
112 37 ▶ $self->_ignore_regex( $ignore_regex ne q{} ? qr{$ignore_regex} : undef );
Branch: 1 branch
BranchTrueFalseTotal
$ignore_regex ne '' ? : 12 25 37
113 ## use critic
114  
115 KEY:
116 37 for my $key ( keys %args ) {
117 28 ▶ next KEY if $key eq 'ignore';
Branch: 1 branch
BranchTrueFalseTotal
if $key eq "ignore" 6 22 28
118 22 ▶ next KEY if $key eq 'ignore_match';
Branch: 1 branch
BranchTrueFalseTotal
if $key eq "ignore_match" 7 15 22
119 15 ▶ next KEY if $key eq 'ua';
Branch: 1 branch
BranchTrueFalseTotal
if $key eq "ua" 14 1 15
120  
121 1 Carp::croak "new() knows nothing about argument '$key'";
122 }
123  
124 36 return $self;
125 }
126  
127 18 ▶sub pod_file_ok {
Subroutine pod_file_ok: called CC=12 SCAR=24.9
Pod documented
128 18 my ( $self, $file ) = @_;
129  
130 18 ▶ Carp::croak 'usage: pod_file_ok(FILE)' if @_ != 2 || !defined $file;
Branch: 1 branch
BranchTrueFalseTotal
if @_ != 2 or not defined $file 3 15 18
Condition100%3/3
@_ != 2 or not defined $file
l!l&&r!l&&!r
2115
MC/DC100%2/2
@_ != 2 or not defined $file
@_ != 2 not defined $file
Truth table100%3/3
A or not(B)
A= @_ != 2B= not defined $file
ABresult
1X1
011
000
131  
132 15 my $parse_msg = "Parse Pod ($file)";
133  
134 15 ▶ if ( !-f $file ) {
Branch: 1 branch
BranchTrueFalseTotal
unless (-f $file) 1 14 15
135 1 $TEST->ok( 0, $parse_msg );
136 1 $TEST->diag("\n");
137 1 $TEST->diag("File $file does not exist or is not a file");
138 1 return;
139 }
140  
141 14 my $pod = Pod::Simple::SimpleTree->new->parse_file($file);
142  
143 14 ▶ if ( $pod->any_errata_seen ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($pod->any_errata_seen) 1 13 14
144  
145 # Pod contains errors
146 1 $TEST->ok( 0, $parse_msg );
147 1 return;
148 }
149  
150 13 $TEST->ok( 1, $parse_msg );
151  
152 my @links =
153 35 ▶ grep { defined && m{ ^ http(?:s)? :// }xsmi }
Condition33%1/3
defined $_ && m[ ^ http(?:s)? :// ]imsx
!ll&&!rl&&r
0035
MC/DC0%0/2
defined $_ && m[ ^ http(?:s)? :// ]imsx
defined $_ m[ ^ http(?:s)? :// ]imsx
Truth table33%1/3
A && B
A= defined $_B= m[ ^ http(?:s)? :// ]imsx
ABresult
0X0
100
111
154 35 map { ${ $_->{to} }[2] }
155 13 grep { $_->{type} eq 'url' } $self->_extract_links_from_pod( $pod->root );
156  
157 13 my $ignore_regex = $self->_ignore_regex;
158 13 ▶ if ( defined $ignore_regex ) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $ignore_regex) 3 10 13
159 3 @links = grep { $_ !~ $ignore_regex } @links;
160 }
161  
162 13 my $rc = 1;
163 13 my %url_checked_in_this_file;
164  
165 LINK:
166 13 for my $link (@links) {
167 29 ▶ next LINK if exists $url_checked_in_this_file{$link};
Branch: 1 branch
BranchTrueFalseTotal
if exists $url_checked_in_this_file{$link} 2 27 29
168 27 $url_checked_in_this_file{$link} = 1;
169  
170 27 ▶ if ( !exists $self->{_cache}->{$link} ) {
Branch: 1 branch
BranchTrueFalseTotal
unless (exists $self->{"_cache"}{$link}) 24 3 27
171 24 $self->{_cache}->{$link} = $self->_check_url($link);
172 }
173 27 my $res = $self->{_cache}->{$link};
174  
175 27 $TEST->ok( $res->{success}, "$link ($file)" );
176  
177 27 ▶ if ( !$res->{success} ) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($res->{"success"}) 4 23 27
178 4 $rc = 0;
179 4 $TEST->diag("\n");
180 4 $TEST->diag( $res->{reason} );
181 4 $TEST->diag("\n");
182 }
183 }
184  
185 13 ▶ return 1 if $rc;
Branch: 1 branch
BranchTrueFalseTotal
if $rc 9 4 13
186 4 return;
187 }
188  
189 # Some web servers do not answer HEAD requests, e.g. news.ycombinator.com
190 # replies with a '405 Not Allowed', but serve the very same URL without a
191 # complaint on a GET request. Retry such a link with GET before we report it
192 # as broken.
193 #
194 # HTTP::Tiny uses the status 599 to signal an internal error, e.g. a failed
195 # connection or a timeout. In that case we never received a response from a
196 # server and a GET request would only run into the same error again, which is
197 # why we don't retry these.
198 #
199 # The response of the last request we made is the one we report, because that
200 # is the one that describes why we consider the link broken.
201 24 ▶sub _check_url {
Subroutine _check_url: called CC=5 SCAR=16.1
202 24 my ( $self, $url ) = @_;
203  
204 24 my $ua = $self->_ua;
205 24 my $res = $ua->head($url);
206  
207 24 ▶ return $res if $res->{success};
Branch: 1 branch
BranchTrueFalseTotal
if $res->{"success"} 19 5 24
208 5 ▶ return $res if defined $res->{status} && $res->{status} == 599;
Branch: 1 branch
BranchTrueFalseTotal
if defined $res->{"status"} and $res->{"status"} == 599 2 3 5
Condition66%2/3
defined $res->{"status"} and $res->{"status"} == 599
!ll&&!rl&&r
032
MC/DC50%1/2
defined $res->{"status"} and $res->{"status"} == 599
defined $res->{"status"} $res->{"status"} == 599
Truth table66%2/3
A and B
A= defined $res->{"status"}B= $res->{"status"} == 599
ABresult
0X0
100
111
209 3 ▶ return $res if !$ua->can('get');
Branch: 1 branch
BranchTrueFalseTotal
unless $ua->can("get") 1 2 3
210  
211 2 return $ua->get($url);
212 }
213  
214 159 ▶sub _extract_links_from_pod {
Subroutine _extract_links_from_pod: called CC=7 SCAR=19.5
215 159 my ( $self, $node_ref ) = @_;
216  
217 159 ▶ Carp::croak 'usage: _extract_links_from_pod([ elementname, \%attributes, ...subnodes... ])' if @_ != 2 || ref $node_ref ne ref [] || scalar @{$node_ref} < 2;
Branch: 1 branch
BranchTrueFalseTotal
if @_ != 2 or ref $node_ref ne ref [] or scalar @{$node_ref;} < 2 4 155 159
Condition100%6/6
@_ != 2 or ref $node_ref ne ref [] or scalar @{$node_ref;} < 2
l!l&&r!l&&!r
31155
@_ != 2 or ref $node_ref ne ref []
l!l&&r!l&&!r
21156
MC/DC100%3/3
@_ != 2 or ref $node_ref ne ref [] or scalar @{$node_ref;} < 2
@_ != 2 ref $node_ref ne ref [] scalar @{$node_ref;} < 2
Truth table100%4/4
A or B or C
A= @_ != 2B= ref $node_ref ne ref []C= scalar @{$node_ref;} < 2
ABCresult
1XX1
01X1
0011
0000
218  
219 155 my @links;
220 155 my ( $elem_name, $attr_ref, @subnodes ) = @{$node_ref};
221  
222 155 ▶ if ( $elem_name eq 'L' ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($elem_name eq "L") 51 104 155
223 51 push @links, $attr_ref;
224 }
225  
226 SUBNODE:
227 155 for my $subnode (@subnodes) {
228 314 ▶ next SUBNODE if ref $subnode ne ref [];
Branch: 1 branch
BranchTrueFalseTotal
if ref $subnode ne ref [] 175 139 314
229  
230 139 push @links, $self->_extract_links_from_pod($subnode);
231 }
232  
233 155 return @links;
234 }
235  
236 92 ▶sub _ignore_regex {
Subroutine _ignore_regex: called CC=2 SCAR=6.9
237 92 my $self = shift;
238  
239 92 ▶ if (@_) {
Branch: 1 branch
BranchTrueFalseTotal
if (@_) 39 53 92
240 39 my $ignore_regex = shift;
241 39 $self->{_ignore_regex} = $ignore_regex;
242 }
243  
244 92 return $self->{_ignore_regex};
245 }
246  
247 68 ▶sub _ua {
Subroutine _ua: called CC=4 SCAR=13.9
248 68 my $self = shift;
249  
250 68 ▶ if (@_) {
Branch: 1 branch
BranchTrueFalseTotal
if (@_) 42 26 68
251 42 my $ua = shift;
252 42 ▶ Carp::croak q{ua must have method 'head'} if !Scalar::Util::blessed($ua) || !$ua->can('head');
Branch: 1 branch
BranchTrueFalseTotal
unless builtin::blessed($ua) and $ua->can("head") 3 39 42
Condition100%3/3
builtin::blessed($ua) and $ua->can("head")
!ll&&!rl&&r
2139
MC/DC100%2/2
builtin::blessed($ua) and $ua->can("head")
builtin::blessed($ua) $ua->can("head")
Truth table100%3/3
A and B
A= builtin::blessed($ua)B= $ua->can("head")
ABresult
0X0
100
111
253 39 $self->{_ua} = $ua;
254 }
255  
256 65 return $self->{_ua};
257 }
258  
259 12 1;
260  
261 __END__
↑ Summary