Merge pull request #2013 from rspec/add_example_finished_notification

Add example_finished to the formatter protocol

Author: JonRowe

Changelog.md

@@ -9,6 +9,8 @@ Enhancements:
   objects, replacing Ruby's excessively verbose output. (Gavin Miller, #1922)
 * Add `silence_filter_announcements` configuration option.
   (David Raffensperger, #2007)
+* Add optional `example_finished` notification to the reporter protocol for
+  when you don't care about the example outcome. (Jon Rowe, #2013)
 
 ### 3.3.1 / 2015-06-18
 [Full Changelog](http://github.com/rspec/rspec-core/compare/v3.3.0...v3.3.1)

lib/rspec/core/example.rb

@@ -406,6 +406,7 @@ def start(reporter)
       def finish(reporter)
         pending_message = execution_result.pending_message
 
+        reporter.example_finished(self)
         if @exception
           record_finished :failed
           execution_result.exception = @exception

lib/rspec/core/formatters/protocol.rb

@@ -66,6 +66,15 @@ class Protocol
         # @param notification [ExampleNotification] containing example subclass
         #   of `RSpec::Core::Example`
 
+        # @method example_finished
+        # @api public
+        # @group Example Notifications
+        #
+        # Invoked at the end of the execution of each example.
+        #
+        # @param notification [ExampleNotification] containing example subclass
+        #   of `RSpec::Core::Example`
+
         # @method example_passed
         # @api public
         # @group Example Notifications

lib/rspec/core/reporter.rb

@@ -8,7 +8,7 @@ class Reporter
         :close, :deprecation, :deprecation_summary, :dump_failures, :dump_pending,
         :dump_profile, :dump_summary, :example_failed, :example_group_finished,
         :example_group_started, :example_passed, :example_pending, :example_started,
-        :message, :seed, :start, :start_dump, :stop
+        :message, :seed, :start, :start_dump, :stop, :example_finished
       ])
 
     def initialize(configuration)
@@ -124,6 +124,11 @@ def example_started(example)
       notify :example_started, Notifications::ExampleNotification.for(example)
     end
 
+    # @private
+    def example_finished(example)
+      notify :example_finished, Notifications::ExampleNotification.for(example)
+    end
+
     # @private
     def example_passed(example)
       notify :example_passed, Notifications::ExampleNotification.for(example)

spec/rspec/core/reporter_spec.rb

@@ -76,30 +76,47 @@ module RSpec::Core
         reporter.example_started(example)
       end
 
-      it "passes example_group_started and example_group_finished messages to that formatter in that order" do
+      it "passes messages to the formatter in the correct order" do
         order = []
 
         formatter = double("formatter")
         allow(formatter).to receive(:example_group_started)  { |n| order << "Started: #{n.group.description}" }
+        allow(formatter).to receive(:example_started)        { |n| order << "Started Example" }
+        allow(formatter).to receive(:example_finished)       { |n| order << "Finished Example" }
+        allow(formatter).to receive(:example_passed)         { |n| order << "Passed" }
+        allow(formatter).to receive(:example_pending)        { |n| order << "Pending" }
+        allow(formatter).to receive(:example_failed)         { |n| order << "Failed" }
         allow(formatter).to receive(:example_group_finished) { |n| order << "Finished: #{n.group.description}" }
 
-        reporter.register_listener formatter, :example_group_started, :example_group_finished
+        reporter.register_listener formatter, :example_group_started, :example_group_finished,
+                                              :example_started, :example_finished,
+                                              :example_passed, :example_failed, :example_pending
 
         group = RSpec.describe("root")
         group.describe("context 1") do
-          example("ignore") {}
+          example("passing example") {}
+          example("pending example", :skip => true) { }
         end
         group.describe("context 2") do
-          example("ignore") {}
+          example("failed example") { fail }
         end
 
         group.run(reporter)
 
         expect(order).to eq([
            "Started: root",
            "Started: context 1",
+           "Started Example",
+           "Finished Example",
+           "Passed",
+           "Started Example",
+           "Finished Example",
+           "Pending",
            "Finished: context 1",
            "Started: context 2",
+           "Started Example",
+           "Finished Example",
+           "Failed",
            "Finished: context 2",
            "Finished: root"
         ])