NAME¶
Test::Pod::Content - Test a Pod's content
SYNOPSIS¶
use Test::Pod::Content tests => 3;
pod_section_is 'Test::Pod::Content' , 'NAME', "Test::Pod::Content - Test a Pod's content", 'NAME section';
pod_section_like 'Test/Pod/Content.pm', 'SYNOPSIS', qr{ use \s Test::Pod::Content; }xm, 'SYNOPSIS section';
pod_section_like 'Test/Pod/Content.pm', 'DESCRIPTION', qr{ Test::Pod::Content \s provides \s the }xm, 'DESCRIPTION section';
DESCRIPTION¶
This is a very simple module for testing a Pod's content. It is mainly intended
for testing the content of generated Pod - that is, the Pod included in perl
modules generated by some mechanism.
Another usage example is to test whether all files contain the same copyright
notice:
plan tests => scalar @filelist;
for my $file (sort @filelist) {
pod_section_like( $file, 'LICENSE AND COPYRIGHT', qr{
This \s library \s is \s free \s software\. \s
You \s may \s distribute/modify \s it \s under \s
the \s same \s terms \s as \s perl \s itself
}xms, "$file License notice");
}
See the files in the t/ directory for live examples.
Test::Pod::Content has a very simple concept of Pods: To Test::Pod::Content, a
Pod is separated into section. Each section starts with a =head(1|2|3|4)
directive, and ends with the next =head, or with the end of the document
(=cut).
This is a very drastic simplification of Pod's document object model, and only
allows for coarse-grained tests.
Test::Pod::Content provides the following subroutines for testing a Pod's
content:
SUBROUTINES/METHODS¶
pod_section_is¶
pod_section_is $file, $section, $content, $comment;
Tests whether a Pod section contains exactly the text given. Most useful for
testing the NAME section. You probably want to use pod_section_like for all
other sections.
$file may either be a filename (including path) or a module name.
Test::Pod::Content will search in @INC for the file/module given.
pod_section_like¶
pod_section_like $file, $section, qr{ use \s Test::Pod::Content\s }xm, $comment;
Tests whether the text in a Pod section matches the given regex. Be sure to
include the m / s regex qualifier if you expect your Pod section to span
multiple lines.
$file may either be a filename (including path) or a module name.
Test::Pod::Content will search in @INC for the file/module given.
BUGS AND LIMITATIONS¶
- •
- Performance
Every call to a pod_section_* method searches for the file in question in
@INC and parses it from its start. This means that every test requires a
Pod parser run, which is quite inefficient if you conduct a big number of
tests.
- •
- Pod Syntax
Test::Pod::Coverage may report wrong test results if your pod is not
syntactically correct. You should use Test::Pod to check your Pod's
syntax.
DEPENDENCIES¶
Test::More
Pod::Simple
version
INCOMPATIBILITIES¶
None known
SEE ALSO¶
Test::Pod for testing your POD's validity
Test::Pod::Coverage for checking wether your pod is complete
Pod::Tests, Test::Pod::Snippets and Pod::Snippets for extracting and executing
tests from a POD (If you plan doing so, here's a little brain-train: Which of
the tests in this module's "SYNOPSIS" section would fail if you
extracted and executed it?).
LICENSE AND COPYRIGHT¶
Copyright 2007 Martin Kutter.
This library is free software. You may distribute/modify it under the same terms
as perl itself
AUTHOR¶
Martin Kutter <martin.kutter fen-net.de>
$Id: Content.pm 505 2008-06-22 09:54:54Z kutterma $
$Revision: 505 $
$Source: a $
$Date: 2008-06-22 11:54:54 +0200 (So, 22 Jun 2008) $
$HeadURL: http://svn.hyper-framework.org/Hyper/Test-Pod-Content/trunk/lib/Test/Pod/Content.pm $