lib/Test/Harness/TAP.pod

   1 =head1 NAME
   2
   3 Test::Harness::TAP - Documentation for the TAP format
   4
   5 =head1 SYNOPSIS
   6
   7 Perl's interface between testing modules like Test::More and the
   8 test harness Test::Harness is a simple text-based format called
   9 TAP, the Test Anything Protocol.  This is its story.
  10
  11 =head1 TERMINOLOGY
  12
  13 The "interpreter" is the program that reads and analyzes some TAP
  14 output.  In Perl, this is handled by the C<Test::Harness> module,
  15 with the C<runtests()> function.
  16
  17 =head1 THE TAP FORMAT
  18
  19 Perl test scripts print to standard output C<"ok N"> for each single
  20 test, where C<N> is an increasing sequence of integers. The first
  21 line output by a standard test script is C<"1..M"> with C<M> being
  22 the number of tests that should be run within the test script.
  23
  24 After all tests have been performed, runtests() prints some performance
  25 statistics that are computed by the Benchmark module.
  26
  27 =head2 The test script output
  28
  29 The following explains how Test::Harness interprets the output of your
  30 test program.
  31
  32 =over 4
  33
  34 =item B<"1..M">
  35
  36 This header tells how many tests there will be.  For example, C<1..10>
  37 means you plan on running 10 tests.  This is a safeguard in case
  38 your test dies quietly in the middle of its run.
  39
  40 It should be the first non-comment line output by your test program.
  41
  42 In certain instances, you may not know how many tests you will
  43 ultimately be running.  In this case, it is permitted for the C<1..M>
  44 header to appear as the B<last> line output by your test (again,
  45 it can be followed by further comments).
  46
  47 Under no circumstances should C<1..M> appear in the middle of your
  48 output or more than once.
  49
  50 =item B<'ok', 'not ok'.  Ok?>
  51
  52 Any output from the testscript to standard error is ignored and
  53 bypassed, thus will be seen by the user. Lines written to standard
  54 output containing C</^(not\s+)?ok\b/> are interpreted as feedback for
  55 the TAP interpreter.  All other lines are discarded.
  56
  57 C</^not ok/> indicates a failed test.  C</^ok/> is a successful test.
  58
  59 =item B<test numbers>
  60
  61 TAP normally expects the "ok" or "not ok" to be followed by a test
  62 number.  It is tolerated if the test numbers after "ok" are omitted.
  63 In this case, the interpreter must temporarily maintain its own
  64 counter until the script supplies test numbers again. So the following
  65 test script
  66
  67     print <<END;
  68     1..6
  69     not ok
  70     ok
  71     not ok
  72     ok
  73     ok
  74     END
  75
  76 will generate
  77
  78     FAILED tests 1, 3, 6
  79     Failed 3/6 tests, 50.00% okay
  80
  81 =item B<test labels>
  82
  83 Anything after the test number, but before the "#", is considered
  84 to be the label for the test.
  85
  86   ok 42 this is the label of the test
  87
  88 Currently, Test::Harness does nothing with this information.
  89
  90 =item B<Skipping tests>
  91
  92 If the standard output line contains the substring C< # Skip> (with
  93 variations in spacing and case) after C<ok> or C<ok NUMBER>, it is
  94 counted as a skipped test.  If the whole testscript succeeds, the
  95 count of skipped tests is included in the generated output.
  96 C<Test::Harness> reports the text after C< # Skip\S*\s+> as a reason
  97 for skipping.
  98
  99   ok 23 # skip Insufficient flogiston pressure.
 100
 101 Similarly, one can include a similar explanation in a C<1..0> line
 102 emitted if the test script is skipped completely:
 103
 104   1..0 # Skipped: no leverage found
 105
 106 =item B<Todo tests>
 107
 108 If the standard output line contains the substring C< # TODO > after
 109 C<not ok> or C<not ok NUMBER>, it is counted as a todo test.  The text
 110 afterwards is the thing that has to be done before this test will
 111 succeed.
 112
 113   not ok 13 # TODO harness the power of the atom
 114
 115 Note that the TODO must have a space after it.
 116
 117 These tests represent a feature to be implemented or a bug to be fixed
 118 and act as something of an executable "thing to do" list.  They are
 119 B<not> expected to succeed.  Should a todo test begin succeeding,
 120 Test::Harness will report it as a bonus.  This indicates that whatever
 121 you were supposed to do has been done and you should promote this to a
 122 normal test.
 123
 124 =item B<Bail out!>
 125
 126 As an emergency measure, a test script can decide that further tests
 127 are useless (e.g. missing dependencies) and testing should stop
 128 immediately. In that case the test script prints the magic words
 129
 130   Bail out!
 131
 132 to standard output. Any message after these words must be displayed
 133 by the interpreter as the reason why testing must be stopped.
 134
 135 =item B<Comments>
 136
 137 Additional comments may be put into the testing output on their own
 138 lines.  Comment lines should begin with a '#', Test::Harness will
 139 ignore them.
 140
 141   ok 1
 142   # Life is good, the sun is shining, RAM is cheap.
 143   not ok 2
 144   # got 'Bush' expected 'Gore'
 145
 146 =item B<Anything else>
 147
 148 Any other output Test::Harness sees it will silently ignore B<BUT WE
 149 PLAN TO CHANGE THIS!> If you wish to place additional output in your
 150 test script, please use a comment.
 151
 152 =back
 153
 154 =head1 DESCRIPTION
 155
 156 =head1 RATIONALE
 157
 158 =head1 ACKNOWLEDGEMENTS
 159
 160 =head1 AUTHORS
 161
 162 Andy Lester, based on the original Test::Harness documentation by Michael Schwern.
 163
 164 =head1 COPYRIGHT
 165
 166 Copyright 2003-2004 by
 167 Michael G Schwern C<< <schwern@pobox.com> >>,
 168 Andy Lester C<< <andy@petdance.com> >>.
 169
 170 This program is free software; you can redistribute it and/or
 171 modify it under the same terms as Perl itself.
 172
 173 See L<http://www.perl.com/perl/misc/Artistic.html>.
 174
 175 =cut