NAME

       Plack::Middleware::Test::StashWarnings - Test your application's warnings

SYNOPSIS

         # for your PSGI application:
         enable "Test::StashWarnings";

         # for your Test::WWW::Mechanize subclass:
         use Storable 'thaw';
         sub get_warnings {
             local $Test::Builder::Level = $Test::Builder::Level + 1;
             my $self = shift;

             my $clone = $self->clone;
             return unless $clone->get_ok('/__test_warnings');

             my @warnings = @{ thaw $clone->content };
             return @warnings;
         }

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.

       The warnings generated by your application are available at a special URL
       ("/__test_warnings"), encoded with "nfreeze" in Storable. So using Test::WWW::Mechanize
       you can just "get" that URL and "thaw" in Storable its content.

ARGUMENTS

       Plack::Middleware::Test::StashWarnings takes one optional argument, "verbose", which
       defaults to $ENV{TEST_VERBOSE}.  If set to true, it will bubble warnings up to any pre-
       existing "__WARN__" 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.

RATIONALE

       Warnings are an important part of any application. Your web application should warn its
       operators when something is amiss.

       Almost as importantly, your web application should gracefully cope with bad input, the
       back button, and all other aspects of the user experience.

       Unfortunately, tests seldom cover what happens when things go poorly. Are you sure that
       your application correctly denies that action and logs the failure? Are you sure it will
       tomorrow?

       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.

AUTHOR

       Shawn M Moore "sartak@bestpractical.com"

       Tatsuhiko Miyagawa wrote Plack::Middleware::Test::Recorder which served as a model for
       this module.

LICENSE

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

SEE ALSO

       Test::HTTP::Server::Simple::StashWarnings