Contents
TopSYNOPSIS
Topuse Template::Test;
$Template::Test::DEBUG = 0;   # set this true to see each test running
$Template::Test::EXTRA = 2;   # 2 extra tests follow test_expect()...
# ok() can be called any number of times before test_expect
ok( $true_or_false )
# test_expect() splits $input into individual tests, processes each 
# and compares generated output against expected output
test_expect($input, $template, \%replace );
# $input is text or filehandle (e.g. DATA section after __END__)
test_expect( $text );
test_expect( \*DATA );
# $template is a Template object or configuration hash
my $template_cfg = { ... };
test_expect( $input, $template_cfg );
my $template_obj = Template->new($template_cfg);
test_expect( $input, $template_obj );
# $replace is a hash reference of template variables
my $replace = {
    a => 'alpha',
    b => 'bravo'
};
test_expect( $input, $template, $replace );
# ok() called after test_expect should be declared in $EXTRA (2)
ok( $true_or_false )   
ok( $true_or_false )
              DESCRIPTION
Top
                      The Template::Test module defines the test_expect() and other related
                      subroutines which can be used to automate test scripts for the Template
                      Toolkit. See the numerous tests in the t sub-directory of the
                      distribution for examples of use.
                    
PACKAGE SUBROUTINES
Toptext_expect()
Top
                          The test_expect() subroutine splits an input document into a
                          number of separate tests, processes each one using the Template Toolkit
                          and then compares the generated output against an expected output, also
                          specified in the input document. It generates the familiar
                          ok/not ok output compatible with
                          Test::Harness.
                        
                          The test input should be specified as a text string or a reference to a
                          filehandle (e.g. GLOB or IO::Handle) from which
                          it can be read. In particular, this allows the test input to be placed
                          after the __END__ marker and read via the DATA
                          filehandle.
                        
use Template::Test; test_expect(\*DATA); __END__ # this is the first test (this is a comment) -- test -- blah blah blah [% foo %] -- expect -- blah blah blah value_of_foo # here's the second test (no surprise, so is this) -- test -- more blah blah [% bar %] -- expect -- more blah blah value_of_bar
                          Blank lines between test sections are generally ignored. Any line
                          starting with # is treated as a comment and is ignored.
                        
                          The second and third parameters to test_expect() are
                          optional. The second may be either a reference to a Template object which
                          should be used to process the template fragments, or a reference to a
                          hash array containing configuration values which should be used to
                          instantiate a new Template object.
                        
# pass reference to config hash
my $config = {
    INCLUDE_PATH => '/here/there:/every/where',
    POST_CHOMP   => 1,
};
test_expect(\*DATA, $config);
# or create Template object explicitly
my $template = Template->new($config);
test_expect(\*DATA, $template);
                        The third parameter may be used to reference a hash array of template variable which should be defined when processing the tests. This is passed to the Template process() method.
my $replace = {
    a => 'alpha',
    b => 'bravo',
};
test_expect(\*DATA, $config, $replace);
                        The second parameter may be left undefined to specify a default Template configuration.
test_expect(\*DATA, undef, $replace);
For testing the output of different Template configurations, a reference to a list of named Template objects also may be passed as the second parameter.
my $tt1 = Template->new({ ... });
my $tt2 = Template->new({ ... });
my @tts = [ one => $tt1, two => $tt1 ];
                        
                          The first object in the list is used by default. Other objects may be
                          switched in with a '-- use $name --' marker. This should
                          immediately follow a '-- test --' line. That object will
                          then be used for the rest of the test, or until a different object is
                          selected.
                        
-- test -- -- use one -- [% blah %] -- expect -- blah, blah -- test -- still using one... -- expect -- ... -- test -- -- use two -- [% blah %] -- expect -- blah, blah, more blah
                          The test_expect() sub counts the number of tests, and then
                          calls ntests() to generate the familiar
                          "1..$ntests\n" test harness line. Each test defined
                          generates two test numbers. The first indicates that the input was
                          processed without error, and the second that the output matches that
                          expected.
                        
                          Additional test may be run before test_expect() by calling
                          ok(). These test results are cached until ntests() is called and the final number of
                          tests can be calculated. Then, the "1..$ntests" line is
                          output, along with "ok $n" / "not ok $n" lines
                          for each of the cached test result. Subsequent calls to ok() then generate an output line immediately.
                        
my $something = SomeObject->new(); ok( $something ); my $other = AnotherThing->new(); ok( $other ); test_expect(\*DATA);
                          If any tests are to follow after test_expect() is called
                          then these should be pre-declared by setting the $EXTRA
                          package variable. This value (default: 0) is added to the
                          grand total calculated by ntests(). The
                          results of the additional tests are also registered by calling ok().
                        
$Template::Test::EXTRA = 2; # can call ok() any number of times before test_expect() ok( $did_that_work ); ok( $make_sure ); ok( $dead_certain ); # <some> number of tests... test_expect(\*DATA, $config, $replace); # here's those $EXTRA tests ok( defined $some_result && ref $some_result eq 'ARRAY' ); ok( $some_result->[0] eq 'some expected value' );
                          If you don't want to call test_expect() at all then you can
                          call ntests($n) to declare the number of tests and generate
                          the test header line. After that, simply call ok() for each test passing a true or false values
                          to indicate that the test passed or failed.
                        
ntests(2); ok(1); ok(0);
If you're really lazy, you can just call ok() and not bother declaring the number of tests at all. All tests results will be cached until the end of the script and then printed in one go before the program exits.
ok( $x ); ok( $y );
                          You can identify only a specific part of the input file for testing using
                          the '-- start --' and '-- stop --' markers.
                          Anything before the first '-- start --' is ignored, along
                          with anything after the next '-- stop --' marker.
                        
-- test -- this is test 1 (not performed) -- expect -- this is test 1 (not performed) -- start -- -- test -- this is test 2 -- expect -- this is test 2 -- stop -- ...
ntests()
TopSubroutine used to specify how many tests you're expecting to run.
ok($test)
Top
                          Generates an "ok $n" or "not ok $n" message if
                          $test is true or false.
                        
not_ok($test)
Top
                          The logical inverse of ok(). Prints an "ok
                          $n" message is $test is false and vice-versa.
                        
callsign()
Top
                          For historical reasons and general utility, the module also defines a
                          callsign() subroutine which returns a hash mapping the
                          letters a to z to their phonetic alphabet
                          equivalent (e.g. radio callsigns). This is used by many of the test
                          scripts as a known source of variable values.
                        
test_expect(\*DATA, $config, callsign());
banner()
Top
                          This subroutine prints a simple banner including any text passed as
                          parameters. The $DEBUG variable must be set for it to
                          generate any output.
                        
banner('Testing something-or-other');
                        example output:
#------------------------------------------------------------ # Testing something-or-other (27 tests completed) #------------------------------------------------------------
PACKAGE VARIABLES
TopHISTORY
Top
                      This module started its butt-ugly life as the t/texpect.pl
                      script. It was cleaned up to became the Template::Test
                      module some time around version 0.29. It underwent further cosmetic
                      surgery for version 2.00 but still retains some remarkable rear-end
                      resemblances.
                    
                      Since then the Test::More and related modules have appeared
                      on CPAN making this module mostly, but not entirely, redundant.
                    
BUGS / KNOWN "FEATURES"
TopImports all methods by default. This is generally a Bad Thing, but this module is only used in test scripts (i.e. at build time) so a) we don't really care and b) it saves typing.
                      The line splitter may be a bit dumb, especially if it sees lines like
                      -- this -- that aren't supposed to be special markers. So
                      don't do that.
                    
AUTHOR
TopAndy Wardley <abw@wardley.org> http://wardley.org/
COPYRIGHT
TopCopyright (C) 1996-2007 Andy Wardley. All Rights Reserved.
This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.