rspec-core 3.1.7 → 3.2.0

data/lib/rspec/core/memoized_helpers.rb

@@ -20,7 +20,7 @@ module RSpec
       #
       # @example
       #
-      #   # explicit declaration of subject
+      #   # Explicit declaration of subject.
       #   describe Person do
       #     subject { Person.new(:birthdate => 19.years.ago) }
       #     it "should be eligible to vote" do
@@ -29,7 +29,7 @@ module RSpec
       #     end
       #   end
       #
-      #   # implicit subject => { Person.new }
+      #   # Implicit subject => { Person.new }.
       #   describe Person do
       #     it "should be eligible to vote" do
       #       subject.should be_eligible_to_vote
@@ -37,17 +37,17 @@ module RSpec
       #     end
       #   end
       #
-      #   # one-liner syntax - expectation is set on the subject
+      #   # One-liner syntax - expectation is set on the subject.
       #   describe Person do
       #     it { is_expected.to be_eligible_to_vote }
       #     # or
       #     it { should be_eligible_to_vote }
       #   end
       #
-      # @note Because `subject` is designed to create state that is reset between
-      #   each example, and `before(:context)` is designed to setup state that is
-      #   shared across _all_ examples in an example group, `subject` is _not_
-      #   intended to be used in a `before(:context)` hook.
+      # @note Because `subject` is designed to create state that is reset
+      #   between each example, and `before(:context)` is designed to setup
+      #   state that is shared across _all_ examples in an example group,
+      #   `subject` is _not_ intended to be used in a `before(:context)` hook.
       #
       # @see #should
       # @see #should_not
@@ -211,8 +211,8 @@ EOS
         #   though we have yet to see this in practice. You've been warned.
         #
         # @note Because `let` is designed to create state that is reset between
-        #   each example, and `before(:context)` is designed to setup state that is
-        #   shared across _all_ examples in an example group, `let` is _not_
+        #   each example, and `before(:context)` is designed to setup state that
+        #   is shared across _all_ examples in an example group, `let` is _not_
         #   intended to be used in a `before(:context)` hook.
         #
         # @example
@@ -221,10 +221,10 @@ EOS
         #     let(:thing) { Thing.new }
         #
         #     it "does something" do
-        #       # first invocation, executes block, memoizes and returns result
+        #       # First invocation, executes block, memoizes and returns result.
         #       thing.do_something
         #
-        #       # second invocation, returns the memoized value
+        #       # Second invocation, returns the memoized value.
         #       thing.should be_something
         #     end
         #   end
@@ -302,8 +302,8 @@ EOS
         end
 
         # Declares a `subject` for an example group which can then be wrapped
-        # with `expect` using `is_expected` to make it the target of an expectation
-        # in a concise, one-line example.
+        # with `expect` using `is_expected` to make it the target of an
+        # expectation in a concise, one-line example.
         #
         # Given a `name`, defines a method with that name which returns the
         # `subject`. This lets you declare the subject once and access it
@@ -348,9 +348,9 @@ EOS
           end
         end
 
-        # Just like `subject`, except the block is invoked by an implicit `before`
-        # hook. This serves a dual purpose of setting up state and providing a
-        # memoized reference to that state.
+        # Just like `subject`, except the block is invoked by an implicit
+        # `before` hook. This serves a dual purpose of setting up state and
+        # providing a memoized reference to that state.
         #
         # @example
         #

data/lib/rspec/core/metadata.rb

@@ -25,30 +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)
-        # 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
-        #
-
-        regex = /(\A|\s)#{File.expand_path('.')}(#{File::SEPARATOR}|\s|\Z)/
-
-        line = line.sub(regex, "\\1.\\2")
-        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
         nil
       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
       # Used internally to build a hash from an args array.
       # Symbols are converted into hash keys with a value of `true`.
@@ -67,6 +88,17 @@ module RSpec
         hash
       end
 
+      # @private
+      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.backtrace_from(block)
         return caller unless block.respond_to?(:source_location)
@@ -114,10 +146,11 @@ module RSpec
                                      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}"
+          relative_file_path            = Metadata.relative_path(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] = File.expand_path(relative_file_path)
         end
 
         def file_path_and_line_number_from(backtrace)
@@ -128,16 +161,16 @@ module RSpec
 
         def description_separator(parent_part, child_part)
           if parent_part.is_a?(Module) && child_part =~ /^(#|::|\.)/
-            ''
+            ''.freeze
           else
-            ' '
+            ' '.freeze
           end
         end
 
         def build_description_from(parent_description=nil, my_description=nil)
           return parent_description.to_s unless my_description
           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 ensure_valid_user_keys
@@ -171,9 +204,11 @@ module RSpec
           group_metadata.update(example_metadata)
 
           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, description_args, block)
           hash.populate
           hash.metadata
         end
@@ -215,16 +250,18 @@ 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.
+              # 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]
                 RSpec.deprecate("The `:example_group` key in an example group's metadata hash",
                                 :replacement => "the example group's hash directly for the " \
@@ -275,6 +312,7 @@ module RSpec
         :parent_example_group,
         :execution_result,
         :file_path,
+        :absolute_file_path,
         :full_description,
         :line_number,
         :location,
@@ -405,7 +443,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

@@ -8,13 +8,8 @@ module RSpec
     module MetadataFilter
       class << self
         # @private
-        def any_apply?(filters, metadata)
-          filters.any? { |k, v| filter_applies?(k, v, metadata) }
-        end
-
-        # @private
-        def all_apply?(filters, metadata)
-          filters.all? { |k, v| filter_applies?(k, v, metadata) }
+        def apply?(predicate, filters, metadata)
+          filters.__send__(predicate) { |k, v| filter_applies?(k, v, metadata) }
         end
 
         # @private
@@ -48,9 +43,8 @@ module RSpec
         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
+          line_numbers = example_group_declaration_lines(locations, metadata)
+          line_numbers.empty? || line_number_filter_applies?(line_numbers, metadata)
         end
 
         def line_number_filter_applies?(line_numbers, metadata)
@@ -59,14 +53,13 @@ module RSpec
         end
 
         def relevant_line_numbers(metadata)
-          return [] unless metadata
-          [metadata[:line_number]].compact + (relevant_line_numbers(parent_of metadata))
+          Metadata.ascend(metadata).map { |meta| meta[:line_number] }
         end
 
-        def example_group_declaration_line(locations, metadata)
-          parent = parent_of(metadata)
-          return nil unless parent
-          locations[File.expand_path(parent[:file_path])]
+        def example_group_declaration_lines(locations, metadata)
+          FlatMap.flat_map(Metadata.ascend(metadata)) do |meta|
+            locations[meta[:absolute_file_path]]
+          end.uniq
         end
 
         def filters_apply?(key, value, metadata)
@@ -75,14 +68,6 @@ module RSpec
           value.all? { |k, v| filter_applies?(k, v, subhash) }
         end
 
-        def parent_of(metadata)
-          if metadata.key?(:example_group)
-            metadata[:example_group]
-          else
-            metadata[:parent_example_group]
-          end
-        end
-
         def silence_metadata_example_group_deprecations
           RSpec.thread_local_metadata[:silence_metadata_example_group_deprecations] = true
           yield
@@ -91,5 +76,147 @@ module RSpec
         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 examle
+      # groups.
+      # @private
+      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 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
+          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
+          end
+        end
+      end
+
+      # 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 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 append(item, metadata)
+          super
+          handle_mutation(metadata)
+        end
+
+        def prepend(item, metadata)
+          super
+          handle_mutation(metadata)
+        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)
+
+          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 handle_mutation(metadata)
+          @applicable_keys.merge(metadata.keys)
+          @proc_keys.merge(proc_keys_from metadata)
+          @memoized_lookups.clear
+        end
+
+        def applicable_metadata_from(metadata)
+          @applicable_keys.inject({}) do |hash, key|
+            hash[key] = metadata[key] if metadata.key?(key)
+            hash
+          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
+          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
+        end
+      end
+    end
   end
 end