Timecop is a Ruby gem that provides time travel, time freezing, and time acceleration capabilities for testing time-dependent code. It mocks Time.now, Date.today, DateTime.now, and Process.clock_gettime through a unified API, eliminating the need to mock each separately.
The gem solves the problem of testing code whose behavior depends on the current time. It offers three distinct modes of operation: freeze locks time to a specific point so Time.now returns the same value on repeated calls; travel sets time to a specific point but allows it to advance naturally from there; and scale accelerates time by a given factor to simulate the passage of days or months in seconds. The tool supports flexible argument formats including Time, DateTime, and Date instances, individual date components, or integer offsets in seconds. Nested calls to freeze and travel are supported, with each block maintaining its own interpretation of the current time.
Timecop suits any Ruby project that needs to test time-sensitive functionality, from simple scripts to Rails applications. It has no external dependencies and works equally well in both contexts. The gem is particularly valuable for Rails applications where you can configure it globally in the test environment to build test data at a single point in time and move through it as needed. Safe mode is available to enforce block-based usage, ensuring time is always restored after each operation. The tool also provides optional mocking of Process.clock_gettime, which must be explicitly enabled.
The project maintains a straightforward codebase with clear separation between its three core features. Development activity shows attention to edge cases, particularly around Rails and Ruby Date/Time library interactions, with documentation noting potential issues when mixing Rails date methods like Date.tomorrow with Ruby's Date.today. The maintainer has preserved the original creator's work while actively managing contributions and addressing compatibility concerns.
