lib/timecop/stack_item.rb test/run_tests.sh test/test_timecop_internals.rb test/test_timecop_without_date.rb @@ -1,3 +1,29 @@ +=== 0.2.0 / 2008-12-23 + +* API Changes + + * Timecop#travel no longer freezes time. Rather, it computes the current offset between the new "now" and the real "now", and + returns times as if Time had continued to move forward + + * Timecop#freeze now behaves exactly as the old Timecop#travel behaved. Unless you depended on the actual freezing of time + (which I think would be rare), you should be able to continue to use #travel without worry. + + * Timecop#return is now exposed (previously Timecop#unset_all, but not well advertised). It will completely unmock time, + and will probably be rarely used outside of the actual implementation of this library. + +* More Test Coverage + + * Tests now explicitly cover the cases when the Date and DateTime objects are not loaded, and ensures proper functionality + in their absence and existence. + + * Still haven't done regression testing against anything other than a few version of 1.8.6 (including REE). We should + probably try to get this tested on both 1.8.7 and 1.9.1. + +* Documentation + + * Fixed up a lot of the poorly-formatted rdoc syntax. The public API should now be properly published in the rdoc, + and the internals are omitted. + === 0.1.0 / 2008-11-09 * Initial Feature Set History.txt @@ -3,8 +3,12 @@ Manifest.txt README.txt Rakefile lib/timecop.rb +lib/timecop/stack_item.rb lib/timecop/time_extensions.rb lib/timecop/timecop.rb lib/timecop/version.rb +test/run_tests.sh test/test_timecop.rb +test/test_timecop_internals.rb +test/test_timecop_without_date.rb timecop.gemspec Manifest.txt @@ -31,3 +31,13 @@ end # vim: syntax=Ruby +# Override the test task and instruct them how to actually run the tests. +Rake.application.send(:eval, "@tasks.delete('test')") +desc "Does not execute tests. Manually run shell script ./run_tests.sh to execute tests." +task :test do + puts <<-MSG + In order to run the test suite, run: cd test && ./run_tests.sh + The tests need to be run with different libraries loaded, which rules out using Rake + to automate them. + MSG +end Rakefile @@ -1,26 +1,25 @@ -require File.join(File.dirname(__FILE__), 'time_extensions') require 'singleton' +require File.join(File.dirname(__FILE__), 'time_extensions') +require File.join(File.dirname(__FILE__), 'stack_item') -# 1. Wrapper class for manipulating the extensions to the Time, Date, and DateTime objects -# 2. Allows us to "freeze" time in our Ruby applications. -# 3. Optionally allows time travel to simulate a running clock, such time is not technically frozen. -# 4. This is very useful when your app's functionality is dependent on time (e.g. +# Timecop +# * Wrapper class for manipulating the extensions to the Time, Date, and DateTime objects +# * Allows us to "freeze" time in our Ruby applications. +# * Optionally allows time travel to simulate a running clock, such time is not technically frozen. +# +# This is very useful when your app's functionality is dependent on time (e.g. # anything that might expire). This will allow us to alter the return value of # Date.today, Time.now, and DateTime.now, such that our application code _never_ has to change. -class StackItem - - attr_reader :mock_type, :year, :month, :day, :hour, :minute, :second - def initialize(mock_type, year, month, day, hour, minute, second) - @mock_type, @year, @month, @day, @hour, @minute, @second = mock_type, year, month, day, hour, minute, second - end -end - class Timecop - include Singleton + # Timecop + # 1. Wrapper class for manipulating the extensions to the Time, Date, and DateTime objects + # 2. Allows us to "freeze" time in our Ruby applications. + # 3. Optionally allows time travel to simulate a running clock, such time is not technically frozen. + # 4. This is very useful when your app's functionality is dependent on time (e.g. + # anything that might expire). This will allow us to alter the return value of + # Date.today, Time.now, and DateTime.now, such that our application code _never_ has to change. - def initialize - @_stack = [] - end + include Singleton # Allows you to run a block of code and "fake" a time throughout the execution of that block. # This is particularly useful for writing test methods where the passage of time is critical to the business @@ -30,67 +29,99 @@ class Timecop # joe = User.find(1) # joe.purchase_home() # assert !joe.mortgage_due? - # Timecop.travel(2008, 10, 5) do + # Timecop.freeze(2008, 10, 5) do # assert joe.mortgage_due? # end # </code> # - # travel will respond to several different arguments: - # 1. Timecop.travel(time_inst) - # 2. Timecop.travel(datetime_inst) - # 3. Timecop.travel(date_inst) - # 4. Timecop.travel(year, month, day, hour=0, minute=0, second=0) + # freeze and travel will respond to several different arguments: + # 1. Timecop.freeze(time_inst) + # 2. Timecop.freeze(datetime_inst) + # 3. Timecop.freeze(date_inst) + # 4. Timecop.freeze(year, month, day, hour=0, minute=0, second=0) # - # When a block is also passed, the Time.now, DateTime.now and Date.today are all reset to their + # When a block is also passed, Time.now, DateTime.now and Date.today are all reset to their # previous values. This allows us to nest multiple calls to Timecop.travel and have each block # maintain it's concept of "now." - def self.travel(*args, &block) - instance().travel(:freeze, *args, &block) + # + # * Note: Timecop.freeze will actually freeze time. This can cause unanticipated problems if + # benchmark or other timing calls are executed, which implicitly expect Time to actually move + # forward. + # + # * Rails Users: Be especially careful when setting this in your development environment in a + # rails project. Generators will load your environment, including the migration generator, + # which will lead to files being generated with the timestamp set by the Timecop.freeze call + # in your dev environment + def self.freeze(*args, &block) + instance().send(:travel, :freeze, *args, &block) end - def self.rebase(*args, &block) - instance().travel(:move, *args, &block) + # Allows you to run a block of code and "fake" a time throughout the execution of that block. + # See Timecop#freeze for a sample of how to use (same exact usage syntax) + # + # * Note: Timecop.travel will not freeze time (as opposed to Timecop.freeze). This is a particularly + # good candidate for use in environment files in rails projects. + def self.travel(*args, &block) + instance().send(:travel, :move, *args, &block) end # Reverts back to system's Time.now, Date.today and DateTime.now (if it exists). If freeze_all or rebase_all # was never called in the first place, this method will have no effect. + def self.return + instance().send(:unmock!) + end + + # [Deprecated]: See Timecop#return instead. def self.unset_all - instance().unmock! + $stderr.puts "Timecop#unset_all is deprecated. Please use Timecop#return instead." + $stderr.flush + self.return end + protected - def travel(mock_type, *args, &block) - year, month, day, hour, minute, second = parse_travel_args(*args) - - if mock_type == :freeze - freeze_all(year, month, day, hour, minute, second) - else - move_all(year, month, day, hour, minute, second) + def initialize + @_stack = [] end - @_stack << StackItem.new(mock_type, year, month, day, hour, minute, second) - if block_given? - begin - yield - ensure - stack_item = @_stack.pop - if @_stack.size == 0 - unmock! - else - new_top = @_stack.last - if new_top.mock_type == :freeze - freeze_all(new_top.year, new_top.month, new_top.day, new_top.hour, new_top.minute, new_top.second) + def travel(mock_type, *args, &block) + # parse the arguments, build our base time units + year, month, day, hour, minute, second = parse_travel_args(*args) + + # perform our action + if mock_type == :freeze + freeze_all(year, month, day, hour, minute, second) + else + move_all(year, month, day, hour, minute, second) + end + # store this time traveling on our stack... + @_stack << StackItem.new(mock_type, year, month, day, hour, minute, second) + + if block_given? + begin + yield + ensure + # pull it off the stack... + stack_item = @_stack.pop + if @_stack.size == 0 + # completely unmock if there's nothing to revert back to + unmock! else - move_all(new_top.year, new_top.month, new_top.day, new_top.hour, new_top.minute, new_top.second) + # or reinstantiate the new the top of the stack (could be a :freeze or a :move) + new_top = @_stack.last + if new_top.mock_type == :freeze + freeze_all(new_top.year, new_top.month, new_top.day, new_top.hour, new_top.minute, new_top.second) + else + move_all(new_top.year, new_top.month, new_top.day, new_top.hour, new_top.minute, new_top.second) + end end end end end - end - def unmock! - Time.unmock! - end + def unmock! + Time.unmock! + end private @@ -112,6 +143,12 @@ class Timecop Time.freeze_time(time) end + # Re-bases Time.now, Date.today and DateTime.now to use the time passed in and to continue moving time + # forward. When using this method directly, it is up to the developer to call return to return us to + # sanity. + # + # * If being consumed in a rails app, Time.zone.local will be used to instantiate the time. + # Otherwise, Time.local will be used. def move_all(year, month, day, hour=0, minute=0, second=0) if Time.respond_to?(:zone) && !Time.zone.nil? # ActiveSupport loaded lib/timecop/timecop.rb @@ -11,37 +11,37 @@ class TestTimecop < Test::Unit::TestCase # just in case...let's really make sure that Timecop is disabled between tests... def teardown - Timecop.unset_all + Timecop.return end - def test_travel_changes_and_resets_time + def test_freeze_changes_and_resets_time # depending on how we're invoked (individually or via the rake test suite) assert !Time.respond_to?(:zone) || Time.zone.nil? t = Time.local(2008, 10, 10, 10, 10, 10) assert_not_equal t, Time.now - Timecop.travel(2008, 10, 10, 10, 10, 10) do + Timecop.freeze(2008, 10, 10, 10, 10, 10) do assert_equal t, Time.now end assert_not_equal t, Time.now end - def test_recursive_travel + def test_recursive_freeze t = Time.local(2008, 10, 10, 10, 10, 10) - Timecop.travel(2008, 10, 10, 10, 10, 10) do + Timecop.freeze(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 + Timecop.freeze(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) + assert_not_equal t, Time.now end - def test_travel_with_time_instance_works_as_expected + def test_freeze_with_time_instance_works_as_expected t = Time.local(2008, 10, 10, 10, 10, 10) - Timecop.travel(t) do + Timecop.freeze(t) do assert_equal t, Time.now assert_equal DateTime.new(2008, 10, 10, 10, 10, 10), DateTime.now assert_equal Date.new(2008, 10, 10), Date.today @@ -51,9 +51,9 @@ class TestTimecop < Test::Unit::TestCase assert_not_equal Date.new(2008, 10, 10), Date.today end - def test_travel_with_datetime_instance_works_as_expected + def test_freeze_with_datetime_instance_works_as_expected t = DateTime.new(2008, 10, 10, 10, 10, 10) - Timecop.travel(t) do + Timecop.freeze(t) do assert_equal t, DateTime.now assert_equal Time.local(2008, 10, 10, 10, 10, 10), Time.now assert_equal Date.new(2008, 10, 10), Date.today @@ -63,9 +63,9 @@ class TestTimecop < Test::Unit::TestCase assert_not_equal Date.new(2008, 10, 10), Date.today end - def test_travel_with_date_instance_works_as_expected + def test_freeze_with_date_instance_works_as_expected d = Date.new(2008, 10, 10) - Timecop.travel(d) do + Timecop.freeze(d) do assert_equal d, Date.today assert_equal Time.local(2008, 10, 10, 0, 0, 0), Time.now assert_equal DateTime.new(2008, 10, 10, 0, 0, 0), DateTime.now @@ -75,10 +75,10 @@ class TestTimecop < Test::Unit::TestCase assert_not_equal DateTime.new(2008, 10, 10, 0, 0, 0), DateTime.now end - def test_exception_thrown_in_travel_block_properly_resets_time + def test_exception_thrown_in_freeze_block_properly_resets_time t = Time.local(2008, 10, 10, 10, 10, 10) begin - Timecop.travel(t) do + Timecop.freeze(t) do assert_equal t, Time.now raise "blah exception" end @@ -88,13 +88,13 @@ class TestTimecop < Test::Unit::TestCase end end - def test_travel_freezes_time + def test_freeze_freezes_time t = Time.local(2008, 10, 10, 10, 10, 10) now = Time.now - Timecop.travel(t) do - #assert Time.now < now, "If we had failed to rebase, time would have proceeded, which is what appears to have happened." + Timecop.freeze(t) do + #assert Time.now < now, "If we had failed to freeze, time would have proceeded, which is what appears to have happened." new_t, new_d, new_dt = Time.now, Date.today, DateTime.now - assert_equal t, new_t, "Failed to change move time." # 2 seconds + assert_equal t, new_t, "Failed to freeze time." # 2 seconds #sleep(10) assert_equal new_t, Time.now assert_equal new_d, Date.today @@ -102,12 +102,12 @@ class TestTimecop < Test::Unit::TestCase end end - def test_rebasing_keeps_time_moving + def test_travel_keeps_time_moving t = Time.local(2008, 10, 10, 10, 10, 10) now = Time.now - Timecop.rebase(t) do - #assert Time.now < now, "If we had failed to rebase, time would have proceeded, which is what appears to have happened." - assert Time.now - t < 2000, "Looks like we failed to actually rebase time" # 2 seconds + Timecop.travel(t) do + #assert Time.now < now, "If we had failed to freeze, time would have proceeded, which is what appears to have happened." + assert Time.now - t < 2000, "Looks like we failed to actually travel time" # 2 seconds new_t = Time.now #sleep(10) assert_not_equal new_t, Time.now @@ -116,89 +116,43 @@ class TestTimecop < Test::Unit::TestCase def test_recursive_rebasing_maintains_each_context t = Time.local(2008, 10, 10, 10, 10, 10) - Timecop.rebase(2008, 10, 10, 10, 10, 10) do - assert((t - Time.now).abs < 50, "Failed to rebase time.") + Timecop.travel(2008, 10, 10, 10, 10, 10) do + assert((t - Time.now).abs < 50, "Failed to travel time.") t2 = Time.local(2008, 9, 9, 9, 9, 9) - Timecop.rebase(2008, 9, 9, 9, 9, 9) do - assert((t2 - Time.now) < 50, "Failed to rebase time.") - assert((t - Time.now) > 1000, "Failed to rebase time.") + Timecop.travel(2008, 9, 9, 9, 9, 9) do + assert((t2 - Time.now) < 50, "Failed to travel time.") + assert((t - Time.now) > 1000, "Failed to travel time.") end - assert((t - Time.now).abs < 2000, "Failed to restore previously-rebased time.") + assert((t - Time.now).abs < 2000, "Failed to restore previously-traveled time.") end assert_nil Time.send(:mock_time) end - def test_recursive_rebase_then_travel + def test_recursive_travel_then_freeze t = Time.local(2008, 10, 10, 10, 10, 10) - Timecop.rebase(2008, 10, 10, 10, 10, 10) do - assert((t - Time.now).abs < 50, "Failed to rebase time.") + Timecop.travel(2008, 10, 10, 10, 10, 10) do + assert((t - Time.now).abs < 50, "Failed to travel time.") t2 = Time.local(2008, 9, 9, 9, 9, 9) - Timecop.travel(2008, 9, 9, 9, 9, 9) do + Timecop.freeze(2008, 9, 9, 9, 9, 9) do assert_equal t2, Time.now end - assert((t - Time.now).abs < 2000, "Failed to restore previously-rebased time.") + assert((t - Time.now).abs < 2000, "Failed to restore previously-traveled time.") end assert_nil Time.send(:mock_time) end - def test_recursive_travel_then_rebase + def test_recursive_freeze_then_travel t = Time.local(2008, 10, 10, 10, 10, 10) - Timecop.travel(t) do + Timecop.freeze(t) do assert_equal t, Time.now t2 = Time.local(2008, 9, 9, 9, 9, 9) - Timecop.rebase(t2) do - assert((t2 - Time.now) < 50, "Failed to rebase time.") - assert((t - Time.now) > 1000, "Failed to rebase time.") + Timecop.travel(t2) do + assert((t2 - Time.now) < 50, "Failed to travel time.") + assert((t - Time.now) > 1000, "Failed to travel time.") end assert_equal t, Time.now end assert_nil Time.send(:mock_time) end - def test_parse_travel_args_with_time - t = Time.now - y, m, d, h, min, s = t.year, t.month, t.day, t.hour, t.min, t.sec - ty, tm, td, th, tmin, ts = Timecop.instance().send(:parse_travel_args, t) - assert_equal y, ty - assert_equal m, tm - assert_equal d, td - assert_equal h, th - assert_equal min, tmin - assert_equal s, ts - end - - def test_parse_travel_args_with_datetime - t = DateTime.now - y, m, d, h, min, s = t.year, t.month, t.day, t.hour, t.min, t.sec - ty, tm, td, th, tmin, ts = Timecop.instance().send(:parse_travel_args, t) - assert_equal y, ty - assert_equal m, tm - assert_equal d, td - assert_equal h, th - assert_equal min, tmin - assert_equal s, ts - end - - def test_parse_travel_args_with_date - date = Date.today - y, m, d, h, min, s = date.year, date.month, date.day, 0, 0, 0 - ty, tm, td, th, tmin, ts = Timecop.instance().send(:parse_travel_args, date) - assert_equal y, ty - assert_equal m, tm - assert_equal d, td - assert_equal h, th - assert_equal min, tmin - assert_equal s, ts - end - - def test_parse_travel_args_with_individual_arguments - y, m, d, h, min, s = 2008, 10, 10, 10, 10, 10 - ty, tm, td, th, tmin, ts = Timecop.instance().send(:parse_travel_args, y, m, d, h, min, s) - assert_equal y, ty - assert_equal m, tm - assert_equal d, td - assert_equal h, th - assert_equal min, tmin - assert_equal s, ts - end end \ No newline at end of file test/test_timecop.rb @@ -6,11 +6,11 @@ Gem::Specification.new do |s| s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version= s.authors = ["John Trupiano"] - s.date = %q{2008-12-07} + s.date = %q{2008-12-23} s.description = %q{A gem providing simple ways to temporarily override Time.now, Date.today, and DateTime.now. It provides "time travel" capabilities, making it dead simple to write test time-dependent code.} s.email = %q{jtrupiano@gmail.com} s.extra_rdoc_files = ["History.txt", "Manifest.txt", "README.txt"] - s.files = ["History.txt", "Manifest.txt", "README.txt", "Rakefile", "lib/timecop.rb", "lib/timecop/time_extensions.rb", "lib/timecop/timecop.rb", "lib/timecop/version.rb", "test/test_timecop.rb", "timecop.gemspec", "test/test_timecop_with_rails.rb", "test/test_timecop_without_date.rb"] + s.files = ["History.txt", "Manifest.txt", "README.txt", "Rakefile", "lib/timecop.rb", "lib/timecop/stack_item.rb", "lib/timecop/time_extensions.rb", "lib/timecop/timecop.rb", "lib/timecop/version.rb", "test/run_tests.sh", "test/test_timecop.rb", "test/test_timecop_internals.rb", "test/test_timecop_without_date.rb", "timecop.gemspec"] s.has_rdoc = true s.homepage = %q{http://github.com/jtrupiano/timecop} s.rdoc_options = ["--main", "README.txt"] @@ -18,7 +18,7 @@ Gem::Specification.new do |s| s.rubyforge_project = %q{johntrupiano} s.rubygems_version = %q{1.3.1} s.summary = %q{A gem providing simple ways to temporarily override Time.now, Date.today, and DateTime.now. It provides "time travel" capabilities, making it dead simple to write test time-dependent code.} - s.test_files = ["test/test_timecop.rb", "test/test_timecop_with_rails.rb", "test/test_timecop_without_date.rb"] + s.test_files = ["test/test_timecop.rb", "test/test_timecop_internals.rb", "test/test_timecop_without_date.rb"] if s.respond_to? :specification_version then current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION timecop.gemspec 332482f03fa69834672964cfab25307f6a9c5a16 John Trupiano john@john-mbp.local http://github.com/jtrupiano/timecop/commit/c67c11ba041b36199bdd5fb6bf5e8b9c5679caec c67c11ba041b36199bdd5fb6bf5e8b9c5679caec 2008-12-23T19:17:01-08:00 2008-12-23T19:17:01-08:00 Completed the 0.2.0 feature set. Broader testing, better documentation, and now we can rebase (and not just freeze) time. 3032c656e95bb11d323892f30d476a5853ee3e25 John Trupiano john@john-mbp.local