NAME Test::Pod::Links - Test Pod for invalid HTTP/S links VERSION Version 0.002 SYNOPSIS use Test::Pod::Links; Test::Pod::Links->new->all_pod_files_ok; DESCRIPTION Tests that all HTTP/S links from Pod documentation are reachable by calling the head method of HTTP::Tiny on them. All non HTTP/S links are ignored. You can check them with Test::Pod::LinkCheck. This test is an author test and should not run on end-user installations. Recommendation is to put it into your xt instead of your t directory. USAGE new( [ ARGS ] ) Returns a new Test::Pod::Link instance. new takes an optional hash ref with its arguments. Test::Pod::Links->new({ ignore => 'url_to_ignore', ignore_match => qr{url to ignore}, ua => HTTP::Tiny->new, }); The following arguments are supported: ignore (optional) The ignore argument is either a string or an array ref of strings. URLs that match one of these strings are not checked. The comparison is done case-sensitive. This can be used to exclude URLs that are known to not work like http://www.example.com/. (But if a link doesn't work it most likely shouldn't be in an L tag anyway.) ignore_match (optional) The ignore_match argument is either a regex or an array ref of regexes. URLs that match one of these regexes are not checked. ua (optional) The ua argument is used to supply your own, HTTP::Tiny compatible, user agent. Use this if you need a special configured HTTP::Tiny user agent. pod_file_ok( FILENAME ) This will run a test for parsing the Pod and another test for every web link found in the Pod. It is therefore unlikely to know the exact number of tests that will run in advance. Use done_testing from Test::More if you call this test directly instead of a plan. pod_file_ok returns something true if all web links are reachable and false otherwise. all_pod_files_ok( [ @entries ] ) Checks all the web links in all files under @entries by calling pod_file_ok on every file. Directories are recursive searched for files containing Pod. Everything not a file and not a directory (e.g. a symlink) is ignored. It calls done_testing or skip_all so you can't have already called plan. If @entries is empty default directories are searched for files containing Pod. The default directories are blib, or lib if it doesn't exist, bin and script. The method contains_pod from Pod::Simple::Search is used to identify files that contain Pod. returns something true if all web links are reachable and false otherwise. EXAMPLES Example 1 Default Usage Check the web links in all files in the bin, script and lib directory. use 5.006; use strict; use warnings; use Test::Pod::Links; if ( exists $ENV{AUTOMATED_TESTING} ) { print "1..0 # SKIP these tests during AUTOMATED_TESTING\n"; exit 0; } Test::Pod::Links->new->all_pod_files_ok; Example 2 Check non-default directories or files use 5.006; use strict; use warnings; use Test::Pod::Links; if ( exists $ENV{AUTOMATED_TESTING} ) { print "1..0 # SKIP these tests during AUTOMATED_TESTING\n"; exit 0; } Test::Pod::Links->new->all_pod_files_ok(qw( corpus/7_links.pod corpus/hello lib tools )); Example 3 Specify a different user agent for HTTP::Tiny use 5.006; use strict; use warnings; use Test::Pod::Links; use HTTP::Tiny; if ( exists $ENV{AUTOMATED_TESTING} ) { print "1..0 # SKIP these tests during AUTOMATED_TESTING\n"; exit 0; } Test::Pod::Links->new( ua => HTTP::Tiny->new( agent => 'Mozilla/5.0', ), )->all_pod_files_ok; Example 4 Exclude a URL use 5.006; use strict; use warnings; use Test::Pod::Links; if ( exists $ENV{AUTOMATED_TESTING} ) { print "1..0 # SKIP these tests during AUTOMATED_TESTING\n"; exit 0; } Test::Pod::Links->new( ignore => 'http://example.com/index.html', )->all_pod_files_ok; Example 5 Exclude all urls for a domain use 5.006; use strict; use warnings; use Test::Pod::Links; if ( exists $ENV{AUTOMATED_TESTING} ) { print "1..0 # SKIP these tests during AUTOMATED_TESTING\n"; exit 0; } Test::Pod::Links->new( ignore_match => qr{ # We are going to exclude every URL that uses a host in the # example.com domain. ^ # begin of string (?: (?i) http (?:s)? ) # case-insensitive match of http # and https :// # the protocol delimiter (?: [^/]* [.] )? # this matches any hostname (or none) example[.]com # the domain example.com (?: / | $ ) # After the domain we get either a / # or nothing }x, )->all_pod_files_ok; Example 6 Call pod_file_ok directly use 5.006; use strict; use warnings; use Test::More 0.88; use Test::Pod::Links; if ( exists $ENV{AUTOMATED_TESTING} ) { print "1..0 # SKIP these tests during AUTOMATED_TESTING\n"; exit 0; } my $tpl = Test::Pod::Links->new; $tpl->pod_file_ok('corpus/7_links.pod'); $tpl->pod_file_ok('corpus/hello'); done_testing(); RATIONALE Why this instead of Test::Pod::No404s? This module is much like Test::Pod::No404s. It checks that HTTP/S links in your Pod are valid. There are a few differences to Test::Pod::No404s: * Test::Pod::No404s does not cache the result. If you add a link to your github repository in every .pm file it will verify the same link for every module by connecting to the same URL again and again. That is slow, excessive and not very nice to the web server. Test::Pod::Links caches the result of every request only issuing a head request once for every URL. * Test::Pod::No404s converts the Pod to text and then checks everything that looks like a web URL which will pick up things that look like a URL but are not a link. Test::Pod::Links only checks HTTP/S links inside an L tag. * Test::Pod::Links supports a ua argument with the new method that allows you to pass a custom, HTTP::Tiny compatible, user agent to it. It can also be used to configure HTTP::Tiny to your liking, e.g. configuring the user-agent string. * Test::Pod::No404s uses a hard coded list of hostnames to ignore, with Test::Pod::Links you have the ignore and ignore_match option to decide which URLs to skip over. SEE ALSO HTTP::Tiny, Test::More, Test::Pod::LinkCheck, Test::Pod::No404s SUPPORT Bugs / Feature Requests Please report any bugs or feature requests through the issue tracker at https://github.com/skirmess/Test-Pod-Links/issues. You will be notified automatically of any progress on your issue. Source Code This is open source software. The code repository is available for public review and contribution under the terms of the license. https://github.com/skirmess/Test-Pod-Links git clone https://github.com/skirmess/Test-Pod-Links.git AUTHOR Sven Kirmess COPYRIGHT AND LICENSE This software is Copyright (c) 2018 by Sven Kirmess. This is free software, licensed under: The (two-clause) FreeBSD License