123456789_123456789_123456789_123456789_123456789_

Class: RSpec::Core::Runner

Relationships & Source Files
Inherits: Object
Defined in: rspec-core/lib/rspec/core/runner.rb

Overview

Provides the main entry point to run a suite of ::RSpec examples.

Class Attribute Summary

Class Method Summary

Instance Attribute Summary

  • #configuration readonly Internal use only Internal use only
  • #options readonly Internal use only Internal use only
  • #world readonly Internal use only Internal use only

Instance Method Summary

Constructor Details

.new(options, configuration = RSpec.configuration, world = RSpec.world) ⇒ Runner

[ GitHub ] 

  


# File 'rspec-core/lib/rspec/core/runner.rb', line 75



def initialize(options, configuration=RSpec.configuration, world=RSpec.world)
  @options       = options
  @configuration = configuration
  @world         = world
end


  







Class Attribute Details



  

    .autorun_disabled?  ⇒ Boolean  (readonly)
  

  

    This method is for internal use only.
  



  

    
  





  


  [ GitHub ]


  

  


# File 'rspec-core/lib/rspec/core/runner.rb', line 141



def self.autorun_disabled?
  @autorun_disabled ||= false
end


  








  

    .installed_at_exit?  ⇒ Boolean  (readonly)
  

  

    This method is for internal use only.
  



  

    
  





  


  [ GitHub ]


  

  


# File 'rspec-core/lib/rspec/core/runner.rb', line 146



def self.installed_at_exit?
  @installed_at_exit ||= false
end


  








  

    .running_in_drb?  ⇒ Boolean  (readonly)
  

  

    This method is for internal use only.
  



  

    
  





  


  [ GitHub ]


  

  


# File 'rspec-core/lib/rspec/core/runner.rb', line 151



def self.running_in_drb?
  return false unless defined?(DRb)

  server = begin
             DRb.current_server
           rescue DRb::DRbServerNotFound
             return false
           end

  return false unless server && server.alive?

  require 'socket'
  require 'uri'

  local_ipv4 = begin
                 IPSocket.getaddress(Socket.gethostname)
               rescue SocketError
                 return false
               end

  ["127.0.0.1", "localhost", local_ipv4].any? { |addr| addr == URI(DRb.current_server.uri).host }
end


  







Class Method Details



  

    .autorun  
  



  

    
  

    Note:
    


This is not generally needed. The rspec command takes care of running examples for you without involving an at_exit hook. This is only needed if you are running specs using the ruby command, and even then, the normal way to invoke this is by requiring rspec/autorun.



  




Register an at_exit hook that runs the suite when the process exits.


  



  [ GitHub ]


  

  


# File 'rspec-core/lib/rspec/core/runner.rb', line 16



def self.autorun
  if autorun_disabled?
    RSpec.deprecate("Requiring `rspec/autorun` when running RSpec via the `rspec` command")
    return
  elsif installed_at_exit? || running_in_drb?
    return
  end

  at_exit { perform_at_exit }
  @installed_at_exit = true
end


  








  

    .disable_autorun!  
  

  

    This method is for internal use only.
  

  [ GitHub ]


  

  


# File 'rspec-core/lib/rspec/core/runner.rb', line 136



def self.disable_autorun!
  @autorun_disabled = true
end


  








  

    .handle_interrupt  
  

  

    This method is for internal use only.
  

  [ GitHub ]


  

  


# File 'rspec-core/lib/rspec/core/runner.rb', line 180



def self.handle_interrupt
  if RSpec.world.wants_to_quit
    exit!(1)
  else
    RSpec.world.wants_to_quit = true

    $stderr.puts(
      "\nRSpec is shutting down and will print the summary report... Interrupt again to force quit " \
      "(warning: at_exit hooks will be skipped if you force quit)."
    )
  end
end


  








  

    .invoke  
  



  

    

Runs the suite of specs and exits the process with an appropriate exit code.


  



  [ GitHub ]


  

  


# File 'rspec-core/lib/rspec/core/runner.rb', line 43



def self.invoke
  disable_autorun!
  status = run(ARGV, $stderr, $stdout).to_i
  exit(status) if status != 0
end


  








  

    .perform_at_exit  
  

  

    This method is for internal use only.
  

  [ GitHub ]


  

  


# File 'rspec-core/lib/rspec/core/runner.rb', line 29



def self.perform_at_exit
  # Don't bother running any specs and just let the program terminate
  # if we got here due to an unrescued exception (anything other than
  # SystemExit, which is raised when somebody calls Kernel#exit).
  return unless $!.nil? || $!.is_a?(SystemExit)

  # We got here because either the end of the program was reached or
  # somebody called Kernel#exit. Run the specs and then override any
  # existing exit status with RSpec's exit status if any specs failed.
  invoke
end


  








  

    .run(args, err = $stderr, out = $stdout)  ⇒ Fixnum 
  



  

    

Run a suite of ::RSpec examples. Does not exit.



This is used internally by ::RSpec to run a suite, but is available for use by any other automation tool.



If you want to run this multiple times in the same process, and you want files like spec_helper.rb to be reloaded, be sure to load load instead of require.


  





  
Parameters:


    
  
  • 
    args
    (Array)
—    
    

    command-line-supported arguments
    

    
  
    • 
  
  • 
    err
    (IO)
    (defaults to: $stderr)
—    
    

    error stream
    

    
  
    • 
  
  • 
    out
    (IO)
    (defaults to: $stdout)
—    
    

    output stream
    

    
  
    • 



Returns:


    
  
  • 
    (Fixnum)
—    
    

    exit status code. 0 if all specs passed, or the configured failure exit code (1 by default) if specs failed.
    

    
  
    • 





  [ GitHub ]


  

  


# File 'rspec-core/lib/rspec/core/runner.rb', line 64



def self.run(args, err=$stderr, out=$stdout)
  trap_interrupt
  options = ConfigurationOptions.new(args)

  if options.options[:runner]
    options.options[:runner].call(options, err, out)
  else
    new(options).run(err, out)
  end
end


  








  

    .trap_interrupt  
  

  

    This method is for internal use only.
  

  [ GitHub ]


  

  


# File 'rspec-core/lib/rspec/core/runner.rb', line 175



def self.trap_interrupt
  trap('INT') { handle_interrupt }
end


  







Instance Attribute Details



  

    #configuration   (readonly)
  

  

    This method is for internal use only.
  

  [ GitHub ]


  

  


# File 'rspec-core/lib/rspec/core/runner.rb', line 7



attr_reader :options, :configuration, :world


  








  

    #options   (readonly)
  

  

    This method is for internal use only.
  

  [ GitHub ]


  

  


# File 'rspec-core/lib/rspec/core/runner.rb', line 7



attr_reader :options, :configuration, :world


  








  

    #world   (readonly)
  

  

    This method is for internal use only.
  

  [ GitHub ]


  

  


# File 'rspec-core/lib/rspec/core/runner.rb', line 7



attr_reader :options, :configuration, :world


  







Instance Method Details



  

    #configure(err, out)  
  

  

    This method is for internal use only.
  

  [ GitHub ]


  

  


# File 'rspec-core/lib/rspec/core/runner.rb', line 129



def configure(err, out)
  @configuration.error_stream = err
  @configuration.output_stream = out if @configuration.output_stream == $stdout
  @options.configure(@configuration)
end


  








  

    #exit_code(examples_passed = false)  
  

  

    This method is for internal use only.
  

  [ GitHub ]


  

  


# File 'rspec-core/lib/rspec/core/runner.rb', line 194



def exit_code(examples_passed=false)
  return @configuration.error_exit_code || @configuration.failure_exit_code if @world.non_example_failure
  return @configuration.failure_exit_code unless examples_passed

  0
end


  








  

    #persist_example_statuses   (private)
  

  [ GitHub ]


  

  


# File 'rspec-core/lib/rspec/core/runner.rb', line 203



def persist_example_statuses
  return if @configuration.dry_run
  return unless (path = @configuration.example_status_persistence_file_path)

  ExampleStatusPersister.persist(@world.all_examples, path)
rescue SystemCallError => e
  RSpec.warning "Could not write example statuses to #{path} (configured as " \
                "`config.example_status_persistence_file_path`) due to a " \
                "system error: #{e.inspect}. Please check that the config " \
                "option is set to an accessible, valid file path", :call_site => nil
end


  








  

    #run(err, out)  
  



  

    

Configures and runs a spec suite.


  





  
Parameters:


    
  
  • 
    err
    (IO)
—    
    

    error stream
    

    
  
    • 
  
  • 
    out
    (IO)
—    
    

    output stream
    

    
  
    • 





  [ GitHub ]


  

  


# File 'rspec-core/lib/rspec/core/runner.rb', line 85



def run(err, out)
  setup(err, out)
  return @configuration.reporter.exit_early(exit_code) if RSpec.world.wants_to_quit

  run_specs(@world.ordered_example_groups).tap do
    persist_example_statuses
  end
end


  








  

    #run_specs(example_groups)  ⇒ Fixnum 
  



  

    

Runs the provided example groups.


  





  
Parameters:



Returns:


    
  
  • 
    (Fixnum)
—    
    

    exit status code. 0 if all specs passed, or the configured failure exit code (1 by default) if specs failed.
    

    
  
    • 





  [ GitHub ]


  

  


# File 'rspec-core/lib/rspec/core/runner.rb', line 113



def run_specs(example_groups)
  examples_count = @world.example_count(example_groups)
  examples_passed = @configuration.reporter.report(examples_count) do |reporter|
    @configuration.with_suite_hooks do
      if examples_count == 0 && @configuration.fail_if_no_examples
        return @configuration.failure_exit_code
      end

      example_groups.map { |g| g.run(reporter) }.all?
    end
  end

  exit_code(examples_passed)
end


  








  

    #setup(err, out)  
  



  

    

Wires together the various configuration objects and state holders.


  





  
Parameters:


    
  
  • 
    err
    (IO)
—    
    

    error stream
    

    
  
    • 
  
  • 
    out
    (IO)
—    
    

    output stream
    

    
  
    • 





  [ GitHub ]


  

  


# File 'rspec-core/lib/rspec/core/runner.rb', line 98



def setup(err, out)
  configure(err, out)
  return if RSpec.world.wants_to_quit

  @configuration.load_spec_files
ensure
  @world.announce_filters
end