tap.html

来自「perl教程」· HTML 代码 · 共 432 行 · 第 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::TAP - Documentation for the TAP format</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__',3);</script>
<h1><a>Test::Harness::TAP - Documentation for the TAP format</a></h1>
<p><a name="__index__"></a></p>

<!-- INDEX BEGIN -->

<ul>

	<li><a href="#name">NAME</a></li>
	<li><a href="#synopsis">SYNOPSIS</a></li>
	<li><a href="#todo">TODO</a></li>
	<li><a href="#the_tap_format">THE TAP FORMAT</a></li>
	<li><a href="#harness_behavior">HARNESS BEHAVIOR</a></li>
	<li><a href="#tests_lines_and_the_plan">TESTS LINES AND THE PLAN</a></li>
	<ul>

		<li><a href="#the_plan">The plan</a></li>
		<li><a href="#the_test_line">The test line</a></li>
	</ul>

	<li><a href="#directives">DIRECTIVES</a></li>
	<ul>

		<li><a href="#todo_tests">TODO tests</a></li>
		<li><a href="#skipping_tests">Skipping tests</a></li>
	</ul>

	<li><a href="#other_lines">OTHER LINES</a></li>
	<ul>

		<li><a href="#bail_out_">Bail out!</a></li>
		<li><a href="#diagnostics">Diagnostics</a></li>
		<li><a href="#anything_else">Anything else</a></li>
	</ul>

	<li><a href="#examples">EXAMPLES</a></li>
	<ul>

		<li><a href="#common_with_explanation">Common with explanation</a></li>
		<li><a href="#unknown_amount_and_failures">Unknown amount and failures</a></li>
		<li><a href="#giving_up">Giving up</a></li>
		<li><a href="#skipping_a_few">Skipping a few</a></li>
		<li><a href="#skipping_everything">Skipping everything</a></li>
		<li><a href="#got_spare_tuits">Got spare tuits?</a></li>
		<li><a href="#creative_liberties">Creative liberties</a></li>
	</ul>

	<li><a href="#authors">AUTHORS</a></li>
	<li><a href="#acknowledgements">ACKNOWLEDGEMENTS</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::TAP - Documentation for the TAP format</p>
<p>
</p>
<hr />
<h1><a name="synopsis">SYNOPSIS</a></h1>
<p>TAP, the Test Anything Protocol, is Perl's simple text-based interface
between testing modules such as Test::More and the test harness
Test::Harness.</p>
<p>
</p>
<hr />
<h1><a name="todo">TODO</a></h1>
<p>Exit code of the process.</p>
<p>
</p>
<hr />
<h1><a name="the_tap_format">THE TAP FORMAT</a></h1>
<p>TAP's general format is:</p>
<pre>
    1..N
    ok 1 Description # Directive
    # Diagnostic
    ....
    ok 47 Description
    ok 48 Description
    more tests....</pre>
<p>For example, a test file's output might look like:</p>
<pre>
    1..4
    ok 1 - Input file opened
    not ok 2 - First line of the input valid
    ok 3 - Read the rest of the file
    not ok 4 - Summarized correctly # TODO Not written yet</pre>
<p>
</p>
<hr />
<h1><a name="harness_behavior">HARNESS BEHAVIOR</a></h1>
<p>In this document, the &quot;harness&quot; is any program analyzing TAP output.
Typically this will be Perl's <em>prove</em> program, or the underlying
<code>Test::Harness::runtests</code> subroutine.</p>
<p>A harness must only read TAP output from standard output and not
from standard error.  Lines written to standard output matching
<code>/^(not )?ok\b/</code> must be interpreted as test lines.  All other
lines must not be considered test output.</p>
<p>
</p>
<hr />
<h1><a name="tests_lines_and_the_plan">TESTS LINES AND THE PLAN</a></h1>
<p>
</p>
<h2><a name="the_plan">The plan</a></h2>
<p>The plan tells how many tests will be run, or how many tests have
run.  It's a check that the test file hasn't stopped prematurely.
It must appear once, whether at the beginning or end of the output.</p>
<p>The plan is usually the first line of TAP output and it specifies how
many test points are to follow. For example,</p>
<pre>
    1..10</pre>
<p>means you plan on running 10 tests. This is a safeguard in case your test
file dies silently in the middle of its run.  The plan is optional but if
there is a plan before the test points it must be the first non-diagnostic
line output by the test file.</p>
<p>In certain instances a test file may not know how many test points
it will ultimately be running. In this case the plan can be the last
non-diagnostic line in the output.</p>
<p>The plan cannot appear in the middle of the output, nor can it appear more
than once.</p>
<p>
</p>
<h2><a name="the_test_line">The test line</a></h2>
<p>The core of TAP is the test line.  A test file prints one test line test
point executed. There must be at least one test line in TAP output. Each
test line comprises the following elements:</p>
<ul>
<li><strong><a name="item_ok_or_not_ok"><a href="#item_ok"><code>ok</code></a> or <code>not ok</code></a></strong>

<p>This tells whether the test point passed or failed. It must be
at the beginning of the line. <code>/^not ok/</code> indicates a failed test
point. <code>/^ok/</code> is a successful test point. This is the only mandatory
part of the line.</p>
<p>Note that unlike the Directives below, <a href="#item_ok"><code>ok</code></a> and <code>not ok</code> are
case-sensitive.</p>
</li>
<li><strong><a name="item_test_number">Test number</a></strong>

<p>TAP expects the <a href="#item_ok"><code>ok</code></a> or <code>not ok</code> to be followed by a test point
number. If there is no number the harness must maintain
its own counter until the script supplies test numbers again. So
the following test output</p>
<pre>
    1..6
    not ok
    ok
    not ok
    ok
    ok</pre>
<p>has five tests.  The sixth is missing.  Test::Harness will generate</p>
<pre>
    FAILED tests 1, 3, 6
    Failed 3/6 tests, 50.00% okay</pre>
</li>
<li><strong><a name="item_description">Description</a></strong>

<p>Any text after the test number but before a <code>#</code> is the description of
the test point.</p>
<pre>
    ok 42 this is the description of the test</pre>
<p>Descriptions should not begin with a digit so that they are not confused
with the test point number.</p>
<p>The harness may do whatever it wants with the description.</p>
</li>
<li><strong><a name="item_directive">Directive</a></strong>

<p>The test point may include a directive, following a hash on the
test line.  There are currently two directives allowed: <code>TODO</code> and
<code>SKIP</code>.  These are discussed below.</p>
</li>
</ul>
<p>To summarize:</p>
<ul>
<li><strong><a name="item_ok">ok/not ok (required)</a></strong>

<li><strong><a name="item_number">Test number (recommended)</a></strong>

<li><strong>Description (recommended)</strong>

<li><strong>Directive (only when necessary)</strong>

</ul>
<p>
</p>
<hr />
<h1><a name="directives">DIRECTIVES</a></h1>
<p>Directives are special notes that follow a <code>#</code> on the test line.
Only two are currently defined: <code>TODO</code> and <code>SKIP</code>.  Note that
these two keywords are not case-sensitive.</p>
<p>
</p>
<h2><a name="todo_tests">TODO tests</a></h2>
<p>If the directive starts with <code># TODO</code>, the test is counted as a
todo test, and the text after <code>TODO</code> is the explanation.</p>
<pre>