rspec-expectations 2.11.3 → 3.11.0

data/lib/rspec/matchers/fail_matchers.rb

@@ -0,0 +1,42 @@
+require 'rspec/expectations'
+
+module RSpec
+  module Matchers
+    # Matchers for testing RSpec matchers. Include them with:
+    #
+    #     require 'rspec/matchers/fail_matchers'
+    #     RSpec.configure do |config|
+    #       config.include RSpec::Matchers::FailMatchers
+    #     end
+    #
+    module FailMatchers
+      # Matches if an expectation fails
+      #
+      # @example
+      #   expect { some_expectation }.to fail
+      def fail(&block)
+        raise_error(RSpec::Expectations::ExpectationNotMetError, &block)
+      end
+
+      # Matches if an expectation fails with the provided message
+      #
+      # @example
+      #   expect { some_expectation }.to fail_with("some failure message")
+      #   expect { some_expectation }.to fail_with(/some failure message/)
+      def fail_with(message)
+        raise_error(RSpec::Expectations::ExpectationNotMetError, message)
+      end
+
+      # Matches if an expectation fails including the provided message
+      #
+      # @example
+      #   expect { some_expectation }.to fail_including("portion of some failure message")
+      def fail_including(*snippets)
+        raise_error(
+          RSpec::Expectations::ExpectationNotMetError,
+          a_string_including(*snippets)
+        )
+      end
+    end
+  end
+end

data/lib/rspec/matchers/generated_descriptions.rb

@@ -1,30 +1,36 @@
 module RSpec
   module Matchers
     class << self
-      attr_accessor :last_matcher, :last_should
+      # @private
+      attr_accessor :last_matcher, :last_expectation_handler
     end
 
+    # @api private
+    # Used by rspec-core to clear the state used to generate
+    # descriptions after an example.
     def self.clear_generated_description
       self.last_matcher = nil
-      self.last_should = nil
+      self.last_expectation_handler = nil
     end
 
+    # @api private
+    # Generates an an example description based on the last expectation.
+    # Used by rspec-core's one-liner syntax.
     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
-    
+
+    # @private
     def self.last_description
       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
@@ -33,4 +39,3 @@ MESSAGE
     end
   end
 end
-      

data/lib/rspec/matchers/matcher_delegator.rb

@@ -0,0 +1,35 @@
+module RSpec
+  module Matchers
+    # Provides the necessary plumbing to wrap a matcher with a decorator.
+    # @private
+    class MatcherDelegator
+      include Composable
+      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
+        # :nocov:
+        def respond_to?(name, include_all=false)
+          super || base_matcher.respond_to?(name, include_all)
+        end
+        # :nocov:
+      end
+
+      def initialize_copy(other)
+        @base_matcher = @base_matcher.clone
+        super
+      end
+    end
+  end
+end

data/lib/rspec/matchers/matcher_protocol.rb

@@ -0,0 +1,105 @@
+module RSpec
+  module Matchers
+    # rspec-expectations can work with any matcher object that implements this protocol.
+    #
+    # @note This class is not loaded at runtime by rspec-expectations. It exists
+    #   purely to provide documentation for the matcher protocol.
+    class MatcherProtocol
+      # @!group Required Methods
+
+      # @!method matches?(actual)
+      #   @param actual [Object] The object being matched against.
+      #   @yield For an expression like `expect(x).to matcher do...end`, the `do/end`
+      #     block binds to `to`. It passes that block, if there is one, on to this method.
+      #   @return [Boolean] true if this matcher matches the provided object.
+
+      # @!method failure_message
+      #   This will only be called if {#matches?} returns false.
+      #   @return [String] Explanation for the failure.
+
+      # @!endgroup
+
+      # @!group Optional Methods
+
+      # @!method does_not_match?(actual)
+      #   In a negative expectation such as `expect(x).not_to foo`, RSpec will
+      #   call `foo.does_not_match?(x)` if this method is defined. If it's not
+      #   defined it will fall back to using `!foo.matches?(x)`. This allows you
+      #   to provide custom logic for the negative case.
+      #
+      #   @param actual [Object] The object being matched against.
+      #   @yield For an expression like `expect(x).not_to matcher do...end`, the `do/end`
+      #     block binds to `not_to`. It passes that block, if there is one, on to this method.
+      #   @return [Boolean] true if this matcher does not match the provided object.
+
+      # @!method failure_message_when_negated
+      #   This will only be called when a negative match fails.
+      #   @return [String] Explanation for the failure.
+      #   @note This method is listed as optional because matchers do not have to
+      #     support negation. But if your matcher does support negation, this is a
+      #     required method -- otherwise, you'll get a `NoMethodError`.
+
+      # @!method description
+      #   The description is used for two things:
+      #
+      #     * When using RSpec's one-liner syntax
+      #       (e.g. `it { is_expected.to matcher }`), the description
+      #       is used to generate the example's doc string since you
+      #       have not provided one.
+      #     * In a composed matcher expression, the description is used
+      #       as part of the failure message (and description) of the outer
+      #       matcher.
+      #
+      #   @return [String] Description of the matcher.
+
+      # @!method supports_block_expectations?
+      #   Indicates that this matcher can be used in a block expectation expression,
+      #   such as `expect { foo }.to raise_error`. Generally speaking, this is
+      #   only needed for matchers which operate on a side effect of a block, rather
+      #   than on a particular object.
+      #   @return [Boolean] true if this matcher can be used in block expressions.
+      #   @note If not defined, RSpec assumes a value of `false` for this method.
+
+      # @!method supports_value_expectations?
+      #   Indicates that this matcher can be used in a value expectation expression,
+      #   such as `expect(foo).to eq(bar)`.
+      #   @return [Boolean] true if this matcher can be used in value expressions.
+      #   @note If not defined, RSpec assumes a value of `true` for this method.
+
+      # @!method expects_call_stack_jump?
+      #   Indicates that when this matcher is used in a block expectation
+      #   expression, it expects the block to use a ruby construct that causes
+      #   a call stack jump (such as raising an error or throwing a symbol).
+      #
+      #   This is used internally for compound block expressions, as matchers
+      #   which expect call stack jumps must be treated with care to work properly.
+      #
+      #   @return [Boolean] true if the matcher expects a call stack jump
+      #
+      #   @note This method is very rarely used or needed.
+      #   @note If not defined, RSpec assumes a value of `false` for this method.
+
+      # @!method diffable?
+      #   @return [Boolean] true if `actual` and `expected` can be diffed.
+      #   Indicates that this matcher provides `actual` and `expected` attributes,
+      #   and that the values returned by these can be usefully diffed, which can
+      #   be included in the output.
+
+      # @!method actual
+      #   @return [String, Object] If an object (rather than a string) is provided,
+      #     RSpec will use the `pp` library to convert it to multi-line output in
+      #     order to diff.
+      #   The actual value for the purposes of a diff.
+      #   @note This method is required if `diffable?` returns true.
+
+      # @!method expected
+      #   @return [String, Object] If an object (rather than a string) is provided,
+      #     RSpec will use the `pp` library to convert it to multi-line output in
+      #     order to diff.
+      #   The expected value for the purposes of a diff.
+      #   @note This method is required if `diffable?` returns true.
+
+      # @!endgroup
+    end
+  end
+end