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.

    <all_pod_files_ok> 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 <sven.kirmess@kzone.ch>

COPYRIGHT AND LICENSE

    This software is Copyright (c) 2018 by Sven Kirmess.

    This is free software, licensed under:

      The (two-clause) FreeBSD License