---
name: "Test2::Harness::Log::CoverageAggregator"
section: "3pm"
platform: "linux"
package: "libtest2-harness-perl"
version: "1.000158-1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Test2::Harness::Log::CoverageAggregator"
---

# Test2::Harness::Log::CoverageAggregator(3pm)

Module for aggregating coverage data from a stream of events.

## 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/*