1Test::MockTime(3)     User Contributed Perl Documentation    Test::MockTime(3)
2
3
4

NAME

6       Test::MockTime - Replaces actual time with simulated time
7

VERSION

9       Version 0.17
10

SYNOPSIS

12         use Test::MockTime qw( :all );
13         set_relative_time(-600);
14
15         # do some tests depending on time increasing from 600 seconds ago
16
17         set_absolute_time(0);
18
19         # do some more tests depending on time starting from the epoch
20         # epoch may vary according to platform.  see perlport.
21
22         set_fixed_time(CORE::time());
23
24         # do some more tests depending on time staying at the current actual time
25
26         set_absolute_time('1970-01-01T00:00:00Z');
27
28         # do some tests depending on time starting at Unix epoch time
29
30         set_fixed_time('01/01/1970 00:00:00', '%m/%d/%Y %H:%M:%S');
31
32         # do some tests depending on time staying at the Unix epoch time
33
34         restore_time();
35
36         # resume normal service
37

DESCRIPTION

39       This module was created to enable test suites to test code at specific
40       points in time. Specifically it overrides localtime, gmtime and time at
41       compile time and then relies on the user supplying a mock time via
42       set_relative_time, set_absolute_time or set_fixed_time to alter future
43       calls to gmtime,time or localtime.
44

SUBROUTINES/METHODS

46       set_absolute_time
47           If given a single, numeric argument, the argument is an absolute
48           time (for example, if 0 is supplied, the absolute time will be the
49           epoch), and calculates the offset to allow subsequent calls to
50           time, gmtime and localtime to reflect this.
51
52           for example, in the following code
53
54             Test::MockTime::set_absolute_time(0);
55             my ($start) = time;
56             sleep 2;
57             my ($end) = time;
58
59           The $end variable should contain 2 seconds past the epoch;
60
61           If given two arguments, the first argument is taken to be an
62           absolute time in some string format (for example, "01/01/1970
63           00:00:00").  The second argument is taken to be a "strptime" format
64           string (for example, "%m/%d/%Y %H:%M:%S").  If a single argument is
65           given, but that argument is not numeric, a "strptime" format string
66           of "%Y-%m-%dT%H:%M:%SZ" is assumed.
67
68           for example, in the following code
69
70             Test::MockTime::set_absolute_time('1970-01-01T00:00:00Z');
71             my ($start) = time;
72             sleep 2;
73             my ($end) = time;
74
75           The $end variable should contain 2 seconds past the Unix epoch;
76
77       set_relative_time($relative)
78           takes as an argument an relative value from current time (for
79           example, if -10 is supplied, current time be converted to actual
80           machine time - 10 seconds) and calculates the offset to allow
81           subsequent calls to time,gmtime and localtime to reflect this.
82
83           for example, in the following code
84
85             my ($start) = time;
86             Test::MockTime::set_relative_time(-600);
87             sleep 600;
88             my ($end) = time;
89
90           The $end variable should contain either the same or very similar
91           values to the $start variable.
92
93       set_fixed_time
94           If given a single, numeric argument, the argument is an absolute
95           time (for example, if 0 is supplied, the absolute time will be the
96           epoch).  All subsequent calls to gmtime, localtime and time will
97           return this value.
98
99           for example, in the following code
100
101             Test::MockTime::set_fixed_time(time)
102             my ($start) = time;
103             sleep 3;
104             my ($end) = time;
105
106           the $end variable and the $start variable will contain the same
107           results
108
109           If given two arguments, the first argument is taken to be an
110           absolute time in some string format (for example, "01/01/1970
111           00:00:00").  The second argument is taken to be a "strptime" format
112           string (for example, "%m/%d/%Y %H:%M:%S").  If a single argument is
113           given, but that argument is not numeric, a "strptime" format string
114           of "%Y-%m-%dT%H:%M:%SZ" is assumed.
115
116       restore()
117           restore the default time handling values.  "restore_time" is an
118           alias. When exported with the 'all' tag, this subroutine is
119           exported as "restore_time".
120

CONFIGURATION AND ENVIRONMENT

122       Test::MockTime requires no configuration files or environment
123       variables.
124

DEPENDENCIES

126       Test::MockTime depends on the following non-core Perl modules.
127
128       •   Time::Piece 1.08 or greater
129

INCOMPATIBILITIES

131       None reported
132

BUGS AND LIMITATIONS

134       Probably.
135

AUTHOR

137       David Dick <ddick@cpan.org>
138

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

ACKNOWLEDGEMENTS

144       Thanks to a use.perl.org journal entry
145       <http://use.perl.org/~geoff/journal/20660> by Geoffrey Young.
146
147
148
149perl v5.38.0                      2023-07-21                 Test::MockTime(3)
Impressum