18.5. Testing POD
We can even test things that aren't code. Documentation is just as important as code, since other people can't use our perfect, lovely code unless they know what to do with it. As we mentioned in Chapter 16, the Perl way to document code is by embedding POD formatted text in the code. Tools such as perldoc can extract the POD and display it in a variety of formats.
What if we mess up the POD format so that formatters can't parse it as we intended? To solve this problem, brian wrote Test::Pod to go through his modules looking for POD errors.[*] For most things, we can take the entire test code from the Test::Pod documentation.
use Test::More; eval "use Test::Pod 1.00"; plan skip_all => "Test::Pod 1.00 required for testing POD" if $@; all_pod_files_ok( );
We don't want to require everyone to install the module though, so the suggested test code first checks if we can load the module by using the string form of eval that we told you about in Chapter 2. If that fails, eval sets the error variable $@, and once that is set, we tell Test::More to skip the rest of the tests.
If we've installed the module, however, we'll get past the skip_all check and run all_pod_files_ok. The module takes care of finding all the POD files, which it then checks for format. If we want to change which files it checks, we can do that too. Without arguments, all_pod_files_ok TRies to find files in the usual places. With arguments, it only tests the files we tell it to test.
use Test::More; eval "use Test::Pod 1.00"; plan skip_all => "Test::Pod 1.00 required for testing POD" if $@; all_pod_files_ok( 'lib/Maps.pm' );
Testing the POD format isn't all we can do, though. What if we want to ensure that we documented all of our methods? It's Test::Pod::Coverage to the rescue. It goes through our embedded documentation and tells us which subroutine names don't have corresponding entries in the documentation. The example use looks almost the same as that for Test::Pod.[*]
use Test::More; eval "use Test::Pod::Coverage"; plan skip_all => "Test::Pod::Coverage required for testing pod coverage" if $@; plan tests => 1; pod_coverage_ok( "Island::Plotting::Maps");
Both of these modules can do more than what we've shown you, so check their documentation to get the full story. If you use Module::Starter that we talked about in Chapter 16, you'll probably already have these tests in your distribution.