rspec-core 3.1.7 → 3.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: dc437d7748b2d4e51abc67ecdee4b3222ddbee53
-  data.tar.gz: fa6c35c84c11393fa3f72dd0bdd8712e31b8ca9e
+  metadata.gz: 64add3bc6c923a094fe43e64de951766afb3d546
+  data.tar.gz: a6edfdd40534051c51205124394016d6ee23b90c
 SHA512:
-  metadata.gz: cc7190d5420cb26fa663b62e4355284b6a869300c118b6ea535d37f5d86bfc8ce9199259f1c1036be7b4193090e03db2e57ef8b7e41574cfb69c239349479a54
-  data.tar.gz: 0f213b46212dfe8233f1d7466f7e519ef375b6eb1757db8f4a3cdaf630554d43588bf248385eaa79ae0b0d523acb3800493e84e3c31d9c26b1dfc23867db161a
+  metadata.gz: ee07178fc56ffde6a07f6f1488acc6a468eda931765714b06f995e073fe539a5468e1b4c31f878761f226fe9223252d078ef43bd2d7c114b03c2352c4baa0600
+  data.tar.gz: 370912d590a0243d8f2b532a49e513c87855cfe8ebf3d6d1e6bad896e5011c3fb9fcff932a09fdcefb1d7bef4ebfbf5153f023cac9ca2c2769747c2984d0168f

data/.yardopts

@@ -3,5 +3,6 @@
 --markup markdown
 --default-return void
 -
+Filtering.md
 Changelog.md
 License.txt

data/Changelog.md

@@ -1,3 +1,84 @@
+### 3.2.0 / 2015-02-03
+[Full Changelog](http://github.com/rspec/rspec-core/compare/v3.1.7...v3.2.0)
+
+Enhancements:
+
+* Improve the `inspect` output of example groups. (Mike Dalton, #1687)
+* When rake task fails, only output the command if `verbose` flag is
+  set. (Ben Snape, #1704)
+* Add `RSpec.clear_examples` as a clear way to reset examples in between
+  spec runs, whilst retaining user configuration.  (Alexey Fedorov, #1706)
+* Reduce string allocations when defining and running examples by 70%
+  and 50% respectively. (Myron Marston, #1738)
+* Removed dependency on pathname from stdlib. (Sam Phippen, #1703)
+* Improve the message presented when a user hits Ctrl-C.
+  (Alex Chaffee #1717, #1742)
+* Improve shared example group inclusion backtrace displayed
+  in failed example output so that it works for all methods
+  of including shared example groups and shows all inclusion
+  locations. (Myron Marston, #1763)
+* Issue seed notification at start (as well as the end) of the reporter
+  run. (Arlandis Word, #1761)
+* Improve the documentation of around hooks. (Jim Kingdon, #1772)
+* Support prepending of modules into example groups from config and allow
+  filtering based on metadata. (Arlandis Word, #1806)
+* Emit warnings when `:suite` hooks are registered on an example group
+  (where it has always been ignored) or are registered with metadata
+  (which has always been ignored). (Myron Marston, #1805)
+* Provide a friendly error message when users call RSpec example group
+  APIs (e.g. `context`, `describe`, `it`, `let`, `before`, etc) from
+  within an example where those APIs are unavailable. (Myron Marston, #1819)
+* Provide a friendly error message when users call RSpec example
+  APIs (e.g. `expect`, `double`, `stub_const`, etc) from
+  within an example group where those APIs are unavailable.
+  (Myron Marston, #1819)
+* Add new `RSpec::Core::Sandbox.sandboxed { }` API that facilitates
+  testing RSpec with RSpec, allowing you to define example groups
+  and example from within an example without affecting the global
+  `RSpec.world` state. (Tyler Ball, 1808)
+* Apply line-number filters only to the files they are scoped to,
+  allowing you to mix filtered and unfiltered files. (Myron Marston, #1839)
+* When dumping pending examples, include the failure details so that you
+  don't have to un-pend the example to see it. (Myron Marston, #1844)
+* Make `-I` option support multiple values when separated by
+  `File::PATH_SEPARATOR`, such as `rspec -I foo:bar`. This matches
+  the behavior of Ruby's `-I` option. (Fumiaki Matsushima, #1855).
+
+Bug Fixes:
+
+* When assigning generated example descriptions, surface errors
+  raised by `matcher.description` in the example description.
+  (Myron Marston, #1771)
+* Don't consider expectations from `after` hooks when generating
+  example descriptions. (Myron Marston, #1771)
+* Don't apply metadata-filtered config hooks to examples in groups
+  with matching metadata when those examples override the parent
+  metadata value to not match. (Myron Marston, #1796)
+* Fix `config.expect_with :minitest` so that `skip` uses RSpec's
+  implementation rather than Minitest's. (Jonathan Rochkind, #1822)
+* Fix `NameError` caused when duplicate example group aliases are defined and
+  the DSL is not globally exposed. (Aaron Kromer, #1825)
+* When a shared example defined in an external file fails, use the host
+  example group (from a loaded spec file) for the re-run command to
+  ensure the command will actually work. (Myron Marston, #1835)
+* Fix location filtering to work properly for examples defined in
+  a nested example group within a shared example group defined in
+  an external file. (Bradley Schaefer, Xavier Shay, Myron Marston, #1837)
+* When a pending example fails (as expected) due to a mock expectation,
+  set `RSpec::Core::Example::ExecutionResult#pending_exception` --
+  previously it was not being set but should have been. (Myron Marston, #1844)
+* Fix rake task to work when `rspec-core` is installed in a directory
+  containing a space. (Guido Günther, #1845)
+* Fix regression in 3.1 that caused `describe Regexp` to raise errors.
+  (Durran Jordan, #1853)
+* Fix regression in 3.x that caused the profile information to be printed
+  after the summary. (Max Lincoln, #1857)
+* Apply `--seed` before loading `--require` files so that required files
+  can access the provided seed. (Myron Marston, #1745)
+* Handle `RSpec::Core::Formatters::DeprecationFormatter::FileStream` being
+  reopened with an IO stream, which sometimes happens with spring.
+  (Kevin Mook, #1757)
+
 ### 3.1.7 / 2014-10-11
 [Full Changelog](http://github.com/rspec/rspec-core/compare/v3.1.6...v3.1.7)
 
@@ -456,6 +537,9 @@ Bug Fixes:
   directory (was broken in beta1). (Jon Rowe)
 * Prevent RSpec mangling file names that have substrings containing `line_number`
   or `default_path`. (Matijs van Zuijlen)
+* Fix failure line detection so that it handles relative file paths
+  (which can happen when running specs through `ruby` using `rspec/autorun`).
+  (Myron Marston, #1829)
 
 ### 3.0.0.beta1 / 2013-11-07
 [Full Changelog](http://github.com/rspec/rspec-core/compare/v2.99.1...v3.0.0.beta1)

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.svg?branch=master)](http://travis-ci.org/rspec/rspec-core) [![Code Climate](https://codeclimate.com/github/rspec/rspec-core.svg)](https://codeclimate.com/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
@@ -10,6 +10,15 @@ examples get run and tailor the output.
     gem install rspec-core # for rspec-core only
     rspec --help
 
+Want to run against the `master` branch? You'll need to include the dependent
+RSpec repos as well. Add the following to your `Gemfile`:
+
+```ruby
+%w[rspec-core rspec-expectations rspec-mocks rspec-support].each do |lib|
+  gem lib, :git => "git://github.com/rspec/#{lib}.git", :branch => 'master'
+end
+```
+
 ## basic structure
 
 RSpec uses the words "describe" and "it" so we can express concepts like a conversation:

data/lib/rspec/core.rb

@@ -43,18 +43,38 @@ module RSpec
 
   extend RSpec::Core::Warnings
 
-  # Used to ensure examples get reloaded between multiple runs in
-  # the same process.
+  class << self
+    # Setters for shared global objects
+    # @api private
+    attr_writer :configuration, :world
+  end
+
+  # Used to ensure examples get reloaded and user configuration gets reset to
+  # defaults 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.
+  # they use the runner multiple times within the same process. Users must deal
+  # themselves with re-configuration of RSpec before run.
   def self.reset
     @world = nil
     @configuration = nil
   end
 
-  # Returns the global [Configuration](RSpec/Core/Configuration) object. While you
-  # _can_ use this method to access the configuration, the more common
+  # Used to ensure examples get reloaded between multiple runs in the same
+  # process and ensures user configuration is persisted.
+  #
+  # Users must invoke this if they want to clear all examples but preserve
+  # current configuration when they use the runner multiple times within the
+  # same process.
+  def self.clear_examples
+    world.reset
+    configuration.reporter.reset
+    configuration.start_time = ::RSpec::Core::Time.now
+    configuration.reset_filters
+  end
+
+  # Returns the global [Configuration](RSpec/Core/Configuration) object. While
+  # you _can_ use this method to access the configuration, the more common
   # convention is to use [RSpec.configure](RSpec#configure-class_method).
   #
   # @example
@@ -116,11 +136,11 @@ module RSpec
   # A single thread local variable so we don't excessively pollute that
   # namespace.
   def self.thread_local_metadata
-    Thread.current[:_rspec] ||= {}
+    Thread.current[:_rspec] ||= { :shared_example_group_inclusions => [] }
   end
 
   # @private
-  # Internal container for global non-configuration data
+  # Internal container for global non-configuration data.
   def self.world
     @world ||= RSpec::Core::World.new
   end
@@ -137,7 +157,7 @@ module RSpec
       end
     end
 
-    # @private path to executable file
+    # @private path to executable file.
     def self.path_to_executable
       @path_to_executable ||= File.expand_path('../../../exe/rspec', __FILE__)
     end

data/lib/rspec/core/backport_random.rb

@@ -60,14 +60,14 @@ module RSpec
         coerce_to(obj, Integer, :to_int)
       end
 
-      # Used internally to make it easy to deal with optional arguments
+      # Used internally to make it easy to deal with optional arguments.
       # (from Rubinius)
       Undefined = Object.new
 
       # @private
       class Random
         # @private
-        # An implementation of Mersenne Twister MT19937 in Ruby
+        # An implementation of Mersenne Twister MT19937 in Ruby.
         class MT19937
           STATE_SIZE = 624
           LAST_STATE = STATE_SIZE - 1
@@ -92,9 +92,10 @@ module RSpec
           end
 
           # Seed must be either an Integer (only the first 32 bits will be used)
-          # or an Array of Integers (of which only the first 32 bits will be used)
+          # or an Array of Integers (of which only the first 32 bits will be
+          # used).
           #
-          # No conversion or type checking is done at this level
+          # No conversion or type checking is done at this level.
           def seed=(seed)
             case seed
             when Integer
@@ -129,7 +130,7 @@ module RSpec
             end
           end
 
-          # Returns a random Integer from the range 0 ... (1 << 32)
+          # Returns a random Integer from the range 0 ... (1 << 32).
           def random_32_bits
             next_state if @last_read >= LAST_STATE
             @last_read += 1
@@ -146,12 +147,12 @@ module RSpec
           # No argument checking is done here either.
 
           FLOAT_FACTOR = 1.0/9007199254740992.0
-          # generates a random number on [0,1) with 53-bit resolution
+          # Generates a random number on [0, 1) with 53-bit resolution.
           def random_float
             ((random_32_bits >> 5) * 67108864.0 + (random_32_bits >> 6)) * FLOAT_FACTOR;
           end
 
-          # Returns an integer within 0...upto
+          # Returns an integer within 0...upto.
           def random_integer(upto)
             n = upto - 1
             nb_full_32 = 0
@@ -202,7 +203,8 @@ module RSpec
             end
           end
 
-          # Convert an Integer seed of arbitrary size to either a single 32 bit integer, or an Array of 32 bit integers
+          # Convert an Integer seed of arbitrary size to either a single 32 bit
+          # integer, or an Array of 32 bit integers.
           def self.convert_seed(seed)
             seed = seed.abs
             long_values = []
@@ -211,7 +213,8 @@ module RSpec
               seed >>= 32
             end until seed == 0
 
-            long_values.pop if long_values[-1] == 1 && long_values.size > 1 # Done to allow any kind of sequence of integers
+            # Done to allow any kind of sequence of integers.
+            long_values.pop if long_values[-1] == 1 && long_values.size > 1
 
             long_values.size > 1 ? long_values : long_values.first
           end

data/lib/rspec/core/configuration.rb

@@ -32,15 +32,23 @@ module RSpec
     class Configuration
       include RSpec::Core::Hooks
 
+      # Module that holds `attr_reader` declarations. It's in a separate
+      # module to allow us to override those methods and use `super`.
+      # @private
+      Readers = Module.new
+      include Readers
+
       # @private
       class MustBeConfiguredBeforeExampleGroupsError < StandardError; end
 
       # @private
       def self.define_reader(name)
-        define_method(name) do
-          variable = instance_variable_defined?("@#{name}") ? instance_variable_get("@#{name}") : nil
-          value_for(name, variable)
+        Readers.class_eval do
+          remove_method name if method_defined?(name)
+          attr_reader name
         end
+
+        define_method(name) { value_for(name) { super() } }
       end
 
       # @private
@@ -71,7 +79,7 @@ module RSpec
 
       # @private
       #
-      # As `add_setting` but only add the reader
+      # As `add_setting` but only add the reader.
       def self.add_read_only_setting(name, opts={})
         raise "Use the instance add_setting method if you want to set a default" if opts.key?(:default)
         define_reader name
@@ -90,8 +98,8 @@ module RSpec
       # `"spec"`). Allows you to just type `rspec` instead of `rspec spec` to
       # run all the examples in the `spec` directory.
       #
-      # Note: Other scripts invoking `rspec` indirectly will ignore this
-      # setting.
+      # @note Other scripts invoking `rspec` indirectly will ignore this
+      #   setting.
       add_setting :default_path
 
       # @macro add_setting
@@ -160,11 +168,12 @@ module RSpec
       add_setting :failure_exit_code
 
       # @macro define_reader
-      # Indicates files configured to be required
+      # Indicates files configured to be required.
       define_reader :requires
 
       # @macro define_reader
-      # Returns dirs that have been prepended to the load path by the `-I` command line option
+      # Returns dirs that have been prepended to the load path by the `-I`
+      # command line option.
       define_reader :libs
 
       # @macro add_setting
@@ -172,7 +181,7 @@ module RSpec
       # Default: `$stdout`.
       define_reader :output_stream
 
-      # Set the output stream for reporter
+      # 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)
@@ -186,20 +195,20 @@ module RSpec
       end
 
       # @macro define_reader
-      # Load files matching this pattern (default: `'**{,/*/**}/*_spec.rb'`)
+      # Load files matching this pattern (default: `'**{,/*/**}/*_spec.rb'`).
       define_reader :pattern
 
-      # Set pattern to match files to load
+      # Set pattern to match files to load.
       # @attr value [String] the filename pattern to filter spec files by
       def pattern=(value)
         update_pattern_attr :pattern, value
       end
 
       # @macro define_reader
-      # Exclude files matching this pattern
+      # Exclude files matching this pattern.
       define_reader :exclude_pattern
 
-      # Set pattern to match files to exclude
+      # Set pattern to match files to exclude.
       # @attr value [String] the filename pattern to exclude spec files by
       def exclude_pattern=(value)
         update_pattern_attr :exclude_pattern, value
@@ -211,84 +220,93 @@ module RSpec
       add_setting :profile_examples
 
       # @macro add_setting
-      # Run all examples if none match the configured filters (default: `false`).
+      # Run all examples if none match the configured filters
+      # (default: `false`).
       add_setting :run_all_when_everything_filtered
 
       # @macro add_setting
       # Color to use to indicate success.
       # @param color [Symbol] defaults to `:green` but can be set to one of the
-      #                       following: `[:black, :white, :red, :green, :yellow,
-      #                       :blue, :magenta, :cyan]`
+      #   following: `[:black, :white, :red, :green, :yellow, :blue, :magenta,
+      #   :cyan]`
       add_setting :success_color
 
       # @macro add_setting
       # Color to use to print pending examples.
       # @param color [Symbol] defaults to `:yellow` but can be set to one of the
-      #                       following: `[:black, :white, :red, :green, :yellow,
-      #                       :blue, :magenta, :cyan]`
+      #   following: `[:black, :white, :red, :green, :yellow, :blue, :magenta,
+      #   :cyan]`
       add_setting :pending_color
 
       # @macro add_setting
       # Color to use to indicate failure.
       # @param color [Symbol] defaults to `:red` but can be set to one of the
-      #                       following: `[:black, :white, :red, :green, :yellow,
-      #                       :blue, :magenta, :cyan]`
+      #   following: `[:black, :white, :red, :green, :yellow, :blue, :magenta,
+      #   :cyan]`
       add_setting :failure_color
 
       # @macro add_setting
       # The default output color.
       # @param color [Symbol] defaults to `:white` but can be set to one of the
-      #                       following:`[:black, :white, :red, :green, :yellow,
-      #                       :blue, :magenta, :cyan]`
+      #   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 color [Symbol] defaults to `:blue` but can be set to one of the
-      #                       following: `[:black, :white, :red, :green, :yellow,
-      #                       :blue, :magenta, :cyan]`
+      #   following: `[:black, :white, :red, :green, :yellow, :blue, :magenta,
+      #   :cyan]`
       add_setting :fixed_color
 
       # @macro add_setting
       # Color used to print details.
       # @param color [Symbol] defaults to `:cyan` but can be set to one of the
-      #                       following: `[:black, :white, :red, :green, :yellow,
-      #                       :blue, :magenta, :cyan]`
+      #   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
       # for this being the default behavior in RSpec 3. Now this option is
       # 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= " \
-                                    "is deprecated, it is now set to true as default and setting it to false has no effect.")
+        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= " \
+                      "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
+      # Record the start time of the spec suite to measure load time.
       add_setting :start_time
 
       # @private
       add_setting :tty
       # @private
-      add_setting :include_or_extend_modules
-      # @private
       attr_writer :files_to_run
       # @private
-      add_setting :expecting_with_rspec
-      # @private
       attr_accessor :filter_manager
       # @private
-      attr_reader :backtrace_formatter, :ordering_manager
+      attr_accessor :static_config_filter_manager
+      # @private
+      attr_reader :backtrace_formatter, :ordering_manager, :loaded_spec_files
 
       def initialize
         # rubocop:disable Style/GlobalVars
         @start_time = $_rspec_core_load_started_at || ::RSpec::Core::Time.now
         # rubocop:enable Style/GlobalVars
         @expectation_frameworks = []
-        @include_or_extend_modules = []
+        @include_modules = FilterableItemRepository::QueryOptimized.new(:any?)
+        @extend_modules  = FilterableItemRepository::QueryOptimized.new(:any?)
+        @prepend_modules = FilterableItemRepository::QueryOptimized.new(:any?)
+
+        @before_suite_hooks = []
+        @after_suite_hooks  = []
+
         @mock_framework = nil
         @files_or_directories_to_run = []
+        @loaded_spec_files = Set.new
         @color = false
         @pattern = '**{,/*/**}/*_spec.rb'
         @exclude_pattern = ''
@@ -303,6 +321,7 @@ module RSpec
         @reporter = nil
         @reporter_buffer = nil
         @filter_manager = FilterManager.new
+        @static_config_filter_manager = FilterManager.new
         @ordering_manager = Ordering::ConfigurationManager.new
         @preferred_options = {}
         @failure_color = :red
@@ -314,7 +333,7 @@ module RSpec
         @profile_examples = false
         @requires = []
         @libs = []
-        @derived_metadata_blocks = []
+        @derived_metadata_blocks = FilterableItemRepository::QueryOptimized.new(:any?)
       end
 
       # @private
@@ -332,18 +351,29 @@ module RSpec
         @formatter_loader = nil
       end
 
+      # @private
+      def reset_filters
+        self.filter_manager = FilterManager.new
+        filter_manager.include_only(
+          Metadata.deep_hash_dup(static_config_filter_manager.inclusions.rules)
+        )
+        filter_manager.exclude_only(
+          Metadata.deep_hash_dup(static_config_filter_manager.exclusions.rules)
+        )
+      end
+
       # @overload add_setting(name)
       # @overload add_setting(name, opts)
       # @option opts [Symbol] :default
       #
-      #   set a default value for the generated getter and predicate methods:
+      #   Set a default value for the generated getter and predicate methods:
       #
       #       add_setting(:foo, :default => "default value")
       #
       # @option opts [Symbol] :alias_with
       #
-      #   Use `:alias_with` to alias the setter, getter, and predicate to another
-      #   name, or names:
+      #   Use `:alias_with` to alias the setter, getter, and predicate to
+      #   another name, or names:
       #
       #       add_setting(:foo, :alias_with => :bar)
       #       add_setting(:foo, :alias_with => [:bar, :baz])
@@ -366,7 +396,7 @@ module RSpec
       #
       #     RSpec.configuration.foo=(value)
       #     RSpec.configuration.foo
-      #     RSpec.configuration.foo? # returns true if foo returns anything but nil or false
+      #     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_exec do
@@ -375,7 +405,7 @@ module RSpec
         __send__("#{name}=", default) if default
       end
 
-      # Returns the configured mock framework adapter module
+      # Returns the configured mock framework adapter module.
       def mock_framework
         if @mock_framework.nil?
           begin
@@ -387,7 +417,7 @@ module RSpec
         @mock_framework
       end
 
-      # Delegates to mock_framework=(framework)
+      # Delegates to mock_framework=(framework).
       def mock_framework=(framework)
         mock_with framework
       end
@@ -395,19 +425,19 @@ module RSpec
       # Regexps used to exclude lines from backtraces.
       #
       # Excludes lines from ruby (and jruby) source, installed gems, anything
-      # in any "bin" directory, and any of the rspec libs (outside gem
+      # in any "bin" directory, and any of the RSpec libs (outside gem
       # installs) by default.
       #
       # You can modify the list via the getter, or replace it with the setter.
       #
       # To override this behaviour and display a full backtrace, use
-      # `--backtrace`on the command line, in a `.rspec` file, or in the
+      # `--backtrace` on the command line, in a `.rspec` file, or in the
       # `rspec_options` attribute of RSpec's rake task.
       def backtrace_exclusion_patterns
         @backtrace_formatter.exclusion_patterns
       end
 
-      # Set regular expressions used to exclude lines in backtrace
+      # 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
@@ -425,7 +455,7 @@ module RSpec
         @backtrace_formatter.inclusion_patterns
       end
 
-      # Set regular expressions used to include lines in backtrace
+      # 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
@@ -485,8 +515,8 @@ module RSpec
       #     teardown_mocks_for_rspec
       #       - called after verify_mocks_for_rspec (even if there are errors)
       #
-      # If the module responds to `configuration` and `mock_with` receives a block,
-      # it will yield the configuration object to the block e.g.
+      # If the module responds to `configuration` and `mock_with` receives a
+      # block, it will yield the configuration object to the block e.g.
       #
       #     config.mock_with OtherMockFrameworkAdapter do |mod_config|
       #       mod_config.custom_setting = true
@@ -515,7 +545,8 @@ module RSpec
         end
 
         if block_given?
-          raise "#{framework_module} must respond to `configuration` so that mock_with can yield it." unless framework_module.respond_to?(:configuration)
+          raise "#{framework_module} must respond to `configuration` so that " \
+                "mock_with can yield it." unless framework_module.respond_to?(:configuration)
           yield framework_module.configuration
         end
 
@@ -534,7 +565,7 @@ module RSpec
         @expectation_frameworks
       end
 
-      # Delegates to expect_with(framework)
+      # Delegates to expect_with(framework).
       def expectation_framework=(framework)
         expect_with(framework)
       end
@@ -569,7 +600,6 @@ module RSpec
             framework
           when :rspec
             require 'rspec/expectations'
-            self.expecting_with_rspec = true
             ::RSpec::Matchers
           when :test_unit
             require 'rspec/core/test_unit_assertions_adapter'
@@ -587,21 +617,24 @@ module RSpec
         end
 
         if block_given?
-          raise "expect_with only accepts a block with a single argument. Call expect_with #{modules.length} times, once with each argument, instead." if modules.length > 1
-          raise "#{modules.first} must respond to `configuration` so that expect_with can yield it." unless modules.first.respond_to?(:configuration)
+          raise "expect_with only accepts a block with a single argument. " \
+                "Call expect_with #{modules.length} times, " \
+                "once with each argument, instead." if modules.length > 1
+          raise "#{modules.first} must respond to `configuration` so that " \
+                "expect_with can yield it." unless modules.first.respond_to?(:configuration)
           yield modules.first.configuration
         end
 
         @expectation_frameworks.push(*modules)
       end
 
-      # Check if full backtrace is enabled
+      # Check if full backtrace is enabled.
       # @return [Boolean] is full backtrace enabled
       def full_backtrace?
         @backtrace_formatter.full_backtrace?
       end
 
-      # Toggle full backtrace
+      # 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
@@ -613,10 +646,10 @@ module RSpec
       # @see color_enabled?
       # @return [Boolean]
       def color
-        value_for(:color, @color)
+        value_for(:color) { @color }
       end
 
-      # Check if color is enabled for a particular output
+      # 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]
@@ -624,13 +657,15 @@ module RSpec
         output_to_tty?(output) && color
       end
 
-      # Toggle output color
+      # Toggle output color.
       # @attr true_or_false [Boolean] toggle color enabled
       def color=(true_or_false)
         return unless true_or_false
 
-        if RSpec.world.windows_os? && !ENV['ANSICON']
-          RSpec.warning "You must use ANSICON 1.31 or later (http://adoxa.3eeweb.com/ansicon/) to use colour on Windows"
+        if RSpec::Support::OS.windows? && !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
           @color = true
@@ -743,10 +778,10 @@ module RSpec
 
       # @api private
       #
-      # Defaults `profile_examples` to 10 examples when `@profile_examples` is `true`.
-      #
+      # Defaults `profile_examples` to 10 examples when `@profile_examples` is
+      # `true`.
       def profile_examples
-        profile = value_for(:profile_examples, @profile_examples)
+        profile = value_for(:profile_examples) { @profile_examples }
         if profile && !profile.is_a?(Integer)
           10
         else
@@ -762,7 +797,7 @@ module RSpec
         @files_to_run = nil
       end
 
-      # The spec files RSpec will run
+      # 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)
@@ -776,8 +811,8 @@ module RSpec
       # @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
+      #   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
@@ -860,8 +895,8 @@ module RSpec
       #   #     ...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
+      #   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.define_nested_shared_group_method(new_name, report_label)
@@ -878,28 +913,30 @@ module RSpec
       # or config files (e.g. `.rspec`).
       #
       # @example
-      #     # given this declaration
+      #     # Given this declaration.
       #     describe "something", :foo => 'bar' do
       #       # ...
       #     end
       #
-      #     # any of the following will include that group
+      #     # Any of the following will include that group.
       #     config.filter_run_including :foo => 'bar'
       #     config.filter_run_including :foo => /^ba/
       #     config.filter_run_including :foo => lambda {|v| v == 'bar'}
       #     config.filter_run_including :foo => lambda {|v,m| m[:foo] == 'bar'}
       #
-      #     # given a proc with an arity of 1, the lambda is passed the value related to the key, e.g.
+      #     # Given a proc with an arity of 1, the lambda is passed the value
+      #     # related to the key, e.g.
       #     config.filter_run_including :foo => lambda {|v| v == 'bar'}
       #
-      #     # given a proc with an arity of 2, the lambda is passed the value related to the key,
-      #     # and the metadata itself e.g.
+      #     # Given a proc with an arity of 2, the lambda is passed the value
+      #     # related to the key, and the metadata itself e.g.
       #     config.filter_run_including :foo => lambda {|v,m| m[:foo] == 'bar'}
       #
       #     filter_run_including :foo # same as filter_run_including :foo => true
       def filter_run_including(*args)
         meta = Metadata.build_hash_from(args, :warn_about_example_group_filtering)
         filter_manager.include_with_low_priority meta
+        static_config_filter_manager.include_with_low_priority Metadata.deep_hash_dup(meta)
       end
 
       alias_method :filter_run, :filter_run_including
@@ -936,28 +973,30 @@ module RSpec
       # or config files (e.g. `.rspec`).
       #
       # @example
-      #     # given this declaration
+      #     # Given this declaration.
       #     describe "something", :foo => 'bar' do
       #       # ...
       #     end
       #
-      #     # any of the following will exclude that group
+      #     # Any of the following will exclude that group.
       #     config.filter_run_excluding :foo => 'bar'
       #     config.filter_run_excluding :foo => /^ba/
       #     config.filter_run_excluding :foo => lambda {|v| v == 'bar'}
       #     config.filter_run_excluding :foo => lambda {|v,m| m[:foo] == 'bar'}
       #
-      #     # given a proc with an arity of 1, the lambda is passed the value related to the key, e.g.
+      #     # Given a proc with an arity of 1, the lambda is passed the value
+      #     # related to the key, e.g.
       #     config.filter_run_excluding :foo => lambda {|v| v == 'bar'}
       #
-      #     # given a proc with an arity of 2, the lambda is passed the value related to the key,
-      #     # and the metadata itself e.g.
+      #     # Given a proc with an arity of 2, the lambda is passed the value
+      #     # related to the key, and the metadata itself e.g.
       #     config.filter_run_excluding :foo => lambda {|v,m| m[:foo] == 'bar'}
       #
       #     filter_run_excluding :foo # same as filter_run_excluding :foo => true
       def filter_run_excluding(*args)
         meta = Metadata.build_hash_from(args, :warn_about_example_group_filtering)
         filter_manager.exclude_with_low_priority meta
+        static_config_filter_manager.exclude_with_low_priority Metadata.deep_hash_dup(meta)
       end
 
       # Clears and reassigns the `exclusion_filter`. Set to `nil` if you don't
@@ -979,8 +1018,8 @@ module RSpec
       end
 
       # Tells RSpec to include `mod` in example groups. Methods defined in
-      # `mod` are exposed to examples (not example groups).  Use `filters` to
-      # constrain the groups in which to include the module.
+      # `mod` are exposed to examples (not example groups). Use `filters` to
+      # constrain the groups or examples in which to include the module.
       #
       # @example
       #
@@ -1009,14 +1048,22 @@ module RSpec
       #       end
       #     end
       #
+      # @note Filtered module inclusions can also be applied to
+      #   individual examples that have matching metadata. Just like
+      #   Ruby's object model is that every object has a singleton class
+      #   which has only a single instance, RSpec's model is that every
+      #   example has a singleton example group containing just the one
+      #   example.
+      #
       # @see #extend
+      # @see #prepend
       def include(mod, *filters)
         meta = Metadata.build_hash_from(filters, :warn_about_example_group_filtering)
-        include_or_extend_modules << [:include, mod, meta]
+        @include_modules.append(mod, meta)
       end
 
-      # Tells RSpec to extend example groups with `mod`.  Methods defined in
-      # `mod` are exposed to example groups (not examples).  Use `filters` to
+      # Tells RSpec to extend example groups with `mod`. Methods defined in
+      # `mod` are exposed to example groups (not examples). Use `filters` to
       # constrain the groups to extend.
       #
       # Similar to `include`, but behavior is added to example groups, which
@@ -1044,25 +1091,87 @@ module RSpec
       #     end
       #
       # @see #include
+      # @see #prepend
       def extend(mod, *filters)
         meta = Metadata.build_hash_from(filters, :warn_about_example_group_filtering)
-        include_or_extend_modules << [:extend, mod, meta]
+        @extend_modules.append(mod, meta)
+      end
+
+      if RSpec::Support::RubyFeatures.module_prepends_supported?
+        # Tells RSpec to prepend example groups with `mod`. Methods defined in
+        # `mod` are exposed to examples (not example groups). Use `filters` to
+        # constrain the groups in which to prepend the module.
+        #
+        # Similar to `include`, but module is included before the example group's class
+        # in the ancestor chain.
+        #
+        # @example
+        #
+        #     module OverrideMod
+        #       def override_me
+        #         "overridden"
+        #       end
+        #     end
+        #
+        #     RSpec.configure do |config|
+        #       config.prepend(OverrideMod, :method => :prepend)
+        #     end
+        #
+        #     describe "overriding example's class", :method => :prepend do
+        #       it "finds the user" do
+        #         self.class.class_eval do
+        #           def override_me
+        #           end
+        #         end
+        #         override_me # => "overridden"
+        #         # ...
+        #       end
+        #     end
+        #
+        # @see #include
+        # @see #extend
+        def prepend(mod, *filters)
+          meta = Metadata.build_hash_from(filters, :warn_about_example_group_filtering)
+          @prepend_modules.append(mod, meta)
+        end
       end
 
       # @private
       #
-      # Used internally to extend a group with modules using `include` and/or
+      # Used internally to extend a group with modules using `include`, `prepend` and/or
       # `extend`.
       def configure_group(group)
-        include_or_extend_modules.each do |include_or_extend, mod, filters|
-          next unless filters.empty? || group.any_apply?(filters)
-          __send__("safe_#{include_or_extend}", mod, group)
+        configure_group_with group, @include_modules, :safe_include
+        configure_group_with group, @extend_modules,  :safe_extend
+        configure_group_with group, @prepend_modules, :safe_prepend
+      end
+
+      # @private
+      def configure_group_with(group, module_list, application_method)
+        module_list.items_for(group.metadata).each do |mod|
+          __send__(application_method, mod, group)
         end
       end
 
       # @private
-      def safe_include(mod, host)
-        host.__send__(:include, mod) unless host < mod
+      #
+      # Used internally to extend the singleton class of a single example's
+      # example group instance with modules using `include` and/or `extend`.
+      def configure_example(example)
+        # We replace the metadata so that SharedExampleGroupModule#included
+        # has access to the example's metadata[:location].
+        example.example_group_instance.singleton_class.with_replaced_metadata(example.metadata) do
+          @include_modules.items_for(example.metadata).each do |mod|
+            safe_include(mod, example.example_group_instance.singleton_class)
+          end
+        end
+      end
+
+      if RSpec::Support::RubyFeatures.module_prepends_supported?
+        # @private
+        def safe_prepend(mod, host)
+          host.__send__(:prepend, mod) unless host < mod
+        end
       end
 
       # @private
@@ -1075,11 +1184,21 @@ module RSpec
 
       # @private
       if RUBY_VERSION.to_f >= 1.9
+        # @private
+        def safe_include(mod, host)
+          host.__send__(:include, mod) unless host < mod
+        end
+
         # @private
         def safe_extend(mod, host)
           host.extend(mod) unless host.singleton_class < mod
         end
       else
+        # @private
+        def safe_include(mod, host)
+          host.__send__(:include, mod) unless host.included_modules.include?(mod)
+        end
+
         # @private
         def safe_extend(mod, host)
           host.extend(mod) unless (class << host; self; end).included_modules.include?(mod)
@@ -1102,7 +1221,12 @@ module RSpec
 
       # @private
       def load_spec_files
-        files_to_run.uniq.each { |f| load File.expand_path(f) }
+        files_to_run.uniq.each do |f|
+          file = File.expand_path(f)
+          load file
+          loaded_spec_files << file
+        end
+
         @spec_files_loaded = true
       end
 
@@ -1112,7 +1236,8 @@ module RSpec
       # Formats the docstring output using the block provided.
       #
       # @example
-      #   # This will strip the descriptions of both examples and example groups.
+      #   # This will strip the descriptions of both examples and example
+      #   # groups.
       #   RSpec.configure do |config|
       #     config.format_docstrings { |s| s.strip }
       #   end
@@ -1157,7 +1282,8 @@ module RSpec
 
       # @macro delegate_to_ordering_manager
       #
-      # Sets the default global order and, if order is `'rand:<seed>'`, also sets the seed.
+      # Sets the default global order and, if order is `'rand:<seed>'`, also
+      # sets the seed.
       delegate_to_ordering_manager :order=
 
       # @macro delegate_to_ordering_manager
@@ -1167,8 +1293,10 @@ module RSpec
       #
       # @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::ExampleGroup>] The examples or groups to order
-      # @yieldreturn [Array<RSpec::Core::Example>, Array<RSpec::Core::ExampleGroup>] The re-ordered examples or groups
+      # @yieldparam list [Array<RSpec::Core::Example>,
+      #   Array<RSpec::Core::ExampleGroup>] 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|
@@ -1189,7 +1317,7 @@ module RSpec
       # @private
       delegate_to_ordering_manager :seed_used?, :ordering_registry
 
-      # Set Ruby warnings on or off
+      # Set Ruby warnings on or off.
       def warnings=(value)
         $VERBOSE = !!value
       end
@@ -1252,7 +1380,7 @@ module RSpec
       # `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
+      # simply disables monkey patching on whatever pieces of RSpec
       # the user is using.
       #
       # @note It configures rspec-mocks and rspec-expectations only
@@ -1265,7 +1393,7 @@ module RSpec
       #
       # @example
       #
-      #   # It disables all monkey patching
+      #   # It disables all monkey patching.
       #   RSpec.configure do |config|
       #     config.disable_monkey_patching!
       #   end
@@ -1295,33 +1423,142 @@ module RSpec
 
       # 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.
+      # @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
+      #     # 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)
         meta = Metadata.build_hash_from(filters, :warn_about_example_group_filtering)
-        @derived_metadata_blocks << [meta, block]
+        @derived_metadata_blocks.append(block, meta)
       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)
+        @derived_metadata_blocks.items_for(metadata).each do |block|
+          block.call(metadata)
         end
       end
 
+      # Defines a `before` hook. See {Hooks#before} for full docs.
+      #
+      # This method differs from {Hooks#before} in only one way: it supports
+      # the `:suite` scope. Hooks with the `:suite` scope will be run once before
+      # the first example of the entire suite is executed.
+      #
+      # @see #prepend_before
+      # @see #after
+      # @see #append_after
+      def before(*args, &block)
+        handle_suite_hook(args, @before_suite_hooks, :push,
+                          Hooks::BeforeHook, block) || super(*args, &block)
+      end
+      alias_method :append_before, :before
+
+      # Adds `block` to the start of the list of `before` blocks in the same
+      # scope (`:example`, `:context`, or `:suite`), in contrast to {#before},
+      # which adds the hook to the end of the list.
+      #
+      # See {Hooks#before} for full `before` hook docs.
+      #
+      # This method differs from {Hooks#prepend_before} in only one way: it supports
+      # the `:suite` scope. Hooks with the `:suite` scope will be run once before
+      # the first example of the entire suite is executed.
+      #
+      # @see #before
+      # @see #after
+      # @see #append_after
+      def prepend_before(*args, &block)
+        handle_suite_hook(args, @before_suite_hooks, :unshift,
+                          Hooks::BeforeHook, block) || super(*args, &block)
+      end
+
+      # Defines a `after` hook. See {Hooks#after} for full docs.
+      #
+      # This method differs from {Hooks#after} in only one way: it supports
+      # the `:suite` scope. Hooks with the `:suite` scope will be run once after
+      # the last example of the entire suite is executed.
+      #
+      # @see #append_after
+      # @see #before
+      # @see #prepend_before
+      def after(*args, &block)
+        handle_suite_hook(args, @after_suite_hooks, :unshift,
+                          Hooks::AfterHook, block) || super(*args, &block)
+      end
+      alias_method :prepend_after, :after
+
+      # Adds `block` to the end of the list of `after` blocks in the same
+      # scope (`:example`, `:context`, or `:suite`), in contrast to {#after},
+      # which adds the hook to the start of the list.
+      #
+      # See {Hooks#after} for full `after` hook docs.
+      #
+      # This method differs from {Hooks#append_after} in only one way: it supports
+      # the `:suite` scope. Hooks with the `:suite` scope will be run once after
+      # the last example of the entire suite is executed.
+      #
+      # @see #append_after
+      # @see #before
+      # @see #prepend_before
+      def append_after(*args, &block)
+        handle_suite_hook(args, @after_suite_hooks, :push,
+                          Hooks::AfterHook, block) || super(*args, &block)
+      end
+
+      # @private
+      def with_suite_hooks
+        return yield if dry_run?
+
+        hook_context = SuiteHookContext.new
+        begin
+          run_hooks_with(@before_suite_hooks, hook_context)
+          yield
+        ensure
+          run_hooks_with(@after_suite_hooks, hook_context)
+        end
+      end
+
+      # @private
+      # Holds the various registered hooks. Here we use a FilterableItemRepository
+      # implementation that is specifically optimized for the read/write patterns
+      # of the config object.
+      def hooks
+        @hooks ||= HookCollections.new(self, FilterableItemRepository::QueryOptimized)
+      end
+
     private
 
+      def handle_suite_hook(args, collection, append_or_prepend, hook_type, block)
+        scope, meta = *args
+        return nil unless scope == :suite
+
+        if meta
+          # TODO: in RSpec 4, consider raising an error here.
+          # We warn only for backwards compatibility.
+          RSpec.warn_with "WARNING: `:suite` hooks do not support metadata since " \
+                          "they apply to the suite as a whole rather than " \
+                          "any individual example or example group that has metadata. " \
+                          "The metadata you have provided (#{meta.inspect}) will be ignored."
+        end
+
+        collection.__send__(append_or_prepend, hook_type.new(block, {}))
+      end
+
+      def run_hooks_with(hooks, hook_context)
+        hooks.each { |h| h.run(hook_context) }
+      end
+
       def get_files_to_run(paths)
         FlatMap.flat_map(paths_to_check(paths)) do |path|
           path = path.gsub(File::ALT_SEPARATOR, File::SEPARATOR) if File::ALT_SEPARATOR
@@ -1331,7 +1568,7 @@ module RSpec
 
       def paths_to_check(paths)
         return paths if pattern_might_load_specs_from_vendored_dirs?
-        paths + ['.']
+        paths + [Dir.getwd]
       end
 
       def pattern_might_load_specs_from_vendored_dirs?
@@ -1386,8 +1623,8 @@ module RSpec
         $0.split(File::SEPARATOR).last
       end
 
-      def value_for(key, default=nil)
-        @preferred_options.key?(key) ? @preferred_options[key] : default
+      def value_for(key)
+        @preferred_options.fetch(key) { yield }
       end
 
       def assert_no_example_groups_defined(config_option)
@@ -1428,7 +1665,8 @@ module RSpec
 
       def update_pattern_attr(name, value)
         if @spec_files_loaded
-          RSpec.warning "Configuring `#{name}` to #{value} has no effect since RSpec has already loaded the spec files."
+          RSpec.warning "Configuring `#{name}` to #{value} has no effect since " \
+                        "RSpec has already loaded the spec files."
         end
 
         instance_variable_set(:"@#{name}", value)