/ 
App-Prove-Plugin-Metrics-0.0.1
/ App::Prove::Plugin::Metrics

NAME

App::Prove::Plugin::Metrics - Emit metrics when running prove

VERSION

Version 0.0.1

SYNOPSIS

prove -PMetrics [options] [files or directories]

DESCRIPTION

This module provides a plugin that emits pass-rate metrics from Perl unit tests executed with the `prove` testing tool.

CONFIGURATION

General Options

The plugin can be configured by passing a mode (see below) and a number of key/value options:

-PMetrics=(mode,options),key,value,...

Supported configuration options and their defaults are:

prefix,PREFIX
sep,.
subdepth,.
label,0
allowed,-._/A-Za-z0-9
rollup,0

A metric name is constructed from: The prefix, the test filename, the subtest path, the label. These options control the naming of metrics:

prefix

The prefix to use when constructing any metric name. If empty, the prefix will be omitted.

sep

The separator character used to join the components of the metric name.

subdepth

The maximum number of subtest names to include in the metric name. If subtests are nested beyond this value, they will be interpreted as results at the configured maximum depth, aggregated with a Boolean AND.

If subdepth=0, no subtest paths will be included in the metric name. If subdepth<0, the depth will not be limited.

label

The assertion label will be included in the metric name when label=1.

allowed

The character class of characters that may appear in the final metric name. All other characters will be removed.

rollup

If rollup=1, the metric value will be the percentage of passing tests at that metric name (0 to 1 inclusive). When rollup=0, the default, the metric value will be a Boolean pass/fail value (0 or 1).

File Output

The default output mechanism for test metrics is a plain file. The plugin can be configured as:

-PMetrics=file,key,value,...

The following options are available in file-output mode:

outfile

The output filename.

format

Not yet available.

Module Output

Metrics may be emitted via a separate module:

-PMetrics=module,name,key,value,...

The module must provide a save function that will be called when metrics are emitted, and may optionally provide a stored configuration in configureHarness, as in this example:

package CustomMetrics;
use Data::Dumper;

sub configureHarness {
  return (
    prefix  =>'ORG.TEST.UNIT',
    subdepth=>2,
    label   =>0,
  );
}

sub save {
  my (%metrics)=@_;
  foreach my $name (keys %metrics) {
    print "$metrics{$name} $name\n";
  }
}

BUGS

The plugin assumes that prove is running with the standard console output formatter.

SEE ALSO

TAP::Harness::Metrics

TAP::Parser::Metrics

AUTHORS

Brian Blackmore (brian@mediaalpha.com).

COPYRIGHT

Copyright (c) 2025--2035, MediaAlpha.com.

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Library General Public License Version 3 as published by the Free Software Foundation.