rspec-core 2.10.1 → 2.11.0

data/lib/rspec/core/example_group.rb

@@ -1,7 +1,7 @@
 module RSpec
   module Core
-    # ExampleGroup and Example are the main structural elements of rspec-core.
-    # Consider this example:
+    # ExampleGroup and {Example} are the main structural elements of
+    # rspec-core.  Consider this example:
     #
     #     describe Thing do
     #       it "does something" do
@@ -47,81 +47,118 @@ module RSpec
         alias_method :display_name, :description
         # @private
         alias_method :describes, :described_class
-      end
-
-      # @private
-      def self.define_example_method(name, extra_options={})
-        module_eval(<<-END_RUBY, __FILE__, __LINE__)
-          def self.#{name}(desc=nil, *args, &block)
-            options = build_metadata_hash_from(args)
-            options.update(:pending => RSpec::Core::Pending::NOT_YET_IMPLEMENTED) unless block
-            options.update(#{extra_options.inspect})
-            examples << RSpec::Core::Example.new(self, desc, options, block)
-            examples.last
-          end
-        END_RUBY
-      end
-
-      define_example_method :example
-      define_example_method :it
-      define_example_method :specify
 
-      define_example_method :focused,  :focused => true, :focus => true
-      define_example_method :focus,    :focused => true, :focus => true
-
-      define_example_method :pending,  :pending => true
-      define_example_method :xexample, :pending => 'Temporarily disabled with xexample'
-      define_example_method :xit,      :pending => 'Temporarily disabled with xit'
-      define_example_method :xspecify, :pending => 'Temporarily disabled with xspecify'
+        # @private
+        # @macro [attach] define_example_method
+        #   @param [String] name
+        #   @param [Hash] extra_options
+        #   @param [Block] implementation
+        def self.define_example_method(name, extra_options={})
+          module_eval(<<-END_RUBY, __FILE__, __LINE__)
+            def #{name}(desc=nil, *args, &block)
+              options = build_metadata_hash_from(args)
+              options.update(:pending => RSpec::Core::Pending::NOT_YET_IMPLEMENTED) unless block
+              options.update(#{extra_options.inspect})
+              examples << RSpec::Core::Example.new(self, desc, options, block)
+              examples.last
+            end
+          END_RUBY
+        end
 
-      class << self
-        alias_method :alias_example_to, :define_example_method
-      end
+        # Defines an example within a group.
+        define_example_method :example
+        # Defines an example within a group.
+        #
+        # @see example
+        define_example_method :it
+        # Defines an example within a group.
+        # This is here primarily for backward compatibility with early versions
+        # of RSpec which used `context` and `specify` instead of `describe` and
+        # `it`.
+        define_example_method :specify
+
+        # Shortcut to define an example with `:focus` => true
+        define_example_method :focus,   :focused => true, :focus => true
+        # Shortcut to define an example with `:focus` => true
+        define_example_method :focused, :focused => true, :focus => true
+
+        # Shortcut to define an example with :pending => true
+        define_example_method :pending,  :pending => true
+        # Shortcut to define an example with :pending => 'Temporarily disabled with xexample'
+        define_example_method :xexample, :pending => 'Temporarily disabled with xexample'
+        # Shortcut to define an example with :pending => 'Temporarily disabled with xit'
+        define_example_method :xit,      :pending => 'Temporarily disabled with xit'
+        # Shortcut to define an example with :pending => 'Temporarily disabled with xspecify'
+        define_example_method :xspecify, :pending => 'Temporarily disabled with xspecify'
+
+        # Works like `alias_method :name, :example` with the added benefit of
+        # assigning default metadata to the generated example.
+        #
+        # @note Use with caution. This extends the language used in your
+        #   specs, but does not add any additional documentation.  We use this
+        #   in rspec to define methods like `focus` and `xit`, but we also add
+        #   docs for those methods.
+        def alias_example_to name, extra={}
+          (class << self; self; end).define_example_method name, extra
+        end
 
-      # @private
-      def self.define_nested_shared_group_method(new_name, report_label=nil)
-        module_eval(<<-END_RUBY, __FILE__, __LINE__)
-          def self.#{new_name}(name, *args, &customization_block)
-            group = describe("#{report_label || "it should behave like"} \#{name}") do
-              find_and_eval_shared("examples", name, *args, &customization_block)
+        # @private
+        # @macro [attach] define_nested_shared_group_method
+        #
+        #   @see SharedExampleGroup
+        def self.define_nested_shared_group_method(new_name, report_label=nil)
+          module_eval(<<-END_RUBY, __FILE__, __LINE__)
+            def #{new_name}(name, *args, &customization_block)
+              group = describe("#{report_label || "it should behave like"} \#{name}") do
+                find_and_eval_shared("examples", name, *args, &customization_block)
+              end
+              group.metadata[:shared_group_name] = name
+              group
             end
-            group.metadata[:shared_group_name] = name
-            group
-          end
-        END_RUBY
-      end
-
-      define_nested_shared_group_method :it_should_behave_like
+          END_RUBY
+        end
 
-      class << self
-        alias_method :alias_it_should_behave_like_to, :define_nested_shared_group_method
+        # Generates a nested example group and includes the shared content
+        # mapped to `name` in the nested group.
+        define_nested_shared_group_method :it_behaves_like, "behaves like"
+        # Generates a nested example group and includes the shared content
+        # mapped to `name` in the nested group.
+        define_nested_shared_group_method :it_should_behave_like
+
+        # Works like `alias_method :name, :it_behaves_like` with the added
+        # benefit of assigning default metadata to the generated example.
+        #
+        # @note Use with caution. This extends the language used in your
+        #   specs, but does not add any additional documentation.  We use this
+        #   in rspec to define `it_should_behave_like` (for backward
+        #   compatibility), but we also add docs for that method.
+        def alias_it_behaves_like_to name, *args, &block
+          (class << self; self; end).define_nested_shared_group_method name, *args, &block
+        end
       end
 
-      alias_it_should_behave_like_to :it_behaves_like, "behaves like"
-
-      # Includes shared content declared with `name`.
+      # Includes shared content mapped to `name` directly in the group in which
+      # it is declared, as opposed to `it_behaves_like`, which creates a nested
+      # group. If given a block, that block is also eval'd in the current context.
       #
       # @see SharedExampleGroup
-      def self.include_context(name, *args)
-        block_given? ? block_not_supported("context") : find_and_eval_shared("context", name, *args)
+      def self.include_context(name, *args, &block)
+        find_and_eval_shared("context", name, *args, &block)
       end
 
-      # Includes shared content declared with `name`.
+      # Includes shared content mapped to `name` directly in the group in which
+      # it is declared, as opposed to `it_behaves_like`, which creates a nested
+      # group. If given a block, that block is also eval'd in the current context.
       #
       # @see SharedExampleGroup
-      def self.include_examples(name, *args)
-        block_given? ? block_not_supported("examples") : find_and_eval_shared("examples", name, *args)
-      end
-
-      # @private
-      def self.block_not_supported(label)
-        warn("Customization blocks not supported for include_#{label}.  Use it_behaves_like instead.")
+      def self.include_examples(name, *args, &block)
+        find_and_eval_shared("examples", name, *args, &block)
       end
 
       # @private
       def self.find_and_eval_shared(label, name, *args, &customization_block)
         raise ArgumentError, "Could not find shared #{label} #{name.inspect}" unless
-          shared_block = world.shared_example_groups[name]
+        shared_block = world.shared_example_groups[name]
 
         module_eval_with_args(*args, &shared_block)
         module_eval(&customization_block) if customization_block
@@ -149,7 +186,7 @@ module RSpec
       end
 
       # @private
-      # @return [Metadata] belonging to the parent of a nested [ExampleGroup](ExampleGroup)
+      # @return [Metadata] belonging to the parent of a nested {ExampleGroup}
       def self.superclass_metadata
         @superclass_metadata ||= self.superclass.respond_to?(:metadata) ? self.superclass.metadata : nil
       end
@@ -247,19 +284,7 @@ module RSpec
         args.unshift(symbol_description) if symbol_description
         @metadata = RSpec::Core::Metadata.new(superclass_metadata).process(*args)
         world.configure_group(self)
-        [:before, :after, :around].each do |_when|
-          RSpec.configuration.hooks[_when][:each].each do |hook|
-            unless ancestors.any? {|a| a.hooks[_when][:each].include? hook }
-              hooks[_when][:each] << hook # each's get filtered later per example
-            end
-          end
-          next if _when == :around # no around(:all) hooks
-          RSpec.configuration.hooks[_when][:all].each do |hook|
-            unless ancestors.any? {|a| a.hooks[_when][:all].include? hook }
-              hooks[_when][:all] << hook if hook.options_apply?(self)
-            end
-          end
-        end
+        hooks.register_globals(self, RSpec.configuration.hooks)
       end
 
       # @private
@@ -318,7 +343,7 @@ An error occurred in an after(:all) hook.
   #{e.class}: #{e.message}
   occurred at #{e.backtrace.first}
 
-        EOS
+      EOS
         end
       end
 
@@ -401,11 +426,11 @@ An error occurred in an after(:all) hook.
       end
 
       # @attr_reader
-      # Returns the [Example](Example) object that wraps this instance of
+      # Returns the {Example} object that wraps this instance of
       # `ExampleGroup`
       attr_accessor :example
 
-      # @deprecated use [example](ExampleGroup#example-instance_method)
+      # @deprecated use {ExampleGroup#example}
       def running_example
         RSpec.deprecate("running_example", "example")
         example
@@ -428,12 +453,12 @@ An error occurred in an after(:all) hook.
       # @private
       # instance_evals the block, capturing and reporting an exception if
       # raised
-      def instance_eval_with_rescue(&hook)
+      def instance_eval_with_rescue(context = nil, &hook)
         begin
           instance_eval(&hook)
         rescue Exception => e
           raise unless example
-          example.set_exception(e)
+          example.set_exception(e, context)
         end
       end
     end

data/lib/rspec/core/hooks.rb

@@ -32,7 +32,7 @@ module RSpec
         include HookExtension
 
         def run(example)
-          example.instance_eval_with_rescue(&self)
+          example.instance_eval_with_rescue("in an after hook", &self)
         end
 
         def display_name
@@ -48,7 +48,16 @@ module RSpec
         end
       end
 
+      module HookCollectionAliases
+        def self.included(host)
+          host.send :alias_method, :prepend, :unshift
+          host.send :alias_method, :append,  :push
+        end
+      end
+
       class HookCollection < Array
+        include HookCollectionAliases
+
         def for(example_or_group)
           self.class.new(select {|hook| hook.options_apply?(example_or_group)}).
             with(example_or_group)
@@ -64,18 +73,9 @@ module RSpec
         end
       end
 
-      class GroupHookCollection < Array
-        def for(group)
-          @group = group
-          self
-        end
-
-        def run
-          shift.run(@group) until empty?
-        end
-      end
-
       class AroundHookCollection < Array
+        include HookCollectionAliases
+
         def for(example, initial_procsy=nil)
           self.class.new(select {|hook| hook.options_apply?(example)}).
             with(example, initial_procsy)
@@ -96,13 +96,43 @@ module RSpec
         end
       end
 
+      class GroupHookCollection < Array
+        def for(group)
+          @group = group
+          self
+        end
+
+        def run
+          shift.run(@group) until empty?
+        end
+      end
+
+      module RegistersGlobals
+        def register_globals host, globals
+          [:before, :after, :around].each do |position|
+            process host, globals, position, :each
+            next if position == :around # no around(:all) hooks
+            process host, globals, position, :all
+          end
+        end
+
+        private
+        def process host, globals, position, scope
+          globals[position][scope].each do |hook|
+            unless host.ancestors.any? { |a| a.hooks[position][scope].include? hook }
+              self[position][scope] << hook if scope == :each || hook.options_apply?(host)
+            end
+          end
+        end
+      end
+
       # @private
       def hooks
         @hooks ||= {
           :around => { :each => AroundHookCollection.new },
-          :before => { :each => [], :all => [], :suite => HookCollection.new },
-          :after =>  { :each => [], :all => [], :suite => HookCollection.new }
-        }
+          :before => { :each => HookCollection.new, :all => HookCollection.new, :suite => HookCollection.new },
+          :after =>  { :each => HookCollection.new, :all => HookCollection.new, :suite => HookCollection.new }
+        }.extend(RegistersGlobals)
       end
 
       # @api public
@@ -126,12 +156,11 @@ module RSpec
       #
       # Declare a block of code to be run before each example (using `:each`)
       # or once before any example (using `:all`). These are usually declared
-      # directly in the [ExampleGroup](ExampleGroup) to which they apply, but
-      # they can also be shared across multiple groups.
+      # directly in the {ExampleGroup} to which they apply, but they can also
+      # be shared across multiple groups.
       #
       # You can also use `before(:suite)` to run a block of code before any
-      # example groups are run. This should be declared in
-      # [RSpec.configure](../../RSpec#configure-class_method)
+      # example groups are run. This should be declared in {RSpec.configure}
       #
       # Instance variables declared in `before(:each)` or `before(:all)` are
       # accessible within each example.
@@ -232,7 +261,7 @@ module RSpec
       # rspec-rails, but it will not be wrapped in a transaction for you, so
       # you are on your own to clean up in an `after(:all)` block.
       #
-      # @example before(:each) declared in an [ExampleGroup](ExampleGroup)
+      # @example before(:each) declared in an {ExampleGroup}
       #
       #     describe Thing do
       #       before(:each) do
@@ -244,7 +273,7 @@ module RSpec
       #       end
       #     end
       #
-      # @example before(:all) declared in an [ExampleGroup](ExampleGroup)
+      # @example before(:all) declared in an {ExampleGroup}
       #
       #     describe Parser do
       #       before(:all) do
@@ -264,8 +293,7 @@ module RSpec
       #       end
       #     end
       def before(*args, &block)
-        scope, options = scope_and_options_from(*args)
-        hooks[:before][scope] << block.extend(BeforeHookExtension).with(options)
+        register_hook :append, :before, *args, &block
       end
 
       alias_method :append_before, :before
@@ -275,8 +303,7 @@ module RSpec
       #
       # 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)
+        register_hook :prepend, :before, *args, &block
       end
 
       # @api public
@@ -328,8 +355,7 @@ module RSpec
       # Similarly, if more than one `after` is declared within any one scope,
       # 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].unshift block.extend(AfterHookExtension).with(options)
+        register_hook :prepend, :after, *args, &block
       end
 
       alias_method :prepend_after, :after
@@ -339,8 +365,7 @@ module RSpec
       #
       # 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)
+        register_hook :append, :after, *args, &block
       end
 
       # @api public
@@ -388,8 +413,7 @@ module RSpec
       #     around(:each) {|ex| FakeFS(&ex)}
       #
       def around(*args, &block)
-        scope, options = scope_and_options_from(*args)
-        hooks[:around][scope].unshift block.extend(AroundHookExtension).with(options)
+        register_hook :prepend, :around, *args, &block
       end
 
       # @private
@@ -407,6 +431,14 @@ module RSpec
 
     private
 
+      SCOPES = [:each, :all, :suite]
+
+      EXTENSIONS = {
+        :before => BeforeHookExtension,
+        :after  => AfterHookExtension,
+        :around => AroundHookExtension
+      }
+
       def before_all_hooks_for(group)
         GroupHookCollection.new(hooks[:before][:all]).for(group)
       end
@@ -423,6 +455,11 @@ module RSpec
         HookCollection.new(ancestors.map {|a| a.hooks[:after][:each]}.flatten).for(example)
       end
 
+      def register_hook prepend_or_append, hook, *args, &block
+        scope, options = scope_and_options_from(*args)
+        hooks[hook][scope].send(prepend_or_append, block.extend(EXTENSIONS[hook]).with(options))
+      end
+
       def find_hook(hook, scope, example_or_group, initial_procsy)
         case [hook, scope]
         when [:before, :all]
@@ -440,8 +477,6 @@ module RSpec
         end
       end
 
-      SCOPES = [:each, :all, :suite]
-
       def scope_and_options_from(*args)
         return extract_scope_from(args), build_metadata_hash_from(args)
       end