All the Perl that's Practical to Extract and Report

Test::Pod::Snippets v0.01 is out!

Yanick on 2006-08-24T01:58:34

From T::P::S's manpage:

Fact 1
In a perfect world, a module's full API should be covered by an extensive battery of testcases neatly tucked in the distribution's t directory. But then, in a perfect world each backyard would have a marshmallow tree and postmen would consider their duty to circle all the real good deals in pamphlets before stuffing them in your mailbox. Obviously, we're not living in a perfect world.
Fact 2
Typos and minor errors in module documentation. Let's face it: it happens to everyone. And while it's never the end of the world and is prone to rectify itself in time, it's always kind of embarassing. A little bit like electronic zits on prepubescent docs, if you will.

Test::Pod::Snippets's goal is to address those issues. Quite simply, it extracts verbatim text off pod documents -- which it assumes to be code snippets -- and generate test files out of them.

-----------

Test::Pod::Snippets: on its way to a CPAN near you. In the meantime, it can be peeked at in its svn repository or its web interface.

How does this compare to Test::Inline?

dagolden on 2006-08-24T09:47:33

This sounds very similar to Test::Inline. How does Test::Pod::Snippets compare?

Re:How does this compare to Test::Inline?

Yanick on 2006-08-24T12:23:49

It's very similar indeed. The big difference is that T::P::S extracts the code to test directly from the pod, whereas with T::I you have to explicitly add the test code. In other words, T::I don't do any dark voodoo magic with the pod, it just deal with files that contains code, pod and tests.

For example, with T::I you'd have to write:

=head2 Foo

That's how you do it:

  # will set $x to 'baz'
  my $x = bar( $y );
=begin testing
my $x = bar( $y );
is $x => 'baz';
=end testing

And with T::P::S:

=head2 Foo

That's how you do it:

  # will set $x to 'baz'
  my $x = bar( $y );

=for test
  is $x => 'baz';

It's not a big difference, I'll grant you, but it does reduce the need to cut and paste a few lines. Which is always a big plus for those amongst us who worship the big L of the Perl Virtues. :-)

Re:How does this compare to Test::Inline?

dagolden on 2006-08-24T12:52:56

Ah -- I didn't get that part.

As a result, you've got the opposite problem from Test::Inline -- you have to specially flag verbatim code that isn't related to testing. (E.g. synopses and random examples).

Some say pota-TOE and some say po-TAH-to...

I think it's worth highlighting that difference to Test::Inline in a SEE ALSO section.

I also don't particularly like the way you're using =for test ignore followed by a blank line as parser flag. In my opinion, that meets the letter of the Pod syntax but violates the spirit. (Not that I see any other way for you to do it while meeting your design goal.)

Re:How does this compare to Test::Inline?

Yanick on 2006-08-24T14:16:59

As a result, you've got the opposite problem from Test::Inline -- you have to specially flag verbatim code that isn't related to testing. (E.g. synopses and random examples).

Actually, it's mostly the synopses and the random examples that I am interested to run. They just tend to be stuff that you write directly in the docs and never get around testing, or just get out of sync with the code as time passes by.

And yeah, seen like that, T::P::S is a wee bit like the alter-ego of T::I from the Alternate Universe. Which explains the goatee, I suppose. ;-)

Some say pota-TOE and some say po-TAH-to...

And as this is Perl, you can count on a third party to come along and say "did you know you can also use 'Taters', and thus shave off a whole syllable? Ain't that cool or what?". :-)

I think it's worth highlighting that difference to Test::Inline in a SEE ALSO section.

Very good point. I'll do.

I also don't particularly like the way you're using =for test ignore followed by a blank line as parser flag. In my opinion, that meets the letter of the Pod syntax but violates the spirit. (Not that I see any other way for you to do it while meeting your design goal.)

Yeah. There's a few ways to acheive the same result, but they are fairly circonvoluted. I'm thinking, e.g., of

=for test
$x = <<END_IGNORE

...

=for test
END_IGNORE

but that's kinda ugly... <:-P