Test::Pod::LinkCheck::Lite - Test POD links
use Test::More 0.88; # for done_testing(); use Test::Pod::LinkCheck::Lite; my $t = Test::Pod::LinkCheck::Lite->new(); $t->all_pod_files_ok(); done_testing;
This Perl module tests POD links. A given file generates one failure for each broken link found. If no broken links are found, one passing test is generated. This all means that there is no way to know how many tests will be generated, and you will need to use Test::More's done_testing() (or something equivalent) at the end of your test.
done_testing()
By its nature this module should be used only for author testing. The problem with using it in an installation test is that the validity of links external to the distribution being tested varies with things like operating system type and version, Perl version, installed Perl modules and their versions, and the Internet at large. Caveat user.
This module should probably be considered alpha-quality code at this point. It checks most of my modest corpus (correctly, I hope), but beyond that deponent sayeth not.
This module started its life as a low-dependency version of Test::Pod::LinkCheck. Significant differences from that module include:
This module shells out only to check man links.
man
That is, a skipped test is generated for each. Note that Test::Pod::LinkCheck appears to fail the link in at least some such cases.
This seemed to be an easy enough addition.
Given at least Perl 5.13.9, the only non-core module used is B::Keywords.
POD links come in the following flavors:
These links are of the form L<manpage (section)>. They will only be checked if the man attribute is true, and can only be successfully checked if the man command actually displays man pages, and man -w can be executed.
L<manpage (section)>
man -w
url
These links are of the form L<http://...> (or https: or whatever). They will only be checked if the check_url attribute is true, and can only be successfully checked if Perl has access to the specified URL.
L<http://...>
https:
check_url
pod (internal)
These links are of the form L<text|/section>. They are checked using the parse tree in which the link was found.
L<text|/section>
pod (external)
This is pretty much everything else. There are a number of cases, and the only way to distinguish them is to run through them.
These links are of the form L<text|builtin>> or L<builtin>, and are checked against the lists in B::Keywords.
L<text|builtin>>
L<builtin>
These are resolved to a file using Pod::Perldoc. If a section was specified, the file is parsed to determine whether the section name is valid.
These are checked against modules/02packages.details.txt.gz, provided that (or some reasonable facsimile) can be found. Currently we can look for this information in the following places:
CPAN
If more than one of these is configured (by default they all are), we look in the newest one.
Sections can not be checked. If a link to a valid (but uninstalled) module has a section, a skipped test is generated.
The ::Lite refers to the fact that a real effort has been made to reduce non-core dependencies. Under Perl 5.14 and up, the only known non-core dependencies are B::Keywords and Pod::Simple::SimpleTree.
::Lite
An effort has also been made to minimize the spawning of system commands.
This class supports the following public methods:
my $t = Test::Pod::LinkCheck::Lite->new();
This static method instantiates an object. Optional arguments are passed as name/value pairs.
The following arguments are supported:
This argument is the user agent string to use for web access.
The default is that of HTTP::Tiny.
This Boolean argument is true if the sections of links outside the current Pod are to be checked. If it is false, such sections are not checked, and the link is considered valid if the external Pod exists at all.
The default is true.
This Boolean argument is true if url links are to be checked, and false if not.
This argument specifies one or more URLs to ignore when checking url links. It can be specified as:
Regexp
Any URL that matches this Regexp is ignored.
undef
No URLs are ignored.
This URL is ignored.
The URL referred to is ignored.
The URL is ignored if the hash contains a true value for the URL.
The code is called with the URL to ignore in the topic variable (a.k.a. $_). The URL is ignored if the code returns a true value.
$_
ARRAY
The array can contain any legal ignore specification, and any URL that matches any value in the array is ignored. Nested arrays are flattened.
The default is [].
[]
Note that the order in which the individual checks are made is undefined. OK, the implementation is deterministic, but the order of evaluation is an implementation detail that the author reserves the right to change without warning.
This Boolean argument is true if man links are to be checked, and false if not. The default is the value of IPC::Cmd::can_run( 'man' ). If this returns false a warning is generated, and man links are not checked.
IPC::Cmd::can_run( 'man' )
This argument specifies a list of module indices to consult, as either a comma-delimited string or an array reference. Even if specified a given index will only be used if it is actually available for use. If more than one index is found, the most-recently-updated index will be used. Possible indices are:
Use the module index found in the CPAN working directory.
Use the CPAN Meta database. Because this is an on-line index it is considered to be current, but its as-of time is offset to favor local indices.
By default all indices are considered.
This Boolean argument is true to disable the uninstalled module checks. This means links to modules not installed on the system will fail, even if the module exists.
By default this is false.
This method returns the value of the 'agent' attribute.
'agent'
$t->all_pod_files_ok();
This method takes as its arguments the names of one or more files, and tests any such that are deemed to be Perl files. Directories are recursed into.
Perl files are considered to be all text files whose names end in .pod, .pm, or .PL, plus any text files with a shebang line containing 'perl'. File name suffixes are case-sensitive except for .PL.
'perl'
If no arguments are specified, the contents of blib/ are tested. This is the recommended usage.
If called in scalar context, this method returns the number of test failures encountered. If called in list context it return the number of failures, passes, and skipped tests, in that order.
$t->check_external_sections() and say 'Sections in external links are checked';
This method returns the value of the 'check_url' attribute.
'check_url'
$t->check_url() and say 'URL links are checked';
print 'Ignored URLs ', join ', ', $t->ignore_url();
This method returns the value of the 'ignore_url' attribute. If called in scalar context, it returns an array reference. If called in list context it returns an array. Either way, the results will not be in the same order as originally specified to new().
'ignore_url'
$t->man() and say 'man links are checked';
This method returns the value of the 'man' attribute.
'man'
say 'Module indices: ', join ', ', $self->module_index();
This method returns the value of the 'module_index' attribute. If called in scalar context it returns a comma-delimited string.
'module_index'
my $failures = $t->pod_file_ok( 'lib/Foo/Bar.pm' );
This method tests the links in the given file. Each failure appears in the TAP output as a test failure. If no failures are found, a passing test will appear in the TAP output.
$t->require_installed() and say 'All POD links must be to installed modules';
This method returns the value of the 'require_installed' attribute.
'require_installed'
Test::Pod::LinkCheck by Apocalypse (APOCAL) checks all POD links except for URLs. It is Moose-based.
APOCAL
Test::Pod::Links by Sven Kirmess (SKIRMESS) checks all URLs or URL-like things in the document, whether or not they are actual POD links.
SKIRMESS
Test::Pod::No404s by Apocalypse (APOCAL) checks URL POD links.
The author would like to acknowledge the following, without whom this module would not exist -- at least, not in anything like its current form.
Mohammed Anwar (MANWAR) who submitted the "broken POD link" ticket that started me thinking about testing for this kind of thing.
MANWAR
The CPAN Testers who, by testing my code under such a broad range of configurations, gave me an opportunity to make this module much more robust than it would otherwise have been. It is probably unfair to single out individual testers, but as the luck of the testing cycle would have it, results from Andreas J. König (ANDK), Slaven Rezić (SREZIC), and Chris Williams (BINGOS) were particularly useful to me.
ANDK
SREZIC
BINGOS
Support is by the author. Please file bug reports at http://rt.cpan.org, or in electronic mail to the author.
Thomas R. Wyant, III wyant at cpan dot org
Copyright (C) 2019 by Thomas R. Wyant, III
This program is free software; you can redistribute it and/or modify it under the same terms as Perl 5.10.0. For more details, see the full text of the licenses in the directory LICENSES.
This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose.
To install Test::Pod::LinkCheck::Lite, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Test::Pod::LinkCheck::Lite
CPAN shell
perl -MCPAN -e shell install Test::Pod::LinkCheck::Lite
For more information on module installation, please visit the detailed CPAN module installation guide.