DOKK / manpages / debian 12 / libtest2-harness-perl / Test2::Harness::Log::CoverageAggregator.3pm.en
Test2::Harness::Log::CoverageAggregator(3pm) User Contributed Perl Documentation Test2::Harness::Log::CoverageAggregator(3pm)

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

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

    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;

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.
The source file that was touched
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.
The test file that did the touching.
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.
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,
                ...
            }
        },
    }

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

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/

2023-03-12 perl v5.36.0