Merge pull request #856 from JonRowe/deprecation_io_mk2

Log, count and warn deprecations via configurable io stream

Changelog.md

@@ -40,6 +40,8 @@ Enhancements
   allow access to `Time.now` (Jon Rowe)
 * Make `shared_examples_for` context aware, so that keys may be safely reused
   in multiple contexts without colliding. (Jon Rowe)
+* Make `warn_deprecations` use a configurable `deprecation_io` stream.
+  (Jon Rowe)
 
 Bug fixes
 

lib/rspec/core.rb

@@ -17,6 +17,7 @@
 require_rspec['core/extensions/instance_eval_with_args']
 require_rspec['core/extensions/module_eval_with_args']
 require_rspec['core/extensions/ordered']
+require_rspec['core/deprecation_io']
 require_rspec['core/deprecation']
 require_rspec['core/backward_compatibility']
 require_rspec['core/reporter']

lib/rspec/core/configuration.rb

@@ -195,6 +195,7 @@ def initialize
         @backtrace_cleaner = BacktraceCleaner.new
 
         @default_path = 'spec'
+        @deprecation_io = DeprecationIO.new
         @filter_manager = FilterManager.new
         @preferred_options = {}
         @seed = srand % 0xFFFF
@@ -271,6 +272,18 @@ def add_setting(name, opts={})
         send("#{name}=", default) if default
       end
 
+      # Set the io used for deprection warnings
+      # Defaults to $stderr
+      def deprecation_io=(value)
+        @deprecation_io.set_output value
+      end
+      attr_reader :deprecation_io
+
+      # Set a file to be the io for deprection warnings
+      def log_deprecations_to_file name
+        @deprecation_io.set_output File.open(name,'w+'), name
+      end
+
       # Returns the configured mock framework adapter module
       def mock_framework
         mock_with :rspec unless @mock_framework

lib/rspec/core/deprecation.rb

@@ -21,7 +21,23 @@ def deprecate(method, alternate_method=nil, version=nil)
     #
     # Used internally to print deprecation warnings
     def warn_deprecation(message)
-      warn message
+      RSpec.configuration.deprecation_io.puts(message)
     end
+
+    # @private
+    #
+    # Used internally to print the count of deprecation warnings
+    def deprecations?
+      RSpec.configuration.deprecation_io.deprecations > 0
+    end
+
+    # @private
+    #
+    # Used internally to print deprecation summary
+    def deprecations_summary
+      io = RSpec.configuration.deprecation_io
+      "There were #{io.deprecations} deprecations logged to #{io.description}"
+    end
+
   end
 end

lib/rspec/core/deprecation_io.rb

@@ -0,0 +1,28 @@
+module RSpec
+  module Core
+    class DeprecationIO
+
+      def initialize
+        @io = $stderr
+        @count = 0
+        @description = 'STD_ERR'
+      end
+      attr_reader :io, :description
+
+      def set_output(io, description = io.inspect)
+        @description = description
+        @io = io
+      end
+
+      def puts(message)
+        @count += 1
+        @io.puts message
+      end
+
+      def deprecations
+        @count
+      end
+
+    end
+  end
+end

lib/rspec/core/reporter.rb

@@ -104,6 +104,7 @@ def finish(seed)
         notify :dump_pending
         notify :dump_failures
         notify :dump_summary, @duration, @example_count, @failure_count, @pending_count
+        warn RSpec.deprecations_summary if RSpec.deprecations?
         notify :seed, seed if seed
       ensure
         notify :close

spec/rspec/core/configuration_spec.rb

@@ -16,6 +16,43 @@ module RSpec::Core
       end
     end
 
+    describe '#deprecation_io' do
+      it 'defaults to standard error' do
+        expect(config.deprecation_io.io).to eq $stderr
+      end
+
+      it 'is configurable' do
+        io = double 'deprecation io'
+        config.deprecation_io = io
+        expect(config.deprecation_io.io).to eq io
+      end
+
+      it 'is used by warn_deprecation' do
+        message = double
+        RSpec.configuration.deprecation_io.should_receive(:puts).with(message)
+        RSpec.warn_deprecation message
+      end
+    end
+
+    describe '#log_deprecations_to_file' do
+      let(:name) { 'filename.txt' }
+
+      around do |example|
+        config.log_deprecations_to_file name
+        example.run
+        File.delete name if File.exist? name
+      end
+
+      it 'sets the deprecation io to be a file with the supplied name' do
+        file = config.deprecation_io.io
+        expect(file.path).to eq name
+      end
+
+      it 'sets the deprecation io description to be the supplied file name' do
+        expect(config.deprecation_io.description).to eq name
+      end
+    end
+
     describe "#setup_load_path_and_require" do
       include_context "isolate load path mutation"
 
@@ -1209,7 +1246,7 @@ def metadata_hash(*args)
 
       context "with :alias => " do
         it "is deprecated" do
-          RSpec::should_receive(:warn).with(/deprecated/)
+          RSpec::should_receive(:warn_deprecation).with(/deprecated/)
           config.add_setting :custom_option
           config.add_setting :another_custom_option, :alias => :custom_option
         end

spec/rspec/core/deprecation_io_spec.rb

@@ -0,0 +1,70 @@
+require 'spec_helper'
+require 'tempfile'
+
+module RSpec::Core
+  describe DeprecationIO do
+    let(:std_err) { StringIO.new }
+    let(:io)      { DeprecationIO.new }
+
+    around do |example|
+      @original = $stderr
+      $stderr = std_err
+      example.run
+      $stderr = @original
+    end
+
+    describe 'by default' do
+      it 'starts with 0 deprecations' do
+        expect(io.deprecations).to eq 0
+      end
+
+      it 'counts deprecations' do
+        io.puts 'WARN'
+        expect(io.deprecations).to eq 1
+      end
+
+      it 'logs to std err by default' do
+        std_err.should_receive(:puts).with('WARN').once
+        io.puts 'WARN'
+      end
+
+      it 'leaves description as stderr' do
+        expect(io.description).to eq 'STD_ERR'
+      end
+    end
+
+    describe 'setting an io' do
+      let(:stream) { double "stream", :puts => nil }
+
+      before do
+        io.set_output stream
+      end
+
+      it 'starts with 0 deprecations' do
+        expect(io.deprecations).to eq 0
+      end
+
+      it 'counts deprecations' do
+        io.puts 'WARN'
+        expect(io.deprecations).to eq 1
+      end
+
+      it 'logs to the stream' do
+        stream.should_receive(:puts).with('WARN').once
+        io.puts 'WARN'
+      end
+
+      it 'defaults description to the inspect of stream' do
+        expect(io.description).to eq stream.inspect
+      end
+    end
+
+    describe 'setting an io and description' do
+      it 'sets description' do
+        io.set_output double, 'filename.txt'
+        expect(io.description).to eq 'filename.txt'
+      end
+    end
+
+  end
+end

spec/rspec/core/deprecations_spec.rb

@@ -2,17 +2,17 @@
 
 describe "support for deprecation warnings" do
   it "includes the method to deprecate" do
-    expect(RSpec).to receive(:warn).with(/^DEPRECATION: deprecated_method/)
+    expect(RSpec).to receive(:warn_deprecation).with(/^DEPRECATION: deprecated_method/)
     RSpec.deprecate("deprecated_method")
   end
 
   it "includes the replacement when provided" do
-    expect(RSpec).to receive(:warn).with(/deprecated_method.*\nDEPRECATION:.*replacement/m)
+    expect(RSpec).to receive(:warn_deprecation).with(/deprecated_method.*\nDEPRECATION:.*replacement/m)
     RSpec.deprecate("deprecated_method", "replacement")
   end
 
   it "includes the version number when provided" do
-    expect(RSpec).to receive(:warn).with(/deprecated_method.*rspec-37\.0\.0\nDEPRECATION:.*replacement/m)
+    expect(RSpec).to receive(:warn_deprecation).with(/deprecated_method.*rspec-37\.0\.0\nDEPRECATION:.*replacement/m)
     RSpec.deprecate("deprecated_method", "replacement", "37.0.0")
   end
 

spec/rspec/core/formatters/base_text_formatter_spec.rb

@@ -147,7 +147,7 @@ def run_all_and_dump_failures
     end
 
     context 'for #share_as' do
-      before { RSpec.stub(:warn) }
+      before { RSpec.stub(:warn_deprecation) }
 
       it 'outputs the name and location' do
 
@@ -286,7 +286,7 @@ def run_all_and_dump_pending
       end
 
       context 'for #share_as' do
-        before { RSpec.stub(:warn) }
+        before { RSpec.stub(:warn_deprecation) }
 
         it 'outputs the name and location' do
 
@@ -475,15 +475,15 @@ def run_all_and_dump_pending
     describe "##{name}" do
       before do
         RSpec.configuration.stub(:color_enabled?) { true }
-        RSpec.stub(:warn)
+        RSpec.stub(:warn_deprecation)
       end
 
       it "prints the text using the color code for #{name}" do
         expect(formatter.send(name, "text")).to eq("\e[#{number}mtext\e[0m")
       end
 
       it "prints a deprecation warning" do
-        RSpec.should_receive(:warn).with(/#{name}/)
+        RSpec.should_receive(:warn_deprecation).with(/#{name}/)
         formatter.send(name, "text")
       end
     end

spec/rspec/core/reporter_spec.rb

@@ -136,5 +136,27 @@ module RSpec::Core
         expect(duration).to be < 0.2
       end
     end
+
+    describe 'deprecation warning' do
+      let(:reporter) { Reporter.new double.as_null_object }
+
+      around do |example|
+        RSpec.configure { |config| @io = config.deprecation_io }
+        example.run
+        RSpec.configure { |config| config.deprecation_io = @io }
+      end
+
+      it 'doesnt warn when no deprecations' do
+        reporter.should_not_receive(:warn)
+        reporter.finish 1234
+      end
+
+      it 'warns when it has deprecations' do
+        RSpec.configure { |config| config.deprecation_io = StringIO.new }
+        RSpec.warn_deprecation 'message'
+        reporter.should_receive(:warn).with(/There were \d+ deprecations logged to .+/)
+        reporter.finish 1234
+      end
+    end
   end
 end

spec/rspec/core/shared_example_group_spec.rb

@@ -72,7 +72,7 @@ module RSpec::Core
     end
 
     describe "#share_as" do
-      before { RSpec.stub(:warn) }
+      before { RSpec.stub(:warn_deprecation) }
 
       it "is exposed to the global namespace" do
         expect(Kernel).to respond_to("share_as")