rspec-core 3.0.4 → 3.12.2

data/lib/rspec/core/option_parser.rb

@@ -4,30 +4,47 @@ require 'optparse'
 module RSpec::Core
   # @private
   class Parser
-    def self.parse(args)
-      new.parse(args)
+    def self.parse(args, source=nil)
+      new(args).parse(source)
     end
 
-    def parse(args)
-      return {} if args.empty?
+    attr_reader :original_args
 
-      options = args.delete('--tty') ? {:tty => true} : {}
+    def initialize(original_args)
+      @original_args = original_args
+    end
+
+    def parse(source=nil)
+      return { :files_or_directories_to_run => [] } if original_args.empty?
+      args = original_args.dup
+
+      options = args.delete('--tty') ? { :tty => true } : {}
       begin
         parser(options).parse!(args)
       rescue OptionParser::InvalidOption => e
-        abort "#{e.message}\n\nPlease use --help for a listing of valid options"
+        abort "#{e.message}#{" (defined in #{source})" if source}\n\n" \
+              "Please use --help for a listing of valid options"
       end
 
+      options[:files_or_directories_to_run] = args
       options
     end
 
+  private
+
+    # rubocop:disable Metrics/AbcSize
+    # rubocop:disable Metrics/MethodLength
+    # rubocop:disable Metrics/CyclomaticComplexity
+    # rubocop:disable Metrics/PerceivedComplexity
     def parser(options)
       OptionParser.new do |parser|
+        parser.summary_width = 34
+
         parser.banner = "Usage: rspec [options] [files or directories]\n\n"
 
-        parser.on('-I PATH', 'Specify PATH to add to $LOAD_PATH (may be used more than once).') do |dir|
+        parser.on('-I PATH', 'Specify PATH to add to $LOAD_PATH (may be used more than once).') do |dirs|
           options[:libs] ||= []
-          options[:libs] << dir
+          options[:libs].concat(dirs.split(File::PATH_SEPARATOR))
         end
 
         parser.on('-r', '--require PATH', 'Require a file.') do |path|
@@ -40,10 +57,11 @@ module RSpec::Core
         end
 
         parser.on('--order TYPE[:SEED]', 'Run examples by the specified order type.',
-                  '  [defined] examples and groups are run in the order they are defined',
-                  '  [rand]    randomize the order of groups and examples',
-                  '  [random]  alias for rand',
-                  '  [random:SEED] e.g. --order random:123') do |o|
+                  '  [defined]           examples and groups are run in the order they are defined',
+                  '  [rand]              randomize the order of groups and examples',
+                  '  [random]            alias for rand',
+                  '  [random:SEED]       e.g. --order random:123',
+                  '  [recently-modified] run the most recently modified files first') do |o|
           options[:order] = o
         end
 
@@ -51,45 +69,55 @@ module RSpec::Core
           options[:order] = "rand:#{seed}"
         end
 
-        parser.on('--fail-fast', 'Abort the run on first failure.') do |o|
-          options[:fail_fast] = true
+        parser.on('--bisect[=verbose]', 'Repeatedly runs the suite in order to isolate the failures to the ',
+                  '  smallest reproducible case.') do |argument|
+          options[:bisect] = argument || true
+          options[:runner] = RSpec::Core::Invocations::Bisect.new
         end
 
-        parser.on('--no-fail-fast', 'Do not abort the run on first failure.') do |o|
-          options[:fail_fast] = false
+        parser.on('--[no-]fail-fast[=COUNT]', 'Abort the run after a certain number of failures (1 by default).') do |argument|
+          if argument == true
+            value = 1
+          elsif argument == false || argument == 0
+            value = false
+          else
+            begin
+              value = Integer(argument)
+            rescue ArgumentError
+              RSpec.warning "Expected an integer value for `--fail-fast`, got: #{argument.inspect}", :call_site => nil
+            end
+          end
+          set_fail_fast(options, value)
         end
 
-        parser.on('--failure-exit-code CODE', Integer, 'Override the exit code used when there are failing specs.') do |code|
+        parser.on('--failure-exit-code CODE', Integer,
+                  'Override the exit code used when there are failing specs.') do |code|
           options[:failure_exit_code] = code
         end
 
-        parser.on('--dry-run', 'Print the formatter output of your suite without',
-                  '  running any examples or hooks') do |o|
-          options[:dry_run] = true
+        parser.on('--error-exit-code CODE', Integer,
+                  'Override the exit code used when there are errors loading or running specs outside of examples.') do |code|
+          options[:error_exit_code] = code
         end
 
-        parser.on('-X', '--[no-]drb', 'Run examples via DRb.') do |o|
-          options[:drb] = o
+        parser.on('-X', '--[no-]drb', 'Run examples via DRb.') do |use_drb|
+          options[:drb] = use_drb
+          options[:runner] = RSpec::Core::Invocations::DRbWithFallback.new if use_drb
         end
 
         parser.on('--drb-port PORT', 'Port to connect to the DRb server.') do |o|
           options[:drb_port] = o.to_i
         end
 
-        parser.on('--init', 'Initialize your project with RSpec.') do |cmd|
-          RSpec::Support.require_rspec_core "project_initializer"
-          ProjectInitializer.new.run
-          exit
-        end
-
         parser.separator("\n  **** Output ****\n\n")
 
         parser.on('-f', '--format FORMATTER', 'Choose a formatter.',
-                '  [p]rogress (default - dots)',
-                '  [d]ocumentation (group and example names)',
-                '  [h]tml',
-                '  [j]son',
-                '  custom formatter class name') do |o|
+                  '  [p]rogress (default - dots)',
+                  '  [d]ocumentation (group and example names)',
+                  '  [h]tml',
+                  '  [j]son',
+                  '  [f]ailures ("file:line:reason", suitable for editors integration)',
+                  '  custom formatter class name') do |o|
           options[:formatters] ||= []
           options[:formatters] << [o]
         end
@@ -107,15 +135,32 @@ module RSpec::Core
           options[:deprecation_stream] = file
         end
 
-        parser.on('-b', '--backtrace', 'Enable full backtrace.') do |o|
+        parser.on('-b', '--backtrace', 'Enable full backtrace.') do |_o|
           options[:full_backtrace] = true
         end
 
-        parser.on('-c', '--[no-]color', '--[no-]colour', 'Enable color in the output.') do |o|
-          options[:color] = o
+        parser.on('-c', '--color', '--colour', '') do |_o|
+          # flag will be excluded from `--help` output because it is deprecated
+          options[:color] = true
+          options[:color_mode] = :automatic
+        end
+
+        parser.on('--force-color', '--force-colour', 'Force the output to be in color, even if the output is not a TTY') do |_o|
+          if options[:color_mode] == :off
+            abort "Please only use one of `--force-color` and `--no-color`"
+          end
+          options[:color_mode] = :on
+        end
+
+        parser.on('--no-color', '--no-colour', 'Force the output to not be in color, even if the output is a TTY') do |_o|
+          if options[:color_mode] == :on
+            abort "Please only use one of --force-color and --no-color"
+          end
+          options[:color_mode] = :off
         end
 
-        parser.on('-p', '--[no-]profile [COUNT]', 'Enable profiling of examples and list the slowest examples (default: 10).') do |argument|
+        parser.on('-p', '--[no-]profile [COUNT]',
+                  'Enable profiling of examples and list the slowest examples (default: 10).') do |argument|
           options[:profile_examples] = if argument.nil?
                                          true
                                        elsif argument == false
@@ -124,16 +169,24 @@ module RSpec::Core
                                          begin
                                            Integer(argument)
                                          rescue ArgumentError
-                                           RSpec.warning "Non integer specified as profile count, seperate " +
-                                                       "your path from options with -- e.g. " +
+                                           RSpec.warning "Non integer specified as profile count, separate " \
+                                                       "your path from options with -- e.g. " \
                                                        "`rspec --profile -- #{argument}`",
-                                                       :call_site => nil
+                                                         :call_site => nil
                                            true
                                          end
                                        end
         end
 
+        parser.on('--dry-run', 'Print the formatter output of your suite without',
+                  '  running any examples or hooks') do |_o|
+          options[:dry_run] = true
+        end
+
         parser.on('-w', '--warnings', 'Enable ruby warnings') do
+          if Object.const_defined?(:Warning) && Warning.respond_to?(:[]=)
+            Warning[:deprecated] = true
+          end
           $VERBOSE = true
         end
 
@@ -141,23 +194,52 @@ module RSpec::Core
 
   **** Filtering/tags ****
 
-    In addition to the following options for selecting specific files, groups,
-    or examples, you can select a single example by appending the line number to
+    In addition to the following options for selecting specific files, groups, or
+    examples, you can select individual examples by appending the line number(s) to
     the filename:
 
-      rspec path/to/a_spec.rb:37
+      rspec path/to/a_spec.rb:37:87
+
+    You can also pass example ids enclosed in square brackets:
+
+      rspec path/to/a_spec.rb[1:5,1:6] # run the 5th and 6th examples/groups defined in the 1st group
 
 FILTERING
 
+        parser.on('--only-failures', "Filter to just the examples that failed the last time they ran.") do
+          configure_only_failures(options)
+        end
+
+        parser.on("-n", "--next-failure", "Apply `--only-failures` and abort after one failure.",
+                  "  (Equivalent to `--only-failures --fail-fast --order defined`)") do
+          configure_only_failures(options)
+          set_fail_fast(options, 1)
+          options[:order] ||= 'defined'
+        end
+
         parser.on('-P', '--pattern PATTERN', 'Load files matching pattern (default: "spec/**/*_spec.rb").') do |o|
-          options[:pattern] = o
+          if options[:pattern]
+            options[:pattern] += ',' + o
+          else
+            options[:pattern] = o
+          end
+        end
+
+        parser.on('--exclude-pattern PATTERN',
+                  'Load files except those matching pattern. Opposite effect of --pattern.') do |o|
+          options[:exclude_pattern] = o
         end
 
         parser.on('-e', '--example STRING', "Run examples whose full nested names include STRING (may be",
-                                            "  used more than once)") do |o|
+                  "  used more than once)") do |o|
           (options[:full_description] ||= []) << Regexp.compile(Regexp.escape(o))
         end
 
+        parser.on('-E', '--example-matches REGEX', "Run examples whose full nested names match REGEX (may be",
+                  "  used more than once)") do |o|
+          (options[:full_description] ||= []) << Regexp.compile(o)
+        end
+
         parser.on('-t', '--tag TAG[:VALUE]',
                   'Run examples with the specified tag, or exclude examples',
                   'by adding ~ before the tag.',
@@ -165,54 +247,77 @@ FILTERING
                   '  - TAG is always converted to a symbol') do |tag|
           filter_type = tag =~ /^~/ ? :exclusion_filter : :inclusion_filter
 
-          name,value = tag.gsub(/^(~@|~|@)/, '').split(':',2)
+          name, value = tag.gsub(/^(~@|~|@)/, '').split(':', 2)
           name = name.to_sym
 
-          options[filter_type] ||= {}
-          options[filter_type][name] = case value
-                                         when  nil        then true # The default value for tags is true
-                                         when 'true'      then true
-                                         when 'false'     then false
-                                         when 'nil'       then nil
-                                         when /^:/        then value[1..-1].to_sym
-                                         when /^\d+$/     then Integer(value)
-                                         when /^\d+.\d+$/ then Float(value)
-                                       else
-                                         value
-                                       end
+          parsed_value = case value
+                         when  nil        then true # The default value for tags is true
+                         when 'true'      then true
+                         when 'false'     then false
+                         when 'nil'       then nil
+                         when /^:/        then value[1..-1].to_sym
+                         when /^\d+$/     then Integer(value)
+                         when /^\d+.\d+$/ then Float(value)
+                         else
+                           value
+                         end
+
+          add_tag_filter(options, filter_type, name, parsed_value)
         end
 
         parser.on('--default-path PATH', 'Set the default path where RSpec looks for examples (can',
-                                         '  be a path to a file or a directory).') do |path|
+                  '  be a path to a file or a directory).') do |path|
           options[:default_path] = path
         end
 
         parser.separator("\n  **** Utility ****\n\n")
 
+        parser.on('--init', 'Initialize your project with RSpec.') do |_cmd|
+          options[:runner] = RSpec::Core::Invocations::InitializeProject.new
+        end
+
         parser.on('-v', '--version', 'Display the version.') do
-          puts RSpec::Core::Version::STRING
-          exit
+          options[:runner] = RSpec::Core::Invocations::PrintVersion.new
         end
 
-        # these options would otherwise be confusing to users, so we forcibly prevent them from executing
-        # --I is too similar to -I
-        # -d was a shorthand for --debugger, which is removed, but now would trigger --default-path
+        # These options would otherwise be confusing to users, so we forcibly
+        # prevent them from executing.
+        #
+        #   * --I is too similar to -I.
+        #   * -d was a shorthand for --debugger, which is removed, but now would
+        #     trigger --default-path.
         invalid_options = %w[-d --I]
 
+        hidden_options = invalid_options + %w[-c]
+
         parser.on_tail('-h', '--help', "You're looking at it.") do
-          # removing the blank invalid options from the output
-          puts parser.to_s.gsub(/^\s+(#{invalid_options.join('|')})\s*$\n/,'')
-          exit
+          options[:runner] = RSpec::Core::Invocations::PrintHelp.new(parser, hidden_options)
         end
 
-        # this prevents usage of the invalid_options
+        # This prevents usage of the invalid_options.
         invalid_options.each do |option|
           parser.on(option) do
             raise OptionParser::InvalidOption.new
           end
         end
-
       end
     end
+    # rubocop:enable Metrics/AbcSize
+    # rubocop:enable Metrics/MethodLength
+    # rubocop:enable Metrics/CyclomaticComplexity
+    # rubocop:enable Metrics/PerceivedComplexity
+
+    def add_tag_filter(options, filter_type, tag_name, value=true)
+      (options[filter_type] ||= {})[tag_name] = value
+    end
+
+    def set_fail_fast(options, value)
+      options[:fail_fast] = value
+    end
+
+    def configure_only_failures(options)
+      options[:only_failures] = true
+      add_tag_filter(options, :inclusion_filter, :last_run_status, 'failed')
+    end
   end
 end

data/lib/rspec/core/ordering.rb

@@ -1,14 +1,5 @@
 module RSpec
   module Core
-    if defined?(::Random)
-      # @private
-      RandomNumberGenerator = ::Random
-    else
-      RSpec::Support.require_rspec_core "backport_random"
-      # @private
-      RandomNumberGenerator = RSpec::Core::Backports::Random
-    end
-
     # @private
     module Ordering
       # @private
@@ -33,25 +24,45 @@ module RSpec
 
         def order(items)
           @used = true
-          rng = RandomNumberGenerator.new(@configuration.seed)
-          shuffle items, rng
+
+          seed = @configuration.seed.to_s
+          items.sort_by { |item| jenkins_hash_digest(seed + item.id) }
         end
 
-        if RUBY_VERSION > '1.9.3'
-          def shuffle(list, rng)
-            list.shuffle(:random => rng)
-          end
-        else
-          def shuffle(list, rng)
-            shuffled = list.dup
-            shuffled.size.times do |i|
-              j = i + rng.rand(shuffled.size - i)
-              next if i == j
-              shuffled[i], shuffled[j] = shuffled[j], shuffled[i]
-            end
-
-            shuffled
+      private
+
+        # http://en.wikipedia.org/wiki/Jenkins_hash_function
+        # Jenkins provides a good distribution and is simpler than MD5.
+        # It's a bit slower than MD5 (primarily because `Digest::MD5` is
+        # implemented in C) but has the advantage of not requiring us
+        # to load another part of stdlib, which we try to minimize.
+        def jenkins_hash_digest(string)
+          hash = 0
+
+          string.each_byte do |byte|
+            hash += byte
+            hash &= MAX_32_BIT
+            hash += ((hash << 10) & MAX_32_BIT)
+            hash &= MAX_32_BIT
+            hash ^= hash >> 6
           end
+
+          hash += ((hash << 3) & MAX_32_BIT)
+          hash &= MAX_32_BIT
+          hash ^= hash >> 11
+          hash += ((hash << 15) & MAX_32_BIT)
+          hash &= MAX_32_BIT
+          hash
+        end
+
+        MAX_32_BIT = 4_294_967_295
+      end
+
+      # @private
+      # Orders items by modification time (most recent modified first).
+      class RecentlyModified
+        def order(list)
+          list.sort_by { |item| -File.mtime(item.metadata[:absolute_file_path]).to_i }
         end
       end
 
@@ -74,7 +85,8 @@ module RSpec
           @configuration = configuration
           @strategies    = {}
 
-          register(:random,  Random.new(configuration))
+          register(:random, Random.new(configuration))
+          register(:recently_modified, RecentlyModified.new)
 
           identity = Identity.new
           register(:defined, identity)
@@ -123,29 +135,31 @@ module RSpec
 
         def order=(type)
           order, seed = type.to_s.split(':')
-          @seed = seed = seed.to_i if seed
+          @seed = seed.to_i if seed
 
           ordering_name = if order.include?('rand')
-            :random
-          elsif order == 'defined'
-            :defined
-          end
+                            :random
+                          elsif order == 'defined'
+                            :defined
+                          elsif order == 'recently-modified'
+                            :recently_modified
+                          end
 
           register_ordering(:global, ordering_registry.fetch(ordering_name)) if ordering_name
         end
 
         def force(hash)
-          if hash.has_key?(:seed)
+          if hash.key?(:seed)
             self.seed = hash[:seed]
             @seed_forced  = true
             @order_forced = true
-          elsif hash.has_key?(:order)
+          elsif hash.key?(:order)
             self.order = hash[:order]
             @order_forced = true
           end
         end
 
-        def register_ordering(name, strategy = Custom.new(Proc.new { |l| yield l }))
+        def register_ordering(name, strategy=Custom.new(Proc.new { |l| yield l }))
           return if @order_forced && name == :global
           ordering_registry.register(name, strategy)
         end
@@ -153,4 +167,3 @@ module RSpec
     end
   end
 end
-

data/lib/rspec/core/output_wrapper.rb

@@ -0,0 +1,29 @@
+module RSpec
+  module Core
+    # @private
+    class OutputWrapper
+      # @private
+      attr_accessor :output
+
+      # @private
+      def initialize(output)
+        @output = output
+      end
+
+      def respond_to?(name, priv=false)
+        output.respond_to?(name, priv)
+      end
+
+      def method_missing(name, *args, &block)
+        output.send(name, *args, &block)
+      end
+
+      # Redirect calls for IO interface methods
+      IO.instance_methods(false).each do |method|
+        define_method(method) do |*args, &block|
+          output.send(method, *args, &block)
+        end
+      end
+    end
+  end
+end

data/lib/rspec/core/pending.rb

@@ -1,9 +1,10 @@
 module RSpec
   module Core
-    # Provides methods to mark examples as pending. These methods are available to be
-    # called from within any example or hook.
+    # Provides methods to mark examples as pending. These methods are available
+    # to be called from within any example or hook.
     module Pending
-      # Raised in the middle of an example to indicate that it should be marked as skipped.
+      # Raised in the middle of an example to indicate that it should be marked
+      # as skipped.
       class SkipDeclaredInExample < StandardError
         attr_reader :argument
 
@@ -12,8 +13,9 @@ module RSpec
         end
       end
 
-      # If Test::Unit is loaded, we'll use its error as baseclass, so that Test::Unit
-      # will report unmet RSpec expectations as failures rather than errors.
+      # If Test::Unit is loaded, we'll use its error as baseclass, so that
+      # Test::Unit will report unmet RSpec expectations as failures rather than
+      # errors.
       begin
         class PendingExampleFixedError < Test::Unit::AssertionFailedError; end
       rescue
@@ -36,7 +38,7 @@ module RSpec
       # @param message [String] optional message to add to the summary report.
       #
       # @example
-      #     describe "an example" do
+      #     describe "some behaviour" do
       #       # reported as "Pending: no reason given"
       #       it "is pending with no message" do
       #         pending
@@ -50,28 +52,20 @@ module RSpec
       #       end
       #     end
       #
-      # @note `before(:example)` hooks are eval'd when you use the `pending`
-      #   method within an example. If you want to declare an example `pending`
-      #   and bypass the `before` hooks as well, you can pass `:pending => true`
-      #   to the `it` method:
-      #
-      #       it "does something", :pending => true do
-      #         # ...
-      #       end
-      #
-      #   or pass `:pending => "something else getting finished"` to add a
-      #   message to the summary report:
-      #
-      #       it "does something", :pending => "something else getting finished" do
-      #         # ...
-      #       end
+      # @note When using `pending` inside an example body using this method
+      #   hooks, such as `before(:example)`, have already be run. This means that
+      #   a failure from the code in the `before` hook will prevent the example
+      #   from being considered pending, as the example body would not be
+      #   executed. If you need to consider hooks as pending as well you can use
+      #   the pending metadata as an alternative, e.g.
+      #   `it "does something", pending: "message"`.
       def pending(message=nil)
         current_example = RSpec.current_example
 
         if block_given?
           raise ArgumentError, <<-EOS.gsub(/^\s+\|/, '')
             |The semantics of `RSpec::Core::Pending#pending` have changed in
-            |RSpec 3.  In RSpec 2.x, it caused the example to be skipped. In
+            |RSpec 3. In RSpec 2.x, it caused the example to be skipped. In
             |RSpec 3, the rest of the example is still run but is expected to
             |fail, and will be marked as a failure (rather than as pending) if
             |the example passes.
@@ -89,7 +83,7 @@ module RSpec
         elsif current_example
           Pending.mark_pending! current_example, message
         else
-          raise "`pending` may not be used outside of examples, such as in " +
+          raise "`pending` may not be used outside of examples, such as in " \
                 "before(:context). Maybe you want `skip`?"
         end
       end
@@ -116,16 +110,14 @@ module RSpec
       def skip(message=nil)
         current_example = RSpec.current_example
 
-        if current_example
-          Pending.mark_skipped! current_example, message
-        end
+        Pending.mark_skipped!(current_example, message) if current_example
 
         raise SkipDeclaredInExample.new(message)
       end
 
       # @private
       #
-      # Mark example as skipped
+      # Mark example as skipped.
       #
       # @param example [RSpec::Core::Example] the example to mark as skipped
       # @param message_or_bool [Boolean, String] the message to use, or true
@@ -136,16 +128,16 @@ module RSpec
 
       # @private
       #
-      # Mark example as pending
+      # Mark example as pending.
       #
       # @param example [RSpec::Core::Example] the example to mark as pending
       # @param message_or_bool [Boolean, String] the message to use, or true
       def self.mark_pending!(example, message_or_bool)
         message = if !message_or_bool || !(String === message_or_bool)
-          NO_REASON_GIVEN
-        else
-          message_or_bool
-        end
+                    NO_REASON_GIVEN
+                  else
+                    message_or_bool
+                  end
 
         example.metadata[:pending] = true
         example.execution_result.pending_message = message
@@ -154,7 +146,7 @@ module RSpec
 
       # @private
       #
-      # Mark example as fixed
+      # Mark example as fixed.
       #
       # @param example [RSpec::Core::Example] the example to mark as fixed
       def self.mark_fixed!(example)