Timecop Ruby Gem

To set a consistent time for your entire Rails test environment, you can use an after_initialize block in config/environments/test.rb. This allows you to build test data at a specific point in time.

# in config/environments/test.rb
config.after_initialize do
  # Set Time.now to September 1, 2008 10:05:00 AM
  t = Time.local(2008, 9, 1, 10, 5, 0)
  Timecop.travel(t)
end

Add timecop to your project using Bundler.

bundle add timecop

By default, Timecop does not mock Process.clock_gettime. To enable mocking for this method, set Timecop.mock_process_clock to true.

# turn on
Timecop.mock_process_clock = true

When Timecop.safe_mode is set to true, you are forced to use the block syntax for freeze and travel. This ensures that Timecop always automatically restores the original time once the block finishes. If you attempt to call these methods without a block, a Timecop::SafeModeException will be raised.

# turn on safe mode
Timecop.safe_mode = true

# check if you are in safe mode
Timecop.safe_mode?
# => true

# using method without block
Timecop.freeze
# => Timecop::SafeModeException: Safe mode is enabled, only calls passing a block are allowed.

Use Timecop.scale to accelerate the passage of time by a given scaling factor. This is useful for testing long-running cycles (like 30-day billing) in a short amount of real-world time.

# seconds will now seem like hours
Timecop.scale(3600)
Time.now
# => 2012-09-20 21:23:25 -0500

# seconds later, hours have passed
Time.now
# => 2012-09-21 06:22:59 -0500

Use Timecop.freeze to statically mock the concept of 'now'. When time is frozen, Time.now will not change as your program executes unless you make subsequent calls to the Timecop API. You can pass a Time, DateTime, or Date instance, individual time arguments (year, month, day, etc.), or a single integer representing an offset in seconds from Time.now.

new_time = Time.local(2008, 9, 1, 12, 0, 0)
Timecop.freeze(new_time)
sleep(10)
new_time == Time.now # ==> true

Use Timecop.travel to simulate the passage of time. Unlike freeze, travel computes an offset between the current mocked time and the time passed in, allowing time to continue moving forward from that point. You can pass a Time, DateTime, or Date instance, individual time arguments, or a single integer representing an offset in seconds from Time.now.

new_time = Time.local(2008, 9, 1, 12, 0, 0)
Timecop.return # "turn off" Timecop
Timecop.travel(new_time)
sleep(10)
new_time == Time.now # ==> false

When safe_mode is enabled, Timecop.travel will raise a Timecop::SafeModeException if it is called without a block. This prevents developers from accidentally leaving the system in a mocked state globally.

safe_mode? returns whether safe mode is currently active.

By default, Timecop's state (the stack of mocked times) is global. If you are running tests in a multi-threaded environment and want each thread to have its own independent time state, enable thread_safe mode.

Note: When thread_safe is enabled, the baseline and stack are stored in Thread.current.

Use these methods to inspect whether Timecop is currently manipulating time and which mode is active:

• Timecop.frozen?: Returns true if time is currently frozen.
• Timecop.travelled?: Returns true if time is currently being traveled (offset).
• Timecop.scaled?: Returns true if time is currently being scaled.

Use Timecop.travel to simulate a running clock. Unlike freeze, time continues to move forward, but it is offset from the actual system time. This is a safer option for Rails environment files as it doesn't completely halt the clock.

Supported arguments are identical to Timecop.freeze:

• A Time, DateTime, or Date instance
• An offset in seconds
• Individual components: year, month, day, hour, minute, second
• No arguments (defaults to Time.now)

When passed a block, Timecop reverts to the previous time after the block finishes.