Test::MockTime(3)

✨ Test::MockTime(3) ✨

okay so bestie, buckle up 💖 this is the Test::MockTime page from the User Contributed Perl Documentation, and it's genuinely iconic — it lets your test suite lie about what time it is. no cap. 🕰️✨

---

🌸 NAME 🌸

Test::MockTime — it literally replaces actual time with simulated time. yes. time is fake and we control it now 💅

🦋 VERSION 🦋

Version 0.17 — the one and only 🎀

⭐ SYNOPSIS ⭐

use Test::MockTime qw( :all );
set_relative_time(-600);

# do some tests depending on time increasing from 600 seconds ago

set_absolute_time(0);

# do some more tests depending on time starting from the epoch
# epoch may vary according to platform.  see perlport.

set_fixed_time(CORE::time());

# do some more tests depending on time staying at the current actual time

set_absolute_time('1970-01-01T00:00:00Z');

# do some tests depending on time starting at Unix epoch time

set_fixed_time('01/01/1970 00:00:00', '%m/%d/%Y %H:%M:%S');

# do some tests depending on time staying at the Unix epoch time

restore_time();

# resume normal service

like, look at her go 😭 she's doing the absolute most and I love that for her.

💜 DESCRIPTION 💜

So the whole reason this module exists: test suites need to test code at specific points in time — and you can't exactly wait around for 1970 to come back, right? 🙈

Specifically (and this is the important bit, don't skip it, iykyk): it overrides localtime, gmtime and time at compile time and then relies on you — the user — supplying a mock time via set_relative_time, set_absolute_time or set_fixed_time to alter future calls to gmtime, time or localtime. that's the whole trick. main character energy fr fr 👑

🧚 SUBROUTINES/METHODS 🧚

✨ set_absolute_time ✨

Okay so if you give it a single, numeric argument, that argument is an absolute time (like, if 0 is supplied, the absolute time will be the epoch), and it calculates the offset to allow subsequent calls to time, gmtime and localtime to reflect this.

for example, in the following code

Test::MockTime::set_absolute_time(0);
my ($start) = time;
sleep 2;
my ($end) = time;

the $end variable should contain 2 seconds past the epoch;

If you give it two arguments, the first argument is taken to be an absolute time in some string format (for example, "01/01/1970 00:00:00"). The second argument is taken to be a "strptime" format string (for example, "%m/%d/%Y %H:%M:%S"). And here's the little plot twist 🫶 — if a single argument is given, but that argument is not numeric, a "strptime" format string of "%Y-%m-%dT%H:%M:%SZ" is assumed.

for example, in the following code

Test::MockTime::set_absolute_time('1970-01-01T00:00:00Z');
my ($start) = time;
sleep 2;
my ($end) = time;

the $end variable should contain 2 seconds past the Unix epoch;

🌈 set_relative_time($relative) 🌈

takes as an argument a relative value from current time — like, if -10 is supplied, current time be converted to actual machine time - 10 seconds — and calculates the offset to allow subsequent calls to time, gmtime and localtime to reflect this.

for example, in the following code

my ($start) = time;
Test::MockTime::set_relative_time(-600);
sleep 600;
my ($end) = time;

the $end variable should contain either the same or very similar values to the $start variable. slay. ⏳

🎀 set_fixed_time 🎀

If you give it a single, numeric argument, the argument is an absolute time (for example, if 0 is supplied, the absolute time will be the epoch). All subsequent calls to gmtime, localtime and time will return this value. frozen in time, literally 💀✨

for example, in the following code

Test::MockTime::set_fixed_time(time)
my ($start) = time;
sleep 3;
my ($end) = time;

the $end variable and the $start variable will contain the same results.

If you give it two arguments, the first argument is taken to be an absolute time in some string format (for example, "01/01/1970 00:00:00"). The second argument is taken to be a "strptime" format string (for example, "%m/%d/%Y %H:%M:%S"). And again, per the same rule as above: if a single argument is given, but that argument is not numeric, a "strptime" format string of "%Y-%m-%dT%H:%M:%SZ" is assumed. 💅

🫶 restore() 🫶

restore the default time handling values. "restore_time" is an alias. When exported with the 'all' tag, this subroutine is exported as "restore_time". back to reality bestie 😭🌍

💖 CONFIGURATION AND ENVIRONMENT 💖

Test::MockTime requires no configuration files or environment variables. nothing. zero. a low-maintenance queen 🎀

🍓 DEPENDENCIES 🍓

Test::MockTime depends on the following non-core Perl modules.

• Time::Piece 1.08 or greater

👑 INCOMPATIBILITIES 👑

None reported. 🌸 (iconic behaviour, honestly)

💀 BUGS AND LIMITATIONS 💀

Probably. 😭🙈 literally that's the whole section. probably. no notes.

🌟 AUTHOR 🌟

David Dick <ddick@cpan.org>

🔥 LICENSE AND COPYRIGHT 🔥

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

🦋 ACKNOWLEDGEMENTS 🦋

Thanks to a use.perl.org journal entry <http://use.perl.org/~geoff/journal/20660> by Geoffrey Young. 🫶

---

and that's the whole page, bestie! ✨ drop a 💜 for perl v5.42.0, dated 2018-04-02, and this lil Test::MockTime(3) page from the User Contributed Perl Documentation — she ate and left no crumbs 🎀👑🌈