rspec-expectations 2.13.0 → 2.99.0

data/features/test_frameworks/test_unit.feature

@@ -1,11 +1,12 @@
 Feature: Test::Unit integration
 
-  RSpec-expectations is a stand-alone gem that can be used without
-  the rest of RSpec.  It can easily be used with another test
-  framework such as Test::Unit if you like RSpec's should/should_not
-  syntax but prefer the test organization of another framework.
+  RSpec-expectations is a stand-alone gem that can be used without the rest of
+  RSpec. If you like the way Test::Unit (or MiniTest) organizes tests, but
+  prefer RSpec's approach to expressing expectations, you can have both.
 
-  Scenario: Basic Test::Unit usage
+  The one downside is that failures are reported as errors with MiniTest.
+
+  Scenario: use rspec/expectations with Test::Unit
     Given a file named "rspec_expectations_test.rb" with:
       """ruby
       require 'test/unit'
@@ -17,30 +18,67 @@ Feature: Test::Unit integration
         end
 
         def be_an_int
-          RSpec.deprecate(:be_an_int, :be_an_integer)
+          # This is actually an internal rspec-expectations API, but is used
+          # here to demonstrate that deprecation warnings from within
+          # rspec-expectations work correcty without depending on rspec-core
+          RSpec.deprecate(:be_an_int, :replacement => :be_an_integer)
           be_an_integer
         end
 
         def test_passing_expectation
-          x = 1 + 3
-          x.should == 4
+          expect(1 + 3).to eq 4
         end
 
         def test_failing_expectation
-          array = [1, 2]
-          array.should be_empty
-        end
-
-        def test_expect_matcher
-          expect { @a = 5 }.to change { @a }.from(nil).to(5)
+          expect([1,2]).to be_empty
         end
 
-        def test_custom_matcher_and_deprecation_warning
-          1.should be_an_int
+        def test_custom_matcher_with_deprecation_warning
+          expect(1).to be_an_int
         end
       end
       """
      When I run `ruby rspec_expectations_test.rb`
-     Then the output should contain "4 tests, 0 assertions, 1 failures, 0 errors" or "4 tests, 0 assertions, 0 failures, 1 errors"
+     Then the output should contain "3 tests, 0 assertions, 0 failures, 1 errors" or "3 tests, 0 assertions, 1 failures, 0 errors"
       And the output should contain "expected empty? to return true, got false"
       And the output should contain "be_an_int is deprecated"
+      And the output should contain a deprecation warning about rspec-expecations' built-in integration
+
+  Scenario: use rspec/expectations with Test::Unit
+    Given a file named "rspec_expectations_with_manual_integration_test.rb" with:
+      """
+      require 'test/unit'
+      require "rspec/expectations"
+
+      class RSpecExpectationsTest < Test::Unit::TestCase
+        include ::RSpec::Matchers
+
+        RSpec::Matchers.define :be_an_integer do
+          match { |actual| Integer === actual }
+        end
+
+        def be_an_int
+          # This is actually an internal rspec-expectations API, but is used
+          # here to demonstrate that deprecation warnings from within
+          # rspec-expectations work correcty without depending on rspec-core
+          RSpec.deprecate(:be_an_int, :replacement => :be_an_integer)
+          be_an_integer
+        end
+
+        def test_passing_expectation
+          expect(1 + 3).to eq 4
+        end
+
+        def test_failing_expectation
+          expect([1,2]).to be_empty
+        end
+
+        def test_custom_matcher_with_deprecation_warning
+          expect(1).to be_an_int
+        end
+      end
+      """
+     When I run `ruby rspec_expectations_with_manual_integration_test.rb`
+     Then the output should contain "3 tests, 0 assertions, 0 failures, 1 errors" or "3 tests, 0 assertions, 1 failures, 0 errors"
+      And the output should not contain a deprecation warning about rspec-expecations' built-in integration
+

data/lib/rspec/expectations/caller_filter.rb

@@ -0,0 +1,60 @@
+module RSpec
+  # Consistent implementation for "cleaning" the caller method to strip out
+  # non-rspec lines. This enables errors to be reported at the call site in
+  # the code using the library, which is far more useful than the particular
+  # internal method that raised an error.
+
+  unless defined?(CallerFilter)
+
+    class CallerFilter
+
+      RSPEC_LIBS = %w[
+        core
+        mocks
+        expectations
+        matchers
+        rails
+      ]
+
+      ADDITIONAL_TOP_LEVEL_FILES = %w[ autorun ]
+
+      LIB_REGEX = %r{/lib/rspec/(#{(RSPEC_LIBS + ADDITIONAL_TOP_LEVEL_FILES).join('|')})(\.rb|/)}
+
+      if RUBY_VERSION >= '2.0.0'
+        def self.first_non_rspec_line
+          # `caller` is an expensive method that scales linearly with the size of
+          # the stack. The performance hit for fetching it in chunks is small,
+          # and since the target line is probably near the top of the stack, the
+          # overall improvement of a chunked search like this is significant.
+          #
+          # See benchmarks/caller.rb for measurements.
+
+          # Initial value here is mostly arbitrary, but is chosen to give good
+          # performance on the common case of creating a double.
+          increment = 5
+          i         = 1
+          line      = nil
+
+          while !line
+            stack = caller(i, increment)
+            return nil unless stack
+
+            line = stack.find { |l| l !~ LIB_REGEX }
+
+            i         += increment
+            increment *= 2 # The choice of two here is arbitrary.
+          end
+
+          line
+        end
+      else
+        # Earlier rubies do not support the two argument form of `caller`. This
+        # fallback is logically the same, but slower.
+        def self.first_non_rspec_line
+          caller.find { |line| line !~ LIB_REGEX }
+        end
+      end
+    end
+
+  end
+end

data/lib/rspec/{matchers → expectations}/configuration.rb

@@ -1,7 +1,7 @@
 require 'rspec/expectations/syntax'
 
 module RSpec
-  module Matchers
+  module Expectations
     # Provides configuration options for rspec-expectations.
     class Configuration
       # Configures the supported syntax.
@@ -94,11 +94,13 @@ module RSpec
         end
       end
     end
+  end
 
+  module Matchers
     # The configuration object
-    # @return [RSpec::Matchers::Configuration] the configuration object
+    # @return [RSpec::Expectations::Configuration] the configuration object
     def self.configuration
-      @configuration ||= Configuration.new
+      @configuration ||= Expectations::Configuration.new
     end
 
     # set default syntax

data/lib/rspec/expectations/deprecation.rb

@@ -1,38 +1,27 @@
-module RSpec
-  unless respond_to?(:deprecate)
-    class << self
-      # Used internally by RSpec to display standard deprecation warnings.
-      # This is also defined in rspec-core, but we can't assume it's loaded
-      # since rspec-expectations should be usable w/o rspec-core.
-      def deprecate(method, alternate_method=nil, version=nil)
-        version_string = version ? "rspec-#{version}" : "a future version of RSpec"
-
-        message = <<-NOTICE
-
-*****************************************************************
-DEPRECATION WARNING: you are using deprecated behaviour that will
-be removed from #{version_string}.
-
-#{caller(0)[2]}
+require 'rspec/expectations/caller_filter' unless defined?(::RSpec::CallerFilter)
 
-* #{method} is deprecated.
-NOTICE
-      if alternate_method
-        message << <<-ADDITIONAL
-* please use #{alternate_method} instead.
-ADDITIONAL
-      end
-
-        message << "*****************************************************************"
-        warn_deprecation(message)
+module RSpec
+  module Expectations
+    module Deprecation
+      # @private
+      #
+      # Used internally to print deprecation warnings
+      def deprecate(deprecated, options={})
+        message = "DEPRECATION: #{deprecated} is deprecated."
+        message << " Use #{options[:replacement]} instead." if options[:replacement]
+        message << " Called from #{CallerFilter.first_non_rspec_line}."
+        warn message
       end
 
-      # Used internally by RSpec to display custom deprecation warnings.  This
-      # is also defined in rspec-core, but we can't assume it's loaded since
-      # rspec-expectations should be usable w/o rspec-core.
-      def warn_deprecation(message)
-        warn(message)
+      # @private
+      #
+      # Used internally to print deprecation warnings
+      def warn_deprecation(warning)
+        message = "\nDEPRECATION: #{warning}\n"
+        warn message
       end
     end
   end
+
+  extend(Expectations::Deprecation) unless respond_to?(:deprecate)
 end

data/lib/rspec/expectations/differ.rb

@@ -5,12 +5,14 @@ require 'pp'
 module RSpec
   module Expectations
     class Differ
+
       # This is snagged from diff/lcs/ldiff.rb (which is a commandline tool)
-      def diff_as_string(data_new, data_old)
-        data_old = data_old.split(/\n/).map! { |e| e.chomp }
-        data_new = data_new.split(/\n/).map! { |e| e.chomp }
+      def diff_as_string(input_data_new, input_data_old)
+        encoding = pick_encoding input_data_new, input_data_old
+        output = matching_encoding("", encoding)
+        data_old = input_data_old.split(matching_encoding("\n", encoding)).map! { |e| e.chomp }
+        data_new = input_data_new.split(matching_encoding("\n", encoding)).map! { |e| e.chomp }
         diffs = Diff::LCS.diff(data_old, data_new)
-        output = ""
         return output if diffs.empty?
         oldhunk = hunk = nil
         file_length_difference = 0
@@ -33,16 +35,24 @@ module RSpec
                 hunk.unshift(oldhunk)
               end
             else
-              output << oldhunk.diff(format)
+              output << matching_encoding(oldhunk.diff(format).to_s, encoding)
             end
           ensure
             oldhunk = hunk
-            output << "\n"
+            output << matching_encoding("\n", encoding)
           end
         end
         #Handle the last remaining hunk
-        output << oldhunk.diff(format) << "\n"
+        output << matching_encoding(oldhunk.diff(format).to_s, encoding)
+        output << matching_encoding("\n", encoding)
         color_diff output
+      rescue Encoding::CompatibilityError
+        if input_data_new.encoding != input_data_old.encoding
+          "Could not produce a diff because the encoding of the actual string (#{input_data_old.encoding}) "+
+          "differs from the encoding of the expected string (#{input_data_new.encoding})"
+        else
+          "Could not produce a diff because of the encoding of the string (#{input_data_old.encoding})"
+        end
       end
 
       def diff_as_object(actual, expected)
@@ -99,8 +109,16 @@ module RSpec
       def object_to_string(object)
         case object
         when Hash
-          object.keys.sort_by { |k| k.to_s }.map do |k|
-            %(#{PP.singleline_pp(k, "")} => #{PP.singleline_pp(object[k], "")})
+          object.keys.sort_by { |k| k.to_s }.map do |key|
+            pp_key   = PP.singleline_pp(key, "")
+            pp_value = PP.singleline_pp(object[key], "")
+
+            # on 1.9.3 PP seems to minimise to US-ASCII, ensure we're matching source encoding
+            #
+            # note, PP is used to ensure the ordering of the internal values of key/value e.g.
+            # <# a: b: c:> not <# c: a: b:>
+            encoding = pick_encoding pp_key, pp_value
+            matching_encoding("#{pp_key} => #{pp_value}", encoding)
           end.join(",\n")
         when String
           object =~ /\n/ ? object : object.inspect
@@ -108,6 +126,27 @@ module RSpec
           PP.pp(object,"")
         end
       end
+
+    private
+
+      if String.method_defined?(:encoding)
+        def pick_encoding(source_a, source_b)
+          Encoding.compatible?(source_a, source_b) || Encoding.default_external
+        end
+
+        def matching_encoding(string, encoding)
+          string.encode encoding
+        rescue Encoding::UndefinedConversionError
+          string.encode(encoding, :undef => :replace)
+        end
+      else
+        def pick_encoding(source_a, source_b)
+        end
+
+        def matching_encoding(string, encoding)
+          string
+        end
+      end
     end
 
   end

data/lib/rspec/expectations/expectation_target.rb

@@ -1,23 +1,48 @@
 module RSpec
   module Expectations
     # Wraps the target of an expectation.
+    #
     # @example
-    #   expect(something) # => ExpectationTarget wrapping something
+    #   expect(something)       # => ExpectationTarget wrapping something
+    #   expect { do_something } # => ExpectationTarget wrapping the block
     #
     #   # used with `to`
     #   expect(actual).to eq(3)
     #
-    #   # with `to_not`
-    #   expect(actual).to_not eq(3)
+    #   # with `not_to`
+    #   expect(actual).not_to eq(3)
+    #
+    # @note `ExpectationTarget` is not intended to be instantiated
+    #   directly by users. Use `expect` instead.
     class ExpectationTarget
       class << self
         attr_accessor :deprecated_should_enabled
         alias deprecated_should_enabled? deprecated_should_enabled
       end
 
+      # @private
+      # Used as a sentinel value to be able to tell when the user
+      # did not pass an argument. We can't use `nil` for that because
+      # `nil` is a valid value to pass.
+      UndefinedValue = Module.new
+
       # @api private
-      def initialize(target)
-        @target = target
+      def initialize(value)
+        @target = value
+      end
+
+      # @private
+      def self.for(value, block)
+        if UndefinedValue.equal?(value)
+          unless block
+            raise ArgumentError, "You must pass either an argument or a block to `expect`."
+          end
+          BlockExpectationTarget.new(block)
+        elsif block
+          raise ArgumentError, "You cannot pass both an argument and a block to `expect`."
+        else
+          new(value)
+        end
       end
 
       # Runs the given expectation, passing if `matcher` returns true.
@@ -30,35 +55,34 @@ module RSpec
       # @return [Boolean] true if the expectation succeeds (else raises)
       # @see RSpec::Matchers
       def to(matcher=nil, message=nil, &block)
-        prevent_operator_matchers(:to, matcher)
+        prevent_operator_matchers(:to) unless matcher
         RSpec::Expectations::PositiveExpectationHandler.handle_matcher(@target, matcher, message, &block)
       end
 
       # Runs the given expectation, passing if `matcher` returns false.
       # @example
-      #   expect(value).to_not eq(5)
       #   expect(value).not_to eq(5)
       # @param [Matcher]
       #   matcher
       # @param [String] message optional message to display when the expectation fails
       # @return [Boolean] false if the negative expectation succeeds (else raises)
       # @see RSpec::Matchers
-      def to_not(matcher=nil, message=nil, &block)
-        prevent_operator_matchers(:to_not, matcher)
+      def not_to(matcher=nil, message=nil, &block)
+        prevent_operator_matchers(:not_to) unless matcher
         RSpec::Expectations::NegativeExpectationHandler.handle_matcher(@target, matcher, message, &block)
       end
-      alias not_to to_not
+      alias to_not not_to
 
       def self.enable_deprecated_should
         return if deprecated_should_enabled?
 
         def should(*args)
-          RSpec.deprecate "`expect { }.should`", "`expect { }.to`", 3
+          RSpec.deprecate "`expect { }.should`", :replacement => "`expect { }.to`"
           @target.should(*args)
         end
 
         def should_not(*args)
-          RSpec.deprecate "`expect { }.should_not`", "`expect { }.to_not`", 3
+          RSpec.deprecate "`expect { }.should_not`", :replacement => "`expect { }.not_to`"
           @target.should_not(*args)
         end
 
@@ -76,13 +100,55 @@ module RSpec
 
     private
 
-      def prevent_operator_matchers(verb, matcher)
-        return if matcher
-
+      def prevent_operator_matchers(verb)
         raise ArgumentError, "The expect syntax does not support operator matchers, " +
                              "so you must pass a matcher to `##{verb}`."
       end
     end
+
+    # @private
+    # Validates the provided matcher to ensure it supports block
+    # expectations, in order to avoid user confusion when they
+    # use a block thinking the expectation will be on the return
+    # value of the block rather than the block itself.
+    class BlockExpectationTarget < ExpectationTarget
+      def to(matcher, message=nil, &block)
+        enforce_block_expectation(matcher)
+        super
+      end
+
+      def not_to(matcher, message=nil, &block)
+        enforce_block_expectation(matcher)
+        super
+      end
+      alias to_not not_to
+
+    private
+
+      def enforce_block_expectation(matcher)
+        return if supports_block_expectations?(matcher)
+
+        RSpec.deprecate("Using a matcher in a block expectation expression " +
+                        "(e.g. `expect { }.to matcher`) that does not implement " +
+                        "`supports_block_expectations?`",
+                        :replacement => "a value expectation expression " +
+                        "(e.g. `expect(value).to matcher`) or implement " +
+                        "`supports_block_expectations?` on the provided matcher " +
+                        "(#{description_of matcher})")
+      end
+
+      def supports_block_expectations?(matcher)
+        matcher.supports_block_expectations?
+      rescue NoMethodError
+        false
+      end
+
+      def description_of(matcher)
+        matcher.description
+      rescue NoMethodError
+        matcher.inspect
+      end
+    end
   end
 end
 

data/lib/rspec/expectations/extensions/object.rb

@@ -6,17 +6,7 @@ module RSpec
       def const_missing(name)
         case name
         when :Rspec, :Spec
-          RSpec.warn_deprecation <<-WARNING
-*****************************************************************
-DEPRECATION WARNING: you are using a deprecated constant that will
-be removed from a future version of RSpec.
-
-#{caller(0)[2]}
-
-* #{name} is deprecated.
-* RSpec is the new top-level module in RSpec-2
-***************************************************************
-WARNING
+          RSpec.deprecate(name.to_s, :replacement => "RSpec")
           RSpec
         else
           begin
@@ -31,7 +21,7 @@ WARNING
 
     # @deprecated (no replacement)
     def differ=(ignore)
-      RSpec.deprecate("RSpec::Expectations.differ=(differ)", "nothing at all (diffing is now automatic and no longer configurable)")
+      RSpec.deprecate("RSpec::Expectations.differ=(differ)")
     end
   end
 end

data/lib/rspec/expectations/fail_with.rb

@@ -52,7 +52,17 @@ module RSpec
 
       def coerce_to_string(string_or_array)
         return string_or_array unless Array === string_or_array
-        string_or_array.join(',')
+        diffably_stringify(string_or_array).join("\n")
+      end
+
+      def diffably_stringify(array)
+        array.map do |entry|
+          if Array === entry
+            entry.inspect
+          else
+            entry.to_s.gsub("\n", "\\n")
+          end
+        end
       end
 
       if String.method_defined?(:encoding)

data/lib/rspec/expectations/handler.rb

@@ -2,13 +2,14 @@ module RSpec
   module Expectations
 
     class ExpectationHandler
-      def self.message_must_be_string(msg)
-        "WARNING: ignoring the provided expectation message argument " +
-        "(#{msg.inspect}) since it is not a string."
-      end
-
       def self.check_message(msg)
-        ::Kernel.warn message_must_be_string(msg) unless msg.nil? || msg.is_a?(String)
+        unless msg.nil? || msg.respond_to?(:to_str) || msg.respond_to?(:call)
+          ::Kernel.warn [
+            "WARNING: ignoring the provided expectation message argument (",
+            msg.inspect,
+            ") since it is not a string or a proc."
+          ].join
+        end
       end
     end
 
@@ -23,12 +24,18 @@ module RSpec
         match = matcher.matches?(actual, &block)
         return match if match
 
+        message = message.call if message.respond_to?(:call)
+
         message ||= matcher.respond_to?(:failure_message_for_should) ?
                     matcher.failure_message_for_should :
                     matcher.failure_message
 
         if matcher.respond_to?(:diffable?) && matcher.diffable?
-          ::RSpec::Expectations.fail_with message, matcher.expected, matcher.actual
+          if RSpec::Matchers::DSL::Matcher === matcher
+            ::RSpec::Expectations.fail_with message, matcher.expected_as_array, matcher.actual
+          else
+            ::RSpec::Expectations.fail_with message, matcher.expected, matcher.actual
+          end
         else
           ::RSpec::Expectations.fail_with message
         end
@@ -47,6 +54,8 @@ module RSpec
                 matcher.matches?(actual, &block)
         return match unless match
 
+        message = message.call if message.respond_to?(:call)
+
         message ||= matcher.respond_to?(:failure_message_for_should_not) ?
                     matcher.failure_message_for_should_not :
                     matcher.negative_failure_message

data/lib/rspec/expectations/syntax.rb

@@ -32,10 +32,10 @@ module RSpec
       # `ExpectationTarget`.
       # @example
       #   expect(actual).to eq(expected)
-      #   expect(actual).to_not eq(expected)
+      #   expect(actual).not_to eq(expected)
       # @return [ExpectationTarget]
       # @see ExpectationTarget#to
-      # @see ExpectationTarget#to_not
+      # @see ExpectationTarget#not_to
 
       # @api private
       # Determines where we add `should` and `should_not`.
@@ -79,11 +79,9 @@ module RSpec
       def enable_expect(syntax_host = ::RSpec::Matchers)
         return if expect_enabled?(syntax_host)
 
-        syntax_host.module_eval do
-          def expect(*target, &target_block)
-            target << target_block if block_given?
-            raise ArgumentError.new("You must pass an argument or a block to #expect but not both.") unless target.size == 1
-            ::RSpec::Expectations::ExpectationTarget.new(target.first)
+        syntax_host.module_exec do
+          def expect(value=::RSpec::Expectations::ExpectationTarget::UndefinedValue, &block)
+            ::RSpec::Expectations::ExpectationTarget.for(value, block)
           end
         end
 

data/lib/rspec/expectations/version.rb

@@ -2,7 +2,7 @@ module RSpec
   module Expectations
     # @private
     module Version
-      STRING = '2.13.0'
+      STRING = '2.99.0'
     end
   end
 end

data/lib/rspec/expectations.rb

@@ -1,7 +1,7 @@
 require 'rspec/expectations/extensions'
 require 'rspec/matchers'
 require 'rspec/expectations/expectation_target'
-require 'rspec/matchers/configuration'
+require 'rspec/expectations/configuration'
 require 'rspec/expectations/fail_with'
 require 'rspec/expectations/errors'
 require 'rspec/expectations/deprecation'
@@ -37,11 +37,37 @@ module RSpec
   # `eq.failure_message_for_should_not`.
   #
   # rspec-expectations ships with a standard set of useful matchers, and writing
-  # your own matchers is quite simple. 
+  # your own matchers is quite simple.
   #
   # See [RSpec::Matchers](../RSpec/Matchers) for more information about the
   # built-in matchers that ship with rspec-expectations, and how to write your
   # own custom matchers.
   module Expectations
+
+    # @api private
+    KERNEL_METHOD_METHOD = ::Kernel.instance_method(:method)
+
+    # @api private
+    #
+    # Used internally to get a method handle for a particular object
+    # and method name.
+    #
+    # Includes handling for a few special cases:
+    #
+    #   - Objects that redefine #method (e.g. an HTTPRequest struct)
+    #   - BasicObject subclasses that mixin a Kernel dup (e.g. SimpleDelegator)
+    if RUBY_VERSION.to_i >= 2
+      def self.method_handle_for(object, method_name)
+        KERNEL_METHOD_METHOD.bind(object).call(method_name)
+      end
+    else
+      def self.method_handle_for(object, method_name)
+        if ::Kernel === object
+          KERNEL_METHOD_METHOD.bind(object).call(method_name)
+        else
+          object.method(method_name)
+        end
+      end
+    end
   end
 end