Set alternative RSpec invocations as callables in OptionParser

RSpec can be invoked with a number of CLI flags that result in substantially
different code paths. As well as the default runner, there is:

* `--init` - initializes the project directory and exits
* `--help` - prints CLI usage and exits
* `--version` - prints the version and exits
* `--drb` - runs examples via a DRb connection
* `--bisect` - starts a bisection process

Previously some of these paths were invoked directly in the OptionParser
(--init, --help and --version), while others were invoked by the main
Runner.run call. This necessitated a lot of complexity in Runner.run, and a
reasonable amount of stubbing of exit calls (which can be error-prone, and
lead to a prematurely-terminated test run).

This commit refactors the different invocations into callables, which the
OptionParser sets as the `:runner` option. If an alternative invocation is
found in Runner.run, it is used, falling back to the default of instantiating
a Runner and starting it.

The invocation callables do not handle exiting themselves, but are required to
return an exit code instead. They must all accept the following arguments:

    @param options [RSpec::Core::ConfigurationOptions]
    @param err [IO]
    @param out [IO]

At the moment the invocations are tested via the OptionParser specs - in
future work we intend to extract these to their own module and test them
independently.

Author: urbanautomaton

lib/rspec/core/configuration_options.rb

@@ -35,6 +35,9 @@ def configure_filter_manager(filter_manager)
       # @return [Hash] the final merged options, drawn from all external sources
       attr_reader :options
 
+      # @return [Array<String>] the original command-line arguments
+      attr_reader :args
+
     private
 
       def organize_options

lib/rspec/core/option_parser.rb

@@ -69,6 +69,7 @@ def parser(options)
         parser.on('--bisect[=verbose]', 'Repeatedly runs the suite in order to isolate the failures to the ',
                   '  smallest reproducible case.') do |argument|
           options[:bisect] = argument || true
+          options[:runner] = Callables.bisect
         end
 
         parser.on('--[no-]fail-fast[=COUNT]', 'Abort the run after a certain number of failures (1 by default).') do |argument|
@@ -96,16 +97,17 @@ def parser(options)
           options[:dry_run] = true
         end
 
-        parser.on('-X', '--[no-]drb', 'Run examples via DRb.') do |o|
-          options[:drb] = o
+        parser.on('-X', '--[no-]drb', 'Run examples via DRb.') do |use_drb|
+          options[:drb] = use_drb
+          options[:runner] = Callables.drb_with_fallback if use_drb
         end
 
         parser.on('--drb-port PORT', 'Port to connect to the DRb server.') do |o|
           options[:drb_port] = o.to_i
         end
 
         parser.on('--init', 'Initialize your project with RSpec.') do |_cmd|
-          initialize_project_and_exit
+          options[:runner] = Callables.initialize_project
         end
 
         parser.separator("\n  **** Output ****\n\n")
@@ -242,7 +244,7 @@ def parser(options)
         parser.separator("\n  **** Utility ****\n\n")
 
         parser.on('-v', '--version', 'Display the version.') do
-          print_version_and_exit
+          options[:runner] = Callables.print_version
         end
 
         # These options would otherwise be confusing to users, so we forcibly
@@ -254,7 +256,7 @@ def parser(options)
         invalid_options = %w[-d --I]
 
         parser.on_tail('-h', '--help', "You're looking at it.") do
-          print_help_and_exit(parser, invalid_options)
+          options[:runner] = Callables.print_help(parser, invalid_options)
         end
 
         # This prevents usage of the invalid_options.
@@ -282,21 +284,61 @@ def configure_only_failures(options)
       add_tag_filter(options, :inclusion_filter, :last_run_status, 'failed')
     end
 
-    def initialize_project_and_exit
-      RSpec::Support.require_rspec_core "project_initializer"
-      ProjectInitializer.new.run
-      exit
-    end
+    # @private
+    module Callables
+      def self.initialize_project
+        lambda do |*_args|
+          RSpec::Support.require_rspec_core "project_initializer"
+          ProjectInitializer.new.run
+          0
+        end
+      end
 
-    def print_version_and_exit
-      puts RSpec::Core::Version::STRING
-      exit
-    end
+      def self.drb_with_fallback
+        lambda do |options, err, out|
+          require 'rspec/core/drb'
+          begin
+            return DRbRunner.new(options).run(err, out)
+          rescue DRb::DRbConnError
+            err.puts "No DRb server is running. Running in local process instead ..."
+          end
+          RSpec::Core::Runner.new(options).run(err, out)
+        end
+      end
+
+      def self.bisect
+        lambda do |options, _err, _out|
+          RSpec::Support.require_rspec_core "bisect/coordinator"
 
-    def print_help_and_exit(parser, invalid_options)
-      # Removing the blank invalid options from the output.
-      puts parser.to_s.gsub(/^\s+(#{invalid_options.join('|')})\s*$\n/, '')
-      exit
+          success = Bisect::Coordinator.bisect_with(
+            options.args,
+            RSpec.configuration,
+            bisect_formatter_for(options.options[:bisect])
+          )
+
+          success ? 0 : 1
+        end
+      end
+
+      def self.print_version
+        lambda do |*_args|
+          puts RSpec::Core::Version::STRING
+          0
+        end
+      end
+
+      def self.print_help(parser, invalid_options)
+        lambda do |*_args|
+          # Removing the blank invalid options from the output.
+          puts parser.to_s.gsub(/^\s+(#{invalid_options.join('|')})\s*$\n/, '')
+          0
+        end
+      end
+
+      def self.bisect_formatter_for(argument)
+        return Formatters::BisectDebugFormatter if argument == "verbose"
+        Formatters::BisectProgressFormatter
+      end
     end
   end
 end

lib/rspec/core/runner.rb

@@ -65,32 +65,11 @@ def self.run(args, err=$stderr, out=$stdout)
         trap_interrupt
         options = ConfigurationOptions.new(args)
 
-        if options.options[:drb]
-          require 'rspec/core/drb'
-          begin
-            DRbRunner.new(options).run(err, out)
-            return
-          rescue DRb::DRbConnError
-            err.puts "No DRb server is running. Running in local process instead ..."
-          end
-        elsif options.options[:bisect]
-          RSpec::Support.require_rspec_core "bisect/coordinator"
-
-          success = Bisect::Coordinator.bisect_with(
-            args,
-            RSpec.configuration,
-            bisect_formatter_for(options.options[:bisect])
-          )
-
-          return success ? 0 : 1
+        if options.options[:runner]
+          options.options[:runner].call(options, err, out)
+        else
+          new(options).run(err, out)
         end
-
-        new(options).run(err, out)
-      end
-
-      def self.bisect_formatter_for(argument)
-        return Formatters::BisectDebugFormatter if argument == "verbose"
-        Formatters::BisectProgressFormatter
       end
 
       def initialize(options, configuration=RSpec.configuration, world=RSpec.world)

spec/rspec/core/option_parser_spec.rb

@@ -1,3 +1,5 @@
+require 'rspec/core/drb'
+require 'rspec/core/bisect/coordinator'
 require 'rspec/core/project_initializer'
 
 module RSpec::Core
@@ -70,8 +72,8 @@ module RSpec::Core
     it "won't display invalid options in the help output" do
       def generate_help_text
         parser = Parser.new(["--help"])
-        allow(parser).to receive(:exit)
-        parser.parse
+        options = parser.parse
+        options[:runner].call
       end
 
       useless_lines = /^\s*--?\w+\s*$\n/
@@ -81,28 +83,101 @@ def generate_help_text
 
     %w[ -v --version ].each do |option|
       describe option do
-        it "prints the version and exits" do
+        it "prints the version and returns a zero exit code" do
           parser = Parser.new([option])
-          expect(parser).to receive(:exit)
 
           expect {
-            parser.parse
+            options = parser.parse
+            exit_code = options[:runner].call
+            expect(exit_code).to eq(0)
           }.to output("#{RSpec::Core::Version::STRING}\n").to_stdout
         end
       end
     end
 
+    %w[ -X --drb ].each do |option|
+      describe option do
+        let(:parser) { Parser.new([option]) }
+        let(:configuration_options) { double(:configuration_options) }
+        let(:err) { StringIO.new }
+        let(:out) { StringIO.new }
+
+        it 'sets the `:drb` option to true' do
+          options = parser.parse
+
+          expect(options[:drb]).to be_truthy
+        end
+
+        context 'when a DRb server is running' do
+          it "builds a DRbRunner and runs the specs" do
+            drb_proxy = instance_double(RSpec::Core::DRbRunner, :run => 0)
+            allow(RSpec::Core::DRbRunner).to receive(:new).and_return(drb_proxy)
+
+            options = parser.parse
+            exit_code = options[:runner].call(configuration_options, err, out)
+
+            expect(drb_proxy).to have_received(:run).with(err, out)
+            expect(exit_code).to eq(0)
+          end
+        end
+
+        context 'when a DRb server is not running' do
+          let(:runner) { instance_double(RSpec::Core::Runner, :run => 0) }
+
+          before(:each) do
+            allow(RSpec::Core::Runner).to receive(:new).and_return(runner)
+            allow(RSpec::Core::DRbRunner).to receive(:new).and_raise(DRb::DRbConnError)
+          end
+
+          it "outputs a message" do
+            options = parser.parse
+            options[:runner].call(configuration_options, err, out)
+
+            expect(err.string).to include(
+              "No DRb server is running. Running in local process instead ..."
+            )
+          end
+
+          it "builds a runner instance and runs the specs" do
+            options = parser.parse
+            options[:runner].call(configuration_options, err, out)
+
+            expect(RSpec::Core::Runner).to have_received(:new).with(configuration_options)
+            expect(runner).to have_received(:run).with(err, out)
+          end
+
+          if RSpec::Support::RubyFeatures.supports_exception_cause?
+            it "prevents the DRb error from being listed as the cause of expectation failures" do
+              allow(RSpec::Core::Runner).to receive(:new) do |configuration_options|
+                raise RSpec::Expectations::ExpectationNotMetError
+              end
+
+              expect {
+                options = parser.parse
+                options[:runner].call(configuration_options, err, out)
+
+              }.to raise_error(RSpec::Expectations::ExpectationNotMetError) do |e|
+                expect(e.cause).to be_nil
+              end
+            end
+          end
+        end
+      end
+    end
+
     describe "--init" do
-      it "initializes a project and exits" do
+      it "initializes a project and returns a 0 exit code" do
         project_init = instance_double(ProjectInitializer)
         allow(ProjectInitializer).to receive_messages(:new => project_init)
 
         parser = Parser.new(["--init"])
 
         expect(project_init).to receive(:run).ordered
-        expect(parser).to receive(:exit).ordered
 
-        parser.parse
+        options = parser.parse
+        exit_code = options[:runner].call
+
+        expect(exit_code).to eq(0)
       end
     end
 
@@ -317,6 +392,88 @@ def generate_help_text
       end
     end
 
+    describe "--bisect" do
+      it "sets the `:bisect` option" do
+        options = Parser.parse(%w[ --bisect ])
+
+        expect(options[:bisect]).to be_truthy
+      end
+
+      it "sets a the `:runner` option with a callable" do
+        options = Parser.parse(%w[ --bisect ])
+
+        expect(options[:runner]).to respond_to(:call)
+      end
+
+      context "when the verbose option is specified" do
+        it "records this in the options" do
+          options = Parser.parse(%w[ --bisect=verbose ])
+
+          expect(options[:bisect]).to eq("verbose")
+        end
+      end
+
+      context 'when the runner is called' do
+        let(:args) { double(:args) }
+        let(:err) { double(:stderr) }
+        let(:out) { double(:stdout) }
+        let(:success) { true }
+        let(:configuration_options) { double(:options, :args => args) }
+
+        before do
+          allow(RSpec::Core::Bisect::Coordinator).to receive(:bisect_with).and_return(success)
+        end
+
+        it "starts the bisection coordinator" do
+          options = Parser.parse(%w[ --bisect ])
+          allow(configuration_options).to receive(:options).and_return(options)
+          options[:runner].call(configuration_options, err, out)
+
+          expect(RSpec::Core::Bisect::Coordinator).to have_received(:bisect_with).with(
+            args,
+            RSpec.configuration,
+            Formatters::BisectProgressFormatter
+          )
+        end
+
+        context "when the bisection is successful" do
+          it "returns 0" do
+            options = Parser.parse(%w[ --bisect ])
+            allow(configuration_options).to receive(:options).and_return(options)
+            exit_code = options[:runner].call(configuration_options, err, out)
+
+            expect(exit_code).to eq(0)
+          end
+        end
+
+        context "when the bisection is unsuccessful" do
+          let(:success) { false }
+
+          it "returns 1" do
+            options = Parser.parse(%w[ --bisect ])
+            allow(configuration_options).to receive(:options).and_return(options)
+            exit_code = options[:runner].call(configuration_options, err, out)
+
+            expect(exit_code).to eq(1)
+          end
+        end
+
+        context "and the verbose option is specified" do
+          it "starts the bisection coordinator with the debug formatter" do
+            options = Parser.parse(%w[ --bisect=verbose ])
+            allow(configuration_options).to receive(:options).and_return(options)
+            options[:runner].call(configuration_options, err, out)
+
+            expect(RSpec::Core::Bisect::Coordinator).to have_received(:bisect_with).with(
+              args,
+              RSpec.configuration,
+              Formatters::BisectDebugFormatter
+            )
+          end
+        end
+      end
+    end
+
     describe '--profile' do
       it 'sets profile_examples to true by default' do
         options = Parser.parse(%w[--profile])