class Timecop

Timecop

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

baseline() click to toggle source
# File lib/timecop/timecop.rb, line 84
def baseline
  instance.baseline
end
baseline=(baseline) click to toggle source
# File lib/timecop/timecop.rb, line 88
def baseline=(baseline)
  instance.baseline = baseline
end
freeze(*args, &block) click to toggle source

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:

  1. Timecop.freeze(time_inst)

  2. Timecop.freeze(datetime_inst)

  3. Timecop.freeze(date_inst)

  4. Timecop.freeze(offset_in_seconds)

  5. Timecop.freeze(year, month, day, hour=0, minute=0, second=0)

  6. 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 expect Time 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.

# File lib/timecop/timecop.rb, line 57
def freeze(*args, &block)
  send_travel(:freeze, *args, &block)
end
frozen?() click to toggle source

Returns whether or not Timecop is currently frozen

# File lib/timecop/timecop.rb, line 131
def frozen?
  !instance.stack.empty? && instance.stack.last.mock_type == :freeze
end
mock_process_clock=(mock) click to toggle source
# File lib/timecop/timecop.rb, line 145
def mock_process_clock=(mock)
  @mock_process_clock = mock
end
mock_process_clock?() click to toggle source
# File lib/timecop/timecop.rb, line 149
def mock_process_clock?
  @mock_process_clock ||= false
end
return(&block) click to toggle source

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.

# File lib/timecop/timecop.rb, line 95
def return(&block)
  if block_given?
    instance.return(&block)
  else
    instance.unmock!
    nil
  end
end
Also aliased as: unfreeze
return_to_baseline() click to toggle source
# File lib/timecop/timecop.rb, line 105
def return_to_baseline
  instance.return_to_baseline
  Time.now
end
safe_mode=(safe) click to toggle source
# File lib/timecop/timecop.rb, line 114
def safe_mode=(safe)
  @safe_mode = safe
end
safe_mode?() click to toggle source
# File lib/timecop/timecop.rb, line 118
def safe_mode?
  @safe_mode ||= false
end
scale(*args, &block) click to toggle source

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.

# File lib/timecop/timecop.rb, line 80
def scale(*args, &block)
  send_travel(:scale, *args, &block)
end
scaled?() click to toggle source

Returns whether or not Timecop is currently scaled

# File lib/timecop/timecop.rb, line 141
def scaled?
  !instance.stack.empty? && instance.stack.last.mock_type == :scale
end
thread_safe() click to toggle source
# File lib/timecop/timecop.rb, line 126
def thread_safe
  instance.thread_safe
end
thread_safe=(t) click to toggle source
# File lib/timecop/timecop.rb, line 122
def thread_safe=(t)
  instance.thread_safe = t
end
travel(*args, &block) click to toggle source

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 to Timecop.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.

# File lib/timecop/timecop.rb, line 68
def travel(*args, &block)
  send_travel(:travel, *args, &block)
end
travelled?() click to toggle source

Returns whether or not Timecop is currently travelled

# File lib/timecop/timecop.rb, line 136
def travelled?
  !instance.stack.empty? && instance.stack.last.mock_type == :travel
end
unfreeze(&block)
Alias for: return

Private Class Methods

send_travel(mock_type, *args, &block) click to toggle 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

baseline() click to toggle source
# File lib/timecop/timecop.rb, line 165
def baseline
  if @thread_safe
    Thread.current[:timecop_baseline]
  else
    @baseline
  end
end
baseline=(b) click to toggle source
# File lib/timecop/timecop.rb, line 160
def baseline=(b)
  set_baseline(b)
  stack << TimeStackItem.new(:travel, b)
end
return() { || ... } click to toggle 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
return_to_baseline() click to toggle source
# File lib/timecop/timecop.rb, line 248
def return_to_baseline
  if baseline
    set_stack [stack.shift]
  else
    unmock!
  end
end
set_baseline(b) click to toggle 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
set_stack(s) click to toggle 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
stack() click to toggle 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
thread_safe() click to toggle source
# File lib/timecop/timecop.rb, line 209
def thread_safe
  @thread_safe
end
thread_safe=(t) click to toggle source
# File lib/timecop/timecop.rb, line 204
def thread_safe=(t)
  initialize
  @thread_safe = t
end