Timecop is a RubyGem 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.

Documentation is hosted at RubyForge. The source code is hosted at GitHub.

Updates include:

Maintenance

• Fix various timezone-related issues. Notably, when traveling to a DateTime
  instance specified in a non-local timezone, convert provided DateTime
  instance to a local instance and return that from DateTime.now.
  Code contributed by Michaël Witrant [piglop]
• Fix bug that would not allow Timecop to be used when Ruby’s ‘date’
  library had not been previously loaded.
  Code contributed by Tuomas Kareinen [tuomas]
• Fix bug when traveling to a DateTime across a DST boundary that
  resulted in DateTime’s being off by an hour.
• Migrate argument parsing into Timecop::TimeStackItem to reduce the
  responsibility of the Timecop class.

Timecop is a RubyGem 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.

Documentation is on RubyForge. The source code is hosted at GitHub.

Updates include:

API

• Completely remove Timecop#unset_all (deprecated by Timecop#return in 0.2.0)
• Return Time.now from #freeze, #travel and #return — code contributed by Keith Bennett (keithrbennett)

Maintenance

• Fix bug that left Time#mock_time set in some instances
• Upped build dependency to jeweler ~> 1.2.1
• Don’t pollute top-level namespace with classes/constants

Documentation

• Clearer examples in the README, better description in the gemspec
• Improve RDoc

The primary feature added was the distinction between “freezing” and “rebasing” time. In 0.1.0, Timecop.travel would actually freeze time. This is no longer the case. Rather, a time offset will be calculated, and a running clock is simulated by always offsetting the time returned by Time.now (and friends) by the original offset.

(Note that time can still be frozen with Timecop.freeze.)

To update a previous version:

sudo gem update timecop

To install for the first time:

sudo gem install timecop

The new feature set allows us to avoid the following common pitfalls that were present in 0.1.0.

1. In rails, if you had set up a time mock in the development environment, then every time you invoked script/generate migration (and others), the generator would read your mocked instance of Time.now, and use that date for the migration name.
2. Any benchmarking/timing code executed within the yielded block would always return times of 0 seconds. This was due to time being frozen.

The other major change to the API was the deprecating of Timecop.unset_all in favor or Timecop.return.

This update also vastly improves the rdoc, making the public API much more accessible. The Timecop class has particularly thorough documentation.

For a more complete description of the gem, please refer to the introductory blog post.

This past weekend I released v0.1.0 of the Timecop gem. Timecop makes it dead simple to travel through or freeze time for the sake of creating a predictable and ultimately testable scenario.

The gem is derived from a plugin I wrote a while back to achieve more or less the same functionality for an extremely time-sensitive application. My goals for the gem included:

1. Drop-in-ability: The primary goal is to allow your app to continue to use Time.now, Date.today and DateTime.now as normal within your application. No overloading of functions with optional arguments (a la today=Date.today) just so you can write test cases.
2. Environment independence: I wanted the gem to work (a) w/ rails (ActiveSupport actually), (b) w/ plain ruby when the ‘date’ library has been loaded, and (c) w/ plain ruby when the ‘date’ library had not been loaded.
3. Library independence: I could have utilized mocha to achieve the mocking functionality found under the hood, but because I wanted this to work with plain vanilla ruby, libraries like mocha are out.
4. Short-term time travel: I wanted to expose the ability to temporarily change the concept of “now.” This is particularly helpful when writing tests where time needs to pass.
5. Long-range time travel: I wanted to expose the ability to change the concept of “now” for an indeterminate period of time. This is particularly helpful when setting up a rails test environment along with the test data.
6. Nested time travel: I wanted to provide the ability to nest traveling, allowing the state to be kept within each block (we’ll see an example later).

The gem is hosted on RubyForge and can be installed by simply running:

sudo gem install timecop

Using Timecop

The most basic example is to utilize this within a test. Consider the following test case:

require 'timecop'
require 'test/unit'
 
class MyTestCase < Test::Unit::TestCase
  def test_mortgage_due_in_30_days
    john = User.find(1)
    john.sign_mortgage!
    assert !john.mortgage_payment_due?
    Timecop.travel(Time.now + 30.days) do
      assert john.mortgage_payment_due?
    end
  end
end

What’s nice about this API is that the #travel function will take several different object types. You can pass a Time instance, a Date instance, a DateTime instance, or individual time parameters (the same arguments Time.local()) takes. Also, if you’re a big fan of the chronic gem, then you can easily combine these two:

Timecop.travel(Chronic.parse('this tuesday 5:00')) do
  # test-fu
end

For some applications, you may find it useful to completely re-base the concept of “now” for your test environment. Whenever time-sensitivity is a major priority for your application (e.g. an ordering and delivery system, or any system that encapsulates the concept of “availability” at a particularly fine-grained level) , you may find it useful to “root” your test data at a particular point in time, allowing you to write very specific tests that don’t fall victim to the unstoppable march of real time.

To achieve a static date for your entire test environment, you can simply drop the following into config/environments/test.rb (or config/test/environment.rb if you use environmentalist):

# Setting "now" to May 15, 2008 10:00:00 AM
Timecop.travel(Time.local(2008, 5, 15, 10, 0, 0))

This will cause your whole application to run at a static time. As mentioned previously, this is particularly important for creating static test cases. You may think that you can achieve this by always using relative times, but this proves much more difficult than initially perceived. For example, let’s consider the following scenario, which is an extension of the mortgage example beforehand. Let’s say the business rule is that a mortgage payment is due every month on the same date as the lease is signed, except for when that day falls on a weekend, in which case the payment would be due the following Monday. As such, it’s extremely crucial for us to write a test case where we know the date in the next month falls on a weekend, and a separate test case where the date in the next month falls on a weekday. As such, there are certain months where the following test (not using Timecop) would fail:

require 'test/unit'
 
class MyTestCase < Test::Unit::TestCase
  def test_mortgage_due_in_30_days
    john = User.find(1)
    john.sign_mortgage!
    assert !john.mortgage_payment_due?
    assert john.mortgage_payment_due?(Chronic.parse("1 month from now"))
  end
end

Furthermore, you’ll notice I had to pass a date to the mortgage_payment_due? function, essentially requiring me to change the signature of that function to take an optional date argument. Basically, in order to test my application, I’ve had to go ahead and change my actual code! Something clearly smells here. Another option would be to use mocha to mock Time.now. However, mocha has its own limitations with its inability to unmock. Lastly, specifically mocking Time.now would leave us high and dry if our implementation decided to start using DateTime.now for comparison in lieu of Time.now.

Another feature that I want to illustrate is the ability to nest #travel commands. The following assertions will all pass:

   # this test is taken directly from the test/test_timecop.rb
  def test_recursive_travel
    t = Time.local(2008, 10, 10, 10, 10, 10)
    Timecop.travel(2008, 10, 10, 10, 10, 10) do 
      assert_equal t, Time.now
      t2 = Time.local(2008, 9, 9, 9, 9, 9)
      Timecop.travel(2008, 9, 9, 9, 9, 9) do
        assert_equal t2, Time.now
      end
      assert_equal t, Time.now
    end
    assert_nil Time.send(:mock_time)
  end

Lastly, Timecop handles the scenario where exceptions are raised within the blocks passed to the #travel function.

  # this test is taken directly from the test/test_timecop.rb
  def test_exception_thrown_in_travel_block_properly_resets_time
    t = Time.local(2008, 10, 10, 10, 10, 10)
    begin
      Timecop.travel(t) do
        assert_equal t, Time.now
        raise "blah exception"
      end
    rescue
      assert_not_equal t, Time.now
      assert_nil Time.send(:mock_time)
    end
  end

Timecop is useful both in small and large consumption. Just as mocha can be helpful to give you a quick mock here and there, Timecop can help guide you very easily through testing the few time-sensitive parts of your application. And for those unique applications where everything is time-sensitive, Timecop gives you a very simple way to stabilize your concept of now.