jtrupiano-timecop 0.1.0

data/History.txt

@@ -0,0 +1,9 @@
+=== 0.1.0 / 2008-11-09
+
+* Initial Feature Set
+
+  * Temporarily (or permanently if you prefer) change the concept of Time.now, DateTime.now (if defined), and Date.today (if defined)
+  * Timecop#travel api allows an argument to be passed in as one of: 1) Time instance, 2) DateTime instance, 3) Date instance,
+    4) individual arguments (year, month, day, hour, minute, second)
+  * Nested calls to Timecop#travel are supported -- each block will maintain it's interpretation of now.
+

data/Manifest.txt

@@ -0,0 +1,10 @@
+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

data/README.txt

@@ -0,0 +1,75 @@
+= timecop
+
+* http://github.com/jtrupiano/timecop
+
+== DESCRIPTION:
+
+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.
+
+== FEATURES/PROBLEMS:
+
+* Temporarily (or permanently if you prefer) change the concept of Time.now, DateTime.now (if defined), and Date.today (if defined)
+* Timecop#travel api allows an argument to be passed in as one of: 1) Time instance, 2) DateTime instance, 3) Date instance,
+  4) individual arguments (year, month, day, hour, minute, second)
+* Nested calls to Timecop#travel are supported -- each block will maintain it's interpretation of now.
+
+== SYNOPSIS:
+
+* Run a time-sensitive test:
+<code>
+  joe = User.find(1)
+  joe.purchase_home()
+  assert !joe.mortgage_due?
+  # move ahead a month and assert that the mortgage is due
+  Timecop.travel(Date.today + 30) do
+    assert joe.mortgage_due?
+  end
+</code>
+
+* 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
+
+<code>
+config.after_initialize do
+  # Set Time.now to September 1, 2008 10:05:00 AM
+  t = Time.local(2008, 9, 1, 10, 5, 0)
+  Timecop.travel(t)
+end
+</code>
+
+== REQUIREMENTS:
+
+* None
+
+== INSTALL:
+
+* sudo gem install timecop (latest stable version from rubyforge)
+* sudo gem install jtrupiano-timecop (HEAD of the repo from github)
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2008 FIX
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,33 @@
+# -*- ruby -*-
+
+require 'rubygems'
+require 'hoe'
+require './lib/timecop/version.rb'
+
+PKG_NAME      = "timecop"
+PKG_BUILD     = ENV['PKG_BUILD'] ? '.' + ENV['PKG_BUILD'] : ''
+version = Timecop::Version::STRING.dup
+if ENV['SNAPSHOT'].to_i == 1
+  version << "." << Time.now.utc.strftime("%Y%m%d%H%M%S")
+end
+PKG_VERSION   = version
+PKG_FILE_NAME = "#{PKG_NAME}-#{PKG_VERSION}"
+
+Hoe.new(PKG_NAME, PKG_VERSION) do |p|
+  p.rubyforge_name = 'johntrupiano' # if different than lowercase project name
+  p.developer('John Trupiano', 'jtrupiano@gmail.com')
+  p.name = PKG_NAME
+  p.version = PKG_VERSION
+  #p.platform = Gem::Platform::RUBY
+  p.author = "John Trupiano"
+  p.email = "jtrupiano@gmail.com"
+  p.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.)
+  p.summary = p.description # More details later??
+  p.remote_rdoc_dir = PKG_NAME # Release to /PKG_NAME
+  #  p.changes = p.paragraphs_of('CHANGELOG', 0..1).join("\n\n")
+  p.need_zip = true
+  p.need_tar = false
+end
+
+# vim: syntax=Ruby
+

data/lib/timecop.rb

@@ -0,0 +1,3 @@
+# place gem dependencies here...
+#require 'timecop/timecop'
+require File.join(File.dirname(__FILE__), 'timecop', 'timecop')

data/lib/timecop/time_extensions.rb

@@ -0,0 +1,78 @@
+# 1. Extensions to the Time, Date, and DateTime objects
+# 2. Allows us to "freeze" time in our Ruby applications.
+# 3. 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 Time
+  class << self
+    # Time we might be behaving as
+    attr_reader :mock_time
+    
+    # Set new time to pretend we are.
+    def mock_time=(new_now)
+      @mock_time = new_now
+    end
+    
+    # Alias the original now
+    alias_method :now_without_mock_time, :now
+
+    # Define now_with_mock_time
+    def now_with_mock_time
+      mock_time || now_without_mock_time
+    end
+    
+    # Alias now to now_with_mock_time
+    alias_method :now, :now_with_mock_time
+  end
+end 
+
+if Object.const_defined?(:Date)
+  class Date
+    class << self
+      # Date we might be behaving as
+      attr_reader :mock_date
+    
+      # Set new date to pretend we are.
+      def mock_date=(new_date)
+        @mock_date = new_date
+      end
+    
+      # Alias the original today
+      alias_method :today_without_mock_date, :today
+    
+      # Define today_with_mock_date
+      def today_with_mock_date
+        mock_date || today_without_mock_date
+      end
+    
+      # Alias today to today_with_mock_date
+      alias_method :today, :today_with_mock_date
+    end
+  end
+end
+
+if Object.const_defined?(:DateTime)
+  class DateTime
+    class << self
+      # Time we might be behaving as
+      attr_reader :mock_time
+    
+      # Set new time to pretend we are.
+      def mock_time=(new_now)
+        @mock_time = new_now
+      end
+    
+      # Alias the original now
+      alias_method :now_without_mock_time, :now
+    
+      # Define now_with_mock_time
+      def now_with_mock_time
+        mock_time || now_without_mock_time
+      end
+    
+      # Alias now to now_with_mock_time
+      alias_method :now, :now_with_mock_time
+    end
+  end
+end

data/lib/timecop/timecop.rb

@@ -0,0 +1,121 @@
+require File.join(File.dirname(__FILE__), 'time_extensions')
+
+# 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. 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 Timecop
+  
+  # Re-bases Time.now, Date.today and DateTime.now (if it exists) to use the time passed in.
+  # When using this method directly, it is up to the developer to call unset_all 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 self.set_all(year, month, day, hour=0, minute=0, second=0)
+    if Time.respond_to?(:zone) && !Time.zone.nil?
+      # ActiveSupport loaded
+      time = Time.zone.local(year, month, day, hour, minute, second)
+    else 
+      # ActiveSupport not loaded
+      time = Time.local(year, month, day, hour, minute, second)
+    end
+    
+    Time.mock_time = time
+    Date.mock_date = Date.new(time.year, time.month, time.day) if Object.const_defined?(:Date)
+    DateTime.mock_time = DateTime.new(time.year, time.month, time.day, time.hour, time.min, time.sec) if Object.const_defined?(:DateTime)
+  end
+  
+  # Reverts back to system's Time.now, Date.today and DateTime.now (if it exists). If set_all
+  # was never called in the first place, this method will have no effect.
+  def self.unset_all
+    Date.mock_date = nil
+    DateTime.mock_time = nil if Object.const_defined?(:Date)
+    Time.mock_time = nil if Object.const_defined?(:DateTime)
+  end
+  
+  # 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
+  # logic being tested.  For example:
+  #
+  # <code>
+  #   joe = User.find(1)
+  #   joe.purchase_home()
+  #   assert !joe.mortgage_due?
+  #   Timecop.travel(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)
+  #
+  # When a block is also passed, the 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(year, month, day, hour=0, minute=0, second=0, &block)
+  def self.travel(*args, &block)
+    year, month, day, hour, minute, second = parse_travel_args(*args)
+
+    old_time = Time.mock_time
+    old_date = Date.mock_date if Object.const_defined?(:Date)
+    old_datetime = DateTime.mock_time if Object.const_defined?(:DateTime)
+
+    set_all(year, month, day, hour, minute, second)
+    
+    if block_given?
+      begin
+        yield
+      ensure
+        Time.mock_time = old_time
+        Date.mock_date = old_date if Object.const_defined?(:Date)
+        DateTime.mock_time = old_datetime if Object.const_defined?(:DateTime)
+      end
+    end
+  end
+  
+  private
+    def self.parse_travel_args(*args)
+      arg = args.shift
+      if arg.is_a?(Time) || (Object.const_defined?(:DateTime) && arg.is_a?(DateTime))
+        year, month, day, hour, minute, second = arg.year, arg.month, arg.day, arg.hour, arg.min, arg.sec
+      elsif Object.const_defined?(:Date) && arg.is_a?(Date)
+        year, month, day, hour, minute, second = arg.year, arg.month, arg.day, 0, 0, 0
+        puts "#{year}-#{month}-#{day} #{hour}:#{minute}:#{second}"
+      else # we'll just assume it's a list of y/m/h/d/m/s
+        year   = arg        || 0
+        month  = args.shift || 1
+        day    = args.shift || 1
+        hour   = args.shift || 0
+        minute = args.shift || 0
+        second = args.shift || 0
+      end
+      return year, month, day, hour, minute, second
+    end
+end
+
+#def with_dates(*dates, &block)
+#  dates.flatten.each do |date|
+#    begin
+#      DateTime.forced_now = case date
+#        when String: DateTime.parse(date)
+#        when Time: DateTime.parse(date.to_s)
+#        else
+#          date
+#      end
+#      Date.forced_today = Date.new(DateTime.forced_now.year,
+#DateTime.forced_now.month, DateTime.forced_now.day)
+#      yield
+#    rescue Exception => e
+#      raise e
+#    ensure
+#      DateTime.forced_now = nil
+#      Date.forced_today = nil
+#    end
+#  end
+#end 
+

data/lib/timecop/version.rb

@@ -0,0 +1,20 @@
+module Timecop
+  module Version #:nodoc:
+    # A method for comparing versions of required modules. It expects two
+    # arrays of integers as parameters, the first being the minimum version
+    # required, and the second being the actual version available. It returns
+    # true if the actual version is at least equal to the required version.
+    def self.check(required, actual) #:nodoc:
+      required = required.map { |v| "%06d" % v }.join(".")
+      actual   = actual.map { |v| "%06d" % v }.join(".")
+      return actual >= required
+    end
+
+    MAJOR = 0
+    MINOR = 1
+    TINY  = 0
+
+    STRING = [MAJOR, MINOR, TINY].join(".")
+  end
+end
+

data/test/test_timecop.rb

@@ -0,0 +1,138 @@
+
+require 'date'
+require 'test/unit'
+require File.join(File.dirname(__FILE__), '..', 'lib', 'timecop')
+
+class TestTimecop < Test::Unit::TestCase
+  
+  def setup
+    
+  end
+  
+  # just in case...let's really make sure that Timecop is disabled between tests...
+  def teardown
+    Timecop.unset_all
+  end
+  
+  def test_travel_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
+      assert_equal t, Time.now
+    end
+    assert_not_equal t, Time.now
+  end
+  
+  def test_recursive_travel
+    t = Time.local(2008, 10, 10, 10, 10, 10)
+    Timecop.travel(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
+        assert_equal t2, Time.now
+      end
+      assert_equal t, Time.now
+    end
+    assert_nil Time.send(:mock_time)
+  end
+  
+  def test_travel_with_time_instance_works_as_expected
+    t = Time.local(2008, 10, 10, 10, 10, 10)
+    Timecop.travel(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
+    end
+    assert_not_equal t, Time.now
+    assert_not_equal DateTime.new(2008, 10, 10, 10, 10, 10), DateTime.now
+    assert_not_equal Date.new(2008, 10, 10), Date.today
+  end
+  
+  def test_travel_with_datetime_instance_works_as_expected
+    t = DateTime.new(2008, 10, 10, 10, 10, 10)
+    Timecop.travel(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
+    end
+    assert_not_equal t, DateTime.now
+    assert_not_equal Time.local(2008, 10, 10, 10, 10, 10), Time.now
+    assert_not_equal Date.new(2008, 10, 10), Date.today
+  end
+  
+  def test_travel_with_date_instance_works_as_expected
+    d = Date.new(2008, 10, 10)
+    Timecop.travel(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
+    end
+    assert_not_equal d, Date.today
+    assert_not_equal Time.local(2008, 10, 10, 0, 0, 0), Time.now
+    assert_not_equal DateTime.new(2008, 10, 10, 0, 0, 0), DateTime.now    
+  end
+  
+  def test_exception_thrown_in_travel_block_properly_resets_time
+    t = Time.local(2008, 10, 10, 10, 10, 10)
+    begin
+      Timecop.travel(t) do
+        assert_equal t, Time.now
+        raise "blah exception"
+      end
+    rescue
+      assert_not_equal t, Time.now
+      assert_nil Time.send(:mock_time)
+    end
+  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.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.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.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.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

data/timecop.gemspec

@@ -0,0 +1,35 @@
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{timecop}
+  s.version = "0.1.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["John Trupiano"]
+  s.date = %q{2008-11-09}
+  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.has_rdoc = true
+  s.homepage = %q{http://github.com/jtrupiano/timecop}
+  s.rdoc_options = ["--main", "README.txt"]
+  s.require_paths = ["lib"]
+  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"]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 2
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+      s.add_development_dependency(%q<hoe>, [">= 1.8.2"])
+    else
+      s.add_dependency(%q<hoe>, [">= 1.8.2"])
+    end
+  else
+    s.add_dependency(%q<hoe>, [">= 1.8.2"])
+  end
+end

metadata

@@ -0,0 +1,77 @@
+--- !ruby/object:Gem::Specification 
+name: jtrupiano-timecop
+version: !ruby/object:Gem::Version 
+  version: 0.1.0
+platform: ruby
+authors: 
+- John Trupiano
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2008-11-09 00:00:00 -08:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: hoe
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 1.8.2
+    version: 
+description: 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.
+email: jtrupiano@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- History.txt
+- Manifest.txt
+- README.txt
+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
+has_rdoc: true
+homepage: http://github.com/jtrupiano/timecop
+post_install_message: 
+rdoc_options: 
+- --main
+- README.txt
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: johntrupiano
+rubygems_version: 1.2.0
+signing_key: 
+specification_version: 2
+summary: 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.
+test_files: 
+- test/test_timecop.rb
+- test/test_timecop_with_rails.rb
+- test/test_timecop_without_date.rb