1Template::Test(3) User Contributed Perl Documentation Template::Test(3)
2
6 Template::Test - Module for automating TT2 test scripts
7
9 use Template::Test;
10 $Template::Test::DEBUG = 0; # set this true to see each test running
12 $Template::Test::EXTRA = 2; # 2 extra tests follow test_expect()...
13 # ok() can be called any number of times before test_expect
15 ok( $true_or_false )
16 # test_expect() splits $input into individual tests, processes each
18 # and compares generated output against expected output
19 test_expect($input, $template, \%replace );
20 # $input is text or filehandle (e.g. DATA section after __END__)
22 test_expect( $text );
23 test_expect( \*DATA );
24 # $template is a Template object or configuration hash
26 my $template_cfg = { ... };
27 test_expect( $input, $template_cfg );
28 my $template_obj = Template->new($template_cfg);
29 test_expect( $input, $template_obj );
30 # $replace is a hash reference of template variables
32 my $replace = {
33 a => 'alpha',
34 b => 'bravo'
35 };
36 test_expect( $input, $template, $replace );
37 # ok() called after test_expect should be declared in $EXTRA (2)
39 ok( $true_or_false )
40 ok( $true_or_false )
41
43 The Template::Test module defines the test_expect() and other related
44 subroutines which can be used to automate test scripts for the Template
45 Toolkit. See the numerous tests in the 't' sub-directory of the dis‐
46 tribution for examples of use.
47 The test_expect() subroutine splits an input document into a number of
49 separate tests, processes each one using the Template Toolkit and then
50 compares the generated output against an expected output, also speci‐
51 fied in the input document. It generates the familiar "ok/not ok" out‐
52 put compatible with Test::Harness.
53 The test input should be specified as a text string or a reference to a
55 filehandle (e.g. GLOB or IO::Handle) from which it can be read. In
56 particular, this allows the test input to be placed after the __END__
57 marker and read via the DATA filehandle.
58 use Template::Test;
60 test_expect(\*DATA);
62 __END__
64 # this is the first test (this is a comment)
65 -- test --
66 blah blah blah [% foo %]
67 -- expect --
68 blah blah blah value_of_foo
69 # here's the second test (no surprise, so is this)
71 -- test --
72 more blah blah [% bar %]
73 -- expect --
74 more blah blah value_of_bar
75 Blank lines between test sections are generally ignored. Any line
77 starting with '#' is treated as a comment and is ignored.
78 The second and third parameters to test_expect() are optional. The
80 second may be either a reference to a Template object which should be
81 used to process the template fragments, or a reference to a hash array
82 containing configuration values which should be used to instantiate a
83 new Template object.
84 # pass reference to config hash
86 my $config = {
87 INCLUDE_PATH => '/here/there:/every/where',
88 POST_CHOMP => 1,
89 };
90 test_expect(\*DATA, $config);
91 # or create Template object explicitly
93 my $template = Template->new($config);
94 test_expect(\*DATA, $template);
95 The third parameter may be used to reference a hash array of template
97 variable which should be defined when processing the tests. This is
98 passed to the Template process() method.
99 my $replace = {
101 a => 'alpha',
102 b => 'bravo',
103 };
104 test_expect(\*DATA, $config, $replace);
106 The second parameter may be left undefined to specify a default Tem‐
108 plate configuration.
109 test_expect(\*DATA, undef, $replace);
111 For testing the output of different Template configurations, a refer‐
113 ence to a list of named Template objects also may be passed as the sec‐
114 ond parameter.
115 my $tt1 = Template->new({ ... });
117 my $tt2 = Template->new({ ... });
118 my @tts = [ one => $tt1, two => $tt1 ];
119 The first object in the list is used by default. Other objects may be
121 switched in with the '-- use $name --' marker. This should immediately
122 follow a '-- test --' line. That object will then be used for the rest
123 of the test, or until a different object is selected.
124 -- test --
126 -- use one --
127 [% blah %]
128 -- expect --
129 blah, blah
130 -- test --
132 still using one...
133 -- expect --
134 ...
135 -- test --
137 -- use two --
138 [% blah %]
139 -- expect --
140 blah, blah, more blah
141 The test_expect() sub counts the number of tests, and then calls
143 ntests() to generate the familiar "1..$ntests\n" test harness line.
144 Each test defined generates two test numbers. The first indicates that
145 the input was processed without error, and the second that the output
146 matches that expected.
147 Additional test may be run before test_expect() by calling ok(). These
149 test results are cached until ntests() is called and the final number
150 of tests can be calculated. Then, the "1..$ntests" line is output,
151 along with "ok $n" / "not ok $n" lines for each of the cached test
152 result. Subsequent calls to ok() then generate an output line immedi‐
153 ately.
154 my $something = SomeObject->new();
156 ok( $something );
157 my $other = AnotherThing->new();
159 ok( $other );
160 test_expect(\*DATA);
162 If any tests are to follow after test_expect() is called then these
164 should be pre-declared by setting the $EXTRA package variable. This
165 value (default: 0) is added to the grand total calculated by ntests().
166 The results of the additional tests are also registered by calling
167 ok().
168 $Template::Test::EXTRA = 2;
170 # can call ok() any number of times before test_expect()
172 ok( $did_that_work );
173 ok( $make_sure );
174 ok( $dead_certain );
175 # <some> number of tests...
177 test_expect(\*DATA, $config, $replace);
178 # here's those $EXTRA tests
180 ok( defined $some_result && ref $some_result eq 'ARRAY' );
181 ok( $some_result->[0] eq 'some expected value' );
182 If you don't want to call test_expect() at all then you can call
184 ntests($n) to declare the number of tests and generate the test header
185 line. After that, simply call ok() for each test passing a true or
186 false values to indicate that the test passed or failed.
187 ntests(2);
189 ok(1);
190 ok(0);
191 If you're really lazy, you can just call ok() and not bother declaring
193 the number of tests at all. All tests results will be cached until the
194 end of the script and then printed in one go before the program exits.
195 ok( $x );
197 ok( $y );
198 You can identify only a specific part of the input file for testing
200 using the '-- start --' and '-- stop --' markers. Anything before the
201 first '-- start --' is ignored, along with anything after the next '--
202 stop --' marker.
203 -- test --
205 this is test 1 (not performed)
206 -- expect --
207 this is test 1 (not performed)
208 -- start --
210 -- test --
212 this is test 2
213 -- expect --
214 this is test 2
215 -- stop --
217 ...
219 For historical reasons and general utility, the module also defines a
221 'callsign' subroutine which returns a hash mapping a..z to their pho‐
222 netic alphabet equivalent (e.g. radio callsigns). This is used by many
223 of the test scripts as a "known source" of variable values.
224 test_expect(\*DATA, $config, callsign());
226 A banner() subroutine is also provided which prints a simple banner
228 including any text passed as parameters, if $DEBUG is set.
229 banner('Testing something-or-other');
231 example output:
233 #------------------------------------------------------------
235 # Testing something-or-other (27 tests completed)
236 #------------------------------------------------------------
237 The $DEBUG package variable can be set to enable debugging mode.
239 The $PRESERVE package variable can be set to stop the test_expect()
241 from converting newlines in the output and expected output into the
242 literal strings '\n'.
243
245 This module started its butt-ugly life as the t/texpect.pl script. It
246 was cleaned up to became the Template::Test module some time around
247 version 0.29. It underwent further cosmetic surgery for version 2.00
248 but still retains some rear-end resemblances.
249
251 Imports all methods by default. This is generally a Bad Thing, but
252 this module is only used in test scripts (i.e. at build time) so a) we
253 don't really care and b) it saves typing.
254 The line splitter may be a bit dumb, especially if it sees lines like
256 -- this -- that aren't supposed to be special markers. So don't do
257 that.
258
260 Andy Wardley <abw@wardley.org>
261 <http://wardley.org/⎪http://wardley.org/>
263
265 2.75, distributed as part of the Template Toolkit version 2.18,
266 released on 09 February 2007.
267
269 Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved.
270 This module is free software; you can redistribute it and/or modify it
272 under the same terms as Perl itself.
273
275 Template
276perl v5.8.8 2007-02-09 Template::Test(3)