Test::Pod(3) User Contributed Perl Documentation Test::Pod(3)

# [NAME](#NAME)

Test::Pod - check for POD errors in files

# [VERSION](#VERSION)

Version 1.52

# [SYNOPSIS](#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](#DESCRIPTION)

Check POD files for errors or warnings in a test file, using "Pod::Simple" to do the heavy lifting.

# [FUNCTIONS](#FUNCTIONS)

## [pod\_file\_ok( FILENAME\[, TESTNAME \] )](#pod_file_ok%28_FILENAME_,_TESTNAME___%29)

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\] )](#all_pod_files_ok%28__@entries__%29)

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\] )](#all_pod_files%28__@dirs__%29)

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:

- Any file that ends in *.pl*, *.PL*, *.pm*, *.pod*, *.psgi* or *.t*.
- Any file that has a first line with a shebang and "perl" on it.
- 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](#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](#AUTHORS)

[David E. Wheeler <david@justatheory.com>](#David)

Current maintainer.

[Andy Lester "<andy at petdance.com>"](#Andy)

Maintainer emeritus.

[brian d foy](#brian)

Original author.

# [ACKNOWLEDGEMENTS](#ACKNOWLEDGEMENTS)

Thanks brian d foy for the original code, and to these folks for contributions:

- Andy Lester
- David E. Wheeler
- Paul Miller
- Peter Edwards
- Luca Ferrari

# [COPYRIGHT AND LICENSE](#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.

2026-10-25 perl v5.44.0

---

Document: Test::Pod(3pm) from perl-test-pod 1.52-r12 (Chainguard OS)
Source: https://github.com/perl-pod/test-pod