Class Timecop
In: lib/timecop/timecop.rb
lib/timecop/time_stack_item.rb
Parent: Object

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.

Methods

freeze   return   travel  

Included Modules

Singleton

Public Class methods

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)

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 frozen time.

Reverts back to system‘s Time.now, Date.today and DateTime.now (if it exists).

Returns Time.now, which is now the real current time.

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)

Returns the ‘new’ current Time.

[Validate]