Update: sorry to all for to borked markup. Just used plain-text this time.

NAME
    Test::Most - Most commonly needed test functions and features.

VERSION
    Version 0.01

SYNOPSIS
    WARNING: This is alpha code. It seems to work well, but use with
    caution.

    This module provides you with the most commonly used testing funct
+ions
    and gives you a bit more fine-grained control over your test suite
+.

        use Test::Most tests => 4, 'die';

        ok 1, 'Normal calls to ok() should succeed';
        is 2, 2, '... as should all passing tests';
        eq_or_diff [3], [4], '... but failing tests should die';
        ok 4, '... will never get to here';

    As you can see, the "eq_or_diff" test will fail. Because 'die' is 
+in the
    import list, the test program will halt at that point.

EXPORT
    All functions from the following modules will automatically be exp
+orted
    into your namespace:

    * "Test::More"
    * "Test::Exception"
    * "Test::Differences"
    * "Test::Deep"

    Functions which are *optionally* exported from any of those module
+s must
    be referred to by their fully-qualified name:

      Test::Deep::render_stack( $var, $stack );

FUNCTIONS
    Four other functions are also automatically exported:

  "die_on_fail"
     die_on_fail;
     is_deeply $foo, bar, '... we die if this fails';

    This function, if called, will cause the test program to die if an
+y
    tests fail after it.

  "bail_on_fail"
     bail_on_fail;
     is_deeply $foo, bar, '... we bail out if this fails';

    This function, if called, will cause the test suite to BAIL_OUT() 
+if any
    tests fail after it.

  "restore_fail"
     die_on_fail;
     is_deeply $foo, bar, '... we die if this fails';

     restore_fail;
     cmp_bag(\@got, \@bag, '... we will not die if this fails';

    This restores the original test failure behavior, so subsequent te
+sts
    will no longer die or BAIL_OUT().

  "explain"
    Like "diag()", but only outputs the message if $ENV{TEST_VERBOSE} 
+is
    set. This is typically set by using the "-v" switch with "prove".

    Requires "Test::Harness" 3.07 or greater.

DIE OR BAIL ON FAIL
    Sometimes you want your test suite to die or BAIL_OUT() if a test 
+fails.
    In order to provide maximum flexibility, there are three ways to
    accomplish each of these.

  Import list
     use Test::Most 'die', tests => 7;
     use Test::Most qw< no_plan bail >;

    If "die" or "bail" is anywhere in the import list, the test
    program/suite will "die" or "BAIL_OUT()" as appropriate the first 
+time a
    test fails. Calling "restore_fail" anywhere in the test program wi
+ll
    restore the original behavior (not dieing or bailing out).

  Functions
     use Test::Most 'no_plan;
     ok $bar, 'The test suite will continue if this passes';

     die_on_fail;
     is_deeply $foo, bar, '... we die if this fails';

     restore_fail;
     ok $baz, 'The test suite will continue if this passes';

    The "die_on_fail" and "bail_on_fail" functions will automatically 
+set
    the desired behavior at runtime.

  Environment variables
     DIE_ON_FAIL=1 prove t/
     BAIL_ON_FAIL=1 prove t/

    If the "DIE_ON_FAIL" or "BAIL_ON_FAIL" environment variables are t
+rue,
    any tests which use "Test::Most" will die or call BAIL_OUT on test
    failure.

RATIONALE
    People want more control over their test suites. Sometimes when yo
+u see
    hundreds of tests failing and whizzing by, you want the test suite
+ to
    simply halt on the first failure. This module gives you that contr
+ol.

    As for the reasons for the four test modules chosen, I ran code ov
+er a
    local copy of the CPAN to find the most commonly used testing modu
+les.
    Here were the top ten (out of 287):

     Test::More              44461
     Test                     8937
     Test::Exception          1379
     Test::Simple              731
     Test::Base                316
     Test::Builder::Tester     193
     Test::NoWarnings          174
     Test::Differences         146
     Test::MockObject          139
     Test::Deep                127

    The four modules chosen seemed the best fit for what "Test::Most" 
+is
    trying to do.

AUTHOR
    Curtis Poe, "<ovid at cpan.org>"

BUGS
    Please report any bugs or feature requests to "bug-test-extended a
+t
    rt.cpan.org", or through the web interface at
    <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Test-Most>. I will
+ be
    notified, and then you'll automatically be notified of progress on
+ your
    bug as I make changes.

SUPPORT
    You can find documentation for this module with the perldoc comman
+d.

        perldoc Test::Most

    You can also look for information at:

    * RT: CPAN's request tracker
        <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Test-Most>

    * AnnoCPAN: Annotated CPAN documentation
        <http://annocpan.org/dist/Test-Most>

    * CPAN Ratings
        <http://cpanratings.perl.org/d/Test-Most>

    * Search CPAN
        <http://search.cpan.org/dist/Test-Most>

TODO
  Deferred plans
    Sometimes you don't know the number of tests you will run when you
+ use
    "Test::More". The "plan()" function allows you to delay specifying
+ the
    plan, but you must still call it before the tests are run. This is
+ an
    error:

     use Test::More;

     my $tests = 0;
     foreach my $test (
         my $count = run($test); # assumes tests are being run
         $tests += $count;
     }
     plan($tests);

    The way around this is typically to use 'no_plan' and when the tes
+ts are
    done, "Test::Builder" merely sets the plan to the number of tests 
+run.
    We'd like for the programmer to specify this number instead of let
+ting
    "Test::Builder" do it. However, "Test::Builder" internals are a bi
+t
    difficult to work with, so we're delaying this feature.

  Cleaner skip()
     if ( $some_condition ) {
         skip $message, $num_tests;
     }
     else {
         # run those tests
     }

    That would be cleaner and I might add it if enough people want it.

CAVEATS
    Because of how Perl handles arguments, and because diagnostics are
+ not
    really part of the Test Anything Protocol, what actually happens
    internally is that we note that a test has failed and we die or ba
+il out
    as soon as the *next* test is called (but before it runs). This me
+ans
    that its arguments are automatically evaulated before we can take
    action:

     use Test::Most qw<no_plan die>;

     ok $foo, 'Die if this fails';
     ok factorial(123456), '... but wait a loooong time before you die
+';

ACKNOWLEDGEMENTS
    Many thanks to "perl-qa" for arguing about this so much that I jus
+t went
    ahead and did it :)

    Thanks to Aristotle for suggesting a better way to die or bailout.

COPYRIGHT & LICENSE
    Copyright 2008 Curtis Poe, all rights reserved.

    This program is free software; you can redistribute it and/or modi
+fy it
    under the same terms as Perl itself.
[download]