README
1NAME
2 Plack::Middleware::Test::StashWarnings - Test your application's
3 warnings
4
5SYNOPSIS
6 # for your PSGI application:
7 enable "Test::StashWarnings";
8
9
10 # for your Test::WWW::Mechanize subclass:
11 use Storable 'thaw';
12 sub get_warnings {
13 local $Test::Builder::Level = $Test::Builder::Level + 1;
14 my $self = shift;
15
16 my $clone = $self->clone;
17 return unless $clone->get_ok('/__test_warnings');
18
19 my @warnings = @{ thaw $clone->content };
20 return @warnings;
21 }
22
23DESCRIPTION
24 Plack::Middleware::Test::StashWarnings is a Plack middleware component
25 to record warnings generated by your application so that you can test
26 them to make sure your application complains about the right things.
27
28 The warnings generated by your application are available at a special
29 URL ("/__test_warnings"), encoded with "nfreeze" in Storable. So using
30 Test::WWW::Mechanize you can just "get" that URL and "thaw" in Storable
31 its content.
32
33ARGUMENTS
34 Plack::Middleware::Test::StashWarnings takes one optional argument,
35 "verbose", which defaults to $ENV{TEST_VERBOSE}. If set to true, it will
36 bubble warnings up to any pre-existing "__WARN__" handler. Turning this
37 explicitly off may be useful if your tests load Test::NoWarnings and
38 also use Test::WWW::Mechanize::PSGI for non-forking testing -- failure
39 to do so would result in test failures even for caught warnings.
40
41RATIONALE
42 Warnings are an important part of any application. Your web application
43 should warn its operators when something is amiss.
44
45 Almost as importantly, your web application should gracefully cope with
46 bad input, the back button, and all other aspects of the user
47 experience.
48
49 Unfortunately, tests seldom cover what happens when things go poorly.
50 Are you *sure* that your application correctly denies that action and
51 logs the failure? Are you *sure* it will tomorrow?
52
53 This module lets you retrieve the warnings that your forked server
54 issues. That way you can test that your application continues to issue
55 warnings when it makes sense. Catching the warnings also keeps your test
56 output tidy. Finally, you'll be able to see (and be notified via failing
57 tests) when your application issues new, unexpected warnings so you can
58 fix them immediately.
59
60AUTHOR
61 Shawn M Moore "sartak@bestpractical.com"
62
63 Tatsuhiko Miyagawa wrote Plack::Middleware::Test::Recorder which served
64 as a model for this module.
65
66LICENSE
67 This library is free software; you can redistribute it and/or modify it
68 under the same terms as Perl itself.
69
70SEE ALSO
71 Test::HTTP::Server::Simple::StashWarnings
72
73