Test::Pod(3) User Contributed Perl Documentation Test::Pod(3)
NAME
Test::Pod - check for POD errors in files
VERSION
Version 1.52
SYNOPSIS
"Test::Pod" lets you check the validity of a POD file, and report its
results in standard "Test::Simple" fashion.
use Test::Pod tests => $num_tests;
pod_file_ok( $file, "Valid POD file" );
Module authors can include the following in a t/pod.t file and have
"Test::Pod" automatically find and check all POD files in a module
distribution:
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();
You can also specify a list of files to check, using the
"all_pod_files()" function supplied:
use strict;
use Test::More;
eval "use Test::Pod 1.00";
plan skip_all => "Test::Pod 1.00 required for testing POD" if $@;
my @poddirs = qw( blib script );
all_pod_files_ok( all_pod_files( @poddirs ) );
Or even (if you're running under Apache::Test):
use strict;
use Test::More;
eval "use Test::Pod 1.00";
plan skip_all => "Test::Pod 1.00 required for testing POD" if $@;
my @poddirs = qw( blib script );
use File::Spec::Functions qw( catdir updir );
all_pod_files_ok(
all_pod_files( map { catdir updir, $_ } @poddirs )
);
DESCRIPTION
Check POD files for errors or warnings in a test file, using
"Pod::Simple" to do the heavy lifting.
FUNCTIONS
pod_file_ok( FILENAME[, TESTNAME ] )
"pod_file_ok()" will okay the test if the POD parses correctly.
Certain conditions are not reported yet, such as a file with no pod in
it at all.
When it fails, "pod_file_ok()" will show any pod checking errors as
diagnostics.
The optional second argument TESTNAME is the name of the test. If it
is omitted, "pod_file_ok()" chooses a default test name "POD test for
FILENAME".
all_pod_files_ok( [@entries] )
Checks all the files under @entries for valid POD. It runs
all_pod_files() on directories and assumes everything else to be a file
to be tested. It calls the "plan()" function for you (one test for each
file), so you can't have already called "plan".
If @entries is empty or not passed, the function finds all POD files in
files in the blib directory if it exists, or the lib directory if not.
A POD file matches the conditions specified below in "all_pod_files".
If you're testing a module, just make a t/pod.t:
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();
Returns true if all pod files are ok, or false if any fail.
all_pod_files( [@dirs] )
Returns a list of all the POD files in @dirs and in directories below.
If no directories are passed, it defaults to blib if blib exists, or
else lib if not. Skips any files in CVS, .svn, .git and similar
directories. See %Test::Pod::ignore_dirs for a list of them.
A POD file is:
o Any file that ends in .pl, .PL, .pm, .pod, .psgi or .t.
o Any file that has a first line with a shebang and "perl" on it.
o Any file that ends in .bat and has a first line with "--*-Perl-*--"
on it.
The order of the files returned is machine-dependent. If you want them
sorted, you'll have to sort them yourself.
SUPPORT
This module is managed in an open GitHub repository
<http://github.com/perl-pod/test-pod/>. Feel free to fork and
contribute, or to clone <git://github.com/perl-pod/test-pod.git> and
send patches!
Found a bug? Please post <http://github.com/perl-pod/test-pod/issues>
or email <mailto:bug-test-pod@rt.cpan.org> a report!
AUTHORS
David E. Wheeler <david@justatheory.com>
Current maintainer.
Andy Lester "<andy at petdance.com>"
Maintainer emeritus.
brian d foy
Original author.
ACKNOWLEDGEMENTS
Thanks brian d foy for the original code, and to these folks for
contributions:
o Andy Lester
o David E. Wheeler
o Paul Miller
o Peter Edwards
o Luca Ferrari
COPYRIGHT AND LICENSE
Copyright 2006-2010, Andy Lester; 2010-2015 David E. Wheeler. Some
Rights Reserved.
This module is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
perl v5.34.1 2018-04-19 Test::Pod(3)
test-pod 1.520.0 - Generated Sun Oct 26 10:50:03 CDT 2025