rspec-core 2.8.0.rc1 → 2.8.0.rc2

data/lib/rspec/core/let.rb

@@ -2,23 +2,23 @@ module RSpec
   module Core
     module Let
 
-      module ClassMethods
+      module ExampleGroupMethods
         # Generates a method whose return value is memoized
         # after the first call.
         #
         # @example
         #
-        #  describe Thing do
-        #    let(:thing) { Thing.new }
+        #   describe Thing do
+        #     let(:thing) { Thing.new }
         #
-        #    it "does something" do
-        #      # first invocation, executes block, memoizes and returns result
-        #      thing.do_something
+        #     it "does something" do
+        #       # first invocation, executes block, memoizes and returns result
+        #       thing.do_something
         #
-        #      # second invocation, returns the memoized value
-        #      thing.should be_something
-        #    end
-        #  end
+        #       # second invocation, returns the memoized value
+        #       thing.should be_something
+        #     end
+        #   end
         def let(name, &block)
           define_method(name) do
             __memoized.fetch(name) {|k| __memoized[k] = instance_eval(&block) }
@@ -32,69 +32,70 @@ module RSpec
         #
         # @example
         #
-        #  class Thing
-        #    def self.count
-        #      @count ||= 0
-        #    end
-        #
-        #    def self.count=(val)
-        #      @count += val
-        #    end
-        #
-        #    def self.reset_count
-        #      @count = 0
-        #    end
-        #
-        #    def initialize
-        #      self.class.count += 1
-        #    end
-        #  end
-        #
-        #  describe Thing do
-        #    after(:each) { Thing.reset_count }
-        #
-        #    context "using let" do
-        #      let(:thing) { Thing.new }
-        #
-        #      it "is not invoked implicitly" do
-        #        Thing.count.should eq(0)
-        #      end
-        #
-        #      it "can be invoked explicitly" do
-        #        thing
-        #        Thing.count.should eq(1)
-        #      end
-        #    end
-        #
-        #    context "using let!" do
-        #      let!(:thing) { Thing.new }
-        #
-        #      it "is invoked implicitly" do
-        #        Thing.count.should eq(1)
-        #      end
-        #
-        #      it "returns memoized version on first invocation" do
-        #        thing
-        #        Thing.count.should eq(1)
-        #      end
-        #    end
-        #  end
+        #   class Thing
+        #     def self.count
+        #       @count ||= 0
+        #     end
+        #
+        #     def self.count=(val)
+        #       @count += val
+        #     end
+        #
+        #     def self.reset_count
+        #       @count = 0
+        #     end
+        #
+        #     def initialize
+        #       self.class.count += 1
+        #     end
+        #   end
+        #
+        #   describe Thing do
+        #     after(:each) { Thing.reset_count }
+        #
+        #     context "using let" do
+        #       let(:thing) { Thing.new }
+        #
+        #       it "is not invoked implicitly" do
+        #         Thing.count.should eq(0)
+        #       end
+        #
+        #       it "can be invoked explicitly" do
+        #         thing
+        #         Thing.count.should eq(1)
+        #       end
+        #     end
+        #
+        #     context "using let!" do
+        #       let!(:thing) { Thing.new }
+        #
+        #       it "is invoked implicitly" do
+        #         Thing.count.should eq(1)
+        #       end
+        #
+        #       it "returns memoized version on first invocation" do
+        #         thing
+        #         Thing.count.should eq(1)
+        #       end
+        #     end
+        #   end
         def let!(name, &block)
           let(name, &block)
           before { __send__(name) }
         end
       end
 
-      module InstanceMethods
-        private
+      # @private
+      module ExampleMethods
+        # @private
         def __memoized
           @__memoized ||= {}
         end
       end
 
       def self.included(mod)
-        mod.extend ClassMethods
-        mod.__send__ :include, InstanceMethods
+        mod.extend ExampleGroupMethods
+        mod.__send__ :include, ExampleMethods
       end
 
     end

data/lib/rspec/core/metadata.rb

@@ -1,13 +1,35 @@
 module RSpec
   module Core
-    # Each ExampleGroup class and Example instance ...
+    # Each ExampleGroup class and Example instance owns an instance of
+    # Metadata, which is Hash extended to support lazy evaluation of values
+    # associated with keys that may or may not be used by any example or group.
+    #
+    # In addition to metadata that is used internally, this also stores
+    # user-supplied metadata, e.g.
+    #
+    #     describe Something, :type => :ui do
+    #       it "does something", :slow => true do
+    #         # ...
+    #       end
+    #     end
+    #
+    # `:type => :ui` is stored in the Metadata owned by the example group, and
+    # `:slow => true` is stored in the Metadata owned by the example. These can
+    # then be used to select which examples are run using the `--tag` option on
+    # the command line, or several methods on `Configuration` used to filter a
+    # run (e.g. `filter_run_including`, `filter_run_excluding`, etc).
     #
     # @see Example#metadata
     # @see ExampleGroup.metadata
+    # @see FilterManager
+    # @see Configuration#filter_run_including
+    # @see Configuration#filter_run_excluding
     class Metadata < Hash
 
+      # @private
       module MetadataHash
 
+        # @private
         # Supports lazy evaluation of some values. Extended by
         # ExampleMetadataHash and GroupMetadataHash, which get mixed in to
         # Metadata for ExampleGroups and Examples (respectively).
@@ -23,10 +45,13 @@ module RSpec
             super
           when :execution_result
             store(:execution_result, {})
-          when :describes
-            store(:describes, described_class_for(self))
+          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_for(self))
+            store(:full_description, full_description)
           when :description
             store(:description, build_description_from(*self[:description_args]))
           else
@@ -34,7 +59,7 @@ module RSpec
           end
         end
 
-      private
+        private
 
         def location
           "#{self[:file_path]}:#{self[:line_number]}"
@@ -49,16 +74,8 @@ module RSpec
           self[:caller].detect {|l| l !~ /\/lib\/rspec\/core/}
         end
 
-        def described_class_for(m)
-          m[:example_group][:describes]
-        end
-
-        def full_description_for(m)
-          build_description_from(m[:example_group][:full_description], *m[:description_args])
-        end
-
         def build_description_from(*parts)
-          parts.map {|p| p.to_s}.reduce do |desc, p|
+          parts.map {|p| p.to_s}.inject do |desc, p|
             p =~ /^(#|::|\.)/ ? "#{desc}#{p}" : "#{desc} #{p}"
           end || ""
         end
@@ -68,6 +85,14 @@ module RSpec
       # lazy evaluation of some values.
       module ExampleMetadataHash
         include MetadataHash
+
+        def described_class
+          self[:example_group].described_class
+        end
+
+        def full_description
+          build_description_from(self[:example_group][:full_description], *self[:description_args])
+        end
       end
 
       # Mixed in to Metadata for an ExampleGroup (extends MetadataHash) to
@@ -75,14 +100,13 @@ module RSpec
       module GroupMetadataHash
         include MetadataHash
 
-        private
-
-        def described_class_for(*)
-          ancestors.each do |g|
-            return g[:describes] if g.has_key?(:describes)
+        def described_class
+          container_stack.each do |g|
+            return g[:describes]       if g.has_key?(:describes)
+            return g[:described_class] if g.has_key?(:described_class)
           end
 
-          ancestors.reverse.each do |g|
+          container_stack.reverse.each do |g|
             candidate = g[:description_args].first
             return candidate unless String === candidate || Symbol === candidate
           end
@@ -90,30 +114,26 @@ module RSpec
           nil
         end
 
-        def full_description_for(*)
-          build_description_from(*ancestors.reverse.map do |a|
-            a[:description_args]
-          end.flatten)
+        def full_description
+          build_description_from(*container_stack.reverse.map {|a| a[:description_args]}.flatten)
         end
 
-      private
-
-        def ancestors
-          @ancestors ||= begin
-                           groups = [group = self]
-                           while group.has_key?(:example_group)
-                             groups << group[:example_group]
-                             group = group[:example_group]
-                           end
-                           groups
-                         end
+        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
         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))
+          store(:example_group, {:example_group => parent_group_metadata[:example_group].extend(GroupMetadataHash)}.extend(GroupMetadataHash))
         else
           store(:example_group, {}.extend(GroupMetadataHash))
         end
@@ -121,7 +141,7 @@ module RSpec
         yield self if block_given?
       end
 
-      # @api private
+      # @private
       def process(*args)
         user_metadata = args.last.is_a?(Hash) ? args.pop : {}
         ensure_valid_keys(user_metadata)
@@ -132,36 +152,29 @@ module RSpec
         update(user_metadata)
       end
 
-      # @api private
+      # @private
       def for_example(description, user_metadata)
         dup.extend(ExampleMetadataHash).configure_for_example(description, user_metadata)
       end
 
-      # @api private
+      # @private
       def any_apply?(filters)
         filters.any? {|k,v| filter_applies?(k,v)}
       end
 
-      # @api private
+      # @private
       def all_apply?(filters)
         filters.all? {|k,v| filter_applies?(k,v)}
       end
 
-      # @api private
+      # @private
       def filter_applies?(key, value, metadata=self)
+        return metadata.filter_applies_to_any_value?(key, value) if Array === metadata[key]
+        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
+
         case value
-        when Hash
-          if key == :locations
-            file_path     = (self[:example_group] || {})[:file_path]
-            expanded_path = file_path && File.expand_path( file_path )
-            if expanded_path && line_numbers = value[expanded_path]
-              filter_applies?(:line_numbers, line_numbers)
-            else
-              true
-            end
-          else
-            value.all? { |k, v| filter_applies?(k, v, metadata[key]) }
-          end
         when Regexp
           metadata[key] =~ value
         when Proc
@@ -176,21 +189,35 @@ module RSpec
           else
             value.call(metadata[key]) rescue false
           end
-        when String
-          metadata[key].to_s == value.to_s
-        when Enumerable
-          if key == :line_numbers
-            preceding_declaration_lines = value.map{|v| world.preceding_declaration_line(v)}
-            !(relevant_line_numbers(metadata) & preceding_declaration_lines).empty?
-          else
-            metadata[key] == value
-          end
         else
           metadata[key].to_s == value.to_s
         end
       end
 
-    protected
+      # @private
+      def filters_apply?(key, value)
+        value.all? {|k, v| filter_applies?(k, v, self[key])}
+      end
+
+      # @private
+      def filter_applies_to_any_value?(key, value)
+        self[key].any? {|v| filter_applies?(key, v, {key => value})}
+      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
+      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?
+      end
+
+      protected
 
       def configure_for_example(description, user_metadata)
         store(:description_args, [description])
@@ -198,7 +225,7 @@ module RSpec
         update(user_metadata)
       end
 
-    private
+      private
 
       RESERVED_KEYS = [
         :description,
@@ -212,37 +239,33 @@ module RSpec
 
       def ensure_valid_keys(user_metadata)
         RESERVED_KEYS.each do |key|
-          if user_metadata.keys.include?(key)
+          if user_metadata.has_key?(key)
             raise <<-EOM
-#{"*"*50}
+            #{"*"*50}
 :#{key} is not allowed
 
 RSpec reserves some hash keys for its own internal use,
 including :#{key}, which is used on:
 
-  #{caller(0)[4]}.
+            #{caller(0)[4]}.
 
 Here are all of RSpec's reserved hash keys:
 
-  #{RESERVED_KEYS.join("\n  ")}
-#{"*"*50}
-EOM
-            raise ":#{key} is not allowed"
+            #{RESERVED_KEYS.join("\n  ")}
+            #{"*"*50}
+            EOM
           end
         end
       end
 
-      def world
-        RSpec.world
+      def example_group_declaration_line(locations)
+        locations[File.expand_path(self[:example_group][:file_path])] if self[:example_group]
       end
 
-      def relevant_line_numbers(metadata)
-        line_numbers = [metadata[:line_number]]
-        if metadata[:example_group]
-          line_numbers + relevant_line_numbers(metadata[:example_group])
-        else
-          line_numbers
-        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]) : [])
       end
 
     end