.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .if !\nF .nr F 0 .if \nF>0 \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} .\} .\" ======================================================================== .\" .IX Title "Test::MockTime 3pm" .TH Test::MockTime 3pm "2018-04-07" "perl v5.26.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Test::MockTime \- Replaces actual time with simulated time .SH "VERSION" .IX Header "VERSION" Version 0.17 .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 2 \& use Test::MockTime qw( :all ); \& set_relative_time(\-600); \& \& # do some tests depending on time increasing from 600 seconds ago \& \& set_absolute_time(0); \& \& # do some more tests depending on time starting from the epoch \& # epoch may vary according to platform. see perlport. \& \& set_fixed_time(CORE::time()); \& \& # do some more tests depending on time staying at the current actual time \& \& set_absolute_time(\*(Aq1970\-01\-01T00:00:00Z\*(Aq); \& \& # do some tests depending on time starting at Unix epoch time \& \& set_fixed_time(\*(Aq01/01/1970 00:00:00\*(Aq, \*(Aq%m/%d/%Y %H:%M:%S\*(Aq); \& \& # do some tests depending on time staying at the Unix epoch time \& \& restore_time(); \& \& # resume normal service .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This module was created to enable test suites to test code at specific points in time. Specifically it overrides localtime, gmtime and time at compile time and then relies on the user supplying a mock time via set_relative_time, set_absolute_time or set_fixed_time to alter future calls to gmtime,time or localtime. .SH "SUBROUTINES/METHODS" .IX Header "SUBROUTINES/METHODS" .IP "set_absolute_time" 4 .IX Item "set_absolute_time" If given a single, numeric argument, the argument is an absolute time (for example, if 0 is supplied, the absolute time will be the epoch), and calculates the offset to allow subsequent calls to time, gmtime and localtime to reflect this. .Sp for example, in the following code .Sp .Vb 4 \& Test::MockTime::set_absolute_time(0); \& my ($start) = time; \& sleep 2; \& my ($end) = time; .Ve .Sp The \f(CW$end\fR variable should contain 2 seconds past the epoch; .Sp If given two arguments, the first argument is taken to be an absolute time in some string format (for example, \*(L"01/01/1970 00:00:00\*(R"). The second argument is taken to be a \f(CW\*(C`strptime\*(C'\fR format string (for example, \*(L"%m/%d/%Y \f(CW%H:\fR%M:%S\*(R"). If a single argument is given, but that argument is not numeric, a \&\f(CW\*(C`strptime\*(C'\fR format string of \*(L"%Y\-%m\-%dT%H:%M:%SZ\*(R" is assumed. .Sp for example, in the following code .Sp .Vb 4 \& Test::MockTime::set_absolute_time(\*(Aq1970\-01\-01T00:00:00Z\*(Aq); \& my ($start) = time; \& sleep 2; \& my ($end) = time; .Ve .Sp The \f(CW$end\fR variable should contain 2 seconds past the Unix epoch; .IP "set_relative_time($relative)" 4 .IX Item "set_relative_time($relative)" takes as an argument an relative value from current time (for example, if \-10 is supplied, current time be converted to actual machine time \- 10 seconds) and calculates the offset to allow subsequent calls to time,gmtime and localtime to reflect this. .Sp for example, in the following code .Sp .Vb 4 \& my ($start) = time; \& Test::MockTime::set_relative_time(\-600); \& sleep 600; \& my ($end) = time; .Ve .Sp The \f(CW$end\fR variable should contain either the same or very similar values to the \&\f(CW$start\fR variable. .IP "set_fixed_time" 4 .IX Item "set_fixed_time" If given a single, numeric argument, the argument is an absolute time (for example, if 0 is supplied, the absolute time will be the epoch). All subsequent calls to gmtime, localtime and time will return this value. .Sp for example, in the following code .Sp .Vb 4 \& Test::MockTime::set_fixed_time(time) \& my ($start) = time; \& sleep 3; \& my ($end) = time; .Ve .Sp the \f(CW$end\fR variable and the \f(CW$start\fR variable will contain the same results .Sp If given two arguments, the first argument is taken to be an absolute time in some string format (for example, \*(L"01/01/1970 00:00:00\*(R"). The second argument is taken to be a \f(CW\*(C`strptime\*(C'\fR format string (for example, \*(L"%m/%d/%Y \f(CW%H:\fR%M:%S\*(R"). If a single argument is given, but that argument is not numeric, a \&\f(CW\*(C`strptime\*(C'\fR format string of \*(L"%Y\-%m\-%dT%H:%M:%SZ\*(R" is assumed. .IP "\fIrestore()\fR" 4 .IX Item "restore()" restore the default time handling values. \f(CW\*(C`restore_time\*(C'\fR is an alias. When exported with the 'all' tag, this subroutine is exported as \f(CW\*(C`restore_time\*(C'\fR. .SH "CONFIGURATION AND ENVIRONMENT" .IX Header "CONFIGURATION AND ENVIRONMENT" Test::MockTime requires no configuration files or environment variables. .SH "DEPENDENCIES" .IX Header "DEPENDENCIES" Test::MockTime depends on the following non-core Perl modules. .IP "\(bu" 4 Time::Piece 1.08 or greater .SH "INCOMPATIBILITIES" .IX Header "INCOMPATIBILITIES" None reported .SH "BUGS AND LIMITATIONS" .IX Header "BUGS AND LIMITATIONS" Probably. .SH "AUTHOR" .IX Header "AUTHOR" David Dick .SH "LICENSE AND COPYRIGHT" .IX Header "LICENSE AND COPYRIGHT" This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. .SH "ACKNOWLEDGEMENTS" .IX Header "ACKNOWLEDGEMENTS" Thanks to a use.perl.org journal entry by Geoffrey Young.