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 );
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 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...
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,
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
If you are writing a program that uses TAP::Harness you can load filters by replacing
use TAP::Harness; my $harness = TAP::Harness->new;
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.
As an alternative to the concise filter loading notation above filters may be loaded by calling
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
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
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' );
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.
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.
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 arguments to
ok are a number of key, value pairs. The following keys are recognised:
Boolean. Whether the test passed.
The textual description of the test.
A TODO or SKIP directive.
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.
No bugs have been reported.
Please report any bugs or feature requests to
email@example.com, or through the web interface at http://rt.cpan.org.
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.