rspec-core 2.99.0 → 3.0.0

data/lib/rspec/core/option_parser.rb

@@ -2,21 +2,15 @@
 require 'optparse'
 
 module RSpec::Core
+  # @private
   class Parser
-    def self.parse!(args)
-      new.parse!(args)
+    def self.parse(args)
+      new.parse(args)
     end
 
-    class << self
-      alias_method :parse, :parse!
-    end
-
-    def parse!(args)
+    def parse(args)
       return {} if args.empty?
 
-      pre_parse(args)
-      convert_deprecated_args(args)
-
       options = args.delete('--tty') ? {:tty => true} : {}
       begin
         parser(options).parse!(args)
@@ -27,25 +21,6 @@ module RSpec::Core
       options
     end
 
-    def convert_deprecated_args(args)
-      args.map! { |arg|
-        case arg
-        when "--formatter"
-          RSpec.deprecate("The `--formatter` option", :replacement => "-f or --format", :call_site => nil)
-          "--format"
-        when "--default_path"
-          RSpec.deprecate("The `--default_path` option", :replacement => "--default-path", :call_site => nil)
-          "--default-path"
-        when "--line_number"
-          "--line-number"
-        else
-          arg
-        end
-      }
-    end
-
-    alias_method :parse, :parse!
-
     def parser(options)
       OptionParser.new do |parser|
         parser.banner = "Usage: rspec [options] [files or directories]\n\n"
@@ -65,35 +40,34 @@ module RSpec::Core
         end
 
         parser.on('--order TYPE[:SEED]', 'Run examples by the specified order type.',
-                  '  [defined] groups and examples are run in the order they are defined',
-                  '  [default] deprecated alias for defined',
-                  '  [rand]    randomize the order of files, groups and examples',
+                  '  [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|
-          options[:order] = if o == 'default'
-                              RSpec.deprecate("RSpec's `--order default` CLI option", :replacement => "`--order defined`", :call_site => nil)
-                              'defined'
-                            else
-                              o
-                            end
+          options[:order] = o
         end
 
         parser.on('--seed SEED', Integer, 'Equivalent of --order rand:SEED.') do |seed|
           options[:order] = "rand:#{seed}"
         end
 
-        parser.on('-d', '--debugger', 'Enable debugging.') do |o|
-          options[:debug] = :cli
-        end
-
         parser.on('--fail-fast', 'Abort the run on first failure.') do |o|
           options[:fail_fast] = true
         end
 
+        parser.on('--no-fail-fast', 'Do not abort the run on first failure.') do |o|
+          options[:fail_fast] = false
+        end
+
         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
+        end
+
         parser.on('-X', '--[no-]drb', 'Run examples via DRb.') do |o|
           options[:drb] = o
         end
@@ -103,12 +77,8 @@ module RSpec::Core
         end
 
         parser.on('--init', 'Initialize your project with RSpec.') do |cmd|
-          ProjectInitializer.new(cmd).run
-          exit
-        end
-
-        parser.on('--configure', 'Deprecated. Use --init instead.') do |cmd|
-          warn "--configure is deprecated with no effect. Use --init instead."
+          RSpec::Support.require_rspec_core "project_initializer"
+          ProjectInitializer.new.run
           exit
         end
 
@@ -118,7 +88,6 @@ module RSpec::Core
                 '  [p]rogress (default - dots)',
                 '  [d]ocumentation (group and example names)',
                 '  [h]tml',
-                '  [t]extmate',
                 '  [j]son',
                 '  custom formatter class name') do |o|
           options[:formatters] ||= []
@@ -134,9 +103,8 @@ module RSpec::Core
           options[:formatters].last << o
         end
 
-        parser.on('--deprecation-out FILE', 'Write deprecation warnings to a file instead of $stdout.') do |file|
-          # Handled in `pre_parse` so we can set the deprecation stream as early as
-          # possible in case any other options cause deprecations to be issued.
+        parser.on('--deprecation-out FILE', 'Write deprecation warnings to a file instead of $stderr.') do |file|
+          options[:deprecation_stream] = file
         end
 
         parser.on('-b', '--backtrace', 'Enable full backtrace.') do |o|
@@ -156,16 +124,17 @@ module RSpec::Core
                                          begin
                                            Integer(argument)
                                          rescue ArgumentError
-                                           Kernel.warn "Non integer specified as profile count, seperate " +
+                                           RSpec.warning "Non integer specified as profile count, seperate " +
                                                        "your path from options with -- e.g. " +
-                                                       "`rspec --profile -- #{argument}`"
+                                                       "`rspec --profile -- #{argument}`",
+                                                       :call_site => nil
                                            true
                                          end
                                        end
         end
 
         parser.on('-w', '--warnings', 'Enable ruby warnings') do
-          options[:warnings] = true
+          $VERBOSE = true
         end
 
         parser.separator <<-FILTERING
@@ -189,15 +158,6 @@ FILTERING
           (options[:full_description] ||= []) << Regexp.compile(Regexp.escape(o))
         end
 
-        parser.on('-l', '--line-number LINE', 'Specify line number of an example or group (may be',
-                                              '  used more than once).') do |o|
-          Metadata.line_number_filter_deprecation_issued = true
-          RSpec.deprecate("The `--line-number`/`-l` CLI option",
-                          :replacement => "the `path/to/file.rb:num` form",
-                          :call_site => nil)
-          (options[:line_numbers] ||= []) << o
-        end
-
         parser.on('-t', '--tag TAG[:VALUE]',
                   'Run examples with the specified tag, or exclude examples',
                   'by adding ~ before the tag.',
@@ -205,11 +165,21 @@ FILTERING
                   '  - TAG is always converted to a symbol') do |tag|
           filter_type = tag =~ /^~/ ? :exclusion_filter : :inclusion_filter
 
-          name,value = tag.gsub(/^(~@|~|@)/, '').split(':')
+          name,value = tag.gsub(/^(~@|~|@)/, '').split(':',2)
           name = name.to_sym
 
           options[filter_type] ||= {}
-          options[filter_type][name] = value.nil? ? true : eval(value) rescue value
+          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
         end
 
         parser.on('--default-path PATH', 'Set the default path where RSpec looks for examples (can',
@@ -224,19 +194,24 @@ FILTERING
           exit
         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
+        invalid_options = %w[-d --I]
+
         parser.on_tail('-h', '--help', "You're looking at it.") do
-          puts parser
+          # removing the blank invalid options from the output
+          puts parser.to_s.gsub(/^\s+(#{invalid_options.join('|')})\s*$\n/,'')
           exit
         end
 
-      end
-    end
-
-    def pre_parse(args)
-      args.each_cons(2) do |arg, value|
-        if arg == "--deprecation-out"
-          RSpec.configuration.deprecation_stream = value
+        # this prevents usage of the invalid_options
+        invalid_options.each do |option|
+          parser.on(option) do
+            raise OptionParser::InvalidOption.new
+          end
         end
+
       end
     end
   end

data/lib/rspec/core/ordering.rb

@@ -0,0 +1,156 @@
+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
+      # The default global ordering (defined order).
+      class Identity
+        def order(items)
+          items
+        end
+      end
+
+      # @private
+      # Orders items randomly.
+      class Random
+        def initialize(configuration)
+          @configuration = configuration
+          @used = false
+        end
+
+        def used?
+          @used
+        end
+
+        def order(items)
+          @used = true
+          rng = RandomNumberGenerator.new(@configuration.seed)
+          shuffle items, rng
+        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
+          end
+        end
+      end
+
+      # @private
+      # Orders items based on a custom block.
+      class Custom
+        def initialize(callable)
+          @callable = callable
+        end
+
+        def order(list)
+          @callable.call(list)
+        end
+      end
+
+      # @private
+      # Stores the different ordering strategies.
+      class Registry
+        def initialize(configuration)
+          @configuration = configuration
+          @strategies    = {}
+
+          register(:random,  Random.new(configuration))
+
+          identity = Identity.new
+          register(:defined, identity)
+
+          # The default global ordering is --defined.
+          register(:global, identity)
+        end
+
+        def fetch(name, &fallback)
+          @strategies.fetch(name, &fallback)
+        end
+
+        def register(sym, strategy)
+          @strategies[sym] = strategy
+        end
+
+        def used_random_seed?
+          @strategies[:random].used?
+        end
+      end
+
+      # @private
+      # Manages ordering configuration.
+      #
+      # @note This is not intended to be used externally. Use
+      #       the APIs provided by `RSpec::Core::Configuration` instead.
+      class ConfigurationManager
+        attr_reader :seed, :ordering_registry
+
+        def initialize
+          @ordering_registry = Registry.new(self)
+          @seed = rand(0xFFFF)
+          @seed_forced = false
+          @order_forced = false
+        end
+
+        def seed_used?
+          ordering_registry.used_random_seed?
+        end
+
+        def seed=(seed)
+          return if @seed_forced
+          register_ordering(:global, ordering_registry.fetch(:random))
+          @seed = seed.to_i
+        end
+
+        def order=(type)
+          order, seed = type.to_s.split(':')
+          @seed = seed = seed.to_i if seed
+
+          ordering_name = if order.include?('rand')
+            :random
+          elsif order == 'defined'
+            :defined
+          end
+
+          register_ordering(:global, ordering_registry.fetch(ordering_name)) if ordering_name
+        end
+
+        def force(hash)
+          if hash.has_key?(:seed)
+            self.seed = hash[:seed]
+            @seed_forced  = true
+            @order_forced = true
+          elsif hash.has_key?(:order)
+            self.order = hash[:order]
+            @order_forced = true
+          end
+        end
+
+        def register_ordering(name, strategy = Custom.new(Proc.new { |l| yield l }))
+          return if @order_forced && name == :global
+          ordering_registry.register(name, strategy)
+        end
+      end
+    end
+  end
+end
+

data/lib/rspec/core/pending.rb

@@ -1,16 +1,18 @@
 module RSpec
   module Core
+    # 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.
       class SkipDeclaredInExample < StandardError
         attr_reader :argument
 
         def initialize(argument)
-          super(argument.to_s)
           @argument = argument
         end
       end
 
-      # If Test::Unit is loaed, we'll use its error as baseclass, so that Test::Unit
+      # 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
@@ -18,52 +20,37 @@ module RSpec
         class PendingExampleFixedError < StandardError; end
       end
 
+      # @private
       NO_REASON_GIVEN = 'No reason given'
+
+      # @private
       NOT_YET_IMPLEMENTED = 'Not yet implemented'
 
       # @overload pending()
       # @overload pending(message)
-      # @overload pending(message, &block)
       #
-      # Stops execution of an example, and reports it as pending. Takes an
-      # optional message and block.
+      # Marks an example as pending. The rest of the example will still be
+      # executed, and if it passes the example will fail to indicate that the
+      # pending can be removed.
       #
-      # @param [String] message optional message to add to the summary report.
-      # @param [Block] block optional block. If it fails, the example is
-      #   reported as pending. If it executes cleanly the example fails.
+      # @param message [String] optional message to add to the summary report.
       #
       # @example
-      #
       #     describe "an example" do
       #       # reported as "Pending: no reason given"
       #       it "is pending with no message" do
       #         pending
-      #         this_does_not_get_executed
+      #         raise "broken"
       #       end
       #
       #       # reported as "Pending: something else getting finished"
       #       it "is pending with a custom message" do
       #         pending("something else getting finished")
-      #         this_does_not_get_executed
-      #       end
-      #
-      #       # reported as "Pending: something else getting finished"
-      #       it "is pending with a failing block" do
-      #         pending("something else getting finished") do
-      #           raise "this is the failure"
-      #         end
-      #       end
-      #
-      #       # reported as failure, saying we expected the block to fail but
-      #       # it passed.
-      #       it "is pending with a passing block" do
-      #         pending("something else getting finished") do
-      #           true.should be(true)
-      #         end
+      #         raise "broken"
       #       end
       #     end
       #
-      # @note `before(:each)` hooks are eval'd when you use the `pending`
+      # @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:
@@ -78,90 +65,101 @@ module RSpec
       #       it "does something", :pending => "something else getting finished" do
       #         # ...
       #       end
-      def pending(*args, &block)
-        RSpec.warn_deprecation(<<-EOS.gsub(/^\s+\|/, ''))
-          |The semantics of `RSpec::Core::Pending#pending` are changing in
-          |RSpec 3.  In RSpec 2.x, it caused the example to be skipped. In
-          |RSpec 3, the rest of the example will still be run but is expected
-          |to fail, and will be marked as a failure (rather than as pending)
-          |if the example passes.
-          |
-          |Any passed block will no longer be executed. This feature is being
-          |removed since it was semantically inconsistent, and the behaviour it
-          |offered is being made available with the other ways of marking an
-          |example pending.
-          |
-          |To keep the same skip semantics, change `pending` to `skip`.
-          |Otherwise, if you want the new RSpec 3 behavior, you can safely
-          |ignore this warning and continue to upgrade to RSpec 3 without
-          |addressing it.
-          |
-          |Called from #{CallerFilter.first_non_rspec_line}.
-          |
-        EOS
+      def pending(message=nil)
+        current_example = RSpec.current_example
 
-        pending_no_warning(*args, &block)
+        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, 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.
+            |
+            |Passing a block within an example is now deprecated. Marking the
+            |example as pending provides the same behavior in RSpec 3 which was
+            |provided only by the block in RSpec 2.x.
+            |
+            |Move the code in the block provided to `pending` into the rest of
+            |the example body.
+            |
+            |Called from #{CallerFilter.first_non_rspec_line}.
+            |
+          EOS
+        elsif current_example
+          Pending.mark_pending! current_example, message
+        else
+          raise "`pending` may not be used outside of examples, such as in " +
+                "before(:context). Maybe you want `skip`?"
+        end
       end
 
-      def pending_no_warning(*args)
-        return self.class.before(:each) { pending(*args) } unless RSpec.current_example
-
-        options = args.last.is_a?(Hash) ? args.pop : {}
-        message = args.first || NO_REASON_GIVEN
+      # @overload skip()
+      # @overload skip(message)
+      #
+      # Marks an example as pending and skips execution.
+      #
+      # @param message [String] optional message to add to the summary report.
+      #
+      # @example
+      #     describe "an example" do
+      #       # reported as "Pending: no reason given"
+      #       it "is skipped with no message" do
+      #         skip
+      #       end
+      #
+      #       # reported as "Pending: something else getting finished"
+      #       it "is skipped with a custom message" do
+      #         skip "something else getting finished"
+      #       end
+      #     end
+      def skip(message=nil)
+        current_example = RSpec.current_example
 
-        if options[:unless] || (options.has_key?(:if) && !options[:if])
-          return block_given? ? yield : nil
+        if current_example
+          Pending.mark_skipped! current_example, message
         end
 
-        RSpec.current_example.metadata[:pending] = true
-        RSpec.current_example.metadata[:execution_result][:pending_message] = message
-        RSpec.current_example.execution_result[:pending_fixed] = false
-        if block_given?
-          begin
-            result = begin
-                       yield
-                       RSpec.current_example.example_group_instance.instance_eval { verify_mocks_for_rspec }
-                     end
-            RSpec.current_example.metadata[:pending] = false
-          rescue Exception => e
-            RSpec.current_example.execution_result[:exception] = e
-          ensure
-            teardown_mocks_for_rspec
-          end
-          if result
-            RSpec.current_example.execution_result[:pending_fixed] = true
-            raise PendingExampleFixedError.new
-          end
-        end
         raise SkipDeclaredInExample.new(message)
       end
 
-      # Backport from RSpec 3 to aid in upgrading.
+      # @private
+      #
+      # Mark example as skipped
       #
-      # Not using alias method because we explictly want to discard any block.
-      def skip(*args)
-        pending_no_warning(*args)
+      # @param example [RSpec::Core::Example] the example to mark as skipped
+      # @param message_or_bool [Boolean, String] the message to use, or true
+      def self.mark_skipped!(example, message_or_bool)
+        Pending.mark_pending! example, message_or_bool
+        example.metadata[:skip] = true
       end
 
-      def self.const_missing(name)
-        return super unless name == :PendingDeclaredInExample
-
-        RSpec.deprecate("RSpec::Core::PendingDeclaredInExample",
-          :replacement => "RSpec::Core::Pending::SkipDeclaredInExample")
+      # @private
+      #
+      # 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
 
-        SkipDeclaredInExample
+        example.metadata[:pending] = true
+        example.execution_result.pending_message = message
+        example.execution_result.pending_fixed = false
       end
-    end
-
-    # Alias the error for compatibility with extension gems (e.g. formatters)
-    # that depend on the const name of the error in RSpec <= 2.8.
-    def self.const_missing(name)
-      return super unless name == :PendingExampleFixedError
 
-      RSpec.deprecate("RSpec::Core::PendingExampleFixedError",
-        :replacement => "RSpec::Core::Pending::PendingExampleFixedError")
-
-      Pending::PendingExampleFixedError
+      # @private
+      #
+      # Mark example as fixed
+      #
+      # @param example [RSpec::Core::Example] the example to mark as fixed
+      def self.mark_fixed!(example)
+        example.execution_result.pending_fixed = true
+      end
     end
   end
 end

data/lib/rspec/core/project_initializer/.rspec

@@ -0,0 +1,3 @@
+--color
+--warnings
+--require spec_helper