Test2:...regator(3pm)

📦
version 1.000172 · 8 versions
, in ubuntu stonking

💖 Test2::Harness::Log::CoverageAggregator — yeah that's the one, from Test2:...regator(3pm) bestie 💖

okay so like. this is a Perl module page, it's giving "User Contributed Perl Documentation", and we're about to get INTO it. grab a boba. 🧋

✨ NAME ✨

Test2::Harness::Log::CoverageAggregator — the module for aggregating coverage data from a stream of events. that's it. that's the whole job. she aggregates. 💅

🌸 DESCRIPTION 🌸

so basically: you give her a stream of events, and she hands you back aggregated coverage data. no cap, that's literally the entire premise. she eats events and produces coverage. an icon. an absolute queen of a data structure builder. 👑

🎀 SYNOPSIS 🎀

here's the vibe, copy-paste ready:

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;

like look at her. new, loop, process_event, then you just... ask for the goodies. touched and metrics. effortless. 💖

🦋 METHODS 🦋

💜 IMPLEMENTABLE IN SUBLCASSES 💜

bestie listen. if you implement these in a subclass, they get called for you at the proper times. that's the whole point — it makes subclassing SO much easier. and in most cases you can lowkey just avoid overriding process_event() entirely. she handles the plumbing, you handle the cute stuff. 🫶

  • $agg->start_test($test, $event) — called once per test, right when it starts.
⚠️ Note: if a test is run more than once (a re-run), it will start and stop again for each re-run. the event is also handed to you as an argument so you can check for a try-id or similar, y'know, in the event that re-runs matter to you. 🙈
  • $agg->stop_test($test, $event) — called once per test, right when it stops.
⚠️ Note: same deal — if a test is run more than once (re-run), it starts and stops again for each re-run. and again, the event is provided as an argument so you can look for a try-id or similar if re-runs matter to you. 💀
  • $agg->record_coverage($test, $coverage_data, $event) — called once per coverage event. and yes, there can be several in a single test, especially if it forks or uses threads. no cap, forking tests be like that.
🫶 lowkey in most cases you probably want to leave this one unimplemented and implement the touch() method instead, rather than iterating over the coverage structure yourself. let her do it. she's good at it.
  • $agg->touch(source => $file, sub => $sub, test => $test, manager_data => $mdata, event => $event) — every single touch applied to a source file (and sub) triggers this method call. every one. she does not skip. ✨
    • 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. snitch behaviour, but make it coverage. 🙈
    • 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. you gotta set that up yourself, bestie. 💅
    • event => $event — the full event being processed.

⭐ PUBLIC API ⭐

  • $agg->process_event($event) — process the event, aggregating any coverage info it may contain. the main character method, fr fr.
  • $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" respectively. iconic little sentinel values.
{
    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 begins with an underscore from the coverage metrics and untested sub list. bye bye private subs, you're not in the stats anymore. 🦋

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/. go look, go star, go read the source like the scholar you are. ⭐

👑 MAINTAINERS 👑

Chad Granum <exodist@cpan.org>

💖 AUTHORS 💖

Chad Granum <exodist@cpan.org>

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/

and that's the whole page bestie, we ATE. this came to you from perl v5.40.1, dated 2026-05-10, filed under Test2:...regator(3pm). periodt. 💅✨

📦 where this page comes from