TAP::Parser - Parse TAP output
Version 3.30
use TAP::Parser;
my $parser = TAP::Parser->new( { source => $source } );
while ( my $result = $parser->next ) {
print $result->as_string;
}TAP::Parser is designed to produce a proper parse of TAP output. For an example of how to run tests through this module, see the simple harnesses examples/.
There's a wiki dedicated to the Test Anything Protocol:
It includes the TAP::Parser Cookbook:
http://testanything.org/wiki/index.php/TAP::Parser_Cookbook
newmy $parser = TAP::Parser->new(\%args);Returns a new TAP::Parser object.
The arguments should be a hashref with one of the following keys:
source
CHANGED in 3.18
This is the preferred method of passing input to the constructor.
The source is used to create a TAP::Parser::Source that is passed to the "iterator_factory_class" which in turn figures out how to handle the source and creates a <TAP::Parser::Iterator> for it. The iterator is used by the parser to read in the TAP stream.
To configure the IteratorFactory use the sources parameter below.
Note that source, tap and exec are mutually exclusive.
tap
CHANGED in 3.18
The value should be the complete TAP output.
The tap is used to create a TAP::Parser::Source that is passed to the "iterator_factory_class" which in turn figures out how to handle the source and creates a <TAP::Parser::Iterator> for it. The iterator is used by the parser to read in the TAP stream.
To configure the IteratorFactory use the sources parameter below.
Note that source, tap and exec are mutually exclusive.
exec
Must be passed an array reference.
The exec array ref is used to create a TAP::Parser::Source that is passed to the "iterator_factory_class" which in turn figures out how to handle the source and creates a <TAP::Parser::Iterator> for it. The iterator is used by the parser to read in the TAP stream.
By default the TAP::Parser::SourceHandler::Executable class will create a TAP::Parser::Iterator::Process object to handle the source. This passes the array reference strings as command arguments to IPC::Open3::open3:
exec => [ '/usr/bin/ruby', 't/my_test.rb' ]If any test_args are given they will be appended to the end of the command argument list.
To configure the IteratorFactory use the sources parameter below.
Note that source, tap and exec are mutually exclusive.
The following keys are optional.
sources
NEW to 3.18.
If set, sources must be a hashref containing the names of the TAP::Parser::SourceHandlers to load and/or configure. The values are a hash of configuration that will be accessible to the source handlers via "config_for" in TAP::Parser::Source.
For example:
sources => {
Perl => { exec => '/path/to/custom/perl' },
File => { extensions => [ '.tap', '.txt' ] },
MyCustom => { some => 'config' },
}This will cause TAP::Parser to pass custom configuration to two of the built- in source handlers - TAP::Parser::SourceHandler::Perl, TAP::Parser::SourceHandler::File - and attempt to load the MyCustom class. See "load_handlers" in TAP::Parser::IteratorFactory for more detail.
The sources parameter affects how source, tap and exec parameters are handled.
See TAP::Parser::IteratorFactory, TAP::Parser::SourceHandler and subclasses for more details.
callback
If present, each callback corresponding to a given result type will be called with the result as the argument if the run method is used:
my %callbacks = (
test => \&test_callback,
plan => \&plan_callback,
comment => \&comment_callback,
bailout => \&bailout_callback,
unknown => \&unknown_callback,
);
my $aggregator = TAP::Parser::Aggregator->new;
for my $file ( @test_files ) {
my $parser = TAP::Parser->new(
{
source => $file,
callbacks => \%callbacks,
}
);
$parser->run;
$aggregator->add( $file, $parser );
}switches
If using a Perl file as a source, optional switches may be passed which will be used when invoking the perl executable.
my $parser = TAP::Parser->new( {
source => $test_file,
switches => [ '-Ilib' ],
} );test_args
Used in conjunction with the source and exec option to supply a reference to an @ARGV style array of arguments to pass to the test program.
spool
If passed a filehandle will write a copy of all parsed TAP to that handle.
merge
If false, STDERR is not captured (though it is 'relayed' to keep it somewhat synchronized with STDOUT.)
If true, STDERR and STDOUT are the same filehandle. This may cause breakage if STDERR contains anything resembling TAP format, but does allow exact synchronization.
Subtleties of this behavior may be platform-dependent and may change in the future.
grammar_class
This option was introduced to let you easily customize which grammar class the parser should use. It defaults to TAP::Parser::Grammar.
See also "make_grammar".
result_factory_class
This option was introduced to let you easily customize which result factory class the parser should use. It defaults to TAP::Parser::ResultFactory.
See also "make_result".
iterator_factory_class
CHANGED in 3.18
This option was introduced to let you easily customize which iterator factory class the parser should use. It defaults to TAP::Parser::IteratorFactory.
nextmy $parser = TAP::Parser->new( { source => $file } );
while ( my $result = $parser->next ) {
print $result->as_string, "\n";
}This method returns the results of the parsing, one result at a time. Note that it is destructive. You can't rewind and examine previous results.
If callbacks are used, they will be issued before this call returns.
Each result returned is a subclass of TAP::Parser::Result. See that module and related classes for more information on how to use them.
run$parser->run;This method merely runs the parser and parses all of the TAP.
make_grammarMake a new TAP::Parser::Grammar object and return it. Passes through any arguments given.
The grammar_class can be customized, as described in "new".
make_resultMake a new TAP::Parser::Result object using the parser's TAP::Parser::ResultFactory, and return it. Passes through any arguments given.
The result_factory_class can be customized, as described in "new".
make_iterator_factoryNEW to 3.18.
Make a new TAP::Parser::IteratorFactory object and return it. Passes through any arguments given.
iterator_factory_class can be customized, as described in "new".
If you've read this far in the docs, you've seen this:
while ( my $result = $parser->next ) {
print $result->as_string;
}Each result returned is a TAP::Parser::Result subclass, referred to as result types.
Basically, you fetch individual results from the TAP. The six types, with examples of each, are as follows:
Version
TAP version 12Plan
1..42Pragma
pragma +strictTest
ok 3 - We should start with some foobar!Comment
# Hope we don't use up the foobar.Bailout
Bail out! We ran out of foobar!Unknown
... yo, this ain't TAP! ...Each result fetched is a result object of a different type. There are common methods to each result object and different types may have methods unique to their type. Sometimes a type method may be overridden in a subclass, but its use is guaranteed to be identical.
typeReturns the type of result, such as comment or test.