Merge pull request #1869 from rspec/allow_publishing_custom_events_via_reporter

Allow the reporter to send custom events to registered formatters

Author: JonRowe

lib/rspec/core/notifications.rb

@@ -599,5 +599,19 @@ def self.from_hash(data)
     # currently require no information, but we may wish to extend in future.
     class NullNotification
     end
+
+    # `CustomNotification` is used when sending custom events to formatters /
+    # other registered listeners, it creates attributes based on supplied hash
+    # of options.
+    class CustomNotification < Struct
+      # @param options [Hash] A hash of method / value pairs to create on this notification
+      # @return [CustomNotification]
+      #
+      # Build a custom notification based on the supplied option key / values.
+      def self.for(options={})
+        return NullNotification if options.keys.empty?
+        new(*options.keys).new(*options.values)
+      end
+    end
   end
 end

lib/rspec/core/reporter.rb

@@ -1,7 +1,17 @@
+require 'set'
 module RSpec::Core
   # A reporter will send notifications to listeners, usually formatters for the
   # spec suite run.
   class Reporter
+    # @private
+    RSPEC_NOTIFICATIONS = Set.new(
+      [
+        :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
+      ])
+
     def initialize(configuration)
       @configuration = configuration
       @listeners = Hash.new { |h, k| h[k] = Set.new }
@@ -79,6 +89,19 @@ def message(message)
       notify :message, Notifications::MessageNotification.new(message)
     end
 
+    # @param event [Symbol] Name of the custom event to trigger on formatters
+    # @param options [Hash] Hash of arguments to provide via `CustomNotification`
+    #
+    # Publish a custom event to supporting registered formatters.
+    # @see RSpec::Core::Notifications::CustomNotification
+    def publish(event, options={})
+      if RSPEC_NOTIFICATIONS.include? event
+        raise "RSpec::Core::Reporter#publish is intended for sending custom " \
+              "events not internal RSpec ones, please rename your custom event."
+      end
+      notify event, Notifications::CustomNotification.for(options)
+    end
+
     # @private
     def example_group_started(group)
       notify :example_group_started, Notifications::GroupNotification.new(group) unless group.descendant_filtered_examples.empty?

spec/rspec/core/reporter_spec.rb

@@ -172,6 +172,37 @@ module RSpec::Core
       end
     end
 
+    describe "#publish" do
+      let(:listener) { double("listener", :custom => nil) }
+      before do
+        reporter.register_listener listener, :custom, :start
+      end
+
+      it 'will send custom events to registered listeners' do
+        expect(listener).to receive(:custom).with(RSpec::Core::Notifications::NullNotification)
+        reporter.publish :custom
+      end
+
+      it 'will raise when encountering RSpec standard events' do
+        expect { reporter.publish :start }.to raise_error(
+          StandardError,
+          a_string_including("not internal RSpec ones")
+        )
+      end
+
+      it 'will ignore event names sent as strings' do
+        expect(listener).not_to receive(:custom)
+        reporter.publish "custom"
+      end
+
+      it 'will provide a custom notification object based on the options hash' do
+        expect(listener).to receive(:custom).with(
+          an_object_having_attributes(:my_data => :value)
+        )
+        reporter.publish :custom, :my_data => :value
+      end
+    end
+
     describe "timing" do
       before do
         config.start_time = start_time

spec/support/formatter_support.rb

@@ -275,3 +275,20 @@ def profile_notification(duration, examples, number)
   end
 
 end
+
+if RSpec::Support::RubyFeatures.module_prepends_supported?
+  module RSpec::Core
+    class Reporter
+      module EnforceRSpecNotificationsListComplete
+        def notify(event, *args)
+          return super if caller_locations(1, 1).first.label =~ /publish/
+          return super if RSPEC_NOTIFICATIONS.include?(event)
+
+          raise "#{event.inspect} must be added to `RSPEC_NOTIFICATIONS`"
+        end
+      end
+
+      prepend EnforceRSpecNotificationsListComplete
+    end
+  end
+end