jtrupiano / timecop
watch download tarball
public
Forks6Right
Watchers123Right
Description: A gem providing “time travel” and “time freezing” capabilities, making it dead simple to test time-dependent code. It provides a unified method to mock Time.now, Date.today, and DateTime.now in a single call.
Homepage: http://www.smartlogicsolutions.com/open-source-projects
Clone URL: git://github.com/jtrupiano/timecop.git 
Regenerated gemspec for version 0.3.0
jtrupiano (author)
Sun Sep 20 20:01:45 -0700 2009
commit  7fd24f3ea7c20416bbcd7629ead39453c8a9077b
tree    936a3c4f5519df055f626195609ebe4e5bdef961
parent  63485ad0d4b1cd7cc90d328efc5f85c5813b06b0
README.rdoc

timecop

DESCRIPTION

A gem providing "time travel" and "time freezing" capabilities, making it dead simple to test time-dependent code. It provides a unified method to mock Time.now, Date.today, and DateTime.now in a single call.

FEATURES

  • Freeze time to a specific point.
  • Travel back to a specific point in time, but allow time to continue moving forward from there.
  • Timecop api allows arguments to be passed into #freeze and #travel as one of the following:
    • Time instance
    • DateTime instance
    • Date instance
    • individual arguments (year, month, day, hour, minute, second)
    • a single integer argument that is interpreted as an offset in seconds from Time.now
  • Nested calls to Timecop#travel and Timecop#freeze are supported — each block will maintain its interpretation of now.

USAGE

Run a time-sensitive test 

  joe = User.find(1)
  joe.purchase_home()
  assert !joe.mortgage_due?
  # move ahead a month and assert that the mortgage is due
  Timecop.freeze(Date.today + 30) do
    assert joe.mortgage_due?
  end

Set the time for the test environment of a rails app — this is particularly helpful if your whole application is time-sensitive. It allows you to build your test data at a single point in time, and to move in/out of that time as appropriate (within your tests)

in config/environments/test.rb 

  config.after_initialize do
    # Set Time.now to September 1, 2008 10:05:00 AM (at this instant), but allow it to move forward
    t = Time.local(2008, 9, 1, 10, 5, 0)
    Timecop.travel(t)
  end

The difference between Timecop.freeze and Timecop.travel

#freeze is used to statically mock the concept of now. As your program executes, Time.now will not change unless you make subsequent calls into the Timecop API. #travel, on the other hand, computes an offset between what we currently think Time.now is (recall that we support nested traveling) and the time passed in. It uses this offset to simulate the passage of time. To demonstrate, consider the following code snippets: 

  new_time = Time.local(2008, 9, 1, 12, 0, 0)
  Timecop.freeze(new_time)
  sleep(10)
  new_time == Time.now # ==> true

  Timecop.return # "turn off" Timecop
  Timecop.travel(new_time)
  sleep(10)
  new_time == Time.now # ==> false

DEPENDENCIES

  • None

INSTALL

  • sudo gem install timecop (latest stable version from rubyforge)
  • sudo gem install jtrupiano-timecop (HEAD of the repo from github)

REFERENCES