Allow users to set a formatter instance instead of just a class.

This is useful for when you want to initialize your formatter
with extra state. The simplest approach is for you to instantiate
the formatter yourself instead of depending on RSpec to do it and
trying to update the formatter with your desired state later.

Author: myronmarston

lib/rspec/core/configuration.rb

@@ -861,11 +861,11 @@ def full_description
       # @overload add_formatter(formatter)
       # @overload add_formatter(formatter, output)
       #
-      # @param formatter [Class, String] formatter to use. Can be any of the
+      # @param formatter [Class, String, Object] formatter to use. Can be any of the
       #   string values supported from the CLI (`p`/`progress`,
-      #   `d`/`doc`/`documentation`, `h`/`html`, or `j`/`json`) or any
+      #   `d`/`doc`/`documentation`, `h`/`html`, or `j`/`json`), any
       #   class that implements the formatter protocol and has registered
-      #   itself with RSpec as a formatter.
+      #   itself with RSpec as a formatter, or a formatter instance.
       # @param output [String, IO] where the formatter will write its output.
       #   Can be an IO object or a string path to a file. If not provided,
       #   the configured `output_stream` (`$stdout`, by default) will be used.

lib/rspec/core/formatters.rb

@@ -140,6 +140,13 @@ def setup_default(output_stream, deprecation_stream)
 
     # @private
     def add(formatter_to_use, *paths)
+      # If a formatter instance was passed, we can register it directly,
+      # with no need for any of the further processing that happens below.
+      if Loader.formatters.key?(formatter_to_use.class)
+        register formatter_to_use, notifications_for(formatter_to_use.class)
+        return
+      end
+
       formatter_class = find_formatter(formatter_to_use)
 
       args = paths.map { |p| p.respond_to?(:puts) ? p : open_stream(p) }

spec/rspec/core/formatters_spec.rb

@@ -39,6 +39,14 @@ module RSpec::Core::Formatters
         expect(loader.formatters.first).to be_an_instance_of(CustomFormatter)
       end
 
+      it "lets you pass a formatter instance, for when you need to instantiate it with some custom state" do
+        instance = ProgressFormatter.new(StringIO.new)
+
+        expect {
+          loader.add(instance)
+        }.to change { loader.formatters }.from([]).to([instance])
+      end
+
       context "when a legacy formatter is added with RSpec::LegacyFormatters" do
         formatter_class = Struct.new(:output)
         let(:formatter) { double "formatter", :notifications => notifications, :output => output }