.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.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 "Plack::Middleware::Test::StashWarnings 3pm"
.TH Plack::Middleware::Test::StashWarnings 3pm "2022-06-16" "perl v5.34.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"
Plack::Middleware::Test::StashWarnings \- Test your application's warnings
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&  # for your PSGI application:
\&  enable "Test::StashWarnings";
\&
\&
\&  # for your Test::WWW::Mechanize subclass:
\&  use Storable \*(Aqthaw\*(Aq;
\&  sub get_warnings {
\&      local $Test::Builder::Level = $Test::Builder::Level + 1;
\&      my $self = shift;
\&  
\&      my $clone = $self\->clone;
\&      return unless $clone\->get_ok(\*(Aq/_\|_test_warnings\*(Aq);
\&  
\&      my @warnings = @{ thaw $clone\->content };
\&      return @warnings;
\&  }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Plack::Middleware::Test::StashWarnings is a Plack middleware component to
record warnings generated by your application so that you can test them to make
sure your application complains about the right things.
.PP
The warnings generated by your application are available at a special \s-1URL\s0
(\f(CW\*(C`/_\|_test_warnings\*(C'\fR), encoded with \*(L"nfreeze\*(R" in Storable. So using
Test::WWW::Mechanize you can just \f(CW\*(C`get\*(C'\fR that \s-1URL\s0 and \*(L"thaw\*(R" in Storable its
content.
.SH "ARGUMENTS"
.IX Header "ARGUMENTS"
Plack::Middleware::Test::StashWarnings takes one optional argument,
\&\f(CW\*(C`verbose\*(C'\fR, which defaults to \f(CW$ENV{TEST_VERBOSE}\fR.  If set to true, it
will bubble warnings up to any pre-existing \f(CW\*(C`_\|_WARN_\|_\*(C'\fR handler.
Turning this explicitly off may be useful if your tests load
Test::NoWarnings and also use Test::WWW::Mechanize::PSGI for
non-forking testing \*(-- failure to do so would result in test failures
even for caught warnings.
.SH "RATIONALE"
.IX Header "RATIONALE"
Warnings are an important part of any application. Your web application should
warn its operators when something is amiss.
.PP
Almost as importantly, your web application should gracefully cope with bad
input, the back button, and all other aspects of the user experience.
.PP
Unfortunately, tests seldom cover what happens when things go poorly. Are you
\&\fIsure\fR that your application correctly denies that action and logs the
failure? Are you \fIsure\fR it will tomorrow?
.PP
This module lets you retrieve the warnings that your forked server issues. That
way you can test that your application continues to issue warnings when it
makes sense. Catching the warnings also keeps your test output tidy. Finally,
you'll be able to see (and be notified via failing tests) when your
application issues new, unexpected warnings so you can fix them immediately.
.SH "AUTHOR"
.IX Header "AUTHOR"
Shawn M Moore \f(CW\*(C`sartak@bestpractical.com\*(C'\fR
.PP
Tatsuhiko Miyagawa wrote Plack::Middleware::Test::Recorder which served as
a model for this module.
.SH "LICENSE"
.IX Header "LICENSE"
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Test::HTTP::Server::Simple::StashWarnings