Test::Pod

geoff on 2002-09-05T12:23:59

well, in following brian's example, I've created a portable t/99pod.t that seems to work.

use Test::More;



use File::Spec;
use strict;



eval {
  require Test::Pod;
  Test::Pod->import;
  require File::Find::Rule;
};



my @files;
my $blib = File::Spec->catfile(qw(blib lib));



if ($@) {
  plan skip_all => "Test::Pod and File::Find::Rule required for testing POD";
}
else {
  @files = File::Find::Rule->file()->name('*.pm')->in($blib);
  plan tests => scalar @files;
}



foreach my $file (@files) {
  pod_ok($file);
}


that'll make a nice addition to my (growing) collection of standard tests. I really don't know how I ever got along without writing tests - they make development so much easier. it helps to have stuff like Test::More and Apache::Test around. major kudos to all who contribute and make it all possible.

---

Hooray for teamwork

petdance on 2002-09-05T12:53:07

I'm glad to see the extensions, Geoff. Now we just need brian to include it as an example file with Test::Pod.

At this point, maybe brian should just create a Test::Pod::Distro based on this module to encapsulate all this code, so we module authors are not cut'n'pasting it everywhere.

And don't you want to have the File::Spec::catfile call inside the if? Or can that throw an exception that you're wanting to catch?

use Test::More;

use File::Spec;
use strict;

eval {
  require Test::Pod;
  Test::Pod->import;
  require File::Find::Rule;
};

my @files;

if ($@) {
  plan skip_all => "Test::Pod and File::Find::Rule required for testing POD";
}
else {
  my $blib = File::Spec->catfile(qw(blib lib));
  @files = File::Find::Rule->file()->name('*.pm')->in($blib);
  plan tests => scalar @files;
}

foreach my $file (@files) {
  pod_ok($file);
}

Re:Hooray for teamwork

geoff on 2002-09-05T13:01:44

nope, you're right about the File::Spec stuff - I'm still working on my morning coffee :)

teamwork++

Re:Hooray for teamwork

petdance on 2002-09-05T13:22:41

And we should check *.pod and *.pl files as well. At the very least, Schwern's Test::Tutuorial is distributed as a .pod, not .pm.

# I think this is right
@files = File::Find::Rule->file()->name(['*.pm','*.pod','*.pl'])->in($blib);

And if we REALLY want to be portable, then let's not rely on File::Find::Rule. It's not as if File::Find isn't still perfectly serviceable in this case.

Re:Hooray for teamwork

petdance on 2002-09-05T14:03:53

Thanks to Geoff Young for unwaving my handwave.

use Test::More;

use File::Spec;
use File::Find;
use strict;

eval {
  require Test::Pod;
  Test::Pod->import;
};

my @files;

if ($@) {
  plan skip_all => "Test::Pod required for testing POD";
}
else {
  my $blib = File::Spec->catfile(qw(blib lib));
  find(\&wanted, $blib);
  plan tests => scalar @files;
  foreach my $file (@files) {
    pod_ok($file);
  }
}

sub wanted {
  push @files, $File::Find::name if /\.p(l|m|od)$/;
}

pod_ok - pod_file_ok

markjugg on 2003-03-29T19:31:40

Thanks fur sharing this. Here's a small potential update: It looks like the Test::Pod docs are recommending using pod_file_ok instead of pod_ok.

Re:pod_ok - pod_file_ok

petdance on 2003-03-29T20:07:25

Yes, they are now. pod_ok used to be the standard way. Now that I changed the guts to use Pod::Simple, pod_file_ok is the way to go.

Re:pod_ok - pod_file_ok

geoff on 2003-03-31T13:32:37

speaking of which, is the mandatory warning for pod_ok really necessary? personally, distribution pod tests are not important enough for me to require that end-users have the most recent version of Test::Pod (the test is for me, not for them), so I'd like to make the test as flexible as possible. throwing

99pod.........ok 1/1# NOTE: pod_ok() is deprecated

for users that have old versions of Test::Pod makes we module releasers look bad, and the only way around them is to either PREREQ_PM the newer module (which I think is overkill) or add an additional layer of indirection to vary the test syntax depending on the version of Test::Pod (which makes code overly complex for illustrations in articles :).

so, is it too much to ask to only print the warning when you TEST_VERBOSE or something? do you have plans to truly remove pod_ok?

Re:pod_ok - pod_file_ok

petdance on 2003-03-31T15:14:38

Well, I do indeed have plans to get rid of pod_ok, but I guess I can leave it in for the indefinite future. The big reason to get rid of pod_ok is that the "allow only these types of errors" parm is now meaningless.

Re:Hooray for teamwork

marcel on 2002-09-07T09:43:23

> At this point, maybe brian should just create a Test::Pod::Distro based on this module to
> encapsulate all this code, so we module authors are not cut'n'pasting it everywhere.

That's what Test::Distribution is for. I'm just making it more modular, adding options for checking PREREQ_PM, MANIFEST, exports and more. And I've taken some of code in these comments to make T::D more portable.