NAME

TAP::Filter - Filter TAP stream within TAP::Harness

VERSION

This document describes TAP::Filter version 0.04

SYNOPSIS

In a program:

    use TAP::Filter qw( MyFilter );

    my $harness = TAP::Filter->new;
    $harness->runtests( @tests );

With prove:

    prove --harness=TAP::Filter=MyFilter -rb t

DESCRIPTION

TAP::Filter allows arbitrary filters to be placed in the TAP processing pipeline of TAP::Harness. Installed filters see the parsed TAP stream a line at a time and can modify the stream by

• replacing a result

• injecting extra results

• removing results

TAP::Filter exists mainly to load a number of filters into the TAP processing pipeline. Filters are generally subclasses of TAP::Filter::Iterator. See the documentation for that module for information about writing filters.

Loading filters

Filters may be installed into the TAP processing pipeline in a number of different ways...

From the prove command line

The prove command that is supplied with Test::Harness allows tests to be run interactively from the command line. By default it will use TAP::Harness to run these tests it can be told to use a different harness. TAP::Filter (which is a subclass of TAP::Harness) may be used with prove in this way:

    prove --harness=TAP::Filter=MyFilter,OtherFilter -rb t

TAP::Filter will attempt to load two filters, MyFilter and OtherFilter. If the name of the filter class to be loaded starts with TAP::Filter:: that prefix may be omitted, so the example above would load filter classes called TAP::Filter::MyFilter and TAP::Filter::OtherFilter.

use TAP::Filter qw( MyFilter )

If you are writing a program that uses TAP::Harness you can load filters by replacing

    use TAP::Harness;
    my $harness = TAP::Harness->new;

with

    use TAP::Filter qw( MyFilter OtherFilter );
    my $harness = TAP::Filter->new;

As with the prove command line invocation above TAP::Filter will attempt to load the specified filter classes from the TAP::Filter:: namespace. If that fails the classnames are taken to be absolute.

Calling TAP::Filter->add_filter

As an alternative to the concise filter loading notation above filters may be loaded by calling add_filter:

    use TAP::Filter;
    TAP::Filter->add_filter( 'MyFilter' );
    TAP::Filter->add_filter( 'OtherFilter' );
    my $harness = TAP::Filter->new;

Multiple filters may be loaded with a single call to add_filter:

    TAP::Filter->add_filter( 'MyFilter', 'OtherFilter' );

You may also pass a reference to a filter instance:

    my $my_filter = TAP::Filter::MyFilter->new;
    TAP::Filter->add_filter( $my_filter );

Filter scope

TAP::Filter maintains a single, global list of installed filters. Once loaded filters can not be removed. If either of these features proves problematic let me know and I'll consider alternatives.

INTERFACE

add_filter

Add one or more filters to TAP::Filter's filter chain. Each argument to add_filter may be either

• a partial class name

• a complete class name

• a filter instance

If the filter's class name begins with TAP::Filter:: it is only necessary to supply the trailing portion of the name:

    # Looks for TAP::Filter::Foo::Bar then plain Foo::Bar
    TAP::Filter->add_filter( 'Foo::Bar' );

get_filters

Returns a list of currently installed filters. Each item in the list will be a reference to an instantiated filter - even if the corresponding filter was specified by class name.

make_parser

Subclassed from TAP::Harness. Create a new TAP::Parser and install any registered filters in its TAP processing pipeline.

Study the implementation of make_parser if you need to implement an alternative filter loading scheme.

ok

A convenience method for creating new test results to inject into the TAP stream.

    my $result = TAP::Filter->ok(
        ok          => 1,          # test passed
        description => 'A test',
    );

The returned result is an instance of TAP::Parser::Result suitable for feeding into the TAP stream. See TAP::Filter::Iterator for more information about manipulating the TAP stream.

The arguments to ok are a number of key, value pairs. The following keys are recognised:

ok

Boolean. Whether the test passed.

description

The textual description of the test.

directive

A TODO or SKIP directive.

explanation

Text explaining why the test is a skip or todo.

CONFIGURATION AND ENVIRONMENT

TAP::Filter requires no configuration files or environment variables.

DEPENDENCIES

TAP::Filter requires Test::Harness version 3.11 or later.

INCOMPATIBILITIES

None reported.

BUGS AND LIMITATIONS

No bugs have been reported.

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

AUTHOR

Andy Armstrong <andy.armstrong@messagesystems.com>

LICENCE AND COPYRIGHT

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

Copyright (c) 2008, Message Systems, Inc. All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

    * Redistributions of source code must retain the above copyright
      notice, this list of conditions and the following disclaimer.
    * Redistributions in binary form must reproduce the above copyright
      notice, this list of conditions and the following disclaimer in
      the documentation and/or other materials provided with the
      distribution.
    * Neither the name Message Systems, Inc. nor the names of its
      contributors may be used to endorse or promote products derived
      from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

cpanm TAP::Filter

perl -MCPAN -e shell
install TAP::Filter