NAME
TB2::History - Holds information about the state of the test
SYNOPSIS
use TB2::History;
# An EventCoordinator contains a History object by default
my $ec = TB2::EventCoordinator->create();
my $pass = TB2::Result->new_result( pass => 1 );
$ec->post_event( $pass );
$ec->history->can_succeed; # true
my $result = TB2::Result->new_result( pass => 0 );
$ec->post_event( $pass );
$ec->history->can_succeed; # falseDESCRIPTION
TB2::History records information and statistics about the state of the test. It watches and analyses events as they happen. It is used to get information about the state of the test such as has it started, has it ended, is it passing, how many tests have run and so on.
The history for a test is usually accessed by going through the TB2::TestState history accessor.
To save memory it does not, by default, store the complete history of all events.
Each subtest gets its own TB2::EventCoordinator and thus its own TB2::History object.
It is a TB2::EventHandler.
METHODS
Constructors
new
my $history = TB2::History->new;Creates a new, unique History object.
new() takes the following options.
store_events
If true, $history will keep a complete record of all test events accessible via events and results. This will cause memory usage to grow over the life of the test.
If false, $history will discard events and only keep a summary of events. events and results will throw an exception if called.
Defaults to false, events are not stored by default.
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
Accessors
Unless otherwise stated, these are all accessor methods of the form:
my $value = $history->method; # get
$history->method($value); # setEvents
events
my $events = $history->events;An array ref of all events seen.
By default, no events are stored and this will throw an exception unless $history->store_events is true.
last_event
my $event = $history->last_event;Returns the last event seen.
Results
results
# The result of test #4.
my $result = $history->results->[3];Returns a list of all TB2::Result objects seen in this test.
By default, no results are stored and this will throw an exception unless $history->store_events is true.
has_results
Returns true if we have stored results, false otherwise.
last_result
my $result = $history->last_result;Returns the last result seen.
Statistics
event_count
A count of number of events that have been seen.
result_count
A count of the number of results which have been seen.
pass_count
A count of the number of passed tests seen.
That is any result for which is_pass is true.
fail_count
A count of the number of failed tests seen.
That is any result for which is_fail is true.
todo_count
A count of the number of TODO tests seen.
That is any result for which is_todo is true.
skip_count
A count of the number of SKIP tests seen.
That is any result for which is_skip is true.
can_succeed
Returns true if the test can still succeed. That is, if nothing yet has happened to cause it to fail and the plan can be fulfilled.
For example, running too few tests is ok, but if too many have been run the test can never succeed.
In another example, if there is no plan yet issued, there is no plan to violate.
test_was_successful
my $test_passed = $history->test_was_successful;This returns true if the test is considered successful, false otherwise.
The conditions for a test passing are...
* test_start, set_plan and test_end events were seen * the plan is satisfied (the right number of Results were seen) * no Results were seen out of order according to their test_number * For every Result, is_fail() is false * If asked at END time, the test process is exiting with 0
Note that this will not be true until test_end has been seen. Until then, use can_succeed.
in_test
my $am_in_test = $history->in_test;Returns true if we're in the middle of a test, that is a test_start event was seen but a test_end event has not.
done_testing
my $testing_is_done = $history->done_testing;Returns true if testing was started and it is done. That is, both a test_start and a test_end event has been seen.
counter
my $counter = $formatter->counter;
$formatter->counter($counter);Gets/sets the result counter. This is usually the number of results seen, but it is not guaranteed to be so. It can be reset.
plan
my $plan = $history->plan;Returns the plan event for the current test, if any.
test_start
my $test_start = $history->test_start;Returns the test_start event, if it has been seen.
test_end
my $test_end = $history->test_end;Returns the test_end event, if it has been seen.
subtest
my $subtest = $history->subtest;Returns the current subtest event for this object, if there is one.
is_subtest
my $is_subtest = $history->is_subtest;Returns whether this $history represents a subtest.
subtest_depth
my $depth = $history->subtest_depth;Returns how deep in subtests the current test is.
The top level test has a depth of 0. The first subtest is 1, the next nested is 2 and so on.
subtest_start
my $subtest_start = $history->subtest_start;Returns the subtest_start event, if it has been seen.
This is the event for the subtest about to start or which has just ended. It is not the event for the current subtest.
abort
my $abort = $history->abort;Returns the last abort event seen, if any.
pid_at_test_start
my $process_id = $history->pid_at_test_start;History records the $process_id at the time the test has started.
is_child_process
my $is_child = $history->is_child_process;Returns true if the current process is a child of the process which started the test.
HISTORY INTERACTION
consume
$history->consume($old_history);Appends $old_history results in to $history's results stack.