Test::...teTime(3pm)

💖 NAME 💖

okay so welcome to the User Contributed Perl Documentation page for Test::...teTime (3pm) — yes that truncated title is giving ✨mystery✨ but it's really just this:

Test::MockDateTime — mock DateTime->now calls during tests. periodt. 💅

---

🌸 VERSION 🌸

version 0.02 — tiny but iconic 🎀

---

✨ SYNOPSIS ✨

bestie here's the whole vibe in one go:

use Test::More;
use Test::MockDateTime;
use DateTime;

on '2013-01-02 03:04:05' => sub {
    # inside this block all calls to DateTime::now
    # will report a mocked date.

    my $now = DateTime->now;
    is $now->ymd, '2013-01-02', 'occured now';
};

done_testing;

like… you just wrap your code in on and suddenly time itself is under your control. main character energy fr fr 👑

---

🦋 DESCRIPTION 🦋

ngl, grabbing the actual current time is lowkey useless when you're testing stuff. 😭 like what even is "now"? it's different every single run! but if you could get a known value while your testcase is running? suddenly your results are predictable and you can actually assert on things. slay. 💖

so why yet another Date Mocker? valid question bestie. the author wanted something simple, with a very concise usage pattern, AND — this is the important part — the mocked date should only exist and stay constant inside a scope. the moment you leave that scope, the current time should be back. that whole idea is what led to this tiny module. 🌈

so basically: this simple module lets you fake a given date and time for the runtime of a subsequent code block. by default the on keyword gets exported into the namespace of the test file. 🫶 the date you want mocked must be in a format that DateTime::Format::DateParse recognizes. no cap.

on '2013-01-02 03:04:05', sub { ... };

is basically the same as

{
    my $now = DateTime::Format::DateParse->parse_datetime(
        '2013-01-02 03:04:05'
    );

    local *DateTime::now = sub { $now->clone };

    ... everything from code block above
}

⚠️ one drawback you gotta know about: if you're relying on this module, you must know that the module you're testing actually uses DateTime->now to obtain the current time. if it doesn't, this whole thing does nothing for you and that's just the way it is 🙈

---

💅 FUNCTIONS 💅

on $date_and_time, \&code

mocks date and time and then executes code. that's it. that's the function. she's simple, she's elegant, she ate. ✨

---

💀 CAVEATS 💀

this module only mocks calls to DateTime->now. every other possible way to obtain a current time is not touched. so if your code goes looking for the time somewhere else, it's gonna find the real one and your test is gonna be real confused. 🙈

---

🔥 SEE ALSO 🔥

there are some alternatives out there! depending on your environment, you might wanna consider using one of them instead. iykyk 👑

Test::MockTime very universal — it overwrites several subs at compile time and allows you to set a fixed or ticking time at any place in your code. 💜

Time::Mock also lets you set a time at various places inside your code.

Test::MockTime::DateCalc mocks several Date::Calc functions.

Time::Fake also overwrites several subs at compile time.

---

🎀 AUTHOR 🎀

Wolfgang Kinkeldei, <wolfgang@kinkeldei.de> — thank you for your service king 🫡💖

---

🌟 LICENSE 🌟

this library is free software. you can redistribute it and/or modify it under the same terms as Perl itself. so go wild bestie, respectfully. ✨

---

and that's a wrap on the Test::...teTime page, rendered with perl v5.36.0, dated 2022-12-16 💖 you're all caught up, bestie, go write some tests that don't depend on the actual clock 🦋✨🎀