Merge pull request #1479 from rspec/fix-around-hook-yielded-arg

Fix around hook yielded arg

Author: myronmarston

Changelog.md

@@ -115,6 +115,8 @@ Bug Fixes:
   that it applies to files loaded by `--require`. (Myron Marston)
 * Issue a warning when you set `config.deprecation_stream` too late for
   it to take effect because the reporter has already been setup. (Myron Marston)
+* Add the full `RSpec::Core::Example` interface to the argument yielded
+  to `around` hooks. (Myron Marston)
 
 ### 3.0.0.beta2 / 2014-02-17
 [Full Changelog](http://github.com/rspec/rspec-core/compare/v3.0.0.beta1...v3.0.0.beta2)

lib/rspec/core/example.rb

@@ -1,9 +1,11 @@
 module RSpec
   module Core
     # Wrapper for an instance of a subclass of {ExampleGroup}. An instance of
-    # `RSpec::Core::Example` is returned by the {ExampleGroup#example example}
-    # method exposed to examples, {Hooks#before before} and {Hooks#after after}
-    # hooks, and yielded to {Hooks#around around} hooks.
+    # `RSpec::Core::Example` is returned by example definition methods
+    # such as {ExampleGroup.it it} and is yielded to the {ExampleGroup.it it},
+    # {Hooks#before before}, {Hooks#after after}, {Hooks#around around},
+    # {MemoizedHelpers::ClassMethods#let let} and
+    # {MemoizedHelpers::ClassMethods#subject subject} blocks.
     #
     # This allows us to provide rich metadata about each individual
     # example without adding tons of methods directly to the ExampleGroup
@@ -15,17 +17,17 @@ module Core
     # @example
     #
     #     RSpec.configure do |config|
-    #       config.before do
+    #       config.before do |example|
     #         log example.description
     #       end
     #
-    #       config.after do
+    #       config.after do |example|
     #         log example.description
     #       end
     #
-    #       config.around do |ex|
+    #       config.around do |example|
     #         log example.description
-    #         ex.run
+    #         example.run
     #       end
     #     end
     #
@@ -38,17 +40,32 @@ module Core
     #
     # @see ExampleGroup
     # @note Example blocks are evaluated in the context of an instance
-    # of an `ExampleGroup`, not in the context of an instance of `Example`.
+    #   of an `ExampleGroup`, not in the context of an instance of `Example`.
     class Example
       # @private
       #
       # Used to define methods that delegate to this example's metadata
-      def self.delegate_to_metadata(*keys)
-        keys.each { |key| define_method(key) { @metadata[key] } }
+      def self.delegate_to_metadata(key)
+        define_method(key) { @metadata[key] }
       end
 
-      delegate_to_metadata :execution_result, :file_path, :full_description,
-                           :location, :pending, :skip
+      # @return [ExecutionResult] represents the result of running this example.
+      delegate_to_metadata :execution_result
+      # @return [String] the relative path to the file where this example was defined.
+      delegate_to_metadata :file_path
+      # @return [String] the full description (including the docstrings of
+      #   all parent example groups).
+      delegate_to_metadata :full_description
+      # @return [String] the exact source location of this example in a form
+      #   like `./path/to/spec.rb:17`
+      delegate_to_metadata :location
+      # @return [Boolean] flag that indicates that the example is not expected to pass.
+      #   It will be run and will either have a pending result (if a failure occurs)
+      #   or a failed result (if no failure occurs).
+      delegate_to_metadata :pending
+      # @return [Boolean] flag that will cause the example to not run.
+      #   The {ExecutionResult} status will be `:pending`.
+      delegate_to_metadata :skip
 
       # Returns the string submitted to `example` or its aliases (e.g.
       # `specify`, `it`, etc).  If no string is submitted (e.g. `it { is_expected.to
@@ -161,12 +178,10 @@ def run(example_group_instance, reporter)
         RSpec.current_example = nil
       end
 
-      # Wraps a `Proc` and exposes a `run` method for use in {Hooks#around
-      # around} hooks.
-      #
-      # @note Procsy, itself, is not a public API, but we're documenting it
-      #   here to document how to interact with the object yielded to an
-      #   `around` hook.
+      # Wraps both a `Proc` and an {Example} for use in {Hooks#around
+      # around} hooks. In around hooks we need to yield this special
+      # kind of object (rather than the raw {Example}) because when
+      # there are multiple `around` hooks we have to wrap them recursively.
       #
       # @example
       #
@@ -178,23 +193,30 @@ def run(example_group_instance, reporter)
       #         ex.run         # run delegates to ex.call
       #       end
       #     end
+      #
+      # @note This class also exposes the instance methods of {Example},
+      #   proxying them through to the wrapped {Example} instance.
       class Procsy
-        # The `metadata` of the {Example} instance.
-        attr_reader :metadata
+        # The {Example} instance.
+        attr_reader :example
+
+        Example.public_instance_methods(false).each do |name|
+          define_method(name) { |*a, &b| @example.__send__(name, *a, &b) }
+        end
 
         Proc.public_instance_methods(false).each do |name|
           define_method(name) { |*a, &b| @proc.__send__(name, *a, &b) }
         end
         alias run call
 
-        def initialize(metadata, &block)
-          @metadata = metadata
-          @proc = block
+        def initialize(example, &block)
+          @example = example
+          @proc    = block
         end
 
         # @private
         def wrap(&block)
-          self.class.new(metadata, &block)
+          self.class.new(example, &block)
         end
       end
 
@@ -276,7 +298,7 @@ def with_around_example_hooks(&block)
         if around_example_hooks.empty?
           yield
         else
-          @example_group_class.hooks.run(:around, :example, self, Procsy.new(metadata, &block))
+          @example_group_class.hooks.run(:around, :example, self, Procsy.new(self, &block))
         end
       rescue Exception => e
         set_exception(e, "in an `around(:example)` hook")

spec/rspec/core/hooks_spec.rb

@@ -145,6 +145,42 @@ def parent_groups
           group.run
           expect(foos).to eq({:first => :bar, :second => :bar})
         end
+
+        it "exposes the full example interface to each around hook" do
+          data_1 = {}
+          data_2 = {}
+          ex     = nil
+
+          group = ExampleGroup.describe do
+            def self.data_from(ex)
+              {
+                :description => ex.description,
+                :full_description => ex.full_description,
+                :example_group => ex.example_group,
+                :file_path => ex.file_path,
+                :location => ex.location
+              }
+            end
+
+            around do |example|
+              data_1.update(self.class.data_from example)
+              example.run
+            end
+
+            around do |example|
+              data_2.update(self.class.data_from example)
+              example.run
+            end
+
+            ex = example("the example") { }
+          end
+
+          group.run
+
+          expected_data = group.data_from(ex)
+          expect(data_1).to eq(expected_data)
+          expect(data_2).to eq(expected_data)
+        end
       end
 
       context "when running the example within a block passed to a method" do