If you have a module on CPAN consisting of several files and you want to test the POD with Test::Pod, this is a test that you can add to your t/ directory and MANIFEST. The code assumes that your modules lie below a lib/ directory instead together with the administrative files. For example the files that go together with the test below are : 
lib/WWW/Mechanize/FormFiller.pm
lib/WWW/Mechanize/FormFiller/Value.pm
lib/WWW/Mechanize/FormFiller/Value/Fixed.pm
lib/WWW/Mechanize/FormFiller/Value/Default.pm
lib/WWW/Mechanize/FormFiller/Value/Callback.pm
lib/WWW/Mechanize/FormFiller/Value/Interactive.pm
lib/WWW/Mechanize/FormFiller/Value/Random.pm

Comments on portability etc. are very welcome, as I want to release modules using this test via CPAN and I don't want too many portability errors :-)

use strict;

use vars qw( @modules );

BEGIN { @modules = qw(
  WWW::Mechanize::FormFiller
  WWW::Mechanize::FormFiller::Value
  WWW::Mechanize::FormFiller::Value::Fixed
  WWW::Mechanize::FormFiller::Value::Default
  WWW::Mechanize::FormFiller::Value::Callback
  WWW::Mechanize::FormFiller::Value::Interactive
  WWW::Mechanize::FormFiller::Value::Random
)};

use Test::More tests => scalar @modules;

sub test_module_pod {
  my $modulename;

  for $modulename (@_) {
    # We assume that we live in the t/ directory, and that our main mo
+dule lives below t/../lib/
    my @modulepath = (File::Spec->splitpath($FindBin::Bin));
    pop @modulepath;
    push @modulepath, "lib",split /::/, $modulename;
    my $constructed_module_name = File::Spec->catfile(@modulepath) . "
+.pm";

    pop @modulepath;
    pod_ok($constructed_module_name);
  };
};

SKIP: {
  eval { require FindBin; FindBin->import() };
  skip "Need FindBin to check the Pod", scalar @modules if $@;
  eval { require File::Spec; File::SpecBase->import() };
  skip "Need File::Spec to check the Pod",scalar @modules if $@;
  eval { require Test::Pod; Test::Pod->import() };
  skip "Need Test::Pod to check the Pod",scalar @modules if $@;

  test_module_pod($_) for @modules;

  # make warnings.pm happy
  $FindBin::Bin eq $FindBin::Bin or 1;
};

[download]

Replies are listed 'Best First'.
Re: Test the Pod of your files
by adrianh (Chancellor) on Jan 06, 2003 at 17:58 UTC

    If you want something completely general you should check under blib rather than lib, since the Makefile.PL could run a filter on the source (not really an issue if you don't do that - but you never know :-). It also might be easier to just base it on Test::Builder instead of pulling in Test:More.

    You might want to take a glance at pod.t and documented.t (part of the tests for Test::Class and Test::Exception) written before Test::Pod was around.

    They're a little hacky but seem to work a fair number of places (see http://testers.cpan.org/ for the full list).

    pod.t does basically what Test::Pod does, but searches for all modules in the specified directories, rather than being given an explicit list.

    documented.t uses Pod::Coverage to check that the POD actually documents the code in the module. Again, it searches for modules rather than being given an explicit list.

[reply]
•Re: Test the Pod of your files
by merlyn (Sage) on Jan 06, 2003 at 17:59 UTC
[reply]

      I use Test::Pod, but I find it bad to have a big list prerequisites only needed for the tests - that's why I skip the tests unless all needed modules are there...

      perl -MHTTP::Daemon -MHTTP::Response -MLWP::Simple -e ' ;    # The  
$d = new HTTP::Daemon and fork and getprint $d->url and exit;#spider
($c = $d->accept())->get_request(); $c->send_response( new   #in the
HTTP::Response(200,$_,$_,qq(Just another Perl hacker\n))); ' #  web

      [download]
[reply]
[d/l]

      Why is there a • in all of your replies? It doesn't even show up? Why bother?

      For that matter, why can people even change titles? Shouldn't only moderators be able to change the title of root nodes and have all corresponding replies automatically change? Is it so off-topic replies can be labelled more effectively? If this is the case, why abuse it just to add meaningless, uninterpreted escape sequences to the title?

      Just struck me as odd, especially coming from a big name.

      Previewing this • shows up as • why isn't this the case with the titles?

[reply]
[d/l]
        Shouldn't only moderators be able to change the title of root nodes

        They are the only ones who can. merlyn's reply is not the actual root node that started the thread.

        merlyn adds the • to his nodes to make them easier for him to see and track his replies. However the powers that be decided to filter out escape sequences within the node titles.

        TStanley
        --------
        It is God's job to forgive Osama Bin Laden. It is our job to arrange the meeting -- General Norman Schwartzkopf
[reply]

Back to Cool Uses for Perl