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.

EventCoordinator methods

TestState delegates to a stack of EventCoordinators. It does all the methods of TB2::EventCoordinator.

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.

current_coordinator

    my $ec = $state->current_coordinator;

Returns the current TB2::EventCoordinator which is being delegated to.

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