rspec-core 3.0.4 → 3.12.2

data/lib/rspec/core/example.rb

@@ -9,7 +9,7 @@ module RSpec
     #
     # This allows us to provide rich metadata about each individual
     # example without adding tons of methods directly to the ExampleGroup
-    # that users may inadvertantly redefine.
+    # that users may inadvertently redefine.
     #
     # Useful for configuring logging and/or taking some action based
     # on the state of an example's metadata.
@@ -44,14 +44,15 @@ module RSpec
     class Example
       # @private
       #
-      # Used to define methods that delegate to this example's metadata
+      # Used to define methods that delegate to this example's metadata.
       def self.delegate_to_metadata(key)
         define_method(key) { @metadata[key] }
       end
 
       # @return [ExecutionResult] represents the result of running this example.
       delegate_to_metadata :execution_result
-      # @return [String] the relative path to the file where this example was defined.
+      # @return [String] the relative path to the file where this example was
+      #   defined.
       delegate_to_metadata :file_path
       # @return [String] the full description (including the docstrings of
       #   all parent example groups).
@@ -59,30 +60,101 @@ module RSpec
       # @return [String] the exact source location of this example in a form
       #   like `./path/to/spec.rb:17`
       delegate_to_metadata :location
-      # @return [Boolean] flag that indicates that the example is not expected to pass.
-      #   It will be run and will either have a pending result (if a failure occurs)
-      #   or a failed result (if no failure occurs).
+      # @return [Boolean] flag that indicates that the example is not expected
+      #   to pass. It will be run and will either have a pending result (if a
+      #   failure occurs) or a failed result (if no failure occurs).
       delegate_to_metadata :pending
       # @return [Boolean] flag that will cause the example to not run.
       #   The {ExecutionResult} status will be `:pending`.
       delegate_to_metadata :skip
 
       # Returns the string submitted to `example` or its aliases (e.g.
-      # `specify`, `it`, etc).  If no string is submitted (e.g. `it { is_expected.to
-      # do_something }`) it returns the message generated by the matcher if
-      # there is one, otherwise returns a message including the location of the
-      # example.
+      # `specify`, `it`, etc). If no string is submitted (e.g.
+      # `it { is_expected.to do_something }`) it returns the message generated
+      # by the matcher if there is one, otherwise returns a message including
+      # the location of the example.
       def description
-        description = metadata[:description].to_s.empty? ?
-          "example at #{location}" :
-          metadata[:description]
+        description = if metadata[:description].to_s.empty?
+                        location_description
+                      else
+                        metadata[:description]
+                      end
+
         RSpec.configuration.format_docstrings_block.call(description)
       end
 
+      # Returns a description of the example that always includes the location.
+      def inspect_output
+        inspect_output = "\"#{description}\""
+        unless metadata[:description].to_s.empty?
+          inspect_output += " (#{location})"
+        end
+        inspect_output
+      end
+
+      # Returns the location-based argument that can be passed to the `rspec` command to rerun this example.
+      def location_rerun_argument
+        @location_rerun_argument ||= begin
+          loaded_spec_files = RSpec.configuration.loaded_spec_files
+
+          Metadata.ascending(metadata) do |meta|
+            return meta[:location] if loaded_spec_files.include?(meta[:absolute_file_path])
+          end
+        end
+      end
+
+      # Returns the location-based argument that can be passed to the `rspec` command to rerun this example.
+      #
+      # @deprecated Use {#location_rerun_argument} instead.
+      # @note If there are multiple examples identified by this location, they will use {#id}
+      #   to rerun instead, but this method will still return the location (that's why it is deprecated!).
+      def rerun_argument
+        location_rerun_argument
+      end
+
+      # @return [String] the unique id of this example. Pass
+      #   this at the command line to re-run this exact example.
+      def id
+        @id ||= Metadata.id_from(metadata)
+      end
+
+      # @private
+      def self.parse_id(id)
+        # http://rubular.com/r/OMZSAPcAfn
+        id.match(/\A(.*?)(?:\[([\d\s:,]+)\])?\z/).captures
+      end
+
+      # Duplicates the example and overrides metadata with the provided
+      # hash.
+      #
+      # @param metadata_overrides [Hash] the hash to override the example metadata
+      # @return [Example] a duplicate of the example with modified metadata
+      def duplicate_with(metadata_overrides={})
+        new_metadata = metadata.clone.merge(metadata_overrides)
+
+        RSpec::Core::Metadata::RESERVED_KEYS.each do |reserved_key|
+          new_metadata.delete reserved_key
+        end
+
+        # don't clone the example group because the new example
+        # must belong to the same example group (not a clone).
+        #
+        # block is nil in new_metadata so we have to get it from metadata.
+        Example.new(example_group, description.clone,
+                    new_metadata, metadata[:block])
+      end
+
+      # @private
+      def update_inherited_metadata(updates)
+        metadata.update(updates) do |_key, existing_example_value, _new_inherited_value|
+          existing_example_value
+        end
+      end
+
       # @attr_reader
       #
       # Returns the first exception raised in the context of running this
-      # example (nil if no exception is raised)
+      # example (nil if no exception is raised).
       attr_reader :exception
 
       # @attr_reader
@@ -102,31 +174,70 @@ module RSpec
       attr_accessor :clock
 
       # Creates a new instance of Example.
-      # @param example_group_class [Class] the subclass of ExampleGroup in which this Example is declared
-      # @param description [String] the String passed to the `it` method (or alias)
-      # @param user_metadata [Hash] additional args passed to `it` to be used as metadata
-      # @param example_block [Proc] the block of code that represents the example
+      # @param example_group_class [Class] the subclass of ExampleGroup in which
+      #   this Example is declared
+      # @param description [String] the String passed to the `it` method (or
+      #   alias)
+      # @param user_metadata [Hash] additional args passed to `it` to be used as
+      #   metadata
+      # @param example_block [Proc] the block of code that represents the
+      #   example
       # @api private
       def initialize(example_group_class, description, user_metadata, example_block=nil)
         @example_group_class = example_group_class
         @example_block       = example_block
 
+        # Register the example with the group before creating the metadata hash.
+        # This is necessary since creating the metadata hash triggers
+        # `when_first_matching_example_defined` callbacks, in which users can
+        # load RSpec support code which defines hooks. For that to work, the
+        # examples and example groups must be registered at the time the
+        # support code is called or be defined afterwards.
+        # Begin defined beforehand but registered afterwards causes hooks to
+        # not be applied where they should.
+        example_group_class.examples << self
+
         @metadata = Metadata::ExampleHash.create(
-          @example_group_class.metadata, user_metadata, description, example_block
+          @example_group_class.metadata, user_metadata,
+          example_group_class.method(:next_runnable_index_for),
+          description, example_block
         )
 
+        config = RSpec.configuration
+        config.apply_derived_metadata_to(@metadata)
+
+        # This should perhaps be done in `Metadata::ExampleHash.create`,
+        # but the logic there has no knowledge of `RSpec.world` and we
+        # want to keep it that way. It's easier to just assign it here.
+        @metadata[:last_run_status] = config.last_run_statuses[id]
+
         @example_group_instance = @exception = nil
         @clock = RSpec::Core::Time
+        @reporter = RSpec::Core::NullReporter
       end
 
+      # Provide a human-readable representation of this class
+      def inspect
+        "#<#{self.class.name} #{description.inspect}>"
+      end
+      alias to_s inspect
+
+      # @return [RSpec::Core::Reporter] the current reporter for the example
+      attr_reader :reporter
+
       # Returns the example group class that provides the context for running
       # this example.
       def example_group
         @example_group_class
       end
 
-      alias_method :pending?, :pending
-      alias_method :skipped?, :skip
+      def pending?
+        !!pending
+      end
+
+      def skipped?
+        !!skip
+      end
 
       # @api private
       # instance_execs the block passed to the constructor in the context of
@@ -134,50 +245,71 @@ module RSpec
       # @param example_group_instance the instance of an ExampleGroup subclass
       def run(example_group_instance, reporter)
         @example_group_instance = example_group_instance
+        @reporter = reporter
+        RSpec.configuration.configure_example(self, hooks)
         RSpec.current_example = self
 
         start(reporter)
+        Pending.mark_pending!(self, pending) if pending?
 
         begin
           if skipped?
             Pending.mark_pending! self, skip
           elsif !RSpec.configuration.dry_run?
-            with_around_example_hooks do
+            with_around_and_singleton_context_hooks do
               begin
                 run_before_example
+                RSpec.current_scope = :example
                 @example_group_instance.instance_exec(self, &@example_block)
 
                 if pending?
                   Pending.mark_fixed! self
 
                   raise Pending::PendingExampleFixedError,
-                    'Expected example to fail since it is pending, but it passed.',
-                    [location]
+                        'Expected example to fail since it is pending, but it passed.',
+                        [location]
                 end
-              rescue Pending::SkipDeclaredInExample
+              rescue Pending::SkipDeclaredInExample => _
+                # The "=> _" is normally useless but on JRuby it is a workaround
+                # for a bug that prevents us from getting backtraces:
+                # https://github.com/jruby/jruby/issues/4467
+                #
                 # no-op, required metadata has already been set by the `skip`
                 # method.
-              rescue Exception => e
+              rescue AllExceptionsExcludingDangerousOnesOnRubiesThatAllowIt => e
                 set_exception(e)
               ensure
+                RSpec.current_scope = :after_example_hook
                 run_after_example
               end
             end
           end
-        rescue Exception => e
+        rescue Support::AllExceptionsExceptOnesWeMustNotRescue => e
           set_exception(e)
         ensure
-          @example_group_instance.instance_variables.each do |ivar|
-            @example_group_instance.instance_variable_set(ivar, nil)
-          end
-          @example_group_instance = nil
+          @example_group_instance = nil # if you love something... let it go
         end
 
         finish(reporter)
       ensure
+        execution_result.ensure_timing_set(clock)
         RSpec.current_example = nil
       end
 
+      if RSpec::Support::Ruby.jruby? || RUBY_VERSION.to_f < 1.9
+        # :nocov:
+        # For some reason, rescuing `Support::AllExceptionsExceptOnesWeMustNotRescue`
+        # in place of `Exception` above can cause the exit status to be the wrong
+        # thing. I have no idea why. See:
+        # https://github.com/rspec/rspec-core/pull/2063#discussion_r38284978
+        # @private
+        AllExceptionsExcludingDangerousOnesOnRubiesThatAllowIt = Exception
+        # :nocov:
+      else
+        # @private
+        AllExceptionsExcludingDangerousOnesOnRubiesThatAllowIt = Support::AllExceptionsExceptOnesWeMustNotRescue
+      end
+
       # Wraps both a `Proc` and an {Example} for use in {Hooks#around
       # around} hooks. In around hooks we need to yield this special
       # kind of object (rather than the raw {Example}) because when
@@ -190,7 +322,7 @@ module RSpec
       #         if ex.metadata[:key] == :some_value && some_global_condition
       #           raise "some message"
       #         end
-      #         ex.run         # run delegates to ex.call
+      #         ex.run         # run delegates to ex.call.
       #       end
       #     end
       #
@@ -201,67 +333,105 @@ module RSpec
         attr_reader :example
 
         Example.public_instance_methods(false).each do |name|
-          unless name.to_sym == :run
-            define_method(name) { |*a, &b| @example.__send__(name, *a, &b) }
-          end
+          name_sym = name.to_sym
+          next if name_sym == :run || name_sym == :inspect || name_sym == :to_s
+
+          define_method(name) { |*a, &b| @example.__send__(name, *a, &b) }
         end
 
         Proc.public_instance_methods(false).each do |name|
+          name_sym = name.to_sym
+          next if name_sym == :call || name_sym == :inspect || name_sym == :to_s || name_sym == :to_proc
+
           define_method(name) { |*a, &b| @proc.__send__(name, *a, &b) }
         end
+
+        # Calls the proc and notes that the example has been executed.
+        def call(*args, &block)
+          @executed = true
+          @proc.call(*args, &block)
+        end
         alias run call
 
+        # Provides a wrapped proc that will update our `executed?` state when
+        # executed.
+        def to_proc
+          method(:call).to_proc
+        end
+
         def initialize(example, &block)
-          @example = example
-          @proc    = block
+          @example  = example
+          @proc     = block
+          @executed = false
         end
 
         # @private
         def wrap(&block)
           self.class.new(example, &block)
         end
-      end
 
-      # @private
-      def any_apply?(filters)
-        MetadataFilter.any_apply?(filters, metadata)
+        # Indicates whether or not the around hook has executed the example.
+        def executed?
+          @executed
+        end
+
+        # @private
+        def inspect
+          @example.inspect.gsub('Example', 'Example::Procsy')
+        end
       end
 
       # @private
-      def all_apply?(filters)
-        MetadataFilter.all_apply?(filters, metadata) || @example_group_class.all_apply?(filters)
+      #
+      # The exception that will be displayed to the user -- either the failure of
+      # the example or the `pending_exception` if the example is pending.
+      def display_exception
+        @exception || execution_result.pending_exception
       end
 
       # @private
-      def around_example_hooks
-        @around_example_hooks ||= example_group.hooks.around_example_hooks_for(self)
+      #
+      # Assigns the exception that will be displayed to the user -- either the failure of
+      # the example or the `pending_exception` if the example is pending.
+      def display_exception=(ex)
+        if pending? && !(Pending::PendingExampleFixedError === ex)
+          @exception = nil
+          execution_result.pending_fixed = false
+          execution_result.pending_exception = ex
+        else
+          @exception = ex
+        end
       end
 
+      # rubocop:disable Naming/AccessorMethodName
+
       # @private
       #
       # Used internally to set an exception in an after hook, which
       # captures the exception but doesn't raise it.
-      def set_exception(exception, context=nil)
-        if pending? && !(Pending::PendingExampleFixedError === exception)
-          execution_result.pending_exception = exception
-        else
-          if @exception
-            # An error has already been set; we don't want to override it,
-            # but we also don't want silence the error, so let's print it.
-            msg = <<-EOS
+      def set_exception(exception)
+        return self.display_exception = exception unless display_exception
 
-  An error occurred #{context}
-    #{exception.class}: #{exception.message}
-    occurred at #{exception.backtrace.first}
+        unless RSpec::Core::MultipleExceptionError === display_exception
+          self.display_exception = RSpec::Core::MultipleExceptionError.new(display_exception)
+        end
 
-            EOS
-            RSpec.configuration.reporter.message(msg)
-          end
+        display_exception.add exception
+      end
 
-          @exception ||= exception
-        end
+      # @private
+      #
+      # Used to set the exception when `aggregate_failures` fails.
+      def set_aggregate_failures_exception(exception)
+        return set_exception(exception) unless display_exception
+
+        exception = RSpec::Core::MultipleExceptionError::InterfaceTag.for(exception)
+        exception.add display_exception
+        self.display_exception = exception
       end
 
+      # rubocop:enable Naming/AccessorMethodName
+
       # @private
       #
       # Used internally to set an exception and fail without actually executing
@@ -275,20 +445,13 @@ module RSpec
       # @private
       #
       # Used internally to skip without actually executing the example when
-      # skip is used in before(:context)
+      # skip is used in before(:context).
       def skip_with_exception(reporter, exception)
         start(reporter)
         Pending.mark_skipped! self, exception.argument
         finish(reporter)
       end
 
-      # @private
-      def instance_exec_with_rescue(context, &block)
-        @example_group_instance.instance_exec(self, &block)
-      rescue Exception => e
-        set_exception(e, context)
-      end
-
       # @private
       def instance_exec(*args, &block)
         @example_group_instance.instance_exec(*args, &block)
@@ -296,14 +459,15 @@ module RSpec
 
     private
 
-      def with_around_example_hooks(&block)
-        if around_example_hooks.empty?
-          yield
-        else
-          @example_group_class.hooks.run(:around, :example, self, Procsy.new(self, &block))
-        end
-      rescue Exception => e
-        set_exception(e, "in an `around(:example)` hook")
+      def hooks
+        example_group_instance.singleton_class.hooks
+      end
+
+      def with_around_example_hooks
+        RSpec.current_scope = :before_example_hook
+        hooks.run(:around, :example, self) { yield }
+      rescue Support::AllExceptionsExceptOnesWeMustNotRescue => e
+        set_exception(e)
       end
 
       def start(reporter)
@@ -315,50 +479,52 @@ module RSpec
         pending_message = execution_result.pending_message
 
         if @exception
-          record_finished :failed
           execution_result.exception = @exception
+          record_finished :failed, reporter
           reporter.example_failed self
           false
         elsif pending_message
-          record_finished :pending
           execution_result.pending_message = pending_message
+          record_finished :pending, reporter
           reporter.example_pending self
           true
         else
-          record_finished :passed
+          record_finished :passed, reporter
           reporter.example_passed self
           true
         end
       end
 
-      def record_finished(status)
+      def record_finished(status, reporter)
         execution_result.record_finished(status, clock.now)
+        reporter.example_finished(self)
       end
 
       def run_before_example
         @example_group_instance.setup_mocks_for_rspec
-        @example_group_class.hooks.run(:before, :example, self)
+        hooks.run(:before, :example, self)
+      end
+
+      def with_around_and_singleton_context_hooks
+        singleton_context_hooks_host = example_group_instance.singleton_class
+        singleton_context_hooks_host.run_before_context_hooks(example_group_instance)
+        with_around_example_hooks { yield }
+      ensure
+        singleton_context_hooks_host.run_after_context_hooks(example_group_instance)
       end
 
       def run_after_example
-        @example_group_class.hooks.run(:after, :example, self)
+        assign_generated_description if defined?(::RSpec::Matchers)
+        hooks.run(:after, :example, self)
         verify_mocks
-        assign_generated_description if RSpec.configuration.expecting_with_rspec?
-      rescue Exception => e
-        set_exception(e, "in an `after(:example)` hook")
       ensure
         @example_group_instance.teardown_mocks_for_rspec
       end
 
       def verify_mocks
         @example_group_instance.verify_mocks_for_rspec if mocks_need_verification?
-      rescue Exception => e
-        if pending?
-          execution_result.pending_fixed = false
-          @exception = nil
-        else
-          set_exception(e)
-        end
+      rescue Support::AllExceptionsExceptOnesWeMustNotRescue => e
+        set_exception(e)
       end
 
       def mocks_need_verification?
@@ -366,22 +532,23 @@ module RSpec
       end
 
       def assign_generated_description
-        if metadata[:description].empty? && (description = RSpec::Matchers.generated_description)
+        if metadata[:description].empty? && (description = generate_description)
           metadata[:description] = description
-          metadata[:full_description] << description
+          metadata[:full_description] += description
         end
-      rescue Exception => e
-        set_exception(e, "while assigning the example description")
       ensure
         RSpec::Matchers.clear_generated_description
       end
 
-      def skip_message
-        if String === skip
-          skip
-        else
-          Pending::NO_REASON_GIVEN
-        end
+      def generate_description
+        RSpec::Matchers.generated_description
+      rescue Support::AllExceptionsExceptOnesWeMustNotRescue => e
+        location_description + " (Got an error when generating description " \
+          "from matcher: #{e.class}: #{e.message} -- #{e.backtrace.first})"
+      end
+
+      def location_description
+        "example at #{location}"
       end
 
       # Represents the result of executing an example.
@@ -418,18 +585,39 @@ module RSpec
         #   this indicates whether or not it now passes.
         attr_accessor :pending_fixed
 
-        alias pending_fixed? pending_fixed
+        def pending_fixed?
+          !!pending_fixed
+        end
+
+        # @return [Boolean] Indicates if the example was completely skipped
+        #   (typically done via `:skip` metadata or the `skip` method). Skipped examples
+        #   will have a `:pending` result. A `:pending` result can also come from examples
+        #   that were marked as `:pending`, which causes them to be run, and produces a
+        #   `:failed` result if the example passes.
+        def example_skipped?
+          status == :pending && !pending_exception
+        end
 
         # @api private
         # Records the finished status of the example.
         def record_finished(status, finished_at)
-          self.status      = status
-          self.finished_at = finished_at
-          self.run_time    = (finished_at - started_at).to_f
+          self.status = status
+          calculate_run_time(finished_at)
+        end
+
+        # @api private
+        # Populates finished_at and run_time if it has not yet been set
+        def ensure_timing_set(clock)
+          calculate_run_time(clock.now) unless finished_at
         end
 
       private
 
+        def calculate_run_time(finished_at)
+          self.finished_at = finished_at
+          self.run_time    = (finished_at - started_at).to_f
+        end
+
         # For backwards compatibility we present `status` as a string
         # when presenting the legacy hash interface.
         def hash_for_delegation
@@ -451,7 +639,7 @@ module RSpec
           end
         end
 
-        def issue_deprecation(method_name, *args)
+        def issue_deprecation(_method_name, *_args)
           RSpec.deprecate("Treating `metadata[:execution_result]` as a hash",
                           :replacement => "the attributes methods to access the data")
         end
@@ -461,14 +649,18 @@ module RSpec
     # @private
     # Provides an execution context for before/after :suite hooks.
     class SuiteHookContext < Example
-      def initialize
-        super(AnonymousExampleGroup, "", {})
+      def initialize(hook_description, reporter)
+        super(AnonymousExampleGroup, hook_description, {})
+        @example_group_instance = AnonymousExampleGroup.new
+        @reporter = reporter
       end
 
-      # To ensure we don't silence errors...
-      def set_exception(exception, context=nil)
-        raise exception
+      # rubocop:disable Naming/AccessorMethodName
+      def set_exception(exception)
+        reporter.notify_non_example_exception(exception, "An error occurred in #{description}.")
+        RSpec.world.wants_to_quit = true
       end
+      # rubocop:enable Naming/AccessorMethodName
     end
   end
 end