NAME

Test::Builder2::EventCoordinator - Coordinate events amongst the builders

SYNOPSIS

# A builder gets and stores a copy of the singleton
use Test::Builder2::EventCoordinator;
my $ec = Test::Builder2::EventCoordinator->singleton;

# The builder sends it events like assert results and the beginning
# and end of test streams.
$ec->post_result($result);  # special case for results
$ec->post_event($event);

# The EventCoordinator comes with History and the default Formatter,
# but they can be replaced or added to.  You can also add watchers of
# your own devising.
$events->add_formatters($formatter);
$events->add_watcher($watcher);

DESCRIPTION

Test::Builder2 is a federated system of test formatters and assert generators. This lets people make new and interesting ways to write tests and format the results while keeping them coordianted. The EventCoordiantor is responsible for that coordination.

Each thing that generates events, usually something that causes asserts, will report them to the EventCoordinator. This in turn reports them to things like History and result Formatters and whatever else you want to watch events.

METHODS

Attributes

These are attributes which can be set and gotten through a method of the same name. They can also be passed into new.

history

The History object which is listening to events.

This is a special case of watchers provided so you can distinguish between formatters and other watchers.

Defaults to [ Test::Builder2::History->new ].

Unlike other watchers, there is only one history.

formatters

An array ref of Formatter objects which are listening to events.

This is a special case of watchers provided so you can distinguish between formatters and other watchers.

Defaults to [ Test::Builder2::Formatter::TAP->new ].

early_watchers

An array ref of any additional objects which are listening to events. They all must do the Test::Builder2::EventWatcher role (or have equivalent methods).

early_watchers are called first before any other watchers. This lets them manipulate the result before a formatter can act on it.

By default there are no early_watchers.

late_watchers

An array ref of any additional objects which are listening to events. They all must do the Test::Builder2::EventWatcher role (or have equivalent methods).

late_watchers are called last after all other watchers. This lets them see the result after any manipulations.

By default there are no late_watchers.

Constructors

These are methods which create or retrieve EventCoordinator objects.

singleton

my $ec = Test::Builder2::EventCoordinator->singleton;

Returns the default EventCoordinator. If you want to be hooked into the state of the globally active test, use this.

It will contain the History and Formatter singletons.

create

my $ec = Test::Builder2::EventCoordinator->create(%args);

Creates a new EventCoordinator.

%args corresponds to the Attributes.

Methods

post_result

$ec->post_result($result);

This is a special case of post_event for assert results.

post_event

$ec->post_event($event);

The $ec will hand the $event around to all its watchers, along with itself. See all_watchers for ordering information.

all_watchers

my @watchers = $ec->all_watchers;

Returns a list of all watchers in the order they will be passed events.

The order is early_watchers, history, formatters, late_watchers.

add_early_watchers

add_formatters

add_late_watchers

$ec->add_early_watchers($watcher1, $watcher2, ...);

Adds new watchers to their respective types.

Use this instead of manipulating the list of watchers directly.

clear_early_watchers

clear_formatters

clear_late_watchers

$ec->clear_early_watchers;

Removes all watchers of their respective types.