.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Test::Block 3pm"
.TH Test::Block 3pm "2022-12-07" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Test::Block \- DEPRECIATED: Specify fine granularity test plans
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&  use Test::More \*(Aqno_plan\*(Aq;
\&  use Test::Block qw($Plan);
\&
\&  {
\&      # This block should run exactly two tests
\&      local $Plan = 2;
\&      pass \*(Aqfirst test\*(Aq;
\&      # oops. forgot second test
\&  };
\&
\&  SKIP: {
\&      local $Plan = 3;
\&      pass(\*(Aqfirst test in second block\*(Aq);
\&      skip "skip remaining tests" => $Plan;
\&  };
\&
\&  ok( Test::Block\->all_in_block, \*(Aqall test run in blocks\*(Aq );
\&  is( Test::Block\->block_count, 2, \*(Aqtwo blocks ran\*(Aq );
\&
\&  # 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.
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fB\s-1NOTE:\s0 This module was written before subtests existed in \s-1TAP\s0 and Test::More. These days subtests will probably be a better option for you.\fR
.PP
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.
.PP
If you are not already familiar with Test::More now would be the time to go take a look.
.SS "Creating test blocks"
.IX Subsection "Creating test blocks"
Test::Block supplies a special variable \f(CW$Plan\fR that you can localize to specify the number of tests in a block like this:
.PP
.Vb 2
\&    use Test::More \*(Aqno_plan\*(Aq;
\&    use Test::Block qw($Plan);
\&    
\&    {
\&        local $Plan = 2;
\&        pass(\*(Aqfirst test\*(Aq);
\&        pass(\*(Aqsecond test\*(Aq);
\&    };
.Ve
.SS "What if the block runs a different number of tests?"
.IX Subsection "What if the block runs a different number of tests?"
If a block doesn't run the number of tests specified in \f(CW$Plan\fR then Test::Block will automatically produce a failing test. For example:
.PP
.Vb 5
\&    {
\&        local $Plan = 2;
\&        pass(\*(Aqfirst test\*(Aq);
\&        # oops \- forgot second test
\&    };
.Ve
.PP
will output
.PP
.Vb 2
\&    ok 1 \- first test
\&    not ok 2 \- block 1 expected 2 test(s) and ran 1
.Ve
.SS "Tracking the number of remaining tests"
.IX Subsection "Tracking the number of remaining tests"
During the execution of a block \f(CW$Plan\fR will contain the number of remaining tests that are expected to run so:
.PP
.Vb 8
\&    {
\&        local $Plan = 2;
\&        diag "$Plan tests to run";
\&        pass(\*(Aqfirst test\*(Aq);
\&        diag "$Plan tests to run";
\&        pass(\*(Aqsecond test\*(Aq);
\&        diag "$Plan tests to run";
\&    };
.Ve
.PP
will produce
.PP
.Vb 5
\&    # 2 tests to run
\&    ok 1 \- first test
\&    # 1 tests to run
\&    ok 2 \- second test
\&    # 0 tests to run
.Ve
.PP
This can make skip blocks easier to write and maintain, for example:
.PP
.Vb 10
\&    SKIP: {
\&        local $Plan = 5;
\&        pass(\*(Aqfirst test\*(Aq);
\&        pass(\*(Aqsecond test\*(Aq);
\&        skip "debug tests" => $Plan unless DEBUG > 0;
\&        pass(\*(Aqthird test\*(Aq);
\&        pass(\*(Aqfourth test\*(Aq);
\&        skip "high level debug tests" => $Plan unless DEBUG > 2;
\&        pass(\*(Aqfifth test\*(Aq);
\&    };
.Ve
.SS "Named blocks"
.IX Subsection "Named blocks"
To make debugging easier you can give your blocks an optional name like this:
.PP
.Vb 5
\&    {
\&        local $Plan = { example => 2 };
\&        pass(\*(Aqfirst test\*(Aq);
\&        # oops \- forgot second test
\&    };
.Ve
.PP
which would output
.PP
.Vb 2
\&    ok 1 \- first test
\&    not ok 2 \- block example expected 2 test(s) and ran 1
.Ve
.SS "Test::Block objects"
.IX Subsection "Test::Block objects"
The \f(CW$Plan\fR 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.
.IP "\fBplan\fR" 4
.IX Item "plan"
.Vb 2
\&  # create a block expecting 4 tests
\&  my $block = Test::Block\->plan(4);
\&
\&  # create a named block with two tests
\&  my $block = Test::Block\->plan(\*(Aqtest name\*(Aq => 2);
.Ve
.Sp
You create Test::Block objects with the \f(CW\*(C`plan\*(C'\fR method. When the object is destroyed it outputs a failing test if the expected number of tests have not run.
.IP "\fBremaining\fR" 4
.IX Item "remaining"
You can find out the number of remaining tests in the block by calling the \f(CW\*(C`remaining\*(C'\fR method on the object.
.Sp
Test::Block objects overload \f(CW""\fR and \f(CW\*(C`0+\*(C'\fR to return the result of the remaining method.
.IP "\fBbuilder\fR" 4
.IX Item "builder"
Returns Test::Builder object used by Test::Block. For example:
.Sp
.Vb 1
\&  Test::Block\->builder\->skip(\*(Aqskip a test\*(Aq);
.Ve
.Sp
See Test::Builder for more information.
.IP "\fBblock_count\fR" 4
.IX Item "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:
.Sp
.Vb 1
\&  is( Test::Block\->block_count, 5, \*(Aqfive blocks run\*(Aq );
.Ve
.Sp
at the end of your test script.
.IP "\fBall_in_block\fR" 4
.IX Item "all_in_block"
Returns true if all tests so far run have been inside the scope of a Test::Block object.
.Sp
.Vb 1
\&  ok( Test::Block\->all_in_block, \*(Aqall tests run in blocks\*(Aq );
.Ve
.SH "BUGS"
.IX Header "BUGS"
None known at the time of writing.
.PP
If you find any please let me know by e\-mail, or report the problem with <http://rt.cpan.org/>.
.SH "COMMUNITY"
.IX Header "COMMUNITY"
.IP "perl-qa" 4
.IX Item "perl-qa"
If you are interested in testing using Perl I recommend you visit <http://qa.perl.org/> and join the excellent perl-qa mailing list. See <http://lists.perl.org/showlist.cgi?name=perl\-qa> for details on how to subscribe.
.IP "perlmonks" 4
.IX Item "perlmonks"
You can find users of Test::Block, including the module author, on  <http://www.perlmonks.org/>. Feel free to ask questions on Test::Block there.
.IP "CPAN::Forum" 4
.IX Item "CPAN::Forum"
The \s-1CPAN\s0 Forum is a web forum for discussing Perl's \s-1CPAN\s0 modules.   The Test::Block forum can be found at <http://www.cpanforum.com/dist/Test\-Block>.
.IP "AnnoCPAN" 4
.IX Item "AnnoCPAN"
AnnoCPAN is a web site that allows community annotations of Perl module documentation. The Test::Block annotations can be found at <http://annocpan.org/~ADIE/Test\-Block/>.
.SH "TO DO"
.IX Header "TO DO"
If you think this module should do something that it doesn't (or does something that it shouldn't) please let me know.
.PP
You can see my current to do list at <http://adrianh.tadalist.com/lists/public/15423>, with an \s-1RSS\s0 feed of changes at <http://adrianh.tadalist.com/lists/feed_public/15423>.
.SH "ACKNOWLEDGMENTS"
.IX Header "ACKNOWLEDGMENTS"
Thanks to chromatic and Michael G Schwern for the excellent Test::Builder, without which this module wouldn't be possible.
.PP
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 \f(CW$Plan\fR. Thanks to Nadim Khemir for feedback and Andreas Koenig for spotting bugs.
.SH "AUTHOR"
.IX Header "AUTHOR"
Adrian Howard <adrianh@quietstars.com>
.PP
If you can spare the time, please drop me a line if you find this module useful.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.IP "Test::Group" 4
.IX Item "Test::Group"
A framework for grouping related tests in a test suite
.IP "Test::Class" 4
.IX Item "Test::Class"
Test::Class is an xUnit testing framework for Perl. It allows you to group tests into methods with independent test plans.
.IP "Test::Builder" 4
.IX Item "Test::Builder"
Support module for building test libraries.
.IP "Test::Simple & Test::More" 4
.IX Item "Test::Simple & Test::More"
Basic utilities for writing tests.
.IP "<http://qa.perl.org/test\-modules.html>" 4
.IX Item "<http://qa.perl.org/test-modules.html>"
Overview of some of the many testing modules available on \s-1CPAN.\s0
.SH "LICENCE"
.IX Header "LICENCE"
Copyright 2003\-2006 Adrian Howard, All Rights Reserved.
.PP
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.