Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Contact Us
Online Help
Domain Status
Man Pages

Virtual Servers

Topology Map

Server Agreement
Year 2038

USA Flag



Man Pages

Manual Reference Pages  -  TEST::BLOCK (3)

.ds Aq ’


Test::Block - DEPRECIATED: Specify fine granularity test plans



  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 ( 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
  # Looks like you failed 1 tests of 7.


<B>NOTE: This module was written before subtests existed in TAP and Test::More. These days subtests will probably be a better option for you.B>

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.

  # 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.

<B>remainingB> 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.

<B>builderB> Returns Test::Builder object used by Test::Block. For example:

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

See Test::Builder for more information.

<B>block_countB> 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.

<B>all_in_blockB> 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 );


None known at the time of writing.

If you find any please let me know by e-mail, or report the problem with <>.


perl-qa If you are interested in testing using Perl I recommend you visit <> and join the excellent perl-qa mailing list. See <> for details on how to subscribe.
perlmonks You can find users of Test::Block, including the module author, on <>. Feel free to ask questions on Test::Block there.
CPAN::Forum The CPAN Forum is a web forum for discussing Perl’s CPAN modules. The Test::Block forum can be found at <>.
AnnoCPAN AnnoCPAN is a web site that allows community annotations of Perl module documentation. The Test::Block annotations can be found at <>.


If you think this module should do something that it doesn’t (or does something that it shouldn’t) please let me know.

You can see my current to do list at <>, with an RSS feed of changes at <>.


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 that sparked the idea for this module. Thanks to Fergal Daly for suggesting named blocks. Thanks to Michael G Schwern for suggesting $Plan. Thanks to Nadim Khemir for feedback and Andreas Koenig for spotting bugs.


Adrian Howard <>

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


Test::Group A framework for grouping related tests in a test suite
Test::Class Test::Class is an xUnit testing framework for Perl. It allows you to group tests into methods with independent test plans.
Test::Builder Support module for building test libraries.
Test::Simple & Test::More Basic utilities for writing tests.
<> Overview of some of the many testing modules available on CPAN.


Copyright 2003-2006 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.

Search for    or go to Top of page |  Section 3 |  Main Index

perl v5.20.3 TEST::BLOCK (3) 2012-01-24

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.