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

As a Ruby programmer, I’ve come to love test-driven programming. As such, I’ve made an effort recently to build a test-based workflow into this existing codebase (not always the easiest thing to do, applying a test-base to a large existing codebase). Today I found myself in dire need of being able to test private functions in C++. As a testament to the poor state of testing in other programming languages, many message boards/threads simply told me that I was testing the wrong thing (you should test the public API, not the private implementation). Well, needless to say, this left me a bit uncomfortable. The fact is, the majority of my code is tucked into private methods, and I’d be left with huge long-running end-to-end tests if I strictly followed this heuristic.

However, I came across one golden nugget, one of the most clever hacks I’ve seen in some time. By utilizing pre-processor directives, we can temporarily override the meaning of private and protected in C++ code, essentially aliasing it to public.

 #define protected public
 #define private   public
 #include "TheClassHeaderUnderTest.h"
 #undef protected
 #undef private

See what this is doing? We wrap the class that we’ll be testing in pre-processor directives to interpret protected and private as an alias for public, essentially loading that class (when including the header file) as entirely public. This allows me to access everything! Private methods, private variables, you name it. And now, just like in Ruby, it’s no holds barred, allowing me to poke and prod my objects without being wrapped on the wrist by the compiler.

Even better, these directives simply wrap your includes in your test files. In other words, I don’t have to change my implementation to achieve this.

A clever hack, no matter the language or technology, is a clever hack. And I absolutely love this hack.

Credit: I discovered this technique as a comment on this wiki.

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.