rspec-core 2.99.0 → 3.0.0

data/lib/rspec/core/runner.rb

@@ -1,10 +1,23 @@
 module RSpec
   module Core
+    # Provides the main entry point to run a suite of RSpec examples.
     class Runner
 
-      # Register an at_exit hook that runs the suite.
+      # Register an `at_exit` hook that runs the suite when the process exits.
+      #
+      # @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`.
       def self.autorun
-        return if autorun_disabled? || installed_at_exit? || running_in_drb?
+        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 do
           # Don't bother running any specs and just let the program terminate
           # if we got here due to an unrescued exception (anything other than
@@ -14,73 +27,41 @@ module RSpec
           # 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.
-          status = run(ARGV, $stderr, $stdout).to_i
-          exit status if status != 0
+          invoke
         end
         @installed_at_exit = true
       end
-      AT_EXIT_HOOK_BACKTRACE_LINE = "#{__FILE__}:#{__LINE__ - 2}:in `autorun'"
 
-      def self.disable_autorun!
-        @autorun_disabled = true
-      end
-
-      def self.autorun_disabled?
-        @autorun_disabled ||= false
+      # Runs the suite of specs and exits the process with an appropriate exit code.
+      def self.invoke
+        disable_autorun!
+        status = run(ARGV, $stderr, $stdout).to_i
+        exit(status) if status != 0
       end
 
-      def self.installed_at_exit?
-        @installed_at_exit ||= false
-      end
-
-      def self.running_in_drb?
-        defined?(DRb) &&
-        (DRb.current_server rescue false) &&
-         DRb.current_server.uri =~ /druby\:\/\/127.0.0.1\:/
-      end
-
-      def self.trap_interrupt
-        trap('INT') do
-          exit!(1) if RSpec.wants_to_quit
-          RSpec.wants_to_quit = true
-          STDERR.puts "\nExiting... Interrupt again to exit immediately."
-        end
-      end
-
-      # Run a suite of RSpec examples.
+      # 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`
+      # want files like `spec_helper.rb` to be reloaded, be sure to load `load`
       # instead of `require`.
       #
-      # #### Parameters
-      # * +args+ - an array of command-line-supported arguments
-      # * +err+ - error stream (Default: $stderr)
-      # * +out+ - output stream (Default: $stdout)
-      #
-      # #### Returns
-      # * +Fixnum+ - exit status code (0/1)
+      # @param args [Array] command-line-supported arguments
+      # @param err [IO] error stream
+      # @param out [IO] output stream
+      # @return [Fixnum] exit status code. 0 if all specs passed,
+      #   or the configured failure exit code (1 by default) if specs
+      #   failed.
       def self.run(args, err=$stderr, out=$stdout)
         trap_interrupt
         options = ConfigurationOptions.new(args)
-        options.parse_options
-
-        major, minor, point = RUBY_VERSION.split('.').map { |v| v.to_i }
-
-        if major == 1 && ( (minor == 9 && point < 2) || (minor == 8 && point < 7) )
-          RSpec.deprecate "RSpec support for Ruby #{RUBY_VERSION}",
-                          :replacement => "1.8.7 or >= 1.9.2",
-                          :call_site   => nil
-        end
-
 
         if options.options[:drb]
-          require 'rspec/core/drb_command_line'
+          require 'rspec/core/drb'
           begin
-            DRbCommandLine.new(options).run(err, out)
+            DRbRunner.new(options).run(err, out)
           rescue DRb::DRbConnError
             err.puts "No DRb server is running. Running in local process instead ..."
             new(options).run(err, out)
@@ -88,8 +69,92 @@ module RSpec
         else
           new(options).run(err, out)
         end
-      ensure
-        RSpec.reset
+      end
+
+      def initialize(options, configuration=RSpec.configuration, world=RSpec.world)
+        @options       = options
+        @configuration = configuration
+        @world         = world
+      end
+
+      # Configures and runs a spec suite.
+      #
+      # @param err [IO] error stream
+      # @param out [IO] output stream
+      def run(err, out)
+        setup(err, out)
+        run_specs(@world.ordered_example_groups)
+      end
+
+      # Wires together the various configuration objects and state holders.
+      #
+      # @param err [IO] error stream
+      # @param out [IO] output stream
+      def setup(err, out)
+        @configuration.error_stream = err
+        @configuration.output_stream = out if @configuration.output_stream == $stdout
+        @options.configure(@configuration)
+        @configuration.load_spec_files
+        @world.announce_filters
+      end
+
+      # Runs the provided example groups.
+      #
+      # @param example_groups [Array<RSpec::Core::ExampleGroup>] groups to run
+      # @return [Fixnum] exit status code. 0 if all specs passed,
+      #   or the configured failure exit code (1 by default) if specs
+      #   failed.
+      def run_specs(example_groups)
+        @configuration.reporter.report(@world.example_count(example_groups)) do |reporter|
+          begin
+            hook_context = SuiteHookContext.new
+            @configuration.hooks.run(:before, :suite, hook_context)
+            example_groups.map { |g| g.run(reporter) }.all? ? 0 : @configuration.failure_exit_code
+          ensure
+            @configuration.hooks.run(:after, :suite, hook_context)
+          end
+        end
+      end
+
+      # @private
+      def self.disable_autorun!
+        @autorun_disabled = true
+      end
+
+      # @private
+      def self.autorun_disabled?
+        @autorun_disabled ||= false
+      end
+
+      # @private
+      def self.installed_at_exit?
+        @installed_at_exit ||= false
+      end
+
+      # @private
+      def self.running_in_drb?
+        begin
+          if defined?(DRb) && DRb.current_server
+            require 'socket'
+            require 'uri'
+
+            local_ipv4 = IPSocket.getaddress(Socket.gethostname)
+
+            local_drb = ["127.0.0.1", "localhost", local_ipv4].any? { |addr| addr == URI(DRb.current_server.uri).host }
+          end
+        rescue DRb::DRbServerNotFound
+        ensure
+          return local_drb || false
+        end
+      end
+
+      # @private
+      def self.trap_interrupt
+        trap('INT') do
+          exit!(1) if RSpec.world.wants_to_quit
+          RSpec.world.wants_to_quit = true
+          STDERR.puts "\nExiting... Interrupt again to exit immediately."
+        end
       end
     end
   end

data/lib/rspec/core/shared_context.rb

@@ -7,7 +7,7 @@ module RSpec
     #
     #     module LoggedInAsAdmin
     #       extend RSpec::Core::SharedContext
-    #       before(:each) do
+    #       before(:example) do
     #         log_in_as :admin
     #       end
     #     end
@@ -17,39 +17,39 @@ module RSpec
     #       # ...
     #     end
     module SharedContext
-      # @api private
+      # @private
       def included(group)
         __shared_context_recordings.each do |recording|
           recording.playback_onto(group)
         end
       end
 
-      # @api private
+      # @private
       def __shared_context_recordings
         @__shared_context_recordings ||= []
       end
 
+      # @private
       Recording = Struct.new(:method_name, :args, :block) do
         def playback_onto(group)
           group.__send__(method_name, *args, &block)
         end
       end
 
-      # @api private
+      # @private
       def self.record(methods)
         methods.each do |meth|
-          class_eval <<-EOS, __FILE__, __LINE__ + 1
-            def #{meth}(*args, &block)
-              __shared_context_recordings << Recording.new(:#{meth}, args, block)
-            end
-          EOS
+          define_method(meth) do |*args, &block|
+            __shared_context_recordings << Recording.new(meth, args, block)
+          end
         end
       end
 
+      # @private
       record [:describe, :context] + Hooks.instance_methods(false) +
         MemoizedHelpers::ClassMethods.instance_methods(false)
     end
   end
-
+  # @private
   SharedContext = Core::SharedContext
 end

data/lib/rspec/core/shared_example_group.rb

@@ -1,163 +1,158 @@
 module RSpec
   module Core
+    # Shared example groups let you define common context and/or common
+    # examples that you wish to use in multiple example groups.
+    #
+    # When defined, the shared group block is stored for later evaluation.
+    # It can later be included in an example group either explicitly
+    # (using `include_examples`, `include_context` or `it_behaves_like`)
+    # or implicitly (via matching metadata).
+    #
+    # Named shared example groups are scoped based on where they are
+    # defined. Shared groups defined in an example group are available
+    # for inclusion in that example group or any child example groups,
+    # but not in any parent or sibling example groups. Shared example
+    # groups defined at the top level can be included from any example group.
     module SharedExampleGroup
       # @overload shared_examples(name, &block)
-      # @overload shared_examples(name, tags, &block)
+      #   @param name [String, Symbol, Module] identifer to use when looking up this shared group
+      #   @param block The block to be eval'd
+      # @overload shared_examples(name, metadata, &block)
+      #   @param name [String, Symbol, Module] identifer to use when looking up this shared group
+      #   @param metadata [Array<Symbol>, Hash] metadata to attach to this group; any example group
+      #     with matching metadata will automatically include this shared example group.
+      #   @param block The block to be eval'd
+      # @overload shared_examples(metadata, &block)
+      #   @param metadata [Array<Symbol>, Hash] metadata to attach to this group; any example group
+      #     with matching metadata will automatically include this shared example group.
+      #   @param block The block to be eval'd
       #
-      # Wraps the `block` in a module which can then be included in example
-      # groups using `include_examples`, `include_context`, or
-      # `it_behaves_like`.
-      #
-      # @param [String] name to match when looking up this shared group
-      # @param block to be eval'd in a nested example group generated by `it_behaves_like`
+      # Stores the block for later use. The block will be evaluated
+      # in the context of an example group via `include_examples`,
+      # `include_context`, or `it_behaves_like`.
       #
       # @example
-      #
       #   shared_examples "auditable" do
       #     it "stores an audit record on save!" do
-      #       lambda { auditable.save! }.should change(Audit, :count).by(1)
+      #       expect { auditable.save! }.to change(Audit, :count).by(1)
       #     end
       #   end
       #
-      #   class Account do
+      #   describe Account do
       #     it_behaves_like "auditable" do
-      #       def auditable; Account.new; end
+      #       let(:auditable) { Account.new }
       #     end
       #   end
       #
       # @see ExampleGroup.it_behaves_like
       # @see ExampleGroup.include_examples
       # @see ExampleGroup.include_context
-      def shared_examples(*args, &block)
-        SharedExampleGroup.registry.add_group(self, *args, &block)
-      end
-
-      alias_method :shared_context,      :shared_examples
-      alias_method :shared_examples_for, :shared_examples
-
-      def share_examples_for(*args, &block)
-        RSpec.deprecate("`share_examples_for`", :replacement => "`shared_examples` or `shared_examples_for`")
-        shared_examples(*args, &block)
-      end
-
-      # @deprecated
-      def share_as(name, &block)
-        RSpec.deprecate("Rspec::Core::SharedExampleGroup#share_as",
-                        :replacement => "RSpec::SharedContext or shared_examples")
-        SharedExampleGroup.registry.add_const(self, name, &block)
-      end
+      def shared_examples(name, *args, &block)
+        top_level = self == ExampleGroup
+        if top_level && RSpec.thread_local_metadata[:in_example_group]
+          raise "Creating isolated shared examples from within a context is " +
+                "not allowed. Remove `RSpec.` prefix or move this to a " +
+                "top-level scope."
+        end
 
-      def shared_example_groups
-        SharedExampleGroup.registry.shared_example_groups_for('main', *ancestors[0..-1])
+        RSpec.world.shared_example_group_registry.add(self, name, *args, &block)
       end
+      alias shared_context      shared_examples
+      alias shared_examples_for shared_examples
 
+      # @api private
+      #
+      # Shared examples top level DSL
       module TopLevelDSL
-        def shared_examples(*args, &block)
-          SharedExampleGroup.registry.add_group('main', *args, &block)
+        # @private
+        def self.definitions
+          proc do
+            def shared_examples(name, *args, &block)
+              RSpec.world.shared_example_group_registry.add(:main, name, *args, &block)
+            end
+            alias shared_context      shared_examples
+            alias shared_examples_for shared_examples
+          end
         end
 
-        alias_method :shared_context,      :shared_examples
-        alias_method :shared_examples_for, :shared_examples
-
-        def share_examples_for(*args, &block)
-          RSpec.deprecate("`share_examples_for`", :replacement => "`shared_examples` or `shared_examples_for`")
-          shared_examples(*args, &block)
+        # @private
+        def self.exposed_globally?
+          @exposed_globally ||= false
         end
 
-        def share_as(name, &block)
-          RSpec.deprecate("`share_as`", :replacement => "`RSpec::SharedContext` or `shared_examples`")
-          SharedExampleGroup.registry.add_const('main', name, &block)
+        # @api private
+        #
+        # Adds the top level DSL methods to Module and the top level binding
+        def self.expose_globally!
+          return if exposed_globally?
+          Core::DSL.change_global_dsl(&definitions)
+          @exposed_globally = true
         end
 
-        def shared_example_groups
-          SharedExampleGroup.registry.shared_example_groups_for('main')
+        # @api private
+        #
+        # Removes the top level DSL methods to Module and the top level binding
+        def self.remove_globally!
+          return unless exposed_globally?
+
+          Core::DSL.change_global_dsl do
+            undef shared_examples
+            undef shared_context
+            undef shared_examples_for
+          end
+
+          @exposed_globally = false
         end
-      end
 
-      def self.registry
-        @registry ||= Registry.new
       end
 
       # @private
-      #
-      # Used internally to manage the shared example groups and
-      # constants. We want to limit the number of methods we add
-      # to objects we don't own (main and Module) so this allows
-      # us to have helper methods that don't get added to those
-      # objects.
       class Registry
-        def add_group(source, *args, &block)
-          ensure_block_has_source_location(block, CallerFilter.first_non_rspec_line)
-
-          if key? args.first
-            key = args.shift
-            warn_if_key_taken source, key, block
-            add_shared_example_group source, key, block
+        def add(context, name, *metadata_args, &block)
+          ensure_block_has_source_location(block) { CallerFilter.first_non_rspec_line }
+
+          if valid_name?(name)
+            warn_if_key_taken context, name, block
+            shared_example_groups[context][name] = block
+          else
+            metadata_args.unshift name
           end
 
-          unless args.empty?
+          unless metadata_args.empty?
             mod = Module.new
-            (class << mod; self; end).send :define_method, :extended  do |host|
-              host.class_eval(&block)
+            (class << mod; self; end).__send__(:define_method, :included) do |host|
+              host.class_exec(&block)
             end
-            RSpec.configuration.extend mod, *args
+            RSpec.configuration.include mod, *metadata_args
           end
         end
 
-        def add_const(source, name, &block)
-          if Object.const_defined?(name)
-            mod = Object.const_get(name)
-            raise_name_error unless mod.created_from_caller(caller)
+        def find(lookup_contexts, name)
+          lookup_contexts.each do |context|
+            found = shared_example_groups[context][name]
+            return found if found
           end
 
-          mod = Module.new do
-            @shared_block = block
-            @caller_line = caller.last
-
-            def self.created_from_caller(other_caller)
-              @caller_line == other_caller.last
-            end
-
-            def self.included(kls)
-              kls.describe(&@shared_block)
-              kls.children.first.metadata[:shared_group_name] = name
-            end
-          end
-
-          shared_const = Object.const_set(name, mod)
-          add_shared_example_group source, shared_const, block
-        end
-
-        def shared_example_groups_for(*sources)
-          Collection.new(sources, shared_example_groups)
-        end
-
-        def shared_example_groups
-          @shared_example_groups ||= Hash.new { |hash,key| hash[key] = Hash.new }
-        end
-
-        def clear
-          shared_example_groups.clear
+          shared_example_groups[:main][name]
         end
 
       private
 
-        def add_shared_example_group(source, key, block)
-          shared_example_groups[source][key] = block
-        end
-
-        def key?(candidate)
-          [String, Symbol, Module].any? { |cls| cls === candidate }
+        def shared_example_groups
+          @shared_example_groups ||= Hash.new { |hash, context| hash[context] = {} }
         end
 
-        def raise_name_error
-          raise NameError, "The first argument (#{name}) to share_as must be a legal name for a constant not already in use."
+        def valid_name?(candidate)
+          case candidate
+            when String, Symbol, Module then true
+            else false
+          end
         end
 
-        def warn_if_key_taken(source, key, new_block)
-          return unless existing_block = example_block_for(source, key)
+        def warn_if_key_taken(context, key, new_block)
+          return unless existing_block = shared_example_groups[context][key]
 
-          Kernel.warn <<-WARNING.gsub(/^ +\|/, '')
+          RSpec.warn_with <<-WARNING.gsub(/^ +\|/, ''), :call_site => nil
             |WARNING: Shared example group '#{key}' has been previously defined at:
             |  #{formatted_location existing_block}
             |...and you are now defining it at:
@@ -170,25 +165,17 @@ module RSpec
           block.source_location.join ":"
         end
 
-        def example_block_for(source, key)
-          shared_example_groups[source][key]
-        end
-
         if Proc.method_defined?(:source_location)
-          def ensure_block_has_source_location(block, caller_line); end
+          def ensure_block_has_source_location(block); end
         else # for 1.8.7
-          def ensure_block_has_source_location(block, caller_line)
-            block.extend Module.new {
-              define_method :source_location do
-                caller_line.split(':')
-              end
-            }
+          def ensure_block_has_source_location(block)
+            source_location = yield.split(':')
+            block.extend Module.new { define_method(:source_location) { source_location } }
           end
         end
       end
     end
   end
-end
 
-extend RSpec::Core::SharedExampleGroup::TopLevelDSL
-Module.send(:include, RSpec::Core::SharedExampleGroup::TopLevelDSL)
+  instance_exec(&Core::SharedExampleGroup::TopLevelDSL.definitions)
+end

data/lib/rspec/core/version.rb

@@ -1,7 +1,9 @@
 module RSpec
   module Core
+    # Version information for RSpec Core.
     module Version
-      STRING = '2.99.0'
+      # Current version of RSpec Core, in semantic versioning format.
+      STRING = '3.0.0'
     end
   end
 end

data/lib/rspec/core/warnings.rb

@@ -0,0 +1,40 @@
+require "rspec/support/warnings"
+
+module RSpec
+  module Core
+    # @private
+    module Warnings
+      # @private
+      #
+      # Used internally to print deprecation warnings
+      def deprecate(deprecated, data = {})
+        RSpec.configuration.reporter.deprecation(
+          {
+            :deprecated => deprecated,
+            :call_site => CallerFilter.first_non_rspec_line
+          }.merge(data)
+        )
+      end
+
+      # @private
+      #
+      # Used internally to print deprecation warnings
+      def warn_deprecation(message, opts = {})
+        RSpec.configuration.reporter.deprecation opts.merge( :message => message )
+      end
+
+      # @private
+      def warn_with(message, options = {})
+        if options[:use_spec_location_as_call_site]
+          message += "." unless message.end_with?(".")
+
+          if RSpec.current_example
+            message += " Warning generated from spec at `#{RSpec.current_example.location}`."
+          end
+        end
+
+        super(message, options)
+      end
+    end
+  end
+end