deprecatable 1.0.0

data/test/test_deprecatable.rb

@@ -0,0 +1,149 @@
+require "helpers"
+
+class TestDeprecatable < MiniTest::Unit::TestCase
+
+  def setup
+    Deprecatable.registry.clear
+    Deprecatable.options.reset
+
+    @deprecated_class = Class.new do
+      extend Deprecatable
+      def self.name
+        "TestDeprecatable::DeprecateMe"
+      end
+      def deprecate_me; end
+      deprecate :deprecate_me
+    end
+
+    @deprecatable_class = Class.new do
+      extend Deprecatable
+      def self.name
+        "TestDeprecatable::DeprecatableClass"
+      end
+      def deprecate_me; end
+    end
+  end
+
+  def test_deprecated_method_is_regsitered
+    assert_equal( 1, Deprecatable.registry.size )
+  end
+
+  def test_call_site_is_recorded
+    i = @deprecated_class.new
+    capture_io do
+      i.deprecate_me
+    end
+    assert_equal( 1, Deprecatable.registry.items.first.invocation_count )
+  end
+
+  def test_different_call_sites_are_recorded_independently
+    i = @deprecated_class.new
+    capture_io do
+      42.times { i.deprecate_me }
+      24.times { i.deprecate_me }
+    end
+    dm = Deprecatable.registry.items.first
+    assert_equal( 66, dm.invocation_count )
+    assert_equal( 2, dm.call_site_count )
+  end
+
+  def test_alerts_are_issued_only_once_for_a_callsite
+    i = @deprecated_class.new
+    callable = lambda { |c| c.deprecate_me }
+    stdout, stderr = capture_io do
+      callable.call( i )
+    end
+    line = __LINE__ - 4
+
+    assert_match( /#{File.expand_path( __FILE__ )}:#{line}/m, stderr )
+      assert_match( /---> #{line}:\s+callable = lambda \{ |c| c\.deprecate_me \}/, stderr )
+
+    assert_silent do
+      callable.call( i )
+    end
+  end
+
+  def test_alerts_are_issued_never_for_a_callsite
+    ::Deprecatable.options.alert_frequency = :never
+    i = @deprecated_class.new
+    assert_silent do
+      i.deprecate_me
+    end
+  end
+
+  def test_alerts_are_issued_for_every_call_to_a_callsite
+    ::Deprecatable.options.alert_frequency = :always
+    i = @deprecated_class.new
+    stdout, stderr = capture_io do
+      42.times { i.deprecate_me }
+    end
+    line = __LINE__ - 2
+    lines = stderr.split(/\n/)
+    assert_equal( 42, lines.grep( /#{File.expand_path( __FILE__)}:#{line}/ ).size )
+    assert_equal( 42, lines.grep( /--->/ ).size )
+  end
+
+  def test_raise_an_exception_if_deprecating_a_method_that_does_not_exist
+    assert_raises( NameError ) do
+      @deprecatable_class.deprecate :wibble
+    end
+  end
+
+  def assert_alert_match( regex, klass, &block )
+    stdout, stderr = capture_io do
+      i = klass.new
+      i.deprecate_me
+    end
+    assert_match( regex, stderr )
+    return stderr
+  end
+
+  def test_adds_an_additional_message_when_given
+    @deprecatable_class.deprecate :deprecate_me, :message => "You should switch to using Something#bar"
+    assert_alert_match( /\* You should switch to using Something#bar/m, @deprecatable_class )
+  end
+
+  def test_adds_a_removal_date_when_given
+    @deprecatable_class.deprecate :deprecate_me, :removal_date => "2011-09-02"
+    assert_alert_match( /Will be removed after 2011-09-02/m, @deprecatable_class )
+  end
+
+  def test_adds_a_removal_version_when_given
+    @deprecatable_class.deprecate :deprecate_me, :removal_version => "4.2"
+    assert_alert_match( /Will be removed in version 4.2/m, @deprecatable_class )
+  end
+
+  def test_deprecating_an_included_method
+    mod = Module.new do
+      extend Deprecatable
+      def deprecate_me; end
+      deprecate :deprecate_me, :message => "KABOOM!"
+    end
+    klass = Class.new do
+      include mod
+    end
+
+    assert_alert_match( /KABOOM!/, klass )
+  end
+
+  def test_deprecating_a_class_method
+    klass = Class.new do
+      class << self
+        extend Deprecatable
+        def deprecate_me; end
+        deprecate :deprecate_me, :message => "Class Method KABOOM!"
+      end
+    end
+
+    stdout, stderr = capture_io do
+      klass.deprecate_me
+    end
+    assert_match( /Class Method KABOOM/, stderr )
+  end
+
+  def test_has_an_at_exit_handler
+    io = IO.popen( "ruby -Ilib examples/at_exit.rb 2>&1" )
+    lines = io.readlines.join('')
+    assert_match( /Deprecatable 'at_exit' Report/m, lines )
+  end
+end

data/test/test_deprecatable_alerter.rb

@@ -0,0 +1,41 @@
+require 'helpers'
+
+class TestDeprecatableAlerter < MiniTest::Unit::TestCase
+  def setup
+    Deprecatable.registry.clear
+    Deprecatable.options.reset
+
+    @old_alerter = Deprecatable.alerter
+    @alerter = ::Deprecatable::StringIOAlerter.new
+    Deprecatable.alerter = @alerter
+
+    @deprecated_class = Class.new do
+      extend Deprecatable
+      def self.name
+        "TestDeprecatable::DeprecateMe"
+      end
+      def deprecate_me; end
+      deprecate :deprecate_me
+    end
+  end
+
+  def teardown
+    Deprecatable.alerter = @old_alerter
+  end
+
+  def test_alert
+    i = @deprecated_class.new
+    i.deprecate_me
+
+    assert_match( /---> #{__LINE__ - 2}:/, Deprecatable.alerter.to_s )
+  end
+
+  def test_final_report
+    i = @deprecated_class.new
+    12.times { i.deprecate_me }
+    10.times { i.deprecate_me }
+    Deprecatable.alerter.final_report
+    assert_match( /Called 12 time/, Deprecatable.alerter.to_s )
+    assert_match( /Called 10 time/, Deprecatable.alerter.to_s )
+  end
+end

data/test/test_deprecatable_call_site.rb

@@ -0,0 +1,28 @@
+require 'helpers'
+# This file requires exact position of lines. If you should happent to chagen
+# tne numer of lines in this file that appear before the first test, some of the
+# tests will fail
+class TestDeprecatableCallSite < MiniTest::Unit::TestCase
+  def setup
+    @file = __FILE__
+    @before = 'This is the line before'
+    @line = __LINE__
+    @after = 'This is the line after'
+    @call_site = ::Deprecatable::CallSite.new( @file, @line, 1 )
+  end
+
+  def test_initializes_with_a_filename_and_line_number
+    assert_equal( File.expand_path( @file ), @call_site.file )
+    assert_equal( @line, @call_site.line_number )
+    assert_equal( 1, @call_site.context_padding )
+  end
+
+  def test_captures_the_call_site_context
+    context = [
+      "      8:     @before = 'This is the line before'\n",
+      "--->  9:     @line = __LINE__\n",
+      "     10:     @after = 'This is the line after'\n",
+    ]
+    assert_array_equal( context,  @call_site.formatted_context_lines )
+  end
+end

data/test/test_deprecatable_call_site_context.rb

@@ -0,0 +1,57 @@
+# Context line 1
+# Context line 2
+# Context line 3
+# Context line 4
+
+
+require 'helpers'
+
+# Context line 9
+# Context line 10
+# Context line 11
+# Context line 12
+# Context line 13
+
+class TestDeprecatableCallSiteContext < MiniTest::Unit::TestCase
+  def setup
+    @ctx = Deprecatable::CallSiteContext.new( File.expand_path(__FILE__), 11, 2 )
+  end
+
+  def context_lines_for( range, arrow_line )
+    width = ("%d" % range.to_a.last).length
+    range.map do |x|
+      prefix = ( x == arrow_line ) ? "--->" : "    "
+      "#{prefix} #{("%d" % x).rjust( width )}: # Context line #{x}\n"
+    end
+  end
+
+  def test_gets_the_context_from_the_middle_of_a_file
+    context_lines = (9..13).map { |x| "# Context line #{x}\n" }
+    assert_array_equal( context_lines, @ctx.context_lines )
+  end
+
+  def test_properly_formats_the_context_from_the_middle_of_the_file
+    formatted_lines = [ ]
+    formatted_lines += context_lines_for( (9..13), 11 )
+    assert_array_equal( formatted_lines, @ctx.formatted_context_lines )
+  end
+
+  def test_properly_formats_the_context_at_the_beginning_of_the_file
+    ctx = Deprecatable::CallSiteContext.new( File.expand_path(__FILE__), 2, 2 )
+    formatted_lines = [ ]
+    formatted_lines += context_lines_for( (1..4), 2 )
+    assert_array_equal( formatted_lines, ctx.formatted_context_lines )
+  end
+
+  def test_properly_formats_the_context_at_the_end_of_the_file
+    ctx = Deprecatable::CallSiteContext.new( File.expand_path(__FILE__), 56, 2 )
+    formatted_lines = [ ]
+    formatted_lines += context_lines_for( (54..57), 56)
+    assert_array_equal( formatted_lines, ctx.formatted_context_lines )
+  end
+end
+
+# Context line 54
+# Context line 55
+# Context line 56
+# Context line 57

data/test/test_deprecatable_deprecated_method.rb

@@ -0,0 +1,61 @@
+require 'helpers'
+
+class TestDeprecatableDeprecatedMethod < MiniTest::Unit::TestCase
+  def setup
+    @klass = Class.new do
+      def self.name
+        "TestDeprecatableDeprecatedMethod::DeprecatableClass"
+      end
+      def m1
+        "m1"
+      end
+    end
+
+    @module = Module.new do
+      def self.name
+        "TestDeprecatableDeprecatedMethod::DeprecatableModule"
+      end
+      def m2; "m2"; end
+    end
+
+    @dep_class = Deprecatable::DeprecatedMethod.new( @klass, "m1", __FILE__, 7 )
+  end
+
+  def test_records_meta_information_about_the_deprecation
+    assert_equal( @klass                       , @dep_class.klass                  )
+    assert_equal( "m1"                         , @dep_class.method                 )
+    assert_equal( File.expand_path( __FILE__ ) , @dep_class.file                   )
+    assert_equal( 7                            , @dep_class.line_number            )
+    assert_equal( "_deprecated_m1"             , @dep_class.deprecated_method_name )
+  end
+
+  def test_records_an_invocation_of_an_instance_method
+    dc = @klass.new
+    m = nil
+    capture_io do
+      m = dc.m1
+    end
+    assert_equal( "m1", m )
+    assert_equal( 1, @dep_class.invocation_count )
+  end
+
+  def test_records_uniq_call_sites
+    dc = @klass.new
+    capture_io do
+      3.times { dc.m1 }
+      3.times { dc.m1 }
+    end
+    assert_equal( 6, @dep_class.invocation_count )
+    assert_equal( 2, @dep_class.call_site_count )
+    assert_equal( 2, @dep_class.call_sites.size )
+  end
+
+  def test_has_a_string_representation_of_a_deprecated_instance_method
+    assert_equal( "TestDeprecatableDeprecatedMethod::DeprecatableClass#m1 defined at #{File.expand_path(__FILE__)}:7", @dep_class.to_s )
+  end
+
+  def test_has_a_string_representation_of_a_deprecated_module_method
+    dm = Deprecatable::DeprecatedMethod.new( @module, "m2", __FILE__, 11 )
+    assert_equal( "TestDeprecatableDeprecatedMethod::DeprecatableModule.m2 defined at #{File.expand_path(__FILE__)}:11", dm.to_s )
+  end
+end

data/test/test_deprecatable_options.rb

@@ -0,0 +1,83 @@
+require "helpers"
+
+class TestDeprecatableOptions < MiniTest::Unit::TestCase
+
+  def setup
+    @options = Deprecatable::Options.new
+  end
+
+  def teardown
+    ENV.keys.each do |k|
+      next unless k =~/^DEPRECATABLE/
+      ENV.delete( k )
+    end
+  end
+
+  def test_defaults_exist
+    assert_equal( 2    , @options.caller_context_padding )
+    assert_equal( true , @options.has_at_exit_report?    )
+    assert_equal( 1    , @options.alert_frequency        )
+  end
+
+  def test_caller_context_padding_raises_error_if_set_to_negative_number
+    assert_raises( ArgumentError, "caller_context_mapping must be > 0" ) do
+      @options.caller_context_padding = -1
+    end
+  end
+
+  def test_caller_context_padding_raises_error_if_environemtn_set_to_negative_number
+    ENV['DEPRECATABLE_CALLER_CONTEXT_PADDING'] = "-1"
+    assert_raises( ArgumentError, "caller_context_mapping must be > 0" ) do
+      @options.caller_context_padding
+    end
+  end
+
+  def test_caller_context_padding_may_be_set
+    @options.caller_context_padding = 4
+    assert_equal( 4, @options.caller_context_padding )
+  end
+
+  def test_caller_context_padding_may_be_overridden_by_environment_variable
+    assert_equal( 2, @options.caller_context_padding )
+    @options.caller_context_padding = 4
+    assert_equal( 4, @options.caller_context_padding )
+    ENV['DEPRECATABLE_CALLER_CONTEXT_PADDING'] = "10"
+    assert_equal( 10, @options.caller_context_padding )
+  end
+
+  def test_has_at_exit_report_may_be_turned_off
+    @options.has_at_exit_report = false
+    refute @options.has_at_exit_report?, "has_at_exit_report? must be false"
+  end
+
+  def test_has_at_exit_report_may_be_overridden_by_environment_variable
+    @options.has_at_exit_report = false
+    refute @options.has_at_exit_report?
+    ENV['DEPRECATABLE_HAS_AT_EXIT_REPORT'] = "true"
+    assert @options.has_at_exit_report?, "has_at_exit_report? must be true"
+  end
+
+  def test_alert_frequency_may_be_set
+    @options.alert_frequency = :once
+    assert_equal( 1, @options.alert_frequency )
+
+    @options.alert_frequency = :never
+    assert_equal( 0, @options.alert_frequency )
+
+    @options.alert_frequency = :always
+    assert_equal( "Infinity", @options.alert_frequency.to_s )
+    assert @options.alert_frequency.infinite?
+  end
+
+  def test_alert_frequency_may_be_overridden_by_environment_variable
+    ENV['DEPRECATABLE_ALERT_FREQUENCY'] = "42"
+    assert_equal( 42, @options.alert_frequency)
+    ENV['DEPRECATABLE_ALERT_FREQUENCY'] = "once"
+    assert_equal( 1, @options.alert_frequency)
+    ENV['DEPRECATABLE_ALERT_FREQUENCY'] = "never"
+    assert_equal( 0, @options.alert_frequency)
+    ENV['DEPRECATABLE_ALERT_FREQUENCY'] = "always"
+    assert @options.alert_frequency.infinite?
+  end
+
+end

data/test/test_deprecatable_registry.rb

@@ -0,0 +1,32 @@
+require 'helpers'
+
+class TestDeprecatableRegistry < MiniTest::Unit::TestCase
+  class DeprecatedExample
+    def boom; end
+  end
+
+  def setup
+    @registry = Deprecatable::Registry.new
+    @dm       = Deprecatable::DeprecatedMethod.new( TestDeprecatableRegistry::DeprecatedExample, "boom", __FILE__, 6 )
+  end
+
+  def test_registers_a_deprecated_method
+    assert_equal( 0, @registry.size )
+    @registry.register( @dm )
+    assert_equal( 1, @registry.size )
+  end
+
+  def test_that_a_given_method_may_only_be_registered_once
+    assert_equal( 0, @registry.size )
+    @registry.register( @dm )
+    assert_equal( 1, @registry.size )
+    @registry.register( @dm )
+    assert_equal( 1, @registry.size )
+  end
+
+  def test_returns_all_the_items_in_the_registry
+    @registry.register( @dm )
+    assert_equal( 1, @registry.items.size )
+  end
+
+end