local-lib5/man/man3/Template::Test.3pm

   1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sh \" Subsection heading
   6 .br
   7 .if t .Sp
   8 .ne 5
   9 .PP
  10 \fB\\$1\fR
  11 .PP
  12 ..
  13 .de Sp \" Vertical space (when we can't use .PP)
  14 .if t .sp .5v
  15 .if n .sp
  16 ..
  17 .de Vb \" Begin verbatim text
  18 .ft CW
  19 .nf
  20 .ne \\$1
  21 ..
  22 .de Ve \" End verbatim text
  23 .ft R
  24 .fi
  25 ..
  26 .\" Set up some character translations and predefined strings.  \*(-- will
  27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  28 .\" double quote, and \*(R" will give a right double quote.  | will give a
  29 .\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
  30 .\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
  31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
  32 .tr \(*W-|\(bv\*(Tr
  33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  34 .ie n \{\
  35 .    ds -- \(*W-
  36 .    ds PI pi
  37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  39 .    ds L" ""
  40 .    ds R" ""
  41 .    ds C` ""
  42 .    ds C' ""
  43 'br\}
  44 .el\{\
  45 .    ds -- \|\(em\|
  46 .    ds PI \(*p
  47 .    ds L" ``
  48 .    ds R" ''
  49 'br\}
  50 .\"
  51 .\" If the F register is turned on, we'll generate index entries on stderr for
  52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
  53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  54 .\" output yourself in some meaningful fashion.
  55 .if \nF \{\
  56 .    de IX
  57 .    tm Index:\\$1\t\\n%\t"\\$2"
  58 ..
  59 .    nr % 0
  60 .    rr F
  61 .\}
  62 .\"
  63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
  64 .\" way too many mistakes in technical documents.
  65 .hy 0
  66 .if n .na
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "Template::Test 3"
 132 .TH Template::Test 3 "2009-07-04" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 Template::Test \- Module for automating TT2 test scripts
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 .Vb 1
 138 \&    use Template::Test;
 139 .Ve
 140 .PP
 141 .Vb 2
 142 \&    $Template::Test::DEBUG = 0;   # set this true to see each test running
 143 \&    $Template::Test::EXTRA = 2;   # 2 extra tests follow test_expect()...
 144 .Ve
 145 .PP
 146 .Vb 2
 147 \&    # ok() can be called any number of times before test_expect
 148 \&    ok( $true_or_false )
 149 .Ve
 150 .PP
 151 .Vb 3
 152 \&    # test_expect() splits $input into individual tests, processes each
 153 \&    # and compares generated output against expected output
 154 \&    test_expect($input, $template, \e%replace );
 155 .Ve
 156 .PP
 157 .Vb 3
 158 \&    # $input is text or filehandle (e.g. DATA section after __END__)
 159 \&    test_expect( $text );
 160 \&    test_expect( \e*DATA );
 161 .Ve
 162 .PP
 163 .Vb 5
 164 \&    # $template is a Template object or configuration hash
 165 \&    my $template_cfg = { ... };
 166 \&    test_expect( $input, $template_cfg );
 167 \&    my $template_obj = Template\->new($template_cfg);
 168 \&    test_expect( $input, $template_obj );
 169 .Ve
 170 .PP
 171 .Vb 6
 172 \&    # $replace is a hash reference of template variables
 173 \&    my $replace = {
 174 \&        a => 'alpha',
 175 \&        b => 'bravo'
 176 \&    };
 177 \&    test_expect( $input, $template, $replace );
 178 .Ve
 179 .PP
 180 .Vb 3
 181 \&    # ok() called after test_expect should be declared in $EXTRA (2)
 182 \&    ok( $true_or_false )
 183 \&    ok( $true_or_false )
 184 .Ve
 185 .SH "DESCRIPTION"
 186 .IX Header "DESCRIPTION"
 187 The \f(CW\*(C`Template::Test\*(C'\fR module defines the \fItest_expect()\fR and other related
 188 subroutines which can be used to automate test scripts for the
 189 Template Toolkit.  See the numerous tests in the \fIt\fR sub-directory of
 190 the distribution for examples of use.
 191 .SH "PACKAGE SUBROUTINES"
 192 .IX Header "PACKAGE SUBROUTINES"
 193 .Sh "\fItext_expect()\fP"
 194 .IX Subsection "text_expect()"
 195 The \f(CW\*(C`test_expect()\*(C'\fR subroutine splits an input document into a number
 196 of separate tests, processes each one using the Template Toolkit and
 197 then compares the generated output against an expected output, also
 198 specified in the input document.  It generates the familiar
 199 \&\f(CW\*(C`ok\*(C'\fR/\f(CW\*(C`not ok\*(C'\fR output compatible with \f(CW\*(C`Test::Harness\*(C'\fR.
 200 .PP
 201 The test input should be specified as a text string or a reference to
 202 a filehandle (e.g. \f(CW\*(C`GLOB\*(C'\fR or \f(CW\*(C`IO::Handle\*(C'\fR) from which it can be read.  In
 203 particular, this allows the test input to be placed after the \f(CW\*(C`_\|_END_\|_\*(C'\fR
 204 marker and read via the \f(CW\*(C`DATA\*(C'\fR filehandle.
 205 .PP
 206 .Vb 1
 207 \&    use Template::Test;
 208 .Ve
 209 .PP
 210 .Vb 1
 211 \&    test_expect(\e*DATA);
 212 .Ve
 213 .PP
 214 .Vb 6
 215 \&    __END__
 216 \&    # this is the first test (this is a comment)
 217 \&    \-\- test \-\-
 218 \&    blah blah blah [% foo %]
 219 \&    \-\- expect \-\-
 220 \&    blah blah blah value_of_foo
 221 .Ve
 222 .PP
 223 .Vb 5
 224 \&    # here's the second test (no surprise, so is this)
 225 \&    \-\- test \-\-
 226 \&    more blah blah [% bar %]
 227 \&    \-\- expect \-\-
 228 \&    more blah blah value_of_bar
 229 .Ve
 230 .PP
 231 Blank lines between test sections are generally ignored.  Any line starting
 232 with \f(CW\*(C`#\*(C'\fR is treated as a comment and is ignored.
 233 .PP
 234 The second and third parameters to \f(CW\*(C`test_expect()\*(C'\fR are optional.  The second
 235 may be either a reference to a Template object which should be used to
 236 process the template fragments, or a reference to a hash array containing
 237 configuration values which should be used to instantiate a new Template
 238 object.
 239 .PP
 240 .Vb 6
 241 \&    # pass reference to config hash
 242 \&    my $config = {
 243 \&        INCLUDE_PATH => '/here/there:/every/where',
 244 \&        POST_CHOMP   => 1,
 245 \&    };
 246 \&    test_expect(\e*DATA, $config);
 247 .Ve
 248 .PP
 249 .Vb 3
 250 \&    # or create Template object explicitly
 251 \&    my $template = Template\->new($config);
 252 \&    test_expect(\e*DATA, $template);
 253 .Ve
 254 .PP
 255 The third parameter may be used to reference a hash array of template
 256 variable which should be defined when processing the tests.  This is
 257 passed to the Template \fIprocess()\fR method.
 258 .PP
 259 .Vb 4
 260 \&    my $replace = {
 261 \&        a => 'alpha',
 262 \&        b => 'bravo',
 263 \&    };
 264 .Ve
 265 .PP
 266 .Vb 1
 267 \&    test_expect(\e*DATA, $config, $replace);
 268 .Ve
 269 .PP
 270 The second parameter may be left undefined to specify a default Template
 271 configuration.
 272 .PP
 273 .Vb 1
 274 \&    test_expect(\e*DATA, undef, $replace);
 275 .Ve
 276 .PP
 277 For testing the output of different Template configurations, a
 278 reference to a list of named Template objects also may be passed as
 279 the second parameter.
 280 .PP
 281 .Vb 3
 282 \&    my $tt1 = Template\->new({ ... });
 283 \&    my $tt2 = Template\->new({ ... });
 284 \&    my @tts = [ one => $tt1, two => $tt1 ];
 285 .Ve
 286 .PP
 287 The first object in the list is used by default.  Other objects may be
 288 switched in with a '\f(CW\*(C`\-\- use $name \-\-\*(C'\fR' marker.  This should immediately
 289 follow a '\f(CW\*(C`\-\- test \-\-\*(C'\fR' line.  That object will then be used for the rest
 290 of the test, or until a different object is selected.
 291 .PP
 292 .Vb 5
 293 \&    \-\- test \-\-
 294 \&    \-\- use one \-\-
 295 \&    [% blah %]
 296 \&    \-\- expect \-\-
 297 \&    blah, blah
 298 .Ve
 299 .PP
 300 .Vb 4
 301 \&    \-\- test \-\-
 302 \&    still using one...
 303 \&    \-\- expect \-\-
 304 \&    ...
 305 .Ve
 306 .PP
 307 .Vb 5
 308 \&    \-\- test \-\-
 309 \&    \-\- use two \-\-
 310 \&    [% blah %]
 311 \&    \-\- expect \-\-
 312 \&    blah, blah, more blah
 313 .Ve
 314 .PP
 315 The \f(CW\*(C`test_expect()\*(C'\fR sub counts the number of tests, and then calls \fIntests()\fR
 316 to generate the familiar "\f(CW\*(C`1..$ntests\en\*(C'\fR" test harness line.  Each
 317 test defined generates two test numbers.  The first indicates
 318 that the input was processed without error, and the second that the
 319 output matches that expected.
 320 .PP
 321 Additional test may be run before \f(CW\*(C`test_expect()\*(C'\fR by calling \fIok()\fR. These
 322 test results are cached until \fIntests()\fR is called and the final number of
 323 tests can be calculated. Then, the "\f(CW\*(C`1..$ntests\*(C'\fR\*(L" line is output, along with
 324 \&\*(R"\f(CW\*(C`ok $n\*(C'\fR\*(L" / \*(R"\f(CW\*(C`not ok $n\*(C'\fR" lines for each of the cached test result.
 325 Subsequent calls to \fIok()\fR then generate an output line immediately.
 326 .PP
 327 .Vb 2
 328 \&    my $something = SomeObject\->new();
 329 \&    ok( $something );
 330 .Ve
 331 .PP
 332 .Vb 2
 333 \&    my $other = AnotherThing\->new();
 334 \&    ok( $other );
 335 .Ve
 336 .PP
 337 .Vb 1
 338 \&    test_expect(\e*DATA);
 339 .Ve
 340 .PP
 341 If any tests are to follow after \f(CW\*(C`test_expect()\*(C'\fR is called then these
 342 should be pre-declared by setting the \f(CW$EXTRA\fR package variable.  This
 343 value (default: \f(CW0\fR) is added to the grand total calculated by \fIntests()\fR.
 344 The results of the additional tests are also registered by calling \fIok()\fR.
 345 .PP
 346 .Vb 1
 347 \&    $Template::Test::EXTRA = 2;
 348 .Ve
 349 .PP
 350 .Vb 4
 351 \&    # can call ok() any number of times before test_expect()
 352 \&    ok( $did_that_work );
 353 \&    ok( $make_sure );
 354 \&    ok( $dead_certain );
 355 .Ve
 356 .PP
 357 .Vb 2
 358 \&    # <some> number of tests...
 359 \&    test_expect(\e*DATA, $config, $replace);
 360 .Ve
 361 .PP
 362 .Vb 3
 363 \&    # here's those $EXTRA tests
 364 \&    ok( defined $some_result && ref $some_result eq 'ARRAY' );
 365 \&    ok( $some_result\->[0] eq 'some expected value' );
 366 .Ve
 367 .PP
 368 If you don't want to call \f(CW\*(C`test_expect()\*(C'\fR at all then you can call
 369 \&\f(CW\*(C`ntests($n)\*(C'\fR to declare the number of tests and generate the test
 370 header line.  After that, simply call \fIok()\fR for each test passing
 371 a true or false values to indicate that the test passed or failed.
 372 .PP
 373 .Vb 3
 374 \&    ntests(2);
 375 \&    ok(1);
 376 \&    ok(0);
 377 .Ve
 378 .PP
 379 If you're really lazy, you can just call \fIok()\fR and not bother declaring
 380 the number of tests at all.  All tests results will be cached until the
 381 end of the script and then printed in one go before the program exits.
 382 .PP
 383 .Vb 2
 384 \&    ok( $x );
 385 \&    ok( $y );
 386 .Ve
 387 .PP
 388 You can identify only a specific part of the input file for testing
 389 using the '\f(CW\*(C`\-\- start \-\-\*(C'\fR' and '\f(CW\*(C`\-\- stop \-\-\*(C'\fR' markers.  Anything before the
 390 first '\f(CW\*(C`\-\- start \-\-\*(C'\fR' is ignored, along with anything after the next
 391 \&'\f(CW\*(C`\-\- stop \-\-\*(C'\fR' marker.
 392 .PP
 393 .Vb 4
 394 \&    \-\- test \-\-
 395 \&    this is test 1 (not performed)
 396 \&    \-\- expect \-\-
 397 \&    this is test 1 (not performed)
 398 .Ve
 399 .PP
 400 .Vb 1
 401 \&    \-\- start \-\-
 402 .Ve
 403 .PP
 404 .Vb 4
 405 \&    \-\- test \-\-
 406 \&    this is test 2
 407 \&    \-\- expect \-\-
 408 \&    this is test 2
 409 .Ve
 410 .PP
 411 .Vb 1
 412 \&    \-\- stop \-\-
 413 .Ve
 414 .PP
 415 .Vb 1
 416 \&    ...
 417 .Ve
 418 .Sh "\fIntests()\fP"
 419 .IX Subsection "ntests()"
 420 Subroutine used to specify how many tests you're expecting to run.
 421 .Sh "ok($test)"
 422 .IX Subsection "ok($test)"
 423 Generates an "\f(CW\*(C`ok $n\*(C'\fR\*(L" or \*(R"\f(CW\*(C`not ok $n\*(C'\fR" message if \f(CW$test\fR is true or false.
 424 .Sh "not_ok($test)"
 425 .IX Subsection "not_ok($test)"
 426 The logical inverse of \fIok()\fR. Prints an "\f(CW\*(C`ok $n\*(C'\fR" message is \f(CW$test\fR is
 427 \&\fIfalse\fR and vice\-versa.
 428 .Sh "\fIcallsign()\fP"
 429 .IX Subsection "callsign()"
 430 For historical reasons and general utility, the module also defines a
 431 \&\f(CW\*(C`callsign()\*(C'\fR subroutine which returns a hash mapping the letters \f(CW\*(C`a\*(C'\fR
 432 to \f(CW\*(C`z\*(C'\fR to their phonetic alphabet equivalent (e.g. radio callsigns).
 433 This is used by many of the test scripts as a known source of variable values.
 434 .PP
 435 .Vb 1
 436 \&    test_expect(\e*DATA, $config, callsign());
 437 .Ve
 438 .Sh "\fIbanner()\fP"
 439 .IX Subsection "banner()"
 440 This subroutine prints a simple banner including any text passed as parameters.
 441 The \f(CW$DEBUG\fR variable must be set for it to generate any output.
 442 .PP
 443 .Vb 1
 444 \&    banner('Testing something\-or\-other');
 445 .Ve
 446 .PP
 447 example output:
 448 .PP
 449 .Vb 3
 450 \&    #\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
 451 \&    # Testing something\-or\-other (27 tests completed)
 452 \&    #\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
 453 .Ve
 454 .SH "PACKAGE VARIABLES"
 455 .IX Header "PACKAGE VARIABLES"
 456 .Sh "$DEBUG"
 457 .IX Subsection "$DEBUG"
 458 The \f(CW$DEBUG\fR package variable can be set to enable debugging mode.
 459 .Sh "$PRESERVE"
 460 .IX Subsection "$PRESERVE"
 461 The \f(CW$PRESERVE\fR package variable can be set to stop the \fItest_expect()\fR
 462 from converting newlines in the output and expected output into
 463 the literal strings '\en'.
 464 .SH "HISTORY"
 465 .IX Header "HISTORY"
 466 This module started its butt-ugly life as the \f(CW\*(C`t/texpect.pl\*(C'\fR script.  It
 467 was cleaned up to became the \f(CW\*(C`Template::Test\*(C'\fR module some time around
 468 version 0.29.  It underwent further cosmetic surgery for version 2.00
 469 but still retains some remarkable rear-end resemblances.
 470 .PP
 471 Since then the \f(CW\*(C`Test::More\*(C'\fR and related modules have appeared on \s-1CPAN\s0
 472 making this module mostly, but not entirely, redundant.
 473 .ie n .SH "BUGS / KNOWN ""FEATURES"""
 474 .el .SH "BUGS / KNOWN ``FEATURES''"
 475 .IX Header "BUGS / KNOWN FEATURES"
 476 Imports all methods by default.  This is generally a Bad Thing, but
 477 this module is only used in test scripts (i.e. at build time) so a) we
 478 don't really care and b) it saves typing.
 479 .PP
 480 The line splitter may be a bit dumb, especially if it sees lines like
 481 \&\f(CW\*(C`\-\- this \-\-\*(C'\fR that aren't supposed to be special markers.  So don't do that.
 482 .SH "AUTHOR"
 483 .IX Header "AUTHOR"
 484 Andy Wardley <abw@wardley.org> <http://wardley.org/>
 485 .SH "COPYRIGHT"
 486 .IX Header "COPYRIGHT"
 487 Copyright (C) 1996\-2007 Andy Wardley.  All Rights Reserved.
 488 .PP
 489 This module is free software; you can redistribute it and/or
 490 modify it under the same terms as Perl itself.
 491 .SH "SEE ALSO"
 492 .IX Header "SEE ALSO"
 493 Template