1Test::Block(3) User Contributed Perl Documentation Test::Block(3)
2
6 Test::Block - 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 This module allows you to specify the number of expected tests at a
43 finer level of granularity than an entire test script. It is built with
44 Test::Builder and plays happily with Test::More and friends.
45 If you are not already familiar with Test::More now would be the time
47 to go take a look.
48 Creating test blocks
50 Test::Block supplies a special variable $Plan that you can localize to
51 specify the number of tests in a block like this:
52 use Test::More 'no_plan';
54 use Test::Block qw($Plan);
55 {
57 local $Plan = 2;
58 pass('first test');
59 pass('second test');
60 };
61 What if the block runs a different number of tests?
63 If a block doesn't run the number of tests specified in $Plan then
64 Test::Block will automatically produce a failing test. For example:
65 {
67 local $Plan = 2;
68 pass('first test');
69 # oops - forgot second test
70 };
71 will output
73 ok 1 - first test
75 not ok 2 - block 1 expected 2 test(s) and ran 1
76 Tracking the number of remaining tests
78 During the execution of a block $Plan will contain the number of
79 remaining tests that are expected to run so:
80 {
82 local $Plan = 2;
83 diag "$Plan tests to run";
84 pass('first test');
85 diag "$Plan tests to run";
86 pass('second test');
87 diag "$Plan tests to run";
88 };
89 will produce
91 # 2 tests to run
93 ok 1 - first test
94 # 1 tests to run
95 ok 2 - second test
96 # 0 tests to run
97 This can make skip blocks easier to write and maintain, for example:
99 SKIP: {
101 local $Plan = 5;
102 pass('first test');
103 pass('second test');
104 skip "debug tests" => $Plan unless DEBUG > 0;
105 pass('third test');
106 pass('fourth test');
107 skip "high level debug tests" => $Plan unless DEBUG > 2;
108 pass('fifth test');
109 };
110 Named blocks
112 To make debugging easier you can give your blocks an optional name like
113 this:
114 {
116 local $Plan = { example => 2 };
117 pass('first test');
118 # oops - forgot second test
119 };
120 which would output
122 ok 1 - first test
124 not ok 2 - block example expected 2 test(s) and ran 1
125 Test::Block objects
127 The $Plan is implemented using a tied variable that stores and
128 retrieves Test::Block objects. If you want to avoid the tied interface
129 you can use Test::Block objects directly.
130 plan
132 # create a block expecting 4 tests
133 my $block = Test::Block->plan(4);
134 # create a named block with two tests
136 my $block = Test::Block->plan('test name' => 2);
137 You create Test::Block objects with the "plan" method. When the
139 object is destroyed it outputs a failing test if the expected
140 number of tests have not run.
141 remaining
143 You can find out the number of remaining tests in the block by
144 calling the "remaining" method on the object.
145 Test::Block objects overload "" and "0+" to return the result of
147 the remaining method.
148 builder
150 Returns Test::Builder object used by Test::Block. For example:
151 Test::Block->builder->skip('skip a test');
153 See Test::Builder for more information.
155 block_count
157 A class method that returns the number of blocks that have been
158 created. You can use this to check that the expected number of
159 blocks have run by doing something like:
160 is( Test::Block->block_count, 5, 'five blocks run' );
162 at the end of your test script.
164 all_in_block
166 Returns true if all tests so far run have been inside the scope of
167 a Test::Block object.
168 ok( Test::Block->all_in_block, 'all tests run in blocks' );
170
172 None known at the time of writing.
173 If you find any please let me know by e-mail, or report the problem
175 with <http://rt.cpan.org/>.
176
178 perl-qa
179 If you are interested in testing using Perl I recommend you visit
180 <http://qa.perl.org/> and join the excellent perl-qa mailing list.
181 See http://lists.perl.org/showlist.cgi?name=perl-qa
182 <http://lists.perl.org/showlist.cgi?name=perl-qa> for details on
183 how to subscribe.
184 perlmonks
186 You can find users of Test::Block, including the module author, on
187 <http://www.perlmonks.org/>. Feel free to ask questions on
188 Test::Block there.
189 CPAN::Forum
191 The CPAN Forum is a web forum for discussing Perl's CPAN modules.
192 The Test::Block forum can be found at
193 http://www.cpanforum.com/dist/Test-Block
194 <http://www.cpanforum.com/dist/Test-Block>.
195 AnnoCPAN
197 AnnoCPAN is a web site that allows community annotations of Perl
198 module documentation. The Test::Block annotations can be found at
199 http://annocpan.org/~ADIE/Test-Block/
200 <http://annocpan.org/~ADIE/Test-Block/>.
201
203 If you think this module should do something that it doesn't (or does
204 something that it shouldn't) please let me know.
205 You can see my current to do list at
207 <http://adrianh.tadalist.com/lists/public/15423>, with an RSS feed of
208 changes at <http://adrianh.tadalist.com/lists/feed_public/15423>.
209
211 Thanks to chromatic and Michael G Schwern for the excellent
212 Test::Builder, without which this module wouldn't be possible.
213 Thanks to Michael G Schwern and Tony Bowden for the mails on
215 perl-qa@perl.org that sparked the idea for this module. Thanks to
216 Fergal Daly for suggesting named blocks. Thanks to Michael G Schwern
217 for suggesting $Plan. Thanks to Nadim Khemir for feedback.
218
220 Adrian Howard <adrianh@quietstars.com>
221 If you can spare the time, please drop me a line if you find this
223 module useful.
224
226 Test::Group
227 A framework for grouping related tests in a test suite
228 Test::Class
230 Test::Class is an xUnit testing framework for Perl. It allows you
231 to group tests into methods with independent test plans.
232 Test::Builder
234 Support module for building test libraries.
235 Test::Simple & Test::More
237 Basic utilities for writing tests.
238 http://qa.perl.org/test-modules.html <http://qa.perl.org/test-
240 modules.html>
241 Overview of some of the many testing modules available on CPAN.
242
244 Copyright 2003-2006 Adrian Howard, All Rights Reserved.
245 This program is free software; you can redistribute it and/or modify it
247 under the same terms as Perl itself.
248perl v5.12.0 2006-11-29 Test::Block(3)