Curtis "Ovid" Poe > TAP-Stream-0.44 > TAP::Stream

Download:
TAP-Stream-0.44.tar.gz

Dependencies

Annotate this POD

Website

View/Report Bugs
Module Version: 0.44   Source  

NAME ^

TAP::Stream - Combine multiple TAP streams with subtests

VERSION ^

version 0.44

SYNOPSIS ^

    use TAP::Stream;
    use TAP::Stream::Text;

    my $tap1 = <<'END';
    ok 1 - foo 1
    ok 2 - foo 2
    1..2
    END

    # note that we have a failing test
    my $tap2 = <<'END';
    ok 1 - bar 1
    ok 2 - bar 2
        1..3
        ok 1 - bar subtest 1
        ok 2 - bar subtest 2
        not ok 3 - bar subtest 3 #TODO ignore
    ok 3 - bar subtest
    not ok 4 - bar 4
    1..4
    END

    my $stream = TAP::Stream->new;

    $stream->add_to_stream(
        TAP::Stream::Text->new( name => 'foo tests', text => $tap1 ),
        TAP::Stream::Text->new( name => 'bar tests', text => $tap2 )
    );

    print $stream->to_string;

Output:

        ok 1 - foo 1
        ok 2 - foo 2
        1..2
    ok 1 - foo tests
        ok 1 - bar 1
        ok 2 - bar 2
            1..3
            ok 1 - bar subtest 1
            ok 2 - bar subtest 2
            not ok 3 - bar subtest 3 #TODO ignore
        ok 3 - bar subtest
        not ok 4 - bar 4
        1..4
    not ok 2 - bar tests
    # Failed 1 out of 4 tests
    1..2

DESCRIPTION ^

Sometimes you find yourself needing to merge multiple streams of TAP. Several use cases:

TAP::Stream allows you to do this. You can both merge multiple chunks of TAP text, or even multiple TAP::Stream objects.

DESCRIPTION ^

Experimental module to combine multiple TAP streams.

METHODS ^

new

    my $stream = TAP::Stream->new( name => 'Parent stream' );

Creates a TAP::Stream object. The name is optional, but highly recommend to be unique. The top-level stream's name is not used, but if you use add_to_stream to add another stream object, that stream object should be named or else the summary (not) ok line will be named Unnamed TAP stream and this may make it harder to figure out which stream contained a failure.

Names should be descriptive of the use case of the stream.

name

    my $name = $stream->name;

A read/write string accessor.

Returns the name of the stream. Default to Unnamed TAP stream. If you add this stream to another stream, consider naming this stream for a more useful TAP output. This is used to create the subtest summary line:

        1..2
        ok 1 - some test
        ok 2 - another test
    ok 1 - this is $stream->name

add_to_stream

    $stream->add_to_stream(TAP::Stream::Text->new(%args));
    # or
    $stream->add_to_stream($another_stream);

Add a TAP::Stream::Text object or another TAP::Stream object. You may call this method multiple times. The following two chunks of code are the same:

    $stream->add_to_stream(
        TAP::Stream::Text->new( name => 'foo tests', text => $tap1 ),
        TAP::Stream::Text->new( name => 'bar tests', text => $tap2 )
    );

Versus:

    $stream->add_to_stream(
        TAP::Stream::Text->new( name => 'foo tests', text => $tap1 ),
    );
    $stream->add_to_stream(
        TAP::Stream::Text->new( name => 'bar tests', text => $tap2 )
    );

Stream objects can be added to other stream objects:

    my $parent = TAP::Stream->new; # the name is unused for the parent

    my $stream = TAP::Stream->new( name => 'child stream' );

    $stream->add_to_stream(
        TAP::Stream::Text->new( name => 'foo tests', text => $tap1 ),
        TAP::Stream::Text->new( name => 'bar tests', text => $tap2 )
    );
    $parent->add_to_stream($stream);

    # later:
    $parent->add_to_stream($another_stream);
    $parent->add_to_stream(TAP::Stream::Text->new%args);
    $parent->add_to_stream($yet_another_stream);

    say $parent->to_string;

to_string

    say $stream->to_string;

Prints the stream as TAP. We do not overload stringification.

HOW IT WORKS ^

Each chunk of TAP (or stream) that is added is added as a subtest. This avoids issues of trying to recalculate the numbers. This means that if you concatenate three TAP streams, each with 25 tests, you will still see 3 tests reported (because you have three subtests).

There is a mini-TAP parser within TAP::Stream. As you add a chunk of TAP or a stream, the parser analyzes the TAP and if there is a failure, the subtest itself will be reported as a failure. Causes of failure:

CAVEATS ^

AUTHOR ^

Curtis "Ovid" Poe <ovid@cpan.org>

COPYRIGHT AND LICENSE ^

This software is copyright (c) 2013 by Curtis "Ovid" Poe.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

syntax highlighting: