Test::...eclare(3pm)

💖 Test::WWW::Declare 💖

okay bestie, sit down, we're doing declarative testing for your web app and it's gonna be so much nicer than whatever you've been doing. this page lives in the User Contributed Perl Documentation corner of your system, and the title on the tin is Test::...eclare(3pm) (truncated, iconic, we love her) ✨

---

🌸 SYNOPSIS 🌸

use Test::WWW::Declare tests => 3;
use Your::Web::App::Test;

Your::Web::App::Test->start_server;

session 'testuser' => run {
    flow 'log in and out' => check {
        flow 'log in' => check {
            get 'http://localhost/';
            fill form 'login' => {
                username => 'testuser',
                password => 'drowssap',
            };
            content should contain 'log out';
        };

        flow 'log out' => check {
            get 'http://localhost/';
            click href 'log out';
        };
    };
};

like... look at that. it reads like a sentence. no cap. 🦋

---

🎀 DESCRIPTION 🎀

so here's the tea: in web apps, tests are super dependent on whatever state the previous test left behind. one test fails (say, follow the link to the admin page) and then boom — a whole cascade of failures, one after another, all because of that one little guy. 😭

this module is here to fix that, and also to hand you a genuinely nicer interface to Test::WWW::Mechanize.

the whole ~concept~ is the flow. a flow is just a sequence of commands (fill in this form) and assertions (content should contain 'testuser'). if any of those commands or assertions fail, the flow gets aborted on the spot. only that one failure gets reported to the test harness and the user — not the twenty domino failures behind it. periodt.

and flows can hold other flows. if an inner flow fails, the outer flow fails too. 💅

---

🌈 FLOWS AND SESSIONS 🌈

✨ session NAME => run { CODE } ✨

sessions are how you tie a bunch of flows to one WWW::Mechanize instance. honestly a session is basically equivalent to one user interacting with your web app. main character energy.

inside a session, every command (get, click link, etc) operates on that session's WWW::Mechanize instance. you can have multiple sessions in one test file, and — plot twist — two sessions with the same name are in fact the same session. so you can write stuff like this, slightly simplified:

session 'first user' => run {
    get "$URL/give?task=1&victim=other";
    session 'other user' => run {
        get "$URL/tasks";
        content should match qr/task 1/;

        # this is the same session/mech as the outermost 'first user'
        session 'first user' => run {
            get "$URL/tasks";
            content shouldnt match qr/task 1/;
        };
    };
};

okay but the way that comment carries the whole joke. 💀

✨ flow NAME => check { CODE } ✨

a flow wraps up a single test. like we said up top, each flow is a sequence of commands, assertions, and other flows. if any of the pieces of a flow fail, the rest of the flow is aborted and one or more test failures get reported to the test harness.

---

🫶 COMMANDS 🫶

• get URL
• click button
• click href
• follow_link
• fill form NAME => {FIELD1 => VALUE1, FIELD2 => VALUE2}

---

👑 ASSERTIONS 👑

every assertion has two parts, bestie: a subject and a verb. that's it. that's the whole structure. slay.

💜 SUBJECTS 💜

• content
• title
• url

💜 VERBS 💜

• should(nt) (caselessly) match REGEX
• should(nt) (caselessly) contain STRING
• should(nt) (caselessly) lack STRING
• should(nt) (caselessly) equal STRING

---

🧚 SUBCLASSING 🧚

one of the goals of this module is to let you subclass it so you can bolt on extra features — like automatically logging a user in every single time a session gets created. yes, that's a real example. go wild. 🔥

---

⚠️ CAVEATS ⚠️

if you fail any tests, then the actual number of tests run may be fewer than you have in your file. this is because when a flow fails, it immediately aborts the rest of its body (which may include other flows).

so if you're setting the number of tests based on how many actually ran — make sure all tests passed. no pressure or anything. 🙈

---

🐛 BUGS 🐛

hopefully few. we'd like to know about any of them. please report them to bug-test-www-declare@rt.cpan.org. 💌

---

🌟 SEE ALSO 🌟

• Test::WWW::Mechanize
• Jifty

---

💅 MAINTAINER 💅

Shawn M Moore <sartak@bestpractical.com>

🌸 ORIGINAL AUTHOR 🌸

Jesse Vincent <jesse@bestpractical.com>

💖 COPYRIGHT 💖

Copyright 2007-2008 Best Practical Solutions, LLC

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

---

and that's the whole page, bestie!! 🎀 this cutie was built on perl v5.36.0 and the docs are dated 2022-12-28 — you didn't ask, but I love you, so now you know. mwah. 💋 ✨