NAME¶

Time::Fake - Simulate different times without changing your system clock

SYNOPSIS¶

Pretend we are running 1 day in the future:

  use Time::Fake '+1d';

Pretend we are running 1 year in the past:

  use Time::Fake '-1y';

Pretend the script started at epoch time 1234567:

  use Time::Fake 1234567;

See what an existing script would do if run 20 years in the future:

  % perl -MTime::Fake="+20y" test.pl

Run a section of code in a time warp:

  use Time::Fake;
  
  # do some setup
  
  Time::Fake->offset("+1y");
  run_tests(); # thinks it's a year ahead
  Time::Fake->reset; # back to the present

DESCRIPTION¶

Use this module to achieve the effect of changing your system clock, but without actually changing your system clock. It overrides the Perl builtin subs "time", "localtime", and "gmtime", causing them to return a "faked" time of your choice. From the script's point of view, time still flows at the normal rate, but it is just offset as if it were executing in the past or present.

You may find this module useful in writing test scripts for code that has time-sensitive logic.

USAGE¶

  use Time::Fake $t;

  use Time::Fake;
  Time::Fake->offset($t);

  % perl -MTime::Fake=+1y script.pl

  Time::Fake->offset( [$t] );

  +3    # 3 seconds in the future
  -3s   # 3 seconds in the past
  +1h   # 1 hour in the future
  etc..

  s second
  m minute
  h hour
  d day (24 hours)
  M month (30 days)
  y year (365 days)

  Time::Fake->offset("+1h");
  Time::Fake->offset("+1h");
  
  ## same as
  # Time::Fake->offset("+1h");
  
  ## NOT the same as 
  # Time::Fake->offset("+2h");

  Time::Fake->offset("+1h");
  ...
  Time::Fake->offset( Time::Fake->offset + 3600 ); # add another hour

  Time::Fake->reset;

  Time::Fake->offset(0);

KNOWN CAVEATS¶

Time::Fake must be loaded at "BEGIN"-time (e.g., with a standard "use" statement). It must be loaded before perl compiles any code that uses "time", "localtime", or "gmtime". Due to inherent limitations in overriding builtin subs, any code that was compiled before loading Time::Fake will not be affected.

Because the system clock is not being changed, only Perl code that uses "time", "localtime", or "gmtime" will be fooled about the date. In particular, the operating system is not fooled, nor are other programs. If your Perl code modifies a file for example, the file's modification time will reflect the actual (not faked) time. Along the same lines, if your Perl script obtains the time from somewhere other than the affected builtins subs (e.g., "qx/date/"), the actual (not faked) time will be reflected.

Time::Fake doesn't affect -M, -A, -C filetest operators in the way you'd probably want. These still report the actual (not faked) script start time minus file access time.

Time::Fake has not been tested with other modules that override the time builtins, e.g., Time::HiRes.

SEE ALSO¶

Time::Warp, which uses XS to fool more of Perl.

AUTHOR¶

Time::Fake is written by Mike Rosulek <mike@mikero.com>. Feel free to contact me with comments, questions, patches, or whatever.

COPYRIGHT¶

Copyright (c) 2008 Mike Rosulek. All rights reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.