1TAP::Parser(3)        User Contributed Perl Documentation       TAP::Parser(3)
2
3
4

NAME

6       TAP::Parser - Parse TAP output
7

VERSION

9       Version 3.43
10

SYNOPSIS

12           use TAP::Parser;
13
14           my $parser = TAP::Parser->new( { source => $source } );
15
16           while ( my $result = $parser->next ) {
17               print $result->as_string;
18           }
19

DESCRIPTION

21       "TAP::Parser" is designed to produce a proper parse of TAP output. For
22       an example of how to run tests through this module, see the simple
23       harnesses "examples/".
24
25       There's a wiki dedicated to the Test Anything Protocol:
26
27       <http://testanything.org>
28
29       It includes the TAP::Parser Cookbook:
30
31       <http://testanything.org/testing-with-tap/perl/tap::parser-cookbook.html>
32

METHODS

34   Class Methods
35       "new"
36
37        my $parser = TAP::Parser->new(\%args);
38
39       Returns a new "TAP::Parser" object.
40
41       The arguments should be a hashref with one of the following keys:
42
43       •   "source"
44
45           CHANGED in 3.18
46
47           This is the preferred method of passing input to the constructor.
48
49           The "source" is used to create a TAP::Parser::Source that is passed
50           to the "iterator_factory_class" which in turn figures out how to
51           handle the source and creates a <TAP::Parser::Iterator> for it.
52           The iterator is used by the parser to read in the TAP stream.
53
54           To configure the IteratorFactory use the "sources" parameter below.
55
56           Note that "source", "tap" and "exec" are mutually exclusive.
57
58       •   "tap"
59
60           CHANGED in 3.18
61
62           The value should be the complete TAP output.
63
64           The tap is used to create a TAP::Parser::Source that is passed to
65           the "iterator_factory_class" which in turn figures out how to
66           handle the source and creates a <TAP::Parser::Iterator> for it.
67           The iterator is used by the parser to read in the TAP stream.
68
69           To configure the IteratorFactory use the "sources" parameter below.
70
71           Note that "source", "tap" and "exec" are mutually exclusive.
72
73       •   "exec"
74
75           Must be passed an array reference.
76
77           The exec array ref is used to create a TAP::Parser::Source that is
78           passed to the "iterator_factory_class" which in turn figures out
79           how to handle the source and creates a <TAP::Parser::Iterator> for
80           it.  The iterator is used by the parser to read in the TAP stream.
81
82           By default the TAP::Parser::SourceHandler::Executable class will
83           create a TAP::Parser::Iterator::Process object to handle the
84           source.  This passes the array reference strings as command
85           arguments to IPC::Open3::open3:
86
87            exec => [ '/usr/bin/ruby', 't/my_test.rb' ]
88
89           If any "test_args" are given they will be appended to the end of
90           the command argument list.
91
92           To configure the IteratorFactory use the "sources" parameter below.
93
94           Note that "source", "tap" and "exec" are mutually exclusive.
95
96       The following keys are optional.
97
98       •   "sources"
99
100           NEW to 3.18.
101
102           If set, "sources" must be a hashref containing the names of the
103           TAP::Parser::SourceHandlers to load and/or configure.  The values
104           are a hash of configuration that will be accessible to the source
105           handlers via "config_for" in TAP::Parser::Source.
106
107           For example:
108
109             sources => {
110               Perl => { exec => '/path/to/custom/perl' },
111               File => { extensions => [ '.tap', '.txt' ] },
112               MyCustom => { some => 'config' },
113             }
114
115           This will cause "TAP::Parser" to pass custom configuration to two
116           of the built- in source handlers -
117           TAP::Parser::SourceHandler::Perl, TAP::Parser::SourceHandler::File
118           - and attempt to load the "MyCustom" class.  See "load_handlers" in
119           TAP::Parser::IteratorFactory for more detail.
120
121           The "sources" parameter affects how "source", "tap" and "exec"
122           parameters are handled.
123
124           See TAP::Parser::IteratorFactory, TAP::Parser::SourceHandler and
125           subclasses for more details.
126
127       •   "callback"
128
129           If present, each callback corresponding to a given result type will
130           be called with the result as the argument if the "run" method is
131           used:
132
133            my %callbacks = (
134                test    => \&test_callback,
135                plan    => \&plan_callback,
136                comment => \&comment_callback,
137                bailout => \&bailout_callback,
138                unknown => \&unknown_callback,
139            );
140
141            my $aggregator = TAP::Parser::Aggregator->new;
142            for my $file ( @test_files ) {
143                my $parser = TAP::Parser->new(
144                    {
145                        source    => $file,
146                        callbacks => \%callbacks,
147                    }
148                );
149                $parser->run;
150                $aggregator->add( $file, $parser );
151            }
152
153       •   "switches"
154
155           If using a Perl file as a source, optional switches may be passed
156           which will be used when invoking the perl executable.
157
158            my $parser = TAP::Parser->new( {
159                source   => $test_file,
160                switches => [ '-Ilib' ],
161            } );
162
163       •   "test_args"
164
165           Used in conjunction with the "source" and "exec" option to supply a
166           reference to an @ARGV style array of arguments to pass to the test
167           program.
168
169       •   "spool"
170
171           If passed a filehandle will write a copy of all parsed TAP to that
172           handle.
173
174       •   "merge"
175
176           If false, STDERR is not captured (though it is 'relayed' to keep it
177           somewhat synchronized with STDOUT.)
178
179           If true, STDERR and STDOUT are the same filehandle.  This may cause
180           breakage if STDERR contains anything resembling TAP format, but
181           does allow exact synchronization.
182
183           Subtleties of this behavior may be platform-dependent and may
184           change in the future.
185
186       •   "grammar_class"
187
188           This option was introduced to let you easily customize which
189           grammar class the parser should use.  It defaults to
190           TAP::Parser::Grammar.
191
192           See also "make_grammar".
193
194       •   "result_factory_class"
195
196           This option was introduced to let you easily customize which result
197           factory class the parser should use.  It defaults to
198           TAP::Parser::ResultFactory.
199
200           See also "make_result".
201
202       •   "iterator_factory_class"
203
204           CHANGED in 3.18
205
206           This option was introduced to let you easily customize which
207           iterator factory class the parser should use.  It defaults to
208           TAP::Parser::IteratorFactory.
209
210   Instance Methods
211       "next"
212
213         my $parser = TAP::Parser->new( { source => $file } );
214         while ( my $result = $parser->next ) {
215             print $result->as_string, "\n";
216         }
217
218       This method returns the results of the parsing, one result at a time.
219       Note that it is destructive.  You can't rewind and examine previous
220       results.
221
222       If callbacks are used, they will be issued before this call returns.
223
224       Each result returned is a subclass of TAP::Parser::Result.  See that
225       module and related classes for more information on how to use them.
226
227       "run"
228
229         $parser->run;
230
231       This method merely runs the parser and parses all of the TAP.
232
233       "make_grammar"
234
235       Make a new TAP::Parser::Grammar object and return it.  Passes through
236       any arguments given.
237
238       The "grammar_class" can be customized, as described in "new".
239
240       "make_result"
241
242       Make a new TAP::Parser::Result object using the parser's
243       TAP::Parser::ResultFactory, and return it.  Passes through any
244       arguments given.
245
246       The "result_factory_class" can be customized, as described in "new".
247
248       "make_iterator_factory"
249
250       NEW to 3.18.
251
252       Make a new TAP::Parser::IteratorFactory object and return it.  Passes
253       through any arguments given.
254
255       "iterator_factory_class" can be customized, as described in "new".
256

INDIVIDUAL RESULTS

258       If you've read this far in the docs, you've seen this:
259
260           while ( my $result = $parser->next ) {
261               print $result->as_string;
262           }
263
264       Each result returned is a TAP::Parser::Result subclass, referred to as
265       result types.
266
267   Result types
268       Basically, you fetch individual results from the TAP.  The six types,
269       with examples of each, are as follows:
270
271       •   Version
272
273            TAP version 12
274
275       •   Plan
276
277            1..42
278
279       •   Pragma
280
281            pragma +strict
282
283       •   Test
284
285            ok 3 - We should start with some foobar!
286
287       •   Comment
288
289            # Hope we don't use up the foobar.
290
291       •   Bailout
292
293            Bail out!  We ran out of foobar!
294
295       •   Unknown
296
297            ... yo, this ain't TAP! ...
298
299       Each result fetched is a result object of a different type.  There are
300       common methods to each result object and different types may have
301       methods unique to their type.  Sometimes a type method may be
302       overridden in a subclass, but its use is guaranteed to be identical.
303
304   Common type methods
305       "type"
306
307       Returns the type of result, such as "comment" or "test".
308
309       "as_string"
310
311       Prints a string representation of the token.  This might not be the
312       exact output, however.  Tests will have test numbers added if not
313       present, TODO and SKIP directives will be capitalized and, in general,
314       things will be cleaned up.  If you need the original text for the
315       token, see the "raw" method.
316
317       "raw"
318
319       Returns the original line of text which was parsed.
320
321       "is_plan"
322
323       Indicates whether or not this is the test plan line.
324
325       "is_test"
326
327       Indicates whether or not this is a test line.
328
329       "is_comment"
330
331       Indicates whether or not this is a comment. Comments will generally
332       only appear in the TAP stream if STDERR is merged to STDOUT. See the
333       "merge" option.
334
335       "is_bailout"
336
337       Indicates whether or not this is bailout line.
338
339       "is_yaml"
340
341       Indicates whether or not the current item is a YAML block.
342
343       "is_unknown"
344
345       Indicates whether or not the current line could be parsed.
346
347       "is_ok"
348
349         if ( $result->is_ok ) { ... }
350
351       Reports whether or not a given result has passed.  Anything which is
352       not a test result returns true.  This is merely provided as a
353       convenient shortcut which allows you to do this:
354
355        my $parser = TAP::Parser->new( { source => $source } );
356        while ( my $result = $parser->next ) {
357            # only print failing results
358            print $result->as_string unless $result->is_ok;
359        }
360
361   "plan" methods
362        if ( $result->is_plan ) { ... }
363
364       If the above evaluates as true, the following methods will be available
365       on the $result object.
366
367       "plan"
368
369         if ( $result->is_plan ) {
370            print $result->plan;
371         }
372
373       This is merely a synonym for "as_string".
374
375       "directive"
376
377        my $directive = $result->directive;
378
379       If a SKIP directive is included with the plan, this method will return
380       it.
381
382        1..0 # SKIP: why bother?
383
384       "explanation"
385
386        my $explanation = $result->explanation;
387
388       If a SKIP directive was included with the plan, this method will return
389       the explanation, if any.
390
391   "pragma" methods
392        if ( $result->is_pragma ) { ... }
393
394       If the above evaluates as true, the following methods will be available
395       on the $result object.
396
397       "pragmas"
398
399       Returns a list of pragmas each of which is a + or - followed by the
400       pragma name.
401
402   "comment" methods
403        if ( $result->is_comment ) { ... }
404
405       If the above evaluates as true, the following methods will be available
406       on the $result object.
407
408       "comment"
409
410         if ( $result->is_comment ) {
411             my $comment = $result->comment;
412             print "I have something to say:  $comment";
413         }
414
415   "bailout" methods
416        if ( $result->is_bailout ) { ... }
417
418       If the above evaluates as true, the following methods will be available
419       on the $result object.
420
421       "explanation"
422
423         if ( $result->is_bailout ) {
424             my $explanation = $result->explanation;
425             print "We bailed out because ($explanation)";
426         }
427
428       If, and only if, a token is a bailout token, you can get an
429       "explanation" via this method.  The explanation is the text after the
430       mystical "Bail out!" words which appear in the tap output.
431
432   "unknown" methods
433        if ( $result->is_unknown ) { ... }
434
435       There are no unique methods for unknown results.
436
437   "test" methods
438        if ( $result->is_test ) { ... }
439
440       If the above evaluates as true, the following methods will be available
441       on the $result object.
442
443       "ok"
444
445         my $ok = $result->ok;
446
447       Returns the literal text of the "ok" or "not ok" status.
448
449       "number"
450
451         my $test_number = $result->number;
452
453       Returns the number of the test, even if the original TAP output did not
454       supply that number.
455
456       "description"
457
458         my $description = $result->description;
459
460       Returns the description of the test, if any.  This is the portion after
461       the test number but before the directive.
462
463       "directive"
464
465         my $directive = $result->directive;
466
467       Returns either "TODO" or "SKIP" if either directive was present for a
468       test line.
469
470       "explanation"
471
472         my $explanation = $result->explanation;
473
474       If a test had either a "TODO" or "SKIP" directive, this method will
475       return the accompanying explanation, if present.
476
477         not ok 17 - 'Pigs can fly' # TODO not enough acid
478
479       For the above line, the explanation is not enough acid.
480
481       "is_ok"
482
483         if ( $result->is_ok ) { ... }
484
485       Returns a boolean value indicating whether or not the test passed.
486       Remember that for TODO tests, the test always passes.
487
488       Note:  this was formerly "passed".  The latter method is deprecated and
489       will issue a warning.
490
491       "is_actual_ok"
492
493         if ( $result->is_actual_ok ) { ... }
494
495       Returns a boolean value indicating whether or not the test passed,
496       regardless of its TODO status.
497
498       Note:  this was formerly "actual_passed".  The latter method is
499       deprecated and will issue a warning.
500
501       "is_unplanned"
502
503         if ( $test->is_unplanned ) { ... }
504
505       If a test number is greater than the number of planned tests, this
506       method will return true.  Unplanned tests will always return false for
507       "is_ok", regardless of whether or not the test "has_todo" (see
508       TAP::Parser::Result::Test for more information about this).
509
510       "has_skip"
511
512         if ( $result->has_skip ) { ... }
513
514       Returns a boolean value indicating whether or not this test had a SKIP
515       directive.
516
517       "has_todo"
518
519         if ( $result->has_todo ) { ... }
520
521       Returns a boolean value indicating whether or not this test had a TODO
522       directive.
523
524       Note that TODO tests always pass.  If you need to know whether or not
525       they really passed, check the "is_actual_ok" method.
526
527       "in_todo"
528
529         if ( $parser->in_todo ) { ... }
530
531       True while the most recent result was a TODO. Becomes true before the
532       TODO result is returned and stays true until just before the next non-
533       TODO test is returned.
534

TOTAL RESULTS

536       After parsing the TAP, there are many methods available to let you dig
537       through the results and determine what is meaningful to you.
538
539   Individual Results
540       These results refer to individual tests which are run.
541
542       "passed"
543
544        my @passed = $parser->passed; # the test numbers which passed
545        my $passed = $parser->passed; # the number of tests which passed
546
547       This method lets you know which (or how many) tests passed.  If a test
548       failed but had a TODO directive, it will be counted as a passed test.
549
550       "failed"
551
552        my @failed = $parser->failed; # the test numbers which failed
553        my $failed = $parser->failed; # the number of tests which failed
554
555       This method lets you know which (or how many) tests failed.  If a test
556       passed but had a TODO directive, it will NOT be counted as a failed
557       test.
558
559       "actual_passed"
560
561        # the test numbers which actually passed
562        my @actual_passed = $parser->actual_passed;
563
564        # the number of tests which actually passed
565        my $actual_passed = $parser->actual_passed;
566
567       This method lets you know which (or how many) tests actually passed,
568       regardless of whether or not a TODO directive was found.
569
570       "actual_ok"
571
572       This method is a synonym for "actual_passed".
573
574       "actual_failed"
575
576        # the test numbers which actually failed
577        my @actual_failed = $parser->actual_failed;
578
579        # the number of tests which actually failed
580        my $actual_failed = $parser->actual_failed;
581
582       This method lets you know which (or how many) tests actually failed,
583       regardless of whether or not a TODO directive was found.
584
585       "todo"
586
587        my @todo = $parser->todo; # the test numbers with todo directives
588        my $todo = $parser->todo; # the number of tests with todo directives
589
590       This method lets you know which (or how many) tests had TODO
591       directives.
592
593       "todo_passed"
594
595        # the test numbers which unexpectedly succeeded
596        my @todo_passed = $parser->todo_passed;
597
598        # the number of tests which unexpectedly succeeded
599        my $todo_passed = $parser->todo_passed;
600
601       This method lets you know which (or how many) tests actually passed but
602       were declared as "TODO" tests.
603
604       "todo_failed"
605
606         # deprecated in favor of 'todo_passed'.  This method was horribly misnamed.
607
608       This was a badly misnamed method.  It indicates which TODO tests
609       unexpectedly succeeded.  Will now issue a warning and call
610       "todo_passed".
611
612       "skipped"
613
614        my @skipped = $parser->skipped; # the test numbers with SKIP directives
615        my $skipped = $parser->skipped; # the number of tests with SKIP directives
616
617       This method lets you know which (or how many) tests had SKIP
618       directives.
619
620   Pragmas
621       "pragma"
622
623       Get or set a pragma. To get the state of a pragma:
624
625         if ( $p->pragma('strict') ) {
626             # be strict
627         }
628
629       To set the state of a pragma:
630
631         $p->pragma('strict', 1); # enable strict mode
632
633       "pragmas"
634
635       Get a list of all the currently enabled pragmas:
636
637         my @pragmas_enabled = $p->pragmas;
638
639   Summary Results
640       These results are "meta" information about the total results of an
641       individual test program.
642
643       "plan"
644
645        my $plan = $parser->plan;
646
647       Returns the test plan, if found.
648
649       "good_plan"
650
651       Deprecated.  Use "is_good_plan" instead.
652
653       "is_good_plan"
654
655         if ( $parser->is_good_plan ) { ... }
656
657       Returns a boolean value indicating whether or not the number of tests
658       planned matches the number of tests run.
659
660       Note:  this was formerly "good_plan".  The latter method is deprecated
661       and will issue a warning.
662
663       And since we're on that subject ...
664
665       "tests_planned"
666
667         print $parser->tests_planned;
668
669       Returns the number of tests planned, according to the plan.  For
670       example, a plan of '1..17' will mean that 17 tests were planned.
671
672       "tests_run"
673
674         print $parser->tests_run;
675
676       Returns the number of tests which actually were run.  Hopefully this
677       will match the number of "$parser->tests_planned".
678
679       "skip_all"
680
681       Returns a true value (actually the reason for skipping) if all tests
682       were skipped.
683
684       "start_time"
685
686       Returns the wall-clock time when the Parser was created.
687
688       "end_time"
689
690       Returns the wall-clock time when the end of TAP input was seen.
691
692       "start_times"
693
694       Returns the CPU times (like "times" in perlfunc when the Parser was
695       created.
696
697       "end_times"
698
699       Returns the CPU times (like "times" in perlfunc when the end of TAP
700       input was seen.
701
702       "has_problems"
703
704         if ( $parser->has_problems ) {
705             ...
706         }
707
708       This is a 'catch-all' method which returns true if any tests have
709       currently failed, any TODO tests unexpectedly succeeded, or any parse
710       errors occurred.
711
712       "version"
713
714         $parser->version;
715
716       Once the parser is done, this will return the version number for the
717       parsed TAP. Version numbers were introduced with TAP version 13 so if
718       no version number is found version 12 is assumed.
719
720       "exit"
721
722         $parser->exit;
723
724       Once the parser is done, this will return the exit status.  If the
725       parser ran an executable, it returns the exit status of the executable.
726
727       "wait"
728
729         $parser->wait;
730
731       Once the parser is done, this will return the wait status.  If the
732       parser ran an executable, it returns the wait status of the executable.
733       Otherwise, this merely returns the "exit" status.
734
735   "ignore_exit"
736         $parser->ignore_exit(1);
737
738       Tell the parser to ignore the exit status from the test when
739       determining whether the test passed. Normally tests with non-zero exit
740       status are considered to have failed even if all individual tests
741       passed. In cases where it is not possible to control the exit value of
742       the test script use this option to ignore it.
743
744       "parse_errors"
745
746        my @errors = $parser->parse_errors; # the parser errors
747        my $errors = $parser->parse_errors; # the number of parser_errors
748
749       Fortunately, all TAP output is perfect.  In the event that it is not,
750       this method will return parser errors.  Note that a junk line which the
751       parser does not recognize is "not" an error.  This allows this parser
752       to handle future versions of TAP.  The following are all TAP errors
753       reported by the parser:
754
755       •   Misplaced plan
756
757           The plan (for example, '1..5'), must only come at the beginning or
758           end of the TAP output.
759
760       •   No plan
761
762           Gotta have a plan!
763
764       •   More than one plan
765
766            1..3
767            ok 1 - input file opened
768            not ok 2 - first line of the input valid # todo some data
769            ok 3 read the rest of the file
770            1..3
771
772           Right.  Very funny.  Don't do that.
773
774       •   Test numbers out of sequence
775
776            1..3
777            ok 1 - input file opened
778            not ok 2 - first line of the input valid # todo some data
779            ok 2 read the rest of the file
780
781           That last test line above should have the number '3' instead of
782           '2'.
783
784           Note that it's perfectly acceptable for some lines to have test
785           numbers and others to not have them.  However, when a test number
786           is found, it must be in sequence.  The following is also an error:
787
788            1..3
789            ok 1 - input file opened
790            not ok - first line of the input valid # todo some data
791            ok 2 read the rest of the file
792
793           But this is not:
794
795            1..3
796            ok  - input file opened
797            not ok - first line of the input valid # todo some data
798            ok 3 read the rest of the file
799
800       "get_select_handles"
801
802       Get an a list of file handles which can be passed to "select" to
803       determine the readiness of this parser.
804
805       "delete_spool"
806
807       Delete and return the spool.
808
809         my $fh = $parser->delete_spool;
810

CALLBACKS

812       As mentioned earlier, a "callback" key may be added to the
813       "TAP::Parser" constructor. If present, each callback corresponding to a
814       given result type will be called with the result as the argument if the
815       "run" method is used. The callback is expected to be a subroutine
816       reference (or anonymous subroutine) which is invoked with the parser
817       result as its argument.
818
819        my %callbacks = (
820            test    => \&test_callback,
821            plan    => \&plan_callback,
822            comment => \&comment_callback,
823            bailout => \&bailout_callback,
824            unknown => \&unknown_callback,
825        );
826
827        my $aggregator = TAP::Parser::Aggregator->new;
828        for my $file ( @test_files ) {
829            my $parser = TAP::Parser->new(
830                {
831                    source    => $file,
832                    callbacks => \%callbacks,
833                }
834            );
835            $parser->run;
836            $aggregator->add( $file, $parser );
837        }
838
839       Callbacks may also be added like this:
840
841        $parser->callback( test => \&test_callback );
842        $parser->callback( plan => \&plan_callback );
843
844       The following keys allowed for callbacks. These keys are case-
845       sensitive.
846
847       •   "test"
848
849           Invoked if "$result->is_test" returns true.
850
851       •   "version"
852
853           Invoked if "$result->is_version" returns true.
854
855       •   "plan"
856
857           Invoked if "$result->is_plan" returns true.
858
859       •   "comment"
860
861           Invoked if "$result->is_comment" returns true.
862
863       •   "bailout"
864
865           Invoked if "$result->is_unknown" returns true.
866
867       •   "yaml"
868
869           Invoked if "$result->is_yaml" returns true.
870
871       •   "unknown"
872
873           Invoked if "$result->is_unknown" returns true.
874
875       •   "ELSE"
876
877           If a result does not have a callback defined for it, this callback
878           will be invoked. Thus, if all of the previous result types are
879           specified as callbacks, this callback will never be invoked.
880
881       •   "ALL"
882
883           This callback will always be invoked and this will happen for each
884           result after one of the above callbacks is invoked.  For example,
885           if Term::ANSIColor is loaded, you could use the following to color
886           your test output:
887
888            my %callbacks = (
889                test => sub {
890                    my $test = shift;
891                    if ( $test->is_ok && not $test->directive ) {
892                        # normal passing test
893                        print color 'green';
894                    }
895                    elsif ( !$test->is_ok ) {    # even if it's TODO
896                        print color 'white on_red';
897                    }
898                    elsif ( $test->has_skip ) {
899                        print color 'white on_blue';
900
901                    }
902                    elsif ( $test->has_todo ) {
903                        print color 'white';
904                    }
905                },
906                ELSE => sub {
907                    # plan, comment, and so on (anything which isn't a test line)
908                    print color 'black on_white';
909                },
910                ALL => sub {
911                    # now print them
912                    print shift->as_string;
913                    print color 'reset';
914                    print "\n";
915                },
916            );
917
918       •   "EOF"
919
920           Invoked when there are no more lines to be parsed. Since there is
921           no accompanying TAP::Parser::Result object the "TAP::Parser" object
922           is passed instead.
923

TAP GRAMMAR

925       If you're looking for an EBNF grammar, see TAP::Parser::Grammar.
926

BACKWARDS COMPATIBILITY

928       The Perl-QA list attempted to ensure backwards compatibility with
929       Test::Harness.  However, there are some minor differences.
930
931   Differences
932       •   TODO plans
933
934           A little-known feature of Test::Harness is that it supported TODO
935           lists in the plan:
936
937            1..2 todo 2
938            ok 1 - We have liftoff
939            not ok 2 - Anti-gravity device activated
940
941           Under Test::Harness, test number 2 would pass because it was listed
942           as a TODO test on the plan line. However, we are not aware of
943           anyone actually using this feature and hard-coding test numbers is
944           discouraged because it's very easy to add a test and break the test
945           number sequence. This makes test suites very fragile. Instead, the
946           following should be used:
947
948            1..2
949            ok 1 - We have liftoff
950            not ok 2 - Anti-gravity device activated # TODO
951
952       •   'Missing' tests
953
954           It rarely happens, but sometimes a harness might encounter 'missing
955           tests:
956
957            ok 1
958            ok 2
959            ok 15
960            ok 16
961            ok 17
962
963           Test::Harness would report tests 3-14 as having failed. For the
964           "TAP::Parser", these tests are not considered failed because
965           they've never run. They're reported as parse failures (tests out of
966           sequence).
967

SUBCLASSING

969       If you find you need to provide custom functionality (as you would have
970       using Test::Harness::Straps), you're in luck: "TAP::Parser" and friends
971       are designed to be easily plugged-into and/or subclassed.
972
973       Before you start, it's important to know a few things:
974
975       1.
976         All "TAP::*" objects inherit from TAP::Object.
977
978       2.
979         Many "TAP::*" classes have a SUBCLASSING section to guide you.
980
981       3.
982         Note that "TAP::Parser" is designed to be the central "maker" - ie:
983         it is responsible for creating most new objects in the
984         "TAP::Parser::*" namespace.
985
986         This makes it possible for you to have a single point of configuring
987         what subclasses should be used, which means that in many cases you'll
988         find you only need to sub-class one of the parser's components.
989
990         The exception to this rule are SourceHandlers & Iterators, but those
991         are both created with customizable IteratorFactory.
992
993       4.
994         By subclassing, you may end up overriding undocumented methods.
995         That's not a bad thing per se, but be forewarned that undocumented
996         methods may change without warning from one release to the next - we
997         cannot guarantee backwards compatibility.  If any documented method
998         needs changing, it will be deprecated first, and changed in a later
999         release.
1000
1001   Parser Components
1002       Sources
1003
1004       A TAP parser consumes input from a single raw source of TAP, which
1005       could come from anywhere (a file, an executable, a database, an IO
1006       handle, a URI, etc..).  The source gets bundled up in a
1007       TAP::Parser::Source object which gathers some meta data about it.  The
1008       parser then uses a TAP::Parser::IteratorFactory to determine which
1009       TAP::Parser::SourceHandler to use to turn the raw source into a stream
1010       of TAP by way of "Iterators".
1011
1012       If you simply want "TAP::Parser" to handle a new source of TAP you
1013       probably don't need to subclass "TAP::Parser" itself.  Rather, you'll
1014       need to create a new TAP::Parser::SourceHandler class, and just plug it
1015       into the parser using the sources param to "new".  Before you start
1016       writing one, read through TAP::Parser::IteratorFactory to get a feel
1017       for how the system works first.
1018
1019       If you find you really need to use your own iterator factory you can
1020       still do so without sub-classing "TAP::Parser" by setting
1021       "iterator_factory_class".
1022
1023       If you just need to customize the objects on creation, subclass
1024       TAP::Parser and override "make_iterator_factory".
1025
1026       Note that "make_source" & "make_perl_source" have been DEPRECATED and
1027       are now removed.
1028
1029       Iterators
1030
1031       A TAP parser uses iterators to loop through the stream of TAP read in
1032       from the source it was given.  There are a few types of Iterators
1033       available by default, all sub-classes of TAP::Parser::Iterator.
1034       Choosing which iterator to use is the responsibility of the iterator
1035       factory, though it simply delegates to the Source Handler it uses.
1036
1037       If you're writing your own TAP::Parser::SourceHandler, you may need to
1038       create your own iterators too.  If so you'll need to subclass
1039       TAP::Parser::Iterator.
1040
1041       Note that "make_iterator" has been DEPRECATED and is now removed.
1042
1043       Results
1044
1045       A TAP parser creates TAP::Parser::Results as it iterates through the
1046       input stream.  There are quite a few result types available; choosing
1047       which class to use is the responsibility of the result factory.
1048
1049       To create your own result types you have two options:
1050
1051       option 1
1052         Subclass TAP::Parser::Result and register your new result type/class
1053         with the default TAP::Parser::ResultFactory.
1054
1055       option 2
1056         Subclass TAP::Parser::ResultFactory itself and implement your own
1057         TAP::Parser::Result creation logic.  Then you'll need to customize
1058         the class used by your parser by setting the "result_factory_class"
1059         parameter.  See "new" for more details.
1060
1061       If you need to customize the objects on creation, subclass TAP::Parser
1062       and override "make_result".
1063
1064       Grammar
1065
1066       TAP::Parser::Grammar is the heart of the parser.  It tokenizes the TAP
1067       input stream and produces results.  If you need to customize its
1068       behaviour you should probably familiarize yourself with the source
1069       first.  Enough lecturing.
1070
1071       Subclass TAP::Parser::Grammar and customize your parser by setting the
1072       "grammar_class" parameter.  See "new" for more details.
1073
1074       If you need to customize the objects on creation, subclass TAP::Parser
1075       and override "make_grammar"
1076

ACKNOWLEDGMENTS

1078       All of the following have helped. Bug reports, patches, (im)moral
1079       support, or just words of encouragement have all been forthcoming.
1080
1081       •   Michael Schwern
1082
1083       •   Andy Lester
1084
1085       •   chromatic
1086
1087       •   GEOFFR
1088
1089       •   Shlomi Fish
1090
1091       •   Torsten Schoenfeld
1092
1093       •   Jerry Gay
1094
1095       •   Aristotle
1096
1097       •   Adam Kennedy
1098
1099       •   Yves Orton
1100
1101       •   Adrian Howard
1102
1103       •   Sean & Lil
1104
1105       •   Andreas J. Koenig
1106
1107       •   Florian Ragwitz
1108
1109       •   Corion
1110
1111       •   Mark Stosberg
1112
1113       •   Matt Kraai
1114
1115       •   David Wheeler
1116
1117       •   Alex Vandiver
1118
1119       •   Cosimo Streppone
1120
1121       •   Ville Skyttä
1122

AUTHORS

1124       Curtis "Ovid" Poe <ovid@cpan.org>
1125
1126       Andy Armstong <andy@hexten.net>
1127
1128       Eric Wilhelm @ <ewilhelm at cpan dot org>
1129
1130       Michael Peters <mpeters at plusthree dot com>
1131
1132       Leif Eriksen <leif dot eriksen at bigpond dot com>
1133
1134       Steve Purkis <spurkis@cpan.org>
1135
1136       Nicholas Clark <nick@ccl4.org>
1137
1138       Lee Johnson <notfadeaway at btinternet dot com>
1139
1140       Philippe Bruhat <book@cpan.org>
1141

BUGS

1143       Please report any bugs or feature requests to
1144       "bug-test-harness@rt.cpan.org", or through the web interface at
1145       <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Test-Harness>.  We will
1146       be notified, and then you'll automatically be notified of progress on
1147       your bug as we make changes.
1148
1149       Obviously, bugs which include patches are best. If you prefer, you can
1150       patch against bleed by via anonymous checkout of the latest version:
1151
1152        git clone git://github.com/Perl-Toolchain-Gang/Test-Harness.git
1153
1155       Copyright 2006-2008 Curtis "Ovid" Poe, all rights reserved.
1156
1157       This program is free software; you can redistribute it and/or modify it
1158       under the same terms as Perl itself.
1159
1160
1161
1162perl v5.34.0                      2021-07-23                    TAP::Parser(3)
Impressum