NAME

TB2::TestState - Object which holds the state of the test

SYNOPSIS

    use TB2::TestState;

    # Get the state of the default test.
    # Usually you'd ask your builder for the TestState object,
    # but we'll get it directly.
    my $state = TB2::TestState->default;

    # Post an event, like an EventCoordinator
    $state->post_event($event);

    # Get the history of the test
    my $history = $state->history;

DESCRIPTION

All test state resides not in the builder objects but in the TestState and its attached TB2::EventHandler objects. TestState holds onto the current event handlers and passes events along to them. It also manages subtest state.

For example, when a builder has generated a Result object, it should post it to the TestState.

    $state->post_event($result);

TestState does everything a TB2::EventCoordinator does. It delegates to a stack of EventCoordinators, one for each layer of subtesting.

TestState has a default object to hold the state of the default test. Builders should use TB2::TestState->default to get the TestState if they want to play nice with others. You can also create your own test states with <TB2::TestState-create >>.

METHODS

Constructors

Because TestState is a default, it does not provide a new to avoid confusion. It instead has create and default.

create

    my $state = TB2::TestState->create(%event_coordinator_args);

Create a new test state.

%event_coordinator_args are passed to the constructor when it creates new event coordinators. This lets you pass in different formatters and handlers.

    # Make a test state with no formatter
    my $state = TB2::TestState->create(
        formatters => []
    );

default

    my $state = TB2::TestState->default;

Retrieve the shared TestState.

You should use this if you want to coordinate with other test libraries.

Misc

object_id

    my $id = $thing->object_id;

Returns an identifier for this object unique to the running process. The identifier is fairly simple and easily predictable.

See TB2::HasObjectID for details.

EventCoordinator methods

TestState contains a stack of TB2::EventCoordinator objects and delegates most of the work to the first event coordinator in the stack.

The following TB2::EventCoordinator methods can be called on a TB2::TestState object and work exactly the same.

post_event

history

formatters

early_handlers

late_handlers

all_handlers

add_early_handlers

add_formatters

add_late_handlers

clear_early_handlers

clear_formatters

clear_late_handlers

Stack management

TestState maintains state in a stack of EventCoordinators. Each item in the stack is isolated from another (unless they decide to share EventHandlers).

One can add a coordinator to the stack to set up an isolated test state and remove it to restore the original state. This is useful both for testing tests (see TB2::Tester) and for running subtests in isolation.

push_coordinator

    my $event_coordinator = $state->push_coordinator;
    my $event_coordinator = $state->push_coordinator($event_coordinator);

Add an $event_coordinator to the stack. This will become the new delegate.

If an $event_coordinator is not passed in, a new one will be made using the arguments originally passed into create.

pop_coordinator

    my $event_coordinator = $state->pop_coordinator;

This will remove the current coordinator from the stack. Test state will be delegated to the coordinator below it.

An exception will be thrown if the final coordinator is attempted to be removed.

ec

    my $ec = $state->ec;

Returns the TB2::EventCoordinator which is currently in control of the test.

DO NOT store this object! The event coordinator in control of the test can change over the course of the test.

SEE ALSO

TB2::EventCoordinator which TestState delegates to under the hood.

TB2::EventHandler which handle events.

TB2::Formatter which handle output.

TB2::History which stores events for reference.

cpanm Test::Simple

perl -MCPAN -e shell
install Test::Simple