dsl.rb

module RSpec
  module Matchers
    # Defines the custom matcher DSL.
    module DSL
      # Defines a custom matcher.
      # @see RSpec::Matchers
      def define(name, &declarations)
        warn_about_block_args(name, declarations)
        define_method name do |*expected, &block_arg|
          RSpec::Matchers::DSL::Matcher.new(name, declarations, self, *expected, &block_arg)
        end
      end
      alias_method :matcher, :define

    private

      if Proc.method_defined?(:parameters)
        def warn_about_block_args(name, declarations)
          declarations.parameters.each do |type, arg_name|
            next unless type == :block
            RSpec.warning("Your `#{name}` custom matcher receives a block argument (`#{arg_name}`), " \
                          "but due to limitations in ruby, RSpec cannot provide the block. Instead, " \
                          "use the `block_arg` method to access the block")
          end
        end
      else
        # :nocov:
        def warn_about_block_args(*)
          # There's no way to detect block params on 1.8 since the method reflection APIs don't expose it
        end
        # :nocov:
      end

      RSpec.configure { |c| c.extend self } if RSpec.respond_to?(:configure)

      # 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

        # Declares that the matcher can be used in a block expectation.
        # Users will not be able to use your matcher in a block
        # expectation without declaring this.
        # (e.g. `expect { do_something }.to matcher`).
        def supports_block_expectations
          define_method(:supports_block_expectations?) { 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. If the method is invoked and the
        # `include_chain_clauses_in_custom_matcher_descriptions` config option
        # hash been enabled, the chained method name and args will be added to the
        # default description and failure message.
        #
        # In the common case where you just want the chained method to store some
        # value(s) for later use (e.g. in `match`), you can provide one or more
        # attribute names instead of a block; the chained method will store its
        # arguments in instance variables with those names, and the values will
        # be exposed via getters.
        #
        # @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(method_name, *attr_names, &definition)
          unless block_given? ^ attr_names.any?
            raise ArgumentError, "You must pass either a block or some attribute names (but not both) to `chain`."
          end

          definition = assign_attributes(attr_names) if attr_names.any?

          define_user_override(method_name, definition) do |*args, &block|
            super(*args, &block)
            @chained_method_clauses.push([method_name, args])
            self
          end
        end

        def assign_attributes(attr_names)
          attr_reader(*attr_names)
          private(*attr_names)

          lambda do |*attr_values|
            attr_names.zip(attr_values) do |attr_name, attr_value|
              instance_variable_set(:"@#{attr_name}", attr_value)
            end
          end
        end

        # assign_attributes isn't defined in the private section below because
        # that makes MRI 1.9.2 emit a warning about private attributes.
        private :assign_attributes

      private

        # Does the following:
        #
        # - Defines the named method using 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
        include BuiltIn::BaseMatcher::DefaultFailureMessages

        # @api private
        # Used internally by objects returns by `should` and `should_not`.
        def diffable?
          false
        end

        # The default description.
        def description
          english_name = EnglishPhrasing.split_words(name)
          expected_list = EnglishPhrasing.list(expected)
          "#{english_name}#{expected_list}#{chained_method_clause_sentences}"
        end

        # Matchers do not support block expectations by default. You
        # must opt-in.
        def supports_block_expectations?
          false
        end

        # Most matchers do not expect call stack jumps.
        def expects_call_stack_jump?
          false
        end

      private

        def chained_method_clause_sentences
          return '' unless Expectations.configuration.include_chain_clauses_in_custom_matcher_descriptions?

          @chained_method_clauses.map do |(method_name, method_args)|
            english_name = EnglishPhrasing.split_words(method_name)
            arg_list = EnglishPhrasing.list(method_args)
            " #{english_name}#{arg_list}"
          end.join
        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

        # 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

        # Exposes the value being matched against -- generally the object
        # object wrapped by `expect`.
        attr_reader :actual

        # Exposes the exception raised during the matching by `match_unless_raises`.
        # Could be useful to extract details for a failure message.
        attr_reader :rescued_exception

        # The block parameter used in the expectation
        attr_reader :block_arg

        # The name of the matcher.
        attr_reader :name

        # @api private
        def initialize(name, declarations, matcher_execution_context, *expected, &block_arg)
          @name     = name
          @actual   = nil
          @expected_as_array = expected
          @matcher_execution_context = matcher_execution_context
          @chained_method_clauses = []
          @block_arg = block_arg

          class << self
            # See `Macros#define_user_override` above, for an explanation.
            include(@user_method_defs = Module.new)
            self
          end.class_exec(*expected, &declarations)
        end

        # Provides the expected value. This will return an array if
        # multiple arguments were passed to the matcher; otherwise it
        # will return a single value.
        # @see #expected_as_array
        def expected
          if expected_as_array.size == 1
            expected_as_array[0]
          else
            expected_as_array
          end
        end

        # Returns the expected value as an an array. This exists primarily
        # to aid in upgrading from RSpec 2.x, since in RSpec 2, `expected`
        # always returned an array.
        # @see #expected
        attr_reader :expected_as_array

        # 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
          # :nocov:
          # 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
          # :nocov:
        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

RSpec::Matchers.extend RSpec::Matchers::DSL