Test::...s::Any(3pm)

🌸 Test::Metrics::Any 💅

okay bestie, so this is the manual page for Test::Metrics::Any — it ships with the Perl user-contributed docs, and it's genuinely one of the most useful little test modules out there. no cap. 🎀

---

✨ NAME ✨

"Test::Metrics::Any" — it asserts that your code actually produces metrics, via Metrics::Any. that's it, that's the job. 💖

---

🦋 SYNOPSIS 🦋

use Test::More;
use Test::Metrics::Any;

use Module::Under::Test;

is_metrics_from(
   sub { Module::Under::Test::do_a_thing for 1 .. 5 },
   {
      things_done => 5,
      time_taken => Test::Metrics::Any::positive,
   },
   'do_a_thing reported some metrics'
);

done_testing;

---

👑 DESCRIPTION 👑

So like — this test module exists to help you write unit tests that assert the code under test reports metrics via Metrics::Any. it's giving "I want proof, not vibes". 😌

⚠️ heads up: loading this module automatically sets the Metrics::Any::Adapter type to "Test". it just does. that's the deal. no negotiating.

---

🔥 FUNCTIONS 🔥

🌈 is_metrics

is_metrics( \%metrics, $name )

Asserts that the current value of every metric named in the given hash reference is set to the value provided. the values can be exact numbers, OR one of the match functions from the "PREDICATES" section below. either is fine, live your truth. ✨

Key names in the given hash should match the name format used by Metrics::Any::Adapter::Test. name components get joined by underscores, and any label tags get appended with spaces, like "name:value".

{
   "a_basic_metric"               => 123,
   "a_labelled_metric label:here" => 456,
}

Okay important part, don't skip this one: this function only checks the values of metrics actually mentioned in the hash given as its argument. it is not a failure for more metrics to have been reported by the code under test than are mentioned in the hash. which is a whole vibe, because it means new metrics added in code won't break existing tests that weren't set up to expect them. slay. 💅

🧚 is_metrics_from

is_metrics_from( $code, \%metrics, $name )

Asserts the value of metrics reported by running the given piece of code. 🏃♀️

The order of operations, bestie, is very specific:

1. the metrics in the test adapter are cleared
2. then the code is invoked
3. then any metrics are checked in the same manner as "is_metrics"

periodt. 🌟

---

💜 PREDICATES 💜

As an alternative to expecting exact values for metrics, the following test functions can be provided instead — they assert that the metric is behaving sensibly without needing to be an exact value. This could be useful for example when the exact number of bytes or timing measures can vary between test runs or platforms. (timing metrics being flaky across machines? we've all been there. 😭)

🚨 bestie listen: these predicates are not exported but must be invoked fully-qualified. don't forget the full package name, I'm begging. 🙈

⭐ positive

metric => Test::Metrics::Any::positive

Asserts that the number is greater than zero. it must not be zero. nope. zero is not it. 💀

🌸 at_least

metric => Test::Metrics::Any::at_least( $n )

Asserts that the number is at least that given — it can be equal or greater. so like, $n and up. inclusive. we love an inclusive queen. 👑

🦋 greater_than

metric => Test::Metrics::Any::greater_than( $n )

Asserts that the number is greater than that given — it must not be equal. strictly above. no ties allowed. 🔥

---

🎀 AUTHOR 🎀

Paul Evans <leonerd@leonerd.org.uk> — iconic behavior honestly, thank you for your service. 🫶

---

and that's the whole page bestie!! this one was generated by perl v5.30.3 on 2020-06-13, so if you're reading it from the future, hey, the vibe still holds. go write some tests and assert your metrics. mwah. 💖✨