1Test::Block(3)        User Contributed Perl Documentation       Test::Block(3)
2
3
4

NAME

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

SYNOPSIS

9         use Test::More 'no_plan';
10         use Test::Block qw($Plan);
11
12         {
13             # This block should run exactly two tests
14             local $Plan = 2;
15             pass 'first test';
16             # oops. forgot second test
17         };
18
19         SKIP: {
20             local $Plan = 3;
21             pass('first test in second block');
22             skip "skip remaining tests" => $Plan;
23         };
24
25         ok( Test::Block->all_in_block, 'all test run in blocks' );
26         is( Test::Block->block_count, 2, 'two blocks ran' );
27
28         # This produces...
29
30         ok 1 - first test
31         not ok 2 - block expected 2 test(s) and ran 1
32         #     Failed test (foo.pl at line 6)
33         ok 3 - first test in second block
34         ok 4 # skip skip remaining tests
35         ok 5 # skip skip remaining tests
36         ok 6 - all test run in blocks
37         ok 7 - two blocks ran
38         1..7
39         # Looks like you failed 1 tests of 7.
40

DESCRIPTION

42       NOTE: This module was written before subtests existed in TAP and
43       Test::More. These days subtests will probably be a better option for
44       you.
45
46       This module allows you to specify the number of expected tests at a
47       finer level of granularity than an entire test script. It is built with
48       Test::Builder and plays happily with Test::More and friends.
49
50       If you are not already familiar with Test::More now would be the time
51       to go take a look.
52
53   Creating test blocks
54       Test::Block supplies a special variable $Plan that you can localize to
55       specify the number of tests in a block like this:
56
57           use Test::More 'no_plan';
58           use Test::Block qw($Plan);
59
60           {
61               local $Plan = 2;
62               pass('first test');
63               pass('second test');
64           };
65
66   What if the block runs a different number of tests?
67       If a block doesn't run the number of tests specified in $Plan then
68       Test::Block will automatically produce a failing test. For example:
69
70           {
71               local $Plan = 2;
72               pass('first test');
73               # oops - forgot second test
74           };
75
76       will output
77
78           ok 1 - first test
79           not ok 2 - block 1 expected 2 test(s) and ran 1
80
81   Tracking the number of remaining tests
82       During the execution of a block $Plan will contain the number of
83       remaining tests that are expected to run so:
84
85           {
86               local $Plan = 2;
87               diag "$Plan tests to run";
88               pass('first test');
89               diag "$Plan tests to run";
90               pass('second test');
91               diag "$Plan tests to run";
92           };
93
94       will produce
95
96           # 2 tests to run
97           ok 1 - first test
98           # 1 tests to run
99           ok 2 - second test
100           # 0 tests to run
101
102       This can make skip blocks easier to write and maintain, for example:
103
104           SKIP: {
105               local $Plan = 5;
106               pass('first test');
107               pass('second test');
108               skip "debug tests" => $Plan unless DEBUG > 0;
109               pass('third test');
110               pass('fourth test');
111               skip "high level debug tests" => $Plan unless DEBUG > 2;
112               pass('fifth test');
113           };
114
115   Named blocks
116       To make debugging easier you can give your blocks an optional name like
117       this:
118
119           {
120               local $Plan = { example => 2 };
121               pass('first test');
122               # oops - forgot second test
123           };
124
125       which would output
126
127           ok 1 - first test
128           not ok 2 - block example expected 2 test(s) and ran 1
129
130   Test::Block objects
131       The $Plan is implemented using a tied variable that stores and
132       retrieves Test::Block objects. If you want to avoid the tied interface
133       you can use Test::Block objects directly.
134
135       plan
136             # create a block expecting 4 tests
137             my $block = Test::Block->plan(4);
138
139             # create a named block with two tests
140             my $block = Test::Block->plan('test name' => 2);
141
142           You create Test::Block objects with the "plan" method. When the
143           object is destroyed it outputs a failing test if the expected
144           number of tests have not run.
145
146       remaining
147           You can find out the number of remaining tests in the block by
148           calling the "remaining" method on the object.
149
150           Test::Block objects overload "" and "0+" to return the result of
151           the remaining method.
152
153       builder
154           Returns Test::Builder object used by Test::Block. For example:
155
156             Test::Block->builder->skip('skip a test');
157
158           See Test::Builder for more information.
159
160       block_count
161           A class method that returns the number of blocks that have been
162           created. You can use this to check that the expected number of
163           blocks have run by doing something like:
164
165             is( Test::Block->block_count, 5, 'five blocks run' );
166
167           at the end of your test script.
168
169       all_in_block
170           Returns true if all tests so far run have been inside the scope of
171           a Test::Block object.
172
173             ok( Test::Block->all_in_block, 'all tests run in blocks' );
174

BUGS

176       None known at the time of writing.
177
178       If you find any please let me know by e-mail, or report the problem
179       with <http://rt.cpan.org/>.
180

COMMUNITY

182       perl-qa
183           If you are interested in testing using Perl I recommend you visit
184           <http://qa.perl.org/> and join the excellent perl-qa mailing list.
185           See <http://lists.perl.org/showlist.cgi?name=perl-qa> for details
186           on how to subscribe.
187
188       perlmonks
189           You can find users of Test::Block, including the module author, on
190           <http://www.perlmonks.org/>. Feel free to ask questions on
191           Test::Block there.
192
193       CPAN::Forum
194           The CPAN Forum is a web forum for discussing Perl's CPAN modules.
195           The Test::Block forum can be found at
196           <http://www.cpanforum.com/dist/Test-Block>.
197
198       AnnoCPAN
199           AnnoCPAN is a web site that allows community annotations of Perl
200           module documentation. The Test::Block annotations can be found at
201           <http://annocpan.org/~ADIE/Test-Block/>.
202

TO DO

204       If you think this module should do something that it doesn't (or does
205       something that it shouldn't) please let me know.
206
207       You can see my current to do list at
208       <http://adrianh.tadalist.com/lists/public/15423>, with an RSS feed of
209       changes at <http://adrianh.tadalist.com/lists/feed_public/15423>.
210

ACKNOWLEDGMENTS

212       Thanks to chromatic and Michael G Schwern for the excellent
213       Test::Builder, without which this module wouldn't be possible.
214
215       Thanks to Michael G Schwern and Tony Bowden for the mails on
216       perl-qa@perl.org that sparked the idea for this module. Thanks to
217       Fergal Daly for suggesting named blocks. Thanks to Michael G Schwern
218       for suggesting $Plan. Thanks to Nadim Khemir for feedback and Andreas
219       Koenig for spotting bugs.
220

AUTHOR

222       Adrian Howard <adrianh@quietstars.com>
223
224       If you can spare the time, please drop me a line if you find this
225       module useful.
226

SEE ALSO

228       Test::Group
229           A framework for grouping related tests in a test suite
230
231       Test::Class
232           Test::Class is an xUnit testing framework for Perl. It allows you
233           to group tests into methods with independent test plans.
234
235       Test::Builder
236           Support module for building test libraries.
237
238       Test::Simple & Test::More
239           Basic utilities for writing tests.
240
241       <http://qa.perl.org/test-modules.html>
242           Overview of some of the many testing modules available on CPAN.
243

LICENCE

245       Copyright 2003-2006 Adrian Howard, All Rights Reserved.
246
247       This program is free software; you can redistribute it and/or modify it
248       under the same terms as Perl itself.
249
250
251
252perl v5.36.0                      2023-01-20                    Test::Block(3)
Impressum