1Test::Block(3) User Contributed Perl Documentation Test::Block(3)
2
6 Test::Block - DEPRECIATED: Specify fine granularity test plans
7
9 use Test::More 'no_plan';
10 use Test::Block qw($Plan);
11 {
13 # This block should run exactly two tests
14 local $Plan = 2;
15 pass 'first test';
16 # oops. forgot second test
17 };
18 SKIP: {
20 local $Plan = 3;
21 pass('first test in second block');
22 skip "skip remaining tests" => $Plan;
23 };
24 ok( Test::Block->all_in_block, 'all test run in blocks' );
26 is( Test::Block->block_count, 2, 'two blocks ran' );
27 # This produces...
29 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
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 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 If you are not already familiar with Test::More now would be the time
51 to go take a look.
52 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 use Test::More 'no_plan';
58 use Test::Block qw($Plan);
59 {
61 local $Plan = 2;
62 pass('first test');
63 pass('second test');
64 };
65 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 {
71 local $Plan = 2;
72 pass('first test');
73 # oops - forgot second test
74 };
75 will output
77 ok 1 - first test
79 not ok 2 - block 1 expected 2 test(s) and ran 1
80 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 {
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 will produce
95 # 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 This can make skip blocks easier to write and maintain, for example:
103 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 Named blocks
116 To make debugging easier you can give your blocks an optional name like
117 this:
118 {
120 local $Plan = { example => 2 };
121 pass('first test');
122 # oops - forgot second test
123 };
124 which would output
126 ok 1 - first test
128 not ok 2 - block example expected 2 test(s) and ran 1
129 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 plan
136 # create a block expecting 4 tests
137 my $block = Test::Block->plan(4);
138 # create a named block with two tests
140 my $block = Test::Block->plan('test name' => 2);
141 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 remaining
147 You can find out the number of remaining tests in the block by
148 calling the "remaining" method on the object.
149 Test::Block objects overload "" and "0+" to return the result of
151 the remaining method.
152 builder
154 Returns Test::Builder object used by Test::Block. For example:
155 Test::Block->builder->skip('skip a test');
157 See Test::Builder for more information.
159 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 is( Test::Block->block_count, 5, 'five blocks run' );
166 at the end of your test script.
168 all_in_block
170 Returns true if all tests so far run have been inside the scope of
171 a Test::Block object.
172 ok( Test::Block->all_in_block, 'all tests run in blocks' );
174
176 None known at the time of writing.
177 If you find any please let me know by e-mail, or report the problem
179 with <http://rt.cpan.org/>.
180
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 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 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 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
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 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
212 Thanks to chromatic and Michael G Schwern for the excellent
213 Test::Builder, without which this module wouldn't be possible.
214 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
222 Adrian Howard <adrianh@quietstars.com>
223 If you can spare the time, please drop me a line if you find this
225 module useful.
226
228 Test::Group
229 A framework for grouping related tests in a test suite
230 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 Test::Builder
236 Support module for building test libraries.
237 Test::Simple & Test::More
239 Basic utilities for writing tests.
240 <http://qa.perl.org/test-modules.html>
242 Overview of some of the many testing modules available on CPAN.
243
245 Copyright 2003-2006 Adrian Howard, All Rights Reserved.
246 This program is free software; you can redistribute it and/or modify it
248 under the same terms as Perl itself.
249perl v5.36.0 2023-01-20 Test::Block(3)