Stories
Slash Boxes
Comments
NOTE: use Perl; is on undef hiatus. You can read content, but you can't post it. More info will be forthcoming forthcomingly.

All the Perl that's Practical to Extract and Report

use Perl Log In

Log In

[ Create a new account ]

Yanick (3196)

Yanick
  (email not shown publicly)
http://babyl.dyndns.org/techblog

Journal of Yanick (3196)

Wednesday August 23, 2006
08:58 PM

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

[ #30734 ]

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.


List all Journal entries
The Fine Print: The following comments are owned by whoever posted them. We are not responsible for them in any way.

Test::Pod::Snippets v0.01 is out! 4 Comments More | Login | Reply /

 Full
 Abbreviated
 Hidden
More | Login | Reply
Loading... please wait.

  • This sounds very similar to Test::Inline [cpan.org]. How does Test::Pod::Snippets compare?

    • 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 tes

      • 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 v

        • 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 Univ

Stories, comments, journals, and other submissions on use Perl; are Copyright 1998-2006, their respective owners.