rspec-core 3.1.7 → 3.2.0

data/lib/rspec/core/formatters/helpers.rb

@@ -1,7 +1,7 @@
 module RSpec
   module Core
     module Formatters
-      # Formatters helpers
+      # Formatters helpers.
       module Helpers
         # @private
         SUB_SECOND_PRECISION = 5
@@ -39,8 +39,9 @@ module RSpec
 
         # @api private
         #
-        # Formats seconds to have 5 digits of precision with trailing zeros removed if the number
-        # is less than 1 or with 2 digits of precision if the number is greater than zero.
+        # Formats seconds to have 5 digits of precision with trailing zeros
+        # removed if the number is less than 1 or with 2 digits of precision if
+        # the number is greater than zero.
         #
         # @param float [Float]
         # @return [String] formatted float
@@ -50,7 +51,8 @@ module RSpec
         #    format_seconds(0.020000) #=> "0.02"
         #    format_seconds(1.00000000001) #=> "1"
         #
-        # The precision used is set in {Helpers::SUB_SECOND_PRECISION} and {Helpers::DEFAULT_PRECISION}.
+        # The precision used is set in {Helpers::SUB_SECOND_PRECISION} and
+        # {Helpers::DEFAULT_PRECISION}.
         #
         # @see #strip_trailing_zeroes
         def self.format_seconds(float, precision=nil)

data/lib/rspec/core/formatters/html_formatter.rb

@@ -31,7 +31,9 @@ module RSpec
           @example_group_number += 1
 
           @printer.print_example_group_end unless example_group_number == 1
-          @printer.print_example_group_start(example_group_number, notification.group.description, notification.group.parent_groups.size)
+          @printer.print_example_group_start(example_group_number,
+                                             notification.group.description,
+                                             notification.group.parent_groups.size)
           @printer.flush
         end
 
@@ -111,15 +113,16 @@ module RSpec
 
       private
 
-        # If these methods are declared with attr_reader Ruby will issue a warning because they are private
+        # If these methods are declared with attr_reader Ruby will issue a
+        # warning because they are private.
         # rubocop:disable Style/TrivialAccessors
 
-        # The number of the currently running example_group
+        # The number of the currently running example_group.
         def example_group_number
           @example_group_number
         end
 
-        # The number of the currently running example (a global counter)
+        # The number of the currently running example (a global counter).
         def example_number
           @example_number
         end
@@ -133,12 +136,14 @@ module RSpec
           result
         end
 
-        # Override this method if you wish to output extra HTML for a failed spec. For example, you
-        # could output links to images or other files produced during the specs.
-        #
+        # Override this method if you wish to output extra HTML for a failed
+        # spec. For example, you could output links to images or other files
+        # produced during the specs.
         def extra_failure_content(failure)
           RSpec::Support.require_rspec_core "formatters/snippet_extractor"
-          backtrace = failure.exception.backtrace.map { |line| RSpec.configuration.backtrace_formatter.backtrace_line(line) }
+          backtrace = failure.exception.backtrace.map do |line|
+            RSpec.configuration.backtrace_formatter.backtrace_line(line)
+          end
           backtrace.compact!
           @snippet_extractor ||= SnippetExtractor.new
           "    <pre class=\"ruby\"><code>#{@snippet_extractor.snippet(backtrace)}</code></pre>"

data/lib/rspec/core/formatters/html_printer.rb

@@ -5,7 +5,7 @@ module RSpec
     module Formatters
       # @private
       class HtmlPrinter
-        include ERB::Util # for the #h method
+        include ERB::Util # For the #h method.
         def initialize(output)
           @output = output
         end
@@ -28,11 +28,14 @@ module RSpec
 
         def print_example_passed(description, run_time)
           formatted_run_time = "%.5f" % run_time
-          @output.puts "    <dd class=\"example passed\"><span class=\"passed_spec_name\">#{h(description)}</span><span class='duration'>#{formatted_run_time}s</span></dd>"
+          @output.puts "    <dd class=\"example passed\">" \
+            "<span class=\"passed_spec_name\">#{h(description)}</span>" \
+            "<span class='duration'>#{formatted_run_time}s</span></dd>"
         end
 
         # rubocop:disable Style/ParameterLists
-        def print_example_failed(pending_fixed, description, run_time, failure_id, exception, extra_content, escape_backtrace=false)
+        def print_example_failed(pending_fixed, description, run_time, failure_id,
+                                 exception, extra_content, escape_backtrace=false)
           # rubocop:enable Style/ParameterLists
           formatted_run_time = "%.5f" % run_time
 
@@ -54,7 +57,9 @@ module RSpec
         end
 
         def print_example_pending(description, pending_message)
-          @output.puts "    <dd class=\"example not_implemented\"><span class=\"not_implemented_spec_name\">#{h(description)} (PENDING: #{h(pending_message)})</span></dd>"
+          @output.puts "    <dd class=\"example not_implemented\">" \
+            "<span class=\"not_implemented_spec_name\">#{h(description)} " \
+            "(PENDING: #{h(pending_message)})</span></dd>"
         end
 
         def print_summary(duration, example_count, failure_count, pending_count)
@@ -64,8 +69,11 @@ module RSpec
 
           formatted_duration = "%.5f" % duration
 
-          @output.puts "<script type=\"text/javascript\">document.getElementById('duration').innerHTML = \"Finished in <strong>#{formatted_duration} seconds</strong>\";</script>"
-          @output.puts "<script type=\"text/javascript\">document.getElementById('totals').innerHTML = \"#{totals}\";</script>"
+          @output.puts "<script type=\"text/javascript\">" \
+            "document.getElementById('duration').innerHTML = \"Finished in " \
+            "<strong>#{formatted_duration} seconds</strong>\";</script>"
+          @output.puts "<script type=\"text/javascript\">" \
+            "document.getElementById('totals').innerHTML = \"#{totals}\";</script>"
           @output.puts "</div>"
           @output.puts "</div>"
           @output.puts "</body>"
@@ -90,13 +98,17 @@ module RSpec
         end
 
         def make_example_group_header_red(group_id)
-          @output.puts "    <script type=\"text/javascript\">makeRed('div_group_#{group_id}');</script>"
-          @output.puts "    <script type=\"text/javascript\">makeRed('example_group_#{group_id}');</script>"
+          @output.puts "    <script type=\"text/javascript\">" \
+                       "makeRed('div_group_#{group_id}');</script>"
+          @output.puts "    <script type=\"text/javascript\">" \
+                       "makeRed('example_group_#{group_id}');</script>"
         end
 
         def make_example_group_header_yellow(group_id)
-          @output.puts "    <script type=\"text/javascript\">makeYellow('div_group_#{group_id}');</script>"
-          @output.puts "    <script type=\"text/javascript\">makeYellow('example_group_#{group_id}');</script>"
+          @output.puts "    <script type=\"text/javascript\">" \
+                       "makeYellow('div_group_#{group_id}');</script>"
+          @output.puts "    <script type=\"text/javascript\">" \
+                       "makeYellow('example_group_#{group_id}');</script>"
         end
 
       private
@@ -105,6 +117,7 @@ module RSpec
           "style=\"margin-left: #{(number_of_parents - 1) * 15}px;\""
         end
 
+        # rubocop:disable LineLength
         REPORT_HEADER = <<-EOF
 <div class="rspec-report">
 
@@ -128,7 +141,9 @@ module RSpec
 
 <div class="results">
 EOF
+        # rubocop:enable LineLength
 
+        # rubocop:disable LineLength
         GLOBAL_SCRIPTS = <<-EOF
 
 function addClass(element_id, classname) {
@@ -205,6 +220,7 @@ function assign_display_style_for_group(classname, display_flag, subgroup_flag)
   }
 }
 EOF
+        # rubocop:enable LineLength
 
         GLOBAL_STYLES = <<-EOF
 #rspec-header {

data/lib/rspec/core/formatters/profile_formatter.rb

@@ -4,7 +4,7 @@ module RSpec
   module Core
     module Formatters
       # @api private
-      # Formatter for providing profile output
+      # Formatter for providing profile output.
       class ProfileFormatter
         Formatters.register self, :dump_profile
 
@@ -15,14 +15,13 @@ module RSpec
         # @private
         attr_reader :output
 
-        # @method dump_profile
         # @api public
         #
         # This method is invoked after the dumping the summary if profiling is
         # enabled.
         #
-        # @param profile [ProfileNotification] containing duration, slowest_examples
-        #                                      and slowest_example_groups
+        # @param profile [ProfileNotification] containing duration,
+        #   slowest_examples and slowest_example_groups
         def dump_profile(profile)
           dump_profile_slowest_examples(profile)
           dump_profile_slowest_example_groups(profile)
@@ -31,11 +30,14 @@ module RSpec
       private
 
         def dump_profile_slowest_examples(profile)
-          @output.puts "\nTop #{profile.slowest_examples.size} slowest examples (#{Helpers.format_seconds(profile.slow_duration)} seconds, #{profile.percentage}% of total time):\n"
+          @output.puts "\nTop #{profile.slowest_examples.size} slowest " \
+            "examples (#{Helpers.format_seconds(profile.slow_duration)} " \
+            "seconds, #{profile.percentage}% of total time):\n"
 
           profile.slowest_examples.each do |example|
             @output.puts "  #{example.full_description}"
-            @output.puts "    #{bold(Helpers.format_seconds(example.execution_result.run_time))} #{bold("seconds")} #{format_caller(example.location)}"
+            @output.puts "    #{bold(Helpers.format_seconds(example.execution_result.run_time))} " \
+                         "#{bold("seconds")} #{format_caller(example.location)}"
           end
         end
 
@@ -53,7 +55,8 @@ module RSpec
         end
 
         def format_caller(caller_info)
-          RSpec.configuration.backtrace_formatter.backtrace_line(caller_info.to_s.split(':in `block').first)
+          RSpec.configuration.backtrace_formatter.backtrace_line(
+            caller_info.to_s.split(':in `block').first)
         end
 
         def bold(text)

data/lib/rspec/core/formatters/protocol.rb

@@ -39,12 +39,14 @@ module RSpec
         # @api public
         # @group Group Notifications
         #
-        # This method is invoked at the beginning of the execution of each example group.
+        # This method is invoked at the beginning of the execution of each
+        # example group.
         #
         # The next method to be invoked after this is {#example_passed},
         # {#example_pending}, or {#example_group_finished}.
         #
-        # @param notification [GroupNotification] containing example_group subclass of `RSpec::Core::ExampleGroup`
+        # @param notification [GroupNotification] containing example_group
+        #   subclass of `RSpec::Core::ExampleGroup`
 
         # @method example_group_finished
         # @api public
@@ -52,7 +54,8 @@ module RSpec
         #
         # Invoked at the end of the execution of each example group.
         #
-        # @param notification [GroupNotification] containing example_group subclass of `RSpec::Core::ExampleGroup`
+        # @param notification [GroupNotification] containing example_group
+        #   subclass of `RSpec::Core::ExampleGroup`
 
         # @method example_started
         # @api public
@@ -60,7 +63,8 @@ module RSpec
         #
         # Invoked at the beginning of the execution of each example.
         #
-        # @param notification [ExampleNotification] containing example subclass of `RSpec::Core::Example`
+        # @param notification [ExampleNotification] containing example subclass
+        #   of `RSpec::Core::Example`
 
         # @method example_passed
         # @api public
@@ -68,7 +72,8 @@ module RSpec
         #
         # Invoked when an example passes.
         #
-        # @param notification [ExampleNotification] containing example subclass of `RSpec::Core::Example`
+        # @param notification [ExampleNotification] containing example subclass
+        #   of `RSpec::Core::Example`
 
         # @method example_pending
         # @api public
@@ -76,7 +81,8 @@ module RSpec
         #
         # Invoked when an example is pending.
         #
-        # @param notification [ExampleNotification] containing example subclass of `RSpec::Core::Example`
+        # @param notification [ExampleNotification] containing example subclass
+        #   of `RSpec::Core::Example`
 
         # @method example_failed
         # @api public
@@ -84,7 +90,8 @@ module RSpec
         #
         # Invoked when an example fails.
         #
-        # @param notification [ExampleNotification] containing example subclass of `RSpec::Core::Example`
+        # @param notification [ExampleNotification] containing example subclass
+        #   of `RSpec::Core::Example`
 
         # @method message
         # @api public
@@ -98,7 +105,8 @@ module RSpec
         # @api public
         # @group Suite Notifications
         #
-        # Invoked after all examples have executed, before dumping post-run reports.
+        # Invoked after all examples have executed, before dumping post-run
+        # reports.
         #
         # @param notification [NullNotification]
 
@@ -106,9 +114,10 @@ module RSpec
         # @api public
         # @group Suite Notifications
         #
-        # This method is invoked after all of the examples have executed. The next method
-        # to be invoked after this one is {#dump_failures}
-        # (BaseTextFormatter then calls {#dump_failure} once for each failed example.)
+        # This method is invoked after all of the examples have executed. The
+        # next method to be invoked after this one is {#dump_failures}
+        # (BaseTextFormatter then calls {#dump_failures} once for each failed
+        # example).
         #
         # @param notification [NullNotification]
 
@@ -124,11 +133,11 @@ module RSpec
         # @api public
         # @group Suite Notifications
         #
-        # This method is invoked after the dumping of examples and failures. Each parameter
-        # is assigned to a corresponding attribute.
+        # This method is invoked after the dumping of examples and failures.
+        # Each parameter is assigned to a corresponding attribute.
         #
-        # @param summary [SummaryNotification] containing duration, example_count,
-        #                                      failure_count and pending_count
+        # @param summary [SummaryNotification] containing duration,
+        #   example_count, failure_count and pending_count
 
         # @method dump_profile
         # @api public
@@ -137,14 +146,14 @@ module RSpec
         # This method is invoked after the dumping the summary if profiling is
         # enabled.
         #
-        # @param profile [ProfileNotification] containing duration, slowest_examples
-        #                                      and slowest_example_groups
+        # @param profile [ProfileNotification] containing duration,
+        #   slowest_examples and slowest_example_groups
 
         # @method dump_pending
         # @api public
         # @group Suite Notifications
         #
-        # Outputs a report of pending examples.  This gets invoked
+        # Outputs a report of pending examples. This gets invoked
         # after the summary if option is set to do so.
         #
         # @param notification [NullNotification]

data/lib/rspec/core/formatters/snippet_extractor.rb

@@ -3,7 +3,8 @@ module RSpec
     module Formatters
       # @api private
       #
-      # Extracts code snippets by looking at the backtrace of the passed error and applies synax highlighting and line numbers using html.
+      # Extracts code snippets by looking at the backtrace of the passed error
+      # and applies synax highlighting and line numbers using html.
       class SnippetExtractor
         # @private
         class NullConverter
@@ -33,7 +34,8 @@ module RSpec
         # Extract lines of code corresponding to  a backtrace.
         #
         # @param backtrace [String] the backtrace from a test failure
-        # @return [String] highlighted code snippet indicating where the test failure occured
+        # @return [String] highlighted code snippet indicating where the test
+        #   failure occured
         #
         # @see #post_process
         def snippet(backtrace)
@@ -46,7 +48,8 @@ module RSpec
         #
         # Create a snippet from a line of code.
         #
-        # @param error_line [String] file name with line number (i.e. 'foo_spec.rb:12')
+        # @param error_line [String] file name with line number (i.e.
+        #   'foo_spec.rb:12')
         # @return [String] lines around the target line within the file
         #
         # @see #lines_around
@@ -62,11 +65,13 @@ module RSpec
 
         # @api private
         #
-        # Extract lines of code centered around a particular line within a source file.
+        # Extract lines of code centered around a particular line within a
+        # source file.
         #
         # @param file [String] filename
         # @param line [Fixnum] line number
-        # @return [String] lines around the target line within the file (2 above and 1 below).
+        # @return [String] lines around the target line within the file (2 above
+        #   and 1 below).
         def lines_around(file, line)
           if File.file?(file)
             lines = File.read(file).split("\n")
@@ -84,9 +89,11 @@ module RSpec
 
         # @api private
         #
-        # Adds line numbers to all lines and highlights the line where the failure occurred using html `span` tags.
+        # Adds line numbers to all lines and highlights the line where the
+        # failure occurred using html `span` tags.
         #
-        # @param highlighted [String] syntax-highlighted snippet surrounding the offending line of code
+        # @param highlighted [String] syntax-highlighted snippet surrounding the
+        #   offending line of code
         # @param offending_line [Fixnum] line where failure occured
         # @return [String] completed snippet
         def post_process(highlighted, offending_line)

data/lib/rspec/core/hooks.rb

@@ -11,18 +11,20 @@ module RSpec
       #
       # @overload before(&block)
       # @overload before(scope, &block)
-      #   @param scope [Symbol] `:example`, `:context`, or `:suite` (defaults to `:example`)
+      #   @param scope [Symbol] `:example`, `:context`, or `:suite`
+      #     (defaults to `:example`)
       # @overload before(scope, conditions, &block)
-      #   @param scope [Symbol] `:example`, `:context`, or `:suite` (defaults to `:example`)
+      #   @param scope [Symbol] `:example`, `:context`, or `:suite`
+      #     (defaults to `:example`)
       #   @param conditions [Hash]
       #     constrains this hook to examples matching these conditions e.g.
-      #     `before(:example, :ui => true) { ... }` will only run with examples or
-      #     groups declared with `:ui => true`.
+      #     `before(:example, :ui => true) { ... }` will only run with examples
+      #     or groups declared with `:ui => true`.
       # @overload before(conditions, &block)
       #   @param conditions [Hash]
       #     constrains this hook to examples matching these conditions e.g.
-      #     `before(:example, :ui => true) { ... }` will only run with examples or
-      #     groups declared with `:ui => true`.
+      #     `before(:example, :ui => true) { ... }` will only run with examples
+      #     or groups declared with `:ui => true`.
       #
       # @see #after
       # @see #around
@@ -32,39 +34,39 @@ module RSpec
       # @see Configuration
       #
       # Declare a block of code to be run before each example (using `:example`)
-      # or once before any example (using `:context`). These are usually declared
-      # directly in the {ExampleGroup} to which they apply, but they can also
-      # be shared across multiple groups.
+      # or once before any example (using `:context`). These are usually
+      # declared directly in the {ExampleGroup} to which they apply, but they
+      # can also be shared across multiple groups.
       #
       # You can also use `before(:suite)` to run a block of code before any
-      # example groups are run. This should be declared in {RSpec.configure}
+      # example groups are run. This should be declared in {RSpec.configure}.
       #
-      # Instance variables declared in `before(:example)` or `before(:context)` are
-      # accessible within each example.
+      # Instance variables declared in `before(:example)` or `before(:context)`
+      # are accessible within each example.
       #
       # ### Order
       #
       # `before` hooks are stored in three scopes, which are run in order:
-      # `:suite`, `:context`, and `:example`. They can also be declared in several
-      # different places: `RSpec.configure`, a parent group, the current group.
-      # They are run in the following order:
-      #
-      #     before(:suite)    # declared in RSpec.configure
-      #     before(:context)  # declared in RSpec.configure
-      #     before(:context)  # declared in a parent group
-      #     before(:context)  # declared in the current group
-      #     before(:example)  # declared in RSpec.configure
-      #     before(:example)  # declared in a parent group
-      #     before(:example)  # declared in the current group
+      # `:suite`, `:context`, and `:example`. They can also be declared in
+      # several different places: `RSpec.configure`, a parent group, the current
+      # group. They are run in the following order:
+      #
+      #     before(:suite)    # Declared in RSpec.configure.
+      #     before(:context)  # Declared in RSpec.configure.
+      #     before(:context)  # Declared in a parent group.
+      #     before(:context)  # Declared in the current group.
+      #     before(:example)  # Declared in RSpec.configure.
+      #     before(:example)  # Declared in a parent group.
+      #     before(:example)  # Declared in the current group.
       #
       # If more than one `before` is declared within any one scope, they are run
       # in the order in which they are declared.
       #
       # ### Conditions
       #
-      # When you add a conditions hash to `before(:example)` or `before(:context)`,
-      # RSpec will only apply that hook to groups or examples that match the
-      # conditions. e.g.
+      # When you add a conditions hash to `before(:example)` or
+      # `before(:context)`, RSpec will only apply that hook to groups or
+      # examples that match the conditions. e.g.
       #
       #     RSpec.configure do |config|
       #       config.before(:example, :authorized => true) do
@@ -73,19 +75,26 @@ module RSpec
       #     end
       #
       #     describe Something, :authorized => true do
-      #       # the before hook will run in before each example in this group
+      #       # The before hook will run in before each example in this group.
       #     end
       #
       #     describe SomethingElse do
       #       it "does something", :authorized => true do
-      #         # the before hook will run before this example
+      #         # The before hook will run before this example.
       #       end
       #
       #       it "does something else" do
-      #         # the hook will not run before this example
+      #         # The hook will not run before this example.
       #       end
       #     end
       #
+      # Note that filtered config `:context` hooks can still 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.
+      #
       # ### Warning: `before(:suite, :with => :conditions)`
       #
       # The conditions hash is used to match against specific examples. Since
@@ -113,22 +122,23 @@ module RSpec
       # recommend that you avoid this as there are a number of gotchas, as well
       # as things that simply don't work.
       #
-      # #### context
+      # #### Context
       #
-      # `before(:context)` is run in an example that is generated to provide group
-      # context for the block.
+      # `before(:context)` is run in an example that is generated to provide
+      # group context for the block.
       #
-      # #### instance variables
+      # #### Instance variables
       #
-      # Instance variables declared in `before(:context)` are shared across all the
-      # examples in the group.  This means that each example can change the
+      # Instance variables declared in `before(:context)` are shared across all
+      # the examples in the group. This means that each example can change the
       # state of a shared object, resulting in an ordering dependency that can
       # make it difficult to reason about failures.
       #
-      # #### unsupported rspec constructs
+      # #### Unsupported RSpec constructs
       #
       # RSpec has several constructs that reset state between each example
-      # automatically. These are not intended for use from within `before(:context)`:
+      # automatically. These are not intended for use from within
+      # `before(:context)`:
       #
       #   * `let` declarations
       #   * `subject` declarations
@@ -138,13 +148,13 @@ module RSpec
       #
       # Mock object frameworks and database transaction managers (like
       # ActiveRecord) are typically designed around the idea of setting up
-      # before an example, running that one example, and then tearing down.
-      # This means that mocks and stubs can (sometimes) be declared in
-      # `before(:context)`, but get torn down before the first real example is ever
-      # run.
+      # before an example, running that one example, and then tearing down. This
+      # means that mocks and stubs can (sometimes) be declared in
+      # `before(:context)`, but get torn down before the first real example is
+      # ever run.
       #
-      # You _can_ create database-backed model objects in a `before(:context)` in
-      # rspec-rails, but it will not be wrapped in a transaction for you, so
+      # You _can_ create database-backed model objects in a `before(:context)`
+      # in rspec-rails, but it will not be wrapped in a transaction for you, so
       # you are on your own to clean up in an `after(:context)` block.
       #
       # @example before(:example) declared in an {ExampleGroup}
@@ -155,7 +165,7 @@ module RSpec
       #       end
       #
       #       it "does something" do
-      #         # here you can access @thing
+      #         # Here you can access @thing.
       #       end
       #     end
       #
@@ -181,6 +191,9 @@ module RSpec
       #
       # @note The `:example` and `:context` scopes are also available as
       #       `:each` and `:all`, respectively. Use whichever you prefer.
+      # @note The `:scope` alias is only supported for hooks registered on
+      #       `RSpec.configuration` since they exist independently of any
+      #       example or example group.
       def before(*args, &block)
         hooks.register :append, :before, *args, &block
       end
@@ -198,18 +211,20 @@ module RSpec
       # @api public
       # @overload after(&block)
       # @overload after(scope, &block)
-      #   @param scope [Symbol] `:example`, `:context`, or `:suite` (defaults to `:example`)
+      #   @param scope [Symbol] `:example`, `:context`, or `:suite` (defaults to
+      #     `:example`)
       # @overload after(scope, conditions, &block)
-      #   @param scope [Symbol] `:example`, `:context`, or `:suite` (defaults to `:example`)
+      #   @param scope [Symbol] `:example`, `:context`, or `:suite` (defaults to
+      #     `:example`)
       #   @param conditions [Hash]
       #     constrains this hook to examples matching these conditions e.g.
-      #     `after(:example, :ui => true) { ... }` will only run with examples or
-      #     groups declared with `:ui => true`.
+      #     `after(:example, :ui => true) { ... }` will only run with examples
+      #     or groups declared with `:ui => true`.
       # @overload after(conditions, &block)
       #   @param conditions [Hash]
       #     constrains this hook to examples matching these conditions e.g.
-      #     `after(:example, :ui => true) { ... }` will only run with examples or
-      #     groups declared with `:ui => true`.
+      #     `after(:example, :ui => true) { ... }` will only run with examples
+      #     or groups declared with `:ui => true`.
       #
       # @see #before
       # @see #around
@@ -218,31 +233,31 @@ module RSpec
       # @see SharedExampleGroup
       # @see Configuration
       #
-      # Declare a block of code to be run after each example (using `:example`) or
-      # once after all examples n the context (using `:context`). See {#before} for
-      # more information about ordering.
+      # Declare a block of code to be run after each example (using `:example`)
+      # or once after all examples n the context (using `:context`). See
+      # {#before} for more information about ordering.
       #
       # ### Exceptions
       #
       # `after` hooks are guaranteed to run even when there are exceptions in
-      # `before` hooks or examples.  When an exception is raised in an after
+      # `before` hooks or examples. When an exception is raised in an after
       # block, the exception is captured for later reporting, and subsequent
       # `after` blocks are run.
       #
       # ### Order
       #
       # `after` hooks are stored in three scopes, which are run in order:
-      # `:example`, `:context`, and `:suite`. They can also be declared in several
-      # different places: `RSpec.configure`, a parent group, the current group.
-      # They are run in the following order:
-      #
-      #     after(:example) # declared in the current group
-      #     after(:example) # declared in a parent group
-      #     after(:example) # declared in RSpec.configure
-      #     after(:context) # declared in the current group
-      #     after(:context) # declared in a parent group
-      #     after(:context) # declared in RSpec.configure
-      #     after(:suite)   # declared in RSpec.configure
+      # `:example`, `:context`, and `:suite`. They can also be declared in
+      # several different places: `RSpec.configure`, a parent group, the current
+      # group. They are run in the following order:
+      #
+      #     after(:example) # Declared in the current group.
+      #     after(:example) # Declared in a parent group.
+      #     after(:example) # Declared in RSpec.configure.
+      #     after(:context) # Declared in the current group.
+      #     after(:context) # Declared in a parent group.
+      #     after(:context) # Declared in RSpec.configure.
+      #     after(:suite)   # Declared in RSpec.configure.
       #
       # This is the reverse of the order in which `before` hooks are run.
       # Similarly, if more than one `after` is declared within any one scope,
@@ -250,6 +265,9 @@ module RSpec
       #
       # @note The `:example` and `:context` scopes are also available as
       #       `:each` and `:all`, respectively. Use whichever you prefer.
+      # @note The `:scope` alias is only supported for hooks registered on
+      #       `RSpec.configuration` since they exist independently of any
+      #       example or example group.
       def after(*args, &block)
         hooks.register :prepend, :after, *args, &block
       end
@@ -274,15 +292,13 @@ module RSpec
       #   @param scope [Symbol] `:example` (defaults to `:example`)
       #     present for syntax parity with `before` and `after`, but
       #     `:example`/`:each` is the only supported value.
-      #   @param conditions [Hash]
-      #     constrains this hook to examples matching these conditions e.g.
-      #     `around(:example, :ui => true) { ... }` will only run with examples or
-      #     groups declared with `:ui => true`.
+      #   @param conditions [Hash] constrains this hook to examples matching
+      #     these conditions e.g. `around(:example, :ui => true) { ... }` will
+      #     only run with examples or groups declared with `:ui => true`.
       # @overload around(conditions, &block)
-      #   @param conditions [Hash]
-      #     constrains this hook to examples matching these conditions e.g.
-      #     `around(:example, :ui => true) { ... }` will only run with examples or
-      #     groups declared with `:ui => true`.
+      #   @param conditions [Hash] constrains this hook to examples matching
+      #     these conditions e.g. `around(:example, :ui => true) { ... }` will
+      #     only run with examples or groups declared with `:ui => true`.
       #
       # @yield [Example] the example to run
       #
@@ -300,13 +316,13 @@ module RSpec
       # after the example. It is your responsibility to run the example:
       #
       #     around(:example) do |ex|
-      #       # do some stuff before
+      #       # Do some stuff before.
       #       ex.run
-      #       # do some stuff after
+      #       # Do some stuff after.
       #     end
       #
       # The yielded example aliases `run` with `call`, which lets you treat it
-      # like a `Proc`.  This is especially handy when working with libaries
+      # like a `Proc`. This is especially handy when working with libaries
       # that manage their own setup and teardown using a block or proc syntax,
       # e.g.
       #
@@ -320,12 +336,7 @@ module RSpec
       # @private
       # Holds the various registered hooks.
       def hooks
-        @hooks ||= HookCollections.new(
-          self,
-          :around => { :example => AroundHookCollection.new },
-          :before => { :example => HookCollection.new, :context => HookCollection.new, :suite => HookCollection.new },
-          :after  => { :example => HookCollection.new, :context => HookCollection.new, :suite => HookCollection.new }
-        )
+        @hooks ||= HookCollections.new(self, FilterableItemRepository::UpdateOptimized)
       end
 
     private
@@ -338,10 +349,6 @@ module RSpec
           @block = block
           @options = options
         end
-
-        def options_apply?(example_or_group)
-          example_or_group.all_apply?(options)
-        end
       end
 
       # @private
@@ -363,7 +370,7 @@ module RSpec
         def run(example)
           example.instance_exec(example, &block)
         rescue Exception => e
-          # TODO: come up with a better solution for this.
+          # TODO: Come up with a better solution for this.
           RSpec.configuration.reporter.message <<-EOS
 
 An error occurred in an `after(:context)` hook.
@@ -379,7 +386,8 @@ EOS
         def execute_with(example, procsy)
           example.instance_exec(procsy, &block)
           return if procsy.executed?
-          Pending.mark_skipped!(example, "#{hook_description} did not execute the example")
+          Pending.mark_skipped!(example,
+                                "#{hook_description} did not execute the example")
         end
 
         if Proc.method_defined?(:source_location)
@@ -394,113 +402,81 @@ EOS
       end
 
       # @private
-      class BaseHookCollection
-        Array.public_instance_methods(false).each do |name|
-          define_method(name) { |*a, &b| hooks.__send__(name, *a, &b) }
-        end
-
-        attr_reader :hooks
-        protected :hooks
-
-        alias append push
-        alias prepend unshift
-
-        def initialize(hooks=[])
-          @hooks = hooks
-        end
-      end
-
-      # @private
-      class HookCollection < BaseHookCollection
-        def for(example_or_group)
-          self.class.
-            new(hooks.select { |hook| hook.options_apply?(example_or_group) }).
-            with(example_or_group)
-        end
-
-        def with(example)
-          @example = example
-          self
-        end
-
-        def run
-          hooks.each { |h| h.run(@example) }
-        end
-      end
-
-      # @private
-      class AroundHookCollection < BaseHookCollection
-        def for(example, initial_procsy=nil)
-          self.class.new(hooks.select { |hook| hook.options_apply?(example) }).
-            with(example, initial_procsy)
-        end
-
-        def with(example, initial_procsy)
-          @example = example
-          @initial_procsy = initial_procsy
-          self
+      #
+      # This provides the primary API used by other parts of rspec-core. By hiding all
+      # implementation details behind this facade, it's allowed us to heavily optimize
+      # this, so that, for example, hook collection objects are only instantiated when
+      # a hook is added. This allows us to avoid many object allocations for the common
+      # case of a group having no hooks.
+      #
+      # This is only possible because this interface provides a "tell, don't ask"-style
+      # API, so that callers _tell_ this class what to do with the hooks, rather than
+      # asking this class for a list of hooks, and then doing something with them.
+      class HookCollections
+        def initialize(owner, filterable_item_repo_class)
+          @owner                      = owner
+          @filterable_item_repo_class = filterable_item_repo_class
+          @before_example_hooks       = nil
+          @after_example_hooks        = nil
+          @before_context_hooks       = nil
+          @after_context_hooks        = nil
+          @around_example_hooks       = nil
         end
 
-        def run
-          hooks.inject(@initial_procsy) do |procsy, around_hook|
-            procsy.wrap { around_hook.execute_with(@example, procsy) }
-          end.call
-        end
-      end
+        def register_globals(host, globals)
+          parent_groups = host.parent_groups
 
-      # @private
-      class GroupHookCollection < BaseHookCollection
-        def for(group)
-          @group = group
-          self
-        end
+          process(host, parent_groups, globals, :before, :example, &:options)
+          process(host, parent_groups, globals, :after,  :example, &:options)
+          process(host, parent_groups, globals, :around, :example, &:options)
 
-        def run
-          hooks.shift.run(@group) until hooks.empty?
+          process(host, parent_groups, globals, :before, :context, &:options)
+          process(host, parent_groups, globals, :after,  :context, &:options)
         end
-      end
 
-      # @private
-      class HookCollections
-        def initialize(owner, data)
-          @owner = owner
-          @data  = data
-        end
+        def register_global_singleton_context_hooks(example, globals)
+          parent_groups = example.example_group.parent_groups
 
-        def [](key)
-          @data[key]
+          process(example, parent_groups, globals, :before, :context) { {} }
+          process(example, parent_groups, globals, :after,  :context) { {} }
         end
 
-        def register_globals(host, globals)
-          process(host, globals, :before, :example)
-          process(host, globals, :after,  :example)
-          process(host, globals, :around, :example)
-
-          process(host, globals, :before, :context)
-          process(host, globals, :after,  :context)
-        end
+        def register(prepend_or_append, position, *args, &block)
+          scope, options = scope_and_options_from(*args)
 
-        def around_example_hooks_for(example, initial_procsy=nil)
-          AroundHookCollection.new(FlatMap.flat_map(@owner.parent_groups) do |a|
-            a.hooks[:around][:example]
-          end).for(example, initial_procsy)
-        end
+          if scope == :suite
+            # TODO: consider making this an error in RSpec 4. For SemVer reasons,
+            # we are only warning in RSpec 3.
+            RSpec.warn_with "WARNING: `#{position}(:suite)` hooks are only supported on " \
+                            "the RSpec configuration object. This " \
+                            "`#{position}(:suite)` hook, registered on an example " \
+                            "group, will be ignored."
+            return
+          end
 
-        def register(prepend_or_append, hook, *args, &block)
-          scope, options = scope_and_options_from(*args)
-          self[hook][scope].__send__(prepend_or_append, HOOK_TYPES[hook][scope].new(block, options))
+          hook = HOOK_TYPES[position][scope].new(block, options)
+          ensure_hooks_initialized_for(position, scope).__send__(prepend_or_append, hook, options)
         end
 
         # @private
         #
         # Runs all of the blocks stored with the hook in the context of the
         # example. If no example is provided, just calls the hook directly.
-        def run(hook, scope, example_or_group, initial_procsy=nil)
+        def run(position, scope, example_or_group)
           return if RSpec.configuration.dry_run?
-          find_hook(hook, scope, example_or_group, initial_procsy).run
+
+          if scope == :context
+            run_owned_hooks_for(position, :context, example_or_group)
+          else
+            case position
+            when :before then run_example_hooks_for(example_or_group, :before, :reverse_each)
+            when :after  then run_example_hooks_for(example_or_group, :after,  :each)
+            when :around then run_around_example_hooks_for(example_or_group) { yield }
+            end
+          end
         end
 
-        SCOPES = [:example, :context, :suite]
+        SCOPES = [:example, :context]
 
         SCOPE_ALIASES = { :each => :example, :all => :context }
 
@@ -512,17 +488,89 @@ EOS
 
         HOOK_TYPES[:after][:context] = AfterContextHook
 
+      protected
+
+        EMPTY_HOOK_ARRAY = [].freeze
+
+        def matching_hooks_for(position, scope, example_or_group)
+          repository = hooks_for(position, scope) { return EMPTY_HOOK_ARRAY }
+
+          # It would be nice to not have to switch on type here, but
+          # we don't want to define `ExampleGroup#metadata` because then
+          # `metadata` from within an individual example would return the
+          # group's metadata but the user would probably expect it to be
+          # the example's metadata.
+          metadata = case example_or_group
+                     when ExampleGroup then example_or_group.class.metadata
+                     else example_or_group.metadata
+                     end
+
+          repository.items_for(metadata)
+        end
+
+        def all_hooks_for(position, scope)
+          hooks_for(position, scope) { return EMPTY_HOOK_ARRAY }.items_and_filters.map(&:first)
+        end
+
+        def run_owned_hooks_for(position, scope, example_or_group)
+          matching_hooks_for(position, scope, example_or_group).each do |hook|
+            hook.run(example_or_group)
+          end
+        end
+
+        def processable_hooks_for(position, scope, host)
+          if scope == :example
+            all_hooks_for(position, scope)
+          else
+            matching_hooks_for(position, scope, host)
+          end
+        end
+
       private
 
-        def process(host, globals, position, scope)
-          globals[position][scope].each do |hook|
-            next unless scope == :example || hook.options_apply?(host)
-            next if host.parent_groups.any? { |a| a.hooks[position][scope].include?(hook) }
-            self[position][scope] << hook
+        def hooks_for(position, scope)
+          if position == :before
+            scope == :example ? @before_example_hooks : @before_context_hooks
+          elsif position == :after
+            scope == :example ? @after_example_hooks : @after_context_hooks
+          else # around
+            @around_example_hooks
+          end || yield
+        end
+
+        def ensure_hooks_initialized_for(position, scope)
+          if position == :before
+            if scope == :example
+              @before_example_hooks ||= @filterable_item_repo_class.new(:all?)
+            else
+              @before_context_hooks ||= @filterable_item_repo_class.new(:all?)
+            end
+          elsif position == :after
+            if scope == :example
+              @after_example_hooks ||= @filterable_item_repo_class.new(:all?)
+            else
+              @after_context_hooks ||= @filterable_item_repo_class.new(:all?)
+            end
+          else # around
+            @around_example_hooks ||= @filterable_item_repo_class.new(:all?)
+          end
+        end
+
+        def process(host, parent_groups, globals, position, scope)
+          hooks_to_process = globals.processable_hooks_for(position, scope, host)
+          return if hooks_to_process.empty?
+
+          hooks_to_process -= FlatMap.flat_map(parent_groups) do |group|
+            group.hooks.all_hooks_for(position, scope)
           end
+          return if hooks_to_process.empty?
+
+          repository = ensure_hooks_initialized_for(position, scope)
+          hooks_to_process.each { |hook| repository.append hook, (yield hook) }
         end
 
         def scope_and_options_from(*args)
+          return :suite if args.first == :suite
           scope = extract_scope_from(args)
           meta  = Metadata.build_hash_from(args, :warn_about_example_group_filtering)
           return scope, meta
@@ -532,58 +580,51 @@ EOS
           if known_scope?(args.first)
             normalized_scope_for(args.shift)
           elsif args.any? { |a| a.is_a?(Symbol) }
-            error_message = "You must explicitly give a scope (#{SCOPES.join(", ")}) or scope alias (#{SCOPE_ALIASES.keys.join(", ")}) when using symbols as metadata for a hook."
+            error_message = "You must explicitly give a scope " \
+              "(#{SCOPES.join(", ")}) or scope alias " \
+              "(#{SCOPE_ALIASES.keys.join(", ")}) when using symbols as " \
+              "metadata for a hook."
             raise ArgumentError.new error_message
           else
             :example
           end
         end
 
-        # @api private
         def known_scope?(scope)
           SCOPES.include?(scope) || SCOPE_ALIASES.keys.include?(scope)
         end
 
-        # @api private
         def normalized_scope_for(scope)
           SCOPE_ALIASES[scope] || scope
         end
 
-        def find_hook(hook, scope, example_or_group, initial_procsy)
-          case [hook, scope]
-          when [:before, :context]
-            before_context_hooks_for(example_or_group)
-          when [:after, :context]
-            after_context_hooks_for(example_or_group)
-          when [:around, :example]
-            around_example_hooks_for(example_or_group, initial_procsy)
-          when [:before, :example]
-            before_example_hooks_for(example_or_group)
-          when [:after, :example]
-            after_example_hooks_for(example_or_group)
-          when [:before, :suite], [:after, :suite]
-            self[hook][:suite].with(example_or_group)
+        def run_example_hooks_for(example, position, each_method)
+          owner_parent_groups.__send__(each_method) do |group|
+            group.hooks.run_owned_hooks_for(position, :example, example)
           end
         end
 
-        def before_context_hooks_for(group)
-          GroupHookCollection.new(self[:before][:context]).for(group)
-        end
+        def run_around_example_hooks_for(example)
+          hooks = FlatMap.flat_map(owner_parent_groups) do |group|
+            group.hooks.matching_hooks_for(:around, :example, example)
+          end
 
-        def after_context_hooks_for(group)
-          GroupHookCollection.new(self[:after][:context]).for(group)
-        end
+          return yield if hooks.empty? # exit early to avoid the extra allocation cost of `Example::Procsy`
 
-        def before_example_hooks_for(example)
-          HookCollection.new(FlatMap.flat_map(@owner.parent_groups.reverse) do |a|
-            a.hooks[:before][:example]
-          end).for(example)
+          initial_procsy = Example::Procsy.new(example) { yield }
+          hooks.inject(initial_procsy) do |procsy, around_hook|
+            procsy.wrap { around_hook.execute_with(example, procsy) }
+          end.call
         end
 
-        def after_example_hooks_for(example)
-          HookCollection.new(FlatMap.flat_map(@owner.parent_groups) do |a|
-            a.hooks[:after][:example]
-          end).for(example)
+        if respond_to?(:singleton_class) && singleton_class.ancestors.include?(singleton_class)
+          def owner_parent_groups
+            @owner.parent_groups
+          end
+        else # Ruby < 2.1 (see https://bugs.ruby-lang.org/issues/8035)
+          def owner_parent_groups
+            @owner_parent_groups ||= [@owner] + @owner.parent_groups
+          end
         end
       end
     end