lib/Test/Harness/TAP.pod

   1 =head1 NAME
   2
   3 Test::Harness::TAP - Documentation for the TAP format
   4
   5 =head1 SYNOPSIS
   6
   7 TAP, the Test Anything Protocol, is Perl's simple text-based interface
   8 between testing modules such as Test::More and the test harness
   9 Test::Harness.
  10
  11 =head1 TODO
  12
  13 Exit code of the process.
  14
  15 =head1 THE TAP FORMAT
  16
  17 TAP's general format is:
  18
  19     1..N
  20     ok 1 Description # Directive
  21     # Diagnostic
  22     ....
  23     ok 47 Description
  24     ok 48 Description
  25     more tests....
  26
  27 For example, a test file's output might look like:
  28
  29     1..4
  30     ok 1 - Input file opened
  31     not ok 2 - First line of the input valid
  32     ok 3 - Read the rest of the file
  33     not ok 4 - Summarized correctly # TODO Not written yet
  34
  35 =head1 HARNESS BEHAVIOR
  36
  37 In this document, the "harness" is any program analyzing TAP output.
  38 Typically this will be Perl's I<prove> program, or the underlying
  39 C<Test::Harness::runtests> subroutine.
  40
  41 A harness must only read TAP output from standard output and not
  42 from standard error.  Lines written to standard output matching
  43 C</^(not )?ok\b/> must be interpreted as test lines.  All other
  44 lines must not be considered test output.
  45
  46 =head1 TESTS LINES AND THE PLAN
  47
  48 =head2 The plan
  49
  50 The plan tells how many tests will be run, or how many tests have
  51 run.  It's a check that the test file hasn't stopped prematurely.
  52 It must appear once, whether at the beginning or end of the output.
  53
  54 The plan is usually the first line of TAP output and it specifies how
  55 many test points are to follow. For example,
  56
  57     1..10
  58
  59 means you plan on running 10 tests. This is a safeguard in case your test
  60 file dies silently in the middle of its run.  The plan is optional but if
  61 there is a plan before the test points it must be the first non-diagnostic
  62 line output by the test file.
  63
  64 In certain instances a test file may not know how many test points
  65 it will ultimately be running. In this case the plan can be the last
  66 non-diagnostic line in the output.
  67
  68 The plan cannot appear in the middle of the output, nor can it appear more
  69 than once.
  70
  71 =head2 The test line
  72
  73 The core of TAP is the test line.  A test file prints one test line test
  74 point executed. There must be at least one test line in TAP output. Each
  75 test line comprises the following elements:
  76
  77 =over 4
  78
  79 =item * C<ok> or C<not ok>
  80
  81 This tells whether the test point passed or failed. It must be
  82 at the beginning of the line. C</^not ok/> indicates a failed test
  83 point. C</^ok/> is a successful test point. This is the only mandatory
  84 part of the line.
  85
  86 Note that unlike the Directives below, C<ok> and C<not ok> are
  87 case-sensitive.
  88
  89 =item * Test number
  90
  91 TAP expects the C<ok> or C<not ok> to be followed by a test point
  92 number. If there is no number the harness must maintain
  93 its own counter until the script supplies test numbers again. So
  94 the following test output
  95
  96     1..6
  97     not ok
  98     ok
  99     not ok
 100     ok
 101     ok
 102
 103 has five tests.  The sixth is missing.  Test::Harness will generate
 104
 105     FAILED tests 1, 3, 6
 106     Failed 3/6 tests, 50.00% okay
 107
 108 =item * Description
 109
 110 Any text after the test number but before a C<#> is the description of
 111 the test point.
 112
 113     ok 42 this is the description of the test
 114
 115 Descriptions should not begin with a digit so that they are not confused
 116 with the test point number.
 117
 118 The harness may do whatever it wants with the description.
 119
 120 =item * Directive
 121
 122 The test point may include a directive, following a hash on the
 123 test line.  There are currently two directives allowed: C<TODO> and
 124 C<SKIP>.  These are discussed below.
 125
 126 =back
 127
 128 To summarize:
 129
 130 =over 4
 131
 132 =item * ok/not ok (required)
 133
 134 =item * Test number (recommended)
 135
 136 =item * Description (recommended)
 137
 138 =item * Directive (only when necessary)
 139
 140 =back
 141
 142 =head1 DIRECTIVES
 143
 144 Directives are special notes that follow a C<#> on the test line.
 145 Only two are currently defined: C<TODO> and C<SKIP>.  Note that
 146 these two keywords are not case-sensitive.
 147
 148 =head2 TODO tests
 149
 150 If the directive starts with C<# TODO>, the test is counted as a
 151 todo test, and the text after C<TODO> is the the explanation.
 152
 153     not ok 13 # TODO bend space and time
 154
 155 Note that if the TODO has an explanation it must be separated from
 156 C<TODO> by a space.
 157
 158 These tests represent a feature to be implemented or a bug to be fixed
 159 and act as something of an executable "things to do" list.  They are
 160 B<not> expected to succeed.  Should a todo test point begin succeeding,
 161 the harness should report it as a bonus.  This indicates that whatever
 162 you were supposed to do has been done and you should promote this to a
 163 normal test point.
 164
 165 =head2 Skipping tests
 166
 167 If the directive starts with C<# SKIP>, the test is counted as having
 168 been skipped.  If the whole test file succeeds, the count of skipped
 169 tests is included in the generated output.  The harness should report
 170 the text after C< # SKIP\S*\s+> as a reason for skipping.
 171
 172     ok 23 # skip Insufficient flogiston pressure.
 173
 174 Similarly, one can include an explanation in a plan line,
 175 emitted if the test file is skipped completely:
 176
 177     1..0 # Skipped: WWW::Mechanize not installed
 178
 179 =head1 OTHER LINES
 180
 181 =head2 Bail out!
 182
 183 As an emergency measure a test script can decide that further tests
 184 are useless (e.g. missing dependencies) and testing should stop
 185 immediately. In that case the test script prints the magic words
 186
 187     Bail out!
 188
 189 to standard output. Any message after these words must be displayed
 190 by the interpreter as the reason why testing must be stopped, as
 191 in
 192
 193     Bail out! MySQL is not running.
 194
 195 =head2 Diagnostics
 196
 197 Additional information may be put into the testing output on separate
 198 lines.  Diagnostic lines should begin with a C<#>, which the harness must
 199 ignore, at least as far as analyzing the test results.  The harness is
 200 free, however, to display the diagnostics.  Typically diagnostics are
 201 used to provide information about the environment in which test file is
 202 running, or to delineate a group of tests.
 203     ...
 204     ok 18 - Closed database connection
 205     # End of database section.
 206     # This starts the network part of the test.
 207     # Daemon started on port 2112
 208     ok 19 - Opened socket
 209     ...
 210     ok 47 - Closed socket
 211     # End of network tests
 212
 213 =head2 Anything else
 214
 215 Any output line that is not a plan, a test line or a diagnostic is
 216 incorrect.  How a harness handles the incorrect line is undefined.
 217 Test::Harness silently ignores incorrect lines, but will become more
 218 stringent in the future.
 219
 220 =head1 EXAMPLES
 221
 222 All names, places, and events depicted in any example are wholly
 223 fictitious and bear no resemblance to, connection with, or relation to any
 224 real entity. Any such similarity is purely coincidental, unintentional,
 225 and unintended.
 226
 227 =head2 Common with explanation
 228
 229 The following TAP listing declares that six tests follow as well as
 230 provides handy feedback as to what the test is about to do. All six
 231 tests pass.
 232
 233     1..6
 234     #
 235     # Create a new Board and Tile, then place
 236     # the Tile onto the board.
 237     #
 238     ok 1 - The object isa Board
 239     ok 2 - Board size is zero
 240     ok 3 - The object isa Tile
 241     ok 4 - Get possible places to put the Tile
 242     ok 5 - Placing the tile produces no error
 243     ok 6 - Board size is 1
 244
 245 =head2 Unknown amount and failures
 246
 247 This hypothetical test program ensures that a handful of servers are
 248 online and network-accessible. Because it retrieves the hypothetical
 249 servers from a database, it doesn't know exactly how many servers it
 250 will need to ping. Thus, the test count is declared at the bottom after
 251 all the test points have run. Also, two of the tests fail.
 252
 253     ok 1 - retrieving servers from the database
 254     # need to ping 6 servers
 255     ok 2 - pinged diamond
 256     ok 3 - pinged ruby
 257     not ok 4 - pinged saphire
 258     ok 5 - pinged onyx
 259     not ok 6 - pinged quartz
 260     ok 7 - pinged gold
 261     1..7
 262
 263 =head2 Giving up
 264
 265 This listing reports that a pile of tests are going to be run. However,
 266 the first test fails, reportedly because a connection to the database
 267 could not be established. The program decided that continuing was
 268 pointless and exited.
 269
 270     1..573
 271     not ok 1 - database handle
 272     Bail out! Couldn't connect to database.
 273
 274 =head2 Skipping a few
 275
 276 The following listing plans on running 5 tests. However, our program
 277 decided to not run tests 2 thru 5 at all. To properly report this,
 278 the tests are marked as being skipped.
 279
 280     1..5
 281     ok 1 - approved operating system
 282     # $^0 is solaris
 283     ok 2 - # SKIP no /sys directory
 284     ok 3 - # SKIP no /sys directory
 285     ok 4 - # SKIP no /sys directory
 286     ok 5 - # SKIP no /sys directory
 287
 288 =head2 Skipping everything
 289
 290 This listing shows that the entire listing is a skip. No tests were run.
 291
 292     1..0 # skip because English-to-French translator isn't installed
 293
 294 =head2 Got spare tuits?
 295
 296 The following example reports that four tests are run and the last two
 297 tests failed. However, becauses the failing tests are marked as things
 298 to do later, they are considered successes. Thus, a harness should report
 299 this entire listing as a success.
 300
 301     1..4
 302     ok 1 - Creating test program
 303     ok 2 - Test program runs, no error
 304     not ok 3 - infinite loop # TODO halting problem unsolved
 305     not ok 4 - infinite loop 2 # TODO halting problem unsolved
 306
 307 =head2 Creative liberties
 308
 309 This listing shows an alternate output where the test numbers aren't
 310 provided. The test also reports the state of a ficticious board game in
 311 diagnostic form. Finally, the test count is reported at the end.
 312
 313     ok - created Board
 314     ok
 315     ok
 316     ok
 317     ok
 318     ok
 319     ok
 320     ok
 321     # +------+------+------+------+
 322     # |      |16G   |      |05C   |
 323     # |      |G N C |      |C C G |
 324     # |      |  G   |      |  C  +|
 325     # +------+------+------+------+
 326     # |10C   |01G   |      |03C   |
 327     # |R N G |G A G |      |C C C |
 328     # |  R   |  G   |      |  C  +|
 329     # +------+------+------+------+
 330     # |      |01G   |17C   |00C   |
 331     # |      |G A G |G N R |R N R |
 332     # |      |  G   |  R   |  G   |
 333     # +------+------+------+------+
 334     ok - board has 7 tiles + starter tile
 335     1..9
 336
 337 =head1 AUTHORS
 338
 339 Andy Lester, based on the original Test::Harness documentation by Michael Schwern.
 340
 341 =head1 ACKNOWLEDGEMENTS
 342
 343 Thanks to
 344 Pete Krawczyk,
 345 Paul Johnson,
 346 Ian Langworth
 347 and Nik Clayton
 348 for help and contributions on this document.
 349
 350 The basis for the TAP format was created by Larry Wall in the
 351 original test script for Perl 1.  Tim Bunce and Andreas Koenig
 352 developed it further with their modifications to Test::Harness.
 353
 354 =head1 COPYRIGHT
 355
 356 Copyright 2003-2005 by
 357 Michael G Schwern C<< <schwern@pobox.com> >>,
 358 Andy Lester C<< <andy@petdance.com> >>.
 359
 360 This program is free software; you can redistribute it and/or
 361 modify it under the same terms as Perl itself.
 362
 363 See L<http://www.perl.com/perl/misc/Artistic.html>.
 364
 365 =cut