rspec-core 3.0.0.beta2 → 3.0.0.rc1

data/lib/rspec/core/configuration_options.rb

@@ -1,47 +1,59 @@
 require 'erb'
 require 'shellwords'
+require 'set'
 
 module RSpec
   module Core
-    # @private
+    # Responsible for utilizing externally provided configuration options,
+    # whether via the command line, `.rspec`, `~/.rspec`, `.rspec-local`
+    # or a custom options file.
     class ConfigurationOptions
+      # @param args [Array<String>] command line arguments
       def initialize(args)
         @args = args.dup
+        organize_options
       end
 
+      # Updates the provided {Configuration} instance based on the provided
+      # external configuration options.
+      #
+      # @param config [Configuration] the configuration instance to update
       def configure(config)
-        config.filter_manager = filter_manager
-
         process_options_into config
+        configure_filter_manager config.filter_manager
         load_formatters_into config
       end
 
-      def options
-        @options ||= (file_options << command_line_options << env_options).
-          each {|opts|
-            filter_manager.include opts.delete(:inclusion_filter) if opts.has_key?(:inclusion_filter)
-            filter_manager.exclude opts.delete(:exclusion_filter) if opts.has_key?(:exclusion_filter)
-          }.
-          inject(:libs => [], :requires => []) {|h, opts|
-            h.merge(opts) {|k, oldval, newval|
-              [:libs, :requires].include?(k) ? oldval + newval : newval
-            }
-          }
+      # @api private
+      # Updates the provided {FilterManager} based on the filter options.
+      # @param filter_manager [FilterManager] instance to update
+      def configure_filter_manager(filter_manager)
+        @filter_manager_inclusions.each { |val| filter_manager.include(val) }
+        @filter_manager_exclusions.each { |val| filter_manager.exclude(val) }
       end
 
-      def drb_argv
-        DrbOptions.new(options, filter_manager).options
-      end
-
-      def filter_manager
-        @filter_manager ||= RSpec::configuration.filter_manager
-      end
+      # @return [Hash] the final merged options, drawn from all external sources
+      attr_reader :options
 
     private
 
+      def organize_options
+        @filter_manager_inclusions = []
+        @filter_manager_exclusions = []
+
+        @options = (file_options << command_line_options << env_options).each { |opts|
+          @filter_manager_inclusions << opts.delete(:inclusion_filter) if opts.key?(:inclusion_filter)
+          @filter_manager_exclusions << opts.delete(:exclusion_filter) if opts.key?(:exclusion_filter)
+        }.inject(:libs => [], :requires => []) { |hash, opts|
+          hash.merge(opts) { |key, oldval, newval|
+            [:libs, :requires].include?(key) ? oldval + newval : newval
+          }
+        }
+      end
+
       UNFORCED_OPTIONS = [
         :requires, :profile, :drb, :libs, :files_or_directories_to_run,
-        :line_numbers, :full_description, :full_backtrace, :tty
+        :full_description, :full_backtrace, :tty
       ].to_set
 
       UNPROCESSABLE_OPTIONS = [:formatters].to_set
@@ -58,6 +70,10 @@ module RSpec
       end
 
       OPTIONS_ORDER = [
+        # It's important to set this before anything that might issue a
+        # deprecation (or otherwise access the reporter).
+        :deprecation_stream,
+
         # load paths depend on nothing, but must be set before `requires`
         # to support load-path-relative requires.
         :libs,

data/lib/rspec/core/drb.rb

@@ -0,0 +1,111 @@
+require 'drb/drb'
+
+module RSpec
+  module Core
+    # @private
+    class DRbRunner
+      def initialize(options, configuration=RSpec.configuration)
+        @options       = options
+        @configuration = configuration
+      end
+
+      def drb_port
+        @options.options[:drb_port] || ENV['RSPEC_DRB'] || 8989
+      end
+
+      def run(err, out)
+        begin
+          DRb.start_service("druby://localhost:0")
+        rescue SocketError, Errno::EADDRNOTAVAIL
+          DRb.start_service("druby://:0")
+        end
+        spec_server = DRbObject.new_with_uri("druby://127.0.0.1:#{drb_port}")
+        spec_server.run(drb_argv, err, out)
+      end
+
+      def drb_argv
+        @drb_argv ||= begin
+          @options.configure_filter_manager(@configuration.filter_manager)
+          DRbOptions.new(@options.options, @configuration.filter_manager).options
+        end
+      end
+    end
+
+    # @private
+    class DRbOptions
+      def initialize(submitted_options, filter_manager)
+        @submitted_options = submitted_options
+        @filter_manager = filter_manager
+      end
+
+      def options
+        argv = []
+        argv << "--color"        if @submitted_options[:color]
+        argv << "--profile"      if @submitted_options[:profile_examples]
+        argv << "--backtrace"    if @submitted_options[:full_backtrace]
+        argv << "--tty"          if @submitted_options[:tty]
+        argv << "--fail-fast"    if @submitted_options[:fail_fast]
+        argv << "--options"      << @submitted_options[:custom_options_file] if @submitted_options[:custom_options_file]
+        argv << "--order"        << @submitted_options[:order]               if @submitted_options[:order]
+
+        add_failure_exit_code(argv)
+        add_full_description(argv)
+        add_filter(argv, :inclusion, @filter_manager.inclusions)
+        add_filter(argv, :exclusion, @filter_manager.exclusions)
+        add_formatters(argv)
+        add_libs(argv)
+        add_requires(argv)
+
+        argv + @submitted_options[:files_or_directories_to_run]
+      end
+
+      def add_failure_exit_code(argv)
+        if @submitted_options[:failure_exit_code]
+          argv << "--failure-exit-code" << @submitted_options[:failure_exit_code].to_s
+        end
+      end
+
+      def add_full_description(argv)
+        if @submitted_options[:full_description]
+          # The argument to --example is regexp-escaped before being stuffed
+          # into a regexp when received for the first time (see OptionParser).
+          # Hence, merely grabbing the source of this regexp will retain the
+          # backslashes, so we must remove them.
+          @submitted_options[:full_description].each do |description|
+            argv << "--example" << description.source.delete('\\')
+          end
+        end
+      end
+
+      CONDITIONAL_FILTERS = [:if, :unless]
+
+      def add_filter(argv, name, hash)
+        hash.each_pair do |k, v|
+          next if CONDITIONAL_FILTERS.include?(k)
+          tag = name == :inclusion ? k.to_s : "~#{k}"
+          tag << ":#{v}" if v.is_a?(String)
+          argv << "--tag" << tag
+        end unless hash.empty?
+      end
+
+      def add_formatters(argv)
+        @submitted_options[:formatters].each do |pair|
+          argv << "--format" << pair[0]
+          argv << "--out" << pair[1] if pair[1]
+        end if @submitted_options[:formatters]
+      end
+
+      def add_libs(argv)
+        @submitted_options[:libs].each do |path|
+          argv << "-I" << path
+        end if @submitted_options[:libs]
+      end
+
+      def add_requires(argv)
+        @submitted_options[:requires].each do |path|
+          argv << "--require" << path
+        end if @submitted_options[:requires]
+      end
+    end
+  end
+end

data/lib/rspec/core/dsl.rb

@@ -33,11 +33,12 @@ module RSpec
         @exposed_globally ||= false
       end
 
+      # @private
       def self.expose_example_group_alias(name)
         example_group_aliases << name
 
         (class << RSpec; self; end).__send__(:define_method, name) do |*args, &example_group_block|
-          RSpec::Core::ExampleGroup.__send__(name, *args, &example_group_block).register
+          RSpec.world.register RSpec::Core::ExampleGroup.__send__(name, *args, &example_group_block)
         end
 
         expose_example_group_alias_globally(name) if exposed_globally?
@@ -48,7 +49,8 @@ module RSpec
         attr_accessor :top_level
       end
 
-      # Add's the describe method to Module and the top level binding
+      # Adds the describe method to Module and the top level binding
+      # @api private
       def self.expose_globally!
         return if exposed_globally?
 
@@ -59,6 +61,8 @@ module RSpec
         @exposed_globally = true
       end
 
+      # Removes the describe method from Module and the top level binding
+      # @api private
       def self.remove_globally!
         return unless exposed_globally?
 
@@ -69,12 +73,14 @@ module RSpec
         @exposed_globally = false
       end
 
+      # @private
       def self.expose_example_group_alias_globally(method_name)
         change_global_dsl do
           define_method(method_name) { |*a, &b| ::RSpec.__send__(method_name, *a, &b) }
         end
       end
 
+      # @private
       def self.change_global_dsl(&changes)
         (class << top_level; self; end).class_exec(&changes)
         Module.class_exec(&changes)

data/lib/rspec/core/example.rb

@@ -1,9 +1,15 @@
 module RSpec
   module Core
     # Wrapper for an instance of a subclass of {ExampleGroup}. An instance of
-    # `Example` is returned by the {ExampleGroup#example example} method
-    # exposed to examples, {Hooks#before before} and {Hooks#after after} hooks,
-    # and yielded to {Hooks#around around} hooks.
+    # `RSpec::Core::Example` is returned by example definition methods
+    # such as {ExampleGroup.it it} and is yielded to the {ExampleGroup.it it},
+    # {Hooks#before before}, {Hooks#after after}, {Hooks#around around},
+    # {MemoizedHelpers::ClassMethods#let let} and
+    # {MemoizedHelpers::ClassMethods#subject subject} blocks.
+    #
+    # This allows us to provide rich metadata about each individual
+    # example without adding tons of methods directly to the ExampleGroup
+    # that users may inadvertantly redefine.
     #
     # Useful for configuring logging and/or taking some action based
     # on the state of an example's metadata.
@@ -11,17 +17,17 @@ module RSpec
     # @example
     #
     #     RSpec.configure do |config|
-    #       config.before do
+    #       config.before do |example|
     #         log example.description
     #       end
     #
-    #       config.after do
+    #       config.after do |example|
     #         log example.description
     #       end
     #
-    #       config.around do |ex|
+    #       config.around do |example|
     #         log example.description
-    #         ex.run
+    #         example.run
     #       end
     #     end
     #
@@ -33,16 +39,33 @@ module RSpec
     #     end
     #
     # @see ExampleGroup
+    # @note Example blocks are evaluated in the context of an instance
+    #   of an `ExampleGroup`, not in the context of an instance of `Example`.
     class Example
       # @private
       #
       # Used to define methods that delegate to this example's metadata
-      def self.delegate_to_metadata(*keys)
-        keys.each { |key| define_method(key) { @metadata[key] } }
+      def self.delegate_to_metadata(key)
+        define_method(key) { @metadata[key] }
       end
 
-      delegate_to_metadata :execution_result, :file_path, :full_description,
-                           :location, :pending, :skip
+      # @return [ExecutionResult] represents the result of running this example.
+      delegate_to_metadata :execution_result
+      # @return [String] the relative path to the file where this example was defined.
+      delegate_to_metadata :file_path
+      # @return [String] the full description (including the docstrings of
+      #   all parent example groups).
+      delegate_to_metadata :full_description
+      # @return [String] the exact source location of this example in a form
+      #   like `./path/to/spec.rb:17`
+      delegate_to_metadata :location
+      # @return [Boolean] flag that indicates that the example is not expected to pass.
+      #   It will be run and will either have a pending result (if a failure occurs)
+      #   or a failed result (if no failure occurs).
+      delegate_to_metadata :pending
+      # @return [Boolean] flag that will cause the example to not run.
+      #   The {ExecutionResult} status will be `:pending`.
+      delegate_to_metadata :skip
 
       # Returns the string submitted to `example` or its aliases (e.g.
       # `specify`, `it`, etc).  If no string is submitted (e.g. `it { is_expected.to
@@ -74,27 +97,28 @@ module RSpec
       # running this example.
       attr_reader :example_group_instance
 
-      # @attr_accessor
+      # @attr
       # @private
       attr_accessor :clock
 
       # Creates a new instance of Example.
-      # @param example_group_class the subclass of ExampleGroup in which this Example is declared
-      # @param description the String passed to the `it` method (or alias)
-      # @param metadata additional args passed to `it` to be used as metadata
-      # @param example_block the block of code that represents the example
-      def initialize(example_group_class, description, metadata, example_block=nil)
-        @example_group_class, @options, @example_block = example_group_class, metadata, example_block
-        @metadata  = @example_group_class.metadata.for_example(description, metadata)
+      # @param example_group_class [Class] the subclass of ExampleGroup in which this Example is declared
+      # @param description [String] the String passed to the `it` method (or alias)
+      # @param user_metadata [Hash] additional args passed to `it` to be used as metadata
+      # @param example_block [Proc] the block of code that represents the example
+      # @api private
+      def initialize(example_group_class, description, user_metadata, example_block=nil)
+        @example_group_class = example_group_class
+        @example_block       = example_block
+
+        @metadata = Metadata::ExampleHash.create(
+          @example_group_class.metadata, user_metadata, description, example_block
+        )
+
         @example_group_instance = @exception = nil
         @clock = RSpec::Core::Time
       end
 
-      # @deprecated access options via metadata instead
-      def options
-        @options
-      end
-
       # Returns the example group class that provides the context for running
       # this example.
       def example_group
@@ -105,7 +129,7 @@ module RSpec
       alias_method :skipped?, :skip
 
       # @api private
-      # instance_evals the block passed to the constructor in the context of
+      # instance_execs the block passed to the constructor in the context of
       # the instance of {ExampleGroup}.
       # @param example_group_instance the instance of an ExampleGroup subclass
       def run(example_group_instance, reporter)
@@ -118,9 +142,9 @@ module RSpec
           if skipped?
             Pending.mark_pending! self, skip
           elsif !RSpec.configuration.dry_run?
-            with_around_each_hooks do
+            with_around_example_hooks do
               begin
-                run_before_each
+                run_before_example
                 @example_group_instance.instance_exec(self, &@example_block)
 
                 if pending?
@@ -128,7 +152,7 @@ module RSpec
 
                   raise Pending::PendingExampleFixedError,
                     'Expected example to fail since it is pending, but it passed.',
-                    metadata[:caller]
+                    [location]
                 end
               rescue Pending::SkipDeclaredInExample
                 # no-op, required metadata has already been set by the `skip`
@@ -136,7 +160,7 @@ module RSpec
               rescue Exception => e
                 set_exception(e)
               ensure
-                run_after_each
+                run_after_example
               end
             end
           end
@@ -147,12 +171,6 @@ module RSpec
             @example_group_instance.instance_variable_set(ivar, nil)
           end
           @example_group_instance = nil
-
-          begin
-            assign_generated_description
-          rescue Exception => e
-            set_exception(e, "while assigning the example description")
-          end
         end
 
         finish(reporter)
@@ -160,12 +178,10 @@ module RSpec
         RSpec.current_example = nil
       end
 
-      # Wraps a `Proc` and exposes a `run` method for use in {Hooks#around
-      # around} hooks.
-      #
-      # @note Procsy, itself, is not a public API, but we're documenting it
-      #   here to document how to interact with the object yielded to an
-      #   `around` hook.
+      # Wraps both a `Proc` and an {Example} for use in {Hooks#around
+      # around} hooks. In around hooks we need to yield this special
+      # kind of object (rather than the raw {Example}) because when
+      # there are multiple `around` hooks we have to wrap them recursively.
       #
       # @example
       #
@@ -177,39 +193,46 @@ module RSpec
       #         ex.run         # run delegates to ex.call
       #       end
       #     end
+      #
+      # @note This class also exposes the instance methods of {Example},
+      #   proxying them through to the wrapped {Example} instance.
       class Procsy
-        # The `metadata` of the {Example} instance.
-        attr_reader :metadata
+        # The {Example} instance.
+        attr_reader :example
+
+        Example.public_instance_methods(false).each do |name|
+          define_method(name) { |*a, &b| @example.__send__(name, *a, &b) }
+        end
 
         Proc.public_instance_methods(false).each do |name|
           define_method(name) { |*a, &b| @proc.__send__(name, *a, &b) }
         end
         alias run call
 
-        def initialize(metadata, &block)
-          @metadata = metadata
-          @proc = block
+        def initialize(example, &block)
+          @example = example
+          @proc    = block
         end
 
-        # @api private
+        # @private
         def wrap(&block)
-          self.class.new(metadata, &block)
+          self.class.new(example, &block)
         end
       end
 
       # @private
       def any_apply?(filters)
-        metadata.any_apply?(filters)
+        MetadataFilter.any_apply?(filters, metadata)
       end
 
       # @private
       def all_apply?(filters)
-        @metadata.all_apply?(filters) || @example_group_class.all_apply?(filters)
+        MetadataFilter.all_apply?(filters, metadata) || @example_group_class.all_apply?(filters)
       end
 
       # @private
-      def around_each_hooks
-        @around_each_hooks ||= example_group.hooks.around_each_hooks_for(self)
+      def around_example_hooks
+        @around_example_hooks ||= example_group.hooks.around_example_hooks_for(self)
       end
 
       # @private
@@ -217,10 +240,10 @@ module RSpec
       # Used internally to set an exception in an after hook, which
       # captures the exception but doesn't raise it.
       def set_exception(exception, context=nil)
-        if pending?
-          metadata[:execution_result][:pending_exception] = exception
+        if pending? && !(Pending::PendingExampleFixedError === exception)
+          execution_result.pending_exception = exception
         else
-          if @exception && context != :dont_print
+          if @exception
             # An error has already been set; we don't want to override it,
             # but we also don't want silence the error, so let's print it.
             msg = <<-EOS
@@ -240,7 +263,7 @@ module RSpec
       # @private
       #
       # Used internally to set an exception and fail without actually executing
-      # the example when an exception is raised in before(:all).
+      # the example when an exception is raised in before(:context).
       def fail_with_exception(reporter, exception)
         start(reporter)
         set_exception(exception)
@@ -250,7 +273,7 @@ module RSpec
       # @private
       #
       # Used internally to skip without actually executing the example when
-      # skip is used in before(:all)
+      # skip is used in before(:context)
       def skip_with_exception(reporter, exception)
         start(reporter)
         Pending.mark_skipped! self, exception.argument
@@ -258,8 +281,10 @@ module RSpec
       end
 
       # @private
-      def instance_exec_with_rescue(context = nil, &block)
-        @example_group_instance.instance_exec_with_rescue(self, context, &block)
+      def instance_exec_with_rescue(context, &block)
+        @example_group_instance.instance_exec(self, &block)
+      rescue Exception => e
+        set_exception(e, context)
       end
 
       # @private
@@ -269,88 +294,86 @@ module RSpec
 
     private
 
-      def with_around_each_hooks(&block)
-        if around_each_hooks.empty?
+      def with_around_example_hooks(&block)
+        if around_example_hooks.empty?
           yield
         else
-          @example_group_class.hooks.run(:around, :each, self, Procsy.new(metadata, &block))
+          @example_group_class.hooks.run(:around, :example, self, Procsy.new(self, &block))
         end
       rescue Exception => e
-        set_exception(e, "in an around(:each) hook")
+        set_exception(e, "in an `around(:example)` hook")
       end
 
       def start(reporter)
         reporter.example_started(self)
-        record :started_at => clock.now
+        execution_result.started_at = clock.now
       end
 
       def finish(reporter)
-        pending_message = metadata[:execution_result][:pending_message]
+        pending_message = execution_result.pending_message
 
         if @exception
-          record_finished 'failed', :exception => @exception
+          record_finished :failed
+          execution_result.exception = @exception
           reporter.example_failed self
           false
         elsif pending_message
-          record_finished 'pending', :pending_message => pending_message
+          record_finished :pending
+          execution_result.pending_message = pending_message
           reporter.example_pending self
           true
         else
-          record_finished 'passed'
+          record_finished :passed
           reporter.example_passed self
           true
         end
       end
 
-      def record_finished(status, results={})
-        finished_at = clock.now
-        record results.merge(
-          :status      => status,
-          :finished_at => finished_at,
-          :run_time    => (finished_at - execution_result[:started_at]).to_f
-        )
+      def record_finished(status)
+        execution_result.record_finished(status, clock.now)
       end
 
-      def run_before_each
+      def run_before_example
         @example_group_instance.setup_mocks_for_rspec
-        @example_group_class.hooks.run(:before, :each, self)
+        @example_group_class.hooks.run(:before, :example, self)
       end
 
-      def run_after_each
-        @example_group_class.hooks.run(:after, :each, self)
+      def run_after_example
+        @example_group_class.hooks.run(:after, :example, self)
         verify_mocks
+        assign_generated_description if RSpec.configuration.expecting_with_rspec?
       rescue Exception => e
-        set_exception(e, "in an after(:each) hook")
+        set_exception(e, "in an `after(:example)` hook")
       ensure
         @example_group_instance.teardown_mocks_for_rspec
       end
 
       def verify_mocks
-        @example_group_instance.verify_mocks_for_rspec
+        @example_group_instance.verify_mocks_for_rspec if mocks_need_verification?
       rescue Exception => e
-        if metadata[:execution_result][:pending_message]
-          metadata[:execution_result][:pending_fixed] = false
-          metadata[:pending] = true
+        if pending?
+          execution_result.pending_fixed = false
           @exception = nil
         else
-          set_exception(e, :dont_print)
+          set_exception(e)
         end
       end
 
-      def assign_generated_description
-        return unless RSpec.configuration.expecting_with_rspec?
+      def mocks_need_verification?
+        exception.nil? || execution_result.pending_fixed?
+      end
 
-        if metadata[:description_args].empty?
-          metadata[:description_args] << RSpec::Matchers.generated_description
+      def assign_generated_description
+        if metadata[:description].empty? && (description = RSpec::Matchers.generated_description)
+          metadata[:description] = description
+          metadata[:full_description] << description
         end
-
+      rescue Exception => e
+        set_exception(e, "while assigning the example description")
+      ensure
         RSpec::Matchers.clear_generated_description
       end
 
-      def record(results={})
-        execution_result.update(results)
-      end
-
       def skip_message
         if String === skip
           skip
@@ -358,6 +381,92 @@ module RSpec
           Pending::NO_REASON_GIVEN
         end
       end
+
+      # Represents the result of executing an example.
+      # Behaves like a hash for backwards compatibility.
+      class ExecutionResult
+        include HashImitatable
+
+        # @return [Symbol] `:passed`, `:failed` or `:pending`.
+        attr_accessor :status
+
+        # @return [Exception, nil] The failure, if there was one.
+        attr_accessor :exception
+
+        # @return [Time] When the example started.
+        attr_accessor :started_at
+
+        # @return [Time] When the example finished.
+        attr_accessor :finished_at
+
+        # @return [Float] How long the example took in seconds.
+        attr_accessor :run_time
+
+        # @return [String, nil] The reason the example was pending,
+        #   or nil if the example was not pending.
+        attr_accessor :pending_message
+
+        # @return [Exception, nil] The exception triggered while
+        #   executing the pending example. If no exception was triggered
+        #   it would no longer get a status of `:pending` unless it was
+        #   tagged with `:skip`.
+        attr_accessor :pending_exception
+
+        # @return [Boolean] For examples tagged with `:pending`,
+        #   this indicates whether or not it now passes.
+        attr_accessor :pending_fixed
+
+        alias pending_fixed? pending_fixed
+
+        # @api private
+        # Records the finished status of the example.
+        def record_finished(status, finished_at)
+          self.status      = status
+          self.finished_at = finished_at
+          self.run_time    = (finished_at - started_at).to_f
+        end
+
+      private
+
+        # For backwards compatibility we present `status` as a string
+        # when presenting the legacy hash interface.
+        def hash_for_delegation
+          super.tap do |hash|
+            hash[:status] &&= status.to_s
+          end
+        end
+
+        def set_value(name, value)
+          value &&= value.to_sym if name == :status
+          super(name, value)
+        end
+
+        def get_value(name)
+          if name == :status
+            status.to_s if status
+          else
+            super
+          end
+        end
+
+        def issue_deprecation(method_name, *args)
+          RSpec.deprecate("Treating `metadata[:execution_result]` as a hash",
+                          :replacement => "the attributes methods to access the data")
+        end
+      end
+    end
+
+    # @private
+    # Provides an execution context for before/after :suite hooks.
+    class SuiteHookContext < Example
+      def initialize
+        super(AnonymousExampleGroup, "", {})
+      end
+
+      # To ensure we don't silence errors...
+      def set_exception(exception, context=nil)
+        raise exception
+      end
     end
   end
 end