NAME

Test::Steering - Execute test scripts conditionally

VERSION

This document describes Test::Steering version 0.02

SYNOPSIS

    use Test::Steering;

    include_tests( 'xt/vms/*.t' ) if $^O eq 'VMS';
    include_tests( 'xt/windows/*.t' ) if $^O =~ 'MSWin32';

DESCRIPTION

Often it is useful to have more control over which tests are executed - and how. You can exercise some degree of control by SKIPping unwanted tests but that can be inefficient and cumbersome for large test suites.

Test::Steering runs test scripts and filters their output into a single, syntactically correct TAP stream. In this way a single test script can be responsible for running multiple other tests.

The parameters for the TAP::Harness used run the subtests can also be controlled making it possible to, for example, run certain tests in parallel.

At some point in the future it is likely that TAP syntax will be extended to support hierarchical results. See

    http://testanything.org/wiki/index.php/Test_Groups
    http://testanything.org/wiki/index.php/Test_Blocks

for proposed schemes.

When hierarchical TAP is implemented this module will be upgraded to support it.

INTERFACE

include_tests

Run one or more tests. Wildcards will be expanded.

    include_tests( 'xt/vms/*.t' ) if $^O eq 'VMS';
    include_tests( 'xt/windows/*.t' ) if $^O =~ 'MSWin32';

Behind the scenes a new TAP::Harness will be created and used to run the individual test scripts. The output test results are concatenated, tests renumbered and then sent to STDOUT. The net effect of which is that multiple tests are able to masquerade as a single test.

If there are any problems running the tests (TAP syntax errors, non-zero exit status) those will be turned into additional test failures.

In addition to test names you may pass hash references which will be passed to TAP::Harness->new.

    # Run tests in parallel
    include_tests( { jobs => 9 }, 'xt/parallel/*/t' );

Multiple options hashes may be provided; they will be concatenated.

    # Run tests in parallel, enable warnings
    include_tests( { jobs => 9 },
        'xt/parallel/*/t', { switches => ['-w'] } );

end_plan

Output the trailing plan. Normally there is no need to call end_plan directly: it is called on exit.

tests_run

Get a list of tests that have been run.

    my @tests = tests_run();

OPTIONS

A number of options may be passed.

    use Test::Steering wheel => 'My::Wheel';

add_prefix

Add the name of the current test as a prefix to each result's description.

announce

Output a diagnostic naming each new subtest

defaults

A hash containing default options for include_tests.

wheel

The name of the support class that will be used. Defaults to Test::Steering::Wheel. Use this option to use a custom subclass.

CONFIGURATION AND ENVIRONMENT

Test::Steering requires no configuration files or environment variables.

DEPENDENCIES

None.

INCOMPATIBILITIES

None reported.

BUGS AND LIMITATIONS

No bugs have been reported.

Please report any bugs or feature requests to bug-test-steering@rt.cpan.org, or through the web interface at http://rt.cpan.org.

AUTHOR

Andy Armstrong <andy@hexten.net>

LICENCE AND COPYRIGHT

Copyright (c) 2007, Andy Armstrong <andy@hexten.net>.

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