rspec-core 2.9.0 → 2.10.0

data/lib/rspec/core/formatters/base_text_formatter.rb

@@ -47,13 +47,22 @@ module RSpec
           output.puts
 
           failed_examples.each do |example|
-            output.puts(red("rspec #{BaseFormatter::relative_path(example.location)}") + " " + cyan("# #{example.full_description}"))
+            output.puts(red("rspec #{RSpec::Core::Metadata::relative_path(example.location)}") + " " + cyan("# #{example.full_description}"))
           end
         end
 
         def dump_profile
-          sorted_examples = examples.sort_by { |example| example.execution_result[:run_time] }.reverse.first(10)
-          output.puts "\nTop #{sorted_examples.size} slowest examples:\n"
+          sorted_examples = examples.sort_by {|example|
+            example.execution_result[:run_time] }.reverse.first(10)
+
+          total, slows = [examples, sorted_examples].map {|exs|
+            exs.inject(0.0) {|i, e| i + e.execution_result[:run_time] }}
+
+          time_taken = slows / total
+          percentage = '%.1f' % ((time_taken.nan? ? 0.0 : time_taken) * 100)
+
+          output.puts "\nTop #{sorted_examples.size} slowest examples (#{format_seconds(slows)} seconds, #{percentage}% of total time):\n"
+
           sorted_examples.each do |example|
             output.puts "  #{example.full_description}"
             output.puts cyan("    #{red(format_seconds(example.execution_result[:run_time]))} #{red("seconds")} #{format_caller(example.location)}")
@@ -186,7 +195,7 @@ module RSpec
         end
 
         def group_and_ancestors(example)
-          example.example_group.ancestors.push(example.example_group)
+          example.example_group.ancestors + [example.example_group]
         end
       end
     end

data/lib/rspec/core/hooks.rb

@@ -3,96 +3,105 @@ module RSpec
     module Hooks
       include MetadataHashBuilder::WithConfigWarning
 
-      class Hook
+      module HookExtension
         attr_reader :options
 
-        def initialize(options, &block)
+        def with(options)
           @options = options
-          raise "no block given for #{display_name}" unless block
-          @block = block
+          self
         end
 
         def options_apply?(example_or_group)
           example_or_group.all_apply?(options)
         end
+      end
 
-        def to_proc
-          @block
-        end
+      module BeforeHookExtension
+        include HookExtension
 
-        def call
-          @block.call
+        def run(example)
+          example.instance_eval(&self)
         end
 
         def display_name
-          self.class.name.split('::').last.gsub('Hook','').downcase << " hook"
+          "before hook"
         end
       end
 
-      class BeforeHook < Hook
-        def run_in(example_group_instance)
-          if example_group_instance
-            example_group_instance.instance_eval(&self)
-          else
-            call
-          end
+      module AfterHookExtension
+        include HookExtension
+
+        def run(example)
+          example.instance_eval_with_rescue(&self)
         end
-      end
 
-      class AfterHook < Hook
-        def run_in(example_group_instance)
-          if example_group_instance
-            example_group_instance.instance_eval_with_rescue(&self)
-          else
-            call
-          end
+        def display_name
+          "after hook"
         end
       end
 
-      class AroundHook < Hook
-        def call(wrapped_example)
-          @block.call(wrapped_example)
+      module AroundHookExtension
+        include HookExtension
+
+        def display_name
+          "around hook"
         end
       end
 
       class HookCollection < Array
-        def find_hooks_for(example_or_group)
-          self.class.new(select {|hook| hook.options_apply?(example_or_group)})
+        def for(example_or_group)
+          self.class.new(select {|hook| hook.options_apply?(example_or_group)}).
+            with(example_or_group)
         end
 
-        def without_hooks_for(example_or_group)
-          self.class.new(reject {|hook| hook.options_apply?(example_or_group)})
+        def with(example)
+          @example = example
+          self
+        end
+
+        def run
+          each {|h| h.run(@example) } unless empty?
         end
       end
 
-      class BeforeHooks < HookCollection
-        def run_all(example_group_instance)
-          each {|h| h.run_in(example_group_instance) } unless empty?
+      class GroupHookCollection < Array
+        def for(group)
+          @group = group
+          self
         end
 
-        def run_all!(example_group_instance)
-          shift.run_in(example_group_instance) until empty?
+        def run
+          shift.run(@group) until empty?
         end
       end
 
-      class AfterHooks < HookCollection
-        def run_all(example_group_instance)
-          reverse.each {|h| h.run_in(example_group_instance) }
+      class AroundHookCollection < Array
+        def for(example, initial_procsy=nil)
+          self.class.new(select {|hook| hook.options_apply?(example)}).
+            with(example, initial_procsy)
         end
 
-        def run_all!(example_group_instance)
-          pop.run_in(example_group_instance) until empty?
+        def with(example, initial_procsy)
+          @example = example
+          @initial_procsy = initial_procsy
+          self
         end
-      end
 
-      class AroundHooks < HookCollection; end
+        def run
+          inject(@initial_procsy) do |procsy, around_hook|
+            Example.procsy(procsy.metadata) do
+              @example.instance_eval_with_args(procsy, &around_hook)
+            end
+          end.call
+        end
+      end
 
       # @private
       def hooks
         @hooks ||= {
-          :around => { :each => AroundHooks.new },
-          :before => { :each => BeforeHooks.new, :all => BeforeHooks.new, :suite => BeforeHooks.new },
-          :after => { :each => AfterHooks.new, :all => AfterHooks.new, :suite => AfterHooks.new }
+          :around => { :each => AroundHookCollection.new },
+          :before => { :each => [], :all => [], :suite => HookCollection.new },
+          :after =>  { :each => [], :all => [], :suite => HookCollection.new }
         }
       end
 
@@ -256,7 +265,18 @@ module RSpec
       #     end
       def before(*args, &block)
         scope, options = scope_and_options_from(*args)
-        hooks[:before][scope] << BeforeHook.new(options, &block)
+        hooks[:before][scope] << block.extend(BeforeHookExtension).with(options)
+      end
+
+      alias_method :append_before, :before
+
+      # Adds `block` to the front of the list of `before` blocks in the same
+      # scope (`:each`, `:all`, or `:suite`).
+      #
+      # See #before for scoping semantics.
+      def prepend_before(*args, &block)
+        scope, options = scope_and_options_from(*args)
+        hooks[:before][scope].unshift block.extend(BeforeHookExtension).with(options)
       end
 
       # @api public
@@ -309,7 +329,18 @@ module RSpec
       # they are run in reverse order of that in which they are declared.
       def after(*args, &block)
         scope, options = scope_and_options_from(*args)
-        hooks[:after][scope] << AfterHook.new(options, &block)
+        hooks[:after][scope].unshift block.extend(AfterHookExtension).with(options)
+      end
+
+      alias_method :prepend_after, :after
+
+      # Adds `block` to the back of the list of `after` blocks in the same
+      # scope (`:each`, `:all`, or `:suite`).
+      #
+      # See #after for scoping semantics.
+      def append_after(*args, &block)
+        scope, options = scope_and_options_from(*args)
+        hooks[:after][scope] << block.extend(AfterHookExtension).with(options)
       end
 
       # @api public
@@ -358,59 +389,71 @@ module RSpec
       #
       def around(*args, &block)
         scope, options = scope_and_options_from(*args)
-        hooks[:around][scope] << AroundHook.new(options, &block)
+        hooks[:around][scope].unshift block.extend(AroundHookExtension).with(options)
       end
 
       # @private
+      #
       # Runs all of the blocks stored with the hook in the context of the
       # example. If no example is provided, just calls the hook directly.
-      def run_hook(hook, scope, example_group_instance=nil)
-        hooks[hook][scope].run_all(example_group_instance)
+      def run_hook(hook, scope, example_or_group=ExampleGroup.new, initial_procsy=nil)
+        find_hook(hook, scope, example_or_group, initial_procsy).run
       end
 
       # @private
-      # Just like run_hook, except it removes the blocks as it evalutes them,
-      # ensuring that they will only be run once.
-      def run_hook!(hook, scope, example_group_instance)
-        hooks[hook][scope].run_all!(example_group_instance)
+      def around_each_hooks_for(example, initial_procsy=nil)
+        AroundHookCollection.new(ancestors.map {|a| a.hooks[:around][:each]}.flatten).for(example, initial_procsy)
       end
 
-      # @private
-      def run_hook_filtered(hook, scope, group, example_group_instance, example = nil)
-        find_hook(hook, scope, group, example).run_all(example_group_instance)
+    private
+
+      def before_all_hooks_for(group)
+        GroupHookCollection.new(hooks[:before][:all]).for(group)
       end
 
-      # @private
-      def find_hook(hook, scope, example_group_class, example = nil)
-        found_hooks = hooks[hook][scope].find_hooks_for(example || example_group_class)
-
-        # ensure we don't re-run :all hooks that were applied to any of the parent groups
-        if scope == :all
-          super_klass = example_group_class.superclass
-          while super_klass != RSpec::Core::ExampleGroup
-            found_hooks = found_hooks.without_hooks_for(super_klass)
-            super_klass = super_klass.superclass
-          end
-        end
+      def after_all_hooks_for(group)
+        GroupHookCollection.new(hooks[:after][:all]).for(group)
+      end
 
-        found_hooks
+      def before_each_hooks_for(example)
+        HookCollection.new(ancestors.reverse.map {|a| a.hooks[:before][:each]}.flatten).for(example)
       end
 
-    private
+      def after_each_hooks_for(example)
+        HookCollection.new(ancestors.map {|a| a.hooks[:after][:each]}.flatten).for(example)
+      end
+
+      def find_hook(hook, scope, example_or_group, initial_procsy)
+        case [hook, scope]
+        when [:before, :all]
+          before_all_hooks_for(example_or_group)
+        when [:after, :all]
+          after_all_hooks_for(example_or_group)
+        when [:around, :each]
+          around_each_hooks_for(example_or_group, initial_procsy)
+        when [:before, :each]
+          before_each_hooks_for(example_or_group)
+        when [:after, :each]
+          after_each_hooks_for(example_or_group)
+        when [:before, :suite], [:after, :suite]
+          hooks[hook][:suite].with(example_or_group)
+        end
+      end
 
       SCOPES = [:each, :all, :suite]
 
       def scope_and_options_from(*args)
-        scope = if SCOPES.include?(args.first)
+        return extract_scope_from(args), build_metadata_hash_from(args)
+      end
+
+      def extract_scope_from(args)
+        if SCOPES.include?(args.first)
           args.shift
         elsif args.any? { |a| a.is_a?(Symbol) }
           raise ArgumentError.new("You must explicitly give a scope (:each, :all, or :suite) when using symbols as metadata for a hook.")
         else
           :each
         end
-
-        options = build_metadata_hash_from(args)
-        return scope, options
       end
     end
   end

data/lib/rspec/core/let.rb

@@ -3,8 +3,17 @@ module RSpec
     module Let
 
       module ExampleGroupMethods
-        # Generates a method whose return value is memoized
-        # after the first call.
+        # Generates a method whose return value is memoized after the first
+        # call. Useful for reducing duplication between examples that assign
+        # values to the same local variable.
+        #
+        # @note `let` _can_ enhance readability when used sparingly (1,2, or
+        #   maybe 3 declarations) in any given example group, but that can
+        #   quickly degrade with overuse. YMMV.
+        #
+        # @note `let` uses an `||=` conditional that has the potential to
+        #   behave in surprising ways in examples that spawn separate threads,
+        #   though we have yet to see this in practice. You've been warned.
         #
         # @example
         #
@@ -25,10 +34,9 @@ module RSpec
           end
         end
 
-        # Just like <tt>let()</tt>, except the block is invoked
-        # by an implicit <tt>before</tt> hook. This serves a dual
-        # purpose of setting up state and providing a memoized
-        # reference to that state.
+        # Just like `let`, 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

@@ -26,6 +26,13 @@ module RSpec
     # @see Configuration#filter_run_excluding
     class Metadata < Hash
 
+      def self.relative_path(line)
+        line = line.sub(File.expand_path("."), ".")
+        line = line.sub(/\A([^:]+:\d+)$/, '\\1')
+        return nil if line == '-e:1'
+        line
+      end
+
       # @private
       module MetadataHash
 
@@ -67,7 +74,7 @@ module RSpec
 
         def file_and_line_number
           first_caller_from_outside_rspec =~ /(.+?):(\d+)(|:\d+)/
-          return [$1, $2.to_i]
+          return [Metadata::relative_path($1), $2.to_i]
         end
 
         def first_caller_from_outside_rspec
@@ -181,8 +188,9 @@ module RSpec
           metadata[key] =~ value
         when Proc
           case value.arity
-          when 1 then value.call(metadata[key])
+          when 0 then value.call
           when 2 then value.call(metadata[key], metadata)
+          else value.call(metadata[key])
           end
         else
           metadata[key].to_s == value.to_s

data/lib/rspec/core/subject.rb

@@ -3,17 +3,29 @@ module RSpec
     module Subject
       module ExampleMethods
 
-        # Returns the subject defined by the example group. The subject block is
-        # only executed once per example, the result of which is cached and
-        # returned by any subsequent calls to +subject+.
+        # Returns the subject defined by the example group. The subject block
+        # is only executed once per example, the result of which is cached and
+        # returned by any subsequent calls to `subject`.
         #
-        # If a class is passed to +describe+ and no subject is explicitly
-        # declared in the example group, then +subject+ will return a new
+        # If a class is passed to `describe` and no subject is explicitly
+        # declared in the example group, then `subject` will return a new
         # instance of that class.
         #
+        # @note `subject` was contributed by Joe Ferris to support the one-liner
+        #   syntax embraced by shoulda matchers:
+        #
+        #       describe Widget do
+        #         it { should validate_presence_of(:name) }
+        #       end
+        #
+        #   While the examples below demonstrate how to use `subject`
+        #   explicitly in specs, we think it works best for extensions like
+        #   shoulda, custom matchers, and shared example groups, where it is
+        #   not referenced explicitly in specs.
+        #
         # @example
         #
-        #   # explicit subject defined by the subject method
+        #   # explicit declaration of subject
         #   describe Person do
         #     subject { Person.new(:birthdate => 19.years.ago) }
         #     it "should be eligible to vote" do
@@ -27,6 +39,11 @@ module RSpec
         #       subject.should be_eligible_to_vote
         #     end
         #   end
+        #
+        #   describe Person do
+        #     # one liner syntax - should is invoked on subject
+        #     it { should be_eligible_to_vote }
+        #   end
         def subject
           if defined?(@original_subject)
             @original_subject
@@ -36,9 +53,7 @@ module RSpec
         end
 
         begin
-          require 'rspec/expectations/extensions/kernel'
-          alias_method :__should_for_example_group__,     :should
-          alias_method :__should_not_for_example_group__, :should_not
+          require 'rspec/expectations/handler'
 
           # When +should+ is called with no explicit receiver, the call is
           # delegated to the object returned by +subject+. Combined with
@@ -51,7 +66,7 @@ module RSpec
           #     it { should be_eligible_to_vote }
           #   end
           def should(matcher=nil, message=nil)
-            self == subject ? self.__should_for_example_group__(matcher) : subject.should(matcher,message)
+            RSpec::Expectations::PositiveExpectationHandler.handle_matcher(subject, matcher, message)
           end
 
           # Just like +should+, +should_not+ delegates to the subject (implicit or
@@ -63,7 +78,7 @@ module RSpec
           #     it { should_not be_eligible_to_vote }
           #   end
           def should_not(matcher=nil, message=nil)
-            self == subject ? self.__should_not_for_example_group__(matcher) : subject.should_not(matcher,message)
+            RSpec::Expectations::NegativeExpectationHandler.handle_matcher(subject, matcher, message)
           end
         rescue LoadError
         end
@@ -73,8 +88,8 @@ module RSpec
         end
 
         def _nested_attribute(subject, attribute)
-          _attribute_chain(attribute).inject(subject) do |subject, attr|
-            subject.send(attr)
+          _attribute_chain(attribute).inject(subject) do |inner_subject, attr|
+            inner_subject.send(attr)
           end
         end
       end
@@ -83,6 +98,8 @@ module RSpec
         # Creates a nested example group named by the submitted +attribute+,
         # and then generates an example using the submitted block.
         #
+        # @example
+        #
         #   # This ...
         #   describe Array do
         #     its(:size) { should eq(0) }
@@ -101,6 +118,8 @@ module RSpec
         # with dots, the result is as though you concatenated that +String+
         # onto the subject in an expression.
         #
+        # @example
+        #
         #   describe Person do
         #     subject do
         #       Person.new.tap do |person|
@@ -114,6 +133,8 @@ module RSpec
         # When the subject is a +Hash+, you can refer to the Hash keys by
         # specifying a +Symbol+ or +String+ in an array.
         #
+        # @example
+        #
         #   describe "a configuration Hash" do
         #     subject do
         #       { :max_users => 3,