NAME
    Test::Block - specify fine granularity test plans

SYNOPSIS
      use Test::More 'no_plan';
      use Test::Block qw($Plan);

      {
          # This block should run exactly two tests
          local $Plan = 2;
          pass 'first test';
          # oops. forgot second test
      };

      SKIP: {
          local $Plan = 3;
          pass('first test in second block');
          skip "skip remaining tests" => $Plan;
      };

      ok( Test::Block->all_in_block, 'all test run in blocks' );
      is( Test::Block->block_count, 2, 'two blocks ran' );

      # This produces...
  
      ok 1 - first test
      not ok 2 - block expected 2 test(s) and ran 1
      #     Failed test (foo.pl at line 6)
      ok 3 - first test in second block
      ok 4 # skip skip remaining tests
      ok 5 # skip skip remaining tests
      ok 6 - all test run in blocks
      ok 7 - two blocks ran
      1..7
      # Looks like you failed 1 tests of 7.

DESCRIPTION
    This module allows you to specify the number of expected tests at a
    finer level of granularity than an entire test script. It is built with
    Test::Builder and plays happily with Test::More and friends.

    If you are not already familiar with Test::More now would be the time to
    go take a look.

  Creating test blocks
    Test::Block supplies a special variable $Plan that you can localize to
    specify the number of tests in a block like this:

        use Test::More 'no_plan';
        use Test::Block qw($Plan);
    
        {
            local $Plan = 2;
            pass('first test');
            pass('second test');
        };
    
  What if the block runs a different number of tests?
    If a block doesn't run the number of tests specified in $Plan then
    Test::Block will automatically produce a failing test. For example:

        {
            local $Plan = 2;
            pass('first test');
            # oops - forgot second test
        };

    will output

        ok 1 - first test
        not ok 2 - block 1 expected 2 test(s) and ran 1

  Tracking the number of remaining tests
    During the execution of a block $Plan will contain the number of
    remaining tests that are expected to run so:

        {
            local $Plan = 2;
            diag "$Plan tests to run";
            pass('first test');
            diag "$Plan tests to run";
            pass('second test');
            diag "$Plan tests to run";
        };

    will produce

        # 2 tests to run
        ok 1 - first test
        # 1 tests to run
        ok 2 - second test
        # 0 tests to run

    This can make skip blocks easier to write and maintain, for example:

        SKIP: {
            local $Plan = 5;
            pass('first test');
            pass('second test');
            skip "debug tests" => $Plan unless DEBUG > 0;
            pass('third test');
            pass('fourth test');
            skip "high level debug tests" => $Plan unless DEBUG > 2;
            pass('fifth test');
        };

  Named blocks
    To make debugging easier you can give your blocks an optional name like
    this:

        {
            local $Plan = { example => 2 };
            pass('first test');
            # oops - forgot second test
        };

    which would output

        ok 1 - first test
        not ok 2 - block example expected 2 test(s) and ran 1

  Test::Block objects
    The $Plan is implemented using a tied variable that stores and retrieves
    Test::Block objects. If you want to avoid the tied interface you can use
    Test::Block objects directly.

    plan
          # create a block expecting 4 tests
          my $block = Test::Block->plan(4);

          # create a named block with two tests
          my $block = Test::Block->plan('test name' => 2);

        You create Test::Block objects with the "plan" method. When the
        object is destroyed it outputs a failing test if the expected number
        of tests have not run.

    remaining
        You can find out the number of remaining tests in the block by
        calling the "remaining" method on the object.

        Test::Block objects overload "" and "0+" to return the result of the
        remaining method.

    builder
        Returns Test::Builder object used by Test::Block. For example:

          Test::Block->builder->skip('skip a test');

        See Test::Builder for more information.

    block_count
        A class method that returns the number of blocks that have been
        created. You can use this to check that the expected number of
        blocks have run by doing something like:

          is( Test::Block->block_count, 5, 'five blocks run' );

        at the end of your test script.

    all_in_block
        Returns true if all tests so far run have been inside the scope of a
        Test::Block object.

          ok( Test::Block->all_in_block, 'all tests run in blocks' );

BUGS
    None known at the time of writing.

    If you find any please let me know by e-mail, or report the problem with
    <http://rt.cpan.org/>.

TO DO
    Nothing at the time of writing.

    If you think this module should do something that it doesn't do at the
    moment please let me know.

ACKNOWLEGEMENTS
    Thanks to chromatic and Michael G Schwern for the excellent
    Test::Builder, without which this module wouldn't be possible.

    Thanks to Michael G Schwern and Tony Bowden for the mails on
    perl-qa@perl.org that sparked the idea for this module. Thanks to Fergal
    Daly for suggesting named blocks. Thanks to Michael G Schwern for
    suggesting $Plan.

AUTHOR
    Adrian Howard <adrianh@quietstars.com>

    If you can spare the time, please drop me a line if you find this module
    useful.

SEE ALSO
    Test::Builder
        Support module for building test libraries.

    Test::Simple & Test::More
        Basic utilities for writing tests.

    <http://qa.perl.org/test-modules.html>
        Overview of some of the many testing modules available on CPAN.

LICENCE
    Copyright 2003-2004 Adrian Howard, All Rights Reserved.

    This program is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself.