NAME

Test::Bulder::Stream - The stream between Test::Builder and the formatters.

TEST COMPONENT MAP

  [Test Script] > [Test Tool] > [Test::Builder] > [Test::Bulder::Stream] > [Result Formatter]
                                                             ^
                                                       You are here

A test script uses a test tool such as Test::More, which uses Test::Builder to produce results. The results are sent to Test::Builder::Stream which then forwards them on to one or more formatters. The default formatter is Test::Builder::Fromatter::TAP which produces TAP output.

DESCRIPTION

This module is responsible for taking result object from Test::Builder and forwarding them to the listeners/formatters. It also has facilities for intercepting the results and munging them. Examples of this are forking support and Test::Tester2.

METHODS

CONSTRUCTION/FETCHING

It is possible to construct an independant stream object using new(). Most of the time however you do not want an independant stream, you want the shared stream. The shared stream is the stream to which all test output should be sent. The shared stream is actually a stack, and the topmost stream should always be used unless you really know what you are doing.

$stream = $class->new();

$stream = $class->new(use_tap => 1);

$stream = $class->new(use_lresults => 1);

$stream = $class->new(no_follow => 1);

Create a new/independant stream object. No listeners by default, but you can specify 'use_tap' and/or 'use_lresults' to add those listeners.

no_follow will disable the legacy behavior of exiting on bailout, or when a skip_all plan is encountered.

$stream = $class->shared()

Get the topmost stream on the shared stream stack.

$stream = $class->root()

Get the bottom-most stream in the shared stack.

$class->clear()

Remove all streams from the shared stack.

$stream->intercept(sub { ... })

Push a new stream onto the stack, run the specified code, then pop the new stream off of the stack.

$stream->intercept_start()

$stream->intercept_start($stream)

Push a new stream onto the top of the shared stack. Returns the $stream that was pushed. Optionally you can provide a stream to push instead of letting it make a new one for you.

$stream->intercept_stop($stream)

Pop the topmost stream. You must pass in the stream you expect to be popped. If the stream you pass in does not match the one popped an exception will be thrown.

$child = $stream->spawn()

$child = $stream->spawn(no_tap => 1)

$child = $stream->spawn(no_lresults => 1)

Spawn a cloned stream. The clone will have all the same listeners and mungers as the parent. Removing a listener from the parent will be reflected in the child, but the reverse is not true.

TAP and legacy results are special, so they are also cloned instead of carrying them over. Removing them from the parent will not remove them from the child.

ACCESSORS

$plan = $stream->plan()

$stream->plan($plan)

$stream->plan(undef)

Get/Set the plan, usually done for you when a plan object is encountered.

$pid = $stream->pid()

Get the original PID in which the stream object was built.

$num = $stream->tests_run()

$stream->tests_run($delta)

Get the number of tests run. Optionally you can provide a delta, the number of tests run will be adjusted by the delta.

$stream->tests_failed($delta)

Get the number of tests failed. Optionally you can provide a delta, the number of tests failed will be adjusted by the delta.

$bool = $stream->is_passing()

$stream->is_padding($bool)

Check if tests are passing, optinally you can pass in a $bool to reset this.

BEHAVIOR CONTROL

$bool = $stream->no_ending()

$stream->no_ending($bool)

enable/disable endings. Defaults to false.

$action = $stream->follow_up('Test::Builder::Result::...')

$stream->follow_up('Test::Builder::Result::...' => sub { ($r) = @_; ... })

Fetch or Specify a followup behavior to run after all listeners have gotten a result of the specified type.

$stream->legacy_followup

switch to legacy follow-up behavior. This means exiting for bailout or skip_all.

$stream->exception_followup

Switch to exception follow-up behavior. This means throwing an exception on bailout or skip_all. This is necessary for intercepting results.

$fork_handler = $stream->fork

Get the fork handler.

$stream->use_fork

Enable forking

$stream->no_fork

Disable forking.

PLANNING

$count = $stream->expected_tests

Get the expected number of tests, if any.

LISTENER CONTROL

NORMAL LISTENERS

$L = $stream->listener($id)

Get the listener with the given ID.

$unlisten = $stream->listen($id, $listener)

Add a listener with the given ID. The listener can either be a coderef that takes a result object as an argument, or any object that implements a handle() method.

This method returns a coderef that can be used to remove the listener. It is better to use this method over unlisten as it will remove the listener from the original stream object and any child stream objects.

$stream->unlisten($id)

Remove a listener by id.

LEGACY TAP LISTENER

$L = $stream->tap

Get the tap listener object (if TAP is enabled)

$stream->use_tap

Enable the legacy tap listener.

$stream->no_tap

Disable the legacy tap listener.

LEGACY RESULTS LISTENER

$L = $stream->lresults

Get the Legacy Result lsitener object.

$stream->use_lresults

Enable legacy results

$stream->no_lresults

Disable legacy results

MUNGING RESULTS

Mungers are expected to take a result object and return 1 or more result objects to replace the original. They are also allowed to simply modify the original, or return nothing to remove it.

Mungers are run in the order they are added, it is possible that the first munger will remove a result in which case later mungers will never see it. Listeners get the product of running all the mungers on the original results.

$M = $stream->munger($id)

Get the munger with the specified ID.

$unmunge = $stream->munge($id => $munger)

Add a munger. The munger may be a coderef that takes a single result object as an argument, or it can be any object that implements a handle() method.

This method returns a coderef that can be used to remove the munger. It is better to use this method over unmunge as it will remove the munger from the original stream object and any child stream objects.

$stream->unmunge($id)

Remove a munger by id.

PROVIDING RESULTS

$stream->send($result)

Send a result to all listeners (also goes through munging and the form handler, etc.)

AUTHORS

Chad Granum <exodist@cpan.org>

SOURCE

The source code repository for Test::More can be found at http://github.com/Test-More/test-more/.

COPYRIGHT

Copyright 2014 Chad Granum <exodist7@gmail.com>.

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

See http://www.perl.com/perl/misc/Artistic.html

cpanm Test::Simple

perl -MCPAN -e shell
install Test::Simple