NAME

Metrics::Any::Adapter::Test - a metrics reporting adapter for unit testing

SYNOPSIS

use Test2::V0;
use Metrics::Any::Adapter 'Test';

{
   Metrics::Any::Adapter::Test->clear;

   # perform some work in the code under test

   is( Metrics::Any::Adapter::Test->metrics,
      "an_expected_metric = 1\n",
      'Metrics were reported while doing something'
   );
}

DESCRIPTION

This Metrics::Any adapter type stores reported metrics locally, allowing access to them by the "metrics" method. This is useful to use in a unit test to check that the code under test reports the correct metrics.

This adapter supports timer metrics by storing as distributions. By default, distributions store only a summary, giving the count and total duration. If required, the full values can be stored by setting "use_full_distributions".

For predictable output of timer metrics in unit tests, a unit test may wish to use the "override_timer_duration" method.

This adapter type supports batch mode reporting. Callbacks are invoked at the beginning of the "metrics" method.

METHODS

metrics

$result = Metrics::Any::Adapter::Test->metrics

This class method returns a string describing all of the stored metric values. Each is reported on a line formatted as

name = value

Each line, including the final one, is terminated by a linefeed. The metrics are sorted alphabetically. Any multi-part metric names will be joined with underscores (_).

Metrics that have additional labels are formatted with additional label names and label values in declared order after the name and before the = symbol:

name l1:v1 l2:v2 = value

use_full_distributions

Metrics::Any::Adapter::Test->use_full_distributions;  # enables the option

Metrics::Any::Adapter::Test->use_full_distributions( $enable );

Since version 0.08.

If enabled, this option stores the full value of every reported observation into distributions, rathr than just the count-and-total summary.

Full value distributions will be formatted as a sequence of lines containing the count of observations at that particular value, in square brackets, followed by the summary count.

name[v1] = c1
name[v2] = c2
...
name_count = c

In order not to be too sensitive to numerical rounding errors, values are stored to only 3 decimal places.

clear

Metrics::Any::Adapter::Test->clear

This class method removes all of the stored values of reported metrics.

override_timer_duration

Metrics::Any::Adapter::Test->override_timer_duration( $duration )

This class method sets a duration value, that any subsequent call to inc_timer will use instead of the value the caller actually passed in. This will ensure reliably predictable output in unit tests.

Any value set here will be cleared by "clear".

AUTHOR

Paul Evans <leonerd@leonerd.org.uk>

cpanm Metrics::Any

perl -MCPAN -e shell
install Metrics::Any