| 1 |
#============================================================= -*-Perl-*- |
| 2 |
# |
| 3 |
# Template::Test |
| 4 |
# |
| 5 |
# DESCRIPTION |
| 6 |
# Module defining a test harness which processes template input and |
| 7 |
# then compares the output against pre-define expected output. |
| 8 |
# Generates test output compatible with Test::Harness. This was |
| 9 |
# originally the t/texpect.pl script. |
| 10 |
# |
| 11 |
# AUTHOR |
| 12 |
# Andy Wardley <[email protected]> |
| 13 |
# |
| 14 |
# COPYRIGHT |
| 15 |
# Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved. |
| 16 |
# |
| 17 |
# This module is free software; you can redistribute it and/or |
| 18 |
# modify it under the same terms as Perl itself. |
| 19 |
# |
| 20 |
#============================================================================ |
| 21 |
|
| 22 |
package Template::Test; |
| 23 |
|
| 24 |
use strict; |
| 25 |
use warnings; |
| 26 |
use Template qw( :template ); |
| 27 |
use Exporter; |
| 28 |
|
| 29 |
our $VERSION = 2.75; |
| 30 |
our $DEBUG = 0; |
| 31 |
our @ISA = qw( Exporter ); |
| 32 |
our @EXPORT = qw( ntests ok is match flush skip_all test_expect callsign banner ); |
| 33 |
our @EXPORT_OK = ( 'assert' ); |
| 34 |
our %EXPORT_TAGS = ( all => [ @EXPORT_OK, @EXPORT ] ); |
| 35 |
$| = 1; |
| 36 |
|
| 37 |
our $REASON = 'not applicable on this platform'; |
| 38 |
our $NO_FLUSH = 0; |
| 39 |
our $EXTRA = 0; # any extra tests to come after test_expect() |
| 40 |
our $PRESERVE = 0 # don't mangle newlines in output/expect |
| 41 |
unless defined $PRESERVE; |
| 42 |
|
| 43 |
our ($loaded, %callsign); |
| 44 |
|
| 45 |
# always set binmode on Win32 machines so that any output generated |
| 46 |
# is true to what we expect |
| 47 |
$Template::BINMODE = ($^O eq 'MSWin32') ? 1 : 0; |
| 48 |
|
| 49 |
my @results = (); |
| 50 |
my ($ntests, $ok_count); |
| 51 |
*is = \&match; |
| 52 |
|
| 53 |
END { |
| 54 |
# ensure flush() is called to print any cached results |
| 55 |
flush(); |
| 56 |
} |
| 57 |
|
| 58 |
|
| 59 |
#------------------------------------------------------------------------ |
| 60 |
# ntests($n) |
| 61 |
# |
| 62 |
# Declare how many (more) tests are expected to come. If ok() is called |
| 63 |
# before ntests() then the results are cached instead of being printed |
| 64 |
# to STDOUT. When ntests() is called, the total number of tests |
| 65 |
# (including any cached) is known and the "1..$ntests" line can be |
| 66 |
# printed along with the cached results. After that, calls to ok() |
| 67 |
# generated printed output immediately. |
| 68 |
#------------------------------------------------------------------------ |
| 69 |
|
| 70 |
sub ntests { |
| 71 |
$ntests = shift; |
| 72 |
# add any pre-declared extra tests, or pre-stored test @results, to |
| 73 |
# the grand total of tests |
| 74 |
$ntests += $EXTRA + scalar @results; |
| 75 |
$ok_count = 1; |
| 76 |
print $ntests ? "1..$ntests\n" : "1..$ntests # skip $REASON\n"; |
| 77 |
# flush cached results |
| 78 |
foreach my $pre_test (@results) { |
| 79 |
ok(@$pre_test); |
| 80 |
} |
| 81 |
} |
| 82 |
|
| 83 |
|
| 84 |
#------------------------------------------------------------------------ |
| 85 |
# ok($truth, $msg) |
| 86 |
# |
| 87 |
# Tests the value passed for truth and generates an "ok $n" or "not ok $n" |
| 88 |
# line accordingly. If ntests() hasn't been called then we cached |
| 89 |
# results for later, instead. |
| 90 |
#------------------------------------------------------------------------ |
| 91 |
|
| 92 |
sub ok { |
| 93 |
my ($ok, $msg) = @_; |
| 94 |
|
| 95 |
# cache results if ntests() not yet called |
| 96 |
unless ($ok_count) { |
| 97 |
push(@results, [ $ok, $msg ]); |
| 98 |
return $ok; |
| 99 |
} |
| 100 |
|
| 101 |
$msg = defined $msg ? " - $msg" : ''; |
| 102 |
if ($ok) { |
| 103 |
print "ok ", $ok_count++, "$msg\n"; |
| 104 |
} |
| 105 |
else { |
| 106 |
print STDERR "FAILED $ok_count: $msg\n" if defined $msg; |
| 107 |
print "not ok ", $ok_count++, "$msg\n"; |
| 108 |
} |
| 109 |
} |
| 110 |
|
| 111 |
|
| 112 |
|
| 113 |
#------------------------------------------------------------------------ |
| 114 |
# assert($truth, $error) |
| 115 |
# |
| 116 |
# Test value for truth, die if false. |
| 117 |
#------------------------------------------------------------------------ |
| 118 |
|
| 119 |
sub assert { |
| 120 |
my ($ok, $err) = @_; |
| 121 |
return ok(1) if $ok; |
| 122 |
|
| 123 |
# failed |
| 124 |
my ($pkg, $file, $line) = caller(); |
| 125 |
$err ||= "assert failed"; |
| 126 |
$err .= " at $file line $line\n"; |
| 127 |
ok(0); |
| 128 |
die $err; |
| 129 |
} |
| 130 |
|
| 131 |
#------------------------------------------------------------------------ |
| 132 |
# match( $result, $expect ) |
| 133 |
#------------------------------------------------------------------------ |
| 134 |
|
| 135 |
sub match { |
| 136 |
my ($result, $expect, $msg) = @_; |
| 137 |
my $count = $ok_count ? $ok_count : scalar @results + 1; |
| 138 |
|
| 139 |
# force stringification of $result to avoid 'no eq method' overload errors |
| 140 |
$result = "$result" if ref $result; |
| 141 |
|
| 142 |
if ($result eq $expect) { |
| 143 |
return ok(1, $msg); |
| 144 |
} |
| 145 |
else { |
| 146 |
print STDERR "FAILED $count:\n expect: [$expect]\n result: [$result]\n"; |
| 147 |
return ok(0, $msg); |
| 148 |
} |
| 149 |
} |
| 150 |
|
| 151 |
|
| 152 |
#------------------------------------------------------------------------ |
| 153 |
# flush() |
| 154 |
# |
| 155 |
# Flush any tests results. |
| 156 |
#------------------------------------------------------------------------ |
| 157 |
|
| 158 |
sub flush { |
| 159 |
ntests(0) |
| 160 |
unless $ok_count || $NO_FLUSH; |
| 161 |
} |
| 162 |
|
| 163 |
|
| 164 |
#------------------------------------------------------------------------ |
| 165 |
# skip_all($reason) |
| 166 |
# |
| 167 |
# Skip all tests, setting $REASON to contain any message passed. Calls |
| 168 |
# exit(0) which triggers flush() which generates a "1..0 # $REASON" |
| 169 |
# string to keep to test harness happy. |
| 170 |
#------------------------------------------------------------------------ |
| 171 |
|
| 172 |
sub skip_all { |
| 173 |
$REASON = join('', @_); |
| 174 |
exit(0); |
| 175 |
} |
| 176 |
|
| 177 |
|
| 178 |
#------------------------------------------------------------------------ |
| 179 |
# test_expect($input, $template, \%replace) |
| 180 |
# |
| 181 |
# This is the main testing sub-routine. The $input parameter should be a |
| 182 |
# text string or a filehandle reference (e.g. GLOB or IO::Handle) from |
| 183 |
# which the input text can be read. The input should contain a number |
| 184 |
# of tests which are split up and processed individually, comparing the |
| 185 |
# generated output against the expected output. Tests should be defined |
| 186 |
# as follows: |
| 187 |
# |
| 188 |
# -- test -- |
| 189 |
# test input |
| 190 |
# -- expect -- |
| 191 |
# expected output |
| 192 |
# |
| 193 |
# -- test -- |
| 194 |
# etc... |
| 195 |
# |
| 196 |
# The number of tests is determined and ntests() is called to generate |
| 197 |
# the "0..$n" line compatible with Test::Harness. Each test input is |
| 198 |
# then processed by the Template object passed as the second parameter, |
| 199 |
# $template. This may also be a hash reference containing configuration |
| 200 |
# which are used to instantiate a Template object, or may be left |
| 201 |
# undefined in which case a default Template object will be instantiated. |
| 202 |
# The third parameter, also optional, may be a reference to a hash array |
| 203 |
# defining template variables. This is passed to the template process() |
| 204 |
# method. |
| 205 |
#------------------------------------------------------------------------ |
| 206 |
|
| 207 |
sub test_expect { |
| 208 |
my ($src, $tproc, $params) = @_; |
| 209 |
my ($input, @tests); |
| 210 |
my ($output, $expect, $match); |
| 211 |
my $count = 0; |
| 212 |
my $ttprocs; |
| 213 |
|
| 214 |
# read input text |
| 215 |
eval { |
| 216 |
local $/ = undef; |
| 217 |
$input = ref $src ? <$src> : $src; |
| 218 |
}; |
| 219 |
if ($@) { |
| 220 |
ntests(1); ok(0); |
| 221 |
warn "Cannot read input text from $src\n"; |
| 222 |
return undef; |
| 223 |
} |
| 224 |
|
| 225 |
# remove any comment lines |
| 226 |
$input =~ s/^#.*?\n//gm; |
| 227 |
|
| 228 |
# remove anything before '-- start --' and/or after '-- stop --' |
| 229 |
$input = $' if $input =~ /\s*--\s*start\s*--\s*/; |
| 230 |
$input = $` if $input =~ /\s*--\s*stop\s*--\s*/; |
| 231 |
|
| 232 |
@tests = split(/^\s*--\s*test\s*--\s*\n/im, $input); |
| 233 |
|
| 234 |
# if the first line of the file was '--test--' (optional) then the |
| 235 |
# first test will be empty and can be discarded |
| 236 |
shift(@tests) if $tests[0] =~ /^\s*$/; |
| 237 |
|
| 238 |
ntests(3 + scalar(@tests) * 2); |
| 239 |
|
| 240 |
# first test is that Template loaded OK, which it did |
| 241 |
ok(1, 'running test_expect()'); |
| 242 |
|
| 243 |
# optional second param may contain a Template reference or a HASH ref |
| 244 |
# of constructor options, or may be undefined |
| 245 |
if (ref($tproc) eq 'HASH') { |
| 246 |
# create Template object using hash of config items |
| 247 |
$tproc = Template->new($tproc) |
| 248 |
|| die Template->error(), "\n"; |
| 249 |
} |
| 250 |
elsif (ref($tproc) eq 'ARRAY') { |
| 251 |
# list of [ name => $tproc, name => $tproc ], use first $tproc |
| 252 |
$ttprocs = { @$tproc }; |
| 253 |
$tproc = $tproc->[1]; |
| 254 |
} |
| 255 |
elsif (! ref $tproc) { |
| 256 |
$tproc = Template->new() |
| 257 |
|| die Template->error(), "\n"; |
| 258 |
} |
| 259 |
# otherwise, we assume it's a Template reference |
| 260 |
|
| 261 |
# test: template processor created OK |
| 262 |
ok($tproc, 'template processor is engaged'); |
| 263 |
|
| 264 |
# third test is that the input read ok, which it did |
| 265 |
ok(1, 'input read and split into ' . scalar @tests . ' tests'); |
| 266 |
|
| 267 |
# the remaining tests are defined in @tests... |
| 268 |
foreach $input (@tests) { |
| 269 |
$count++; |
| 270 |
my $name = ''; |
| 271 |
|
| 272 |
if ($input =~ s/^\s*-- name:? (.*?) --\s*\n//im) { |
| 273 |
$name = $1; |
| 274 |
} |
| 275 |
else { |
| 276 |
$name = "template text $count"; |
| 277 |
} |
| 278 |
|
| 279 |
# split input by a line like "-- expect --" |
| 280 |
($input, $expect) = |
| 281 |
split(/^\s*--\s*expect\s*--\s*\n/im, $input); |
| 282 |
$expect = '' |
| 283 |
unless defined $expect; |
| 284 |
|
| 285 |
$output = ''; |
| 286 |
|
| 287 |
# input text may be prefixed with "-- use name --" to indicate a |
| 288 |
# Template object in the $ttproc hash which we should use |
| 289 |
if ($input =~ s/^\s*--\s*use\s+(\S+)\s*--\s*\n//im) { |
| 290 |
my $ttname = $1; |
| 291 |
my $ttlookup; |
| 292 |
if ($ttlookup = $ttprocs->{ $ttname }) { |
| 293 |
$tproc = $ttlookup; |
| 294 |
} |
| 295 |
else { |
| 296 |
warn "no such template object to use: $ttname\n"; |
| 297 |
} |
| 298 |
} |
| 299 |
|
| 300 |
# process input text |
| 301 |
$tproc->process(\$input, $params, \$output) || do { |
| 302 |
warn "Template process failed: ", $tproc->error(), "\n"; |
| 303 |
# report failure and automatically fail the expect match |
| 304 |
ok(0, "$name process FAILED: " . subtext($input)); |
| 305 |
ok(0, '(obviously did not match expected)'); |
| 306 |
next; |
| 307 |
}; |
| 308 |
|
| 309 |
# processed OK |
| 310 |
ok(1, "$name processed OK: " . subtext($input)); |
| 311 |
|
| 312 |
# another hack: if the '-- expect --' section starts with |
| 313 |
# '-- process --' then we process the expected output |
| 314 |
# before comparing it with the generated output. This is |
| 315 |
# slightly twisted but it makes it possible to run tests |
| 316 |
# where the expected output isn't static. See t/date.t for |
| 317 |
# an example. |
| 318 |
|
| 319 |
if ($expect =~ s/^\s*--+\s*process\s*--+\s*\n//im) { |
| 320 |
my $out; |
| 321 |
$tproc->process(\$expect, $params, \$out) || do { |
| 322 |
warn("Template process failed (expect): ", |
| 323 |
$tproc->error(), "\n"); |
| 324 |
# report failure and automatically fail the expect match |
| 325 |
ok(0, "failed to process expected output [" |
| 326 |
. subtext($expect) . ']'); |
| 327 |
next; |
| 328 |
}; |
| 329 |
$expect = $out; |
| 330 |
}; |
| 331 |
|
| 332 |
# strip any trailing blank lines from expected and real output |
| 333 |
foreach ($expect, $output) { |
| 334 |
s/[\n\r]*\Z//mg; |
| 335 |
} |
| 336 |
|
| 337 |
$match = ($expect eq $output) ? 1 : 0; |
| 338 |
if (! $match || $DEBUG) { |
| 339 |
print "MATCH FAILED\n" |
| 340 |
unless $match; |
| 341 |
|
| 342 |
my ($copyi, $copye, $copyo) = ($input, $expect, $output); |
| 343 |
unless ($PRESERVE) { |
| 344 |
foreach ($copyi, $copye, $copyo) { |
| 345 |
s/\n/\\n/g; |
| 346 |
} |
| 347 |
} |
| 348 |
printf(" input: [%s]\nexpect: [%s]\noutput: [%s]\n", |
| 349 |
$copyi, $copye, $copyo); |
| 350 |
} |
| 351 |
|
| 352 |
ok($match, $match ? "$name matched expected" : "$name did not match expected"); |
| 353 |
}; |
| 354 |
} |
| 355 |
|
| 356 |
#------------------------------------------------------------------------ |
| 357 |
# callsign() |
| 358 |
# |
| 359 |
# Returns a hash array mapping lower a..z to their phonetic alphabet |
| 360 |
# equivalent. |
| 361 |
#------------------------------------------------------------------------ |
| 362 |
|
| 363 |
sub callsign { |
| 364 |
my %callsign; |
| 365 |
@callsign{ 'a'..'z' } = qw( |
| 366 |
alpha bravo charlie delta echo foxtrot golf hotel india |
| 367 |
juliet kilo lima mike november oscar papa quebec romeo |
| 368 |
sierra tango umbrella victor whisky x-ray yankee zulu ); |
| 369 |
return \%callsign; |
| 370 |
} |
| 371 |
|
| 372 |
|
| 373 |
#------------------------------------------------------------------------ |
| 374 |
# banner($text) |
| 375 |
# |
| 376 |
# Prints a banner with the specified text if $DEBUG is set. |
| 377 |
#------------------------------------------------------------------------ |
| 378 |
|
| 379 |
sub banner { |
| 380 |
return unless $DEBUG; |
| 381 |
my $text = join('', @_); |
| 382 |
my $count = $ok_count ? $ok_count - 1 : scalar @results; |
| 383 |
print "-" x 72, "\n$text ($count tests completed)\n", "-" x 72, "\n"; |
| 384 |
} |
| 385 |
|
| 386 |
|
| 387 |
sub subtext { |
| 388 |
my $text = shift; |
| 389 |
$text =~ s/\s*$//sg; |
| 390 |
$text = substr($text, 0, 32) . '...' if length $text > 32; |
| 391 |
$text =~ s/\n/\\n/g; |
| 392 |
return $text; |
| 393 |
} |
| 394 |
|
| 395 |
|
| 396 |
1; |
| 397 |
|
| 398 |
__END__ |
| 399 |
|
| 400 |
=head1 NAME |
| 401 |
|
| 402 |
Template::Test - Module for automating TT2 test scripts |
| 403 |
|
| 404 |
=head1 SYNOPSIS |
| 405 |
|
| 406 |
use Template::Test; |
| 407 |
|
| 408 |
$Template::Test::DEBUG = 0; # set this true to see each test running |
| 409 |
$Template::Test::EXTRA = 2; # 2 extra tests follow test_expect()... |
| 410 |
|
| 411 |
# ok() can be called any number of times before test_expect |
| 412 |
ok( $true_or_false ) |
| 413 |
|
| 414 |
# test_expect() splits $input into individual tests, processes each |
| 415 |
# and compares generated output against expected output |
| 416 |
test_expect($input, $template, \%replace ); |
| 417 |
|
| 418 |
# $input is text or filehandle (e.g. DATA section after __END__) |
| 419 |
test_expect( $text ); |
| 420 |
test_expect( \*DATA ); |
| 421 |
|
| 422 |
# $template is a Template object or configuration hash |
| 423 |
my $template_cfg = { ... }; |
| 424 |
test_expect( $input, $template_cfg ); |
| 425 |
my $template_obj = Template->new($template_cfg); |
| 426 |
test_expect( $input, $template_obj ); |
| 427 |
|
| 428 |
# $replace is a hash reference of template variables |
| 429 |
my $replace = { |
| 430 |
a => 'alpha', |
| 431 |
b => 'bravo' |
| 432 |
}; |
| 433 |
test_expect( $input, $template, $replace ); |
| 434 |
|
| 435 |
# ok() called after test_expect should be declared in $EXTRA (2) |
| 436 |
ok( $true_or_false ) |
| 437 |
ok( $true_or_false ) |
| 438 |
|
| 439 |
=head1 DESCRIPTION |
| 440 |
|
| 441 |
The C<Template::Test> module defines the L<test_expect()> and other related |
| 442 |
subroutines which can be used to automate test scripts for the |
| 443 |
Template Toolkit. See the numerous tests in the F<t> sub-directory of |
| 444 |
the distribution for examples of use. |
| 445 |
|
| 446 |
=head1 PACKAGE SUBROUTINES |
| 447 |
|
| 448 |
=head2 text_expect() |
| 449 |
|
| 450 |
The C<test_expect()> subroutine splits an input document into a number |
| 451 |
of separate tests, processes each one using the Template Toolkit and |
| 452 |
then compares the generated output against an expected output, also |
| 453 |
specified in the input document. It generates the familiar |
| 454 |
C<ok>/C<not ok> output compatible with C<Test::Harness>. |
| 455 |
|
| 456 |
The test input should be specified as a text string or a reference to |
| 457 |
a filehandle (e.g. C<GLOB> or C<IO::Handle>) from which it can be read. In |
| 458 |
particular, this allows the test input to be placed after the C<__END__> |
| 459 |
marker and read via the C<DATA> filehandle. |
| 460 |
|
| 461 |
use Template::Test; |
| 462 |
|
| 463 |
test_expect(\*DATA); |
| 464 |
|
| 465 |
__END__ |
| 466 |
# this is the first test (this is a comment) |
| 467 |
-- test -- |
| 468 |
blah blah blah [% foo %] |
| 469 |
-- expect -- |
| 470 |
blah blah blah value_of_foo |
| 471 |
|
| 472 |
# here's the second test (no surprise, so is this) |
| 473 |
-- test -- |
| 474 |
more blah blah [% bar %] |
| 475 |
-- expect -- |
| 476 |
more blah blah value_of_bar |
| 477 |
|
| 478 |
Blank lines between test sections are generally ignored. Any line starting |
| 479 |
with C<#> is treated as a comment and is ignored. |
| 480 |
|
| 481 |
The second and third parameters to C<test_expect()> are optional. The second |
| 482 |
may be either a reference to a Template object which should be used to |
| 483 |
process the template fragments, or a reference to a hash array containing |
| 484 |
configuration values which should be used to instantiate a new Template |
| 485 |
object. |
| 486 |
|
| 487 |
# pass reference to config hash |
| 488 |
my $config = { |
| 489 |
INCLUDE_PATH => '/here/there:/every/where', |
| 490 |
POST_CHOMP => 1, |
| 491 |
}; |
| 492 |
test_expect(\*DATA, $config); |
| 493 |
|
| 494 |
# or create Template object explicitly |
| 495 |
my $template = Template->new($config); |
| 496 |
test_expect(\*DATA, $template); |
| 497 |
|
| 498 |
The third parameter may be used to reference a hash array of template |
| 499 |
variable which should be defined when processing the tests. This is |
| 500 |
passed to the L<Template> L<process()|Template#process()> method. |
| 501 |
|
| 502 |
my $replace = { |
| 503 |
a => 'alpha', |
| 504 |
b => 'bravo', |
| 505 |
}; |
| 506 |
|
| 507 |
test_expect(\*DATA, $config, $replace); |
| 508 |
|
| 509 |
The second parameter may be left undefined to specify a default L<Template> |
| 510 |
configuration. |
| 511 |
|
| 512 |
test_expect(\*DATA, undef, $replace); |
| 513 |
|
| 514 |
For testing the output of different L<Template> configurations, a |
| 515 |
reference to a list of named L<Template> objects also may be passed as |
| 516 |
the second parameter. |
| 517 |
|
| 518 |
my $tt1 = Template->new({ ... }); |
| 519 |
my $tt2 = Template->new({ ... }); |
| 520 |
my @tts = [ one => $tt1, two => $tt1 ]; |
| 521 |
|
| 522 |
The first object in the list is used by default. Other objects may be |
| 523 |
switched in with a 'C<-- use $name -->' marker. This should immediately |
| 524 |
follow a 'C<-- test -->' line. That object will then be used for the rest |
| 525 |
of the test, or until a different object is selected. |
| 526 |
|
| 527 |
-- test -- |
| 528 |
-- use one -- |
| 529 |
[% blah %] |
| 530 |
-- expect -- |
| 531 |
blah, blah |
| 532 |
|
| 533 |
-- test -- |
| 534 |
still using one... |
| 535 |
-- expect -- |
| 536 |
... |
| 537 |
|
| 538 |
-- test -- |
| 539 |
-- use two -- |
| 540 |
[% blah %] |
| 541 |
-- expect -- |
| 542 |
blah, blah, more blah |
| 543 |
|
| 544 |
The C<test_expect()> sub counts the number of tests, and then calls L<ntests()> |
| 545 |
to generate the familiar "C<1..$ntests\n>" test harness line. Each |
| 546 |
test defined generates two test numbers. The first indicates |
| 547 |
that the input was processed without error, and the second that the |
| 548 |
output matches that expected. |
| 549 |
|
| 550 |
Additional test may be run before C<test_expect()> by calling L<ok()>. These |
| 551 |
test results are cached until L<ntests()> is called and the final number of |
| 552 |
tests can be calculated. Then, the "C<1..$ntests>" line is output, along with |
| 553 |
"C<ok $n>" / "C<not ok $n>" lines for each of the cached test result. |
| 554 |
Subsequent calls to L<ok()> then generate an output line immediately. |
| 555 |
|
| 556 |
my $something = SomeObject->new(); |
| 557 |
ok( $something ); |
| 558 |
|
| 559 |
my $other = AnotherThing->new(); |
| 560 |
ok( $other ); |
| 561 |
|
| 562 |
test_expect(\*DATA); |
| 563 |
|
| 564 |
If any tests are to follow after C<test_expect()> is called then these |
| 565 |
should be pre-declared by setting the C<$EXTRA> package variable. This |
| 566 |
value (default: C<0>) is added to the grand total calculated by L<ntests()>. |
| 567 |
The results of the additional tests are also registered by calling L<ok()>. |
| 568 |
|
| 569 |
$Template::Test::EXTRA = 2; |
| 570 |
|
| 571 |
# can call ok() any number of times before test_expect() |
| 572 |
ok( $did_that_work ); |
| 573 |
ok( $make_sure ); |
| 574 |
ok( $dead_certain ); |
| 575 |
|
| 576 |
# <some> number of tests... |
| 577 |
test_expect(\*DATA, $config, $replace); |
| 578 |
|
| 579 |
# here's those $EXTRA tests |
| 580 |
ok( defined $some_result && ref $some_result eq 'ARRAY' ); |
| 581 |
ok( $some_result->[0] eq 'some expected value' ); |
| 582 |
|
| 583 |
If you don't want to call C<test_expect()> at all then you can call |
| 584 |
C<ntests($n)> to declare the number of tests and generate the test |
| 585 |
header line. After that, simply call L<ok()> for each test passing |
| 586 |
a true or false values to indicate that the test passed or failed. |
| 587 |
|
| 588 |
ntests(2); |
| 589 |
ok(1); |
| 590 |
ok(0); |
| 591 |
|
| 592 |
If you're really lazy, you can just call L<ok()> and not bother declaring |
| 593 |
the number of tests at all. All tests results will be cached until the |
| 594 |
end of the script and then printed in one go before the program exits. |
| 595 |
|
| 596 |
ok( $x ); |
| 597 |
ok( $y ); |
| 598 |
|
| 599 |
You can identify only a specific part of the input file for testing |
| 600 |
using the 'C<-- start -->' and 'C<-- stop -->' markers. Anything before the |
| 601 |
first 'C<-- start -->' is ignored, along with anything after the next |
| 602 |
'C<-- stop -->' marker. |
| 603 |
|
| 604 |
-- test -- |
| 605 |
this is test 1 (not performed) |
| 606 |
-- expect -- |
| 607 |
this is test 1 (not performed) |
| 608 |
|
| 609 |
-- start -- |
| 610 |
|
| 611 |
-- test -- |
| 612 |
this is test 2 |
| 613 |
-- expect -- |
| 614 |
this is test 2 |
| 615 |
|
| 616 |
-- stop -- |
| 617 |
|
| 618 |
... |
| 619 |
|
| 620 |
=head2 ntests() |
| 621 |
|
| 622 |
Subroutine used to specify how many tests you're expecting to run. |
| 623 |
|
| 624 |
=head2 ok($test) |
| 625 |
|
| 626 |
Generates an "C<ok $n>" or "C<not ok $n>" message if C<$test> is true or false. |
| 627 |
|
| 628 |
=head2 not_ok($test) |
| 629 |
|
| 630 |
The logical inverse of L<ok()>. Prints an "C<ok $n>" message is C<$test> is |
| 631 |
I<false> and vice-versa. |
| 632 |
|
| 633 |
=head2 callsign() |
| 634 |
|
| 635 |
For historical reasons and general utility, the module also defines a |
| 636 |
C<callsign()> subroutine which returns a hash mapping the letters C<a> |
| 637 |
to C<z> to their phonetic alphabet equivalent (e.g. radio callsigns). |
| 638 |
This is used by many of the test scripts as a known source of variable values. |
| 639 |
|
| 640 |
test_expect(\*DATA, $config, callsign()); |
| 641 |
|
| 642 |
=head2 banner() |
| 643 |
|
| 644 |
This subroutine prints a simple banner including any text passed as parameters. |
| 645 |
The C<$DEBUG> variable must be set for it to generate any output. |
| 646 |
|
| 647 |
banner('Testing something-or-other'); |
| 648 |
|
| 649 |
example output: |
| 650 |
|
| 651 |
#------------------------------------------------------------ |
| 652 |
# Testing something-or-other (27 tests completed) |
| 653 |
#------------------------------------------------------------ |
| 654 |
|
| 655 |
=head1 PACKAGE VARIABLES |
| 656 |
|
| 657 |
=head2 $DEBUG |
| 658 |
|
| 659 |
The $DEBUG package variable can be set to enable debugging mode. |
| 660 |
|
| 661 |
=head2 $PRESERVE |
| 662 |
|
| 663 |
The $PRESERVE package variable can be set to stop the test_expect() |
| 664 |
from converting newlines in the output and expected output into |
| 665 |
the literal strings '\n'. |
| 666 |
|
| 667 |
=head1 HISTORY |
| 668 |
|
| 669 |
This module started its butt-ugly life as the C<t/texpect.pl> script. It |
| 670 |
was cleaned up to became the C<Template::Test> module some time around |
| 671 |
version 0.29. It underwent further cosmetic surgery for version 2.00 |
| 672 |
but still retains some remarkable rear-end resemblances. |
| 673 |
|
| 674 |
Since then the C<Test::More> and related modules have appeared on CPAN |
| 675 |
making this module mostly, but not entirely, redundant. |
| 676 |
|
| 677 |
=head1 BUGS / KNOWN "FEATURES" |
| 678 |
|
| 679 |
Imports all methods by default. This is generally a Bad Thing, but |
| 680 |
this module is only used in test scripts (i.e. at build time) so a) we |
| 681 |
don't really care and b) it saves typing. |
| 682 |
|
| 683 |
The line splitter may be a bit dumb, especially if it sees lines like |
| 684 |
C<-- this --> that aren't supposed to be special markers. So don't do that. |
| 685 |
|
| 686 |
=head1 AUTHOR |
| 687 |
|
| 688 |
Andy Wardley E<lt>[email protected]<gt> L<http://wardley.org/> |
| 689 |
|
| 690 |
=head1 COPYRIGHT |
| 691 |
|
| 692 |
Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved. |
| 693 |
|
| 694 |
This module is free software; you can redistribute it and/or |
| 695 |
modify it under the same terms as Perl itself. |
| 696 |
|
| 697 |
=head1 SEE ALSO |
| 698 |
|
| 699 |
L<Template> |
| 700 |
|
| 701 |
=cut |
| 702 |
|
| 703 |
# Local Variables: |
| 704 |
# mode: perl |
| 705 |
# perl-indent-level: 4 |
| 706 |
# indent-tabs-mode: nil |
| 707 |
# End: |
| 708 |
# |
| 709 |
# vim: expandtab shiftwidth=4: |