.\" 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 "Test::HTTP::Server::Simple::StashWarnings 3pm"
.TH Test::HTTP::Server::Simple::StashWarnings 3pm "2022-06-17" "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"
Test::HTTP::Server::Simple::StashWarnings \- catch your forked server's warnings
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&    package My::Webserver::Test;
\&    use base qw/Test::HTTP::Server::Simple::StashWarnings My::Webserver/;
\&
\&    sub test_warning_path { "/_\|_test_warnings" }
\&
\&
\&    package main;
\&    use Test::More tests => 42;
\&
\&    my $s = My::WebServer::Test\->new;
\&
\&    my $url_root = $s\->started_ok("start up my web server");
\&
\&    my $mech = WWW::Mechanize\->new;
\&
\&    $mech\->get("$url_root/some_action");
\&
\&    $mech\->get("/_\|_test_warnings");
\&    my @warnings = My::WebServer::Test\->decode_warnings($mech\->content);
\&    is(@warnings, 0, "some_action gave no warnings");
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Warnings are an important part of any application. Your web application should
warn the user when something is amiss.
.PP
Almost as importantly, we want to be able to test that the web application
gracefully copes 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
\&\f(CW\*(C`sure\*(C'\fR that your application checks authorization for that action? Are you
\&\f(CW\*(C`sure\*(C'\fR it will tomorrow?
.PP
This module lets you retrieve the warnings that your forked server throws. That
way you can test that your application continues to throw warnings when it
makes sense. Catching the warnings also keeps your test output tidy. Finally,
you'll be able to see when your application throws new, unexpected warnings.
.SH "SETUP"
.IX Header "SETUP"
The way this module works is it catches warnings and makes them available on a
special \s-1URL\s0 (which must be defined by you in the \f(CW\*(C`test_warning_path\*(C'\fR method).
You can use \f(CW\*(C`WWW::Mechanize\*(C'\fR (or whichever \s-1HTTP\s0 agent you prefer) to download
the warnings. The warnings will be serialized. Use decode_warnings to get
the list of warnings seen so far (since last request anyway).
.PP
Warnings are encoded using Storable by default, but your subclass may override the \f(CW\*(C`encode_warnings\*(C'\fR and \f(CW\*(C`decode_warnings\*(C'\fR methods.
.SH "TIPS"
.IX Header "TIPS"
Setting the \f(CW\*(C`TEST_VERBOSE\*(C'\fR environment variable to a true value will cause
warnings to be displayed immediately, even if they would be captured and tested
later.
.SH "AUTHOR"
.IX Header "AUTHOR"
Shawn M Moore, \f(CW\*(C`<sartak at bestpractical.com>\*(C'\fR
.SH "BUGS"
.IX Header "BUGS"
Please report any bugs or feature requests to
\&\f(CW\*(C`bug\-test\-http\-server\-simple\-stashwarnings at rt.cpan.org\*(C'\fR, or through the web
interface at
<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=test\-http\-server\-simple\-stashwarnings>.
.SH "COPYRIGHT & LICENSE"
.IX Header "COPYRIGHT & LICENSE"
Copyright 2008 Best Practical Solutions.
.PP
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.