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
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.