README
1NAME
2
3 Test::Metrics::Any - assert that code produces metrics via Metrics::Any
4
5SYNOPSIS
6
7 use Test::More;
8 use Test::Metrics::Any;
9
10 use Module::Under::Test;
11
12 is_metrics_from(
13 sub { Module::Under::Test::do_a_thing for 1 .. 5 },
14 {
15 things_done => 5,
16 time_taken => Test::Metrics::Any::positive,
17 },
18 'do_a_thing reported some metrics'
19 );
20
21 done_testing;
22
23DESCRIPTION
24
25 This test module helps write unit tests which assert that the code
26 under test reports metrics via Metrics::Any.
27
28 Loading this module automatically sets the Metrics::Any::Adapter type
29 to Test.
30
31FUNCTIONS
32
33 is_metrics
34
35 is_metrics( \%metrics, $name )
36
37 Asserts that the current value of every metric named in the given hash
38 reference is set to the value provided. Values can either be given as
39 exact numbers, or by one of the match functions mentioned in
40 "PREDICATES".
41
42 Key names in the given hash should match the name format used by
43 Metrics::Any::Adapter::Test. Name components are joined by underscores,
44 and any label tags are appended with spaces, as name:value.
45
46 {
47 "a_basic_metric" => 123,
48 "a_labelled_metric label:here" => 456,
49 }
50
51 This function only checks the values of metrics actually mentioned in
52 the hash given as its argument. It is not a failure for more metrics to
53 have been reported by the code under test than are mentioned in the
54 hash. This helps to ensure that new metrics added in code do not break
55 existing tests that weren't set up to expect them.
56
57 is_metrics_from
58
59 is_metrics_from( $code, \%metrics, $name )
60
61 Asserts the value of metrics reported by running the given piece of
62 code.
63
64 The metrics in the test adapter are cleared, then the code is invoked,
65 then any metrics are checked in the same manner as "is_metrics".
66
67PREDICATES
68
69 As an alternative to expecting exact values for metrics, the following
70 test functions can be provided instead to assert that the metric is
71 behaving sensibly without needing to be an exact value. This could be
72 useful for example when the exact number of bytes or timing measures
73 can vary between test runs or platforms.
74
75 These predicates are not exported but must be invoked fully-qualified.
76
77 positive
78
79 metric => Test::Metrics::Any::positive
80
81 Asserts that the number is greater than zero. It must not be zero.
82
83 at_least
84
85 metric => Test::Metrics::Any::at_least( $n )
86
87 Asserts that the number at least that given - it can be equal or
88 greater.
89
90 greater_than
91
92 metric => Test::Metrics::Any::greater_than( $n )
93
94 Asserts that the number is greater than that given - it must not be
95 equal.
96
97AUTHOR
98
99 Paul Evans <leonerd@leonerd.org.uk>
100
101