Develop faster and manage open source risks with the Tidelift Subscription.
Learn more

nard-tech/timecop

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.

INSTALL

gem install timecop

FEATURES

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 Time.now

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

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 dueTimecop.freeze(Date.today +30) do
assert joe.mortgage_due?
end

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

describe "some set of tests to mock"do
before doTimecop.freeze(Time.local(1990))
end
after doTimecop.return
end
it "should do blah blah blah"doendend

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)

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:

Timecop.scale

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.

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

Timecop.safe_mode

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 modeTimecop.safe_mode =true# check if you are in safe modeTimecop.safe_mode?
# => true# using method without blockTimecop.freeze
# => Timecop::SafeModeException: Safe mode is enabled, only calls passing a block are allowed.