Your IP : 3.16.51.188
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Strict//EN">
<html>
<head>
<title>Template::Test</title>
<link rel="stylesheet" type="text/css" href="../../css/blue.css" title="Clear Blue">
<link rel="alternate stylesheet" type="text/css" href="../../css/orange.css" title="Clear Orange">
<link rel="alternate stylesheet" type="text/css" href="../../css/green.css" title="Clear Green">
<link rel="alternate stylesheet" type="text/css" href="../../css/purple.css" title="Clear Purple">
<link rel="alternate stylesheet" type="text/css" href="../../css/grey.css" title="Clear Grey">
<!--[if IE 6]>
<link rel="stylesheet" type="text/css" href="../../css/ie6.css" />
<![endif]-->
<link rel="stylesheet" type="text/css" href="/css/print.css" media="print">
<script type="text/javascript" src="../../js/tt2.js"></script>
<meta http-equiv="Content-Type" content="text/html;charset=utf-8">
<meta name="author" content="Andy Wardley">
</head>
<body id="body">
<div id="layout">
<div id="header">
<a href="../../index.html" id="logo" alt="" title="Click for the Home Page"><span class="alt">TT2 Home Page</span></a>
<ul id="trail">
<li><a href="../../modules/index.html">Modules</a></li>
<li><a href="../../modules/Template/index.html">Template::*</a></li>
<li class="last"><a href="../../modules/Template/Test.html">Test.pm</a></li>
</ul>
<div class="controls">
<a href="#" class="menu show" onclick="widescreen_off(); return false" title="Show Menu">
<span class="about">Click to view the menu. It's very nice.</span>
</a>
<a href="#" class="menu hide" onclick="widescreen_on(); return false" title="Hide Menu">
<span class="about">Click to hide the menu and go all widescreen!</span>
</a>
<div class="pager">
<a href="../../modules/Template/Stash/index.html" title="Template::Stash::* Modules" class="go back">Back<span class="about"><h4>Template::Stash::* Modules</h4></span></a>
<a href="../../modules/Template/index.html" title="Template::* Modules" class="go up">Up<span class="about"><h4>Template::* Modules</h4></span></a>
<a href="../../modules/Template/VMethods.html" title="Template::VMethods" class="go next">Next<span class="about"><h4>Template::VMethods</h4>Virtual methods for variables</span></a>
</div>
</div>
<h1 class="headline">Template::Test</h1>
<h2 class="subhead">Module for automating TT2 test scripts</h1>
</div>
<div id="page">
<div id="sidebar">
<a href="../../index.html" id="logo"></a>
<div id="menu">
<ul class="menu">
<li class="l0 first"><a href="../../manual/index.html">Manual</a></li>
<li class="l0"><a href="../../modules/index.html" class="warm">Modules</a></li>
<li class="l1"><a href="../../modules/Template.html">Template.pm</a></li>
<li class="l1"><a href="../../modules/Template/index.html" class="warm">Template::*</a></li>
<li class="l2"><a href="../../modules/Template/Base.html">Base.pm</a></li>
<li class="l2"><a href="../../modules/Template/Config.html">Config.pm</a></li>
<li class="l2"><a href="../../modules/Template/Constants.html">Constants.pm</a></li>
<li class="l2"><a href="../../modules/Template/Context.html">Context.pm</a></li>
<li class="l2"><a href="../../modules/Template/Directive.html">Directive.pm</a></li>
<li class="l2"><a href="../../modules/Template/Document.html">Document.pm</a></li>
<li class="l2"><a href="../../modules/Template/Exception.html">Exception.pm</a></li>
<li class="l2"><a href="../../modules/Template/Filters.html">Filters.pm</a></li>
<li class="l2"><a href="../../modules/Template/Grammar.html">Grammar.pm</a></li>
<li class="l2"><a href="../../modules/Template/Iterator.html">Iterator.pm</a></li>
<li class="l2"><a href="../../modules/Template/Namespace/index.html">Namespace::*</a></li>
<li class="l2"><a href="../../modules/Template/Parser.html">Parser.pm</a></li>
<li class="l2"><a href="../../modules/Template/Plugin.html">Plugin.pm</a></li>
<li class="l2"><a href="../../modules/Template/Plugin/index.html">Plugin::*</a></li>
<li class="l2"><a href="../../modules/Template/Plugins.html">Plugins.pm</a></li>
<li class="l2"><a href="../../modules/Template/Provider.html">Provider.pm</a></li>
<li class="l2"><a href="../../modules/Template/Service.html">Service.pm</a></li>
<li class="l2"><a href="../../modules/Template/Stash.html">Stash.pm</a></li>
<li class="l2"><a href="../../modules/Template/Stash/index.html">Stash::*</a></li>
<li class="l2"><a href="../../modules/Template/Test.html" class="warm">Test.pm</a></li>
<li class="l2"><a href="../../modules/Template/VMethods.html">VMethods.pm</a></li>
<li class="l2"><a href="../../modules/Template/View.html">View.pm</a></li>
<li class="l0"><a href="../../tools/index.html">Tools</a></li>
<li class="l0 last"><a href="../../tutorial/index.html">Tutorial</a></li>
</ul>
<div class="foot"></div>
</div>
</div>
<div id="content">
<div class="section">
<div class="head">
<h1 id="contents" onclick="switch_section(this)" title="Click title to show/hide section content.">Contents</h1>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<ul class="toc">
<li class=""><a href="#SYNOPSIS">SYNOPSIS</a></li>
<li class=""><a href="#DESCRIPTION">DESCRIPTION</a></li>
<li class=""><a href="#PACKAGE_SUBROUTINES">PACKAGE SUBROUTINES</a></li>
<li class="sub"><a href="#method_text_expect">text_expect()</a></li>
<li class="sub"><a href="#method_ntests">ntests()</a></li>
<li class="sub"><a href="#method_ok">ok($test)</a></li>
<li class="sub"><a href="#method_not_ok">not_ok($test)</a></li>
<li class="sub"><a href="#method_callsign">callsign()</a></li>
<li class="sub"><a href="#method_banner">banner()</a></li>
<li class=""><a href="#PACKAGE_VARIABLES">PACKAGE VARIABLES</a></li>
<li class="sub"><a href="#section__DEBUG">$DEBUG</a></li>
<li class="sub"><a href="#section__PRESERVE">$PRESERVE</a></li>
<li class=""><a href="#HISTORY">HISTORY</a></li>
<li class=""><a href="#BUGS_KNOWN_FEATURES_">BUGS / KNOWN "FEATURES"</a></li>
<li class=""><a href="#AUTHOR">AUTHOR</a></li>
<li class=""><a href="#COPYRIGHT">COPYRIGHT</a></li>
<li class=""><a href="#SEE_ALSO">SEE ALSO</a></li>
</ul>
</div>
</div>
<div class="pod">
<div class="section">
<div class="head">
<h1 id="SYNOPSIS" onclick="switch_section(this)" title="Click title to show/hide section content.">SYNOPSIS</h1>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<pre>use 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 ) </pre>
</div>
</div>
<div class="section">
<div class="head">
<h1 id="DESCRIPTION" onclick="switch_section(this)" title="Click title to show/hide section content.">DESCRIPTION</h1>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
The <code>Template::Test</code> module defines the <a
href="#method_test_expect">test_expect()</a> and other related
subroutines which can be used to automate test scripts for the Template
Toolkit. See the numerous tests in the <i>t</i> sub-directory of the
distribution for examples of use.
</p>
</div>
</div>
<div class="section">
<div class="head">
<h1 id="PACKAGE_SUBROUTINES" onclick="switch_section(this)" title="Click title to show/hide section content.">PACKAGE SUBROUTINES</h1>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<div class="subsection">
<div class="head">
<h2 id="method_text_expect" class="method" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">text_expect()</h2>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
The <code>test_expect()</code> 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
<code>ok</code>/<code>not ok</code> output compatible with
<code>Test::Harness</code>.
</p>
<p>
The test input should be specified as a text string or a reference to a
filehandle (e.g. <code>GLOB</code> or <code>IO::Handle</code>) from which
it can be read. In particular, this allows the test input to be placed
after the <code>__END__</code> marker and read via the <code>DATA</code>
filehandle.
</p>
<pre>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</pre>
<p>
Blank lines between test sections are generally ignored. Any line
starting with <code>#</code> is treated as a comment and is ignored.
</p>
<p>
The second and third parameters to <code>test_expect()</code> 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.
</p>
<pre># 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);</pre>
<p>
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 <a href="../../modules/Template.html">Template</a> <a
href="../../modules/Template.html#method_process">process()</a> method.
</p>
<pre>my $replace = {
a => 'alpha',
b => 'bravo',
};
test_expect(\*DATA, $config, $replace);</pre>
<p>
The second parameter may be left undefined to specify a default <a
href="../../modules/Template.html">Template</a> configuration.
</p>
<pre>test_expect(\*DATA, undef, $replace);</pre>
<p>
For testing the output of different <a href="../../modules/Template.html">Template</a> configurations, a reference to a list of named <a
href="../../modules/Template.html">Template</a> objects also may be
passed as the second parameter.
</p>
<pre>my $tt1 = Template->new({ ... });
my $tt2 = Template->new({ ... });
my @tts = [ one => $tt1, two => $tt1 ];</pre>
<p>
The first object in the list is used by default. Other objects may be
switched in with a '<code>-- use $name --</code>' marker. This should
immediately follow a '<code>-- test --</code>' line. That object will
then be used for the rest of the test, or until a different object is
selected.
</p>
<pre>-- test --
-- use one --
[% blah %]
-- expect --
blah, blah
-- test --
still using one...
-- expect --
...
-- test --
-- use two --
[% blah %]
-- expect --
blah, blah, more blah</pre>
<p>
The <code>test_expect()</code> sub counts the number of tests, and then
calls <a href="#method_ntests">ntests()</a> to generate the familiar
"<code>1..$ntests\n</code>" 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.
</p>
<p>
Additional test may be run before <code>test_expect()</code> by calling
<a href="#method_ok">ok()</a>. These test results are cached until <a
href="#method_ntests">ntests()</a> is called and the final number of
tests can be calculated. Then, the "<code>1..$ntests</code>" line is
output, along with "<code>ok $n</code>" / "<code>not ok $n</code>" lines
for each of the cached test result. Subsequent calls to <a
href="#method_ok">ok()</a> then generate an output line immediately.
</p>
<pre>my $something = SomeObject->new();
ok( $something );
my $other = AnotherThing->new();
ok( $other );
test_expect(\*DATA);</pre>
<p>
If any tests are to follow after <code>test_expect()</code> is called
then these should be pre-declared by setting the <code>$EXTRA</code>
package variable. This value (default: <code>0</code>) is added to the
grand total calculated by <a href="#method_ntests">ntests()</a>. The
results of the additional tests are also registered by calling <a
href="#method_ok">ok()</a>.
</p>
<pre>$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' );</pre>
<p>
If you don't want to call <code>test_expect()</code> at all then you can
call <code>ntests($n)</code> to declare the number of tests and generate
the test header line. After that, simply call <a
href="#method_ok">ok()</a> for each test passing a true or false values
to indicate that the test passed or failed.
</p>
<pre>ntests(2);
ok(1);
ok(0);</pre>
<p>
If you're really lazy, you can just call <a href="#method_ok">ok()</a>
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.
</p>
<pre>ok( $x );
ok( $y );</pre>
<p>
You can identify only a specific part of the input file for testing using
the '<code>-- start --</code>' and '<code>-- stop --</code>' markers.
Anything before the first '<code>-- start --</code>' is ignored, along
with anything after the next '<code>-- stop --</code>' marker.
</p>
<pre>-- 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 --
...</pre>
</div>
</div> <div class="subsection">
<div class="head">
<h2 id="method_ntests" class="method" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">ntests()</h2>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
Subroutine used to specify how many tests you're expecting to run.
</p>
</div>
</div> <div class="subsection">
<div class="head">
<h2 id="method_ok" class="method" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">ok($test)</h2>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
Generates an "<code>ok $n</code>" or "<code>not ok $n</code>" message if
<code>$test</code> is true or false.
</p>
</div>
</div> <div class="subsection">
<div class="head">
<h2 id="method_not_ok" class="method" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">not_ok($test)</h2>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
The logical inverse of <a href="#method_ok">ok()</a>. Prints an "<code>ok
$n</code>" message is <code>$test</code> is <i>false</i> and vice-versa.
</p>
</div>
</div> <div class="subsection">
<div class="head">
<h2 id="method_callsign" class="method" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">callsign()</h2>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
For historical reasons and general utility, the module also defines a
<code>callsign()</code> subroutine which returns a hash mapping the
letters <code>a</code> to <code>z</code> 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.
</p>
<pre>test_expect(\*DATA, $config, callsign());</pre>
</div>
</div> <div class="subsection">
<div class="head">
<h2 id="method_banner" class="method" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">banner()</h2>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
This subroutine prints a simple banner including any text passed as
parameters. The <code>$DEBUG</code> variable must be set for it to
generate any output.
</p>
<pre>banner('Testing something-or-other');</pre>
<p>
example output:
</p>
<pre>#------------------------------------------------------------
# Testing something-or-other (27 tests completed)
#------------------------------------------------------------</pre>
</div>
</div>
</div>
</div>
<div class="section">
<div class="head">
<h1 id="PACKAGE_VARIABLES" onclick="switch_section(this)" title="Click title to show/hide section content.">PACKAGE VARIABLES</h1>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<div class="subsection">
<div class="head">
<h2 id="section__DEBUG" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">$DEBUG</h2>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
The $DEBUG package variable can be set to enable debugging mode.
</p>
</div>
</div> <div class="subsection">
<div class="head">
<h2 id="section__PRESERVE" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">$PRESERVE</h2>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
The $PRESERVE package variable can be set to stop the test_expect() from
converting newlines in the output and expected output into the literal
strings '\n'.
</p>
</div>
</div>
</div>
</div>
<div class="section">
<div class="head">
<h1 id="HISTORY" onclick="switch_section(this)" title="Click title to show/hide section content.">HISTORY</h1>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
This module started its butt-ugly life as the <code>t/texpect.pl</code>
script. It was cleaned up to became the <code>Template::Test</code>
module some time around version 0.29. It underwent further cosmetic
surgery for version 2.00 but still retains some remarkable rear-end
resemblances.
</p>
<p>
Since then the <code>Test::More</code> and related modules have appeared
on CPAN making this module mostly, but not entirely, redundant.
</p>
</div>
</div>
<div class="section">
<div class="head">
<h1 id="BUGS_KNOWN_FEATURES_" onclick="switch_section(this)" title="Click title to show/hide section content.">BUGS / KNOWN "FEATURES"</h1>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
Imports 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.
</p>
<p>
The line splitter may be a bit dumb, especially if it sees lines like
<code>-- this --</code> that aren't supposed to be special markers. So
don't do that.
</p>
</div>
</div>
<div class="section">
<div class="head">
<h1 id="AUTHOR" onclick="switch_section(this)" title="Click title to show/hide section content.">AUTHOR</h1>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
Andy Wardley <abw@wardley.org> <a
href="http://wardley.org/">http://wardley.org/</a>
</p>
</div>
</div>
<div class="section">
<div class="head">
<h1 id="COPYRIGHT" onclick="switch_section(this)" title="Click title to show/hide section content.">COPYRIGHT</h1>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved.
</p>
<p>
This module is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
</p>
</div>
</div>
<div class="section">
<div class="head">
<h1 id="SEE_ALSO" onclick="switch_section(this)" title="Click title to show/hide section content.">SEE ALSO</h1>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
<a href="../../modules/Template.html">Template</a>
</p>
</div>
</div>
</div></div>
<br class="clear" />
<div class="pageinfo">
/modules/Template/Test.html last modified 10:55:10 31-May-2007
</div>
</div>
<div id="footer">
<a href="http://opensource.org/" class="osi"></a>
<div class="controls">
<div class="pager">
<a href="../../modules/Template/Stash/index.html" title="Template::Stash::* Modules" class="go back">Back<span class="about"><h4>Template::Stash::* Modules</h4></span></a>
<a href="../../modules/Template/index.html" title="Template::* Modules" class="go up">Up<span class="about"><h4>Template::* Modules</h4></span></a>
<a href="../../modules/Template/VMethods.html" title="Template::VMethods" class="go next">Next<span class="about"><h4>Template::VMethods</h4></span></a>
</div>
</div>
<div class="copyright">
Copyright © 1996-2007 <a href="http://wardley.org/">Andy Wardley</a>. All Rights Reserved.
</div>
<div class="licence">
The <a href="http://template-toolkit.org/">Template Toolkit</a> is <a href="http://opensource.org/">Open Source</a> software.
You can redistribute and/or modify it under the terms of the <a href="http://www.opensource.org/licenses/gpl-license.php">GNU Public Licence</a>
or the <a href="http://www.opensource.org/licenses/artistic-license.php">Perl Artistic Licence</a>.
</div>
</div>
<div id="palette">
<ul>
<li class="first"><a href="#" class="blue" onclick="set_style('Clear Blue')"></a></li>
<li><a href="#" class="orange" onclick="set_style('Clear Orange')"></a></li>
<li><a href="#" class="green" onclick="set_style('Clear Green')"></a></li>
<li><a href="#" class="purple" onclick="set_style('Clear Purple')"></a></li>
<li><a href="#" class="grey" onclick="set_style('Clear Grey')"></a></li>
</ul>
</div>
</div> </body>
</html>