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.8"

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Timecop

:nodoc:



174
175
176
177
178
 
# File 'lib/timecop/timecop.rb', line 174

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

Class Method Details

.baseline ⇒ Object 



78
79
80
 
# File 'lib/timecop/timecop.rb', line 78

def baseline
  instance.baseline
end

.baseline=(baseline) ⇒ Object 



82
83
84
 
# File 'lib/timecop/timecop.rb', line 82

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.”

  • 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.



51
52
53
 
# File 'lib/timecop/timecop.rb', line 51

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

.frozen? ⇒ Boolean

Returns whether or not Timecop is currently frozen

Returns:

  • (Boolean) 


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

def frozen?
  !instance.stack.empty? && instance.stack.last.mock_type == :freeze
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.



89
90
91
92
93
94
95
96
 
# File 'lib/timecop/timecop.rb', line 89

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

.return_to_baseline ⇒ Object 



99
100
101
102
 
# File 'lib/timecop/timecop.rb', line 99

def return_to_baseline
  instance.return_to_baseline
  Time.now
end

.safe_mode=(safe) ⇒ Object 



108
109
110
 
# File 'lib/timecop/timecop.rb', line 108

def safe_mode=(safe)
  @safe_mode = safe
end

.safe_mode? ⇒ Boolean

Returns:

  • (Boolean) 


112
113
114
 
# File 'lib/timecop/timecop.rb', line 112

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.



74
75
76
 
# File 'lib/timecop/timecop.rb', line 74

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

.thread_safe ⇒ Object 



120
121
122
 
# File 'lib/timecop/timecop.rb', line 120

def thread_safe
  instance.thread_safe
end

.thread_safe=(t) ⇒ Object 



116
117
118
 
# File 'lib/timecop/timecop.rb', line 116

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

.top_stack_item ⇒ Object

:nodoc:



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

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.



62
63
64
 
# File 'lib/timecop/timecop.rb', line 62

def travel(*args, &block)
  send_travel(:travel, *args, &block)
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.



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

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

Instance Method Details

#baseline ⇒ Object 



141
142
143
144
145
146
147
 
# File 'lib/timecop/timecop.rb', line 141

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

#baseline=(b) ⇒ Object 



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

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

#return(&block) ⇒ Object 



209
210
211
212
213
214
215
216
217
 
# File 'lib/timecop/timecop.rb', line 209

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 



224
225
226
227
228
229
230
 
# File 'lib/timecop/timecop.rb', line 224

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

#set_baseline(b) ⇒ Object 



149
150
151
152
153
154
155
 
# File 'lib/timecop/timecop.rb', line 149

def set_baseline(b)
  if @thread_safe
    Thread.current[:timecop_baseline] = b
  else
    @baseline = b
  end
end

#set_stack(s) ⇒ Object 



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

def set_stack(s)
  if @thread_safe
    Thread.current[:timecop_stack] = s
  else
    @stack = s
  end
end

#stack ⇒ Object 



157
158
159
160
161
162
163
164
 
# File 'lib/timecop/timecop.rb', line 157

def stack
  if @thread_safe
    Thread.current[:timecop_stack] ||= []
    Thread.current[:timecop_stack]
  else
    @stack
  end
end

#thread_safe ⇒ Object 



185
186
187
 
# File 'lib/timecop/timecop.rb', line 185

def thread_safe
  @thread_safe
end

#thread_safe=(t) ⇒ Object 



180
181
182
183
 
# File 'lib/timecop/timecop.rb', line 180

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

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

:nodoc:

Raises:



189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
 
# File 'lib/timecop/timecop.rb', line 189

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:



219
220
221
222
 
# File 'lib/timecop/timecop.rb', line 219

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