blib/lib/Test/Metrics/Any.pm

filter: Statementstmt 100% 62 / 62 Branchbran 100% 8 / 8 Conditioncond n/a MC/DCmcdc n/a Subroutinesub 100% 19 / 19 Podpod 83.3% 5 / 6 totaltotal 98.9% 94 / 95 CC 6 SCAR 8.1
CC
6
Cov
100%
is_metrics
6.0
BEGIN
1.0
BEGIN
1.0
CRAP 2.2
↑ Summary
1 # You may distribute under the terms of either the GNU General Public License
2 # or the Artistic License (the same terms as Perl itself)
3 #
4 # (C) Paul Evans, 2020-2026 -- leonerd@leonerd.org.uk
5  
6 package Test::Metrics::Any 0.02;
7  
8 3 ▶use v5.20;
Subroutine BEGIN: called CC=1 SCAR=0.0
9 3 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
10 3 ▶use base qw( Test::Builder::Module );
Subroutine BEGIN: called CC=1 SCAR=0.0
11  
12 3 ▶use feature qw( signatures );
Subroutine BEGIN: called CC=1 SCAR=0.0
13 3 ▶no warnings qw( experimental::signatures );
Subroutine BEGIN: called CC=1 SCAR=0.0
14  
15 3 ▶use Metrics::Any::Adapter 'Test';
Subroutine BEGIN: called CC=1 SCAR=0.0
16 3 ▶use Metrics::Any::Adapter::Test; # Eager load
Subroutine BEGIN: called CC=1 SCAR=0.0
17  
18 3 our @EXPORT = qw(
19 is_metrics
20 is_metrics_from
21 );
22  
23 =head1 NAME
24  
25 C<Test::Metrics::Any> - assert that code produces metrics via L<Metrics::Any>
26  
27 =head1 SYNOPSIS
28  
29 =for highlighter language=perl
30  
31 use Test::More;
32 use Test::Metrics::Any;
33  
34 use Module::Under::Test;
35  
36 is_metrics_from(
37 sub { Module::Under::Test::do_a_thing for 1 .. 5 },
38 {
39 things_done => 5,
40 time_taken => Test::Metrics::Any::positive,
41 },
42 'do_a_thing reported some metrics'
43 );
44  
45 done_testing;
46  
47 =head1 DESCRIPTION
48  
49 This test module helps write unit tests which assert that the code under test
50 reports metrics via L<Metrics::Any>.
51  
52 Loading this module automatically sets the L<Metrics::Any::Adapter> type to
53 C<Test>.
54  
55 =cut
56  
57 =head1 FUNCTIONS
58  
59 =cut
60  
61 =head2 is_metrics
62  
63 is_metrics( \%metrics, $name );
64  
65 Asserts that the current value of every metric named in the given hash
66 reference is set to the value provided. Values can either be given as exact
67 numbers, or by one of the match functions mentioned in L</PREDICATES>.
68  
69 Key names in the given hash should match the name format used by
70 L<Metrics::Any::Adapter::Test>. Name components are joined by underscores, and
71 any label tags are appended with spaces, as C<name:value>.
72  
73 {
74 "a_basic_metric" => 123,
75 "a_labelled_metric label:here" => 456,
76 }
77  
78 This function only checks the values of metrics actually mentioned in the hash
79 given as its argument. It is not a failure for more metrics to have been
80 reported by the code under test than are mentioned in the hash. This helps to
81 ensure that new metrics added in code do not break existing tests that weren't
82 set up to expect them.
83  
84 =cut
85  
86 9 ▶sub is_metrics ( $expect, $testname )
Subroutine is_metrics: called CC=6 SCAR=17.9
Pod documented
87 {
88 9 my $tb = __PACKAGE__->builder;
89  
90 9 my %got = map { ( split m/\s*=\s*/, $_ )[0,1] } split m/\n/, Metrics::Any::Adapter::Test->metrics;
91  
92 9 foreach my $name ( sort keys %$expect ) {
93 9 my $expectval = $expect->{$name};
94  
95 9 my $gotval = $got{$name};
96 9 ▶ unless( defined $gotval ) {
Branch: 1 branch
BranchTrueFalseTotal
unless (defined $gotval) 1 8 9
97 1 my $ret = $tb->ok( 0, $testname );
98 1 $tb->diag( "Expected a metric called '$name' but didn't find one" );
99 1 return $ret;
100 }
101  
102 8 ▶ if( ref $expectval eq "Test::Metrics::Any::_predicate" ) {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $expectval eq 'Test::Metrics::Any::_predicate') { } 6 2 8
103 6 ▶ unless( $expectval->check( $gotval ) ) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($expectval->check($gotval)) 3 3 6
104 3 my $ret = $tb->ok( 0, $testname );
105 3 $tb->diag( "Expected metric '$name' to be ${\$expectval->message} but got $gotval" );
106 3 return $ret;
107 }
108 }
109 else {
110 2 ▶ unless( $gotval == $expectval ) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($gotval == $expectval) 1 1 2
111 1 my $ret = $tb->ok( 0, $testname );
112 1 $tb->diag( "Expected metric '$name' to be $expectval but got $gotval" );
113 1 return $ret;
114 }
115 }
116 }
117  
118 4 return $tb->ok( 1, $testname );
119 }
120  
121 =head2 is_metrics_from
122  
123 is_metrics_from( $code, \%metrics, $name );
124  
125 Asserts the value of metrics reported by running the given piece of code.
126  
127 The metrics in the test adapter are cleared, then the code is invoked, then
128 any metrics are checked in the same manner as L</is_metrics>.
129  
130 =cut
131  
132 # mixing prototype and signature is awkward before 5.28
133 {
134 3 ▶ no feature 'signatures';
Subroutine BEGIN: called CC=1 SCAR=0.0
135  
136 sub is_metrics_from(&@)
137 9 ▶ {
Subroutine is_metrics_from: called CC=1 SCAR=0.0
Pod documented
138 9 my ( $code, $expect, $testname ) = @_;
139 9 Metrics::Any::Adapter::Test->clear;
140  
141 9 $code->();
142  
143 9 local $Test::Builder::Level = $Test::Builder::Level + 1;
144 9 return is_metrics( $expect, $testname );
145 }
146 }
147  
148 =head1 PREDICATES
149  
150 As an alternative to expecting exact values for metrics, the following test
151 functions can be provided instead to assert that the metric is behaving
152 sensibly without needing to be an exact value. This could be useful for
153 example when the exact number of bytes or timing measures can vary between
154 test runs or platforms.
155  
156 These predicates are not exported but must be invoked fully-qualified.
157  
158 =cut
159  
160 3 ▶sub predicate ( $message, $checker )
Subroutine predicate: called CC=1 SCAR=0.0
Pod undocumented
161 {
162 6 return bless [ $message, $checker ], "Test::Metrics::Any::_predicate";
163 }
164 3 package Test::Metrics::Any::_predicate {
165 6 ▶ sub check ( $self, $value ) { $self->[1]->( $value ) }
Subroutine check: called CC=1 SCAR=0.0
166 3 ▶ sub message ( $self ) { $self->[0] }
Subroutine message: called CC=1 SCAR=0.0
167 }
168  
169 =head2 positive
170  
171 metric => Test::Metrics::Any::positive
172  
173 Asserts that the number is greater than zero. It must not be zero.
174  
175 =cut
176  
177 2 ▶sub positive ()
Subroutine positive: called CC=1 SCAR=0.0
Pod documented
178 {
179 2 ▶ predicate positive => sub ( $value ) { $value > 0 };
Subroutine __ANON__: called CC=1 SCAR=0.0
180 }
181  
182 =head2 at_least
183  
184 metric => Test::Metrics::Any::at_least( $n )
185  
186 Asserts that the number at least that given - it can be equal or greater.
187  
188 =cut
189  
190 2 ▶sub at_least ( $n )
Subroutine at_least: called CC=1 SCAR=0.0
Pod documented
191 {
192 2 ▶ predicate "at least $n" => sub ( $value ) { $value >= $n };
Subroutine __ANON__: called CC=1 SCAR=0.0
193 }
194  
195 =head2 greater_than
196  
197 metric => Test::Metrics::Any::greater_than( $n )
198  
199 Asserts that the number is greater than that given - it must not be equal.
200  
201 =cut
202  
203 2 ▶sub greater_than ( $n )
Subroutine greater_than: called CC=1 SCAR=0.0
Pod documented
204 {
205 2 ▶ predicate "greater than $n" => sub ( $value ) { $value > $n }
Subroutine __ANON__: called CC=1 SCAR=0.0
206 2 }
207  
208 =head1 AUTHOR
209  
210 Paul Evans <leonerd@leonerd.org.uk>
211  
212 =cut
213  
214 3 0x55AA;
↑ Summary