1Time::Fake(3)         User Contributed Perl Documentation        Time::Fake(3)
2
3
4

NAME

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

SYNOPSIS

10       Pretend we are running 1 day in the future:
11
12         use Time::Fake '+1d';
13
14       Pretend we are running 1 year in the past:
15
16         use Time::Fake '-1y';
17
18       Pretend the script started at epoch time 1234567:
19
20         use Time::Fake 1234567;
21
22       See what an existing script would do if run 20 years in the future:
23
24         % perl -MTime::Fake="+20y" test.pl
25
26       Run a section of code in a time warp:
27
28         use Time::Fake;
29
30         # do some setup
31
32         Time::Fake->offset("+1y");
33         run_tests(); # thinks it's a year ahead
34
35         Time::Fake->reset; # back to the present
36

DESCRIPTION

38       Use this module to achieve the effect of changing your system clock,
39       but without actually changing your system clock. It overrides the Perl
40       builtin subs "time", "localtime", and "gmtime", causing them to return
41       a "faked" time of your choice. From the script's point of view, time
42       still flows at the normal rate, but it is just offset as if it were
43       executing in the past or present.
44
45       You may find this module useful in writing test scripts for code that
46       has time-sensitive logic.
47

USAGE

49   Using and importing:
50         use Time::Fake $t;
51
52       Is equivalent to:
53
54         use Time::Fake;
55         Time::Fake->offset($t);
56
57       See below for arguments to "offset". This usage makes it easy to fake
58       the time for existing scripts, as in:
59
60         % perl -MTime::Fake=+1y script.pl
61
62   offset
63         Time::Fake->offset( [$t] );
64
65       $t is either an epoch time, or a relative offset of the following form:
66
67         +3    # 3 seconds in the future
68         -3s   # 3 seconds in the past
69         +1h   # 1 hour in the future
70         etc..
71
72       Relative offsets must begin with a plus or minus symbol. The supported
73       units are:
74
75         s second
76         m minute
77         h hour
78         d day (24 hours)
79         M month (30 days)
80         y year (365 days)
81
82       If $t is an epoch time, then "time", "localtime", and "gmtime" will act
83       as though the the current time (when "offset" was called) was actually
84       at $t epoch seconds.  Otherwise, the offset $t will be added to the
85       times returned by these builtin subs.
86
87       When $t is false, "time", "localtime", "gmtime" remain overridden, but
88       their behavior resets to reflect the actual system time.
89
90       When $t is omitted, nothing is changed, but "offset" returns the
91       current additive offset (in seconds). Otherwise, its return value is
92       the previous offset.
93
94       "offset" may be called several times. However, The effect of multiple
95       calls is NOT CUMULATIVE. That is:
96
97         Time::Fake->offset("+1h");
98         Time::Fake->offset("+1h");
99
100         ## same as
101         # Time::Fake->offset("+1h");
102
103         ## NOT the same as
104         # Time::Fake->offset("+2h");
105
106       Each call to "offset" completely cancels out the effect of any previous
107       calls. To make the effect cumulative, use the return value of calling
108       "offset" with no arguments:
109
110         Time::Fake->offset("+1h");
111         ...
112         Time::Fake->offset( Time::Fake->offset + 3600 ); # add another hour
113
114   reset
115         Time::Fake->reset;
116
117       Is the same as:
118
119         Time::Fake->offset(0);
120
121       That is, it returns all the affected builtin subs to their default
122       behavior -- reporing the actual system time.
123

KNOWN CAVEATS

125       Time::Fake must be loaded at "BEGIN"-time (e.g., with a standard "use"
126       statement). It must be loaded before perl compiles any code that uses
127       "time", "localtime", or "gmtime". Due to inherent limitations in
128       overriding builtin subs, any code that was compiled before loading
129       Time::Fake will not be affected.
130
131       Because the system clock is not being changed, only Perl code that uses
132       "time", "localtime", or "gmtime" will be fooled about the date.  In
133       particular, the operating system is not fooled, nor are other programs.
134       If your Perl code modifies a file for example, the file's modification
135       time will reflect the actual (not faked) time.  Along the same lines,
136       if your Perl script obtains the time from somewhere other than the
137       affected builtins subs (e.g., "qx/date/"), the actual (not faked) time
138       will be reflected.
139
140       Time::Fake doesn't affect -M, -A, -C filetest operators in the way
141       you'd probably want. These still report the actual (not faked) script
142       start time minus file access time.
143
144       Time::Fake has not been tested with other modules that override the
145       time builtins, e.g., Time::HiRes.
146

SEE ALSO

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

AUTHOR

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

COPYRIGHT

155       Copyright (c) 2008 Mike Rosulek. All rights reserved. This module is
156       free software; you can redistribute it and/or modify it under the same
157       terms as Perl itself.
158
159
160
161perl v5.36.0                      2023-01-20                     Time::Fake(3)