rspec-expectations 3.0.0.beta1 → 3.0.0.beta2

data/lib/rspec/matchers/dsl.rb

@@ -16,6 +16,336 @@ module RSpec
       if RSpec.respond_to?(:configure)
         RSpec.configure {|c| c.extend self}
       end
+
+      # Contains the methods that are available from within the
+      # `RSpec::Matchers.define` DSL for creating custom matchers.
+      module Macros
+        # Stores the block that is used to determine whether this matcher passes
+        # or fails. The block should return a boolean value. When the matcher is
+        # passed to `expect(...).to` and the block returns `true`, then the expectation
+        # passes. Similarly, when the matcher is passed to `expect(...).not_to` and the
+        # block returns `false`, then the expectation passes.
+        #
+        # @example
+        #
+        #     RSpec::Matchers.define :be_even do
+        #       match do |actual|
+        #         actual.even?
+        #       end
+        #     end
+        #
+        #     expect(4).to be_even     # passes
+        #     expect(3).not_to be_even # passes
+        #     expect(3).to be_even     # fails
+        #     expect(4).not_to be_even # fails
+        #
+        # @yield [Object] actual the actual value (i.e. the value wrapped by `expect`)
+        def match(&match_block)
+          define_user_override(:matches?, match_block) do |actual|
+            begin
+              @actual = actual
+              super(*actual_arg_for(match_block))
+            rescue RSpec::Expectations::ExpectationNotMetError
+              false
+            end
+          end
+        end
+
+        # Use this to define the block for a negative expectation (`expect(...).not_to`)
+        # when the positive and negative forms require different handling. This
+        # is rarely necessary, but can be helpful, for example, when specifying
+        # asynchronous processes that require different timeouts.
+        #
+        # @yield [Object] actual the actual value (i.e. the value wrapped by `expect`)
+        def match_when_negated(&match_block)
+          define_user_override(:does_not_match?, match_block) do |actual|
+            @actual = actual
+            super(*actual_arg_for(match_block))
+          end
+        end
+
+        # Use this instead of `match` when the block will raise an exception
+        # rather than returning false to indicate a failure.
+        #
+        # @example
+        #
+        #     RSpec::Matchers.define :accept_as_valid do |candidate_address|
+        #       match_unless_raises ValidationException do |validator|
+        #         validator.validate(candidate_address)
+        #       end
+        #     end
+        #
+        #     expect(email_validator).to accept_as_valid("person@company.com")
+        #
+        # @yield [Object] actual the actual object (i.e. the value wrapped by `expect`)
+        def match_unless_raises(expected_exception=Exception, &match_block)
+          define_user_override(:matches?, match_block) do |actual|
+            @actual = actual
+            begin
+              super(*actual_arg_for(match_block))
+            rescue expected_exception => @rescued_exception
+              false
+            else
+              true
+            end
+          end
+        end
+
+        # Customizes the failure messsage to use when this matcher is
+        # asked to positively match. Only use this when the message
+        # generated by default doesn't suit your needs.
+        #
+        # @example
+        #
+        #     RSpec::Matchers.define :have_strength do |expected|
+        #       match { your_match_logic }
+        #
+        #       failure_message do |actual|
+        #         "Expected strength of #{expected}, but had #{actual.strength}"
+        #       end
+        #     end
+        #
+        # @yield [Object] actual the actual object (i.e. the value wrapped by `expect`)
+        def failure_message(&definition)
+          define_user_override(__method__, definition)
+        end
+
+        # Customize the failure messsage to use when this matcher is asked
+        # to negatively match. Only use this when the message generated by
+        # default doesn't suit your needs.
+        #
+        # @example
+        #
+        #     RSpec::Matchers.define :have_strength do |expected|
+        #       match { your_match_logic }
+        #
+        #       failure_message_when_negated do |actual|
+        #         "Expected not to have strength of #{expected}, but did"
+        #       end
+        #     end
+        #
+        # @yield [Object] actual the actual object (i.e. the value wrapped by `expect`)
+        def failure_message_when_negated(&definition)
+          define_user_override(__method__, definition)
+        end
+
+        # Customize the description to use for one-liners.  Only use this when
+        # the description generated by default doesn't suit your needs.
+        #
+        # @example
+        #
+        #     RSpec::Matchers.define :qualify_for do |expected|
+        #       match { your_match_logic }
+        #
+        #       description do
+        #         "qualify for #{expected}"
+        #       end
+        #     end
+        #
+        # @yield [Object] actual the actual object (i.e. the value wrapped by `expect`)
+        def description(&definition)
+          define_user_override(__method__, definition)
+        end
+
+        # Tells the matcher to diff the actual and expected values in the failure
+        # message.
+        def diffable
+          define_method(:diffable?) { true }
+        end
+
+        # Convenience for defining methods on this matcher to create a fluent
+        # interface. The trick about fluent interfaces is that each method must
+        # return self in order to chain methods together. `chain` handles that
+        # for you.
+        #
+        # @example
+        #
+        #     RSpec::Matchers.define :have_errors_on do |key|
+        #       chain :with do |message|
+        #         @message = message
+        #       end
+        #
+        #       match do |actual|
+        #         actual.errors[key] == @message
+        #       end
+        #     end
+        #
+        #     expect(minor).to have_errors_on(:age).with("Not old enough to participate")
+        def chain(name, &definition)
+          define_user_override(name, definition) do |*args, &block|
+            super(*args, &block)
+            self
+          end
+        end
+
+      private
+
+        # Does the following:
+        #
+        # - Defines the named method usign a user-provided block
+        #   in @user_method_defs, which is included as an ancestor
+        #   in the singleton class in which we eval the `define` block.
+        # - Defines an overriden definition for the same method
+        #   usign the provided `our_def` block.
+        # - Provides a default `our_def` block for the common case
+        #   of needing to call the user's definition with `@actual`
+        #   as an arg, but only if their block's arity can handle it.
+        #
+        # This compiles the user block into an actual method, allowing
+        # them to use normal method constructs like `return`
+        # (e.g. for a early guard statement), while allowing us to define
+        # an override that can provide the wrapped handling
+        # (e.g. assigning `@actual`, rescueing errors, etc) and
+        # can `super` to the user's definition.
+        def define_user_override(method_name, user_def, &our_def)
+          @user_method_defs.__send__(:define_method, method_name, &user_def)
+          our_def ||= lambda { super(*actual_arg_for(user_def)) }
+          define_method(method_name, &our_def)
+        end
+
+        # Defines deprecated macro methods from RSpec 2 for backwards compatibility.
+        # @deprecated Use the methods from {Macros} instead.
+        module Deprecated
+          # @deprecated Use {Macros#match} instead.
+          def match_for_should(&definition)
+            RSpec.deprecate("`match_for_should`", :replacement => "`match`")
+            match(&definition)
+          end
+
+          # @deprecated Use {Macros#match_when_negated} instead.
+          def match_for_should_not(&definition)
+            RSpec.deprecate("`match_for_should_not`", :replacement => "`match_when_negated`")
+            match_when_negated(&definition)
+          end
+
+          # @deprecated Use {Macros#failure_message} instead.
+          def failure_message_for_should(&definition)
+            RSpec.deprecate("`failure_message_for_should`", :replacement => "`failure_message`")
+            failure_message(&definition)
+          end
+
+          # @deprecated Use {Macros#failure_message_when_negated} instead.
+          def failure_message_for_should_not(&definition)
+            RSpec.deprecate("`failure_message_for_should_not`", :replacement => "`failure_message_when_negated`")
+            failure_message_when_negated(&definition)
+          end
+        end
+      end
+
+      # Defines default implementations of the matcher
+      # protocol methods for custom matchers. You can
+      # override any of these using the {RSpec::Matchers::DSL::Macros Macros} methods
+      # from within an `RSpec::Matchers.define` block.
+      module DefaultImplementations
+        # @api private
+        # Used internally by objects returns by `should` and `should_not`.
+        def diffable?
+          false
+        end
+
+        # The default description.
+        def description
+          "#{name_to_sentence}#{expected_to_sentence}"
+        end
+
+        # The default failure message for positive expectations.
+        def failure_message
+          "expected #{actual.inspect} to #{name_to_sentence}#{expected_to_sentence}"
+        end
+
+        # The default failure message for negative expectations.
+        def failure_message_when_negated
+          "expected #{actual.inspect} not to #{name_to_sentence}#{expected_to_sentence}"
+        end
+      end
+
+      # The class used for custom matchers. The block passed to
+      # `RSpec::Matchers.define` will be evaluated in the context
+      # of the singleton class of an instance, and will have the
+      # {RSpec::Matchers::DSL::Macros Macros} methods available.
+      class Matcher
+        # Provides default implementations for the matcher protocol methods.
+        include DefaultImplementations
+
+        # Allows expectation expressions to be used in the match block.
+        include RSpec::Matchers
+
+        # Converts matcher name and expected args to an English expresion.
+        include RSpec::Matchers::Pretty
+
+        # Supports the matcher composability features of RSpec 3+.
+        include Composable
+
+        # Makes the macro methods available to an `RSpec::Matchers.define` block.
+        extend Macros
+        extend Macros::Deprecated
+
+        attr_reader   :expected_as_array, :actual, :rescued_exception
+        attr_accessor :matcher_execution_context
+
+        # @api private
+        def initialize(name, declarations, *expected)
+          @name     = name
+          @actual   = nil
+          @expected_as_array = expected
+
+          class << self
+            # See `Macros#define_user_override` above, for an explanation.
+            include(@user_method_defs = Module.new)
+            self
+          end.class_exec(*expected, &declarations)
+        end
+
+        def expected
+          if expected_as_array.size == 1
+            expected_as_array[0]
+          else
+            expected_as_array
+          end
+        end
+
+        # Adds the name (rather than a cryptic hex number)
+        # so we can identify an instance of
+        # the matcher in error messages (e.g. for `NoMethodError`)
+        def inspect
+          "#<#{self.class.name} #{name}>"
+        end
+
+        if RUBY_VERSION.to_f >= 1.9
+          # Indicates that this matcher responds to messages
+          # from the `matcher_execution_context` as well.
+          # Also, supports getting a method object for such methods.
+          def respond_to_missing?(method, include_private=false)
+            super || matcher_execution_context.respond_to?(method, include_private)
+          end
+        else # for 1.8.7
+          # Indicates that this matcher responds to messages
+          # from the `matcher_execution_context` as well.
+          def respond_to?(method, include_private=false)
+            super || matcher_execution_context.respond_to?(method, include_private)
+          end
+        end
+
+      private
+
+        def actual_arg_for(block)
+          block.arity.zero? ? [] : [@actual]
+        end
+
+        # Takes care of forwarding unhandled messages to the
+        # `matcher_execution_context` (typically the current
+        # running `RSpec::Core::Example`). This is needed by
+        # rspec-rails so that it can define matchers that wrap
+        # Rails' test helper methods, but it's also a useful
+        # feature in its own right.
+        def method_missing(method, *args, &block)
+          if matcher_execution_context.respond_to?(method)
+            matcher_execution_context.__send__ method, *args, &block
+          else
+            super(method, *args, &block)
+          end
+        end
+      end
     end
   end
 end

data/lib/rspec/matchers/generated_descriptions.rb

@@ -1,17 +1,17 @@
 module RSpec
   module Matchers
     class << self
-      attr_accessor :last_matcher, :last_should
+      attr_accessor :last_matcher, :last_expectation_handler
     end
 
     def self.clear_generated_description
       self.last_matcher = nil
-      self.last_should = nil
+      self.last_expectation_handler = nil
     end
 
     def self.generated_description
-      return nil if last_should.nil?
-      "#{last_should.to_s.gsub('_',' ')} #{last_description}"
+      return nil if last_expectation_handler.nil?
+      "#{last_expectation_handler.verb} #{last_description}"
     end
 
   private
@@ -20,11 +20,11 @@ module RSpec
       last_matcher.respond_to?(:description) ? last_matcher.description : <<-MESSAGE
 When you call a matcher in an example without a String, like this:
 
-specify { object.should matcher }
+specify { expect(object).to matcher }
 
 or this:
 
-it { should matcher }
+it { is_expected.to matcher }
 
 RSpec expects the matcher to have a #description method. You should either
 add a String to the example this matcher is being used in, or give it a

data/lib/rspec/matchers/matcher_delegator.rb

@@ -0,0 +1,33 @@
+module RSpec
+  module Matchers
+    # Provides the necessary plumbing to wrap a matcher with a decorator.
+    #
+    # @api private
+    class MatcherDelegator
+      attr_reader :base_matcher
+
+      def initialize(base_matcher)
+        @base_matcher = base_matcher
+      end
+
+      def method_missing(*args, &block)
+        base_matcher.__send__(*args, &block)
+      end
+
+      if ::RUBY_VERSION.to_f > 1.8
+        def respond_to_missing?(name, include_all=false)
+          super || base_matcher.respond_to?(name, include_all)
+        end
+      else
+        def respond_to?(name, include_all=false)
+          super || base_matcher.respond_to?(name, include_all)
+        end
+      end
+
+      # So `===` is delegated via `method_missing`.
+      undef ===
+      undef ==
+    end
+  end
+end
+

data/lib/rspec/matchers/pretty.rb

@@ -4,9 +4,10 @@ module RSpec
       def split_words(sym)
         sym.to_s.gsub(/_/,' ')
       end
+      module_function :split_words
 
       def to_sentence(words)
-        return "" unless words
+        return " #{words.inspect}" unless words
         words = Array(words).map { |w| to_word(w) }
         case words.length
           when 0
@@ -43,7 +44,7 @@ module RSpec
       end
 
       def expected_to_sentence
-        to_sentence(@expected) if defined?(@expected)
+        to_sentence(expected) if defined?(expected)
       end
 
       def name
@@ -65,6 +66,16 @@ module RSpec
       def is_matcher_with_description?(object)
         RSpec::Matchers.is_a_matcher?(object) && object.respond_to?(:description)
       end
+
+      # `{ :a => 5, :b => 2 }.inspect` produces:
+      #    {:a=>5, :b=>2}
+      # ...but it looks much better as:
+      #    {:a => 5, :b => 2}
+      #
+      # This is idempotent and safe to run on a string multiple times.
+      def improve_hash_formatting(inspect_string)
+        inspect_string.gsub(/(\S)=>(\S)/, '\1 => \2')
+      end
     end
   end
 end

data/spec/rspec/expectations/{differ_spec.rb → diff_presenter_spec.rb}

@@ -4,21 +4,19 @@ require 'ostruct'
 
 module RSpec
   module Expectations
-    describe Differ do
+    describe DiffPresenter do
+      let(:differ) { RSpec::Expectations::DiffPresenter.new }
       context "without --color" do
 
-      before { RSpec::Matchers.configuration.stub(:color? => false) }
-
-      let(:differ) { RSpec::Expectations::Differ.new }
-
-        # color disabled context
+      before { allow(RSpec::Matchers.configuration).to receive_messages(:color? => false) }
 
       describe '#diff_as_string' do
-        subject { differ.diff_as_string(@expected, @actual) }
+        subject { differ.diff_as_string(@actual, @expected) }
+
         it "outputs unified diff of two strings" do
-          @expected="foo\nbar\nzap\nthis\nis\nsoo\nvery\nvery\nequal\ninsert\na\nline\n"
-          @actual="foo\nzap\nbar\nthis\nis\nsoo\nvery\nvery\nequal\ninsert\na\nanother\nline\n"
-          expect(subject).to eql(<<-'EOD')
+          @expected = "foo\nzap\nbar\nthis\nis\nsoo\nvery\nvery\nequal\ninsert\na\nanother\nline\n"
+          @actual   = "foo\nbar\nzap\nthis\nis\nsoo\nvery\nvery\nequal\ninsert\na\nline\n"
+          expect(subject).to eq(<<-'EOD')
 
 
 @@ -1,6 +1,6 @@
@@ -38,10 +36,11 @@ module RSpec
 EOD
 
         end
-        if RUBY_VERSION.to_f > 1.9
-          it 'copes with encoded strings', :pending => (Diff::LCS::VERSION < '1.2.2') do
-            @expected="Tu avec carté {count} itém has".encode('UTF-16LE')
-            @actual="Tu avec carte {count} item has".encode('UTF-16LE')
+
+        if String.method_defined?(:encoding)
+          it 'copes with encoded strings' do
+            @expected = "Tu avec carte {count} item has".encode('UTF-16LE')
+            @actual   = "Tu avec carté {count} itém has".encode('UTF-16LE')
             expect(subject).to eql(<<-EOD.encode('UTF-16LE'))
 
 @@ -1,2 +1,2 @@
@@ -49,20 +48,27 @@ EOD
 +Tu avec carté {count} itém has
 EOD
           end
-          it 'copes with encoded strings', :pending => (Diff::LCS::VERSION >= '1.2.2') do
-            @expected="Tu avec carté {count} itém has".encode('UTF-16LE')
-            @actual="Tu avec carte {count} item has".encode('UTF-16LE')
-            expect(subject).to eql 'Could not produce a diff because of the encoding of the string (UTF-16LE)'
-          end
+
           it 'handles differently encoded strings that are compatible' do
-            @expected = "강인철".encode('UTF-8')
-            @actual   = "abc".encode('us-ascii')
+            @expected = "abc".encode('us-ascii')
+            @actual   = "강인철".encode('UTF-8')
             expect(subject).to eql "\n@@ -1,2 +1,2 @@\n-abc\n+강인철\n"
           end
-          it 'outputs a message when encountering differently encoded strings' do
-            @expected="Tu avec carté {count} itém has".encode('UTF-16LE')
-            @actual="Tu avec carte {count} item has"
-            expect(subject).to eql 'Could not produce a diff because the encoding of the actual string (UTF-8) differs from the encoding of the expected string (UTF-16LE)'
+
+          it 'uses the default external encoding when the two strings have incompatible encodings' do
+            @expected = "Tu avec carte {count} item has"
+            @actual   = "Tu avec carté {count} itém has".encode('UTF-16LE')
+            expect(subject).to eq("\n@@ -1,2 +1,2 @@\n-Tu avec carte {count} item has\n+Tu avec carté {count} itém has\n")
+            expect(subject.encoding).to eq(Encoding.default_external)
+          end
+
+          it 'handles any encoding error that occurs with a helpful error message' do
+            expect(Differ).to receive(:new).and_raise(Encoding::CompatibilityError)
+            @expected = "Tu avec carte {count} item has".encode('us-ascii')
+            @actual   = "Tu avec carté {count} itém has"
+            expect(subject).to match(/Could not produce a diff/)
+            expect(subject).to match(/actual string \(UTF-8\)/)
+            expect(subject).to match(/expected string \(US-ASCII\)/)
           end
         end
       end
@@ -135,7 +141,7 @@ EOD
 +:delta => "charlie",
  :foo => "bar",
  :metasyntactic => "variable",
- :width => "quite wide"
+ :width => "quite wide",
 EOD
 
           diff = differ.diff_as_object(expected,actual)
@@ -145,8 +151,8 @@ EOD
         it 'outputs unified diff message of two hashes with differing encoding' do
           expected_diff = %Q{
 @@ -1,2 +1,2 @@
--"a" => "a"
-#{ (RUBY_VERSION.to_f > 1.8) ?  %Q{+"ö" => "ö"} : '+"\303\266" => "\303\266"' }
+-"a" => "a",
+#{ (RUBY_VERSION.to_f > 1.8) ?  %Q{+"ö" => "ö"} : '+"\303\266" => "\303\266"' },
 }
 
           diff = differ.diff_as_object({'ö' => 'ö'}, {'a' => 'a'})
@@ -156,8 +162,8 @@ EOD
         it 'outputs unified diff message of two hashes with encoding different to key encoding' do
           expected_diff = %Q{
 @@ -1,2 +1,2 @@
--:a => "a"
-#{ (RUBY_VERSION.to_f > 1.8) ?  %Q{+\"한글\" => \"한글2\"} : '+"\355\225\234\352\270\200" => "\355\225\234\352\270\2002"' }
+-:a => "a",
+#{ (RUBY_VERSION.to_f > 1.8) ?  %Q{+\"한글\" => \"한글2\"} : '+"\355\225\234\352\270\200" => "\355\225\234\352\270\2002"' },
 }
 
           diff = differ.diff_as_object({ "한글" => "한글2"}, { :a => "a"})
@@ -167,8 +173,8 @@ EOD
         it "outputs unified diff message of two hashes with object keys" do
           expected_diff = %Q{
 @@ -1,2 +1,2 @@
--["a", "c"] => "b"
-+["d", "c"] => "b"
+-["a", "c"] => "b",
++["d", "c"] => "b",
 }
 
           diff = differ.diff_as_object({ ['d','c'] => 'b'}, { ['a','c'] => 'b' })
@@ -205,18 +211,32 @@ EOD
           diff = differ.diff_as_object(expected,actual)
           expect(diff).to eq expected_diff
         end
+
+        it "uses matcher descriptions in place of matchers in diffs" do
+          expected = [a_string_matching(/foo/), a_string_matching(/bar/)]
+          actual   = ["poo", "car"]
+
+          expected_diff = dedent(<<-EOS)
+            |
+            |@@ -1,2 +1,2 @@
+            |-["poo", "car"]
+            |+[(a string matching /foo/), (a string matching /bar/)]
+            |
+          EOS
+
+          diff = differ.diff_as_object(expected,actual)
+          expect(diff).to eq expected_diff
+        end
       end
     end
 
     context "with --color" do
-      before { RSpec::Matchers.configuration.stub(:color? => true) }
-
-      let(:differ) { RSpec::Expectations::Differ.new }
+      before { allow(RSpec::Matchers.configuration).to receive_messages(:color? => true) }
 
       it "outputs colored diffs" do
         expected = "foo bar baz"
         actual = "foo bang baz"
-        expected_diff = "\n\e[34m@@ -1,2 +1,2 @@\n\e[0m\e[31m-foo bang baz\n\e[0m\e[32m+foo bar baz\n\e[0m"
+        expected_diff = "\e[0m\n\e[0m\e[34m@@ -1,2 +1,2 @@\n\e[0m\e[31m-foo bang baz\n\e[0m\e[32m+foo bar baz\n\e[0m"
 
 
         diff = differ.diff_as_string(expected,actual)