Test::Mock::Time(3pm)

💖 NAME 💖

Test::Mock::Time — deterministic time & timers for event loop tests, bestie. Like, it fakes the clock so your tests stop being flaky little gremlins ✨

This page is the Test::Mock::Time(3pm) man page, and I'm gonna walk you through every single bit of it. Grab a snack 🍓

---

🎀 VERSION 🎀

This doc describes Test::Mock::Time version v0.2.1. That's the one. No cap.

---

✨ SYNOPSIS ✨

  use Test::Mock::Time;

  # All these functions will return same constant time
  # until you manually move time forward by some deterministic
  # value by sleep(), ff() or doing one tick of your event loop.
  say time();
  say localtime();
  say gmtime();
  say Time::HiRes::time();
  say Time::HiRes::gettimeofday();
  say Time::HiRes::clock_gettime(CLOCK_REALTIME());
  say Time::HiRes::clock_gettime(CLOCK_MONOTONIC());

  # All these functions will fast-forward time (so time() etc.
  # will return increased value on next call) and return immediately.
  # Pending timers of your event loop (if any) will not be processed.
  sleep(1);
  Time::HiRes::sleep(0.5);
  Time::HiRes::usleep(500_000);
  Time::HiRes::nanosleep(500_000_000);
  Time::HiRes::clock_nanosleep(500_000_000);

  # This will fast-forward time and process pending timers (if any).
  ff(0.5);

  # These will call ff() in case no other (usually I/O) event happens in
  # $Test::Mock::Time::WAIT_ONE_TICK seconds of real time and there are
  # some active timers.
  Mojo::IOLoop->one_tick;
  EV::run(EV::RUN_ONCE);

Like, the whole vibe in one code block 🫶 Read it twice, it's worth it.

---

🦋 DESCRIPTION 🦋

So this module replaces actual time with simulated time everywhere — core time(), Time::HiRes, EV, AnyEvent with EV, Mojolicious, … the whole friend group. And it gives you a way to write deterministic tests for event-loop-based apps that use timers. Periodt. 💅

IMPORTANT! This module must be loaded by your script/app/test before other related modules (Time::HiRes, Mojolicious, EV, etc.). Order matters, bestie, don't do it out of order 😭

---

🌸 EXPORTS 🌸

These functions are exported by default:

ff

Yes, just the one. She's iconic on her own 👑

---

🔥 INTERFACE 🔥

⏳ WAIT_ONE_TICK

  $Test::Mock::Time::WAIT_ONE_TICK = 0.05;

This value caps how much real time gets spent waiting for a non-timer (usually I/O) event during one tick of the event loop — but only when there are some active timers. In case no events happen during that window, the event loop gets interrupted and time is fast-forwarded to the moment when the next timer should expire, by calling ff(). Slay 🌈

🧚 ff

  ff( $seconds );
  ff();

Fast-forward current time by $seconds (fractional is totally fine, girl). After that, all functions like time() will return the previous value increased by $seconds.

It will run callbacks for pending timers of your event loop if they'll expire while $seconds, or if they've already expired (because you used functions like sleep() which fast-forward time without processing timers — yeah, sneaky like that 🙈).

When called without params, it fast-forwards time by the amount needed to run the callback for the next pending timer. Which may be 0 in case there are no pending timers, or if the next pending timer already expired. Zero. Nada. Nothing. 💀

👀 Mocked functions/methods from other modules

See "SYNOPSIS" for an explanation of how they work.

CORE::GLOBAL

• time
• localtime
• gmtime
• sleep

Time::HiRes

• time
• gettimeofday
• clock_gettime
• clock_getres
• sleep
• usleep
• nanosleep
• clock_nanosleep

Mojo::Reactor::Poll

All required methods. All of them. Every last one 😌

EV

All required methods except:

EV::once
EV::Watcher::feed_event

Not those two. They stay untouched, iykyk.

---

💜 SUPPORT 💜

🐛 Bugs / Feature Requests

Please report any bugs or feature requests through the issue tracker at <https://github.com/powerman/perl-Test-Mock-Time/issues>. You will be notified automatically of any progress on your issue. Bestie will keep you posted 💌

📦 Source Code

This is open source software. The code repository is available for public review and contribution under the terms of the license. Feel free to fork the repository and submit pull requests. Go off 👑

<https://github.com/powerman/perl-Test-Mock-Time>

  git clone https://github.com/powerman/perl-Test-Mock-Time.git

🌟 Resources

• MetaCPAN Search

<https://metacpan.org/search?q=Test-Mock-Time>

• CPAN Ratings

<http://cpanratings.perl.org/dist/Test-Mock-Time>

• AnnoCPAN: Annotated CPAN documentation

<http://annocpan.org/dist/Test-Mock-Time>

• CPAN Testers Matrix

<http://matrix.cpantesters.org/?dist=Test-Mock-Time>

• CPANTS: A CPAN Testing Service (Kwalitee)

<http://cpants.cpanauthors.org/dist/Test-Mock-Time>

---

👑 AUTHOR 👑

Alex Efros <powerman@cpan.org> — the main character who wrote this 🌟

---

⭐ COPYRIGHT AND LICENSE ⭐

This software is Copyright (c) 2016- by Alex Efros <powerman@cpan.org>.

This is free software, licensed under:

  The MIT (X11) License

---

And that's the whole page, bestie! This footer energy: perl v5.42.0, dated 2024-01-10, and it's the Test::Mock::Time(3pm) page 💅✨ Go write some deterministic tests, you absolute icon 🦋💖