Test::Block3pm

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' );