class Timecop
-
Wrapper class for manipulating the extensions to the
Time
,Date
, andDateTime
objects -
Allows us to “freeze” time in our Ruby applications.
-
Optionally allows time travel to simulate a running clock, such time is not technically frozen.
This is very useful when your app’s functionality is dependent on time (e.g. anything that might expire). This will allow us to alter the return value of Date.today, Time.now, and DateTime.now, such that our application code never has to change.
Constants
- VERSION
Public Class Methods
Source
# File lib/timecop/timecop.rb, line 88 def baseline=(baseline) instance.baseline = baseline end
Source
# File lib/timecop/timecop.rb, line 57 def freeze(*args, &block) send_travel(:freeze, *args, &block) end
Allows you to run a block of code and “fake” a time throughout the execution of that block. This is particularly useful for writing test methods where the passage of time is critical to the business logic being tested. For example:
joe = User.find(1) joe.purchase_home() assert !joe.mortgage_due? Timecop.freeze(2008, 10, 5) do assert joe.mortgage_due? end
freeze and travel will respond to several different arguments:
-
Timecop.freeze(year, month, day, hour=0, minute=0, second=0)
-
Timecop.freeze()
# Defaults to Time.now
When a block is also passed, Time.now, DateTime.now and Date.today are all reset to their previous values after the block has finished executing. This allows us to nest multiple calls to Timecop.travel
and have each block maintain it’s concept of “now.”
The Process.clock_gettime call mocks both CLOCK::MONOTIC and CLOCK::REALTIME
CLOCK::MONOTONIC works slightly differently than other clocks. This clock cannot move to a particular date/time. So the only option that changes this clock is #4 which will move the clock the requested offset. Otherwise the clock is frozen to the current tick.
-
Note:
Timecop.freeze
will actually freeze time. This can cause unanticipated problems if benchmark or other timing calls are executed, which implicitly expectTime
to actually move forward. -
Rails Users: Be especially careful when setting this in your development environment in a rails project. Generators will load your environment, including the migration generator, which will lead to files being generated with the timestamp set by the
Timecop.freeze
call in your dev environment
Returns the value of the block if one is given, or the mocked time.
Source
# File lib/timecop/timecop.rb, line 131 def frozen? !instance.stack.empty? && instance.stack.last.mock_type == :freeze end
Returns whether or not Timecop
is currently frozen
Source
# File lib/timecop/timecop.rb, line 145 def mock_process_clock=(mock) @mock_process_clock = mock end
Source
# File lib/timecop/timecop.rb, line 149 def mock_process_clock? @mock_process_clock ||= false end
Source
# File lib/timecop/timecop.rb, line 95 def return(&block) if block_given? instance.return(&block) else instance.unmock! nil end end
Reverts back to system’s Time.now, Date.today and DateTime.now (if it exists) permamently when no block argument is given, or temporarily reverts back to the system’s time temporarily for the given block.
Source
# File lib/timecop/timecop.rb, line 105 def return_to_baseline instance.return_to_baseline Time.now end
Source
# File lib/timecop/timecop.rb, line 114 def safe_mode=(safe) @safe_mode = safe end
Source
# File lib/timecop/timecop.rb, line 118 def safe_mode? @safe_mode ||= false end
Source
# File lib/timecop/timecop.rb, line 80 def scale(*args, &block) send_travel(:scale, *args, &block) end
Allows you to run a block of code and “scale” a time throughout the execution of that block. The first argument is a scaling factor, for example:
Timecop.scale(2) do ... time will 'go' twice as fast here end
See Timecop#freeze for exact usage of the other arguments
Returns the value of the block if one is given, or the mocked time.
Source
# File lib/timecop/timecop.rb, line 141 def scaled? !instance.stack.empty? && instance.stack.last.mock_type == :scale end
Returns whether or not Timecop
is currently scaled
Source
# File lib/timecop/timecop.rb, line 126 def thread_safe instance.thread_safe end
Source
# File lib/timecop/timecop.rb, line 122 def thread_safe=(t) instance.thread_safe = t end
Source
# File lib/timecop/timecop.rb, line 68 def travel(*args, &block) send_travel(:travel, *args, &block) end
Allows you to run a block of code and “fake” a time throughout the execution of that block. See Timecop#freeze for a sample of how to use (same exact usage syntax)
-
Note:
Timecop.travel
will not freeze time (as opposed toTimecop.freeze
). This is a particularly good candidate for use in environment files in rails projects.
Returns the value of the block if one is given, or the mocked time.
Source
# File lib/timecop/timecop.rb, line 136 def travelled? !instance.stack.empty? && instance.stack.last.mock_type == :travel end
Returns whether or not Timecop
is currently travelled
Private Class Methods
Source
# File lib/timecop/timecop.rb, line 154 def send_travel(mock_type, *args, &block) val = instance.travel(mock_type, *args, &block) block_given? ? val : Time.now end
Public Instance Methods
Source
# File lib/timecop/timecop.rb, line 165 def baseline if @thread_safe Thread.current[:timecop_baseline] else @baseline end end
Source
# File lib/timecop/timecop.rb, line 160 def baseline=(b) set_baseline(b) stack << TimeStackItem.new(:travel, b) end
Source
# File lib/timecop/timecop.rb, line 233 def return(&block) current_stack = stack current_baseline = baseline unmock! yield ensure set_stack current_stack set_baseline current_baseline end
Source
# File lib/timecop/timecop.rb, line 248 def return_to_baseline if baseline set_stack [stack.shift] else unmock! end end
Source
# File lib/timecop/timecop.rb, line 173 def set_baseline(b) if @thread_safe Thread.current[:timecop_baseline] = b else @baseline = b end end
Source
# File lib/timecop/timecop.rb, line 190 def set_stack(s) if @thread_safe Thread.current[:timecop_stack] = s else @stack = s end end
Source
# File lib/timecop/timecop.rb, line 181 def stack if @thread_safe Thread.current[:timecop_stack] ||= [] Thread.current[:timecop_stack] else @stack end end
Source
# File lib/timecop/timecop.rb, line 204 def thread_safe=(t) initialize @thread_safe = t end