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

Class Method Summary collapse

Class Method Details

.baseline ⇒ Object 



76
77
78
 
# File 'lib/timecop/timecop.rb', line 76

def baseline
  instance.send(:baseline)
end

.baseline=(baseline) ⇒ Object 



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

def baseline=(baseline)
  instance.send(: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.



49
50
51
 
# File 'lib/timecop/timecop.rb', line 49

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

.frozen? ⇒ Boolean

Returns whether or not Timecop is currently frozen/travelled

Returns:

  • (Boolean) 


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

def frozen?
  !instance.send(:stack).empty?
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.



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

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

.return_to_baseline ⇒ Object 



97
98
99
100
 
# File 'lib/timecop/timecop.rb', line 97

def return_to_baseline
  instance.send(:return_to_baseline)
  Time.now
end

.safe_mode=(safe) ⇒ Object 



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

def safe_mode=(safe)
  @safe_mode = safe
end

.safe_mode? ⇒ Boolean

Returns:

  • (Boolean) 


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

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.



72
73
74
 
# File 'lib/timecop/timecop.rb', line 72

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

.thread_safe ⇒ Object 



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

def thread_safe
  instance.send(:thread_safe)
end

.thread_safe=(t) ⇒ Object 



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

def thread_safe=(t)
  instance.send(:thread_safe=, t)
end

.top_stack_item ⇒ Object

:nodoc:



102
103
104
 
# File 'lib/timecop/timecop.rb', line 102

def top_stack_item #:nodoc:
  instance.send(: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.



60
61
62
 
# File 'lib/timecop/timecop.rb', line 60

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.



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

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