Build Status


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,, and in a single call.


gem install timecop


  • Freeze time to a specific point.
  • Travel back to a specific point in time, but allow time to continue moving forward from there.
  • Scale time by a given scaling factor that will cause time to move at an accelerated pace.
  • No dependencies, can be used with any ruby project
  • 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
  • Nested calls to Timecop#travel and Timecop#freeze are supported -- each block will maintain its interpretation of now.
  • Works with regular Ruby projects, and Ruby on Rails projects


Run a time-sensitive test

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

You can mock the time for a set of tests easily via setup/teardown methods

describe "some set of tests to mock" do
  before do

  after do

  it "should do blah blah blah" do

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 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)

The difference between Timecop.freeze and

freeze is used to statically mock the concept of now. As your program executes, 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 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)
new_time == # ==> true

Timecop.return # "turn off" Timecop
new_time == # ==> false


Let's say you want to test a "live" integration wherein entire days could pass by in minutes while you're able to simulate "real" activity. For example, one such use case is being able to test reports and invoices that run in 30 day cycles in very little time, while also being able to simulate activity via subsequent calls to your application.

# seconds will now seem like hours
# => 2012-09-20 21:23:25 -0500
# seconds later, hours have passed and it's gone from 9pm at night to 6am in the morning
# => 2012-09-21 06:22:59 -0500

See #42 for more information, thanks to Ken Mayer, David Holcomb, and Pivotal Labs.


Safe mode forces you to use Timecop with the block syntax since it always puts time back the way it was. If you are running in safe mode and use Timecop without the block syntax Timecop::SafeModeException will be raised to tell the user they are not being safe.

# turn on safe mode
Timecop.safe_mode = true

# check if you are in safe mode
# => true

# using method without block
# => Timecop::SafeModeException: Safe mode is enabled, only calls passing a block are allowed.

Rails v Ruby Date/Time libraries

Sometimes Rails Date/Time methods don't play nicely with Ruby Date/Time methods.

Be careful mixing Ruby with Rails Date.tomorrow / Date.yesterday as things might break.


timecop is maintained by travisjeffery, and was created by jtrupiano.

Here's the most direct way to get your work merged into the project.

  • Fork the project
  • Clone down your fork
  • Create a feature branch
  • Hack away and add tests, not necessarily in that order
  • Make sure everything still passes by running tests
  • If necessary, rebase your commits into logical chunks without errors
  • Push the branch up to your fork
  • Send a pull request for your branch

Project Statistics

Sourcerank 1
Repository Size 0 Bytes
Stars 0
Forks 0
Watchers 0
Open issues 0
Dependencies 11
Contributors 45
Tags 40
Last updated
Last pushed

Top Contributors See all

Travis Jeffery John Trupiano Tim Brown Ry Biesemeyer Micah Chalmer Mikhail Pospelov Michael Grosser stopdropandrew John Duff Larry Marburger Olle Jonsson Joel Chippindale Alex Tuomas Kareinen Remon Oldenbeuving Chris Gunther Matthew Schulkind Olivier Lacan Cameron Dutro Akira Matsuda

Recent Tags See all

v0.9.0 June 22, 2017
v0.8.0 July 28, 2015
0.7.4 May 31, 2015
0.7.3 February 19, 2015
0.7.2 February 19, 2015
v0.7.1 December 30, 2013
v0.7.0 November 30, 2013
v0.6.3 August 04, 2013
v0.6.2.2 July 20, 2013
v0.6.2.1 July 20, 2013
v0.6.2 July 14, 2013
v0.6.1 March 11, 2013
v0.6.0 March 08, 2013
v0.5.9.2 February 11, 2013
v0.5.9.1 January 21, 2013

Something wrong with this page? Make a suggestion

Last synced: 2017-07-18 10:41:00 UTC

Login to resync this repository