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

NAME

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

SYNOPSIS

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

DESCRIPTION

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

Functions

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

AUTHOR

119       David Dick <ddick@cpan.org>
120

PREREQUISITES

122       Time::Piece 1.08 or greater
123

BUGS

125       Probably.
126

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

ACKNOWLEDGEMENTS

132       Thanks to a use.perl.org journal entry
133       <http://use.perl.org/~geoff/journal/20660> by Geoffrey Young.
134
135
136
137perl v5.12.0                      2008-06-29                 Test::MockTime(3)
Impressum