perldoc > TAP::Harness

man perldoc info pydoc3 ri search

📖 NAME

TAP::Harness - Run test scripts with statistics

🔖 VERSION

Version 3.43

🚀 Quick Reference

Use Case	Command	Description
Create harness	my $harness = TAP::Harness->new( \%args );	Create a new harness with configuration options
Run tests	$harness->runtests(@tests);	Run test files and aggregate results
Run tests with aliases	$harness->runtests( [ 't/foo.t', 'Alias' ] );	Run same test multiple times with unique names
Set verbosity	verbosity => 1	Control output: 1 verbose, 0 normal, -1 quiet, -2 really quiet, -3 silent
Parallel execution	jobs => 4	Run up to 4 tests concurrently
Custom formatter	formatter_class => 'TAP::Formatter::HTML'	Change output format (default: Console or File)
Custom sources	sources => { Perl => { exec => '/path/to/perl' } }	Customize TAP source handling

📝 DESCRIPTION

This is a simple test harness which allows tests to be run and results automatically aggregated and output to STDOUT.

📋 SYNOPSIS

 use TAP::Harness;
 my $harness = TAP::Harness->new( \%args );
 $harness->runtests(@tests);

⚙️ METHODS

📂 Class Methods

new

my %args = (
   verbosity => 1,
   lib     => [ 'lib', 'blib/lib', 'blib/arch' ],
)
my $harness = TAP::Harness->new( \%args );

The constructor returns a new TAP::Harness object. It accepts an optional hashref whose allowed keys are:

• verbosity - Set the verbosity level:
  • 1 - verbose - Print individual test results to STDOUT.
  • 0 - normal
  • -1 - quiet - Suppress some test output (mostly failures while tests are running).
  • -2 - really quiet - Suppress everything but the tests summary.
  • -3 - silent - Suppress everything.
• timer - Append run time for each test to output. Uses Time::HiRes if available.
• failures - Show test failures (this is a no-op if verbose is selected).
• comments - Show test comments (this is a no-op if verbose is selected).
• show_count - Update the running test count during testing.
• normalize - Set to a true value to normalize the TAP that is emitted in verbose modes.
• lib - Accepts a scalar value or array ref of scalar values indicating which paths to allowed libraries should be included if Perl tests are executed.
• switches - Accepts a scalar value or array ref of scalar values indicating which switches should be included if Perl tests are executed.
• test_args - A reference to an @INC style array of arguments to be passed to each test program. Can also be a hash of arrays keyed by test alias.
• color - Attempt to produce color output.
• exec - Specify the name of the program (and optional switches) to run your tests with. Can also be a subroutine reference that returns the command array or undef for Perl fallback.
• merge - If true, the harness will create parsers that merge STDOUT and STDERR together for any processes they start.
• sources - NEW to 3.18. A hashref containing the names of TAP::Parser::SourceHandlers to load and/or configure.
• aggregator_class - The name of the class to use to aggregate test results (default: TAP::Parser::Aggregator).
• version - NEW to 3.22. Assume this TAP version for TAP::Parser instead of default TAP version 12.
• formatter_class - The name of the class to use to format output (default: TAP::Formatter::Console or TAP::Formatter::File).
• multiplexer_class - The name of the class to use to multiplex tests during parallel testing (default: TAP::Parser::Multiplexer).
• parser_class - The name of the class to use to parse TAP (default: TAP::Parser).
• scheduler_class - The name of the class to use to schedule test execution (default: TAP::Parser::Scheduler).
• formatter - If set, must be an object that is capable of formatting the TAP output.
• errors - If set to true, all parse errors will be shown in the summary report.
• directives - If set to a true value, only test results with directives will be displayed.
• ignore_exit - If set to a true value, instruct TAP::Parser to ignore exit and wait status from test scripts.
• jobs - The maximum number of parallel tests to run at any time. Default is 1.
• rules - A reference to a hash of rules that control which tests may be executed in parallel.
• rulesfiles - Specifies where to find a YAML file of test scheduling rules.
• stdout - A filehandle for catching standard output.
• trap - Attempt to print summary information if run is interrupted by SIGINT (Ctrl-C).

Any keys for which the value is undef will be ignored.

📂 Instance Methods

runtests

$harness->runtests(@tests);

Accepts an array of @tests to be run. Each element in @tests will be passed to TAP::Parser::new() as a source. See TAP::Parser for more information. It is possible to provide aliases by supplying the test as a reference to an array containing [ $test, $alias ]. Tests will be run in the order found. If the environment variable PERL_TEST_HARNESS_DUMP_TAP is defined, a copy of the raw TAP for each test will be written to that directory. Returns a TAP::Parser::Aggregator containing the test results.

summary

$harness->summary( $aggregator );

Output the summary for a TAP::Parser::Aggregator.

aggregate_tests

$harness->aggregate_tests( $aggregate, @tests );

Run the named tests and display a summary of results. Tests will be run in the order found. Test results will be added to the supplied TAP::Parser::Aggregator. May be called multiple times to run several sets of tests. Allows using different TAP::Harness instances for different parts of a test suite. Each element of the @tests array is either the source name of a test to run, or a reference to a [ source name, display name ] array.

make_scheduler

Called by the harness when it needs to create a TAP::Parser::Scheduler. Override in a subclass to provide an alternative scheduler. Passed the list of tests that was passed to aggregate_tests.

jobs

Gets or sets the number of concurrent test runs the harness is handling. By default, this value is 1.

make_parser

my ( $parser, $session ) = $harness->make_parser;

Make a new parser and display formatter session. Typically used and/or overridden in subclasses.

finish_parser

Terminate use of a parser. Typically used and/or overridden in subclasses. The parser isn't destroyed as a result of this.

🔧 CONFIGURING

"TAP::Harness" is designed to be easy to configure.

🔌 Plugins

TAP::Parser plugins let you change the way TAP is input to and output from the parser.

• TAP::Parser::SourceHandlers handle TAP input. You can configure them and load custom handlers using the sources parameter to new.
• TAP::Formatters handle TAP output. You can load custom formatters using the formatter_class parameter to new. To configure a formatter, instantiate it outside of TAP::Harness and pass it with the formatter parameter.

Module::Build

Module::Build version 0.30 supports TAP::Harness. To load plugins, use the tap_harness_args parameter to new in your Build.PL:

Module::Build->new(
    module_name        => 'MyApp',
    test_file_exts     => [qw(.t .tap .txt)],
    use_tap_harness    => 1,
    tap_harness_args   => {
        sources => {
            MyCustom => {},
            File => {
                extensions => ['.tap', '.txt'],
            },
        },
        formatter_class => 'TAP::Formatter::HTML',
    },
    build_requires     => {
        'Module::Build' => '0.30',
        'TAP::Harness'  => '3.18',
    },
)->create_build_script;

ExtUtils::MakeMaker

ExtUtils::MakeMaker does not support TAP::Harness out-of-the-box.

prove

prove supports TAP::Harness plugins, and has a plugin system of its own. See FORMATTERS in prove, SOURCE HANDLERS in prove and App::Prove for more details.

✍️ WRITING PLUGINS

If you can't configure TAP::Harness to do what you want, and you can't find an existing plugin, consider writing one. The two primary use cases are input and output.

• Customize how TAP gets into the parser - Extend an existing TAP::Parser::SourceHandler or write your own. Load and configure using the sources parameter to new.
• Customize how TAP results are output from the parser - Extend an existing TAP::Formatter or write your own. Understand the TAP::Parser API; a good start is understanding how aggregate_tests works. Custom formatters can be loaded using the formatter_class parameter to new.

🧬 SUBCLASSING

If you can't configure TAP::Harness to do exactly what you want, and writing a plugin isn't an option, consider extending it. It is designed to be (mostly) easy to subclass.

📂 Methods

The following methods are ones you may wish to override if you want to subclass TAP::Harness:

• new
• runtests
• summary

🔄 REPLACING

If you like the prove utility and TAP::Parser but you want your own harness, all you need to do is write one and provide new and runtests methods. Then you can use the prove utility like so:

 prove --harness My::Test::Harness

Note that while prove accepts a list of tests, new has a fairly rich set of arguments. You'll probably want to read over this code carefully to see how all of them are being used.

📚 SEE ALSO

Test::Harness

📖 NAME 🔖 VERSION 🚀 Quick Reference 📝 DESCRIPTION 📋 SYNOPSIS ⚙️ METHODS 🔧 CONFIGURING ✍️ WRITING PLUGINS 🧬 SUBCLASSING 🔄 REPLACING 📚 SEE ALSO