Test::...ecorder(3pm)

✨ NAME ✨

Test::LectroTest::FailureRecorder — literally the module that records and plays back failures so you can do regression testing 💖 (and yes bestie, the manual page header calls it Test::...ecorder(3pm) because the name is that long and perl's manpage formatter was like "girl, I'm not doing this" 💅)

---

🌸 VERSION 🌸

version 0.5001 — she's serving, she's vintage, she's stable 🫶

---

🦋 SYNOPSIS 🦋

okay so this is the whole vibe, no cap:

use Test::LectroTest::Recorder;

my $recorder = Test::LectroTest::Recorder->new("storage_file.txt");

my $recorder->record_failure_for_property(
   "property name",
   $input_hashref_from_counterexample
);

my $failures = $recorder->get_failures_for_property("property name");
for my $input_hashref (@$failures) {
   # do something with hashref
}

periodt. 💅

---

💜 DESCRIPTION 💜

So this module is giving simple means of recording property-check failures so they can be reused as regression tests. ✨ And the tea is: you do not need to use this module yourself because the higher-level LectroTest modules will use it for you when needed. (These docs are mainly for LectroTest developers, iykyk 🙈)

The basic idea — the core concept, the main character energy — is to record a failure as a pair of the form

[ <property_name>, <input hash from counterexample> ]

and Dump these pairs into a text file, each record terminated by a blank line so that the file can be read using paragraph-slurp mode. Obsessed with the design ngl 🎀

The module provides methods to add such pairs to a recorder file and to retrieve the recorded failures by property name. It uses a cache to avoid repetitive reads, because reading the same file over and over is not the vibe. 💀

---

🎀 METHODS 🎀

💫 new(storage-file)

my $recorder = Test::LectroTest::Recorder->new("/path/to/storage.txt");

Creates a new recorder object and tells it to use storage-file for the reading and writing of failures. ✨

The recorder will not access the storage file until you attempt to get or record a failure. So bestie, it is OK to specify a storage file that does not yet exist — provided you record failures to it before you attempt to get failures from it. Don't come for her, she's just lazy-loading 🦋

💫 get_failures_for_property(propname)

my $failures = $recorder->get_failures_for_property("property name");
for my $input_hashref (@$failures) {
   # do something with hashref
   while (my ($var, $value) = each %$input_hashref) {
       # ...
   }
}

Returns a reference to an array that contains the recorded failures for the property with the name propname. If no such failures exist, the array will be empty — no drama, just an empty array, we love a graceful nothing 🫶 Each failure is represented by a hash containing the inputs that caused the failure.

⚠️ If the recorder's storage file does not exist or cannot be opened for reading, this method dies. 😭 So you should call it from within an "eval" block. Protect your peace (and your process) fr fr.

💫 record_failure_for_property(propname, input-hashref)

my $recorder->record_failure_for_property(
   "property name",
   $input_hashref_from_counterexample
);

Adds a failure record for the property named propname. The record captures the counterexample represented by input-hashref. The record is immediately appended to the recorder's storage file. No waiting, no buffering drama, she goes straight to disk 💅

Returns 1 upon success; dies otherwise.

⚠️ If the recorder's storage file cannot be opened for writing, this method dies. 😭 So you should call it from within an "eval" block. Again. Every time. It's giving protective girlfriend energy and honestly? Valid.

---

🌈 SEE ALSO 🌈

Test::LectroTest::TestRunner explains the internal testing apparatus, which uses the failure recorders to record and play back failures for regression testing. Go read it, it's the lore 🧚

---

👑 AUTHOR 👑

Tom Moertel (tom@moertel.com) — iconic, legendary, the blueprint 💖

---

💖 COPYRIGHT and LICENSE 💖

Copyright (c) 2004-13 by Thomas G Moertel. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. slay. ✨

---

and that's the whole page bestie — written against perl v5.34.0, dated 2022-06-21, filed under the very long name Test::...ecorder(3pm). mwah 💋 go record some failures, you got this 🦋