| 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
| |||||||||||
| 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
| |||||||||||
| 103 | 6 | ▶ | unless( $expectval->check( $gotval ) ) { | ||||||||
|
Branch: 1 branch
| |||||||||||
| 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
| |||||||||||
| 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; | |||||||||