rspec-core 3.0.0.beta2 → 3.0.0.rc1

data/lib/rspec/core/ruby_project.rb

@@ -6,6 +6,7 @@ require 'pathname'
 
 module RSpec
   module Core
+    # @private
     module RubyProject
       def add_to_load_path(*dirs)
         dirs.map {|dir| add_dir_to_load_path(File.join(root, dir))}

data/lib/rspec/core/runner.rb

@@ -1,8 +1,15 @@
 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
         if autorun_disabled?
           RSpec.deprecate("Requiring `rspec/autorun` when running RSpec via the `rspec` command")
@@ -24,26 +31,107 @@ module RSpec
         end
         @installed_at_exit = true
       end
-      AT_EXIT_HOOK_BACKTRACE_LINE = "#{__FILE__}:#{__LINE__ - 2}:in `autorun'"
 
+      # 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
 
+      # 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`.
+      #
+      # @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)
+
+        if options.options[:drb]
+          require 'rspec/core/drb'
+          begin
+            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)
+          end
+        else
+          new(options).run(err, out)
+        end
+      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
@@ -60,48 +148,14 @@ module RSpec
         end
       end
 
+      # @private
       def self.trap_interrupt
         trap('INT') do
-          exit!(1) if RSpec.wants_to_quit
-          RSpec.wants_to_quit = true
+          exit!(1) if RSpec.world.wants_to_quit
+          RSpec.world.wants_to_quit = true
           STDERR.puts "\nExiting... Interrupt again to exit immediately."
         end
       end
-
-      # Run a suite of RSpec examples.
-      #
-      # 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+ - an array of command-line-supported arguments
-      # * +err+ - error stream (Default: $stderr)
-      # * +out+ - output stream (Default: $stdout)
-      #
-      # #### Returns
-      # * +Fixnum+ - exit status code (0/1)
-      def self.run(args, err=$stderr, out=$stdout)
-        trap_interrupt
-        options = ConfigurationOptions.new(args)
-
-        if options.options[:drb]
-          require 'rspec/core/drb_command_line'
-          begin
-            DRbCommandLine.new(options).run(err, out)
-          rescue DRb::DRbConnError
-            err.puts "No DRb server is running. Running in local process instead ..."
-            CommandLine.new(options).run(err, out)
-          end
-        else
-          CommandLine.new(options).run(err, out)
-        end
-      ensure
-        RSpec.reset
-      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,25 +17,26 @@ 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|
           define_method(meth) do |*args, &block|
@@ -44,10 +45,11 @@ module RSpec
         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,57 +1,77 @@
 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 :share_examples_for,  :shared_examples
-      alias_method :shared_examples_for, :shared_examples
+      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
+        # @private
         def self.definitions
           proc do
-            def shared_examples(*args, &block)
-              SharedExampleGroup.registry.add_group('main', *args, &block)
-            end
-            alias :shared_context      :shared_examples
-            alias :share_examples_for  :shared_examples
-            alias :shared_examples_for :shared_examples
-            def shared_example_groups
-              SharedExampleGroup.registry.shared_example_groups_for('main')
+            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
 
@@ -60,21 +80,25 @@ module RSpec
           @exposed_globally ||= false
         end
 
+        # @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
 
+        # @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 share_examples_for
             undef shared_examples_for
-            undef shared_example_groups
           end
 
           @exposed_globally = false
@@ -82,60 +106,51 @@ module RSpec
 
       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, :included) do |host|
-              host.class_eval(&block)
+              host.class_exec(&block)
             end
-            RSpec.configuration.include mod, *args
+            RSpec.configuration.include mod, *metadata_args
           end
         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 find(lookup_contexts, name)
+          lookup_contexts.each do |context|
+            found = shared_example_groups[context][name]
+            return found if found
+          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
+        def shared_example_groups
+          @shared_example_groups ||= Hash.new { |hash, context| hash[context] = {} }
         end
 
-        def key?(candidate)
-          [String, Symbol, Module].any? { |cls| cls === candidate }
+        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]
 
           RSpec.warn_with <<-WARNING.gsub(/^ +\|/, ''), :call_site => nil
             |WARNING: Shared example group '#{key}' has been previously defined at:
@@ -150,24 +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
 
-  instance_eval(&Core::SharedExampleGroup::TopLevelDSL.definitions)
+  instance_exec(&Core::SharedExampleGroup::TopLevelDSL.definitions)
 end