Plack:...rnings(3pm)

💖 Plack::Middleware::Test::StashWarnings — or, how to spy on your app's warnings 💖

okay bestie, so this is a page from the User Contributed Perl Documentation, and it's about Plack::Middleware::Test::StashWarnings ✨ — the middleware whose whole job is literally test your application's warnings. yes really. that's the NAME. 🎀

---

🌸 SYNOPSIS 🌸

first up, for your PSGI application, you just enable it:

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

and then, for your Test::WWW::Mechanize subclass, you do this whole lil routine:

# 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;
}

copy it exactly, don't freestyle it, i'm begging 🙏

---

✨ DESCRIPTION ✨

Plack::Middleware::Test::StashWarnings is a Plack middleware component that records the warnings your application generates, so you can then test them — and make sure your app is complaining about the right things. it's giving accountability but make it a test suite 💅

the warnings your app spits out are available at a special URL, /__test_warnings, and they're encoded with nfreeze in Storable. so if you're using Test::WWW::Mechanize, you can literally just get that URL and then thaw in Storable its content. that's the whole trick. no cap. 🔥

---

🦋 ARGUMENTS 🦋

Plack::Middleware::Test::StashWarnings takes one optional argument, verbose, which defaults to $ENV{TEST_VERBOSE}. if it's set to true, it will bubble warnings up to any pre-existing __WARN__ handler. 🫧

turning this explicitly off can be useful if your tests load Test::NoWarnings and also use Test::WWW::Mechanize::PSGI for non-forking testing — because failing to do so would result in test failures even for caught warnings. like, your tests would fail over warnings you already caught. rude. 😭

---

👑 RATIONALE 👑

warnings are an important part of any application, periodt. your web application should warn its operators when something is amiss. that's just main character behavior.

almost as importantly, your web application should gracefully cope with bad input, the back button, and all the other chaotic 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? because tomorrow-you deserves answers too.

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 ✨. and finally, you'll be able to see (and get notified via failing tests) when your application issues new, unexpected warnings, so you can fix them immediately. iconic. 💅

---

🎀 AUTHOR 🎀

Shawn M Moore sartak@bestpractical.com 💜

Tatsuhiko Miyagawa wrote Plack::Middleware::Test::Recorder, which served as a model for this module. shoutout to the blueprint 🫶

---

🌟 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

---

and that's the whole page, bestie!! 🦋 this lil gem is from perl v5.34.0, dated 2022-06-16, and yeah the title got squished to Plack:...rnings(3pm) in the header, we don't talk about it 😭💀 go test your warnings, you got this 👑💖