Class: Timecop

Inherits:
Object
  • Object
show all
Includes:
Singleton
Defined in:
lib/timecop/timecop.rb,
lib/timecop/version.rb,
lib/timecop/time_stack_item.rb

Overview

Timecop

  • Wrapper class for manipulating the extensions to the Time, Date, and DateTime 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.

Defined Under Namespace

Classes: SafeModeException, TimeStackItem

Constant Summary collapse

VERSION = 
"0.9.10"

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Timecop

:nodoc:



198
199
200
201
202
 
# File 'lib/timecop/timecop.rb', line 198

def initialize #:nodoc:
  @stack = []
  @safe = nil
  @thread_safe = false
end

Class Method Details

.baseline ⇒ Object 



84
85
86
 
# File 'lib/timecop/timecop.rb', line 84

def baseline
  instance.baseline
end

.baseline=(baseline) ⇒ Object 



88
89
90
 
# File 'lib/timecop/timecop.rb', line 88

def baseline=(baseline)
  instance.baseline = baseline
end

.freeze(*args, &block) ⇒ Object

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.



57
58
59
 
# File 'lib/timecop/timecop.rb', line 57

def freeze(*args, &block)
  send_travel(:freeze, *args, &block)
end

.frozen? ⇒ Boolean

Returns whether or not Timecop is currently frozen

Returns:

  • (Boolean) 


131
132
133
 
# File 'lib/timecop/timecop.rb', line 131

def frozen?
  !instance.stack.empty? && instance.stack.last.mock_type == :freeze
end

.mock_process_clock=(mock) ⇒ Object 



145
146
147
 
# File 'lib/timecop/timecop.rb', line 145

def mock_process_clock=(mock)
  @mock_process_clock = mock
end

.mock_process_clock? ⇒ Boolean

Returns:

  • (Boolean) 


149
150
151
 
# File 'lib/timecop/timecop.rb', line 149

def mock_process_clock?
  @mock_process_clock ||= false
end

.return(&block) ⇒ Object

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.



95
96
97
98
99
100
101
102
 
# File 'lib/timecop/timecop.rb', line 95

def return(&block)
  if block_given?
    instance.return(&block)
  else
    instance.unmock!
    nil
  end
end

.return_to_baseline ⇒ Object 



105
106
107
108
 
# File 'lib/timecop/timecop.rb', line 105

def return_to_baseline
  instance.return_to_baseline
  Time.now
end

.safe_mode=(safe) ⇒ Object 



114
115
116
 
# File 'lib/timecop/timecop.rb', line 114

def safe_mode=(safe)
  @safe_mode = safe
end

.safe_mode? ⇒ Boolean

Returns:

  • (Boolean) 


118
119
120
 
# File 'lib/timecop/timecop.rb', line 118

def safe_mode?
  @safe_mode ||= false
end

.scale(*args, &block) ⇒ Object

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.



80
81
82
 
# File 'lib/timecop/timecop.rb', line 80

def scale(*args, &block)
  send_travel(:scale, *args, &block)
end

.scaled? ⇒ Boolean

Returns whether or not Timecop is currently scaled

Returns:

  • (Boolean) 


141
142
143
 
# File 'lib/timecop/timecop.rb', line 141

def scaled?
  !instance.stack.empty? && instance.stack.last.mock_type == :scale
end

.thread_safe ⇒ Object 



126
127
128
 
# File 'lib/timecop/timecop.rb', line 126

def thread_safe
  instance.thread_safe
end

.thread_safe=(t) ⇒ Object 



122
123
124
 
# File 'lib/timecop/timecop.rb', line 122

def thread_safe=(t)
  instance.thread_safe = t
end

.top_stack_item ⇒ Object

:nodoc:



110
111
112
 
# File 'lib/timecop/timecop.rb', line 110

def top_stack_item #:nodoc:
  instance.stack.last
end

.travel(*args, &block) ⇒ Object

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.



68
69
70
 
# File 'lib/timecop/timecop.rb', line 68

def travel(*args, &block)
  send_travel(:travel, *args, &block)
end

.travelled? ⇒ Boolean

Returns whether or not Timecop is currently travelled

Returns:

  • (Boolean) 


136
137
138
 
# File 'lib/timecop/timecop.rb', line 136

def travelled?
  !instance.stack.empty? && instance.stack.last.mock_type == :travel
end

.unfreeze ⇒ Object

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.



103
104
105
106
107
108
109
110
 
# File 'lib/timecop/timecop.rb', line 103

def return(&block)
  if block_given?
    instance.return(&block)
  else
    instance.unmock!
    nil
  end
end

Instance Method Details

#baseline ⇒ Object 



165
166
167
168
169
170
171
 
# File 'lib/timecop/timecop.rb', line 165

def baseline
  if @thread_safe
    Thread.current[:timecop_baseline]
  else
    @baseline
  end
end

#baseline=(b) ⇒ Object 



160
161
162
163
 
# File 'lib/timecop/timecop.rb', line 160

def baseline=(b)
  set_baseline(b)
  stack << TimeStackItem.new(:travel, b)
end

#return(&block) ⇒ Object 



233
234
235
236
237
238
239
240
241
 
# 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 ⇒ Object 



248
249
250
251
252
253
254
 
# File 'lib/timecop/timecop.rb', line 248

def return_to_baseline
  if baseline
    set_stack [stack.shift]
  else
    unmock!
  end
end

#set_baseline(b) ⇒ Object 



173
174
175
176
177
178
179
 
# 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) ⇒ Object 



190
191
192
193
194
195
196
 
# 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 ⇒ Object 



181
182
183
184
185
186
187
188
 
# 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 ⇒ Object 



209
210
211
 
# File 'lib/timecop/timecop.rb', line 209

def thread_safe
  @thread_safe
end

#thread_safe=(t) ⇒ Object 



204
205
206
207
 
# File 'lib/timecop/timecop.rb', line 204

def thread_safe=(t)
  initialize
  @thread_safe = t
end

#travel(mock_type, *args, &block) ⇒ Object

:nodoc:

Raises:



213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
 
# File 'lib/timecop/timecop.rb', line 213

def travel(mock_type, *args, &block) #:nodoc:
  raise SafeModeException if Timecop.safe_mode? && !block_given? && !@safe

  stack_item = TimeStackItem.new(mock_type, *args)

  stack_backup = stack.dup
  stack << stack_item

  if block_given?
    safe_backup = @safe
    @safe = true
    begin
      yield stack_item.time
    ensure
      stack.replace stack_backup
      @safe = safe_backup
    end
  end
end

#unmock! ⇒ Object

:nodoc:



243
244
245
246
 
# File 'lib/timecop/timecop.rb', line 243

def unmock! #:nodoc:
  set_baseline nil
  set_stack []
end