.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
.\"
.\" 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
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Log::Any::Test 3"
.TH Log::Any::Test 3 2024-09-01 "perl v5.40.0" "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
Log::Any::Test \- Test what you're logging with Log::Any
.SH VERSION
.IX Header "VERSION"
version 1.717
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 3
\&    use Test::More;
\&    use Log::Any::Test;    # should appear before \*(Aquse Log::Any\*(Aq!
\&    use Log::Any qw($log);
\&
\&    # ...
\&    # call something that logs using Log::Any
\&    # ...
\&
\&    # now test to make sure you logged the right things
\&
\&    $log\->contains_ok(qr/good log message/, "good message was logged");
\&    $log\->does_not_contain_ok(qr/unexpected log message/, "unexpected message was not logged");
\&    $log\->empty_ok("no more logs");
\&
\&    # or
\&
\&    my $msgs = $log\->msgs;
\&    cmp_deeply($msgs, [{message => \*(Aqmsg1\*(Aq, level => \*(Aqdebug\*(Aq}, ...]);
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
\&\f(CW\*(C`Log::Any::Test\*(C'\fR is a simple module that allows you to test what has been
logged with Log::Any. Most of its API and implementation have been taken from
Log::Any::Dispatch.
.PP
Using \f(CW\*(C`Log::Any::Test\*(C'\fR signals \f(CW\*(C`Log::Any\*(C'\fR to send all subsequent log
messages to a single global in-memory buffer and to make the log proxy
provide a number of testing functions.  To use it, load \f(CW\*(C`Log::Any::Test\*(C'\fR
before anything that loads \f(CW\*(C`Log::Any\*(C'\fR.  To actually use the test methods,
you need to load \f(CW\*(C`Log::Any\*(C'\fR and get a log object from it, as shown in the
"SYNOPSIS".
.SH METHODS
.IX Header "METHODS"
The test_name is optional in the *_ok methods; a reasonable default will be
provided.
.IP "msgs ()" 4
.IX Item "msgs ()"
Returns the current contents of the global log buffer as an array reference,
where each element is a hash containing a \fIcategory\fR, \fIlevel\fR, and \fImessage\fR
key.  e.g.
.Sp
.Vb 10
\&  {
\&    category => \*(AqFoo\*(Aq,
\&    level => \*(Aqerror\*(Aq,
\&    message => \*(Aqthis is an error\*(Aq
\&  },
\&  {
\&    category => \*(AqBar::Baz\*(Aq,
\&    level => \*(Aqdebug\*(Aq,
\&    message => \*(Aqthis is a debug\*(Aq
\&  }
.Ve
.ie n .IP "contains_ok ($regex[, $test_name])" 4
.el .IP "contains_ok ($regex[, \f(CW$test_name\fR])" 4
.IX Item "contains_ok ($regex[, $test_name])"
Tests that a message in the log buffer matches \fR\f(CI$regex\fR\fI\fR. On success, the
message is \fIremoved\fR from the log buffer (but any other matches are left
untouched).
.ie n .IP "does_not_contain_ok ($regex[, $test_name])" 4
.el .IP "does_not_contain_ok ($regex[, \f(CW$test_name\fR])" 4
.IX Item "does_not_contain_ok ($regex[, $test_name])"
Tests that no message in the log buffer matches \fR\f(CI$regex\fR\fI\fR.
.ie n .IP "category_contains_ok ($category, $regex[, $test_name])" 4
.el .IP "category_contains_ok ($category, \f(CW$regex\fR[, \f(CW$test_name\fR])" 4
.IX Item "category_contains_ok ($category, $regex[, $test_name])"
Tests that a message in the log buffer from a specific category matches
\&\fR\f(CI$regex\fR\fI\fR. On success, the message is \fIremoved\fR from the log buffer (but any
other matches are left untouched).
.ie n .IP "category_does_not_contain_ok ($category, $regex[, $test_name])" 4
.el .IP "category_does_not_contain_ok ($category, \f(CW$regex\fR[, \f(CW$test_name\fR])" 4
.IX Item "category_does_not_contain_ok ($category, $regex[, $test_name])"
Tests that no message from a specific category in the log buffer matches
\&\fR\f(CI$regex\fR\fI\fR.
.IP "empty_ok ([$test_name])" 4
.IX Item "empty_ok ([$test_name])"
Tests that there is no log buffer left. On failure, the log buffer is cleared
to limit further cascading failures.
.ie n .IP "contains_only_ok ($regex[, $test_name])" 4
.el .IP "contains_only_ok ($regex[, \f(CW$test_name\fR])" 4
.IX Item "contains_only_ok ($regex[, $test_name])"
Tests that there is a single message in the log buffer and it matches
\&\fR\f(CI$regex\fR\fI\fR. On success, the message is removed.
.IP "clear ()" 4
.IX Item "clear ()"
Clears the log buffer.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Log::Any, Test::Log::Dispatch
.SH AUTHORS
.IX Header "AUTHORS"
.IP \(bu 4
Jonathan Swartz <swartz@pobox.com>
.IP \(bu 4
David Golden <dagolden@cpan.org>
.IP \(bu 4
Doug Bell <preaction@cpan.org>
.IP \(bu 4
Daniel Pittman <daniel@rimspace.net>
.IP \(bu 4
Stephen Thirlwall <sdt@cpan.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2017 by Jonathan Swartz, David Golden, and Doug Bell.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.