rspec-core 3.0.0.beta1 → 3.0.0.beta2

data/lib/rspec/core/configuration_options.rb

@@ -5,31 +5,24 @@ module RSpec
   module Core
     # @private
     class ConfigurationOptions
-      attr_reader :options
-
       def initialize(args)
-        @args = args.map {|a|
-          a.sub("default_path", "default-path").sub("line_number",  "line-number")
-        }
+        @args = args.dup
       end
 
       def configure(config)
         config.filter_manager = filter_manager
 
-        config.libs = options[:libs] || []
-        config.setup_load_path_and_require(options[:requires] || [])
-
         process_options_into config
         load_formatters_into config
       end
 
-      def parse_options
-        @options = (file_options << command_line_options << env_options).
+      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 {|h, opts|
+          inject(:libs => [], :requires => []) {|h, opts|
             h.merge(opts) {|k, oldval, newval|
               [:libs, :requires].include?(k) ? oldval + newval : newval
             }
@@ -51,24 +44,45 @@ module RSpec
         :line_numbers, :full_description, :full_backtrace, :tty
       ].to_set
 
-      UNPROCESSABLE_OPTIONS = [:libs, :formatters, :requires].to_set
+      UNPROCESSABLE_OPTIONS = [:formatters].to_set
 
       def force?(key)
         !UNFORCED_OPTIONS.include?(key)
       end
 
-      def order(keys, *ordered)
-        ordered.reverse.each do |key|
+      def order(keys)
+        OPTIONS_ORDER.reverse.each do |key|
           keys.unshift(key) if keys.delete(key)
         end
         keys
       end
 
+      OPTIONS_ORDER = [
+        # load paths depend on nothing, but must be set before `requires`
+        # to support load-path-relative requires.
+        :libs,
+
+        # `files_or_directories_to_run` uses `default_path` so it must be
+        # set before it.
+        :default_path,
+
+        # must be set before `requires` to support checking `config.files_to_run`
+        # from within `spec_helper.rb` when a `-rspec_helper` option is used.
+        :files_or_directories_to_run,
+
+        # In general, we want to require the specified files as early as possible.
+        # The `--require` option is specifically intended to allow early requires.
+        # For later requires, they can just put the require in their spec files, but
+        # `--require` provides a unique opportunity for users to instruct RSpec to
+        # load an extension file early for maximum flexibility.
+        :requires
+      ]
+
       def process_options_into(config)
         opts = options.reject { |k, _| UNPROCESSABLE_OPTIONS.include? k }
 
-        order(opts.keys, :default_path, :pattern).each do |key|
-          force?(key) ? config.force(key => opts[key]) : config.send("#{key}=", opts[key])
+        order(opts.keys).each do |key|
+          force?(key) ? config.force(key => opts[key]) : config.__send__("#{key}=", opts[key])
         end
       end
 
@@ -81,11 +95,11 @@ module RSpec
       end
 
       def env_options
-        ENV["SPEC_OPTS"] ? Parser.parse!(Shellwords.split(ENV["SPEC_OPTS"])) : {}
+        ENV["SPEC_OPTS"] ? Parser.parse(Shellwords.split(ENV["SPEC_OPTS"])) : {}
       end
 
       def command_line_options
-        @command_line_options ||= Parser.parse!(@args).merge :files_or_directories_to_run => @args
+        @command_line_options ||= Parser.parse(@args).merge :files_or_directories_to_run => @args
       end
 
       def custom_options

data/lib/rspec/core/dsl.rb

@@ -1,26 +1,88 @@
 module RSpec
   module Core
-    # Adds the `describe` method to the top-level namespace.
+    # DSL defines methods to group examples, most notably `describe`,
+    # and exposes them as class methods of {RSpec}. They can also be
+    # exposed globally (on `main` and instances of `Module`) through
+    # the {Configuration} option `expose_dsl_globally`.
+    #
+    # By default the methods `describe`, `context` and `example_group`
+    # are exposed. These methods define a named context for one or
+    # more examples. The given block is evaluated in the context of
+    # a generated subclass of {RSpec::Core::ExampleGroup}
+    #
+    # ## Examples:
+    #
+    #     RSpec.describe "something" do
+    #       context "when something is a certain way" do
+    #         it "does something" do
+    #           # example code goes here
+    #         end
+    #       end
+    #     end
+    #
+    # @see ExampleGroup
+    # @see ExampleGroup.example_group
     module DSL
-      # Generates a subclass of {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
+      # @private
+      def self.example_group_aliases
+        @example_group_aliases ||= []
       end
+
+      # @private
+      def self.exposed_globally?
+        @exposed_globally ||= false
+      end
+
+      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
+        end
+
+        expose_example_group_alias_globally(name) if exposed_globally?
+      end
+
+      class << self
+        # @private
+        attr_accessor :top_level
+      end
+
+      # Add's the describe method to Module and the top level binding
+      def self.expose_globally!
+        return if exposed_globally?
+
+        example_group_aliases.each do |method_name|
+          expose_example_group_alias_globally(method_name)
+        end
+
+        @exposed_globally = true
+      end
+
+      def self.remove_globally!
+        return unless exposed_globally?
+
+        example_group_aliases.each do |method_name|
+          change_global_dsl { undef_method method_name }
+        end
+
+        @exposed_globally = false
+      end
+
+      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
+
+      def self.change_global_dsl(&changes)
+        (class << top_level; self; end).class_exec(&changes)
+        Module.class_exec(&changes)
+      end
+
     end
   end
 end
 
-extend RSpec::Core::DSL
-Module.send(:include, RSpec::Core::DSL)
-
+# capture main without an eval
+::RSpec::Core::DSL.top_level = self

data/lib/rspec/core/example.rb

@@ -41,15 +41,18 @@ module RSpec
         keys.each { |key| define_method(key) { @metadata[key] } }
       end
 
-      delegate_to_metadata :full_description, :execution_result, :file_path, :pending, :location
+      delegate_to_metadata :execution_result, :file_path, :full_description,
+                           :location, :pending, :skip
 
       # Returns the string submitted to `example` or its aliases (e.g.
-      # `specify`, `it`, etc).  If no string is submitted (e.g. `it { should
+      # `specify`, `it`, etc).  If no string is submitted (e.g. `it { is_expected.to
       # do_something }`) it returns the message generated by the matcher if
       # there is one, otherwise returns a message including the location of the
       # example.
       def description
-        description = metadata[:description].to_s.empty? ? "example at #{location}" : metadata[:description]
+        description = metadata[:description].to_s.empty? ?
+          "example at #{location}" :
+          metadata[:description]
         RSpec.configuration.format_docstrings_block.call(description)
       end
 
@@ -71,6 +74,10 @@ module RSpec
       # running this example.
       attr_reader :example_group_instance
 
+      # @attr_accessor
+      # @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)
@@ -80,7 +87,7 @@ module RSpec
         @example_group_class, @options, @example_block = example_group_class, metadata, example_block
         @metadata  = @example_group_class.metadata.for_example(description, metadata)
         @example_group_instance = @exception = nil
-        @pending_declared_in_example = false
+        @clock = RSpec::Core::Time
       end
 
       # @deprecated access options via metadata instead
@@ -95,6 +102,7 @@ module RSpec
       end
 
       alias_method :pending?, :pending
+      alias_method :skipped?, :skip
 
       # @api private
       # instance_evals the block passed to the constructor in the context of
@@ -107,13 +115,24 @@ module RSpec
         start(reporter)
 
         begin
-          unless pending || RSpec.configuration.dry_run?
+          if skipped?
+            Pending.mark_pending! self, skip
+          elsif !RSpec.configuration.dry_run?
             with_around_each_hooks do
               begin
                 run_before_each
                 @example_group_instance.instance_exec(self, &@example_block)
-              rescue Pending::PendingDeclaredInExample => e
-                @pending_declared_in_example = e.message
+
+                if pending?
+                  Pending.mark_fixed! self
+
+                  raise Pending::PendingExampleFixedError,
+                    'Expected example to fail since it is pending, but it passed.',
+                    metadata[:caller]
+                end
+              rescue Pending::SkipDeclaredInExample
+                # no-op, required metadata has already been set by the `skip`
+                # method.
               rescue Exception => e
                 set_exception(e)
               ensure
@@ -190,7 +209,7 @@ module RSpec
 
       # @private
       def around_each_hooks
-        @around_each_hooks ||= example_group.around_each_hooks_for(self)
+        @around_each_hooks ||= example_group.hooks.around_each_hooks_for(self)
       end
 
       # @private
@@ -198,20 +217,24 @@ 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 @exception && context != :dont_print
-          # 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
+        if pending?
+          metadata[:execution_result][:pending_exception] = exception
+        else
+          if @exception && context != :dont_print
+            # 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
 
-An error occurred #{context}
-  #{exception.class}: #{exception.message}
-  occurred at #{exception.backtrace.first}
+  An error occurred #{context}
+    #{exception.class}: #{exception.message}
+    occurred at #{exception.backtrace.first}
 
-          EOS
-          RSpec.configuration.reporter.message(msg)
-        end
+            EOS
+            RSpec.configuration.reporter.message(msg)
+          end
 
-        @exception ||= exception
+          @exception ||= exception
+        end
       end
 
       # @private
@@ -224,6 +247,16 @@ An error occurred #{context}
         finish(reporter)
       end
 
+      # @private
+      #
+      # Used internally to skip without actually executing the example when
+      # skip is used in before(:all)
+      def skip_with_exception(reporter, exception)
+        start(reporter)
+        Pending.mark_skipped! self, exception.argument
+        finish(reporter)
+      end
+
       # @private
       def instance_exec_with_rescue(context = nil, &block)
         @example_group_instance.instance_exec_with_rescue(self, context, &block)
@@ -240,7 +273,7 @@ An error occurred #{context}
         if around_each_hooks.empty?
           yield
         else
-          @example_group_class.run_around_each_hooks(self, Procsy.new(metadata, &block))
+          @example_group_class.hooks.run(:around, :each, self, Procsy.new(metadata, &block))
         end
       rescue Exception => e
         set_exception(e, "in an around(:each) hook")
@@ -248,20 +281,18 @@ An error occurred #{context}
 
       def start(reporter)
         reporter.example_started(self)
-        record :started_at => RSpec::Core::Time.now
+        record :started_at => clock.now
       end
 
       def finish(reporter)
+        pending_message = metadata[:execution_result][:pending_message]
+
         if @exception
           record_finished 'failed', :exception => @exception
           reporter.example_failed self
           false
-        elsif @pending_declared_in_example
-          record_finished 'pending', :pending_message => @pending_declared_in_example
-          reporter.example_pending self
-          true
-        elsif pending
-          record_finished 'pending', :pending_message => String === pending ? pending : Pending::NO_REASON_GIVEN
+        elsif pending_message
+          record_finished 'pending', :pending_message => pending_message
           reporter.example_pending self
           true
         else
@@ -272,17 +303,21 @@ An error occurred #{context}
       end
 
       def record_finished(status, results={})
-        finished_at = RSpec::Core::Time.now
-        record results.merge(:status => status, :finished_at => finished_at, :run_time => (finished_at - execution_result[:started_at]).to_f)
+        finished_at = clock.now
+        record results.merge(
+          :status      => status,
+          :finished_at => finished_at,
+          :run_time    => (finished_at - execution_result[:started_at]).to_f
+        )
       end
 
       def run_before_each
         @example_group_instance.setup_mocks_for_rspec
-        @example_group_class.run_before_each_hooks(self)
+        @example_group_class.hooks.run(:before, :each, self)
       end
 
       def run_after_each
-        @example_group_class.run_after_each_hooks(self)
+        @example_group_class.hooks.run(:after, :each, self)
         verify_mocks
       rescue Exception => e
         set_exception(e, "in an after(:each) hook")
@@ -293,20 +328,36 @@ An error occurred #{context}
       def verify_mocks
         @example_group_instance.verify_mocks_for_rspec
       rescue Exception => e
-        set_exception(e, :dont_print)
+        if metadata[:execution_result][:pending_message]
+          metadata[:execution_result][:pending_fixed] = false
+          metadata[:pending] = true
+          @exception = nil
+        else
+          set_exception(e, :dont_print)
+        end
       end
 
       def assign_generated_description
         return unless RSpec.configuration.expecting_with_rspec?
-        if metadata[:description_args].empty? and !pending?
+
+        if metadata[:description_args].empty?
           metadata[:description_args] << RSpec::Matchers.generated_description
         end
+
         RSpec::Matchers.clear_generated_description
       end
 
       def record(results={})
         execution_result.update(results)
       end
+
+      def skip_message
+        if String === skip
+          skip
+        else
+          Pending::NO_REASON_GIVEN
+        end
+      end
     end
   end
 end

data/lib/rspec/core/example_group.rb

@@ -59,13 +59,41 @@ module RSpec
           define_method(name) do |*all_args, &block|
             desc, *args = *all_args
             options = Metadata.build_hash_from(args)
-            options.update(:pending => RSpec::Core::Pending::NOT_YET_IMPLEMENTED) unless block
+            options.update(:skip => RSpec::Core::Pending::NOT_YET_IMPLEMENTED) unless block
             options.update(extra_options)
+
+            # Metadata inheritance normally happens in `Example#initialize`,
+            # but for `:pending` specifically we need it earlier.
+            pending_metadata = options[:pending] || metadata[:pending]
+
+            if pending_metadata
+              options, block = ExampleGroup.pending_metadata_and_block_for(
+                options.merge(:pending => pending_metadata),
+                block
+              )
+            end
+
             examples << RSpec::Core::Example.new(self, desc, options, block)
             examples.last
           end
         end
 
+        def pending_metadata_and_block_for(options, block)
+          if String === options[:pending]
+            reason = options[:pending]
+          else
+            options[:pending] = true
+            reason = RSpec::Core::Pending::NO_REASON_GIVEN
+          end
+
+          # This will fail if no block is provided, which is effectively the
+          # same as failing the example so it will be marked correctly as
+          # pending.
+          callback = Proc.new { pending(reason); instance_exec(&block) }
+
+          return options, callback
+        end
+
         # Defines an example within a group.
         # @example
         #   example do
@@ -100,18 +128,21 @@ module RSpec
         # @see example
         define_example_method :fit,     :focused => true, :focus => true
 
-        # Shortcut to define an example with :pending => true
+        # Shortcut to define an example with :skip => 'Temporarily skipped with xexample'
         # @see example
-        define_example_method :pending,  :pending => true
-        # Shortcut to define an example with :pending => 'Temporarily disabled with xexample'
+        define_example_method :xexample, :skip => 'Temporarily skipped with xexample'
+        # Shortcut to define an example with :skip => 'Temporarily skipped with xit'
         # @see example
-        define_example_method :xexample, :pending => 'Temporarily disabled with xexample'
-        # Shortcut to define an example with :pending => 'Temporarily disabled with xit'
+        define_example_method :xit,      :skip => 'Temporarily skipped with xit'
+        # Shortcut to define an example with :skip => 'Temporarily skipped with xspecify'
         # @see example
-        define_example_method :xit,      :pending => 'Temporarily disabled with xit'
-        # Shortcut to define an example with :pending => 'Temporarily disabled with xspecify'
+        define_example_method :xspecify, :skip => 'Temporarily skipped with xspecify'
+        # Shortcut to define an example with :skip => true
         # @see example
-        define_example_method :xspecify, :pending => 'Temporarily disabled with xspecify'
+        define_example_method :skip,     :skip => true
+        # Shortcut to define an example with :pending => true
+        # @see example
+        define_example_method :pending,  :pending => true
 
         # Works like `alias_method :name, :example` with the added benefit of
         # assigning default metadata to the generated example.
@@ -124,13 +155,30 @@ module RSpec
           (class << self; self; end).define_example_method name, extra
         end
 
+        # @private
+        # @macro [attach] alias_example_group_to
+        #   @scope class
+        #   @param [String] docstring The example group doc string
+        #   @param [Hash] metadata Additional metadata to attach to the example group
+        #   @yield The example group definition
+        def alias_example_group_to(name, metadata={})
+          (class << self; self; end).__send__(:define_method, name) do |*args, &block|
+            combined_metadata = metadata.dup
+            combined_metadata.merge!(args.pop) if args.last.is_a? Hash
+            args << combined_metadata
+            example_group(*args, &block)
+          end
+
+          RSpec::Core::DSL.expose_example_group_alias(name)
+        end
+
         # @private
         # @macro [attach] define_nested_shared_group_method
         #
         #   @see SharedExampleGroup
         def self.define_nested_shared_group_method(new_name, report_label="it should behave like")
           define_method(new_name) do |name, *args, &customization_block|
-            group = describe("#{report_label} #{name}") do
+            group = example_group("#{report_label} #{name}") do
               find_and_eval_shared("examples", name, *args, &customization_block)
             end
             group.metadata[:shared_group_name] = name
@@ -218,7 +266,7 @@ module RSpec
       #
       #     describe "something" do # << This describe method is defined in
       #                             # << RSpec::Core::DSL, included in the
-      #                             # << global namespace
+      #                             # << global namespace (optional)
       #       before do
       #         do_something_before
       #       end
@@ -232,7 +280,7 @@ module RSpec
       #     end
       #
       # @see DSL#describe
-      def self.describe(*args, &example_group_block)
+      def self.example_group(*args, &example_group_block)
         args << {} unless args.last.is_a?(Hash)
         args.last.update(:example_group_block => example_group_block)
 
@@ -241,9 +289,31 @@ module RSpec
         child
       end
 
-      class << self
-        alias_method :context, :describe
-      end
+      # An alias of `example_group`. Generally used when grouping
+      # examples by a thing you are describing (e.g. an object, class or method).
+      # @see example_group
+      alias_example_group_to :describe
+
+      # An alias of `example_group`. Generally used when grouping examples
+      # contextually.
+      # @see example_group
+      alias_example_group_to :context
+
+      # Shortcut to temporarily make an example group pending.
+      # @see example_group
+      alias_example_group_to :xdescribe, :skip => "Temporarily skipped with xdescribe"
+
+      # Shortcut to temporarily make an example group pending.
+      # @see example_group
+      alias_example_group_to :xcontext,  :skip => "Temporarily skipped with xcontext"
+
+      # Shortcut to define an example group with `:focus` => true
+      # @see example_group
+      alias_example_group_to :fdescribe, :focus => true, :focused => true
+
+      # Shortcut to define an example group with `:focus` => true
+      # @see example_group
+      alias_example_group_to :fcontext,  :focus => true, :focused => true
 
       # @private
       def self.subclass(parent, args, &example_group_block)
@@ -324,47 +394,27 @@ module RSpec
         }
       end
 
-      # @private
-      def self.assign_before_all_ivars(ivars, example_group_instance)
-        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?
         begin
-          assign_before_all_ivars(superclass.before_all_ivars, example_group_instance)
+          set_ivars(example_group_instance, superclass.before_all_ivars)
 
           AllHookMemoizedHash::Before.isolate_for_all_hook(example_group_instance) do
-            run_hook(:before, :all, example_group_instance)
+            hooks.run(:before, :all, example_group_instance)
           end
         ensure
           store_before_all_ivars(example_group_instance)
         end
       end
 
-      # @private
-      def self.run_around_each_hooks(example, initial_procsy)
-        run_hook(:around, :each, example, initial_procsy)
-      end
-
-      # @private
-      def self.run_before_each_hooks(example)
-        run_hook(:before, :each, example)
-      end
-
-      # @private
-      def self.run_after_each_hooks(example)
-        run_hook(:after, :each, 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)
+        set_ivars(example_group_instance, before_all_ivars)
 
         AllHookMemoizedHash::After.isolate_for_all_hook(example_group_instance) do
-          run_hook(:after, :all, example_group_instance)
+          hooks.run(:after, :all, example_group_instance)
         end
       end
 
@@ -381,9 +431,11 @@ module RSpec
           result_for_this_group = run_examples(reporter)
           results_for_descendants = ordering_strategy.order(children).map { |child| child.run(reporter) }.all?
           result_for_this_group && results_for_descendants
+        rescue Pending::SkipDeclaredInExample => ex
+          for_filtered_examples(reporter) {|example| example.skip_with_exception(reporter, ex) }
         rescue Exception => ex
           RSpec.wants_to_quit = true if fail_fast?
-          fail_filtered_examples(ex, reporter)
+          for_filtered_examples(reporter) {|example| example.fail_with_exception(reporter, ex) }
         ensure
           run_after_all_hooks(new)
           before_all_ivars.clear
@@ -420,12 +472,12 @@ module RSpec
       end
 
       # @private
-      def self.fail_filtered_examples(exception, reporter)
-        filtered_examples.each { |example| example.fail_with_exception(reporter, exception) }
+      def self.for_filtered_examples(reporter, &block)
+        filtered_examples.each(&block)
 
         children.each do |child|
           reporter.example_group_started(child)
-          child.fail_filtered_examples(exception, reporter)
+          child.for_filtered_examples(reporter, &block)
           reporter.example_group_finished(child)
         end
         false