rspec-core 3.0.4 → 3.12.2

data/lib/rspec/core/metadata.rb

@@ -7,7 +7,7 @@ module RSpec
     # In addition to metadata that is used internally, this also stores
     # user-supplied metadata, e.g.
     #
-    #     describe Something, :type => :ui do
+    #     RSpec.describe Something, :type => :ui do
     #       it "does something", :slow => true do
     #         # ...
     #       end
@@ -25,17 +25,51 @@ module RSpec
     # @see Configuration#filter_run_including
     # @see Configuration#filter_run_excluding
     module Metadata
+      # Matches strings either at the beginning of the input or prefixed with a
+      # whitespace, containing the current path, either postfixed with the
+      # separator, or at the end of the string. Match groups are the character
+      # before and the character after the string if any.
+      #
+      # http://rubular.com/r/fT0gmX6VJX
+      # http://rubular.com/r/duOrD4i3wb
+      # http://rubular.com/r/sbAMHFrOx1
+      def self.relative_path_regex
+        @relative_path_regex ||= /(\A|\s)#{File.expand_path('.')}(#{File::SEPARATOR}|\s|\Z)/
+      end
+
       # @api private
       #
       # @param line [String] current code line
       # @return [String] relative path to line
       def self.relative_path(line)
-        line = line.sub(File.expand_path("."), ".")
-        line = line.sub(/\A([^:]+:\d+)$/, '\\1')
-        return nil if line == '-e:1'
+        line = line.sub(relative_path_regex, "\\1.\\2".freeze)
+        line = line.sub(/\A([^:]+:\d+)$/, '\\1'.freeze)
+        return nil if line == '-e:1'.freeze
         line
       rescue SecurityError
+        # :nocov:
         nil
+        # :nocov:
+      end
+
+      # @private
+      # Iteratively walks up from the given metadata through all
+      # example group ancestors, yielding each metadata hash along the way.
+      def self.ascending(metadata)
+        yield metadata
+        return unless (group_metadata = metadata.fetch(:example_group) { metadata[:parent_example_group] })
+
+        loop do
+          yield group_metadata
+          break unless (group_metadata = group_metadata[:parent_example_group])
+        end
+      end
+
+      # @private
+      # Returns an enumerator that iteratively walks up the given metadata through all
+      # example group ancestors, yielding each metadata hash along the way.
+      def self.ascend(metadata)
+        enum_for(:ascending, metadata)
       end
 
       # @private
@@ -46,9 +80,7 @@ module RSpec
       def self.build_hash_from(args, warn_about_example_group_filtering=false)
         hash = args.last.is_a?(Hash) ? args.pop : {}
 
-        while args.last.is_a?(Symbol)
-          hash[args.pop] = true
-        end
+        hash[args.pop] = true while args.last.is_a?(Symbol)
 
         if warn_about_example_group_filtering && hash.key?(:example_group)
           RSpec.deprecate("Filtering by an `:example_group` subhash",
@@ -59,9 +91,24 @@ module RSpec
       end
 
       # @private
-      def self.backtrace_from(block)
-        return caller unless block.respond_to?(:source_location)
-        [block.source_location.join(':')]
+      def self.deep_hash_dup(object)
+        return object.dup if Array === object
+        return object unless Hash  === object
+
+        object.inject(object.dup) do |duplicate, (key, value)|
+          duplicate[key] = deep_hash_dup(value)
+          duplicate
+        end
+      end
+
+      # @private
+      def self.id_from(metadata)
+        "#{metadata[:rerun_file_path]}[#{metadata[:scoped_id]}]"
+      end
+
+      # @private
+      def self.location_tuple_from(metadata)
+        [metadata[:absolute_file_path], metadata[:line_number]]
       end
 
       # @private
@@ -70,9 +117,10 @@ module RSpec
       class HashPopulator
         attr_reader :metadata, :user_metadata, :description_args, :block
 
-        def initialize(metadata, user_metadata, description_args, block)
+        def initialize(metadata, user_metadata, index_provider, description_args, block)
           @metadata         = metadata
           @user_metadata    = user_metadata
+          @index_provider   = index_provider
           @description_args = description_args
           @block            = block
         end
@@ -80,7 +128,6 @@ module RSpec
         def populate
           ensure_valid_user_keys
 
-          metadata[:execution_result] = Example::ExecutionResult.new
           metadata[:block]            = block
           metadata[:description_args] = description_args
           metadata[:description]      = build_description_from(*metadata[:description_args])
@@ -89,81 +136,95 @@ module RSpec
 
           populate_location_attributes
           metadata.update(user_metadata)
-          RSpec.configuration.apply_derived_metadata_to(metadata)
         end
 
       private
 
         def populate_location_attributes
-          file_path, line_number = if backtrace = user_metadata.delete(:caller)
-            file_path_and_line_number_from(backtrace)
-          elsif block.respond_to?(:source_location)
-            block.source_location
-          else
-            file_path_and_line_number_from(caller)
-          end
-
-          file_path              = Metadata.relative_path(file_path)
-          metadata[:file_path]   = file_path
-          metadata[:line_number] = line_number.to_i
-          metadata[:location]    = "#{file_path}:#{line_number}"
+          backtrace = user_metadata.delete(:caller)
+
+          file_path, line_number = if backtrace
+                                     file_path_and_line_number_from(backtrace)
+                                   elsif block.respond_to?(:source_location)
+                                     block.source_location
+                                   else
+                                     file_path_and_line_number_from(caller)
+                                   end
+
+          relative_file_path            = Metadata.relative_path(file_path)
+          absolute_file_path            = File.expand_path(relative_file_path)
+          metadata[:file_path]          = relative_file_path
+          metadata[:line_number]        = line_number.to_i
+          metadata[:location]           = "#{relative_file_path}:#{line_number}"
+          metadata[:absolute_file_path] = absolute_file_path
+          metadata[:rerun_file_path]  ||= relative_file_path
+          metadata[:scoped_id]          = build_scoped_id_for(absolute_file_path)
         end
 
         def file_path_and_line_number_from(backtrace)
-          first_caller_from_outside_rspec = backtrace.detect { |l| l !~ CallerFilter::LIB_REGEX }
+          first_caller_from_outside_rspec = backtrace.find { |l| l !~ CallerFilter::LIB_REGEX }
           first_caller_from_outside_rspec ||= backtrace.first
           /(.+?):(\d+)(?:|:\d+)/.match(first_caller_from_outside_rspec).captures
         end
 
         def description_separator(parent_part, child_part)
-          if parent_part.is_a?(Module) && child_part =~ /^(#|::|\.)/
-            ''
+          if parent_part.is_a?(Module) && /^(?:#|::|\.)/.match(child_part.to_s)
+            ''.freeze
           else
-            ' '
+            ' '.freeze
           end
         end
 
         def build_description_from(parent_description=nil, my_description=nil)
           return parent_description.to_s unless my_description
+          return my_description.to_s if parent_description.to_s == ''
           separator = description_separator(parent_description, my_description)
-          parent_description.to_s + separator + my_description.to_s
+          (parent_description.to_s + separator) << my_description.to_s
+        end
+
+        def build_scoped_id_for(file_path)
+          index = @index_provider.call(file_path).to_s
+          parent_scoped_id = metadata.fetch(:scoped_id) { return index }
+          "#{parent_scoped_id}:#{index}"
         end
 
         def ensure_valid_user_keys
           RESERVED_KEYS.each do |key|
-            if user_metadata.has_key?(key)
-              raise <<-EOM.gsub(/^\s+\|/, '')
-                |#{"*"*50}
-                |:#{key} is not allowed
-                |
-                |RSpec reserves some hash keys for its own internal use,
-                |including :#{key}, which is used on:
-                |
-                |  #{CallerFilter.first_non_rspec_line}.
-                |
-                |Here are all of RSpec's reserved hash keys:
-                |
-                |  #{RESERVED_KEYS.join("\n  ")}
-                |#{"*"*50}
-              EOM
-            end
+            next unless user_metadata.key?(key)
+            raise <<-EOM.gsub(/^\s+\|/, '')
+              |#{"*" * 50}
+              |:#{key} is not allowed
+              |
+              |RSpec reserves some hash keys for its own internal use,
+              |including :#{key}, which is used on:
+              |
+              |  #{CallerFilter.first_non_rspec_line}.
+              |
+              |Here are all of RSpec's reserved hash keys:
+              |
+              |  #{RESERVED_KEYS.join("\n  ")}
+              |#{"*" * 50}
+            EOM
           end
         end
       end
 
       # @private
       class ExampleHash < HashPopulator
-        def self.create(group_metadata, user_metadata, description, block)
+        def self.create(group_metadata, user_metadata, index_provider, description, block)
           example_metadata = group_metadata.dup
           group_metadata = Hash.new(&ExampleGroupHash.backwards_compatibility_default_proc do |hash|
             hash[:parent_example_group]
           end)
           group_metadata.update(example_metadata)
 
+          example_metadata[:execution_result] = Example::ExecutionResult.new
           example_metadata[:example_group] = group_metadata
+          example_metadata[:shared_group_inclusion_backtrace] = SharedExampleGroupInclusionStackFrame.current_backtrace
           example_metadata.delete(:parent_example_group)
 
-          hash = new(example_metadata, user_metadata, [description].compact, block)
+          description_args = description.nil? ? [] : [description]
+          hash = new(example_metadata, user_metadata, index_provider, description_args, block)
           hash.populate
           hash.metadata
         end
@@ -184,7 +245,7 @@ module RSpec
 
       # @private
       class ExampleGroupHash < HashPopulator
-        def self.create(parent_group_metadata, user_metadata, *args, &block)
+        def self.create(parent_group_metadata, user_metadata, example_group_index, *args, &block)
           group_metadata = hash_with_backwards_compatibility_default_proc
 
           if parent_group_metadata
@@ -192,7 +253,7 @@ module RSpec
             group_metadata[:parent_example_group] = parent_group_metadata
           end
 
-          hash = new(group_metadata, user_metadata, args, block)
+          hash = new(group_metadata, user_metadata, example_group_index, args, block)
           hash.populate
           hash.metadata
         end
@@ -205,20 +266,22 @@ module RSpec
           Proc.new do |hash, key|
             case key
             when :example_group
-              # We commonly get here when rspec-core is applying a previously configured
-              # filter rule, such as when a gem configures:
+              # We commonly get here when rspec-core is applying a previously
+              # configured filter rule, such as when a gem configures:
               #
               #   RSpec.configure do |c|
               #     c.include MyGemHelpers, :example_group => { :file_path => /spec\/my_gem_specs/ }
               #   end
               #
-              # It's confusing for a user to get a deprecation at this point in the code, so instead
-              # we issue a deprecation from the config APIs that take a metadata hash, and MetadataFilter
-              # sets this thread local to silence the warning here since it would be so confusing.
-              unless RSpec.thread_local_metadata[:silence_metadata_example_group_deprecations]
+              # It's confusing for a user to get a deprecation at this point in
+              # the code, so instead we issue a deprecation from the config APIs
+              # that take a metadata hash, and MetadataFilter sets this thread
+              # local to silence the warning here since it would be so
+              # confusing.
+              unless RSpec::Support.thread_local_data[:silence_metadata_example_group_deprecations]
                 RSpec.deprecate("The `:example_group` key in an example group's metadata hash",
-                                :replacement => "the example group's hash directly for the " +
-                                "computed keys and `:parent_example_group` to access the parent " +
+                                :replacement => "the example group's hash directly for the " \
+                                "computed keys and `:parent_example_group` to access the parent " \
                                 "example group metadata")
               end
 
@@ -261,14 +324,21 @@ module RSpec
       # @private
       RESERVED_KEYS = [
         :description,
+        :description_args,
+        :described_class,
         :example_group,
         :parent_example_group,
         :execution_result,
+        :last_run_status,
         :file_path,
+        :absolute_file_path,
+        :rerun_file_path,
         :full_description,
         :line_number,
         :location,
-        :block
+        :scoped_id,
+        :block,
+        :shared_group_inclusion_backtrace
       ]
     end
 
@@ -357,7 +427,7 @@ module RSpec
         to_h
       end
 
-      def issue_deprecation(method_name, *args)
+      def issue_deprecation(_method_name, *_args)
         # no-op by default: subclasses can override
       end
 
@@ -395,7 +465,8 @@ module RSpec
     #     `metadata[:example_group][:described_class]` when you use
     #     anonymous controller specs) such that changes are written
     #     back to the top-level metadata hash.
-    #   * Exposes the parent group metadata as `[:example_group][:example_group]`.
+    #   * Exposes the parent group metadata as
+    #     `[:example_group][:example_group]`.
     class LegacyExampleGroupHash
       include HashImitatable
 

data/lib/rspec/core/metadata_filter.rb

@@ -6,89 +6,249 @@ module RSpec
     # having metadata be a raw hash (not a custom subclass), so externalizing
     # this filtering logic helps us move in that direction.
     module MetadataFilter
-      extend self
+      class << self
+        # @private
+        def apply?(predicate, filters, metadata)
+          filters.__send__(predicate) { |k, v| filter_applies?(k, v, metadata) }
+        end
 
-      # @private
-      def any_apply?(filters, metadata)
-        filters.any? { |k, v| filter_applies?(k, v, metadata) }
-      end
+        # @private
+        def filter_applies?(key, filter_value, metadata)
+          silence_metadata_example_group_deprecations do
+            return location_filter_applies?(filter_value, metadata) if key == :locations
+            return id_filter_applies?(filter_value, metadata)       if key == :ids
+            return filters_apply?(key, filter_value, metadata)      if Hash === filter_value
 
-      # @private
-      def all_apply?(filters, metadata)
-        filters.all? { |k, v| filter_applies?(k, v, metadata) }
+            meta_value = metadata.fetch(key) { return false }
+
+            return true if TrueClass === filter_value && meta_value
+            return proc_filter_applies?(key, filter_value, metadata) if Proc === filter_value
+            return filter_applies_to_any_value?(key, filter_value, metadata) if Array === meta_value
+
+            filter_value === meta_value || filter_value.to_s == meta_value.to_s
+          end
+        end
+
+        # @private
+        def silence_metadata_example_group_deprecations
+          RSpec::Support.thread_local_data[:silence_metadata_example_group_deprecations] = true
+          yield
+        ensure
+          RSpec::Support.thread_local_data.delete(:silence_metadata_example_group_deprecations)
+        end
+
+      private
+
+        def filter_applies_to_any_value?(key, value, metadata)
+          metadata[key].any? { |v| filter_applies?(key, v,  key => value) }
+        end
+
+        def id_filter_applies?(rerun_paths_to_scoped_ids, metadata)
+          scoped_ids = rerun_paths_to_scoped_ids.fetch(metadata[:rerun_file_path]) { return false }
+
+          Metadata.ascend(metadata).any? do |meta|
+            scoped_ids.include?(meta[:scoped_id])
+          end
+        end
+
+        def location_filter_applies?(locations, metadata)
+          Metadata.ascend(metadata).any? do |meta|
+            file_path = meta[:absolute_file_path]
+            line_num  = meta[:line_number]
+
+            locations[file_path].any? do |filter_line_num|
+              line_num == RSpec.world.preceding_declaration_line(file_path, filter_line_num)
+            end
+          end
+        end
+
+        def proc_filter_applies?(key, proc, metadata)
+          case proc.arity
+          when 0 then proc.call
+          when 2 then proc.call(metadata[key], metadata)
+          else proc.call(metadata[key])
+          end
+        end
+
+        def filters_apply?(key, value, metadata)
+          subhash = metadata[key]
+          return false unless Hash === subhash || HashImitatable === subhash
+          value.all? { |k, v| filter_applies?(k, v, subhash) }
+        end
       end
+    end
 
+    # Tracks a collection of filterable items (e.g. modules, hooks, etc)
+    # and provides an optimized API to get the applicable items for the
+    # metadata of an example or example group.
+    #
+    # There are two implementations, optimized for different uses.
+    # @private
+    module FilterableItemRepository
+      # This implementation is simple, and is optimized for frequent
+      # updates but rare queries. `append` and `prepend` do no extra
+      # processing, and no internal memoization is done, since this
+      # is not optimized for queries.
+      #
+      # This is ideal for use by a example or example group, which may
+      # be updated multiple times with globally configured hooks, etc,
+      # but will not be queried frequently by other examples or example
+      # groups.
       # @private
-      def filter_applies?(key, value, metadata)
-        silence_metadata_example_group_deprecations do
-          return filter_applies_to_any_value?(key, value, metadata) if Array === metadata[key] && !(Proc === value)
-          return location_filter_applies?(value, metadata)          if key == :locations
-          return filters_apply?(key, value, metadata)               if Hash === value
-
-          return false unless metadata.has_key?(key)
-
-          case value
-          when Regexp
-            metadata[key] =~ value
-          when Proc
-            case value.arity
-            when 0 then value.call
-            when 2 then value.call(metadata[key], metadata)
-            else value.call(metadata[key])
+      class UpdateOptimized
+        attr_reader :items_and_filters
+
+        def initialize(applies_predicate)
+          @applies_predicate = applies_predicate
+          @items_and_filters = []
+        end
+
+        def append(item, metadata)
+          @items_and_filters << [item, metadata]
+        end
+
+        def prepend(item, metadata)
+          @items_and_filters.unshift [item, metadata]
+        end
+
+        def delete(item, metadata)
+          @items_and_filters.delete [item, metadata]
+        end
+
+        def items_for(request_meta)
+          @items_and_filters.each_with_object([]) do |(item, item_meta), to_return|
+            to_return << item if item_meta.empty? ||
+                                 MetadataFilter.apply?(@applies_predicate, item_meta, request_meta)
+          end
+        end
+
+        unless [].respond_to?(:each_with_object) # For 1.8.7
+          # :nocov:
+          undef items_for
+          def items_for(request_meta)
+            @items_and_filters.inject([]) do |to_return, (item, item_meta)|
+              to_return << item if item_meta.empty? ||
+                                   MetadataFilter.apply?(@applies_predicate, item_meta, request_meta)
+              to_return
             end
-          else
-            metadata[key].to_s == value.to_s
           end
+          # :nocov:
         end
       end
 
-    private
+      # This implementation is much more complex, and is optimized for
+      # rare (or hopefully no) updates once the queries start. Updates
+      # incur a cost as it has to clear the memoization and keep track
+      # of applicable keys. Queries will be O(N) the first time an item
+      # is provided with a given set of applicable metadata; subsequent
+      # queries with items with the same set of applicable metadata will
+      # be O(1) due to internal memoization.
+      #
+      # This is ideal for use by config, where filterable items (e.g. hooks)
+      # are typically added at the start of the process (e.g. in `spec_helper`)
+      # and then repeatedly queried as example groups and examples are defined.
+      # @private
+      class QueryOptimized < UpdateOptimized
+        alias find_items_for items_for
+        private :find_items_for
 
-      def filter_applies_to_any_value?(key, value, metadata)
-        metadata[key].any? {|v| filter_applies?(key, v, {key => value})}
-      end
+        def initialize(applies_predicate)
+          super
+          @applicable_keys   = Set.new
+          @proc_keys         = Set.new
+          @memoized_lookups  = Hash.new do |hash, applicable_metadata|
+            hash[applicable_metadata] = find_items_for(applicable_metadata)
+          end
+        end
 
-      def location_filter_applies?(locations, metadata)
-        # it ignores location filters for other files
-        line_number = example_group_declaration_line(locations, metadata)
-        line_number ? line_number_filter_applies?(line_number, metadata) : true
-      end
+        def append(item, metadata)
+          super
+          handle_mutation(metadata)
+        end
 
-      def line_number_filter_applies?(line_numbers, metadata)
-        preceding_declaration_lines = line_numbers.map {|n| RSpec.world.preceding_declaration_line(n)}
-        !(relevant_line_numbers(metadata) & preceding_declaration_lines).empty?
-      end
+        def prepend(item, metadata)
+          super
+          handle_mutation(metadata)
+        end
 
-      def relevant_line_numbers(metadata)
-        return [] unless metadata
-        [metadata[:line_number]].compact + (relevant_line_numbers(parent_of metadata))
-      end
+        def delete(item, metadata)
+          super
+          reconstruct_caches
+        end
 
-      def example_group_declaration_line(locations, metadata)
-        parent = parent_of(metadata)
-        return nil unless parent
-        locations[File.expand_path(parent[:file_path])]
-      end
+        def items_for(metadata)
+          # The filtering of `metadata` to `applicable_metadata` is the key thing
+          # that makes the memoization actually useful in practice, since each
+          # example and example group have different metadata (e.g. location and
+          # description). By filtering to the metadata keys our items care about,
+          # we can ignore extra metadata keys that differ for each example/group.
+          # For example, given `config.include DBHelpers, :db`, example groups
+          # can be split into these two sets: those that are tagged with `:db` and those
+          # that are not. For each set, this method for the first group in the set is
+          # still an `O(N)` calculation, but all subsequent groups in the set will be
+          # constant time lookups when they call this method.
+          applicable_metadata = applicable_metadata_from(metadata)
 
-      def filters_apply?(key, value, metadata)
-        subhash = metadata[key]
-        return false unless Hash === subhash || HashImitatable === subhash
-        value.all? { |k, v| filter_applies?(k, v, subhash) }
-      end
+          if applicable_metadata.any? { |k, _| @proc_keys.include?(k) }
+            # It's unsafe to memoize lookups involving procs (since they can
+            # be non-deterministic), so we skip the memoization in this case.
+            find_items_for(applicable_metadata)
+          else
+            @memoized_lookups[applicable_metadata]
+          end
+        end
+
+      private
 
-      def parent_of(metadata)
-        if metadata.key?(:example_group)
-          metadata[:example_group]
-        else
-          metadata[:parent_example_group]
+        def reconstruct_caches
+          @applicable_keys.clear
+          @proc_keys.clear
+          @items_and_filters.each do |_item, metadata|
+            handle_mutation(metadata)
+          end
         end
-      end
 
-      def silence_metadata_example_group_deprecations
-        RSpec.thread_local_metadata[:silence_metadata_example_group_deprecations] = true
-        yield
-      ensure
-        RSpec.thread_local_metadata.delete(:silence_metadata_example_group_deprecations)
+        def handle_mutation(metadata)
+          @applicable_keys.merge(metadata.keys)
+          @proc_keys.merge(proc_keys_from metadata)
+          @memoized_lookups.clear
+        end
+
+        def applicable_metadata_from(metadata)
+          MetadataFilter.silence_metadata_example_group_deprecations do
+            @applicable_keys.inject({}) do |hash, key|
+              # :example_group is treated special here because...
+              # - In RSpec 2, example groups had an `:example_group` key
+              # - In RSpec 3, that key is deprecated (it was confusing!).
+              # - The key is not technically present in an example group metadata hash
+              #   (and thus would fail the `metadata.key?(key)` check) but a value
+              #   is provided when accessed via the hash's `default_proc`
+              # - Thus, for backwards compatibility, we have to explicitly check
+              #   for `:example_group` here if it is one of the keys being used to
+              #   filter.
+              hash[key] = metadata[key] if metadata.key?(key) || key == :example_group
+              hash
+            end
+          end
+        end
+
+        def proc_keys_from(metadata)
+          metadata.each_with_object([]) do |(key, value), to_return|
+            to_return << key if Proc === value
+          end
+        end
+
+        unless [].respond_to?(:each_with_object) # For 1.8.7
+          # :nocov:
+          undef proc_keys_from
+          def proc_keys_from(metadata)
+            metadata.inject([]) do |to_return, (key, value)|
+              to_return << key if Proc === value
+              to_return
+            end
+          end
+          # :nocov:
+        end
       end
     end
   end