module ActiveSupport::Testing::TimeHelpers - activesupport-4.2.4 Documentation

# module ActiveSupport::Testing::TimeHelpers

Containing helpers that helps you test passage of time.

### Public Instance Methods

travel(duration, &block) click to toggle source

Changes current time to the time in the future or in the past by a given time difference by stubbing `Time.now` and `Date.today`.

    Time.current # => Sat, 09 Nov 2013 15:34:49 EST -05:00
    travel 1.day
    Time.current # => Sun, 10 Nov 2013 15:34:49 EST -05:00
    Date.current # => Sun, 10 Nov 2013

This method also accepts a block, which will return the current time back to its original state at the end of the block:

    Time.current # => Sat, 09 Nov 2013 15:34:49 EST -05:00
    travel 1.day do
      User.create.created_at # => Sun, 10 Nov 2013 15:34:49 EST -05:00
    end
    Time.current # => Sat, 09 Nov 2013 15:34:49 EST -05:00

    # File lib/active_support/testing/time_helpers.rb, line 60
    def travel(duration, &block)
      travel_to Time.now + duration, &block
    end

travel_back() click to toggle source

Returns the current time back to its original state, by removing the stubs added by `travel` and `travel_to`.

    Time.current # => Sat, 09 Nov 2013 15:34:49 EST -05:00
    travel_to Time.new(2004, 11, 24, 01, 04, 44)
    Time.current # => Wed, 24 Nov 2004 01:04:44 EST -05:00
    travel_back
    Time.current # => Sat, 09 Nov 2013 15:34:49 EST -05:00

    # File lib/active_support/testing/time_helpers.rb, line 120
    def travel_back
      simple_stubs.unstub_all!
    end

travel_to(date_or_time) { || ... } click to toggle source

Changes current time to the given time by stubbing `Time.now` and `Date.today` to return the time or date passed into this method.

    Time.current # => Sat, 09 Nov 2013 15:34:49 EST -05:00
    travel_to Time.new(2004, 11, 24, 01, 04, 44)
    Time.current # => Wed, 24 Nov 2004 01:04:44 EST -05:00
    Date.current # => Wed, 24 Nov 2004

Dates are taken as their timestamp at the beginning of the day in the application time zone. `Time.current` returns said timestamp, and `Time.now` its equivalent in the system time zone. Similarly, `Date.current` returns a date equal to the argument, and `Date.today` the date according to `Time.now`, which may be different. (Note that you rarely want to deal with `Time.now`, or `Date.today`, in order to honor the application time zone please always use `Time.current` and `Date.current`.)

Note that the usec for the time passed will be set to 0 to prevent rounding errors with external services, like MySQL (which will round instead of floor, leading to off-by-one-second errors).

This method also accepts a block, which will return the current time back to its original state at the end of the block:

    Time.current # => Sat, 09 Nov 2013 15:34:49 EST -05:00
    travel_to Time.new(2004, 11, 24, 01, 04, 44) do
      Time.current # => Wed, 24 Nov 2004 01:04:44 EST -05:00
    end
    Time.current # => Sat, 09 Nov 2013 15:34:49 EST -05:00

    # File lib/active_support/testing/time_helpers.rb, line 93
    def travel_to(date_or_time)
      if date_or_time.is_a?(Date) && !date_or_time.is_a?(DateTime)
        now = date_or_time.midnight.to_time
      else
        now = date_or_time.to_time.change(usec: 0)
      end

      simple_stubs.stub_object(Time, :now, now)
      simple_stubs.stub_object(Date, :today, now.to_date)

      if block_given?
        begin
          yield
        ensure
          travel_back
        end
      end
    end

### Private Instance Methods

simple_stubs() click to toggle source

    # File lib/active_support/testing/time_helpers.rb, line 126
    def simple_stubs
      @simple_stubs ||= SimpleStubs.new
    end