Test::Snapshot(3pm)

💖 Test::Snapshot 💖

okay bestie, gather round, because this is the Perl module Test::Snapshot (3pm, she's a Perl one, living in the user-contributed docs) and she is so good at what she does. iykyk. ✨

---

🌸 NAME 🌸

Test::Snapshot — the module that lets you test against data stored in a file that literally names itself. no cap. 💅

---

🦋 SYNOPSIS 🦋

use Test::Snapshot;
my $got = function_generating_data();
is_deeply_snapshot $got, 'test description'; # could also be in a subtest

# command line:
TEST_SNAPSHOT_UPDATE=1 prove -lr t
# or
TEST_SNAPSHOT_UPDATE=1 make test
# if your code means the expected data should change, then inspect with
git diff -w

like. look at her. she's doing the most with the least. 🔥

---

👑 DESCRIPTION 👑

first things first: she is not connected with Test::Snapshots (plural!) — that one is built on a similar concept but it's for running executables. different girl, different vibe. don't mix them up fr fr. 🙈

so what she does: she implements a function that automates the storing and updating of expected test outputs. this whole thing is based on an idea the frontend devs call "snapshot testing", which is where the module name comes from. iconic origin story tbh. ✨

these snapshots get stored in files whose names are automatically generated from:

• the test filename ($0)
• any subtests' names surrounding and including this one
• the test description, if there is one

and if that file isn't there? she treats it as though it contains an undef. the audacity, the confidence, we love it. 💜

---

🎀 FUNCTIONS 🎀

💅 is_deeply_snapshot

exported by default, as a treat. takes two mandatory arguments:

• the got data — mandatory — a scalar which might be a reference. it gets passed to is_deeply in Test::More so it can be compared against the snapshotted data. 🫶
• a text description of this test — mandatory. she uses it for reporting results, but also to derive the filename where the expected data lives. multitasking queen. 👑

she will return the truth value of whether the test passed this time around — see below for the automatic updating of the expected data. ⭐

---

🌈 ENVIRONMENT 🌈

to have this module automatically update her expected data, set the environment variable TEST_SNAPSHOT_UPDATE to a true value. here's the tea though: if the got and expected data do not match, a test failure will be reported — but the expected data will be updated anyway. 😭 she said "i'm telling on you AND fixing it."

which means it is safe to always have the variable set to a true value, as long as you are using source control (you are using source control, right? bestie. answer the question. 👀) and you check your diffs before committing.

ngl, always-on updating plus source control is the whole vibe. just look at the diff before you commit. do not skip the diff. 🙏

---

🍓 FILE FORMAT 🍓

the expected data is stored in a format generated by Dumper in Data::Dumper, with these values set to true — chosen to maximise readability (and to minimise diffs, because pretty diffs are a love language) of the stored data:

• Sortkeys
• Indent
• Terse

three little settings, one big glow-up. ✨

---

🧚 AUTHOR 🧚

Ed J, "<etj at cpan.org>" — say thank you to the icon. 🫶

---

💖 LICENSE 💖

Copyright (C) Ed J

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

---

and that's the whole page, bestie!! she's perl v5.36.0, dated 2023-07-12, and she's Test::Snapshot(3pm) — now go write some snapshots and go check your git diff. mwah. 💖✨🎀🦋