rspec-core 2.7.1 → 2.8.0.rc1

data/lib/rspec/core/configuration_options.rb

@@ -1,6 +1,7 @@
+require 'erb'
+
 module RSpec
   module Core
-
     class ConfigurationOptions
       attr_reader :options
 
@@ -9,68 +10,39 @@ module RSpec
       end
 
       def configure(config)
-        keys = order(options.keys, :libs, :requires, :default_path, :pattern)
-
-        formatters = options[:formatters] if keys.delete(:formatters)
+        formatters = options.delete(:formatters)
 
-        config.exclusion_filter.merge! options[:exclusion_filter] if keys.delete(:exclusion_filter)
+        config.filter_manager = filter_manager
 
-        keys.each do |key|
-          config.send("#{key}=", options[key]) if config.respond_to?("#{key}=")
+        order(options.keys, :libs, :requires, :default_path, :pattern).each do |key|
+          force?(key) ? config.force(key => options[key]) : config.send("#{key}=", options[key]) 
         end
 
         formatters.each {|pair| config.add_formatter(*pair) } if formatters
       end
 
-      def drb_argv
-        argv = []
-        argv << "--color"        if options[:color_enabled]
-        argv << "--profile"      if options[:profile_examples]
-        argv << "--backtrace"    if options[:full_backtrace]
-        argv << "--tty"          if options[:tty]
-        argv << "--fail-fast"    if options[:fail_fast]
-        argv << "--options"      << options[:custom_options_file]     if options[:custom_options_file]
-        if 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" << options[:full_description].source.delete('\\')
-        end
-        if options[:line_numbers]
-          argv += options[:line_numbers].inject([]){|a,l| a << "--line_number" << l}
-        end
-        if options[:filter]
-          options[:filter].each_pair do |k, v|
-            argv << "--tag" << k.to_s
-          end
-        end
-        if options[:exclusion_filter]
-          options[:exclusion_filter].each_pair do |k, v|
-            argv << "--tag" << "~#{k.to_s}"
-          end
-        end
-        if options[:formatters]
-          options[:formatters].each do |pair|
-            argv << "--format" << pair[0]
-            argv << "--out" << pair[1] if pair[1]
-          end
-        end
-        (options[:libs] || []).each do |path|
-          argv << "-I" << path
-        end
-        (options[:requires] || []).each do |path|
-          argv << "--require" << path
+      def parse_options
+        @options ||= extract_filters_from(*all_configs).inject do |merged, pending|
+          merged.merge(pending)
         end
-        argv + options[:files_or_directories_to_run]
       end
 
-      def parse_options
-        @options ||= [file_options, command_line_options, env_options].inject {|merged, o| merged.merge o}
+      def drb_argv
+        DrbOptions.new(options, filter_manager).options
+      end
+
+      def filter_manager
+        @filter_manager ||= FilterManager.new
       end
 
     private
 
+      NON_FORCED_OPTIONS = [:debug, :order, :seed, :requires, :libs, :files_or_directories_to_run, :line_numbers, :full_description]
+
+      def force?(key)
+        !NON_FORCED_OPTIONS.include?(key)
+      end
+
       def order(keys, *ordered)
         ordered.reverse.each do |key|
           keys.unshift(key) if keys.delete(key)
@@ -78,8 +50,19 @@ module RSpec
         keys
       end
 
+      def extract_filters_from(*configs)
+        configs.compact.each do |config|
+          filter_manager.include config.delete(:inclusion_filter) if config.has_key?(:inclusion_filter)
+          filter_manager.exclude config.delete(:exclusion_filter) if config.has_key?(:exclusion_filter)
+        end
+      end
+
+      def all_configs
+        @all_configs ||= file_options << command_line_options << env_options
+      end
+
       def file_options
-        custom_options_file ? custom_options : global_options.merge(local_options)
+        custom_options_file ? [custom_options] : [global_options, local_options]
       end
 
       def env_options
@@ -113,8 +96,7 @@ module RSpec
       end
 
       def options_file_as_erb_string(path)
-        require 'erb'
-        ERB.new(IO.read(path)).result(binding)
+        ERB.new(File.read(path)).result(binding)
       end
 
       def custom_options_file
@@ -133,7 +115,6 @@ module RSpec
           nil
         end
       end
-
     end
   end
 end

data/lib/rspec/core/deprecation.rb

@@ -1,6 +1,8 @@
 module RSpec
 
   class << self
+    # @api private
+    #
     # Used internally to print deprecation warnings
     def deprecate(method, alternate_method=nil, version=nil)
       version_string = version ? "rspec-#{version}" : "a future version of RSpec"
@@ -25,6 +27,8 @@ ADDITIONAL
       warn_deprecation(message)
     end
 
+    # @api private
+    #
     # Used internally to print deprecation warnings
     def warn_deprecation(message)
       send :warn, message

data/lib/rspec/core/drb_options.rb

@@ -0,0 +1,72 @@
+# 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]
+
+    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)
+
+    argv + @submitted_options[:files_or_directories_to_run]
+  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_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_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_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

data/lib/rspec/core/example.rb

@@ -2,12 +2,6 @@ module RSpec
   module Core
     class Example
 
-      attr_reader :metadata, :options, :example_group_instance
-
-      # Returns the first exception raised, if any, in the context of running
-      # this example.
-      attr_reader :exception
-
       def self.delegate_to_metadata(*keys)
         keys.each do |key|
           define_method(key) {@metadata[key]}
@@ -16,6 +10,24 @@ module RSpec
 
       delegate_to_metadata :description, :full_description, :execution_result, :file_path, :pending, :location
 
+      # @attr_reader
+      #
+      # Returns the first exception raised in the context of running this
+      # example (nil if no exception is raised)
+      attr_reader :exception
+
+      # @attr_reader
+      #
+      # Returns the metadata object associated with this example.
+      attr_reader :metadata
+      
+      # @attr_reader
+      # @api 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)
@@ -23,16 +35,15 @@ module RSpec
         @pending_declared_in_example = false
       end
 
-      def example_group
-        @example_group_class
+      # @deprecated access options via metadata instead
+      def options
+        @options
       end
 
-      def around_hooks
-        @around_hooks ||= example_group.around_hooks_for(self)
-      end
-
-      def all_apply?(filters)
-        @metadata.all_apply?(filters) || @example_group_class.all_apply?(filters)
+      # Returns the example group class that provides the context for running
+      # this example.
+      def example_group
+        @example_group_class
       end
 
       alias_method :pending?, :pending
@@ -76,16 +87,6 @@ module RSpec
         finish(reporter)
       end
 
-      def set_exception(exception)
-        @exception ||= exception
-      end
-
-      def fail_fast(reporter, exception)
-        start(reporter)
-        set_exception(exception)
-        finish(reporter)
-      end
-
       def self.procsy(metadata, &block)
         Proc.new(&block).extend(Procsy).with(metadata)
       end
@@ -103,6 +104,39 @@ module RSpec
         end
       end
 
+      # @api private
+      def all_apply?(filters)
+        @metadata.all_apply?(filters) || @example_group_class.all_apply?(filters)
+      end
+
+      # @api private
+      def around_hooks
+        @around_hooks ||= example_group.around_hooks_for(self)
+      end
+
+      # @api private
+      #
+      # Used internally to set an exception in an after hook, which
+      # captures the exception but doesn't raise it.
+      def set_exception(exception)
+        @exception ||= exception
+      end
+
+      # @api private
+      #
+      # Used internally to set an exception and fail without actually executing
+      # the example when an exception is raised in before(:all).
+      def fail_with_exception(reporter, exception)
+        start(reporter)
+        set_exception(exception)
+        finish(reporter)
+      end
+
+      # @api private
+      def any_apply?(filters)
+        metadata.any_apply?(filters)
+      end
+
     private
 
       def with_around_hooks(&block)

data/lib/rspec/core/example_group.rb

@@ -112,7 +112,7 @@ module RSpec
       def self.examples
         @examples ||= []
       end
-
+      
       def self.filtered_examples
         world.filtered_examples[self]
       end
@@ -121,10 +121,13 @@ module RSpec
         @descendant_filtered_examples ||= filtered_examples + children.inject([]){|l,c| l + c.descendant_filtered_examples}
       end
 
+      # @see Metadata
       def self.metadata
         @metadata if defined?(@metadata)
       end
 
+      # @api 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
@@ -156,7 +159,7 @@ module RSpec
       end
 
       def self.children
-        @children ||= []
+        @children ||= [].extend(Extensions::Ordered)
       end
 
       def self.descendants
@@ -272,7 +275,7 @@ An error occurred in an after(:all) hook.
         begin
           run_before_all_hooks(new)
           result_for_this_group = run_examples(reporter)
-          results_for_descendants = children.map {|child| child.run(reporter)}.all?
+          results_for_descendants = children.ordered.map {|child| child.run(reporter)}.all?
           result_for_this_group && results_for_descendants
         rescue Exception => ex
           fail_filtered_examples(ex, reporter)
@@ -284,7 +287,7 @@ An error occurred in an after(:all) hook.
       end
 
       def self.fail_filtered_examples(exception, reporter)
-        filtered_examples.each { |example| example.fail_fast(reporter, exception) }
+        filtered_examples.each { |example| example.fail_with_exception(reporter, exception) }
 
         children.each do |child|
           reporter.example_group_started(child)
@@ -299,7 +302,7 @@ An error occurred in an after(:all) hook.
       end
 
       def self.run_examples(reporter)
-        filtered_examples.map do |example|
+        filtered_examples.ordered.map do |example|
           next if RSpec.wants_to_quit
           instance = new
           set_ivars(instance, before_all_ivars)
@@ -309,10 +312,12 @@ An error occurred in an after(:all) hook.
         end.all?
       end
 
+      # @api private
       def self.any_apply?(filters)
         metadata.any_apply?(filters)
       end
 
+      # @api private
       def self.all_apply?(filters)
         metadata.all_apply?(filters)
       end

data/lib/rspec/core/extensions.rb

@@ -1,3 +1,4 @@
 require 'rspec/core/extensions/kernel'
 require 'rspec/core/extensions/instance_eval_with_args'
 require 'rspec/core/extensions/module_eval_with_args'
+require 'rspec/core/extensions/ordered'

data/lib/rspec/core/extensions/ordered.rb

@@ -0,0 +1,16 @@
+module RSpec
+  module Core
+    module Extensions
+      module Ordered
+        def ordered
+          if RSpec.configuration.randomize?
+            srand RSpec.configuration.seed
+            sort_by { rand size }
+          else
+            self
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rspec/core/filter_manager.rb

@@ -0,0 +1,170 @@
+module RSpec
+  module Core
+    # Manages the filtering of examples and groups by matching tags declared on
+    # the command line or options files, or filters declared via
+    # `RSpec.configure`, with hash key/values submitted within example group
+    # and/or example declarations. For example, given this declaration:
+    #
+    #     describe Thing, :awesome => true do
+    #       it "does something" do
+    #         # ...
+    #       end
+    #     end
+    #
+    # That group (or any other with `:awesome => true`) would be filtered in
+    # with any of the following commands:
+    #
+    #     rspec --tag awesome:true
+    #     rspec --tag awesome
+    #     rspec -t awesome:true
+    #     rspec -t awesome
+    #
+    # Prefixing the tag names with `~` negates the tags, thus excluding this group with
+    # any of:
+    #
+    #     rspec --tag ~awesome:true
+    #     rspec --tag ~awesome
+    #     rspec -t ~awesome:true
+    #     rspec -t ~awesome
+    #
+    # ## Options files and command line overrides
+    #
+    # Tag declarations can be stored in `.rspec`, `~/.rspec`, or a custom
+    # options file.  This is useful for storing defaults. For example, let's
+    # say you've got some slow specs that you want to suppress most of the
+    # time. You can tag them like this:
+    #
+    #     describe Something, :slow => true do
+    #
+    # And then store this in `.rspec`:
+    #
+    #     --tag ~slow:true
+    #
+    # Now when you run `rspec`, that group will be excluded.
+    #
+    # ## Overriding
+    #
+    # Of course, you probably want to run them sometimes, so you can override
+    # this tag on the command line like this:
+    #
+    #     rspec --tag slow:true
+    #
+    # ## RSpec.configure
+    #
+    # You can also store default tags with `RSpec.configure`. We use `tag` on
+    # the command line (and in options files like `.rspec`), but for historical
+    # reasons we use the term `filter` in `RSpec.configure:
+    #
+    #     RSpec.configure do |c|
+    #       c.filter_run_including :foo => :bar
+    #       c.filter_run_excluding :foo => :bar
+    #     end
+    #
+    # These declarations can also be overridden from the command line.
+    class FilterManager
+      DEFAULT_EXCLUSIONS = {
+        :if     => lambda { |value, metadata| metadata.has_key?(:if) && !value },
+        :unless => lambda { |value| value }
+      }
+
+      STANDALONE_FILTERS = [:locations, :line_numbers, :full_description]
+
+      module Describable
+        PROC_HEX_NUMBER = /0x[0-9a-f]+@/
+        PROJECT_DIR = File.expand_path('.')
+
+        def description
+          reject { |k, v| RSpec::Core::FilterManager::DEFAULT_EXCLUSIONS[k] == v }.inspect.gsub(PROC_HEX_NUMBER, '').gsub(PROJECT_DIR, '.').gsub(' (lambda)','')
+        end
+
+        def empty_without_conditional_filters?
+          reject { |k, v| RSpec::Core::FilterManager::DEFAULT_EXCLUSIONS[k] == v }.empty?
+        end
+      end
+
+      module BackwardCompatibility
+        # This is to support a use case that probably doesn't exist: overriding
+        # the if/unless procs.
+        def update(orig, opposite, *updates)
+          if updates.last.has_key?(:unless)
+            RSpec.warn_deprecation("\nDEPRECATION NOTICE: FilterManager#exclude(:unless => #{updates.last[:unless].inspect}) is deprecated with no replacement, and will be removed from rspec-3.0.")
+            @exclusions[:unless] = updates.last.delete(:unless)
+          end
+          if updates.last.has_key?(:if)
+            RSpec.warn_deprecation("\nDEPRECATION NOTICE: FilterManager#exclude(:if => #{updates.last[:if].inspect}) is deprecated with no replacement, and will be removed from rspec-3.0.")
+            @exclusions[:if] = updates.last.delete(:if)
+          end
+
+          super
+        end
+      end
+
+      attr_reader :exclusions, :inclusions
+
+      def initialize
+        @exclusions = DEFAULT_EXCLUSIONS.dup.extend(Describable)
+        @inclusions = {}.extend(Describable)
+        extend(BackwardCompatibility)
+      end
+
+      def add_location(file_path, line_numbers)
+        # filter_locations is a hash of expanded paths to arrays of line
+        # numbers to match against. e.g.
+        #   { "path/to/file.rb" => [37, 42] }
+        filter_locations = @inclusions[:locations] ||= Hash.new {|h,k| h[k] = []}
+        @exclusions.clear
+        @inclusions.clear
+        filter_locations[File.expand_path(file_path)].push(*line_numbers)
+        include :locations => filter_locations
+      end
+
+      def empty?
+        inclusions.empty? && exclusions.empty_without_conditional_filters?
+      end
+
+      def prune(examples)
+        examples.select {|e| !exclude?(e) && include?(e)}
+      end
+
+      def exclude?(example)
+        @exclusions.empty? ? false : example.any_apply?(@exclusions)
+      end
+
+      def include?(example)
+        @inclusions.empty? ? true : example.any_apply?(@inclusions)
+      end
+
+      def exclude(*args)
+        update(@exclusions, @inclusions, *args)
+      end
+
+      def include(*args)
+        return if already_set_standalone_filter?
+
+        is_standalone_filter?(args.last) ? @inclusions.replace(args.last) : update(@inclusions, @exclusions, *args)
+      end
+
+      def update(orig, opposite, *updates)
+        if updates.length == 2
+          if updates[0] == :replace
+            updated = updates.last
+          else
+            updated = updates.last.merge(orig)
+            opposite.each_key {|k| updated.delete(k)}
+          end
+          orig.replace(updated)
+        else
+          orig.merge!(updates.last).each_key {|k| opposite.delete(k)}
+        end
+      end
+
+      def already_set_standalone_filter?
+        is_standalone_filter?(inclusions)
+      end
+
+      def is_standalone_filter?(filter)
+        STANDALONE_FILTERS.any? {|key| filter.has_key?(key)}
+      end
+    end
+  end
+end