rspec-core 2.8.0.rc1 → 2.8.0.rc2

data/lib/rspec/core/extensions.rb

@@ -1,4 +1,4 @@
-require 'rspec/core/extensions/kernel'
-require 'rspec/core/extensions/instance_eval_with_args'
-require 'rspec/core/extensions/module_eval_with_args'
-require 'rspec/core/extensions/ordered'
+require_rspec 'core/extensions/kernel'
+require_rspec 'core/extensions/instance_eval_with_args'
+require_rspec 'core/extensions/module_eval_with_args'
+require_rspec 'core/extensions/ordered'

data/lib/rspec/core/extensions/instance_eval_with_args.rb

@@ -1,7 +1,12 @@
 module RSpec
   module Core
     module Extensions
+      # @private
       module InstanceEvalWithArgs
+        # @private
+        #
+        # Used internally to support `instance_exec` in Ruby 1.8.6.
+        #
         # based on Bounded Spec InstanceExec (Mauricio Fernandez)
         # http://eigenclass.org/hiki/bounded+space+instance_exec
         # - uses singleton_class instead of global InstanceExecHelper module

data/lib/rspec/core/extensions/kernel.rb

@@ -1,5 +1,5 @@
 module Kernel
-  unless respond_to?(:debugger)
+  unless defined?(debugger)
     # If not already defined by ruby-debug, this implementation prints helpful
     # message to STDERR when ruby-debug is not loaded.
     def debugger(*args)

data/lib/rspec/core/extensions/module_eval_with_args.rb

@@ -1,9 +1,13 @@
 module RSpec
   module Core
     module Extensions
+      # @private
       module ModuleEvalWithArgs
         include InstanceEvalWithArgs
 
+        # @private
+        #
+        # Used internally to support `module_exec` in Ruby 1.8.6.
         def module_eval_with_args(*args, &block)
           # ruby > 1.8.6
           return module_exec(*args, &block) if respond_to?(:module_exec)

data/lib/rspec/core/extensions/ordered.rb

@@ -1,11 +1,16 @@
 module RSpec
   module Core
+    # @private
     module Extensions
+      # @private
+      # Used to extend lists of examples and groups to support ordering
+      # strategies like randomization.
       module Ordered
+        # @private
         def ordered
           if RSpec.configuration.randomize?
-            srand RSpec.configuration.seed
-            sort_by { rand size }
+            Kernel.srand RSpec.configuration.seed
+            sort_by { Kernel.rand size }
           else
             self
           end

data/lib/rspec/core/filter_manager.rb

@@ -61,6 +61,10 @@ module RSpec
     #     end
     #
     # These declarations can also be overridden from the command line.
+    #
+    # @see RSpec.configure
+    # @see Configuration#filter_run_including
+    # @see Configuration#filter_run_excluding
     class FilterManager
       DEFAULT_EXCLUSIONS = {
         :if     => lambda { |value, metadata| metadata.has_key?(:if) && !value },
@@ -83,20 +87,29 @@ module RSpec
       end
 
       module BackwardCompatibility
-        # This is to support a use case that probably doesn't exist: overriding
-        # the if/unless procs.
-        def update(orig, opposite, *updates)
-          if updates.last.has_key?(:unless)
-            RSpec.warn_deprecation("\nDEPRECATION NOTICE: FilterManager#exclude(:unless => #{updates.last[:unless].inspect}) is deprecated with no replacement, and will be removed from rspec-3.0.")
-            @exclusions[:unless] = updates.last.delete(:unless)
-          end
-          if updates.last.has_key?(:if)
-            RSpec.warn_deprecation("\nDEPRECATION NOTICE: FilterManager#exclude(:if => #{updates.last[:if].inspect}) is deprecated with no replacement, and will be removed from rspec-3.0.")
-            @exclusions[:if] = updates.last.delete(:if)
-          end
+        def merge(orig, opposite, *updates)
+          _warn_deprecated_keys(updates.last)
+          super
+        end
 
+        def reverse_merge(orig, opposite, *updates)
+          _warn_deprecated_keys(updates.last)
           super
         end
+
+        # Supports a use case that probably doesn't exist: overriding the
+        # if/unless procs.
+        def _warn_deprecated_keys(updates)
+          _warn_deprecated_key(:unless, updates) if updates.has_key?(:unless)
+          _warn_deprecated_key(:if, updates)     if updates.has_key?(:if)
+        end
+
+        # Emits a deprecation warning for keys that will not be supported in
+        # the future.
+        def _warn_deprecated_key(key, updates)
+          RSpec.warn_deprecation("\nDEPRECATION NOTICE: FilterManager#exclude(#{key.inspect} => #{updates[key].inspect}) is deprecated with no replacement, and will be removed from rspec-3.0.")
+          @exclusions[key] = updates.delete(key)
+        end
       end
 
       attr_reader :exclusions, :inclusions
@@ -108,14 +121,13 @@ module RSpec
       end
 
       def add_location(file_path, line_numbers)
-        # filter_locations is a hash of expanded paths to arrays of line
+        # locations is a hash of expanded paths to arrays of line
         # numbers to match against. e.g.
         #   { "path/to/file.rb" => [37, 42] }
-        filter_locations = @inclusions[:locations] ||= Hash.new {|h,k| h[k] = []}
+        locations = @inclusions.delete(:locations) || Hash.new {|h,k| h[k] = []}
+        locations[File.expand_path(file_path)].push(*line_numbers)
+        @inclusions.replace(:locations => locations)
         @exclusions.clear
-        @inclusions.clear
-        filter_locations[File.expand_path(file_path)].push(*line_numbers)
-        include :locations => filter_locations
       end
 
       def empty?
@@ -126,36 +138,57 @@ module RSpec
         examples.select {|e| !exclude?(e) && include?(e)}
       end
 
+      def exclude(*args)
+        merge(@exclusions, @inclusions, *args)
+      end
+
+      def exclude!(*args)
+        replace(@exclusions, @inclusions, *args)
+      end
+
+      def exclude_with_low_priority(*args)
+        reverse_merge(@exclusions, @inclusions, *args)
+      end
+
       def exclude?(example)
         @exclusions.empty? ? false : example.any_apply?(@exclusions)
       end
 
+      def include(*args)
+        unless_standalone(*args) { merge(@inclusions, @exclusions, *args) }
+      end
+
+      def include!(*args)
+        unless_standalone(*args) { replace(@inclusions, @exclusions, *args) }
+      end
+
+      def include_with_low_priority(*args)
+        unless_standalone(*args) { reverse_merge(@inclusions, @exclusions, *args) }
+      end
+
       def include?(example)
         @inclusions.empty? ? true : example.any_apply?(@inclusions)
       end
 
-      def exclude(*args)
-        update(@exclusions, @inclusions, *args)
+      private
+
+      def unless_standalone(*args)
+        is_standalone_filter?(args.last) ? @inclusions.replace(args.last) : yield unless already_set_standalone_filter?
       end
 
-      def include(*args)
-        return if already_set_standalone_filter?
-
-        is_standalone_filter?(args.last) ? @inclusions.replace(args.last) : update(@inclusions, @exclusions, *args)
-      end
-
-      def update(orig, opposite, *updates)
-        if updates.length == 2
-          if updates[0] == :replace
-            updated = updates.last
-          else
-            updated = updates.last.merge(orig)
-            opposite.each_key {|k| updated.delete(k)}
-          end
-          orig.replace(updated)
-        else
-          orig.merge!(updates.last).each_key {|k| opposite.delete(k)}
-        end
+      def merge(orig, opposite, *updates)
+        orig.merge!(updates.last).each_key {|k| opposite.delete(k)}
+      end
+
+      def replace(orig, opposite, *updates)
+        updates.last.each_key {|k| opposite.delete(k)}
+        orig.replace(updates.last)
+      end
+
+      def reverse_merge(orig, opposite, *updates)
+        updated = updates.last.merge(orig)
+        opposite.each_pair {|k,v| updated.delete(k) if updated[k] == v}
+        orig.replace(updated)
       end
 
       def already_set_standalone_filter?

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

@@ -159,7 +159,7 @@ module RSpec
         end
 
         def dump_pending_example_fixed(example, index)
-          if RSpec::Core::PendingExampleFixedError === example.execution_result[:exception]
+          if example.execution_result[:exception].pending_fixed?
             output.puts "#{short_padding}#{index.next}) #{example.full_description} FIXED"
             output.puts blue("#{long_padding}Expected pending '#{example.metadata[:execution_result][:pending_message]}' to fail. No Error was raised.")
             true

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

@@ -67,7 +67,7 @@ module RSpec
 
         def example_passed(example)
           move_progress
-          @output.puts "    <dd class=\"example passed\"><span class=\"passed_spec_name\">#{h(example.description)}</span></dd>"
+          @output.puts "    <dd class=\"example passed\"><span class=\"passed_spec_name\">#{h(example.description)}</span><span class='duration'>#{sprintf("%.5f", example.execution_result[:run_time])}s</span></dd>"
           @output.flush
         end
 
@@ -75,15 +75,15 @@ module RSpec
           super(example)
           exception = example.metadata[:execution_result][:exception]
           extra = extra_failure_content(exception)
-          failure_style = RSpec::Core::PendingExampleFixedError === exception ? 'pending_fixed' : 'failed'
           @output.puts "    <script type=\"text/javascript\">makeRed('rspec-header');</script>" unless @header_red
           @header_red = true
           @output.puts "    <script type=\"text/javascript\">makeRed('div_group_#{example_group_number}');</script>" unless @example_group_red
           @output.puts "    <script type=\"text/javascript\">makeRed('example_group_#{example_group_number}');</script>" unless @example_group_red
           @example_group_red = true
           move_progress
-          @output.puts "    <dd class=\"example #{failure_style}\">"
+          @output.puts "    <dd class=\"example #{exception.pending_fixed? ? 'pending_fixed' : 'failed'}\">"
           @output.puts "      <span class=\"failed_spec_name\">#{h(example.description)}</span>"
+          @output.puts "      <span class=\"duration\">#{sprintf('%.5f', example.execution_result[:run_time])}s</span>"
           @output.puts "      <div class=\"failure\" id=\"failure_#{@failed_examples.size}\">"
           @output.puts "        <div class=\"message\"><pre>#{h(exception.message)}</pre></div>" unless exception.nil?
           @output.puts "        <div class=\"backtrace\"><pre>#{format_backtrace(exception.backtrace, example).join("\n")}</pre></div>" if exception
@@ -142,7 +142,7 @@ module RSpec
             totals << "#{failure_count} failure#{'s' unless failure_count == 1}"
             totals << ", #{pending_count} pending" if pending_count > 0
           end
-          @output.puts "<script type=\"text/javascript\">document.getElementById('duration').innerHTML = \"Finished in <strong>#{duration} seconds</strong>\";</script>"
+          @output.puts "<script type=\"text/javascript\">document.getElementById('duration').innerHTML = \"Finished in <strong>#{sprintf("%.5f", duration)} seconds</strong>\";</script>"
           @output.puts "<script type=\"text/javascript\">document.getElementById('totals').innerHTML = \"#{totals}\";</script>"
           @output.puts "</div>"
           @output.puts "</div>"
@@ -354,6 +354,12 @@ dd {
   padding: 3px 3px 3px 18px;
 }
 
+dd .duration {
+  padding-left: 5px;
+  text-align: right;
+  right: 0px;
+  float:right;
+}
 
 dd.example.passed {
   border-left: 5px solid #65C400;

data/lib/rspec/core/hooks.rb

@@ -87,7 +87,7 @@ module RSpec
 
       class AroundHooks < HookCollection; end
 
-      # @api private
+      # @private
       def hooks
         @hooks ||= {
           :around => { :each => AroundHooks.new },
@@ -99,10 +99,15 @@ module RSpec
       # @api public
       # @overload before(&block)
       # @overload before(scope, &block)
-      # @overload before(scope, tags, &block)
-      # @overload before(tags, &block)
+      # @overload before(scope, conditions, &block)
+      # @overload before(conditions, &block)
+      #
       # @param [Symbol] scope `:each`, `:all`, or `:suite` (defaults to `:each`)
-      # @param [Hash] tags
+      # @param [Hash] conditions
+      #   constrains this hook to examples matching these conditions e.g.
+      #   `before(:each, :ui => true) { ... }` will only run with examples or
+      #   groups declared with `:ui => true`.
+      #
       # @see #after
       # @see #around
       # @see ExampleGroup
@@ -122,12 +127,6 @@ module RSpec
       # Instance variables declared in `before(:each)` or `before(:all)` are
       # accessible within each example.
       #
-      # ### Exceptions
-      #
-      # When an exception is raised in a `before` block, RSpec skips any
-      # subsequent `before` blocks and the example, but runs all of the
-      # `after(:each)` and `after(:all)` hooks.
-      #
       # ### Order
       #
       # `before` hooks are stored in three scopes, which are run in order:
@@ -135,16 +134,55 @@ module RSpec
       # different places: `RSpec.configure`, a parent group, the current group.
       # They are run in the following order:
       #
-      #     before(:all) declared in RSpec.configure
-      #     before(:all) declared in a parent group
-      #     before(:all) declared in the current group
-      #     before(:each) declared in RSpec.configure
-      #     before(:each) declared in a parent group
-      #     before(:each) declared in the current group
+      #     before(:suite) # declared in RSpec.configure
+      #     before(:all)   # declared in RSpec.configure
+      #     before(:all)   # declared in a parent group
+      #     before(:all)   # declared in the current group
+      #     before(:each)  # declared in RSpec.configure
+      #     before(:each)  # declared in a parent group
+      #     before(:each)  # 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(:each)` or `before(:all)`,
+      # RSpec will only apply that hook to groups or examples that match the
+      # conditions. e.g.
+      #
+      #     RSpec.configure do |config|
+      #       config.before(:each, :authorized => true) do
+      #         log_in_as :authorized_user
+      #       end
+      #     end
+      #
+      #     describe Something, :authorized => true do
+      #       # 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
+      #       end
+      #
+      #       it "does something else" do
+      #         # the hook will not run before this example
+      #       end
+      #     end
+      #
+      # ### Warning: `before(:suite, :with => :conditions)`
+      #
+      # The conditions hash is used to match against specific examples. Since
+      # `before(:suite)` is not run in relation to any specific example or
+      # group, conditions passed along with `:suite` are effectively ignored.
+      #
+      # ### Exceptions
+      #
+      # When an exception is raised in a `before` block, RSpec skips any
+      # subsequent `before` blocks and the example, but runs all of the
+      # `after(:each)` and `after(:all)` hooks.
+      #
       # ### Warning: implicit before blocks
       #
       # `before` hooks can also be declared in shared contexts which get
@@ -203,8 +241,8 @@ module RSpec
       #       before(:all) do
       #         File.open(file_to_parse, 'w') do |f|
       #           f.write <<-CONTENT
-      #             Stuff in the file
-      #           end
+      #             stuff in the file
+      #           CONTENT
       #         end
       #       end
       #
@@ -224,10 +262,15 @@ module RSpec
       # @api public
       # @overload after(&block)
       # @overload after(scope, &block)
-      # @overload after(scope, tags, &block)
-      # @overload after(tags, &block)
+      # @overload after(scope, conditions, &block)
+      # @overload after(conditions, &block)
+      #
       # @param [Symbol] scope `:each`, `:all`, or `:suite` (defaults to `:each`)
-      # @param [Hash] tags
+      # @param [Hash] conditions
+      #   constrains this hook to examples matching these conditions e.g.
+      #   `after(:each, :ui => true) { ... }` will only run with examples or
+      #   groups declared with `:ui => true`.
+      #
       # @see #before
       # @see #around
       # @see ExampleGroup
@@ -254,12 +297,12 @@ module RSpec
       # different places: `RSpec.configure`, a parent group, the current group.
       # They are run in the following order:
       #
-      #     after(:each) declared in the current group
-      #     after(:each) declared in a parent group
-      #     after(:each) declared in RSpec.configure
-      #     after(:all) declared in the current group
-      #     after(:all) declared in a parent group
-      #     after(:all) declared in RSpec.configure
+      #     after(:each) # declared in the current group
+      #     after(:each) # declared in a parent group
+      #     after(:each) # declared in RSpec.configure
+      #     after(:all)  # declared in the current group
+      #     after(:all)  # declared in a parent group
+      #     after(:all)  # 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,
@@ -272,12 +315,28 @@ module RSpec
       # @api public
       # @overload around(&block)
       # @overload around(scope, &block)
-      # @overload around(scope, tags, &block)
-      # @overload around(tags, &block)
+      # @overload around(scope, conditions, &block)
+      # @overload around(conditions, &block)
+      #
       # @param [Symbol] scope `:each` (defaults to `:each`)
-      # @param [Hash] tags
+      #   present for syntax parity with `before` and `after`, but `:each` is
+      #   the only supported value.
+      #
+      # @param [Hash] conditions
+      #   constrains this hook to examples matching these conditions e.g.
+      #   `around(:each, :ui => true) { ... }` will only run with examples or
+      #   groups declared with `:ui => true`.
+      #
       # @yield [Example] the example to run
       #
+      # @note the syntax of `around` is similar to that of `before` and `after`
+      #   but the semantics are quite different. `before` and `after` hooks are
+      #   run in the context of of the examples with which they are associated,
+      #   whereas `around` hooks are actually responsible for running the
+      #   examples. Consequently, `around` hooks do not have direct access to
+      #   resources that are made available within the examples and their
+      #   associated `before` and `after` hooks.
+      #
       # @note `:each` is the only supported scope.
       #
       # Declare a block of code, parts of which will be run before and parts
@@ -302,26 +361,26 @@ module RSpec
         hooks[:around][scope] << AroundHook.new(options, &block)
       end
 
-      # @api private
+      # @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(hook, scope, example_group_instance=nil)
         hooks[hook][scope].run_all(example_group_instance)
       end
 
-      # @api private
+      # @private
       # Just like run_hook, except it removes the blocks as it evalutes them,
       # ensuring that they will only be run once.
       def run_hook!(hook, scope, example_group_instance)
         hooks[hook][scope].run_all!(example_group_instance)
       end
 
-      # @api private
+      # @private
       def run_hook_filtered(hook, scope, group, example_group_instance, example = nil)
         find_hook(hook, scope, group, example).run_all(example_group_instance)
       end
 
-      # @api private
+      # @private
       def find_hook(hook, scope, example_group_class, example = nil)
         found_hooks = hooks[hook][scope].find_hooks_for(example || example_group_class)