NAME

       Test2::Harness::Log::CoverageAggregator - Module for aggregating coverage data from a
       stream of events.

DESCRIPTION

       This module takes a stream of events and produces aggregated coverage data.

SYNOPSIS

           use Test2::Harness::Log::CoverageAggregator;

           my $agg = Test2::Harness::Log::CoverageAggregator->new();

           while (my $e = $log->next_event) {
               $agg->process_event($e);
           }

           # Get a structure like { source_file => { source_method => $touched_count, ... }, ...}
           my $touched_source = $agg->touched;

           # Get a structure like
           # {
           #     files => {total => 5,  tested => 2},
           #     subs  => {total => 20, tested => 12},
           #     untested => {files => \@file_list, subs => {file => \@sub_list, ...}},
           # }
           my $metrics = $agg->metrics;

METHODS

   IMPLEMENTABLE IN SUBLCASSES
       If you implement these in a subclass they will be called for you at the proper times,
       making subclassing much easier. In most cases you can avoid overriding process_event().

       $agg->start_test($test, $event)
           This is called once per test when it starts.

           Note: If a test is run more than once (re-run) it will start and stop again for each
           re-run. The event is also provided as an argument so that you can check for a try-id
           or similar in the event that re-runs matter to you.

       $agg->stop_test($test, $event)
           This is called once per test when it stops.

           Note: If a test is run more than once (re-run) it will start and stop again for each
           re-run. The event is also provided as an argument so that you can check for a try-id
           or similar in the event that re-runs matter to you.

       $agg->record_coverage($test, $coverage_data, $event)
           This is called once per coverage event (there can be several in a test, specially if
           it forks or uses threads).

           In most cases you probably want to leave this unimplemented and implement the
           "touch()" method instead of iterating over the coverage structure yourself.

       $agg->touch(source => $file, sub => $sub, test => $test, manager_data => $mdata, event =>
       $event)
           Every touch applied to a source file (and sub) will trigger this method call.

           source => $file
               The source file that was touched

           sub => $sub
               The source subroutine that was touched. Note: This may be '<>' if the source file
               was opened via "open()" or '*' if code outside of a subroutine was executed by the
               test.

           test => $test
               The test file that did the touching.

           manager_data => $mdata
               If the test file makes use of a source manager to attach extra data to coverage,
               this is where that data will be. A good example would be test suites that use
               tools similar to Test::Class or Test::Class::Moose where all tests are run in
               methods and you want to track what test method does the touching. Please note that
               this level of coverage tracking is not automatic.

           event => $event
               The full event being processed.

   PUBLIC API
       $agg->process_event($event)
           Process the event, aggregating any coverage info it may contain.

       $touched = $add->touched()
           Returns the following structure, which tells you how many times a specific source
           file's subroutines were called. There are also "special" subroutines '<>' and '*'
           which mean "file was opened via open" and "code outside of a subroutine".

               {
                   source_file => {
                       source_method => $touched_count,
                       ...
                   },
                   ...
               }

       $metrics = $agg->build_metrics()
       $metrics = $agg->build_metrics(exclude_private => $BOOL)
           Will build metrics, and include them in the output from "$agg->coverage()" next time
           it is called.

           The "exclude_private" option, when set to true, will exclude any method that beings
           with an underscore from the coverage metrics and untested sub list.

           Metrics:

               {
                   files => {total => 20, tested => 18},
                   subs  => {total => 80, tested => 70},

                   untested => {
                       files => \@file_list,
                       subs => {
                           file => \@sub_list,
                           ...
                       }
                   },
               }

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/

perl v5.36.0                                2023-10-0Test2::Harness::Log::CoverageAggregator(3pm)