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.