rspec-expectations 3.0.0.beta2 → 3.0.0.rc1

data/lib/rspec/matchers/built_in/match.rb

@@ -1,19 +1,29 @@
 module RSpec
   module Matchers
     module BuiltIn
+      # @api private
+      # Provides the implementation for `match`.
+      # Not intended to be instantiated directly.
       class Match < BaseMatcher
-        def match(expected, actual)
-          return true if values_match?(expected, actual)
-          actual.match(expected) if actual.respond_to?(:match)
-        end
 
+        # @api private
+        # @return [String]
         def description
           "match #{surface_descriptions_in(expected).inspect}"
         end
 
+        # @api private
+        # @return [Boolean]
         def diffable?
           true
         end
+
+      private
+
+        def match(expected, actual)
+          return true if values_match?(expected, actual)
+          actual.match(expected) if actual.respond_to?(:match)
+        end
       end
     end
   end

data/lib/rspec/matchers/built_in/operators.rb

@@ -3,21 +3,29 @@ require 'rspec/support'
 module RSpec
   module Matchers
     module BuiltIn
+      # @api private
+      # Provides the implementation for operator matchers.
+      # Not intended to be instantiated directly.
+      # Only available for use with `should`.
       class OperatorMatcher
         class << self
+          # @private
           def registry
             @registry ||= {}
           end
 
+          # @private
           def register(klass, operator, matcher)
             registry[klass] ||= {}
             registry[klass][operator] = matcher
           end
 
+          # @private
           def unregister(klass, operator)
             registry[klass] && registry[klass].delete(operator)
           end
 
+          # @private
           def get(klass, operator)
             klass.ancestors.each { |ancestor|
               matcher = registry[ancestor] && registry[ancestor][operator]
@@ -34,6 +42,7 @@ module RSpec
           @actual = actual
         end
 
+        # @private
         def self.use_custom_matcher_or_delegate(operator)
           define_method(operator) do |expected|
             if uses_generic_implementation_of?(operator) && matcher = OperatorMatcher.get(@actual.class, operator)
@@ -57,10 +66,13 @@ module RSpec
           use_custom_matcher_or_delegate operator
         end
 
+        # @private
         def fail_with_message(message)
           RSpec::Expectations.fail_with(message, @expected, @actual)
         end
 
+        # @api private
+        # @return [String]
         def description
           "#{@operator} #{@expected.inspect}"
         end
@@ -80,6 +92,8 @@ module RSpec
         end
       end
 
+      # @private
+      # Handles operator matcher for `should`.
       class PositiveOperatorMatcher < OperatorMatcher
         def __delegate_operator(actual, operator, expected)
           if actual.__send__(operator, expected)
@@ -92,6 +106,8 @@ module RSpec
         end
       end
 
+      # @private
+      # Handles operator matcher for `should_not`.
       class NegativeOperatorMatcher < OperatorMatcher
         def __delegate_operator(actual, operator, expected)
           return false unless actual.__send__(operator, expected)

data/lib/rspec/matchers/built_in/output.rb

@@ -3,6 +3,9 @@ require 'stringio'
 module RSpec
   module Matchers
     module BuiltIn
+      # @api private
+      # Provides the implementation for `output`.
+      # Not intended to be instantiated directly.
       class Output < BaseMatcher
         def initialize(expected)
           @expected = expected
@@ -10,29 +13,44 @@ module RSpec
         end
 
         def matches?(block)
+          @block = block
+          return false unless Proc === block
           @actual = @stream_capturer.capture(block)
-
           @expected ? values_match?(@expected, @actual) : captured?
         end
 
+        def does_not_match?(block)
+          !matches?(block) && Proc === block
+        end
+
+        # @api public
+        # Tells the matcher to match against stdout.
         def to_stdout
           @stream_capturer = CaptureStdout
           self
         end
 
+        # @api public
+        # Tells the matcher to match against stderr.
         def to_stderr
           @stream_capturer = CaptureStderr
           self
         end
 
+        # @api private
+        # @return [String]
         def failure_message
-          "expected block to #{description}, #{actual_description}"
+          "expected block to #{description}, but #{positive_failure_reason}"
         end
 
+        # @api private
+        # @return [String]
         def failure_message_when_negated
-          "expected block to not #{description}, but did"
+          "expected block to not #{description}, but #{negative_failure_reason}"
         end
 
+        # @api private
+        # @return [String]
         def description
           if @expected
             "output #{description_of @expected} to #{@stream_capturer.name}"
@@ -41,21 +59,43 @@ module RSpec
           end
         end
 
+        # @api private
+        # @return [Boolean]
         def diffable?
           true
         end
 
+        # @api private
+        # Indicates this matcher matches against a block.
+        # @return [True]
+        def supports_block_expectations?
+          true
+        end
+
       private
 
         def captured?
           @actual.length > 0
         end
 
-        def actual_description
-          @expected ? "but output #{captured? ? @actual.inspect : 'nothing'}" : "but did not"
+        def positive_failure_reason
+          return "was not a block" unless Proc === @block
+          return "output #{actual_output_description}" if @expected
+          "did not"
+        end
+
+        def negative_failure_reason
+          return "was not a block" unless Proc === @block
+          "output #{actual_output_description}"
+        end
+
+        def actual_output_description
+          return "nothing" unless captured?
+          @actual.inspect
         end
       end
 
+      # @private
       module NullCapture
         def self.name
           "some stream"
@@ -66,6 +106,7 @@ module RSpec
         end
       end
 
+      # @private
       module CaptureStdout
         def self.name
           'stdout'
@@ -85,6 +126,7 @@ module RSpec
         end
       end
 
+      # @private
       module CaptureStderr
         def self.name
           'stderr'

data/lib/rspec/matchers/built_in/raise_error.rb

@@ -1,6 +1,9 @@
 module RSpec
   module Matchers
     module BuiltIn
+      # @api private
+      # Provides the implementation for `raise_error`.
+      # Not intended to be instantiated directly.
       class RaiseError
         include Composable
 
@@ -15,23 +18,24 @@ module RSpec
           end
         end
 
+        # @api public
+        # Specifies the expected error message.
         def with_message(expected_message)
           raise_message_already_set if @expected_message
           @expected_message = expected_message
           self
         end
 
+        # @private
         def matches?(given_proc, negative_expectation = false, &block)
+          @given_proc = given_proc
           @block ||= block
           @raised_expected_error = false
           @with_expected_message = false
           @eval_block = false
           @eval_block_passed = false
 
-          unless given_proc.respond_to?(:call)
-            ::Kernel.warn "`raise_error` was called with non-proc object #{given_proc.inspect}"
-            return false
-          end
+          return false unless Proc === given_proc
 
           begin
             given_proc.call
@@ -49,6 +53,37 @@ module RSpec
           expectation_matched?
         end
 
+        # @private
+        def does_not_match?(given_proc)
+          prevent_invalid_expectations
+          !matches?(given_proc, :negative_expectation) && Proc === given_proc
+        end
+
+        # @private
+        def supports_block_expectations?
+          true
+        end
+
+        # @api private
+        # @return [String]
+        def failure_message
+          @eval_block ? @actual_error.message : "expected #{expected_error}#{given_error}"
+        end
+
+        # @api private
+        # @return [String]
+        def failure_message_when_negated
+          "expected no #{expected_error}#{given_error}"
+        end
+
+        # @api private
+        # @return [String]
+        def description
+          "raise #{expected_error}"
+        end
+
+      private
+
         def expectation_matched?
           error_and_message_match? && block_matches?
         end
@@ -61,11 +96,6 @@ module RSpec
           @eval_block ? @eval_block_passed : true
         end
 
-        def does_not_match?(given_proc)
-          prevent_invalid_expectations
-          !matches?(given_proc, :negative_expectation)
-        end
-
         def eval_block
           @eval_block = true
           begin
@@ -81,20 +111,6 @@ module RSpec
           values_match?(@expected_message, @actual_error.message)
         end
 
-        def failure_message
-          @eval_block ? @actual_error.message : "expected #{expected_error}#{given_error}"
-        end
-
-        def failure_message_when_negated
-          "expected no #{expected_error}#{given_error}"
-        end
-
-        def description
-          "raise #{expected_error}"
-        end
-
-        private
-
         def prevent_invalid_expectations
           if (expecting_specific_exception? || @expected_message)
             what_to_raise = if expecting_specific_exception? && @expected_message
@@ -126,6 +142,7 @@ module RSpec
         end
 
         def given_error
+          return " but was not given a block" unless Proc === @given_proc
           return " but nothing was raised" unless @actual_error
 
           backtrace = format_backtrace(@actual_error.backtrace)

data/lib/rspec/matchers/built_in/respond_to.rb

@@ -1,6 +1,9 @@
 module RSpec
   module Matchers
     module BuiltIn
+      # @api private
+      # Provides the implementation for `respond_to`.
+      # Not intended to be instantiated directly.
       class RespondTo
         include Composable
 
@@ -9,37 +12,60 @@ module RSpec
           @expected_arity = nil
         end
 
+        # @api public
+        # Specifies the number of expected arguments.
+        #
+        # @example
+        #   expect(obj).to respond_to(:message).with(3).arguments
+        def with(n)
+          @expected_arity = n
+          self
+        end
+
+        # @api public
+        # No-op. Intended to be used as syntactic sugar when using `with`.
+        #
+        # @example
+        #   expect(obj).to respond_to(:message).with(3).arguments
+        def argument
+          self
+        end
+        alias :arguments :argument
+
+        # @private
         def matches?(actual)
           find_failing_method_names(actual, :reject).empty?
         end
 
+        # @private
         def does_not_match?(actual)
           find_failing_method_names(actual, :select).empty?
         end
 
+        # @api private
+        # @return [String]
         def failure_message
           "expected #{@actual.inspect} to respond to #{@failing_method_names.collect {|name| name.inspect }.join(', ')}#{with_arity}"
         end
 
+        # @api private
+        # @return [String]
         def failure_message_when_negated
           failure_message.sub(/to respond to/, 'not to respond to')
         end
 
+        # @api private
+        # @return [String]
         def description
           "respond to #{pp_names}#{with_arity}"
         end
 
-        def with(n)
-          @expected_arity = n
-          self
+        # @private
+        def supports_block_expectations?
+          false
         end
 
-        def argument
-          self
-        end
-        alias :arguments :argument
-
-        private
+      private
 
         def find_failing_method_names(actual, filter_method)
           @actual = actual
@@ -51,13 +77,8 @@ module RSpec
         def matches_arity?(actual, name)
           return true unless @expected_arity
 
-          actual_arity = actual.method(name).arity
-          if actual_arity < 0
-            # ~ inverts the one's complement and gives us the number of required args
-            ~actual_arity <= @expected_arity
-          else
-            actual_arity == @expected_arity
-          end
+          signature = Support::MethodSignature.new(actual.method(name))
+          Support::MethodSignatureVerifier.new(signature, Array.new(@expected_arity)).valid?
         end
 
         def with_arity

data/lib/rspec/matchers/built_in/satisfy.rb

@@ -1,6 +1,9 @@
 module RSpec
   module Matchers
     module BuiltIn
+      # @api private
+      # Provides the implementation for `satisfy`.
+      # Not intended to be instantiated directly.
       class Satisfy
         include Composable
 
@@ -8,23 +11,35 @@ module RSpec
           @block = block
         end
 
+        # @private
         def matches?(actual, &block)
           @block = block if block
           @actual = actual
           @block.call(actual)
         end
 
+        # @api private
+        # @return [String]
         def failure_message
           "expected #{@actual} to satisfy block"
         end
 
+        # @api private
+        # @return [String]
         def failure_message_when_negated
           "expected #{@actual} not to satisfy block"
         end
 
+        # @api private
+        # @return [String]
         def description
           "satisfy block"
         end
+
+        # @private
+        def supports_block_expectations?
+          false
+        end
       end
     end
   end