POD Testing

[ Perl tips index ]
[ Subscribe to Perl tips ]

Is there any sexier topic in software development than software testing? That is, besides game programming, 3D graphics, audio, high-performance clustering, cool websites, et cetera? Okay, so software testing is low on the list.

-- Perl Testing: A Developer's Notebook

When software developers are rushed, both testing and documentation tends to suffer. However these two areas are of critical importance when it comes to maintaining and improving the software. Wouldn't it be great if there was an easy way for developers start their test suites and ensure they have good documentation at the same time?

While there aren't any Perl modules that can ensure that your documentation is correct, there are modules that exist to make sure that you have at least documented your interface, and that your documentation syntax is correct. In this Perl Tip we will examine these modules and how they can be used to write a basic test suite for your documentation.

Test::Pod

Test::Pod lets you check the validity of a POD file. While perldoc and many of the other POD tools will be fairly forgiving when it comes to reading your POD, you're much more likely to avoid strange results if you do things correctly.

Test::Pod reports its results in the standard Test::Simple fashion using TAP output. This means that it fits in nicely with any other tests your test suite contains. To use it, add the following test to your test suite, and it'll ensure that the pod in your Perl files is valid. You can either pass the all_pod_files_ok() a list of directories to search through, or have it default to blib/.

        #!/usr/bin/perl
        use Test::Pod 1.00;
        all_pod_files_ok();
        __END__

A Perl file is considered to be any file which ends in .PL, .pl, .pm, .pod, or .t, or a file which starts with a shebang (#!) and includes the word perl.

Test::Pod::Coverage

Test::Pod::Coverage checks that your module documentation is comprehensive. It makes sure that there's either a =headX or an =item block documenting each public subroutine. If it cannot find documentation for a given subroutine, then it will fail.

Like Test::Pod, Test::Pod::Coverage should fit straight into your test suite. To use it, add the following test to your test suite:

        #!/usr/bin/perl
        use Test::Pod::Coverage;
        all_pod_coverage_ok;
        __END__

Private subroutines (those which start with an underscore) are not tested for documentation as they are not considered to be part of the module's application interface.

Trying it out

To see how easily this all works, try the following. Create a module distribution using:

        h2xs -XA -n Acme::Example

(See our tip on Starting modules with h2xs for more details). Create two test files in the t/ directory with the above examples in them. For example pod_valid.t and pod_coverage.t.

Build your module and run the tests:

        perl Makefile.PL
        make
        make test

This should result in output like:

 PERL_DL_NONLAZY=1 /usr/bin/perl "-MExtUtils::Command::MM" "-e"
 "test_harness(0, 'blib/lib', 'blib/arch')" t/*.t
 t/Acme-Example....ok                                                         
 t/pod_coverage....ok                                                         
 t/pod_valid.......ok                                                         
 All tests successful.
 Files=3, Tests=3,  1 wallclock secs ( 0.28 cusr +  0.01 csys =  0.29 CPU)

Add a test subroutine in your module (eg lib/Acme/Example.pm) without documentation, and re-run the tests, to see the pod coverage fail:

 PERL_DL_NONLAZY=1 /usr/bin/perl "-MExtUtils::Command::MM" "-e" "test_harness(0, 'blib/lib', 'blib/arch')" t/*.t
 t/Acme-Example....ok                                                         
 t/pod_coverage....NOK 1#     Failed test (/usr/share/perl5/Test/Pod/Coverage.pm at line 112)
 # Coverage for Acme::Example is 0.0%, with 1 naked subroutine:
 #       undocumented_sub
 # Looks like you failed 1 tests of 1.
 t/pod_coverage....dubious                                                    
         Test returned status 1 (wstat 256, 0x100)
 DIED. FAILED test 1
         Failed 1/1 tests, 0.00% okay
 t/pod_valid.......ok                                                         
 Failed Test      Stat Wstat Total Fail  Failed  List of Failed
 -------------------------------------------------------------------------------
 t/pod_coverage.t    1   256     1    1 100.00%  1
 Failed 1/3 test scripts, 66.67% okay. 1/3 subtests failed, 66.67% okay.
 make: *** [test_dynamic] Error 255

[ Perl tips index ]
[ Subscribe to Perl tips ]

This Perl tip and associated text is copyright Perl Training Australia. You may freely distribute this text so long as it is distributed in full with this Copyright noticed attached.

If you have any questions please don't hesitate to contact us:

Copyright 2001-2012 Perl Training Australia. Contact us at contact@perltraining.com.au