harness.html

来自「perl教程」· HTML 代码 · 共 465 行 · 第 1/2 页

<?xml version="1.0" ?>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<!-- saved from url=(0017)http://localhost/ -->
<script language="JavaScript" src="../../displayToc.js"></script>
<script language="JavaScript" src="../../tocParas.js"></script>
<script language="JavaScript" src="../../tocTab.js"></script>
<link rel="stylesheet" type="text/css" href="../../scineplex.css">
<title>Test::Harness - Run Perl standard test scripts with statistics</title>
<link rel="stylesheet" href="../../Active.css" type="text/css" />
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
<link rev="made" href="mailto:" />
</head>

<body>

<script>writelinks('__top__',2);</script>
<h1><a>Test::Harness - Run Perl standard test scripts with statistics</a></h1>
<p><a name="__index__"></a></p>

<!-- INDEX BEGIN -->

<ul>

	<li><a href="#name">NAME</a></li>
	<li><a href="#version">VERSION</a></li>
	<li><a href="#synopsis">SYNOPSIS</a></li>
	<li><a href="#description">DESCRIPTION</a></li>
	<ul>

		<li><a href="#taint_mode">Taint mode</a></li>
		<li><a href="#configuration_variables_">Configuration variables.</a></li>
		<li><a href="#failure">Failure</a></li>
		<li><a href="#functions">Functions</a></li>
	</ul>

	<li><a href="#export">EXPORT</a></li>
	<li><a href="#diagnostics">DIAGNOSTICS</a></li>
	<li><a href="#environment_variables_that_test__harness_sets">ENVIRONMENT VARIABLES THAT TEST::HARNESS SETS</a></li>
	<li><a href="#environment_variables_that_affect_test__harness">ENVIRONMENT VARIABLES THAT AFFECT TEST::HARNESS</a></li>
	<li><a href="#example">EXAMPLE</a></li>
	<li><a href="#see_also">SEE ALSO</a></li>
	<li><a href="#todo">TODO</a></li>
	<li><a href="#bugs">BUGS</a></li>
	<li><a href="#authors">AUTHORS</a></li>
	<li><a href="#copyright">COPYRIGHT</a></li>
</ul>
<!-- INDEX END -->

<hr />
<p>
</p>
<h1><a name="name">NAME</a></h1>
<p>Test::Harness - Run Perl standard test scripts with statistics</p>
<p>
</p>
<hr />
<h1><a name="version">VERSION</a></h1>
<p>Version 2.56</p>
<p>
</p>
<hr />
<h1><a name="synopsis">SYNOPSIS</a></h1>
<pre>
  <span class="keyword">use</span> <span class="variable">Test::Harness</span><span class="operator">;</span>
</pre>
<pre>
  <span class="variable">runtests</span><span class="operator">(</span><span class="variable">@test_files</span><span class="operator">);</span>
</pre>
<p>
</p>
<hr />
<h1><a name="description">DESCRIPTION</a></h1>
<p><strong>STOP!</strong> If all you want to do is write a test script, consider
using Test::Simple.  Test::Harness is the module that reads the
output from Test::Simple, Test::More and other modules based on
Test::Builder.  You don't need to know about Test::Harness to use
those modules.</p>
<p>Test::Harness runs tests and expects output from the test in a
certain format.  That format is called TAP, the Test Anything
Protocol.  It is defined in <a href="../../lib/Test/Harness/TAP.html">the Test::Harness::TAP manpage</a>.</p>
<p><a href="#item_runtests"><code>Test::Harness::runtests(@tests)</code></a> runs all the testscripts named
as arguments and checks standard output for the expected strings
in TAP format.</p>
<p>The <em>prove</em> utility is a thin wrapper around Test::Harness.</p>
<p>
</p>
<h2><a name="taint_mode">Taint mode</a></h2>
<p>Test::Harness will honor the <a href="../../lib/Pod/perlrun.html#item__2dt"><code>-T</code></a> or <a href="../../lib/Pod/perlrun.html#item__2dt"><code>-t</code></a> in the #! line on your
test files.  So if you begin a test with:</p>
<pre>
    <span class="comment">#!perl -T</span>
</pre>
<p>the test will be run with taint mode on.</p>
<p>
</p>
<h2><a name="configuration_variables_">Configuration variables.</a></h2>
<p>These variables can be used to configure the behavior of
Test::Harness.  They are exported on request.</p>
<dl>
<dt><strong><a name="item__test__harness__verbose"><code>$Test::Harness::Verbose</code></a></strong>

<dd>
<p>The package variable <a href="#item__test__harness__verbose"><code>$Test::Harness::Verbose</code></a> is exportable and can be
used to let <a href="#item_runtests"><code>runtests()</code></a> display the standard output of the script
without altering the behavior otherwise.  The <em>prove</em> utility's <a href="../../lib/Pod/perlrun.html#item__2dv"><code>-v</code></a>
flag will set this.</p>
</dd>
</li>
<dt><strong><a name="item__test__harness__switches"><code>$Test::Harness::switches</code></a></strong>

<dd>
<p>The package variable <a href="#item__test__harness__switches"><code>$Test::Harness::switches</code></a> is exportable and can be
used to set perl command line options used for running the test
script(s). The default value is <a href="../../lib/Pod/perlrun.html#item__2dw"><code>-w</code></a>. It overrides <code>HARNESS_SWITCHES</code>.</p>
</dd>
</li>
<dt><strong><a name="item__test__harness__timer"><code>$Test::Harness::Timer</code></a></strong>

<dd>
<p>If set to true, and <code>Time::HiRes</code> is available, print elapsed seconds
after each test file.</p>
</dd>
</li>
</dl>
<p>
</p>
<h2><a name="failure">Failure</a></h2>
<p>When tests fail, analyze the summary report:</p>
<pre>
  t/base..............ok
  t/nonumbers.........ok
  t/ok................ok
  t/test-harness......ok
  t/waterloo..........dubious
          Test returned status 3 (wstat 768, 0x300)
  DIED. FAILED tests 1, 3, 5, 7, 9, 11, 13, 15, 17, 19
          Failed 10/20 tests, 50.00% okay
  Failed Test  Stat Wstat Total Fail  Failed  List of Failed
  -----------------------------------------------------------------------
  t/waterloo.t    3   768    20   10  50.00%  1 3 5 7 9 11 13 15 17 19
  Failed 1/5 test scripts, 80.00% okay. 10/44 subtests failed, 77.27% okay.</pre>
<p>Everything passed but <em>t/waterloo.t</em>.  It failed 10 of 20 tests and
exited with non-zero status indicating something dubious happened.</p>
<p>The columns in the summary report mean:</p>
<dl>
<dt><strong><a name="item_failed_test"><strong>Failed Test</strong></a></strong>

<dd>
<p>The test file which failed.</p>
</dd>
</li>
<dt><strong><a name="item_stat"><strong>Stat</strong></a></strong>

<dd>
<p>If the test exited with non-zero, this is its exit status.</p>
</dd>
</li>
<dt><strong><a name="item_wstat"><strong>Wstat</strong></a></strong>

<dd>
<p>The wait status of the test.</p>
</dd>
</li>
<dt><strong><a name="item_total"><strong>Total</strong></a></strong>

<dd>
<p>Total number of tests expected to run.</p>
</dd>
</li>
<dt><strong><a name="item_fail"><strong>Fail</strong></a></strong>

<dd>
<p>Number which failed, either from &quot;not ok&quot; or because they never ran.</p>
</dd>
</li>
<dt><strong><a name="item_failed"><strong>Failed</strong></a></strong>

<dd>
<p>Percentage of the total tests which failed.</p>
</dd>
</li>
<dt><strong><a name="item_list_of_failed"><strong>List of Failed</strong></a></strong>

<dd>
<p>A list of the tests which failed.  Successive failures may be
abbreviated (ie. 15-20 to indicate that tests 15, 16, 17, 18, 19 and
20 failed).</p>
</dd>
</li>
</dl>
<p>
</p>
<h2><a name="functions">Functions</a></h2>
<p>Test::Harness currently only has one function, here it is.</p>
<dl>
<dt><strong><a name="item_runtests"><strong>runtests</strong></a></strong>

<dd>
<pre>
  <span class="keyword">my</span> <span class="variable">$allok</span> <span class="operator">=</span> <span class="variable">runtests</span><span class="operator">(</span><span class="variable">@test_files</span><span class="operator">);</span>
</pre>
</dd>
<dd>
<p>This runs all the given <em>@test_files</em> and divines whether they passed
or failed based on their output to STDOUT (details above).  It prints
out each individual test which failed along with a summary report and
a how long it all took.</p>
</dd>
<dd>
<p>It returns true if everything was ok.  Otherwise it will <a href="../../lib/Pod/perlfunc.html#item_die"><code>die()</code></a> with
one of the messages in the DIAGNOSTICS section.</p>
</dd>
</dl>
<p>
</p>
<hr />
<h1><a name="export">EXPORT</a></h1>
<p><code>&amp;runtests</code> is exported by Test::Harness by default.</p>
<p><code>$verbose</code>, <code>$switches</code> and <code>$debug</code> are exported upon request.</p>
<p>
</p>
<hr />
<h1><a name="diagnostics">DIAGNOSTICS</a></h1>
<dl>
<dt><strong><a name="item_all_tests_successful_2e_5cnfiles_3d_25d_2c_tests_3"><code>All tests successful.\nFiles=%d,  Tests=%d, %s</code></a></strong>

<dd>
<p>If all tests are successful some statistics about the performance are
printed.</p>
</dd>
</li>