# Test::MockTime - phpMan

## NAME
    [Test::MockTime] - Replaces actual time with simulated time

## VERSION
    Version 0.17

## SYNOPSIS
      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('1970-01-01T00:00:00Z');

      # do some tests depending on time starting at Unix epoch time

      set_fixed_time('01/01/1970 00:00:00', '%m/%d/%Y %H:%M:%S');

      # do some tests depending on time staying at the Unix epoch time

      restore_time();

      # resume normal service

## 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.

SUBROUTINES/METHODS
    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.

        for example, in the following code

          [Test::MockTime]::[set_absolute_time(0)];
          my ($start) = time;
          sleep 2;
          my ($end) = time;

        The $end variable should contain 2 seconds past the epoch;

        If given two arguments, the first argument is taken to be an
        absolute time in some string format (for example, "01/01/1970
        00:00:00"). The second argument is taken to be a "strptime" format
        string (for example, "%m/%d/%Y %H:%M:%S"). If a single argument is
        given, but that argument is not numeric, a "strptime" format string
        of "%Y-%m-%dT%H:%M:%SZ" is assumed.

        for example, in the following code

          [Test::MockTime::set_absolute_time]('1970-01-01T00:00:00Z');
          my ($start) = time;
          sleep 2;
          my ($end) = time;

        The $end variable should contain 2 seconds past the Unix epoch;

    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.

        for example, in the following code

          my ($start) = time;
          [Test::MockTime::set_relative_time](-600);
          sleep 600;
          my ($end) = time;

        The $end variable should contain either the same or very similar
        values to the $start variable.

    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.

        for example, in the following code

          [Test::MockTime::set_fixed_time](time)
          my ($start) = time;
          sleep 3;
          my ($end) = time;

        the $end variable and the $start variable will contain the same
        results

        If given two arguments, the first argument is taken to be an
        absolute time in some string format (for example, "01/01/1970
        00:00:00"). The second argument is taken to be a "strptime" format
        string (for example, "%m/%d/%Y %H:%M:%S"). If a single argument is
        given, but that argument is not numeric, a "strptime" format string
        of "%Y-%m-%dT%H:%M:%SZ" is assumed.

    restore()
        restore the default time handling values. "restore_time" is an
        alias. When exported with the 'all' tag, this subroutine is exported
        as "restore_time".

## CONFIGURATION AND ENVIRONMENT
    [Test::MockTime] requires no configuration files or environment variables.

## DEPENDENCIES
    [Test::MockTime] depends on the following non-core Perl modules.

    *   [Time::Piece] 1.08 or greater

## INCOMPATIBILITIES
    None reported

## BUGS AND LIMITATIONS
    Probably.

## AUTHOR
    David Dick <<ddick@cpan.org>>

## LICENSE AND COPYRIGHT
    This program is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself.

## ACKNOWLEDGEMENTS
    Thanks to a use.perl.org journal entry
    <<http://use.perl.org/~geoff/journal/20660>> by Geoffrey Young.