rspec-core 3.0.0.beta2 → 3.0.0.rc1

data/README.md

@@ -1,4 +1,4 @@
-# rspec-core [![Build Status](https://secure.travis-ci.org/rspec/rspec-core.png?branch=master)](http://travis-ci.org/rspec/rspec-core) [![Code Climate](https://codeclimate.com/github/rspec/rspec-core.png)](https://codeclimate.com/github/rspec/rspec-core)
+# rspec-core [![Build Status](https://secure.travis-ci.org/rspec/rspec-core.png?branch=master)](http://travis-ci.org/rspec/rspec-core) [![Code Climate](https://codeclimate.com/github/rspec/rspec-core.png)](https://codeclimate.com/github/rspec/rspec-core) [![Inline docs](http://inch-pages.github.io/github/rspec/rspec-core.png)](http://inch-pages.github.io/github/rspec/rspec-core)
 
 rspec-core provides the structure for writing executable examples of how your
 code should behave, and an `rspec` command with tools to constrain which
@@ -18,7 +18,7 @@ RSpec uses the words "describe" and "it" so we can express concepts like a conve
     "It sums the prices of its line items."
 
 ```ruby
-describe Order do
+RSpec.describe Order do
   it "sums the prices of its line items" do
     order = Order.new
     order.add_entry(LineItem.new(:item => Item.new(
@@ -46,7 +46,7 @@ You can also declare nested nested groups using the `describe` or `context`
 methods:
 
 ```ruby
-describe Order do
+RSpec.describe Order do
   context "with no items" do
     it "behaves one way" do
       # ...
@@ -63,8 +63,11 @@ end
 
 ## aliases
 
-You can declare example groups using either `describe` or `context`, though
-only `describe` is available at the top level.
+You can declare example groups using either `describe` or `context`.
+For a top level example group, `describe` and `context` are available
+off of `RSpec`. For backwards compatibility, they are also available
+off of the `main` object and `Module` unless you disable monkey
+patching.
 
 You can declare examples within a group using any of `it`, `specify`, or
 `example`.
@@ -75,17 +78,17 @@ Declare a shared example group using `shared_examples`, and then include it
 in any group using `include_examples`.
 
 ```ruby
-shared_examples "collections" do |collection_class|
+RSpec.shared_examples "collections" do |collection_class|
   it "is empty when first created" do
     expect(collection_class.new).to be_empty
   end
 end
 
-describe Array do
+RSpec.describe Array do
   include_examples "collections", Array
 end
 
-describe Hash do
+RSpec.describe Hash do
   include_examples "collections", Hash
 end
 ```
@@ -123,7 +126,7 @@ using the `described_class` method, which is a wrapper for
 `example.metadata[:described_class]`.
 
 ```ruby
-describe Widget do
+RSpec.describe Widget do
   example do
     expect(described_class).to equal(Widget)
   end
@@ -135,17 +138,17 @@ class is unknown. Taking the collections shared example group from above, we can
 clean it up a bit using `described_class`:
 
 ```ruby
-shared_examples "collections" do
+RSpec.shared_examples "collections" do
   it "is empty when first created" do
     expect(described_class.new).to be_empty
   end
 end
 
-describe Array do
+RSpec.describe Array do
   include_examples "collections"
 end
 
-describe Hash do
+RSpec.describe Hash do
   include_examples "collections"
 end
 ```
@@ -176,7 +179,7 @@ this before you write any implementation code:
 
 ```ruby
 # in spec/calculator_spec.rb
-describe Calculator do
+RSpec.describe Calculator do
   describe '#add' do
     it 'returns the sum of its arguments' do
       expect(Calculator.new.add(1, 2)).to eq(3)

data/lib/rspec/core.rb

@@ -1,77 +1,49 @@
-require_rspec = if defined?(require_relative)
-  lambda do |path|
-    require_relative path
-  end
-else # for 1.8.7
-  lambda do |path|
-    require "rspec/#{path}"
-  end
-end
-
-require 'set'
-require 'time'
+$_rspec_core_load_started_at = Time.now
 require 'rbconfig'
 
-require_rspec['core/version']
-
-require 'rspec/support/caller_filter'
-require 'rspec/core/warnings'
-require 'rspec/support/warnings'
-
-require_rspec['core/flat_map']
-require_rspec['core/filter_manager']
-require_rspec['core/dsl']
-require_rspec['core/notifications']
-require_rspec['core/reporter']
-
-require_rspec['core/hooks']
-require_rspec['core/memoized_helpers']
-require_rspec['core/metadata']
-require_rspec['core/pending']
-require_rspec['core/formatters']
-require_rspec['core/ordering']
-
-require_rspec['core/world']
-require_rspec['core/configuration']
-require_rspec['core/option_parser']
-require_rspec['core/configuration_options']
-require_rspec['core/command_line']
-require_rspec['core/runner']
-require_rspec['core/example']
-require_rspec['core/shared_example_group/collection']
-require_rspec['core/shared_example_group']
-require_rspec['core/example_group']
+require "rspec/support"
+RSpec::Support.require_rspec_support "caller_filter"
+
+RSpec::Support.define_optimized_require_for_rspec(:core) { |f| require_relative f }
+
+%w[
+  version
+  warnings
+
+  flat_map
+  filter_manager
+  dsl
+  notifications
+  reporter
+
+  hooks
+  memoized_helpers
+  metadata
+  metadata_filter
+  pending
+  formatters
+  ordering
+
+  world
+  configuration
+  option_parser
+  configuration_options
+  runner
+  example
+  shared_example_group
+  example_group
+].each { |name| RSpec::Support.require_rspec_core name }
 
 module RSpec
   autoload :SharedContext, 'rspec/core/shared_context'
 
-  # @private
-  def self.wants_to_quit
-  # Used internally to determine what to do when a SIGINT is received
-    world.wants_to_quit
-  end
-
-  # @private
-  # Used internally to determine what to do when a SIGINT is received
-  def self.wants_to_quit=(maybe)
-    world.wants_to_quit=(maybe)
-  end
-
-  # @private
-  # Internal container for global non-configuration data
-  def self.world
-    @world ||= RSpec::Core::World.new
-  end
-
-  # @private
-  # Used internally to set the global object
-  def self.world=(new_world)
-    @world = new_world
-  end
+  extend RSpec::Core::Warnings
 
-  # @private
-  # Used internally to ensure examples get reloaded between multiple runs in
+  # Used to ensure examples get reloaded between multiple runs in
   # the same process.
+  #
+  # Users must invoke this if they want to have the configuration reset when
+  # they use runner multiple times within the same process.
   def self.reset
     @world = nil
     @configuration = nil
@@ -94,12 +66,6 @@ module RSpec
 
   end
 
-  # @private
-  # Used internally to set the global object
-  def self.configuration=(new_configuration)
-    @configuration = new_configuration
-  end
-
   # Yields the global configuration to a block.
   # @yield [Configuration] global configuration
   #
@@ -112,12 +78,6 @@ module RSpec
     yield configuration if block_given?
   end
 
-  # @private
-  # Used internally to clear remaining groups when fail_fast is set
-  def self.clear_remaining_example_groups
-    world.example_groups.clear
-  end
-
   # The example being executed.
   #
   # The primary audience for this method is library authors who need access
@@ -132,7 +92,7 @@ module RSpec
   #       fetch_current_example = RSpec.respond_to?(:current_example) ?
   #         proc { RSpec.current_example } : proc { |context| context.example }
   #
-  #       c.before(:each) do
+  #       c.before(:example) do
   #         example = fetch_current_example.call(self)
   #
   #         # ...
@@ -140,20 +100,29 @@ module RSpec
   #     end
   #
   def self.current_example
-    Thread.current[:_rspec_current_example]
+    thread_local_metadata[:current_example]
   end
 
   # Set the current example being executed.
   # @api private
   def self.current_example=(example)
-    Thread.current[:_rspec_current_example] = example
+    thread_local_metadata[:current_example] = example
   end
 
   # @private
-  def self.windows_os?
-    RbConfig::CONFIG['host_os'] =~ /cygwin|mswin|mingw|bccwin|wince|emx/
+  # A single thread local variable so we don't excessively pollute that
+  # namespace.
+  def self.thread_local_metadata
+    Thread.current[:_rspec] ||= {}
   end
 
+  # @private
+  # Internal container for global non-configuration data
+  def self.world
+    @world ||= RSpec::Core::World.new
+  end
+
+  # Namespace for the rspec-core code.
   module Core
     # @private
     # This avoids issues with reporting time caused by examples that
@@ -171,12 +140,14 @@ module RSpec
     end
   end
 
+  # @private
   MODULES_TO_AUTOLOAD = {
     :Matchers     => "rspec/expectations",
     :Expectations => "rspec/expectations",
     :Mocks        => "rspec/mocks"
   }
 
+  # @private
   def self.const_missing(name)
     # Load rspec-expectations when RSpec::Matchers is referenced. This allows
     # people to define custom matchers (using `RSpec::Matchers.define`) before
@@ -188,7 +159,7 @@ module RSpec
     #
     # As of rspec 2.14.1, we no longer require `rspec/mocks` and
     # `rspec/expectations` when `rspec` is required, so we want
-    # to make them available as an autoload. For more info, see:
+    # to make them available as an autoload.
     require MODULES_TO_AUTOLOAD.fetch(name) { return super }
     ::RSpec.const_get(name)
   end

data/lib/rspec/core/backport_random.rb

@@ -1,12 +1,40 @@
-# This code was (mostly) ported from the backports gem (https://github.com/marcandre/backports).
-# The goal is to provide a random number generator in Ruby versions that do not have one.
-# This was added to support localization of random spec ordering.
+# This code was (mostly) ported from the backports gem found at
+# https://github.com/marcandre/backports which is subject to this license:
+#
+# =============================================================================
+#
+# Copyright (c) 2009 Marc-Andre Lafortune
+#
+# Permission is hereby granted, free of charge, to any person obtaining
+# a copy of this software and associated documentation files (the
+# "Software"), to deal in the Software without restriction, including
+# without limitation the rights to use, copy, modify, merge, publish,
+# distribute, sublicense, and/or sell copies of the Software, and to
+# permit persons to whom the Software is furnished to do so, subject to
+# the following conditions:
+#
+# The above copyright notice and this permission notice shall be
+# included in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+# LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+# WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+#
+# =============================================================================
+#
+# The goal is to provide a random number generator in Ruby versions that do
+# not have one. This was added to support localization of random spec ordering.
 #
 # These were in multiple files in backports, but merged into one here.
 
 module RSpec
   module Core
     # Methods used internally by the backports.
+    # @private
     module Backports
       # Helper method to coerce a value into a specific class.
       # Raises a TypeError if the coercion fails or the returned value
@@ -25,6 +53,7 @@ module RSpec
         ret
       end
 
+      # @private
       def self.coerce_to_int(obj)
         coerce_to(obj, Integer, :to_int)
       end
@@ -33,7 +62,9 @@ module RSpec
       # (from Rubinius)
       Undefined = Object.new
 
+      # @private
       class Random
+        # @private
         # An implementation of Mersenne Twister MT19937 in Ruby
         class MT19937
           STATE_SIZE = 624
@@ -198,6 +229,7 @@ module RSpec
           end
         end
 
+        # @private
         # Implementation corresponding to the actual Random class of Ruby
         # The actual random generator (mersenne twister) is in MT19937.
         # Ruby specific conversions are handled in bits_and_bytes.

data/lib/rspec/core/backtrace_formatter.rb

@@ -1,13 +1,8 @@
 module RSpec
   module Core
+    # @private
     class BacktraceFormatter
-      # This is only used externally by rspec-expectations. Can be removed once
-      # rspec-expectations uses
-      # RSpec.configuration.backtrace_formatter.format_backtrace instead.
-      def self.format_backtrace(backtrace, options = {})
-        RSpec.configuration.backtrace_formatter.format_backtrace(backtrace, options)
-      end
-
+      # @private
       attr_accessor :exclusion_patterns, :inclusion_patterns
 
       def initialize
@@ -33,10 +28,8 @@ module RSpec
 
       def format_backtrace(backtrace, options = {})
         return backtrace if options[:full_backtrace]
-        backtrace.
-          take_while {|l| l != RSpec::Core::Runner::AT_EXIT_HOOK_BACKTRACE_LINE}.
-          map        {|l| backtrace_line(l)}.
-          compact.
+
+        backtrace.map { |l| backtrace_line(l) }.compact.
           tap do |filtered|
             if filtered.empty?
               filtered.concat backtrace
@@ -48,14 +41,12 @@ module RSpec
           end
       end
 
-      # @api private
       def backtrace_line(line)
         RSpec::Core::Metadata::relative_path(line) unless exclude?(line)
       rescue SecurityError
         nil
       end
 
-      # @api private
       def exclude?(line)
         return false if @full_backtrace
         matches_an_exclusion_pattern?(line) &&

data/lib/rspec/core/configuration.rb

@@ -1,7 +1,8 @@
 require 'fileutils'
-require 'rspec/core/backtrace_formatter'
-require 'rspec/core/ruby_project'
-require 'rspec/core/formatters/deprecation_formatter'
+
+RSpec::Support.require_rspec_core "backtrace_formatter"
+RSpec::Support.require_rspec_core "ruby_project"
+RSpec::Support.require_rspec_core "formatters/deprecation_formatter"
 
 module RSpec
   module Core
@@ -21,9 +22,9 @@ module RSpec
     #
     # @example Hooks
     #     RSpec.configure do |c|
-    #       c.before(:suite) { establish_connection }
-    #       c.before(:each)  { log_in_as :authorized }
-    #       c.around(:each)  { |ex| Database.transaction(&ex) }
+    #       c.before(:suite)   { establish_connection }
+    #       c.before(:example) { log_in_as :authorized }
+    #       c.around(:example) { |ex| Database.transaction(&ex) }
     #     end
     #
     # @see RSpec.configure
@@ -31,6 +32,7 @@ module RSpec
     class Configuration
       include RSpec::Core::Hooks
 
+      # @private
       class MustBeConfiguredBeforeExampleGroupsError < StandardError; end
 
       # @private
@@ -77,10 +79,11 @@ module RSpec
       end
 
       # @macro [attach] add_setting
-      #   @attribute $1
+      #   @!attribute [rw] $1
+      #   @!method $1=(value)
       #
       # @macro [attach] define_reader
-      #   @attribute $1
+      #   @!attribute [r] $1
 
       # @macro add_setting
       # Path to use if no path is provided to the `rspec` command (default:
@@ -121,9 +124,24 @@ module RSpec
         end
       end
 
-      # @macro add_setting
-      # Default: `$stderr`.
-      add_setting :deprecation_stream
+      # Determines where deprecation warnings are printed.
+      # Defaults to `$stderr`.
+      # @return [IO, String] IO to write to or filename to write to
+      define_reader :deprecation_stream
+
+      # Determines where deprecation warnings are printed.
+      # @param value [IO, String] IO to write to or filename to write to
+      def deprecation_stream=(value)
+        if @reporter && !value.equal?(@deprecation_stream)
+          warn "RSpec's reporter has already been initialized with " +
+            "#{deprecation_stream.inspect} as the deprecation stream, so your change to "+
+            "`deprecation_stream` will be ignored. You should configure it earlier for " +
+            "it to take effect, or use the `--deprecation-out` CLI option. " +
+            "(Called from #{CallerFilter.first_non_rspec_line})"
+        else
+          @deprecation_stream = value
+        end
+      end
 
       # @macro add_setting
       # Clean up and exit after the first failure (default: `false`).
@@ -143,13 +161,16 @@ module RSpec
       define_reader :requires
 
       # @macro define_reader
-      # Returns dirs that have been prepended to the load path by #lib=
+      # Returns dirs that have been prepended to the load path by the `-I` command line option
       define_reader :libs
 
       # @macro add_setting
+      # Determines where RSpec will send its output.
       # Default: `$stdout`.
-      # Also known as `output` and `out`
       define_reader :output_stream
+
+      # Set the output stream for reporter
+      # @attr value [IO] value for output, defaults to $stdout
       def output_stream=(value)
         if @reporter && !value.equal?(@output_stream)
           warn "RSpec's reporter has already been initialized with " +
@@ -163,15 +184,16 @@ module RSpec
 
       # @macro add_setting
       # Load files matching this pattern (default: `'**/*_spec.rb'`)
-      add_setting :pattern, :alias_with => :filename_pattern
+      add_setting :pattern
 
-      def pattern= value
+      # Set pattern to match files to load
+      # @attr value [String] the filename pattern to filter spec files by
+      def pattern=(value)
         if @spec_files_loaded
           RSpec.warning "Configuring `pattern` to #{value} has no effect since RSpec has already loaded the spec files."
         end
         @pattern = value
       end
-      alias :filename_pattern= :pattern=
 
       # @macro add_setting
       # Report the times for the slowest examples (default: `false`).
@@ -184,32 +206,44 @@ module RSpec
 
       # @macro add_setting
       # Color to use to indicate success.
-      # @param [Symbol] color one of the following: [:black, :white, :red, :green, :yellow, :blue, :magenta, :cyan]
+      # @param color [Symbol] defaults to `:green` but can be set to one of the
+      #                       following: `[:black, :white, :red, :green, :yellow,
+      #                       :blue, :magenta, :cyan]`
       add_setting :success_color
 
       # @macro add_setting
       # Color to use to print pending examples.
-      # @param [Symbol] color one of the following: [:black, :white, :red, :green, :yellow, :blue, :magenta, :cyan]
+      # @param color [Symbol] defaults to `:yellow` but can be set to one of the
+      #                       following: `[:black, :white, :red, :green, :yellow,
+      #                       :blue, :magenta, :cyan]`
       add_setting :pending_color
 
       # @macro add_setting
       # Color to use to indicate failure.
-      # @param [Symbol] color one of the following: [:black, :white, :red, :green, :yellow, :blue, :magenta, :cyan]
+      # @param color [Symbol] defaults to `:red` but can be set to one of the
+      #                       following: `[:black, :white, :red, :green, :yellow,
+      #                       :blue, :magenta, :cyan]`
       add_setting :failure_color
 
       # @macro add_setting
       # The default output color.
-      # @param [Symbol] color one of the following: [:black, :white, :red, :green, :yellow, :blue, :magenta, :cyan]
+      # @param color [Symbol] defaults to `:white` but can be set to one of the
+      #                       following:`[:black, :white, :red, :green, :yellow,
+      #                       :blue, :magenta, :cyan]`
       add_setting :default_color
 
       # @macro add_setting
       # Color used when a pending example is fixed.
-      # @param [Symbol] color one of the following: [:black, :white, :red, :green, :yellow, :blue, :magenta, :cyan]
+      # @param color [Symbol] defaults to `:blue` but can be set to one of the
+      #                       following: `[:black, :white, :red, :green, :yellow,
+      #                       :blue, :magenta, :cyan]`
       add_setting :fixed_color
 
       # @macro add_setting
       # Color used to print details.
-      # @param [Symbol] color one of the following: [:black, :white, :red, :green, :yellow, :blue, :magenta, :cyan]
+      # @param color [Symbol] defaults to `:cyan` but can be set to one of the
+      #                       following: `[:black, :white, :red, :green, :yellow,
+      #                       :blue, :magenta, :cyan]`
       add_setting :detail_color
 
       # Deprecated. This config option was added in RSpec 2 to pave the way
@@ -217,10 +251,13 @@ module RSpec
       # a no-op.
       def treat_symbols_as_metadata_keys_with_true_values=(value)
         RSpec.deprecate("RSpec::Core::Configuration#treat_symbols_as_metadata_keys_with_true_values=",
-                        :message => "RSpec::Core::Configuration#treat_symbols_as_metadata_keys_with_true_values=" +
+                        :message => "RSpec::Core::Configuration#treat_symbols_as_metadata_keys_with_true_values= " +
                                     "is deprecated, it is now set to true as default and setting it to false has no effect.")
       end
 
+      # Record the start time of the spec suite to measure load time
+      add_setting :start_time
+
       # @private
       add_setting :tty
       # @private
@@ -234,12 +271,8 @@ module RSpec
       # @private
       attr_reader :backtrace_formatter, :ordering_manager
 
-      # Alias for rspec-2.x's backtrace_cleaner (now backtrace_formatter)
-      #
-      # TODO: consider deprecating and removing this rather than aliasing in rspec-3?
-      alias backtrace_cleaner backtrace_formatter
-
       def initialize
+        @start_time = $_rspec_core_load_started_at || ::RSpec::Core::Time.now
         @expectation_frameworks = []
         @include_or_extend_modules = []
         @mock_framework = nil
@@ -255,6 +288,7 @@ module RSpec
         @deprecation_stream = $stderr
         @output_stream = $stdout
         @reporter = nil
+        @reporter_buffer = nil
         @filter_manager = FilterManager.new
         @ordering_manager = Ordering::ConfigurationManager.new
         @preferred_options = {}
@@ -267,6 +301,7 @@ module RSpec
         @profile_examples = false
         @requires = []
         @libs = []
+        @derived_metadata_blocks = []
       end
 
       # @private
@@ -275,7 +310,6 @@ module RSpec
       def force(hash)
         ordering_manager.force(hash)
         @preferred_options.merge!(hash)
-        self.warnings = value_for :warnings, nil
       end
 
       # @private
@@ -322,7 +356,7 @@ module RSpec
       #     RSpec.configuration.foo? # returns true if foo returns anything but nil or false
       def add_setting(name, opts={})
         default = opts.delete(:default)
-        (class << self; self; end).class_eval do
+        (class << self; self; end).class_exec do
           add_setting(name, opts)
         end
         __send__("#{name}=", default) if default
@@ -354,6 +388,8 @@ module RSpec
         @backtrace_formatter.exclusion_patterns
       end
 
+      # Set regular expressions used to exclude lines in backtrace
+      # @param patterns [Regexp] set the backtrace exlusion pattern
       def backtrace_exclusion_patterns=(patterns)
         @backtrace_formatter.exclusion_patterns = patterns
       end
@@ -370,11 +406,13 @@ module RSpec
         @backtrace_formatter.inclusion_patterns
       end
 
+      # Set regular expressions used to include lines in backtrace
+      # @attr patterns [Regexp] set backtrace_formatter inclusion_patterns
       def backtrace_inclusion_patterns=(patterns)
         @backtrace_formatter.inclusion_patterns = patterns
       end
 
-      # @api private
+      # @private
       MOCKING_ADAPTERS = {
         :rspec    => :RSpec,
         :flexmock => :Flexmock,
@@ -400,8 +438,8 @@ module RSpec
       #       - called before each example
       #
       #     verify_mocks_for_rspec
-      #       - called after each example. Framework should raise an exception
-      #         when expectations fail
+      #       - called after each example if the example hasn't yet failed.
+      #         Framework should raise an exception when expectations fail
       #
       #     teardown_mocks_for_rspec
       #       - called after verify_mocks_for_rspec (even if there are errors)
@@ -422,7 +460,7 @@ module RSpec
               "Pass a module or one of #{MOCKING_ADAPTERS.keys.inspect}"
           end
 
-          require "rspec/core/mocking_adapters/#{const_name.to_s.downcase}"
+          RSpec::Support.require_rspec_core "mocking_adapters/#{const_name.to_s.downcase}"
           RSpec::Core::MockingAdapters.const_get(const_name)
         end
 
@@ -456,16 +494,17 @@ module RSpec
       # Sets the expectation framework module(s) to be included in each example
       # group.
       #
-      # `frameworks` can be `:rspec`, `:stdlib`, a custom module, or any
-      # combination thereof:
+      # `frameworks` can be `:rspec`, `:test_unit`, `:minitest`, a custom
+      # module, or any combination thereof:
       #
       #     config.expect_with :rspec
-      #     config.expect_with :stdlib
-      #     config.expect_with :rspec, :stdlib
+      #     config.expect_with :test_unit
+      #     config.expect_with :minitest
+      #     config.expect_with :rspec, :minitest
       #     config.expect_with OtherExpectationFramework
       #
-      # RSpec will translate `:rspec` and `:stdlib` into the appropriate
-      # modules.
+      # RSpec will translate `:rspec`, `:minitest`, and `:test_unit` into the
+      # appropriate modules.
       #
       # ## Configuration
       #
@@ -484,9 +523,12 @@ module RSpec
             require 'rspec/expectations'
             self.expecting_with_rspec = true
             ::RSpec::Matchers
-          when :stdlib
-            require 'test/unit/assertions'
-            ::Test::Unit::Assertions
+          when :test_unit
+            require 'rspec/core/test_unit_assertions_adapter'
+            ::RSpec::Core::TestUnitAssertionsAdapter
+          when :minitest
+            require 'rspec/core/minitest_assertions_adapter'
+            ::RSpec::Core::MinitestAssertionsAdapter
           else
             raise ArgumentError, "#{framework.inspect} is not supported"
           end
@@ -505,25 +547,40 @@ module RSpec
         @expectation_frameworks.push(*modules)
       end
 
+      # Check if full backtrace is enabled
+      # @return [Boolean] is full backtrace enabled
       def full_backtrace?
         @backtrace_formatter.full_backtrace?
       end
 
+      # Toggle full backtrace
+      # @attr true_or_false [Boolean] toggle full backtrace display
       def full_backtrace=(true_or_false)
         @backtrace_formatter.full_backtrace = true_or_false
       end
 
-      def color(output=output_stream)
-        # rspec's built-in formatters all call this with the output argument,
-        # but defaulting to output_stream for backward compatibility with
-        # formatters in extension libs
-        return false unless output_to_tty?(output)
+      # Returns the configuration option for color, but should not
+      # be used to check if color is supported.
+      #
+      # @see color_enabled?
+      # @return [Boolean]
+      def color
         value_for(:color, @color)
       end
 
-      def color=(bool)
-        if bool
-          if RSpec.windows_os? and not ENV['ANSICON']
+      # Check if color is enabled for a particular output
+      # @param output [IO] an output stream to use, defaults to the current
+      #        `output_stream`
+      # @return [Boolean]
+      def color_enabled?(output = output_stream)
+        output_to_tty?(output) && color
+      end
+
+      # Toggle output color
+      # @attr true_or_false [Boolean] toggle color enabled
+      def color=(true_or_false)
+        if true_or_false
+          if RSpec.world.windows_os? and not ENV['ANSICON']
             RSpec.warning "You must use ANSICON 1.31 or later (http://adoxa.3eeweb.com/ansicon/) to use colour on Windows"
             @color = false
           else
@@ -532,12 +589,7 @@ module RSpec
         end
       end
 
-      # TODO - deprecate color_enabled - probably not until the last 2.x
-      # release before 3.0
-      alias_method :color_enabled, :color
-      alias_method :color_enabled=, :color=
-      define_predicate_for :color_enabled, :color
-
+      # @private
       def libs=(libs)
         libs.map do |lib|
           @libs.unshift lib
@@ -545,19 +597,13 @@ module RSpec
         end
       end
 
-      # Run examples defined on `line_numbers` in all files to run.
-      def line_numbers=(line_numbers)
-        filter_run :line_numbers => line_numbers.map{|l| l.to_i}
-      end
-
-      def line_numbers
-        filter.fetch(:line_numbers,[])
-      end
-
+      # Run examples matching on `description` in all files to run.
+      # @param description [String, Regexp] the pattern to filter on
       def full_description=(description)
         filter_run :full_description => Regexp.union(*Array(description).map {|d| Regexp.new(d) })
       end
 
+      # @return [Array] full description filter
       def full_description
         filter.fetch :full_description, nil
       end
@@ -579,21 +625,70 @@ module RSpec
       end
       alias_method :formatter=, :add_formatter
 
-      # @api private
+      # The formatter that will be used if no formatter has been set.
+      # Defaults to 'progress'.
+      def default_formatter
+        formatter_loader.default_formatter
+      end
+
+      # Sets a fallback formatter to use if none other has been set.
+      #
+      # @example
+      #
+      #   RSpec.configure do |rspec|
+      #     rspec.default_formatter = 'doc'
+      #   end
+      def default_formatter=(value)
+        formatter_loader.default_formatter = value
+      end
+
+      # Returns a duplicate of the formatters currently loaded in
+      # the `FormatterLoader` for introspection.
+      #
+      # Note as this is a duplicate, any mutations will be disregarded.
+      #
+      # @return [Array] the formatters currently loaded
       def formatters
-        formatter_loader.formatters
+        formatter_loader.formatters.dup
       end
 
-      # @api private
+      # @private
       def formatter_loader
         @formatter_loader ||= Formatters::Loader.new(Reporter.new(self))
       end
 
-      # @api private
+      # @private
+      #
+      # This buffer is used to capture all messages sent to the reporter during
+      # reporter initialization. It can then replay those messages after the
+      # formatter is correctly initialized. Otherwise, deprecation warnings
+      # during formatter initialization can cause an infinite loop.
+      class DeprecationReporterBuffer
+        def initialize
+          @calls = []
+        end
+
+        def deprecation(*args)
+          @calls << args
+        end
+
+        def play_onto(reporter)
+          @calls.each do |args|
+            reporter.deprecation(*args)
+          end
+        end
+      end
+
+      # @private
       def reporter
-        @reporter ||=
+        # @reporter_buffer should only ever be set in this method to cover
+        # initialization of @reporter.
+        @reporter_buffer || @reporter ||=
           begin
+            @reporter_buffer = DeprecationReporterBuffer.new
             formatter_loader.setup_default output_stream, deprecation_stream
+            @reporter_buffer.play_onto(formatter_loader.reporter)
+            @reporter_buffer = nil
             formatter_loader.reporter
           end
       end
@@ -619,54 +714,70 @@ module RSpec
         @files_to_run = nil
       end
 
+      # The spec files RSpec will run
+      # @return [Array] specified files about to run
       def files_to_run
         @files_to_run ||= get_files_to_run(@files_or_directories_to_run)
       end
 
       # Creates a method that delegates to `example` including the submitted
       # `args`. Used internally to add variants of `example` like `pending`:
+      # @param name [String] example name alias
+      # @param args [Array<Symbol>, Hash] metadata for the generated example
+      #
+      # @note The specific example alias below (`pending`) is already
+      #   defined for you.
+      # @note Use with caution. This extends the language used in your
+      #   specs, but does not add any additional documentation.  We use this
+      #   in rspec to define methods like `focus` and `xit`, but we also add
+      #   docs for those methods.
       #
       # @example
-      #     alias_example_to :pending, :pending => true
+      #   RSpec.configure do |config|
+      #     config.alias_example_to :pending, :pending => true
+      #   end
       #
-      #     # This lets you do this:
+      #   # This lets you do this:
       #
-      #     describe Thing do
-      #       pending "does something" do
-      #         thing = Thing.new
-      #       end
+      #   describe Thing do
+      #     pending "does something" do
+      #       thing = Thing.new
       #     end
+      #   end
       #
-      #     # ... which is the equivalent of
+      #   # ... which is the equivalent of
       #
-      #     describe Thing do
-      #       it "does something", :pending => true do
-      #         thing = Thing.new
-      #       end
+      #   describe Thing do
+      #     it "does something", :pending => true do
+      #       thing = Thing.new
       #     end
-      def alias_example_to(new_name, *args)
+      #   end
+      def alias_example_to(name, *args)
         extra_options = Metadata.build_hash_from(args)
-        RSpec::Core::ExampleGroup.alias_example_to(new_name, extra_options)
+        RSpec::Core::ExampleGroup.define_example_method(name, extra_options)
       end
 
       # Creates a method that defines an example group with the provided
       # metadata. Can be used to define example group/metadata shortcuts.
       #
       # @example
-      #     alias_example_group_to :describe_model, :type => :model
-      #     shared_context_for "model tests", :type => :model do
-      #       # define common model test helper methods, `let` declarations, etc
-      #     end
+      #   RSpec.configure do |config|
+      #     config.alias_example_group_to :describe_model, :type => :model
+      #   end
       #
-      #     # This lets you do this:
+      #   shared_context_for "model tests", :type => :model do
+      #     # define common model test helper methods, `let` declarations, etc
+      #   end
       #
-      #     RSpec.describe_model User do
-      #     end
+      #   # This lets you do this:
       #
-      #     # ... which is the equivalent of
+      #   RSpec.describe_model User do
+      #   end
       #
-      #     RSpec.describe User, :type => :model do
-      #     end
+      #   # ... which is the equivalent of
+      #
+      #   RSpec.describe User, :type => :model do
+      #   end
       #
       # @note The defined aliased will also be added to the top level
       #       (e.g. `main` and from within modules) if
@@ -675,34 +786,38 @@ module RSpec
       # @see #expose_dsl_globally=
       def alias_example_group_to(new_name, *args)
         extra_options = Metadata.build_hash_from(args)
-        RSpec::Core::ExampleGroup.alias_example_group_to(new_name, extra_options)
+        RSpec::Core::ExampleGroup.define_example_group_method(new_name, extra_options)
       end
 
       # Define an alias for it_should_behave_like that allows different
       # language (like "it_has_behavior" or "it_behaves_like") to be
       # employed when including shared examples.
       #
-      # Example:
-      #
-      #     alias_it_behaves_like_to(:it_has_behavior, 'has behavior:')
+      # @example
+      #   RSpec.configure do |config|
+      #     config.alias_it_behaves_like_to(:it_has_behavior, 'has behavior:')
+      #   end
       #
-      # allows the user to include a shared example group like:
+      #   # allows the user to include a shared example group like:
       #
-      #     describe Entity do
-      #       it_has_behavior 'sortability' do
-      #         let(:sortable) { Entity.new }
-      #       end
+      #   describe Entity do
+      #     it_has_behavior 'sortability' do
+      #       let(:sortable) { Entity.new }
       #     end
+      #   end
       #
-      # which is reported in the output as:
+      #   # which is reported in the output as:
+      #   # Entity
+      #   #   has behavior: sortability
+      #   #     ...sortability examples here
       #
-      #     Entity
-      #       has behavior: sortability
-      #         # sortability examples here
+      # @note Use with caution. This extends the language used in your
+      #   specs, but does not add any additional documentation.  We use this
+      #   in rspec to define `it_should_behave_like` (for backward
+      #   compatibility), but we also add docs for that method.
       def alias_it_behaves_like_to(new_name, report_label = '')
-        RSpec::Core::ExampleGroup.alias_it_behaves_like_to(new_name, report_label)
+        RSpec::Core::ExampleGroup.define_nested_shared_group_method(new_name, report_label)
       end
-
       alias_method :alias_it_should_behave_like_to, :alias_it_behaves_like_to
 
       # Adds key/value pairs to the `inclusion_filter`. If `args`
@@ -748,7 +863,7 @@ module RSpec
       # This overrides any inclusion filters/tags set on the command line or in
       # configuration files.
       def inclusion_filter=(filter)
-        filter_manager.include! Metadata.build_hash_from([filter])
+        filter_manager.include_only Metadata.build_hash_from([filter])
       end
 
       alias_method :filter=, :inclusion_filter=
@@ -802,7 +917,7 @@ module RSpec
       # This overrides any exclusion filters/tags set on the command line or in
       # configuration files.
       def exclusion_filter=(filter)
-        filter_manager.exclude! Metadata.build_hash_from([filter])
+        filter_manager.exclude_only Metadata.build_hash_from([filter])
       end
 
       # Returns the `exclusion_filter`. If none has been set, returns an empty
@@ -906,10 +1021,12 @@ module RSpec
 
       # @private
       if RUBY_VERSION.to_f >= 1.9
+        # @private
         def safe_extend(mod, host)
           host.extend(mod) unless host.singleton_class < mod
         end
       else
+        # @private
         def safe_extend(mod, host)
           host.extend(mod) unless (class << host; self; end).included_modules.include?(mod)
         end
@@ -918,6 +1035,7 @@ module RSpec
       # @private
       def configure_mock_framework
         RSpec::Core::ExampleGroup.__send__(:include, mock_framework)
+        conditionally_disable_mocks_monkey_patching
       end
 
       # @private
@@ -925,6 +1043,7 @@ module RSpec
         expectation_frameworks.each do |framework|
           RSpec::Core::ExampleGroup.__send__(:include, framework)
         end
+        conditionally_disable_expectations_monkey_patching
       end
 
       # @private
@@ -1015,11 +1134,12 @@ module RSpec
       delegate_to_ordering_manager :seed_used?, :ordering_registry
 
       # Set Ruby warnings on or off
-      def warnings= value
+      def warnings=(value)
         $VERBOSE = !!value
       end
 
-      def warnings
+      # @return [Boolean] Whether or not ruby warnings are enabled.
+      def warnings?
         $VERBOSE
       end
 
@@ -1046,7 +1166,7 @@ module RSpec
       #     end
       #   end
       def expose_current_running_example_as(method_name)
-        ExposeCurrentExample.module_eval do
+        ExposeCurrentExample.module_exec do
           extend RSpec::SharedContext
           let(method_name) { |ex| ex }
         end
@@ -1054,6 +1174,7 @@ module RSpec
         include ExposeCurrentExample
       end
 
+      # @private
       module ExposeCurrentExample; end
 
       # Turns deprecation warnings into errors, in order to surface
@@ -1070,6 +1191,78 @@ module RSpec
         self.deprecation_stream = Formatters::DeprecationFormatter::RaiseErrorStream.new
       end
 
+      # Enables zero monkey patching mode for RSpec. It removes monkey
+      # patching of the top-level DSL methods (`describe`,
+      # `shared_examples_for`, etc) onto `main` and `Module`, instead
+      # requiring you to prefix these methods with `RSpec.`. It enables
+      # expect-only syntax for rspec-mocks and rspec-expectations. It
+      # simply disables monkey patching on whatever pieces of rspec
+      # the user is using.
+      #
+      # @note It configures rspec-mocks and rspec-expectations only
+      #   if the user is using those (either explicitly or implicitly
+      #   by not setting `mock_with` or `expect_with` to anything else).
+      #
+      # @note If the user uses this options with `mock_with :mocha`
+      #   (or similiar) they will still have monkey patching active
+      #   in their test environment from mocha.
+      #
+      # @example
+      #
+      #   # It disables all monkey patching
+      #   RSpec.configure do |config|
+      #     config.disable_monkey_patching!
+      #   end
+      #
+      #   # Is an equivalent to
+      #   RSpec.configure do |config|
+      #     config.expose_dsl_globally = false
+      #
+      #     config.mock_with :rspec do |mocks|
+      #       mocks.syntax = :expect
+      #       mocks.patch_marshal_to_support_partial_doubles = false
+      #     end
+      #
+      #     config.mock_with :rspec do |expectations|
+      #       expectations.syntax = :expect
+      #     end
+      #   end
+      def disable_monkey_patching!
+        self.expose_dsl_globally = false
+        self.disable_monkey_patching = true
+        conditionally_disable_mocks_monkey_patching
+        conditionally_disable_expectations_monkey_patching
+      end
+
+      # @private
+      attr_accessor :disable_monkey_patching
+
+      # Defines a callback that can assign derived metadata values.
+      #
+      # @param filters [Array<Symbol>, Hash] metadata filters that determine which example
+      #   or group metadata hashes the callback will be triggered for. If none are given,
+      #   the callback will be run against the metadata hashes of all groups and examples.
+      # @yieldparam metadata [Hash] original metadata hash from an example or group. Mutate this in
+      #   your block as needed.
+      #
+      # @example
+      #   RSpec.configure do |config|
+      #     # Tag all groups and examples in the spec/unit directory with :type => :unit
+      #     config.define_derived_metadata(:file_path => %r{/spec/unit/}) do |metadata|
+      #       metadata[:type] = :unit
+      #     end
+      #   end
+      def define_derived_metadata(*filters, &block)
+        @derived_metadata_blocks << [Metadata.build_hash_from(filters), block]
+      end
+
+      # @private
+      def apply_derived_metadata_to(metadata)
+        @derived_metadata_blocks.each do |filter, block|
+          block.call(metadata) if filter.empty? || MetadataFilter.any_apply?(filter, metadata)
+        end
+      end
+
     private
 
       def get_files_to_run(paths)
@@ -1113,6 +1306,29 @@ module RSpec
       def output_to_tty?(output=output_stream)
         tty? || (output.respond_to?(:tty?) && output.tty?)
       end
+
+      def conditionally_disable_mocks_monkey_patching
+        return unless disable_monkey_patching && rspec_mocks_loaded?
+
+        RSpec::Mocks.configuration.tap do |config|
+          config.syntax = :expect
+          config.patch_marshal_to_support_partial_doubles = false
+        end
+      end
+
+      def conditionally_disable_expectations_monkey_patching
+        return unless disable_monkey_patching && rspec_expectations_loaded?
+
+        RSpec::Expectations.configuration.syntax = :expect
+      end
+
+      def rspec_mocks_loaded?
+        defined?(RSpec::Mocks.configuration)
+      end
+
+      def rspec_expectations_loaded?
+        defined?(RSpec::Expectations.configuration)
+      end
     end
   end
 end