.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\" ========================================================================
.\"
.IX Title "Test::LectroTest::FailureRecorder 3pm"
.TH Test::LectroTest::FailureRecorder 3pm "2018-01-14" "perl v5.26.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Test::LectroTest::FailureRecorder \- Records/plays failures for regression testing
.SH "VERSION"
.IX Header "VERSION"
version 0.5001
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& 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
\& }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module provides a simple means of recording property-check
failures so they can be reused as regression tests.  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.)
.PP
The basic idea is to record a failure as a pair of the form
.PP
.Vb 1
\& [ <property_name>, <input hash from counterexample> ]
.Ve
.PP
and Dump these pairs into a text file, each record terminated by blank
line so that the file can be read using paragraph-slurp mode.
.PP
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.
.SH "METHODS"
.IX Header "METHODS"
.SS "new(\fIstorage-file\fP)"
.IX Subsection "new(storage-file)"
.Vb 1
\&  my $recorder = Test::LectroTest::Recorder\->new("/path/to/storage.txt");
.Ve
.PP
Creates a new recorder object and tells it to use \fIstorage-file\fR
for the reading and writing of failures.
.PP
The recorder will not access the storage file until you attempt to
get or record a failure.  Thus it is \s-1OK\s0 to specify a storage file that
does not yet exist, provided you record failures to it before you
attempt to get failures from it.
.SS "get_failures_for_property(\fIpropname\fP)"
.IX Subsection "get_failures_for_property(propname)"
.Vb 7
\&  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) {
\&         # ...
\&     }
\&  }
.Ve
.PP
Returns a reference to an array that contains the recorded failures
for the property with the name \fIpropname\fR.  In the event no
such failures exist, the array will be empty.
Each failure is represented by a hash containing the inputs that
caused the failure.
.PP
If the recorder's storage file does not exist or cannot be
opened for reading, this method dies.  Thus, you should call
it from within an \f(CW\*(C`eval\*(C'\fR block.
.SS "record_failure_for_property(\fIpropname\fP, \fIinput-hashref\fP)"
.IX Subsection "record_failure_for_property(propname, input-hashref)"
.Vb 4
\&  my $recorder\->record_failure_for_property(
\&     "property name",
\&     $input_hashref_from_counterexample
\&  );
.Ve
.PP
Adds a failure record for the property named \fIpropname\fR.  The
record captures the counterexample represented by the \fIinput-hashref\fR.
The record is immediately appended to the recorder's storage file.
.PP
Returns 1 upon success; dies otherwise.
.PP
If the recorder's storage file cannot be opened for writing, this
method dies.  Thus, you should call it from within an \f(CW\*(C`eval\*(C'\fR block.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Test::LectroTest::TestRunner explains the internal testing apparatus,
which uses the failure recorders to record and play back failures for
regression testing.
.SH "AUTHOR"
.IX Header "AUTHOR"
Tom Moertel (tom@moertel.com)
.SH "COPYRIGHT and LICENSE"
.IX Header "COPYRIGHT and LICENSE"
Copyright (c) 2004\-13 by Thomas G Moertel.  All rights reserved.
.PP
This program is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.