rspec-core 2.8.0.rc1 → 2.8.0.rc2

data/lib/rspec/core/configuration_options.rb

@@ -2,6 +2,7 @@ require 'erb'
 
 module RSpec
   module Core
+    # @private
     class ConfigurationOptions
       attr_reader :options
 
@@ -37,7 +38,7 @@ module RSpec
 
     private
 
-      NON_FORCED_OPTIONS = [:debug, :order, :seed, :requires, :libs, :files_or_directories_to_run, :line_numbers, :full_description]
+      NON_FORCED_OPTIONS = [:debug, :requires, :libs, :files_or_directories_to_run, :line_numbers, :full_description]
 
       def force?(key)
         !NON_FORCED_OPTIONS.include?(key)

data/lib/rspec/core/deprecation.rb

@@ -1,7 +1,6 @@
 module RSpec
-
   class << self
-    # @api private
+    # @private
     #
     # Used internally to print deprecation warnings
     def deprecate(method, alternate_method=nil, version=nil)
@@ -27,7 +26,7 @@ ADDITIONAL
       warn_deprecation(message)
     end
 
-    # @api private
+    # @private
     #
     # Used internally to print deprecation warnings
     def warn_deprecation(message)

data/lib/rspec/core/drb_options.rb

@@ -1,72 +1,83 @@
 # Builds command line arguments to pass to the rspec command over DRb
-class RSpec::Core::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]
+module RSpec::Core
+  # @private
+  class DrbOptions
+    def initialize(submitted_options, filter_manager)
+      @submitted_options = submitted_options
+      @filter_manager = filter_manager
+    end
 
-    add_full_description(argv)
-    add_line_numbers(argv)
-    add_filter(argv, :inclusion, @filter_manager.inclusions)
-    add_filter(argv, :exclusion, @filter_manager.exclusions)
-    add_formatters(argv)
-    add_libs(argv)
-    add_requires(argv)
+    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]
 
-    argv + @submitted_options[:files_or_directories_to_run]
-  end
+      add_failure_exit_code(argv)
+      add_full_description(argv)
+      add_line_numbers(argv)
+      add_filter(argv, :inclusion, @filter_manager.inclusions)
+      add_filter(argv, :exclusion, @filter_manager.exclusions)
+      add_formatters(argv)
+      add_libs(argv)
+      add_requires(argv)
 
-  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.
-      argv << "--example" << @submitted_options[:full_description].source.delete('\\')
+      argv + @submitted_options[:files_or_directories_to_run]
     end
-  end
 
-  def add_line_numbers(argv)
-    if @submitted_options[:line_numbers]
-      argv.push(*@submitted_options[:line_numbers].inject([]){|a,l| a << "--line_number" << l})
+    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
-  end
 
-  def add_filter(argv, name, hash)
-    hash.each_pair do |k, v|
-      next if [:if,:unless].include?(k)
-      tag = name == :inclusion ? k.to_s : "~#{k.to_s}"
-      tag << ":#{v.to_s}" if v.is_a?(String)
-      argv << "--tag" << tag
-    end unless hash.empty?
-  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.
+        argv << "--example" << @submitted_options[:full_description].source.delete('\\')
+      end
+    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_line_numbers(argv)
+      if @submitted_options[:line_numbers]
+        argv.push(*@submitted_options[:line_numbers].inject([]){|a,l| a << "--line_number" << l})
+      end
+    end
 
-  def add_libs(argv)
-    @submitted_options[:libs].each do |path|
-      argv << "-I" << path
-    end if @submitted_options[:libs]
-  end
+    def add_filter(argv, name, hash)
+      hash.each_pair do |k, v|
+        next if [:if,:unless].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]
+    def add_requires(argv)
+      @submitted_options[:requires].each do |path|
+        argv << "--require" << path
+      end if @submitted_options[:requires]
+    end
   end
 end

data/lib/rspec/core/dsl.rb

@@ -1,6 +1,18 @@
 module RSpec
   module Core
     module DSL
+      # Generates a subclass of [ExampleGroup](ExampleGroup)
+      #
+      # ## Examples:
+      #
+      #     describe "something" do
+      #       it "does something" do
+      #         # example code goes here
+      #       end
+      #     end
+      #
+      # @see ExampleGroup
+      # @see ExampleGroup.describe
       def describe(*args, &example_group_block)
         RSpec::Core::ExampleGroup.describe(*args, &example_group_block).register
       end

data/lib/rspec/core/example.rb

@@ -1,7 +1,16 @@
 module RSpec
   module Core
+    # Wrapper for an instance of a subclass of [ExampleGroup](ExampleGroup). An
+    # instance of `Example` is returned by the
+    # [example](ExampleGroup#example-instance_method) method available in
+    # examples, [before](Hooks#before-instance_method) and
+    # [after](Hooks#after-instance_method) hooks, and yielded to
+    # [around](Hooks#around-instance_method) hooks.
+    # @see ExampleGroup
     class Example
-
+      # @private
+      #
+      # Used to define methods that delegate to this example's metadata
       def self.delegate_to_metadata(*keys)
         keys.each do |key|
           define_method(key) {@metadata[key]}
@@ -20,17 +29,22 @@ module RSpec
       #
       # Returns the metadata object associated with this example.
       attr_reader :metadata
-      
+
       # @attr_reader
-      # @api private
+      # @private
       #
       # Returns the example_group_instance that provides the context for
       # running this example.
       attr_reader :example_group_instance
 
-      def initialize(example_group_class, desc, options, example_block=nil)
-        @example_group_class, @options, @example_block = example_group_class, options, example_block
-        @metadata  = @example_group_class.metadata.for_example(desc, options)
+      # 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)
         @exception = nil
         @pending_declared_in_example = false
       end
@@ -48,6 +62,10 @@ module RSpec
 
       alias_method :pending?, :pending
 
+      # @api private
+      # @param example_group_instance the instance of an ExampleGroup subclass
+      # instance_evals the block submitted to the constructor in the
+      # context of the instance of ExampleGroup
       def run(example_group_instance, reporter)
         @example_group_instance = example_group_instance
         @example_group_instance.example = self
@@ -87,34 +105,50 @@ module RSpec
         finish(reporter)
       end
 
-      def self.procsy(metadata, &block)
-        Proc.new(&block).extend(Procsy).with(metadata)
+      # @private
+      #
+      # Wraps the example block in a Proc so it can invoked using `run` or
+      # `call` in [around](../Hooks#around-instance_method) hooks.
+      def self.procsy(metadata, &proc)
+        Proc.new(&proc).extend(Procsy).with(metadata)
       end
 
+      # @private
       module Procsy
         attr_reader :metadata
 
+        # @private
+        # @param [Proc]
+        # Adds a `run` method to the extended Proc, allowing it to be invoked
+        # in an [around](../Hooks#around-instance_method) hook using either
+        # `run` or `call`.
         def self.extended(object)
           def object.run; call; end
         end
 
+        # @private
         def with(metadata)
           @metadata = metadata
           self
         end
       end
 
-      # @api private
+      # @private
+      def any_apply?(filters)
+        metadata.any_apply?(filters)
+      end
+
+      # @private
       def all_apply?(filters)
         @metadata.all_apply?(filters) || @example_group_class.all_apply?(filters)
       end
 
-      # @api private
+      # @private
       def around_hooks
         @around_hooks ||= example_group.around_hooks_for(self)
       end
 
-      # @api private
+      # @private
       #
       # Used internally to set an exception in an after hook, which
       # captures the exception but doesn't raise it.
@@ -122,7 +156,7 @@ module RSpec
         @exception ||= exception
       end
 
-      # @api private
+      # @private
       #
       # Used internally to set an exception and fail without actually executing
       # the example when an exception is raised in before(:all).
@@ -132,11 +166,6 @@ module RSpec
         finish(reporter)
       end
 
-      # @api private
-      def any_apply?(filters)
-        metadata.any_apply?(filters)
-      end
-
     private
 
       def with_around_hooks(&block)
@@ -152,8 +181,14 @@ module RSpec
         record :started_at => Time.now
       end
 
+      # @private
+      module NotPendingExampleFixed
+        def pending_fixed?; false; end
+      end
+
       def finish(reporter)
         if @exception
+          @exception.extend(NotPendingExampleFixed) unless @exception.respond_to?(:pending_fixed?)
           record_finished 'failed', :exception => @exception
           reporter.example_failed self
           false
@@ -162,7 +197,7 @@ module RSpec
           reporter.example_pending self
           true
         elsif pending
-          record_finished 'pending', :pending_message => 'Not Yet Implemented'
+          record_finished 'pending', :pending_message => String === pending ? pending : Pending::NO_REASON_GIVEN
           reporter.example_pending self
           true
         else

data/lib/rspec/core/example_group.rb

@@ -1,32 +1,40 @@
 module RSpec
   module Core
+    # ExampleGroup and Example are the main structural elements of rspec-core.
+    # Consider this example:
+    #
+    #     describe Thing do
+    #       it "does something" do
+    #       end
+    #     end
+    #
+    # The object returned by `describe Thing` is a subclass of ExampleGroup.
+    # The object returned by `it "does something"` is an instance of Example,
+    # which serves as a wrapper for an instance of the ExampleGroup in which it
+    # is declared.
     class ExampleGroup
       extend  MetadataHashBuilder::WithDeprecationWarning
       extend  Extensions::ModuleEvalWithArgs
-      extend  Subject::ClassMethods
+      extend  Subject::ExampleGroupMethods
       extend  Hooks
 
       include Extensions::InstanceEvalWithArgs
-      include Subject::InstanceMethods
+      include Subject::ExampleMethods
       include Pending
       include Let
 
-      attr_accessor :example
-
-      def running_example
-        RSpec.deprecate("running_example", "example")
-        example
-      end
-
+      # @private
       def self.world
         RSpec.world
       end
 
+      # @private
       def self.register
         world.register(self)
       end
 
       class << self
+        # @private
         def self.delegate_to_metadata(*names)
           names.each do |name|
             define_method name do
@@ -35,16 +43,18 @@ module RSpec
           end
         end
 
-        delegate_to_metadata :description, :describes, :file_path
+        delegate_to_metadata :description, :described_class, :file_path
         alias_method :display_name, :description
-        alias_method :described_class, :describes
+        # @private
+        alias_method :describes, :described_class
       end
 
+      # @private
       def self.define_example_method(name, extra_options={})
         module_eval(<<-END_RUBY, __FILE__, __LINE__)
           def self.#{name}(desc=nil, *args, &block)
             options = build_metadata_hash_from(args)
-            options.update(:pending => true) unless block
+            options.update(:pending => RSpec::Core::Pending::NOT_YET_IMPLEMENTED) unless block
             options.update(#{extra_options.inspect})
             examples << RSpec::Core::Example.new(self, desc, options, block)
             examples.last
@@ -53,31 +63,27 @@ module RSpec
       end
 
       define_example_method :example
+      define_example_method :it
+      define_example_method :specify
+
+      define_example_method :focused,  :focused => true, :focus => true
+      define_example_method :focus,    :focused => true, :focus => true
+
+      define_example_method :pending,  :pending => true
+      define_example_method :xexample, :pending => 'Temporarily disabled with xexample'
+      define_example_method :xit,      :pending => 'Temporarily disabled with xit'
+      define_example_method :xspecify, :pending => 'Temporarily disabled with xspecify'
 
       class << self
         alias_method :alias_example_to, :define_example_method
       end
 
-      alias_example_to :it
-      alias_example_to :specify
-
-      alias_example_to :pending,  :pending => true
-      alias_example_to :xexample, :pending => true
-      alias_example_to :xit,      :pending => true
-      alias_example_to :xspecify, :pending => true
-
-      alias_example_to :focused,  :focused => true, :focus => true
-      alias_example_to :focus,    :focused => true, :focus => true
-
+      # @private
       def self.define_nested_shared_group_method(new_name, report_label=nil)
         module_eval(<<-END_RUBY, __FILE__, __LINE__)
           def self.#{new_name}(name, *args, &customization_block)
-            shared_block = find_shared("examples", name)
-            raise "Could not find shared examples \#{name.inspect}" unless shared_block
-
             group = describe("#{report_label || "it should behave like"} \#{name}") do
-              module_eval_with_args(*args, &shared_block)
-              module_eval(&customization_block) if customization_block
+              find_and_eval_shared("examples", name, *args, &customization_block)
             end
             group.metadata[:shared_group_name] = name
             group
@@ -93,45 +99,82 @@ module RSpec
 
       alias_it_should_behave_like_to :it_behaves_like, "behaves like"
 
-      def self.include_context(name)
-        module_eval(&find_shared("context", name))
+      # Includes shared content declared with `name`.
+      #
+      # @see SharedExampleGroup
+      def self.include_context(name, *args)
+        block_given? ? block_not_supported("context") : find_and_eval_shared("context", name, *args)
+      end
+
+      # Includes shared content declared with `name`.
+      #
+      # @see SharedExampleGroup
+      def self.include_examples(name, *args)
+        block_given? ? block_not_supported("examples") : find_and_eval_shared("examples", name, *args)
       end
 
-      def self.include_examples(name)
-        module_eval(&find_shared("examples", name))
+      # @private
+      def self.block_not_supported(label)
+        warn("Customization blocks not supported for include_#{label}.  Use it_behaves_like instead.")
       end
 
-      def self.find_shared(label, name)
-        if world.shared_example_groups.has_key?(name)
-          world.shared_example_groups[name]
-        else
-          raise ArgumentError, "Could not find shared #{label} #{name.inspect}"
-        end          
+      # @private
+      def self.find_and_eval_shared(label, name, *args, &customization_block)
+        raise ArgumentError, "Could not find shared #{label} #{name.inspect}" unless
+          shared_block = world.shared_example_groups[name]
+
+        module_eval_with_args(*args, &shared_block)
+        module_eval(&customization_block) if customization_block
       end
 
+      # @private
       def self.examples
         @examples ||= []
       end
-      
+
+      # @private
       def self.filtered_examples
         world.filtered_examples[self]
       end
 
+      # @private
       def self.descendant_filtered_examples
         @descendant_filtered_examples ||= filtered_examples + children.inject([]){|l,c| l + c.descendant_filtered_examples}
       end
 
+      # The [Metadata](Metadata) object associated with this group.
       # @see Metadata
       def self.metadata
         @metadata if defined?(@metadata)
       end
 
-      # @api private
+      # @private
       # @return [Metadata] belonging to the parent of a nested [ExampleGroup](ExampleGroup)
       def self.superclass_metadata
         @superclass_metadata ||= self.superclass.respond_to?(:metadata) ? self.superclass.metadata : nil
       end
 
+      # Generates a subclass of this example group which inherits
+      # everything except the examples themselves.
+      #
+      # ## Examples
+      #
+      #     describe "something" do # << This describe method is defined in
+      #                             # << RSpec::Core::DSL, included in the
+      #                             # << global namespace
+      #       before do
+      #         do_something_before
+      #       end
+      #
+      #       let(:thing) { Thing.new }
+      #
+      #       describe "attribute (of something)" do
+      #         # examples in the group get the before hook
+      #         # declared above, and can access `thing`
+      #       end
+      #     end
+      #
+      # @see DSL#describe
       def self.describe(*args, &example_group_block)
         @_subclass_count ||= 0
         @_subclass_count += 1
@@ -151,6 +194,7 @@ module RSpec
         alias_method :context, :describe
       end
 
+      # @private
       def self.subclass(parent, args, &example_group_block)
         subclass = Class.new(parent)
         subclass.set_it_up(*args)
@@ -158,22 +202,27 @@ module RSpec
         subclass
       end
 
+      # @private
       def self.children
         @children ||= [].extend(Extensions::Ordered)
       end
 
+      # @private
       def self.descendants
         @_descendants ||= [self] + children.inject([]) {|list, c| list + c.descendants}
       end
 
+      # @private
       def self.ancestors
         @_ancestors ||= super().select {|a| a < RSpec::Core::ExampleGroup}
       end
 
+      # @private
       def self.top_level?
         @top_level ||= superclass == ExampleGroup
       end
 
+      # @private
       def self.ensure_example_groups_are_configured
         unless defined?(@@example_groups_configured)
           RSpec.configuration.configure_mock_framework
@@ -182,6 +231,7 @@ module RSpec
         end
       end
 
+      # @private
       def self.set_it_up(*args)
         # Ruby 1.9 has a bug that can lead to infinite recursion and a
         # SystemStackError if you include a module in a superclass after
@@ -199,22 +249,26 @@ module RSpec
         world.configure_group(self)
       end
 
+      # @private
       def self.before_all_ivars
         @before_all_ivars ||= {}
       end
 
+      # @private
       def self.store_before_all_ivars(example_group_instance)
         return if example_group_instance.instance_variables.empty?
-        example_group_instance.instance_variables.each { |ivar| 
+        example_group_instance.instance_variables.each { |ivar|
           before_all_ivars[ivar] = example_group_instance.instance_variable_get(ivar)
         }
       end
 
+      # @private
       def self.assign_before_all_ivars(ivars, example_group_instance)
         return if ivars.empty?
         ivars.each { |ivar, val| example_group_instance.instance_variable_set(ivar, val) }
       end
 
+      # @private
       def self.run_before_all_hooks(example_group_instance)
         return if descendant_filtered_examples.empty?
         assign_before_all_ivars(superclass.before_all_ivars, example_group_instance)
@@ -223,6 +277,7 @@ module RSpec
         store_before_all_ivars(example_group_instance)
       end
 
+      # @private
       def self.run_around_each_hooks(example, initial_procsy)
         example.around_hooks.reverse.inject(initial_procsy) do |procsy, around_hook|
           Example.procsy(procsy.metadata) do
@@ -231,16 +286,19 @@ module RSpec
         end
       end
 
+      # @private
       def self.run_before_each_hooks(example)
         world.run_hook_filtered(:before, :each, self, example.example_group_instance, example)
         ancestors.reverse.each { |ancestor| ancestor.run_hook(:before, :each, example.example_group_instance) }
       end
 
+      # @private
       def self.run_after_each_hooks(example)
         ancestors.each { |ancestor| ancestor.run_hook(:after, :each, example.example_group_instance) }
         world.run_hook_filtered(:after, :each, self, example.example_group_instance, example)
       end
 
+      # @private
       def self.run_after_all_hooks(example_group_instance)
         return if descendant_filtered_examples.empty?
         assign_before_all_ivars(before_all_ivars, example_group_instance)
@@ -261,10 +319,12 @@ An error occurred in an after(:all) hook.
         world.run_hook_filtered(:after, :all, self, example_group_instance)
       end
 
+      # @private
       def self.around_hooks_for(example)
         world.find_hook(:around, :each, self, example) + ancestors.reverse.inject([]){|l,a| l + a.find_hook(:around, :each, self, example)}
       end
 
+      # Runs all the examples in this group
       def self.run(reporter)
         if RSpec.wants_to_quit
           RSpec.clear_remaining_example_groups if top_level?
@@ -286,6 +346,19 @@ An error occurred in an after(:all) hook.
         end
       end
 
+      # @private
+      def self.run_examples(reporter)
+        filtered_examples.ordered.map do |example|
+          next if RSpec.wants_to_quit
+          instance = new
+          set_ivars(instance, before_all_ivars)
+          succeeded = example.run(instance, reporter)
+          RSpec.wants_to_quit = true if fail_fast? && !succeeded
+          succeeded
+        end.all?
+      end
+
+      # @private
       def self.fail_filtered_examples(exception, reporter)
         filtered_examples.each { |example| example.fail_with_exception(reporter, exception) }
 
@@ -297,49 +370,66 @@ An error occurred in an after(:all) hook.
         false
       end
 
+      # @private
       def self.fail_fast?
         RSpec.configuration.fail_fast?
       end
 
-      def self.run_examples(reporter)
-        filtered_examples.ordered.map do |example|
-          next if RSpec.wants_to_quit
-          instance = new
-          set_ivars(instance, before_all_ivars)
-          succeeded = example.run(instance, reporter)
-          RSpec.wants_to_quit = true if fail_fast? && !succeeded
-          succeeded
-        end.all?
-      end
-
-      # @api private
+      # @private
       def self.any_apply?(filters)
         metadata.any_apply?(filters)
       end
 
-      # @api private
+      # @private
       def self.all_apply?(filters)
         metadata.all_apply?(filters)
       end
 
+      # @private
       def self.declaration_line_numbers
         @declaration_line_numbers ||= [metadata[:example_group][:line_number]] +
           examples.collect {|e| e.metadata[:line_number]} +
           children.inject([]) {|l,c| l + c.declaration_line_numbers}
       end
 
+      # @private
       def self.top_level_description
         ancestors.last.description
       end
 
+      # @private
       def self.set_ivars(instance, ivars)
         ivars.each {|name, value| instance.instance_variable_set(name, value)}
       end
 
+      # @attr_reader
+      # Returns the [Example](Example) object that wraps this instance of
+      # `ExampleGroup`
+      attr_accessor :example
+
+      # @deprecated use [example](ExampleGroup#example-instance_method)
+      def running_example
+        RSpec.deprecate("running_example", "example")
+        example
+      end
+
+      # Returns the class or module passed to the `describe` method (or alias).
+      # Returns nil if the subject is not a class or module.
+      # @example
+      #     describe Thing do
+      #       it "does something" do
+      #         described_class == Thing
+      #       end
+      #     end
+      #
+      #
       def described_class
         self.class.described_class
       end
 
+      # @private
+      # instance_evals the block, capturing and reporting an exception if
+      # raised
       def instance_eval_with_rescue(&hook)
         begin
           instance_eval(&hook)