TAP::Filter - Filter TAP stream within TAP::Harness
This document describes TAP::Filter version 0.04
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
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
TAP::Filter
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.
Filters may be installed into the TAP processing pipeline in a number of different ways...
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
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.
MyFilter
OtherFilter
TAP::Filter::
TAP::Filter::MyFilter
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.
TAP::Filter->add_filter
As an alternative to the concise filter loading notation above filters may be loaded by calling add_filter:
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 );
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.
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.
TAP::Harness
TAP::Parser
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:
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.
TAP::Filter requires no configuration files or environment variables.
TAP::Filter requires Test::Harness version 3.11 or later.
None reported.
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.
bug-tap-filter@rt.cpan.org
Andy Armstrong <andy.armstrong@messagesystems.com>
<andy.armstrong@messagesystems.com>
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.
To install TAP::Filter, copy and paste the appropriate command in to your terminal.
cpanm
cpanm TAP::Filter
CPAN shell
perl -MCPAN -e shell install TAP::Filter
For more information on module installation, please visit the detailed CPAN module installation guide.