NAME

       Test2::Harness::Auditor::TimeTracker - Module that tracks timing data while an event
       stream is processed.

DESCRIPTION

       The timetracker module tracks timing data of an event stream. All events for a given job
       should be run through a timetracker, which can then give data on how long the test took in
       each of several stages.

       startup - Time from launch to first test event.
       events - Time spent generating test events.
       cleanup - Time from last test event to test exit.
       total - Total time.

SYNOPSIS

           use Test2::Harness::Auditor::TimeTracker;

           my $tracker = Test2::Harness::Auditor::TimeTracker->new();

           my $assert_count = 0;
           for my $event (@events) {
               my $facet_data = $events->facet_data;
               $assert_count++ if $facet_data->{assert};
               $tracker->process($event, $facet_data, $assert_count);
           }

           print $tracker->summary;
           # Startup: 0.00708s | Events: 0.00000s | Cleanup: 0.10390s | Total: 0.11098s

METHODS

       $tracker->process($event, $facet_data, $assert_count)
       $tracker->process($event, undef, $assert_count)
           TimeTracker builds its state from multiple events, each event should be processed by
           this method.

           The second argument is optional, if no facet_data is provided it will pull the
           facet_data from the event itself. This is mainly a micro-optimization to avoid calling
           the "facet_data()" method on the event multiple times if you have already called it.

       $bool = $tracker->useful()
           Returns true if there is any useful data to display.

       $totals = $tracker->totals()
           Returns the totals like this:

               {
                   # Raw numbers
                   startup => ...,
                   events  => ...,
                   cleanup => ...,
                   total   => ...,

                   # Human friendly versions
                   h_startup => ...,
                   h_events  => ...,
                   h_cleanup => ...,
                   h_total   => ...,
               }

       $source = $tracker->source()
           This method returns the data from which the totals are derived.

               {
                   start => ...,    # timestamp of the job starting
                   stop  => ...,    # timestamp of the job ending
                   first => ...,    # timestamp of the first non-harness event
                   last  => ...,    # timestamp of the last non-harness event

                   # These are event_id's of the events that provided the above stamps.
                   start_id    => ...,
                   stop_id     => ...,
                   first_id    => ...,
                   last_id     => ...,
                   complete_id => ...,
               }

       $data = $tracker->data_dump
           This dumps the totals and source data:

               {
                   totals => $tracker->totals,
                   source => $tracker->source,
               }

       $string = $tracker->summary
           This produces a summary string of the totals data:

               Startup: 0.00708s | Events: 0.00000s | Cleanup: 0.10390s | Total: 0.11098s

           Fields that have no data will be ommited from the string.

       $table = $tracker->table
           Returns this structure that is good for use in Term::Table.

               {
                   header => ["Phase", "Time", "Raw", "Explanation"],
                   rows   => [
                       ['startup', $human_readible, $raw, "Time from launch to first test event."],
                       ['events',  $human_radible,  $raw, 'Time spent generating test events.'],
                       ['cleanup', $human_radible,  $raw, 'Time from last test event to test exit.'],
                       ['total',   $human_radible,  $raw, 'Total time.'],
                   ],
               }

       @items = $tracker->job_fields()
           This is used to obtain extra data to attach to the job completion event.

SOURCE

       The source code repository for Test2-Harness can be found at
       http://github.com/Test-More/Test2-Harness/.

MAINTAINERS

       Chad Granum <exodist@cpan.org>

AUTHORS

       Chad Granum <exodist@cpan.org>

COPYRIGHT

       Copyright 2020 Chad Granum <exodist7@gmail.com>.

       This program is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself.

       See http://dev.perl.org/licenses/