rspec-core 3.0.0.beta2 → 3.0.0.rc1

data/lib/rspec/core/memoized_helpers.rb

@@ -1,5 +1,9 @@
 module RSpec
   module Core
+    # This module is included in {ExampleGroup}, making the methods
+    # available to be called from within example blocks.
+    #
+    # @see ClassMethods
     module MemoizedHelpers
       # @note `subject` was contributed by Joe Ferris to support the one-liner
       #   syntax embraced by shoulda matchers:
@@ -41,13 +45,13 @@ module RSpec
       #   end
       #
       # @note Because `subject` is designed to create state that is reset between
-      #   each example, and `before(:all)` is designed to setup state that is
+      #   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(:all)` hook. RSpec 2.13.1 prints
-      #   a warning when you reference a `subject` from `before(:all)` and we plan
-      #   to have it raise an error in RSpec 3.
+      #   intended to be used in a `before(:context)` hook.
       #
       # @see #should
+      # @see #should_not
+      # @see #is_expected
       def subject
         __memoized.fetch(:subject) do
           __memoized[:subject] = begin
@@ -115,7 +119,7 @@ module RSpec
         expect(subject)
       end
 
-      private
+    private
 
       # @private
       def __memoized
@@ -123,14 +127,14 @@ module RSpec
       end
 
       # Used internally to customize the behavior of the
-      # memoized hash when used in a `before(:all)` hook.
+      # memoized hash when used in a `before(:context)` hook.
       #
       # @private
-      class AllHookMemoizedHash
-        def self.isolate_for_all_hook(example_group_instance)
+      class ContextHookMemoizedHash
+        def self.isolate_for_context_hook(example_group_instance)
           hash = self
 
-          example_group_instance.instance_eval do
+          example_group_instance.instance_exec do
             @__memoized = hash
 
             begin
@@ -159,9 +163,10 @@ is reset between each example, while #{hook_expression} exists to
 EOS
         end
 
+        # @private
         class Before < self
           def self.hook_expression
-            "`before(:all)`"
+            "`before(:context)`"
           end
 
           def self.article
@@ -173,9 +178,10 @@ EOS
           end
         end
 
+        # @private
         class After < self
           def self.hook_expression
-            "`after(:all)`"
+            "`after(:context)`"
           end
 
           def self.article
@@ -188,10 +194,9 @@ EOS
         end
       end
 
-      def self.included(mod)
-        mod.extend(ClassMethods)
-      end
-
+      # This module is extended onto {ExampleGroup}, making the methods
+      # available to be called from within example group blocks.
+      # You can think of them as being analagous to class macros.
       module ClassMethods
         # Generates a method whose return value is memoized after the first
         # call. Useful for reducing duplication between examples that assign
@@ -206,11 +211,9 @@ 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(:all)` is designed to setup state that is
+        #   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(:all)` hook. RSpec 2.13.1 prints
-        #   a warning when you reference a `let` from `before(:all)` and we plan
-        #   to have it raise an error in RSpec 3.
+        #   intended to be used in a `before(:context)` hook.
         #
         # @example
         #
@@ -265,7 +268,7 @@ EOS
         #   end
         #
         #   describe Thing do
-        #     after(:each) { Thing.reset_count }
+        #     after(:example) { Thing.reset_count }
         #
         #     context "using let" do
         #       let(:thing) { Thing.new }
@@ -307,7 +310,7 @@ EOS
         # implicitly in one-liners and explicitly using an intention revealing
         # name.
         #
-        # @param [String,Symbol] name used to define an accessor with an
+        # @param name [String,Symbol] used to define an accessor with an
         #   intention revealing name
         # @param block defines the value to be returned by `subject` in examples
         #
@@ -328,6 +331,8 @@ EOS
         #   end
         #
         # @see MemoizedHelpers#should
+        # @see MemoizedHelpers#should_not
+        # @see MemoizedHelpers#is_expected
         def subject(name=nil, &block)
           if name
             let(name, &block)
@@ -366,7 +371,7 @@ EOS
         #   end
         #
         #   describe Thing do
-        #     after(:each) { Thing.reset_count }
+        #     after(:example) { Thing.reset_count }
         #
         #     context "using subject" do
         #       subject { Thing.new }
@@ -400,7 +405,7 @@ EOS
         end
       end
 
-      # @api private
+      # @private
       #
       # Gets the LetDefinitions module. The module is mixed into
       # the example group and is used to hold all let definitions.
@@ -425,13 +430,13 @@ EOS
         end
       end
 
-      # @api private
+      # @private
       def self.define_helpers_on(example_group)
         example_group.__send__(:include, module_for(example_group))
       end
 
       if Module.method(:const_defined?).arity == 1 # for 1.8
-        # @api private
+        # @private
         #
         # Gets the named constant or yields.
         # On 1.8, const_defined? / const_get do not take into
@@ -444,7 +449,7 @@ EOS
           end
         end
       else
-        # @api private
+        # @private
         #
         # Gets the named constant or yields.
         # On 1.9, const_defined? / const_get take into account the

data/lib/rspec/core/metadata.rb

@@ -24,8 +24,11 @@ module RSpec
     # @see FilterManager
     # @see Configuration#filter_run_including
     # @see Configuration#filter_run_excluding
-    class Metadata < Hash
-
+    module Metadata
+      # @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')
@@ -50,264 +53,354 @@ module RSpec
         hash
       end
 
-      module MetadataHash
+      # @private
+      def self.backtrace_from(block)
+        return caller unless block.respond_to?(:source_location)
+        [block.source_location.join(':')]
+      end
 
-        # @private
-        # Supports lazy evaluation of some values. Extended by
-        # ExampleMetadataHash and GroupMetadataHash, which get mixed in to
-        # Metadata for ExampleGroups and Examples (respectively).
-        def [](key)
-          store_computed(key) unless has_key?(key)
-          super
+      # @private
+      # Used internally to populate metadata hashes with computed keys
+      # managed by RSpec.
+      class HashPopulator
+        attr_reader :metadata, :user_metadata, :description_args, :block
+
+        def initialize(metadata, user_metadata, description_args, block)
+          @metadata         = metadata
+          @user_metadata    = user_metadata
+          @description_args = description_args
+          @block            = block
         end
 
-        def fetch(key, *args)
-          store_computed(key) unless has_key?(key)
-          super
+        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])
+          metadata[:full_description] = full_description
+          metadata[:described_class]  = described_class
+
+          populate_location_attributes
+          metadata.update(user_metadata)
+          RSpec.configuration.apply_derived_metadata_to(metadata)
         end
 
-        private
-
-        def store_computed(key)
-          case key
-          when :location
-            store(:location, location)
-          when :file_path, :line_number
-            file_path, line_number = file_and_line_number
-            store(:file_path, file_path)
-            store(:line_number, line_number)
-          when :execution_result
-            store(:execution_result, {})
-          when :describes, :described_class
-            klass = described_class
-            store(:described_class, klass)
-            # TODO (2011-11-07 DC) deprecate :describes as a key
-            store(:describes, klass)
-          when :full_description
-            store(:full_description, full_description)
-          when :description
-            store(:description, build_description_from(*self[:description_args]))
-          when :description_args
-            store(:description_args, [])
+      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
-        end
 
-        def location
-          "#{self[:file_path]}:#{self[:line_number]}"
+          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}"
         end
 
-        def file_and_line_number
-          first_caller_from_outside_rspec =~ /(.+?):(\d+)(|:\d+)/
-          return [Metadata::relative_path($1), $2.to_i]
+        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.first
+          /(.+?):(\d+)(?:|:\d+)/.match(first_caller_from_outside_rspec).captures
         end
 
-        def first_caller_from_outside_rspec
-          self[:caller].detect {|l| l !~ /\/lib\/rspec\/core/}
+        def description_separator(parent_part, child_part)
+          if parent_part.is_a?(Module) && child_part =~ /^(#|::|\.)/
+            ''
+          else
+            ' '
+          end
         end
 
-        def method_description_after_module?(parent_part, child_part)
-          return false unless parent_part.is_a?(Module)
-          child_part =~ /^(#|::|\.)/
+        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
         end
 
-        def build_description_from(first_part = '', *parts)
-          description, _ = parts.inject([first_part.to_s, first_part]) do |(desc, last_part), this_part|
-            this_part = this_part.to_s
-            this_part = (' ' + this_part) unless method_description_after_module?(last_part, this_part)
-            [(desc + this_part), this_part]
+        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
           end
-
-          description
         end
       end
 
-      # Mixed in to Metadata for an Example (extends MetadataHash) to support
-      # lazy evaluation of some values.
-      module ExampleMetadataHash
-        include MetadataHash
+      # @private
+      class ExampleHash < HashPopulator
+        def self.create(group_metadata, user_metadata, 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[:example_group] = group_metadata
+          example_metadata.delete(:parent_example_group)
+
+          hash = new(example_metadata, user_metadata, [description].compact, block)
+          hash.populate
+          hash.metadata
+        end
+
+      private
 
         def described_class
-          self[:example_group].described_class
+          metadata[:example_group][:described_class]
         end
 
         def full_description
-          build_description_from(self[:example_group][:full_description], *self[:description_args])
+          build_description_from(
+            metadata[:example_group][:full_description],
+            metadata[:description]
+          )
         end
       end
 
-      # Mixed in to Metadata for an ExampleGroup (extends MetadataHash) to
-      # support lazy evaluation of some values.
-      module GroupMetadataHash
-        include MetadataHash
+      # @private
+      class ExampleGroupHash < HashPopulator
+        def self.create(parent_group_metadata, user_metadata, *args, &block)
+          group_metadata = hash_with_backwards_compatibility_default_proc
+          group_metadata.update(parent_group_metadata)
+          group_metadata[:parent_example_group] = parent_group_metadata
+
+          hash = new(group_metadata, user_metadata, args, block)
+          hash.populate
+          hash.metadata
+        end
 
-        def described_class
-          container_stack.each do |g|
-            [:described_class, :describes].each do |key|
-              if g.has_key?(key)
-                value = g[key]
-                return value unless value.nil?
-              end
+        def self.hash_with_backwards_compatibility_default_proc
+          Hash.new(&backwards_compatibility_default_proc { |hash| hash })
+        end
+
+        def self.backwards_compatibility_default_proc(&example_group_selector)
+          Proc.new do |hash, key|
+            case key
+            when :example_group
+              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 " +
+                              "example group metadata")
+              LegacyExampleGroupHash.new(example_group_selector.call(hash))
+            when :example_group_block
+              RSpec.deprecate("`metadata[:example_group_block]`",
+                              :replacement => "`metadata[:block]`")
+              hash[:block]
+            when :describes
+              RSpec.deprecate("`metadata[:describes]`",
+                              :replacement => "`metadata[:described_class]`")
+              hash[:described_class]
             end
           end
+        end
 
-          container_stack.reverse.each do |g|
-            candidate = g[:description_args].first
-            return candidate unless String === candidate || Symbol === candidate
-          end
+      private
 
-          nil
+        def described_class
+          candidate = metadata[:description_args].first
+          return candidate unless NilClass === candidate || String === candidate
+          parent_group = metadata[:parent_example_group]
+          parent_group && parent_group[:described_class]
         end
 
         def full_description
-          build_description_from(*FlatMap.flat_map(container_stack.reverse) {|a| a[:description_args]})
-        end
+          description          = metadata[:description]
+          parent_example_group = metadata[:parent_example_group]
+          parent_description   = parent_example_group[:full_description]
+
+          return description unless parent_description
 
-        def container_stack
-          @container_stack ||= begin
-                                 groups = [group = self]
-                                 while group.has_key?(:example_group)
-                                   groups << group[:example_group]
-                                   group = group[:example_group]
-                                 end
-                                 groups
-                               end
+          separator = description_separator(parent_example_group[:description_args].last,
+                                            metadata[:description_args].first)
+
+          parent_description + separator + description
         end
       end
 
-      def initialize(parent_group_metadata=nil)
-        if parent_group_metadata
-          update(parent_group_metadata)
-          store(:example_group, {:example_group => parent_group_metadata[:example_group].extend(GroupMetadataHash)}.extend(GroupMetadataHash))
-        else
-          store(:example_group, {}.extend(GroupMetadataHash))
-        end
+      # @private
+      RESERVED_KEYS = [
+        :description,
+        :example_group,
+        :parent_example_group,
+        :execution_result,
+        :file_path,
+        :full_description,
+        :line_number,
+        :location,
+        :block
+      ]
+    end
 
-        yield self if block_given?
+    # Mixin that makes the including class imitate a hash for backwards
+    # compatibility. The including class should use `attr_accessor` to
+    # declare attributes.
+    # @private
+    module HashImitatable
+      def self.included(klass)
+        klass.extend ClassMethods
       end
 
-      # @private
-      def process(*args)
-        user_metadata = args.last.is_a?(Hash) ? args.pop : {}
-        ensure_valid_keys(user_metadata)
+      def to_h
+        hash = extra_hash_attributes.dup
 
-        self[:example_group].store(:description_args, args)
-        self[:example_group].store(:caller, user_metadata.delete(:caller) || caller)
+        self.class.hash_attribute_names.each do |name|
+          hash[name] = __send__(name)
+        end
 
-        update(user_metadata)
+        hash
       end
 
-      # @private
-      def for_example(description, user_metadata)
-        dup.extend(ExampleMetadataHash).configure_for_example(description, user_metadata)
-      end
+      (Hash.public_instance_methods - Object.public_instance_methods).each do |method_name|
+        next if [:[], :[]=, :to_h].include?(method_name.to_sym)
 
-      # @private
-      def any_apply?(filters)
-        filters.any? {|k,v| filter_applies?(k,v)}
-      end
+        define_method(method_name) do |*args, &block|
+          issue_deprecation(method_name, *args)
 
-      # @private
-      def all_apply?(filters)
-        filters.all? {|k,v| filter_applies?(k,v)}
-      end
+          hash = hash_for_delegation
+          self.class.hash_attribute_names.each do |name|
+            hash.delete(name) unless instance_variable_defined?(:"@#{name}")
+          end
 
-      # @private
-      def filter_applies?(key, value, metadata=self)
-        return metadata.filter_applies_to_any_value?(key, value) if Array === metadata[key] && !(Proc === value)
-        return metadata.line_number_filter_applies?(value)       if key == :line_numbers
-        return metadata.location_filter_applies?(value)          if key == :locations
-        return metadata.filters_apply?(key, value)               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])
+          hash.__send__(method_name, *args, &block).tap do
+            # apply mutations back to the object
+            hash.each do |name, value|
+              if directly_supports_attribute?(name)
+                set_value(name, value)
+              else
+                extra_hash_attributes[name] = value
+              end
+            end
           end
+        end
+      end
+
+      def [](key)
+        issue_deprecation(:[], key)
+
+        if directly_supports_attribute?(key)
+          get_value(key)
         else
-          metadata[key].to_s == value.to_s
+          extra_hash_attributes[key]
         end
       end
 
-      # @private
-      def filters_apply?(key, value)
-        value.all? {|k, v| filter_applies?(k, v, self[key])}
+      def []=(key, value)
+        issue_deprecation(:[]=, key, value)
+
+        if directly_supports_attribute?(key)
+          set_value(key, value)
+        else
+          extra_hash_attributes[key] = value
+        end
       end
 
-      # @private
-      def filter_applies_to_any_value?(key, value)
-        self[key].any? {|v| filter_applies?(key, v, {key => value})}
+    private
+
+      def extra_hash_attributes
+        @extra_hash_attributes ||= {}
       end
 
-      # @private
-      def location_filter_applies?(locations)
-        # it ignores location filters for other files
-        line_number = example_group_declaration_line(locations)
-        line_number ? line_number_filter_applies?(line_number) : true
+      def directly_supports_attribute?(name)
+        self.class.hash_attribute_names.include?(name)
       end
 
-      # @private
-      def line_number_filter_applies?(line_numbers)
-        preceding_declaration_lines = line_numbers.map {|n| RSpec.world.preceding_declaration_line(n)}
-        !(relevant_line_numbers & preceding_declaration_lines).empty?
+      def get_value(name)
+        __send__(name)
       end
 
-      protected
+      def set_value(name, value)
+        __send__(:"#{name}=", value)
+      end
 
-      def configure_for_example(description, user_metadata)
-        store(:description_args, [description]) if description
-        store(:caller, user_metadata.delete(:caller) || caller)
-        update(user_metadata)
+      def hash_for_delegation
+        to_h
       end
 
-      private
+      def issue_deprecation(method_name, *args)
+        # no-op by default: subclasses can override
+      end
 
-      RESERVED_KEYS = [
-        :description,
-        :example_group,
-        :execution_result,
-        :file_path,
-        :full_description,
-        :line_number,
-        :location
-      ]
+      # @private
+      module ClassMethods
+        def hash_attribute_names
+          @hash_attribute_names ||= []
+        end
 
-      def ensure_valid_keys(user_metadata)
-        RESERVED_KEYS.each do |key|
-          if user_metadata.has_key?(key)
-            raise <<-EOM
-            #{"*"*50}
-:#{key} is not allowed
+        def attr_accessor(*names)
+          hash_attribute_names.concat(names)
+          super
+        end
+      end
+    end
 
-RSpec reserves some hash keys for its own internal use,
-including :#{key}, which is used on:
+    # @private
+    # Together with the example group metadata hash default block,
+    # provides backwards compatibility for the old `:example_group`
+    # key. In RSpec 2.x, the computed keys of a group's metadata
+    # were exposed from a nested subhash keyed by `[:example_group]`, and
+    # then the parent group's metadata was exposed by sub-subhash
+    # keyed by `[:example_group][:example_group]`.
+    #
+    # In RSpec 3, we reorganized this to that the computed keys are
+    # exposed directly of the group metadata hash (no nesting), and
+    # `:parent_example_group` returns the parent group's metadata.
+    #
+    # Maintaining backwards compatibility was difficult: we wanted
+    # `:example_group` to return an object that:
+    #
+    #   * Exposes the top-level metadata keys that used to be nested
+    #     under `:example_group`.
+    #   * Supports mutation (rspec-rails, for example, assigns
+    #     `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]`.
+    class LegacyExampleGroupHash
+      include HashImitatable
+
+      def initialize(metadata)
+        @metadata = metadata
+        parent_group_metadata = metadata.fetch(:parent_example_group) { {} }[:example_group]
+        self[:example_group] = parent_group_metadata if parent_group_metadata
+      end
 
-            #{CallerFilter.first_non_rspec_line}.
+      def to_h
+        super.merge(@metadata)
+      end
 
-Here are all of RSpec's reserved hash keys:
+    private
 
-            #{RESERVED_KEYS.join("\n  ")}
-            #{"*"*50}
-            EOM
-          end
-        end
+      def directly_supports_attribute?(name)
+        name != :example_group
       end
 
-      def example_group_declaration_line(locations)
-        locations[File.expand_path(self[:example_group][:file_path])] if self[:example_group]
+      def get_value(name)
+        @metadata[name]
       end
 
-      # TODO - make this a method on metadata - the problem is
-      # metadata[:example_group] is not always a kind of GroupMetadataHash.
-      def relevant_line_numbers(metadata=self)
-        [metadata[:line_number]] + (metadata[:example_group] ? relevant_line_numbers(metadata[:example_group]) : [])
+      def set_value(name, value)
+        @metadata[name] = value
       end
-
     end
   end
 end