rspec-core 2.14.8 → 2.99.0.beta1

data/lib/rspec/core.rb

@@ -2,7 +2,7 @@ require_rspec = if defined?(require_relative)
   lambda do |path|
     require_relative path
   end
-else
+else # for 1.8.7
   lambda do |path|
     require "rspec/#{path}"
   end
@@ -11,6 +11,7 @@ end
 require 'set'
 require 'time'
 require 'rbconfig'
+require_rspec['core/caller_filter']
 require_rspec['core/filter_manager']
 require_rspec['core/dsl']
 require_rspec['core/extensions/kernel']
@@ -94,7 +95,7 @@ DEPRECATION WARNING
 * RSpec.configuration with a block is deprecated and has no effect.
 * please use RSpec.configure with a block instead.
 
-Called from #{caller(0)[1]}
+Called from #{CallerFilter.first_non_rspec_line}
 *****************************************************************
 
 WARNING
@@ -126,6 +127,37 @@ WARNING
     world.example_groups.clear
   end
 
+  # The example being executed.
+  #
+  # The primary audience for this method is library authors who need access
+  # to the example currently being executed and also want to support all
+  # versions of RSpec 2 and 3.
+  #
+  # @example
+  #
+  #     RSpec.configure do |c|
+  #       # context.example is deprecated, but RSpec.current_example is not
+  #       # available until RSpec 3.0.
+  #       fetch_current_example = RSpec.respond_to?(:current_example) ?
+  #         proc { RSpec.current_example } : proc { |context| context.example }
+  #
+  #       c.before(:each) do
+  #         example = fetch_current_example.call(self)
+  #
+  #         # ...
+  #       end
+  #     end
+  #
+  def self.current_example
+    Thread.current[:_rspec_current_example]
+  end
+
+  # Set the current example being executed.
+  # @api private
+  def self.current_example=(example)
+    Thread.current[:_rspec_current_example] = example
+  end
+
   # @private
   def self.windows_os?
     RbConfig::CONFIG['host_os'] =~ /cygwin|mswin|mingw|bccwin|wince|emx/
@@ -141,6 +173,12 @@ WARNING
         define_method(:now,&::Time.method(:now))
       end
     end
+
+    # @private path to executable file
+    def self.path_to_executable
+      File.expand_path('../../../exe/rspec', __FILE__)
+    end
+
   end
 
   MODULES_TO_AUTOLOAD = {

data/lib/rspec/core/caller_filter.rb

@@ -0,0 +1,55 @@
+module RSpec
+  # Consistent implementation for "cleaning" the caller method to strip out
+  # non-rspec lines. This enables errors to be reported at the call site in
+  # the code using the library, which is far more useful than the particular
+  # internal method that raised an error.
+  class CallerFilter
+
+    RSPEC_LIBS = %w[
+      core
+      mocks
+      expectations
+      matchers
+      rails
+    ]
+
+    ADDITIONAL_TOP_LEVEL_FILES = %w[ autorun ]
+
+    LIB_REGEX = %r{/lib/rspec/(#{(RSPEC_LIBS + ADDITIONAL_TOP_LEVEL_FILES).join('|')})(\.rb|/)}
+
+    if RUBY_VERSION >= '2.0.0'
+      def self.first_non_rspec_line
+        # `caller` is an expensive method that scales linearly with the size of
+        # the stack. The performance hit for fetching it in chunks is small,
+        # and since the target line is probably near the top of the stack, the
+        # overall improvement of a chunked search like this is significant.
+        #
+        # See benchmarks/caller.rb for measurements.
+
+        # Initial value here is mostly arbitrary, but is chosen to give good
+        # performance on the common case of creating a double.
+        increment = 5
+        i         = 1
+        line      = nil
+
+        while !line
+          stack = caller(i, increment)
+          raise "No non-lib lines in stack" unless stack
+
+          line = stack.find { |l| l !~ LIB_REGEX }
+
+          i         += increment
+          increment *= 2 # The choice of two here is arbitrary.
+        end
+
+        line
+      end
+    else
+      # Earlier rubies do not support the two argument form of `caller`. This
+      # fallback is logically the same, but slower.
+      def self.first_non_rspec_line
+        caller.find { |line| line !~ LIB_REGEX }
+      end
+    end
+  end
+end

data/lib/rspec/core/command_line.rb

@@ -17,12 +17,12 @@ module RSpec
       # @param [IO] out
       def run(err, out)
         @configuration.error_stream = err
-        @configuration.output_stream ||= out
+        @configuration.output_stream = out if @configuration.output_stream == $stdout
         @options.configure(@configuration)
         @configuration.load_spec_files
         @world.announce_filters
 
-        @configuration.reporter.report(@world.example_count, @configuration.randomize? ? @configuration.seed : nil) do |reporter|
+        @configuration.reporter.report(@world.example_count, @configuration.send(:_randomize?) ? @configuration.seed : nil) do |reporter|
           begin
             @configuration.run_hook(:before, :suite)
             @world.example_groups.ordered.map {|g| g.run(reporter)}.all? ? 0 : @configuration.failure_exit_code

data/lib/rspec/core/configuration.rb

@@ -1,7 +1,7 @@
 require 'fileutils'
 require 'rspec/core/backtrace_cleaner'
 require 'rspec/core/ruby_project'
-require 'rspec/core/formatters/deprecation_formatter.rb'
+require 'rspec/core/formatters/deprecation_formatter'
 
 module RSpec
   module Core
@@ -104,10 +104,6 @@ module RSpec
       # The exit code to return if there are any failures (default: 1).
       add_setting :failure_exit_code
 
-      # Determines the order in which examples are run (default: OS standard
-      # load order for files, declaration order for groups and examples).
-      define_reader :order
-
       # Indicates files configured to be required
       define_reader :requires
 
@@ -116,11 +112,53 @@ module RSpec
 
       # Default: `$stdout`.
       # Also known as `output` and `out`
-      add_setting :output_stream, :alias_with => [:output, :out]
+      define_reader :output_stream
+      def output_stream=(value)
+        if @reporter && !value.equal?(@output_stream)
+          warn "RSpec's reporter has already been initialized with " +
+            "#{output_stream.inspect} as the output stream, so your change to "+
+            "`output_stream` will be ignored. You should configure it earlier for " +
+            "it to take effect. (Called from #{CallerFilter.first_non_rspec_line})"
+        else
+          @output_stream = value
+        end
+      end
+
+      # @deprecated use RSpec::Core::Configuration#output_stream instead.
+      def output
+        RSpec.deprecate("RSpec::Core::Configuration#output", :replacement => "RSpec::Core::Configuration#output_stream")
+        output_stream
+      end
+
+      # @deprecated use RSpec::Core::Configuration#output_stream= instead.
+      def output=(value)
+        RSpec.deprecate("RSpec::Core::Configuration#output=", :replacement => "RSpec::Core::Configuration#output_stream=")
+        self.output_stream = value
+      end
+
+      # @deprecated use RSpec::Core::Configuration#output_stream instead.
+      def out
+        RSpec.deprecate("RSpec::Core::Configuration#out", :replacement => "RSpec::Core::Configuration#output_stream")
+        output_stream
+      end
+
+      # @deprecated use RSpec::Core::Configuration#output_stream= instead.
+      def out=(value)
+        RSpec.deprecate("RSpec::Core::Configuration#out=", :replacement => "RSpec::Core::Configuration#output_stream=")
+        self.output_stream = value
+      end
 
       # Load files matching this pattern (default: `'**/*_spec.rb'`)
       add_setting :pattern, :alias_with => :filename_pattern
 
+      def pattern= value
+        if @spec_files_loaded
+          Kernel.warn "WARNING: Configuring `pattern` to #{value} has no effect since RSpec has already loaded the spec files. Called from #{CallerFilter.first_non_rspec_line}"
+        end
+        @pattern = value
+      end
+      alias :filename_pattern= :pattern=
+
       # Report the times for the slowest examples (default: `false`).
       # Use this to specify the number of examples to include in the profile.
       add_setting :profile_examples
@@ -170,6 +208,14 @@ module RSpec
       #     end
       add_setting :treat_symbols_as_metadata_keys_with_true_values
 
+      def treat_symbols_as_metadata_keys_with_true_values=(value)
+        unless value
+          RSpec.deprecate("RSpec.configuration.treat_symbols_as_metadata_keys_with_true_values = false")
+        end
+
+        @treat_symbols_as_metadata_keys_with_true_values = value
+      end
+
       # @private
       add_setting :tty
       # @private
@@ -190,13 +236,17 @@ module RSpec
         @files_to_run = []
         @formatters = []
         @color = false
+        @order = nil
         @pattern = '**/*_spec.rb'
         @failure_exit_code = 1
+        @spec_files_loaded = false
 
         @backtrace_cleaner = BacktraceCleaner.new
 
         @default_path = 'spec'
         @deprecation_stream = $stderr
+        @output_stream = $stdout
+        @reporter = nil
         @filter_manager = FilterManager.new
         @preferred_options = {}
         @seed = srand % 0xFFFF
@@ -226,6 +276,7 @@ module RSpec
 
       # @private
       def reset
+        @spec_files_loaded = false
         @reporter = nil
         @formatters.clear
       end
@@ -516,6 +567,18 @@ module RSpec
       end
 
       def debug=(bool)
+        if bool
+          # Usually this is called automatically by the --debug CLI option, so the
+          # deprecation message doesn't mention `RSpec::Core::Configuration#debug=`
+          RSpec.deprecate("RSpec's built-in debugger support",
+                          :replacement => "a CLI option like `-rruby-debug` or `-rdebugger`")
+        else
+          # ...but the only way to call this with a false value is to
+          # call it directly, so here we mention the method name.
+          # There's no replacement for it since it's a no-op, though.
+          RSpec.deprecate("RSpec::Core::Configuration#debug=")
+        end
+
         return unless bool
         begin
           require 'ruby-debug'
@@ -537,6 +600,9 @@ EOM
       end
 
       def debug?
+        RSpec.deprecate("RSpec::Core::Configuration#debug?",
+                        :replacement => "defined?(Debugger)")
+
         !!defined?(Debugger)
       end
 
@@ -574,7 +640,7 @@ EOM
           custom_formatter(formatter_to_use) ||
           (raise ArgumentError, "Formatter '#{formatter_to_use}' unknown - maybe you meant 'documentation' or 'progress'?.")
 
-        paths << output if paths.empty?
+        paths << output_stream if paths.empty?
         formatters << formatter_class.new(*paths.map {|p| String === p ? file_at(p) : p})
       end
 
@@ -894,6 +960,7 @@ EOM
       # @private
       def load_spec_files
         files_to_run.uniq.each {|f| load File.expand_path(f) }
+        @spec_files_loaded = true
         raise_if_rspec_1_is_loaded
       end
 
@@ -930,8 +997,28 @@ EOM
         order_and_seed_from_order(type)
       end
 
+      # Determines the order in which examples are run (default: OS standard
+      # load order for files, declaration order for groups and examples).
+      def order
+        RSpec.warn_deprecation(
+          "RSpec::Core::Configuration#order is deprecated with no replacement. " +
+          "In RSpec 3 individal example groups can use a particular ordering, " +
+          "so `order` is no longer a global property of the entire suite. " +
+          "Called from #{CallerFilter.first_non_rspec_line}."
+        )
+
+        value_for(:order, @order)
+      end
+
       def randomize?
-        order.to_s.match(/rand/)
+        RSpec.warn_deprecation(
+          "RSpec::Core::Configuration#randomize? is deprecated with no replacement. " +
+          "In RSpec 3 individal example groups can use a particular ordering, " +
+          "so `randomize?` is no longer a binary property of the entire suite. " +
+          "Called from #{CallerFilter.first_non_rspec_line}."
+        )
+
+        value_for(:order, @order).to_s.match(/rand/)
       end
 
       # @private
@@ -959,6 +1046,7 @@ EOM
       # @see #order=
       # @see #seed=
       def order_examples(&block)
+        RSpec.deprecate("RSpec::Configuration#order_examples", :replacement => "RSpec::Configuration#register_ordering(:global)")
         @example_ordering_block = block
         @order = "custom" unless built_in_orderer?(block)
       end
@@ -982,6 +1070,7 @@ EOM
       # @see #order=
       # @see #seed=
       def order_groups(&block)
+        RSpec.deprecate("RSpec::Configuration#order_groups", :replacement => "RSpec::Configuration#register_ordering(:global)")
         @group_ordering_block = block
         @order = "custom" unless built_in_orderer?(block)
       end
@@ -1009,6 +1098,46 @@ EOM
         order_examples(&block)
       end
 
+      # In RSpec 3, this registers a named ordering strategy that can later be
+      # used to order an example group's subgroups by adding
+      # `:order => <name>` metadata to the example group.
+      #
+      # In RSpec 2.99, only `register_ordering(:global)` is supported,
+      # to set the global ordering.
+      #
+      # @param name [Symbol] The name of the ordering.
+      # @yield Block that will order the given examples or example groups
+      # @yieldparam list [Array<RSpec::Core::Example>, Array<RSpec::Core::ExampleGropu>] The examples or groups to order
+      # @yieldreturn [Array<RSpec::Core::Example>, Array<RSpec::Core::ExampleGroup>] The re-ordered examples or groups
+      #
+      # @example
+      #   RSpec.configure do |rspec|
+      #     rspec.register_ordering :reverse do |list|
+      #       list.reverse
+      #     end
+      #   end
+      #
+      #   describe MyClass, :order => :reverse do
+      #     # ...
+      #   end
+      #
+      # @note Pass the symbol `:global` to set the ordering strategy that
+      #   will be used to order the top-level example groups and any example
+      #   groups that do not have declared `:order` metadata.
+      def register_ordering(name, &block)
+        unless name == :global
+          raise ArgumentError,
+            "Ordering name `#{name.inspect}` given, `:global` expected. " +
+            "RSpec 3 will support named orderings (that can be used for " +
+            "individual example groups) but 2.99 only supports using this " +
+            "to set the global order."
+        end
+
+        @group_ordering_block = block
+        @example_ordering_block = block
+        @order = "custom"
+      end
+
       # Set Ruby warnings on or off
       def warnings= value
         $VERBOSE = !!value
@@ -1018,8 +1147,59 @@ EOM
         $VERBOSE
       end
 
+      # Exposes the current running example via the named
+      # helper method. RSpec 2.x exposed this via `example`,
+      # but in RSpec 3.0, the example is instead exposed via
+      # an arg yielded to `it`, `before`, `let`, etc. However,
+      # some extension gems (such as Capybara) depend on the
+      # RSpec 2.x's `example` method, so this config option
+      # can be used to maintain compatibility.
+      #
+      # @param method_name [Symbol] the name of the helper method
+      #
+      # @example
+      #
+      #   RSpec.configure do |rspec|
+      #     rspec.expose_current_running_example_as :example
+      #   end
+      #
+      #   describe MyClass do
+      #     before do
+      #       # `example` can be used here because of the above config.
+      #       do_something if example.metadata[:type] == "foo"
+      #     end
+      #   end
+      def expose_current_running_example_as(method_name)
+        ExposeCurrentExample.module_eval do
+          extend RSpec::SharedContext
+          let(method_name) { |ex| ex }
+        end
+
+        include ExposeCurrentExample
+      end
+
+      module ExposeCurrentExample; end
+
+      # Turns deprecation warnings into errors, in order to surface
+      # the full backtrace of the call site. This can be useful when
+      # you need more context to address a deprecation than the
+      # single-line call site normally provided.
+      #
+      # @example
+      #
+      #   RSpec.configure do |rspec|
+      #     rspec.raise_errors_for_deprecations!
+      #   end
+      def raise_errors_for_deprecations!
+        self.deprecation_stream = Formatters::DeprecationFormatter::RaiseErrorStream.new
+      end
+
     private
 
+      def _randomize?
+        value_for(:order, @order).to_s.match(/rand/)
+      end
+
       def get_files_to_run(paths)
         paths.map do |path|
           path = path.gsub(File::ALT_SEPARATOR, File::SEPARATOR) if File::ALT_SEPARATOR
@@ -1140,7 +1320,8 @@ MESSAGE
       end
 
       def order_and_seed_from_seed(value)
-        order_groups_and_examples(&RANDOM_ORDERING)
+        @group_ordering_block = RANDOM_ORDERING
+        @example_ordering_block = RANDOM_ORDERING
         @order, @seed = 'rand', value.to_i
         [@order, @seed]
       end
@@ -1155,11 +1336,18 @@ MESSAGE
         @order = order
         @seed  = seed = seed.to_i if seed
 
-        if randomize?
-          order_groups_and_examples(&RANDOM_ORDERING)
-        elsif order == 'default'
+        if order.to_s.match(/rand/)
+          @group_ordering_block = RANDOM_ORDERING
+          @example_ordering_block = RANDOM_ORDERING
+        elsif %w[ default defined ].include?(order)
+          if order == 'default'
+            RSpec.deprecate("RSpec::Core::Configuration#order = 'default'",
+                            :replacement => "RSpec::Core::Configuration#order = 'defined'")
+          end
+
           @order, @seed = nil, nil
-          order_groups_and_examples(&DEFAULT_ORDERING)
+          @group_ordering_block = DEFAULT_ORDERING
+          @example_ordering_block = DEFAULT_ORDERING
         end
 
         return order, seed