Test::...ontent(3pm)

💖 NAME 💖

Test::Pod::Content — bestie, it tests a Pod's content. That's it. That's the whole job. She's simple, she's iconic, she's not trying to be anything she isn't. 🎀

---

✨ SYNOPSIS ✨

okay so here's the vibe, copy-paste this and you're basically done:

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 🦋

So Test::Pod::Content is a very simple module for testing a Pod's content. Like, very simple, no cap. Its whole personality is testing the content of generated Pod — that is, the Pod that ends up included in perl modules that got generated by some mechanism. Autogenerated docs need love too bestie 💅

Another usage example is testing whether all your files contain the same copyright notice. lowkey a classic move:

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. 🫶

Okay so here's the tea about how Test::Pod::Content thinks about Pods: it 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).

That is, fr fr, a very drastic simplification of Pod's document object model, and it only allows for coarse-grained tests. No fine-grained drama here, she keeps it surface level. 🙈

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, because that one's short and sweet. For literally every other section you probably want to use pod_section_like instead. She said what she said.

$file may either be a filename (including path) or a module name. Test::Pod::Content will search in @INC for the file/module given. It'll go looking for it, main character style. 🔥

🌈 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 — otherwise she will simply not find what you're looking for and you'll be sad. 😭

$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. Bestie. It's giving "parsing the same file forty times." Plan accordingly. ⭐

• 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. Don't skip this one, it's not a suggestion, it's a whole vibe check. 🧚

---

🍓 DEPENDENCIES 🍓

• Test::More
• Pod::Simple
• version

---

💅 INCOMPATIBILITIES 💅

None known. She plays nice with everybody. Slay. ✨

---

💜 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>

---

📦 REPOSITORY INFORMATION 📦

 $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 $

---

and that's the whole page, bestie 🫶 this lil gem shipped in perl v5.36.0 and got its glow-up on 2022-11-20, part of the User Contributed Perl Documentation collection — go forth, test your Pod's content, and stay iconic. 💖✨🎀