Add duplicate_with for RSpec Example

lib/rspec/core/example.rb

@@ -124,6 +124,22 @@ def self.parse_id(id)
         id.match(/\A(.*?)(?:\[([\d\s:,]+)\])?\z/).captures
       end
 
+      # Duplicates the example and overrides metadata with the provided
+      # hash.
+      #
+      # @param metadata_overrides [Hash] the hash to override the example metadata
+      # @return [Example] a duplicate of the example with modified metadata
+      def duplicate_with(metadata_overrides={})
+        new_metadata = metadata.clone.merge(metadata_overrides)
+
+        RSpec::Core::Metadata::RESERVED_KEYS.each do |reserved_key|
+          new_metadata.delete reserved_key
+        end
+
+        Example.new(example_group.clone, description.clone,
+                    new_metadata, new_metadata[:block])
+      end
+
       # @attr_reader
       #
       # Returns the first exception raised in the context of running this

spec/rspec/core/example_spec.rb

@@ -40,6 +40,21 @@ def metadata_hash(*args)
     end
   end
 
+  describe '#duplicate_with' do
+    it 'successfully duplicates an example' do
+      example = example_group.example { raise 'first' }
+      example2 = example.duplicate_with({ :custom_key => :custom_value })
+
+      # ensure metadata is unique for each example
+      expect(example.metadata.object_id).to_not eq(example2.metadata.object_id)
+      expect(example.metadata[:custom_key]).to eq(nil)
+      expect(example2.metadata[:custom_key]).to eq(:custom_value)
+
+      # cloned examples must have unique ids
+      expect(example.id).to_not eq(example2.id)
+    end
+  end
+
   describe "#exception" do
     it "supplies the exception raised, if there is one" do
       example = example_group.example { raise "first" }