rspec-core 2.14.8 → 2.99.0.beta1

data/lib/rspec/core/deprecation.rb

@@ -4,16 +4,11 @@ module RSpec
       # @private
       #
       # Used internally to print deprecation warnings
-      def deprecate(deprecated, replacement_or_hash={}, ignore_version=nil)
-        # Temporarily support old and new APIs while we transition the other
-        # rspec libs to use a hash for the 2nd arg and no version arg
-        data = Hash === replacement_or_hash ? replacement_or_hash : { :replacement => replacement_or_hash }
-        call_site = caller.find { |line| line !~ %r{/lib/rspec/(core|mocks|expectations|matchers|rails)/} }
-
+      def deprecate(deprecated, data = {})
         RSpec.configuration.reporter.deprecation(
           {
             :deprecated => deprecated,
-            :call_site => call_site
+            :call_site => CallerFilter.first_non_rspec_line
           }.merge(data)
         )
       end

data/lib/rspec/core/example.rb

@@ -102,7 +102,7 @@ module RSpec
       # @param example_group_instance the instance of an ExampleGroup subclass
       def run(example_group_instance, reporter)
         @example_group_instance = example_group_instance
-        @example_group_instance.example = self
+        RSpec.current_example = self
 
         start(reporter)
 
@@ -111,7 +111,7 @@ module RSpec
             with_around_each_hooks do
               begin
                 run_before_each
-                @example_group_instance.instance_eval(&@example_block)
+                @example_group_instance.instance_eval_with_args(self, &@example_block)
               rescue Pending::PendingDeclaredInExample => e
                 @pending_declared_in_example = e.message
               rescue Exception => e
@@ -137,6 +137,8 @@ module RSpec
         end
 
         finish(reporter)
+      ensure
+        RSpec.current_example = nil
       end
 
       # @api private
@@ -232,14 +234,9 @@ An error occurred #{context}
         finish(reporter)
       end
 
-      # @private
-      def instance_eval(*args, &block)
-        @example_group_instance.instance_eval(*args, &block)
-      end
-
       # @private
       def instance_eval_with_rescue(context = nil, &block)
-        @example_group_instance.instance_eval_with_rescue(context, &block)
+        @example_group_instance.instance_eval_with_rescue(self, context, &block)
       end
 
       # @private

data/lib/rspec/core/example_group.rb

@@ -58,6 +58,7 @@ module RSpec
         #   @param [String] name
         #   @param [Hash] extra_options
         #   @param [Block] implementation
+        #   @yield [Example] the example object
         def self.define_example_method(name, extra_options={})
           module_eval(<<-END_RUBY, __FILE__, __LINE__)
             def #{name}(desc=nil, *args, &block)
@@ -71,10 +72,22 @@ module RSpec
         end
 
         # Defines an example within a group.
+        # @example
+        #   example do
+        #   end
+        #
+        #   example "does something" do
+        #   end
+        #
+        #   example "does something", :with => 'additional metadata' do
+        #   end
+        #
+        #   example "does something" do |ex|
+        #     # ex is the Example object that evals this block
+        #   end
         define_example_method :example
         # Defines an example within a group.
-        #
-        # @see example
+        # @example
         define_example_method :it
         # Defines an example within a group.
         # This is here primarily for backward compatibility with early versions
@@ -83,20 +96,26 @@ module RSpec
         define_example_method :specify
 
         # Shortcut to define an example with `:focus` => true
+        # @see example
         define_example_method :focus,   :focused => true, :focus => true
         # Shortcut to define an example with `:focus` => true
+        # @see example
         define_example_method :focused, :focused => true, :focus => true
         # Shortcut to define an example with `:focus` => true
         # @see example
         define_example_method :fit,     :focused => true, :focus => true
 
         # Shortcut to define an example with :pending => true
+        # @see example
         define_example_method :pending,  :pending => true
         # Shortcut to define an example with :pending => 'Temporarily disabled with xexample'
+        # @see example
         define_example_method :xexample, :pending => 'Temporarily disabled with xexample'
         # Shortcut to define an example with :pending => 'Temporarily disabled with xit'
+        # @see example
         define_example_method :xit,      :pending => 'Temporarily disabled with xit'
         # Shortcut to define an example with :pending => 'Temporarily disabled with xspecify'
+        # @see example
         define_example_method :xspecify, :pending => 'Temporarily disabled with xspecify'
 
         # Works like `alias_method :name, :example` with the added benefit of
@@ -163,10 +182,44 @@ module RSpec
         find_and_eval_shared("examples", name, *args, &block)
       end
 
+      if Proc.method_defined?(:parameters) # for >= 1.9
+        # Warn when submitting the name of more than one example group to
+        # include_examples, it_behaves_like, etc.
+        #
+        # Helpful when upgrading from rspec-1 (which supported multiple shared
+        # groups in one call) to rspec-2 (which does not).
+        #
+        # See https://github.com/rspec/rspec-core/issues/1066 for background.
+        def self.warn_unexpected_args(label, name, args, shared_block)
+          if !args.empty? && shared_block.parameters.count == 0
+            if shared_example_groups[args.first]
+              warn <<-WARNING
+shared #{label} support#{'s' if /context/ =~ label.to_s} the name of only one example group, received #{[name, *args].inspect}
+called from #{CallerFilter.first_non_rspec_line}"
+WARNING
+            else
+                warn <<-WARNING
+shared #{label} #{name.inspect} expected #{shared_block.arity} args, got #{args.inspect}
+called from #{CallerFilter.first_non_rspec_line}"
+WARNING
+            end
+          end
+        end
+      else
+        # no-op for Ruby < 1.9
+        #
+        # Ruby 1.8 reports lambda {}.arity == -1, so can't support this warning
+        # reliably
+        def self.warn_unexpected_args(*)
+        end
+      end
+
       # @private
       def self.find_and_eval_shared(label, name, *args, &customization_block)
         raise ArgumentError, "Could not find shared #{label} #{name.inspect}" unless
-        shared_block = shared_example_groups[name]
+          shared_block = shared_example_groups[name]
+
+        warn_unexpected_args(label, name, args, shared_block)
 
         module_eval_with_args(*args, &shared_block)
         module_eval(&customization_block) if customization_block
@@ -327,7 +380,7 @@ module RSpec
         begin
           assign_before_all_ivars(superclass.before_all_ivars, example_group_instance)
 
-          BeforeAllMemoizedHash.isolate_for_before_all(example_group_instance) do
+          AllHookMemoizedHash::Before.isolate_for_all_hook(example_group_instance) do
             run_hook(:before, :all, example_group_instance)
           end
         ensure
@@ -355,7 +408,9 @@ module RSpec
         return if descendant_filtered_examples.empty?
         assign_before_all_ivars(before_all_ivars, example_group_instance)
 
-        run_hook(:after, :all, example_group_instance)
+        AllHookMemoizedHash::After.isolate_for_all_hook(example_group_instance) do
+          run_hook(:after, :all, example_group_instance)
+        end
       end
 
       # Runs all the examples in this group
@@ -437,16 +492,42 @@ module RSpec
         ivars.each {|name, value| instance.instance_variable_set(name, value)}
       end
 
-      # @attr_reader
-      # Returns the {Example} object that wraps this instance of
-      # `ExampleGroup`
-      attr_accessor :example
+      def example=(current_example)
+        RSpec.current_example = current_example
+      end
+
+      # @deprecated use a block argument
+      def example
+        warn_deprecation_of_example_accessor :example
+        RSpec.current_example
+      end
 
-      # @deprecated use {ExampleGroup#example}
+      # @deprecated use a block argument
       def running_example
-        RSpec.deprecate("running_example",
-                        :replacement => "example")
-        example
+        warn_deprecation_of_example_accessor :running_example
+        RSpec.current_example
+      end
+
+      def warn_deprecation_of_example_accessor(name)
+        RSpec.warn_deprecation(<<-EOS.gsub(/^\s*\|/, ''))
+          |RSpec::Core::ExampleGroup##{name} is deprecated and will be removed
+          |in RSpec 3. There are a few options for what you can use instead:
+          |
+          |  - rspec-core's DSL methods (`it`, `before`, `after`, `let`, `subject`, etc)
+          |    now yield the example as a block argument, and that is the recommended
+          |    way to access the current example from those contexts.
+          |  - The current example is now exposed via `RSpec.current_example`,
+          |    which is accessible from any context.
+          |  - If you can't update the code at this call site (e.g. because it is in
+          |    an extension gem), you can use this snippet to continue making this
+          |    method available in RSpec 2.99 and RSpec 3:
+          |
+          |      RSpec.configure do |c|
+          |        c.expose_current_running_example_as :#{name}
+          |      end
+          |
+          |(Called from #{CallerFilter.first_non_rspec_line})
+        EOS
       end
 
       # Returns the class or module passed to the `describe` method (or alias).
@@ -466,12 +547,15 @@ module RSpec
       # @private
       # instance_evals the block, capturing and reporting an exception if
       # raised
-      def instance_eval_with_rescue(context = nil, &hook)
+      def instance_eval_with_rescue(example, context = nil, &hook)
         begin
-          instance_eval(&hook)
+          instance_eval_with_args(example, &hook)
         rescue Exception => e
-          raise unless example
-          example.set_exception(e, context)
+          if RSpec.current_example
+            RSpec.current_example.set_exception(e, context)
+          else
+            raise
+          end
         end
       end
     end

data/lib/rspec/core/filter_manager.rb

@@ -74,11 +74,11 @@ module RSpec
       STANDALONE_FILTERS = [:locations, :line_numbers, :full_description]
 
       module Describable
-        PROC_HEX_NUMBER = /0x[0-9a-f]+@/
+        PROC_HEX_NUMBER = /0x[0-9a-f]+\s?@/
         PROJECT_DIR = File.expand_path('.')
 
         def description
-          reject { |k, v| RSpec::Core::FilterManager::DEFAULT_EXCLUSIONS[k] == v }.inspect.gsub(PROC_HEX_NUMBER, '').gsub(PROJECT_DIR, '.').gsub(' (lambda)','')
+          reject { |k, v| RSpec::Core::FilterManager::DEFAULT_EXCLUSIONS[k] == v }.inspect.gsub(PROC_HEX_NUMBER, '').gsub(PROJECT_DIR, '.').gsub(' (lambda)','').gsub('__is_lambda__=true','')
         end
 
         def empty_without_conditional_filters?

data/lib/rspec/core/formatters/deprecation_formatter.rb

@@ -1,39 +1,197 @@
+require 'rspec/core/formatters/helpers'
+require 'set'
+
 module RSpec
   module Core
     module Formatters
       class DeprecationFormatter
-        def initialize(deprecation_stream=$stderr, summary_stream=$stdout)
+        attr_reader :count, :deprecation_stream, :summary_stream
+
+        def initialize(deprecation_stream, summary_stream)
           @deprecation_stream = deprecation_stream
           @summary_stream = summary_stream
+          @seen_deprecations = Set.new
           @count = 0
         end
 
-        def start(example_count=nil)
-          #no-op to fix #966
+        def printer
+          @printer ||= case deprecation_stream
+                       when File, RaiseErrorStream
+                         ImmediatePrinter.new(deprecation_stream, summary_stream, self)
+                       else
+                         DelayedPrinter.new(deprecation_stream, summary_stream, self)
+                       end
         end
 
         def deprecation(data)
+          return if @seen_deprecations.include?(data)
+
           @count += 1
+          printer.print_deprecation_message data
+          @seen_deprecations << data
+        end
+
+        def deprecation_summary
+          printer.deprecation_summary
+        end
+
+        def start(example_count=nil)
+          #no-op to fix #966
+        end
+
+        def deprecation_message_for(data)
           if data[:message]
-            @deprecation_stream.print data[:message]
+            SpecifiedDeprecationMessage.new(data)
           else
-            @deprecation_stream.print "DEPRECATION: " unless File === @deprecation_stream
-            @deprecation_stream.print "#{data[:deprecated]} is deprecated."
-            @deprecation_stream.print " Use #{data[:replacement]} instead." if data[:replacement]
-            @deprecation_stream.print " Called from #{data[:call_site]}." if data[:call_site]
-            @deprecation_stream.puts
+            GeneratedDeprecationMessage.new(data)
           end
         end
 
-        def deprecation_summary
-          if @count > 0 && File === @deprecation_stream
-            @summary_stream.print "\n#{@count} deprecation"
-            @summary_stream.print "s" if @count > 1
-            @summary_stream.print " logged to "
-            @summary_stream.puts @deprecation_stream.path
+        RAISE_ERROR_CONFIG_NOTICE = <<-EOS.gsub(/^\s+\|/, '')
+          |
+          |If you need more of the backtrace for any of these deprecations to
+          |identify where to make the necessary changes, you can configure
+          |`config.raise_errors_for_deprecations!`, and it will turn the
+          |deprecation warnings into errors, giving you the full backtrace.
+        EOS
+
+        SpecifiedDeprecationMessage = Struct.new(:type) do
+          def initialize(data)
+            @message = data[:message]
+            super deprecation_type_for(data)
+          end
+
+          def to_s
+            @message
+          end
+
+          def too_many_warnings_message
+            msg = "Too many similar deprecation messages reported, disregarding further reports."
+            msg << " Set config.deprecation_stream to a File for full output."
+            msg
+          end
+
+          private
+
+          def deprecation_type_for(data)
+            data[:message].gsub(/(\w+\/)+\w+\.rb:\d+/, '')
+          end
+        end
+
+        GeneratedDeprecationMessage = Struct.new(:type) do
+          def initialize(data)
+            @data = data
+            super data[:deprecated]
+          end
+
+          def to_s
+            msg =  "#{@data[:deprecated]} is deprecated."
+            msg << " Use #{@data[:replacement]} instead." if @data[:replacement]
+            msg << " Called from #{@data[:call_site]}." if @data[:call_site]
+            msg
+          end
+
+          def too_many_warnings_message
+            msg = "Too many uses of deprecated '#{type}'."
+            msg << " Set config.deprecation_stream to a File for full output."
+            msg
           end
         end
+
+        class ImmediatePrinter
+          include ::RSpec::Core::Formatters::Helpers
+
+          attr_reader :deprecation_stream, :summary_stream, :deprecation_formatter
+
+          def initialize(deprecation_stream, summary_stream, deprecation_formatter)
+            @deprecation_stream = deprecation_stream
+
+            # In one of my test suites, I got lots of duplicate output in the
+            # deprecation file (e.g. 200 of the same deprecation, even though
+            # the `puts` below was only called 6 times). Setting `sync = true`
+            # fixes this (but we really have no idea why!).
+            @deprecation_stream.sync = true
+
+            @summary_stream = summary_stream
+            @deprecation_formatter = deprecation_formatter
+          end
+
+          def print_deprecation_message(data)
+            deprecation_message = deprecation_formatter.deprecation_message_for(data)
+            deprecation_stream.puts deprecation_message.to_s
+          end
+
+          def deprecation_summary
+            if deprecation_formatter.count > 0
+              summary_stream.puts "\n#{pluralize(deprecation_formatter.count, 'deprecation')} logged to #{deprecation_stream.path}"
+              deprecation_stream.puts RAISE_ERROR_CONFIG_NOTICE
+            end
+          end
+        end
+
+        class DelayedPrinter
+          TOO_MANY_USES_LIMIT = 4
+
+          include ::RSpec::Core::Formatters::Helpers
+
+          attr_reader :deprecation_stream, :summary_stream, :deprecation_formatter
+
+          def initialize(deprecation_stream, summary_stream, deprecation_formatter)
+            @deprecation_stream = deprecation_stream
+            @summary_stream = summary_stream
+            @deprecation_formatter = deprecation_formatter
+            @seen_deprecations = Hash.new { 0 }
+            @deprecation_messages = Hash.new { |h, k| h[k] = [] }
+          end
+
+          def print_deprecation_message(data)
+            deprecation_message = deprecation_formatter.deprecation_message_for(data)
+            @seen_deprecations[deprecation_message] += 1
+
+            stash_deprecation_message(deprecation_message)
+          end
+
+          def stash_deprecation_message(deprecation_message)
+            if @seen_deprecations[deprecation_message] < TOO_MANY_USES_LIMIT
+              @deprecation_messages[deprecation_message] << deprecation_message.to_s
+            elsif @seen_deprecations[deprecation_message] == TOO_MANY_USES_LIMIT
+              @deprecation_messages[deprecation_message] << deprecation_message.too_many_warnings_message
+            end
+          end
+
+          def deprecation_summary
+            return unless @deprecation_messages.any?
+
+            print_deferred_deprecation_warnings
+            deprecation_stream.puts RAISE_ERROR_CONFIG_NOTICE
+
+            summary_stream.puts "\n#{pluralize(deprecation_formatter.count, 'deprecation warning')} total"
+          end
+
+          def print_deferred_deprecation_warnings
+            deprecation_stream.puts "\nDeprecation Warnings:\n\n"
+            @deprecation_messages.keys.sort_by(&:type).each do |deprecation|
+              messages = @deprecation_messages[deprecation]
+              messages.each { |msg| deprecation_stream.puts msg }
+              deprecation_stream.puts
+            end
+          end
+        end
+
+        # Not really a stream, but is usable in place of one.
+        class RaiseErrorStream
+          def puts(message)
+            raise DeprecationError, message
+          end
+
+          def sync=(value)
+            # no-op
+          end
+        end
+
       end
     end
+
+    DeprecationError = Class.new(StandardError)
   end
 end