rspec-expectations 3.0.0.beta2 → 3.0.0.rc1

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

@@ -1,12 +1,23 @@
 module RSpec
   module Matchers
     module BuiltIn
+      # @api private
+      # Provides the implementation for `be_between`.
+      # Not intended to be instantiated directly.
       class BeBetween < BaseMatcher
         def initialize(min, max)
           @min, @max = min, max
           inclusive
         end
 
+        # @api public
+        # Makes the between comparison inclusive.
+        #
+        # @example
+        #   expect(3).to be_between(2, 3).inclusive
+        #
+        # @note The matcher is inclusive by default; this simply provides
+        #       a way to be more explicit about it.
         def inclusive
           @less_than_operator = :<=
           @greater_than_operator = :>=
@@ -14,6 +25,11 @@ module RSpec
           self
         end
 
+        # @api public
+        # Makes the between comparison exclusive.
+        #
+        # @example
+        #   expect(3).to be_between(2, 4).exclusive
         def exclusive
           @less_than_operator = :<
           @greater_than_operator = :>
@@ -21,6 +37,8 @@ module RSpec
           self
         end
 
+        # @api private
+        # @return [Boolean]
         def matches?(actual)
           @actual = actual
           comparable? && compare
@@ -28,10 +46,14 @@ module RSpec
           false
         end
 
+        # @api private
+        # @return [String]
         def failure_message
           "#{super}#{not_comparable_clause}"
         end
 
+        # @api private
+        # @return [String]
         def description
           "be between #{@min.inspect} and #{@max.inspect} (#{@mode})"
         end

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

@@ -1,14 +1,22 @@
 module RSpec
   module Matchers
     module BuiltIn
+      # @api private
+      # Provides the implementation for `be_an_instance_of`.
+      # Not intended to be instantiated directly.
       class BeAnInstanceOf < BaseMatcher
-        def match(expected, actual)
-          actual.instance_of? expected
-        end
 
+        # @api private
+        # @return [String]
         def description
           "be an instance of #{expected}"
         end
+
+      private
+
+        def match(expected, actual)
+          actual.instance_of? expected
+        end
       end
     end
   end

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

@@ -1,7 +1,12 @@
 module RSpec
   module Matchers
     module BuiltIn
+      # @api private
+      # Provides the implementation for `be_a_kind_of`.
+      # Not intended to be instantiated directly.
       class BeAKindOf < BaseMatcher
+
+      private
         def match(expected, actual)
           actual.kind_of? expected
         end

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

@@ -1,6 +1,9 @@
 module RSpec
   module Matchers
     module BuiltIn
+      # @api private
+      # Provides the implementation for `be_within`.
+      # Not intended to be instantiated directly.
       class BeWithin
         include Composable
 
@@ -8,12 +11,8 @@ module RSpec
           @delta = delta
         end
 
-        def matches?(actual)
-          @actual = actual
-          raise needs_expected unless defined? @expected
-          numeric? && (@actual - @expected).abs <= @tolerance
-        end
-
+        # @api public
+        # Sets the expected value.
         def of(expected)
           @expected  = expected
           @tolerance = @delta
@@ -21,6 +20,9 @@ module RSpec
           self
         end
 
+        # @api public
+        # Sets the expected value, and makes the matcher do
+        # a percent comparison.
         def percent_of(expected)
           @expected  = expected
           @tolerance = @delta * @expected.abs / 100.0
@@ -28,18 +30,36 @@ module RSpec
           self
         end
 
+        # @private
+        def matches?(actual)
+          @actual = actual
+          raise needs_expected unless defined? @expected
+          numeric? && (@actual - @expected).abs <= @tolerance
+        end
+
+        # @api private
+        # @return [String]
         def failure_message
           "expected #{@actual.inspect} to #{description}#{not_numeric_clause}"
         end
 
+        # @api private
+        # @return [String]
         def failure_message_when_negated
           "expected #{@actual.inspect} not to #{description}"
         end
 
+        # @api private
+        # @return [String]
         def description
           "be within #{@delta}#{@unit} of #{@expected}"
         end
 
+        # @private
+        def supports_block_expectations?
+          false
+        end
+
       private
 
         def numeric?

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

@@ -1,10 +1,13 @@
 module RSpec
   module Matchers
     module BuiltIn
-      # Describes an expected mutation.
+      # @api private
+      # Provides the implementation for `change`.
+      # Not intended to be instantiated directly.
       class Change
         include Composable
 
+        # @api public
         # Specifies the delta of the expected change.
         def by(expected_delta)
           ChangeRelatively.new(@change_details, expected_delta, :by) do |actual_delta|
@@ -12,6 +15,7 @@ module RSpec
           end
         end
 
+        # @api public
         # Specifies a minimum delta of the expected change.
         def by_at_least(minimum)
           ChangeRelatively.new(@change_details, minimum, :by_at_least) do |actual_delta|
@@ -19,6 +23,7 @@ module RSpec
           end
         end
 
+        # @api public
         # Specifies a maximum delta of the expected change.
         def by_at_most(maximum)
           ChangeRelatively.new(@change_details, maximum, :by_at_most) do |actual_delta|
@@ -26,38 +31,55 @@ module RSpec
           end
         end
 
+        # @api public
         # Specifies the new value you expect.
         def to(value)
           ChangeToValue.new(@change_details, value)
         end
 
+        # @api public
         # Specifies the original value.
         def from(value)
           ChangeFromValue.new(@change_details, value)
         end
 
-        # @api private
+        # @private
         def matches?(event_proc)
+          @event_proc = event_proc
+          return false unless Proc === event_proc
           raise_block_syntax_error if block_given?
           @change_details.perform_change(event_proc)
           @change_details.changed?
         end
 
+        def does_not_match?(event_proc)
+          raise_block_syntax_error if block_given?
+          !matches?(event_proc) && Proc === event_proc
+        end
+
         # @api private
+        # @return [String]
         def failure_message
-          "expected #{@change_details.message} to have changed, but is still #{description_of @change_details.actual_before}"
+          "expected #{@change_details.message} to have changed, but #{positive_failure_reason}"
         end
 
         # @api private
+        # @return [String]
         def failure_message_when_negated
-          "expected #{@change_details.message} not to have changed, but did change from #{description_of @change_details.actual_before} to #{description_of @change_details.actual_after}"
+          "expected #{@change_details.message} not to have changed, but #{negative_failure_reason}"
         end
 
         # @api private
+        # @return [String]
         def description
           "change #{@change_details.message}"
         end
 
+        # @private
+        def supports_block_expectations?
+          true
+        end
+
       private
 
         def initialize(receiver=nil, message=nil, &block)
@@ -68,6 +90,16 @@ module RSpec
           raise SyntaxError,
             "The block passed to the `change` matcher must use `{ ... }` instead of do/end"
         end
+
+        def positive_failure_reason
+          return "was not given a block" unless Proc === @event_proc
+          "is still #{description_of @change_details.actual_before}"
+        end
+
+        def negative_failure_reason
+          return "was not given a block" unless Proc === @event_proc
+          "did change from #{description_of @change_details.actual_before} to #{description_of @change_details.actual_after}"
+        end
       end
 
       # Used to specify a relative change.
@@ -82,30 +114,47 @@ module RSpec
           @comparer       = comparer
         end
 
+        # @private
         def failure_message
-          "expected #{@change_details.message} to have changed #{@relativity.to_s.gsub("_", " ")} #{description_of @expected_delta}, " +
-          "but was changed by #{description_of @change_details.actual_delta}"
+          "expected #{@change_details.message} to have changed #{@relativity.to_s.gsub("_", " ")} #{description_of @expected_delta}, but #{failure_reason}"
         end
 
+        # @private
         def matches?(event_proc)
+          @event_proc = event_proc
+          return false unless Proc === event_proc
           @change_details.perform_change(event_proc)
           @comparer.call(@change_details.actual_delta)
         end
 
+        # @private
         def does_not_match?(event_proc)
           raise NotImplementedError, "`expect { }.not_to change { }.#{@relativity}()` is not supported"
         end
 
-        # @api private
+        # @private
         def description
           "change #{@change_details.message} #{@relativity.to_s.gsub("_", " ")} #{description_of @expected_delta}"
         end
+
+        # @private
+        def supports_block_expectations?
+          true
+        end
+
+      private
+
+        def failure_reason
+          return "was not given a block" unless Proc === @event_proc
+          "was changed by #{description_of @change_details.actual_delta}"
+        end
       end
 
-      # Base class for specifying a change from and/or to specific values.
       # @api private
+      # Base class for specifying a change from and/or to specific values.
       class SpecificValuesChange
         include Composable
+        # @private
         MATCH_ANYTHING = ::Object.ancestors.last
 
         def initialize(change_details, from, to)
@@ -114,21 +163,32 @@ module RSpec
           @expected_after  = to
         end
 
+        # @private
         def matches?(event_proc)
+          @event_proc = event_proc
+          return false unless Proc === event_proc
           @change_details.perform_change(event_proc)
           @change_details.changed? && matches_before? && matches_after?
         end
 
+        # @private
         def description
           "change #{@change_details.message} #{change_description}"
         end
 
+        # @private
         def failure_message
-          return before_value_failure   unless matches_before?
-          return did_not_change_failure unless @change_details.changed?
+          return not_given_a_block_failure unless Proc === @event_proc
+          return before_value_failure      unless matches_before?
+          return did_not_change_failure    unless @change_details.changed?
           after_value_failure
         end
 
+        # @private
+        def supports_block_expectations?
+          true
+        end
+
       private
 
         def matches_before?
@@ -154,33 +214,44 @@ module RSpec
         def did_change_failure
           "expected #{@change_details.message} not to have changed, but did change from #{description_of @change_details.actual_before} to #{description_of @change_details.actual_after}"
         end
+
+        def not_given_a_block_failure
+          "expected #{@change_details.message} to have changed #{change_description}, but was not given a block"
+        end
       end
 
+      # @api private
       # Used to specify a change from a specific value
       # (and, optionally, to a specific value).
-      # @api private
       class ChangeFromValue < SpecificValuesChange
         def initialize(change_details, expected_before)
           @description_suffix = nil
           super(change_details, expected_before, MATCH_ANYTHING)
         end
 
+        # @api public
+        # Specifies the new value you expect.
         def to(value)
           @expected_after     = value
           @description_suffix = " to #{description_of value}"
           self
         end
 
+        # @private
         def does_not_match?(event_proc)
           if @description_suffix
             raise NotImplementedError, "`expect { }.not_to change { }.to()` is not supported"
           end
 
+          @event_proc = event_proc
+          return false unless Proc === event_proc
           @change_details.perform_change(event_proc)
           !@change_details.changed? && matches_before?
         end
 
+        # @private
         def failure_message_when_negated
+          return not_given_a_block_failure unless Proc === @event_proc
           return before_value_failure unless matches_before?
           did_change_failure
         end
@@ -192,21 +263,24 @@ module RSpec
         end
       end
 
+      # @api private
       # Used to specify a change to a specific value
       # (and, optionally, from a specific value).
-      # @api private
       class ChangeToValue < SpecificValuesChange
         def initialize(change_details, expected_after)
           @description_suffix = nil
           super(change_details, MATCH_ANYTHING, expected_after)
         end
 
+        # @api public
+        # Specifies the original value.
         def from(value)
           @expected_before    = value
           @description_suffix = " from #{description_of value}"
           self
         end
 
+        # @private
         def does_not_match?(event_proc)
           raise NotImplementedError, "`expect { }.not_to change { }.to()` is not supported"
         end
@@ -218,8 +292,8 @@ module RSpec
         end
       end
 
+      # @private
       # Encapsulates the details of the before/after values.
-      # @api private
       class ChangeDetails
         attr_reader :message, :actual_before, :actual_after
 
@@ -246,6 +320,8 @@ module RSpec
 
         def evaluate_value_proc
           case val = @value_proc.call
+          when IO # enumerable, but we don't want to dup it.
+            val
           when Enumerable, String
             val.dup
           else

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

@@ -1,9 +1,10 @@
 module RSpec
   module Matchers
     module BuiltIn
-      # Base class for `and` and `or` compound matchers.
       # @api private
+      # Base class for `and` and `or` compound matchers.
       class Compound < BaseMatcher
+        # @private
         attr_reader :matcher_1, :matcher_2
 
         def initialize(matcher_1, matcher_2)
@@ -11,17 +12,26 @@ module RSpec
           @matcher_2 = matcher_2
         end
 
+        # @private
         def does_not_match?(actual)
           raise NotImplementedError,
             "`expect(...).not_to matcher.#{conjunction} matcher` is not supported"
         end
 
+        # @api private
+        # @return [String]
         def description
           singleline_message(matcher_1.description, matcher_2.description)
         end
 
       private
 
+        def initialize_copy(other)
+          @matcher_1 = @matcher_1.clone
+          @matcher_2 = @matcher_2.clone
+          super
+        end
+
         def indent_multiline_message(message)
           message.lines.map do |line|
             line =~ /\S/ ? '   ' + line : line
@@ -55,9 +65,12 @@ module RSpec
           [message_1, conjunction, message_2].join(' ')
         end
 
-        # Matcher used to represent a compound `and` expectation.
         # @api public
+        # Matcher used to represent a compound `and` expectation.
         class And < self
+
+          # @api private
+          # @return [String]
           def failure_message
             if @matcher_1_matches
               matcher_2.failure_message
@@ -82,9 +95,12 @@ module RSpec
           end
         end
 
-        # Matcher used to represent a compound `or` expectation.
         # @api public
+        # Matcher used to represent a compound `or` expectation.
         class Or < self
+
+          # @api private
+          # @return [String]
           def failure_message
             compound_failure_message
           end