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/