perldoc > TAP::Parser

man perldoc info pydoc3 ri search

📛 NAME

TAP::Parser - Parse TAP output

🚀 Quick Reference

Use Case	Command	Description
🔍 Create parser from file	TAP::Parser->new({ source => $file })	Parse TAP from a file or executable source
🔍 Create parser from string	TAP::Parser->new({ tap => $tap_string })	Parse TAP from a complete string
🔍 Create parser from command	TAP::Parser->new({ exec => [ 'ruby', 'test.rb' ] })	Execute a command and parse its TAP output
📖 Iterate results	while (my $r = $parser->next) { ... }	Fetch one parsed result at a time
▶️ Run full parse	$parser->run	Parse all TAP at once (uses callbacks)
✅ Check test pass	$result->is_ok	Returns true if the test passed (TODO tests also pass)
📊 Get passed tests	$parser->passed	Returns list/count of passed test numbers
📊 Get failed tests	$parser->failed	Returns list/count of failed test numbers
📋 Get parse errors	$parser->parse_errors	Returns list/count of TAP parse errors
🔧 Check overall plan	$parser->is_good_plan	True if planned tests match run tests

📌 VERSION

Version 3.43

📖 SYNOPSIS

use TAP::Parser;

my $parser = TAP::Parser->new( { source => $source } );

while ( my $result = $parser->next ) {
    print $result->as_string;
}

📝 DESCRIPTION

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:

http://testanything.org

It includes the TAP::Parser Cookbook:

http://testanything.org/testing-with-tap/perl/tap::parser-cookbook.html

⚙️ METHODS

🏗️ Class Methods

new

my $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 — Preferred method of passing input. Creates a TAP::Parser::Source passed to the iterator_factory_class which creates an iterator. Mutually exclusive with tap and exec.

• tap — CHANGED in 3.18 — Complete TAP output string. Creates a TAP::Parser::Source. Mutually exclusive with source and exec.

• exec — Array reference. Creates a TAP::Parser::Source; by default uses TAP::Parser::SourceHandler::Executable to create a TAP::Parser::Iterator::Process. Example: exec => [ '/usr/bin/ruby', 't/my_test.rb' ]. Mutually exclusive with source and tap.

The following keys are optional:

• sources — NEW to 3.18 — Hashref of TAP::Parser::SourceHandlers to load/configure. Keys are handler names, values are config hashes. Example: sources => { Perl => { exec => '/path/to/custom/perl' }, File => { extensions => [ '.tap', '.txt' ] } }

• callback — Hashref of callbacks invoked by run method. Keys: test, plan, comment, bailout, unknown.

  my %callbacks = (
      test    => \&test_callback,
      plan    => \&plan_callback,
      comment => \&comment_callback,
      bailout => \&bailout_callback,
      unknown => \&unknown_callback,
  );

• switches — Array of Perl switches for Perl file sources. Example: switches => [ '-Ilib' ]

• test_args — Array reference of arguments to pass to the test program (with source or exec).

• spool — Filehandle to write a copy of all parsed TAP.

• merge — Boolean. If true, STDERR and STDOUT are merged. May cause breakage if STDERR contains TAP-like output.

• grammar_class — Defaults to TAP::Parser::Grammar.

• result_factory_class — Defaults to TAP::Parser::ResultFactory.

• iterator_factory_class — CHANGED in 3.18 — Defaults to TAP::Parser::IteratorFactory.

🔧 Instance Methods

next

my $parser = TAP::Parser->new( { source => $file } );
while ( my $result = $parser->next ) {
    print $result->as_string, "\n";
}

Returns parsed results one at a time. Destructive — cannot rewind. Callbacks are issued before this returns. Each result is a subclass of TAP::Parser::Result.

run

$parser->run;

Parses all TAP at once.

make_grammar

Creates a new TAP::Parser::Grammar object. Customizable via grammar_class.

make_result

Creates a new TAP::Parser::Result using the TAP::Parser::ResultFactory. Customizable via result_factory_class.

make_iterator_factory

NEW to 3.18. Creates a new TAP::Parser::IteratorFactory. Customizable via iterator_factory_class.

🔬 INDIVIDUAL RESULTS

while ( my $result = $parser->next ) {
    print $result->as_string;
}

Each result is a TAP::Parser::Result subclass (referred to as result types).

📋 Result types

• Version — TAP version 12
• Plan — 1..42
• Pragma — pragma +strict
• Test — 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 object has common methods and type-specific methods.

🔗 Common type methods

type

Returns the result type string (e.g., comment or test).

as_string

Returns a cleaned-up string representation. Test numbers are added if missing, directives are capitalized.

raw

Returns the original parsed line of text.

is_plan

True if this is the test plan line.

is_test

True if this is a test line.

is_comment

True if this is a comment (usually only appears with merged STDERR).

is_bailout

True if this is a bailout line.

is_yaml

True if the current item is a YAML block.

is_unknown

True if the line could not be parsed.

is_ok

if ( $result->is_ok ) { ... }

Reports whether a result has passed. Non-test results return true. Useful for filtering:

my $parser = TAP::Parser->new( { source => $source } );
while ( my $result = $parser->next ) {
    print $result->as_string unless $result->is_ok;
}

Plan methods

if ( $result->is_plan ) { ... }

• plan — Synonym for as_string.
• directive — Returns the SKIP directive if present (e.g., 1..0 # SKIP: why bother?).
• explanation — Returns the explanation for a SKIP directive.

Pragma methods

if ( $result->is_pragma ) { ... }

• pragmas — Returns a list of pragmas (each prefixed with + or -).

Comment methods

if ( $result->is_comment ) { ... }

• comment — Returns the comment text.

Bailout methods

if ( $result->is_bailout ) { ... }

• explanation — Returns the text after Bail out!.

Unknown methods

No unique methods for unknown results.

Test methods

if ( $result->is_test ) { ... }

• ok — Returns the literal ok or not ok text.
• number — Returns the test number (auto-assigned if missing).
• description — Returns the description after the test number, before any directive.
• directive — Returns TODO or SKIP if present.
• explanation — Returns the explanation for a TODO/SKIP directive.
• is_ok — Boolean; true if test passed. TODO tests always pass.
• is_actual_ok — Boolean; true if test passed regardless of TODO status.
• is_unplanned — True if the test number exceeds the planned count. Unplanned tests always return false for is_ok.
• has_skip — True if test had a SKIP directive.
• has_todo — True if test had a TODO directive. TODO tests always pass.
• in_todo — True while the most recent result was a TODO. Stays true until the next non-TODO test.

📊 TOTAL RESULTS

After parsing, many methods are available to analyze results.

🎯 Individual Results

passed

my @passed = $parser->passed; # test numbers which passed
my $passed = $parser->passed; # count of tests passed

TODO tests that failed are counted as passed.

failed

my @failed = $parser->failed; # test numbers which failed
my $failed = $parser->failed; # count of tests failed

TODO tests that passed are NOT counted as failed.

actual_passed

my @actual_passed = $parser->actual_passed;
my $actual_passed = $parser->actual_passed;

Tests that actually passed regardless of TODO.

actual_ok

Synonym for actual_passed.

actual_failed

my @actual_failed = $parser->actual_failed;
my $actual_failed = $parser->actual_failed;

Tests that actually failed regardless of TODO.

todo

my @todo = $parser->todo;
my $todo = $parser->todo;

Tests with TODO directives.

todo_passed

my @todo_passed = $parser->todo_passed;
my $todo_passed = $parser->todo_passed;

Tests that unexpectedly succeeded (TODO but passed).

todo_failed

Deprecated in favor of todo_passed.

skipped

my @skipped = $parser->skipped;
my $skipped = $parser->skipped;

Tests with SKIP directives.

⚙️ Pragmas

pragma

Get or set a pragma:

if ( $p->pragma('strict') ) { ... }
$p->pragma('strict', 1); # enable strict mode

pragmas

my @pragmas_enabled = $p->pragmas;

Get all currently enabled pragmas.

📈 Summary Results

plan

my $plan = $parser->plan;

Returns the test plan, if found.

good_plan

Deprecated. Use is_good_plan.

is_good_plan

if ( $parser->is_good_plan ) { ... }

True if the number of planned tests matches the number of tests run.

tests_planned

print $parser->tests_planned;

Number of tests planned (e.g., 1..17 means 17 planned).

tests_run

print $parser->tests_run;

Number of tests actually run.

skip_all

Returns the reason for skipping if all tests were skipped.

start_time

Wall-clock time when the Parser was created.

end_time

Wall-clock time when the end of TAP input was seen.

start_times

CPU times (like times in perlfunc) when the Parser was created.

end_times

CPU times (like times in perlfunc) when the end of TAP input was seen.

has_problems

if ( $parser->has_problems ) { ... }

Catch-all: true if any tests failed, TODO tests unexpectedly succeeded, or parse errors occurred.

version

$parser->version;

TAP version number (defaults to 12 if not found).

exit

$parser->exit;

Exit status of the executable (if ran).

wait

$parser->wait;

Wait status of the executable. For non-executables, returns the exit status.

ignore_exit

$parser->ignore_exit(1);

Tell the parser to ignore the exit status when determining pass/fail. Useful when exit status cannot be controlled.

parse_errors

my @errors = $parser->parse_errors;
my $errors = $parser->parse_errors;

Returns parser errors. TAP errors include:

• Misplaced plan — Plan must be at beginning or end of TAP output.
• No plan — Must have a plan.
• More than one plan — Duplicate plans are errors.
• Test numbers out of sequence — Test numbers must be sequential when present.

Note: Junk lines the parser doesn't recognize are NOT errors (future-proofing).

get_select_handles

Get file handles for select to check parser readiness.

delete_spool

my $fh = $parser->delete_spool;

Delete and return the spool filehandle.

📞 CALLBACKS

A callback key may be added to the constructor. Each callback is a subroutine reference invoked with the result as argument when run 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 );
}

Callbacks can also be added after construction:

$parser->callback( test => \&test_callback );
$parser->callback( plan => \&plan_callback );

Allowed callback keys (case-sensitive):

• test — Invoked if $result->is_test returns true.
• version — Invoked if $result->is_version returns true.
• plan — Invoked if $result->is_plan returns true.
• comment — Invoked if $result->is_comment returns true.
• bailout — Invoked if $result->is_unknown returns true.
• yaml — Invoked if $result->is_yaml returns true.
• unknown — Invoked if $result->is_unknown returns true.
• ELSE — Fallback for results without a specific callback.
• ALL — Always invoked after each result's specific callback.
• EOF — Invoked when no more lines remain. The parser object is passed instead of a result.

Example with Term::ANSIColor:

my %callbacks = (
    test => sub {
        my $test = shift;
        if ( $test->is_ok && not $test->directive ) {
            print color 'green';
        }
        elsif ( !$test->is_ok ) {
            print color 'white on_red';
        }
        elsif ( $test->has_skip ) {
            print color 'white on_blue';
        }
        elsif ( $test->has_todo ) {
            print color 'white';
        }
    },
    ELSE => sub {
        print color 'black on_white';
    },
    ALL => sub {
        print shift->as_string;
        print color 'reset';
        print "\n";
    },
);

📜 TAP GRAMMAR

For an EBNF grammar, see TAP::Parser::Grammar.

🔄 BACKWARDS COMPATIBILITY

Minor differences from Test::Harness:

🆚 Differences

• TODO plans — Test::Harness supported TODO lists in the plan (1..2 todo 2). TAP::Parser does not; instead use inline TODO directives: not ok 2 - ... # TODO
• 'Missing' tests — Test::Harness reported missing tests as failed. TAP::Parser reports them as parse errors (tests out of sequence) since they never ran.

🧩 SUBCLASSING

All TAP::* objects inherit from TAP::Object. Many classes have a SUBCLASSING section. TAP::Parser is the central "maker" — it creates most objects in the TAP::Parser::* namespace, allowing single-point configuration.

🔧 Parser Components

📁 Sources

A TAP parser consumes input from a single raw source (file, executable, database, IO handle, URI, etc.). The source is bundled into a TAP::Parser::Source, then TAP::Parser::IteratorFactory determines which TAP::Parser::SourceHandler to use. To handle new source types, create a new TAP::Parser::SourceHandler subclass and plug it in via the sources parameter. Use iterator_factory_class for custom iterator factories without subclassing TAP::Parser.

🔄 Iterators

Iterators loop through the TAP stream. Default types subclass TAP::Parser::Iterator. The iterator factory delegates to the source handler. Custom iterators require subclassing TAP::Parser::Iterator.

✅ Results

Results are created as the parser iterates. Two options for custom result types:

• Option 1: Subclass TAP::Parser::Result and register with the default TAP::Parser::ResultFactory.
• Option 2: Subclass TAP::Parser::ResultFactory and set result_factory_class.

Override make_result for custom creation logic.

📖 Grammar

TAP::Parser::Grammar tokenizes the TAP stream and produces results. Subclass it and set grammar_class, or override make_grammar.

🙏 ACKNOWLEDGMENTS

Many thanks to all contributors:

• Michael Schwern
• Andy Lester
• chromatic
• GEOFFR
• Shlomi Fish
• Torsten Schoenfeld
• Jerry Gay
• Aristotle
• Adam Kennedy
• Yves Orton
• Adrian Howard
• Sean & Lil
• Andreas J. Koenig
• Florian Ragwitz
• Corion
• Mark Stosberg
• Matt Kraai
• David Wheeler
• Alex Vandiver
• Cosimo Streppone
• Ville Skyttä

✍️ AUTHORS

• Curtis "Ovid" Poe <ovid AT cpan.org>
• Andy Armstong <andy AT hexten.net>
• Eric Wilhelm @ <ewilhelm at cpan dot org>
• Michael Peters <mpeters at plusthree dot com>
• Leif Eriksen <leif dot eriksen at bigpond dot com>
• Steve Purkis <spurkis AT cpan.org>
• Nicholas Clark <nick AT ccl4.org>
• Lee Johnson <notfadeaway at btinternet dot com>
• Philippe Bruhat <book AT cpan.org>

🐛 BUGS

Report bugs or feature requests to bug-test-harness AT rt.org or via the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Test-Harness. Patches are best. Anonymous checkout of latest version:

git clone git://github.com/Perl-Toolchain-Gang/Test-Harness.git

📄 COPYRIGHT & LICENSE

Copyright 2006-2008 Curtis "Ovid" Poe, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

📛 NAME 🚀 Quick Reference 📌 VERSION 📖 SYNOPSIS 📝 DESCRIPTION ⚙️ METHODS 🔬 INDIVIDUAL RESULTS 📊 TOTAL RESULTS 📞 CALLBACKS 📜 TAP GRAMMAR 🔄 BACKWARDS COMPATIBILITY 🧩 SUBCLASSING 🙏 ACKNOWLEDGMENTS ✍️ AUTHORS 🐛 BUGS 📄 COPYRIGHT & LICENSE