Class: RSpec::Matchers::DSL::Matcher

### Home Classes Methods

### In Files

- lib/rspec/matchers/matcher.rb

### Parent

Object

### Methods

- ::new
- #chain
- #description
- #diffable
- #diffable?
- #does_not_match?
- #failure_message_for_should
- #failure_message_for_should_not
- #for_expected
- #match
- #match_for_should
- #match_for_should_not
- #match_unless_raises
- #matches?
- #respond_to?

### Included Modules

- RSpec::Matchers::Extensions::InstanceEvalWithArgs
- RSpec::Matchers::Pretty
- RSpec::Matchers

### Class/Module Index

Quicksearch

- RSpec
- RSpec::Expectations
- RSpec::Expectations::DeprecatedConstants
- RSpec::Expectations::Deprecation
- RSpec::Expectations::Differ
- RSpec::Expectations::ExpectationHandler
- RSpec::Expectations::ExpectationNotMetError
- RSpec::Expectations::ExpectationTarget
- RSpec::Expectations::NegativeExpectationHandler
- RSpec::Expectations::PositiveExpectationHandler
- RSpec::Expectations::Syntax
- RSpec::Expectations::Syntax::ExpectExpressionGenerator
- RSpec::Expectations::Syntax::ShouldExpressionGenerator
- RSpec::Expectations::Version
- RSpec::Matchers
- RSpec::Matchers::BuiltIn
- RSpec::Matchers::BuiltIn::BaseMatcher
- RSpec::Matchers::BuiltIn::Be
- RSpec::Matchers::BuiltIn::BeAKindOf
- RSpec::Matchers::BuiltIn::BeAnInstanceOf
- RSpec::Matchers::BuiltIn::BeComparedTo
- RSpec::Matchers::BuiltIn::BeFalse
- RSpec::Matchers::BuiltIn::BeHelpers
- RSpec::Matchers::BuiltIn::BeNil
- RSpec::Matchers::BuiltIn::BePredicate
- RSpec::Matchers::BuiltIn::BeTrue
- RSpec::Matchers::BuiltIn::BeWithin
- RSpec::Matchers::BuiltIn::Change
- RSpec::Matchers::BuiltIn::Cover
- RSpec::Matchers::BuiltIn::EndWith
- RSpec::Matchers::BuiltIn::Eq
- RSpec::Matchers::BuiltIn::Eql
- RSpec::Matchers::BuiltIn::Equal
- RSpec::Matchers::BuiltIn::Exist
- RSpec::Matchers::BuiltIn::Has
- RSpec::Matchers::BuiltIn::Have
- RSpec::Matchers::BuiltIn::Include
- RSpec::Matchers::BuiltIn::Match
- RSpec::Matchers::BuiltIn::MatchArray
- RSpec::Matchers::BuiltIn::NegativeOperatorMatcher
- RSpec::Matchers::BuiltIn::PositiveOperatorMatcher
- RSpec::Matchers::BuiltIn::RaiseError
- RSpec::Matchers::BuiltIn::RespondTo
- RSpec::Matchers::BuiltIn::Satisfy
- RSpec::Matchers::BuiltIn::StartAndEndWith
- RSpec::Matchers::BuiltIn::StartWith
- RSpec::Matchers::BuiltIn::ThrowSymbol
- RSpec::Matchers::BuiltIn::YieldControl
- RSpec::Matchers::BuiltIn::YieldProbe
- RSpec::Matchers::BuiltIn::YieldSuccessiveArgs
- RSpec::Matchers::BuiltIn::YieldWithArgs
- RSpec::Matchers::BuiltIn::YieldWithNoArgs
- RSpec::Matchers::Configuration
- RSpec::Matchers::DSL
- RSpec::Matchers::DSL::Matcher
- RSpec::Matchers::Extensions
- RSpec::Matchers::Extensions::InstanceEvalWithArgs
- RSpec::Matchers::OperatorMatcher
- RSpec::Matchers::Pretty
- Array

No matching classes.

# RSpec::Matchers::DSL::Matcher

Provides the context in which the block passed to RSpec::Matchers.define will be evaluated.

### Constants

PERSISTENT_INSTANCE_VARIABLES

### Attributes

actual[R]
expected[R]
matcher_execution_context[RW]
rescued_exception[R]

### Public Class Methods

new(name, &declarations) click to toggle source

@api private

    # File lib/rspec/matchers/matcher.rb, line 17
    def initialize(name, &declarations)
      @name         = name
      @declarations = declarations
      @actual       = nil
      @diffable     = false
      @expected_exception, @rescued_exception = nil, nil
      @match_for_should_not_block = nil
      @messages = {}
    end

### Public Instance Methods

chain(method, &block) click to toggle source

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

    minor.should have_errors_on(:age).with("Not old enough to participate")

    # File lib/rspec/matchers/matcher.rb, line 204
    def chain(method, &block)
      define_method method do |*args|
        block.call(*args)
        self
      end
    end

description(&block) click to toggle source

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 { ... }

      description do
        "qualify for #{expected}"
      end
    end

    # File lib/rspec/matchers/matcher.rb, line 176
    def description(&block)
      cache_or_call_cached(:description, &block)
    end

diffable() click to toggle source

Tells the matcher to diff the actual and expected values in the failure message.

    # File lib/rspec/matchers/matcher.rb, line 182
    def diffable
      @diffable = true
    end

diffable?() click to toggle source

@api private Used internally by objects returns by `should` and `should_not`.

    # File lib/rspec/matchers/matcher.rb, line 213
    def diffable?
      @diffable
    end

does_not_match?(actual) click to toggle source

@api private Used internally by `should_not`

    # File lib/rspec/matchers/matcher.rb, line 219
    def does_not_match?(actual)
      @actual = actual
      @match_for_should_not_block ?
        instance_eval_with_args(actual, &@match_for_should_not_block) :
        !matches?(actual)
    end

failure_message_for_should(&block) click to toggle source

Customize the failure messsage to use when this matcher is invoked with `should`. Only use this when the message generated by default doesn't suit your needs.

@example

    RSpec::Matchers.define :have_strength do |expected|
      match { ... }

      failure_message_for_should do |actual|
        "Expected strength of #{expected}, but had #{actual.strength}"
      end
    end

@yield [Object] actual the actual object

    # File lib/rspec/matchers/matcher.rb, line 139
    def failure_message_for_should(&block)
      cache_or_call_cached(:failure_message_for_should, &block)
    end

failure_message_for_should_not(&block) click to toggle source

Customize the failure messsage to use when this matcher is invoked with `should_not`. Only use this when the message generated by default doesn't suit your needs.

@example

    RSpec::Matchers.define :have_strength do |expected|
      match { ... }

      failure_message_for_should_not do |actual|
        "Expected not to have strength of #{expected}, but did"
      end
    end

@yield [Object] actual the actual object @yield [Object] actual the actual object

    # File lib/rspec/matchers/matcher.rb, line 159
    def failure_message_for_should_not(&block)
      cache_or_call_cached(:failure_message_for_should_not, &block)
    end

for_expected(*expected) click to toggle source

@api private

    # File lib/rspec/matchers/matcher.rb, line 34
    def for_expected(*expected)
      @expected = expected
      dup.instance_eval do
        instance_variables.map {|ivar| ivar.intern}.each do |ivar|
          instance_variable_set(ivar, nil) unless (PERSISTENT_INSTANCE_VARIABLES + [:@expected]).include?(ivar)
        end
        @messages = {}
        making_declared_methods_public do
          instance_eval_with_args(*@expected, &@declarations)
        end
        self
      end
    end

match(&block) click to toggle source

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 `should` and the block returns `true`, then the expectation passes. Similarly, when the matcher is passed to `should_not` and the block returns `false`, then the expectation passes.

Use `match_for_should` when used in conjuntion with `match_for_should_not`.

@example

    RSpec::Matchers.define :be_even do
      match do |actual|
        actual.even?
      end
    end

    4.should be_even     # passes
    3.should_not be_even # passes
    3.should be_even     # fails
    4.should_not be_even # fails

@yield [Object] actual the actual value (or receiver of should)

    # File lib/rspec/matchers/matcher.rb, line 91
    def match(&block)
      @match_block = block
    end

Also aliased as: match_for_should
match_for_should(&block) click to toggle source
Alias for: match
match_for_should_not(&block) click to toggle source

Use this to define the block for a negative expectation (`should_not`) 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 (or receiver of should)

    # File lib/rspec/matchers/matcher.rb, line 103
    def match_for_should_not(&block)
      @match_for_should_not_block = block
    end

match_unless_raises(exception=Exception, &block) click to toggle source

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

    email_validator.should accept_as_valid("person@company.com")

    # File lib/rspec/matchers/matcher.rb, line 119
    def match_unless_raises(exception=Exception, &block)
      @expected_exception = exception
      match(&block)
    end

matches?(actual) click to toggle source

@api private Used internally by `should` and `should_not`.

    # File lib/rspec/matchers/matcher.rb, line 50
    def matches?(actual)
      @actual = actual
      if @expected_exception
        begin
          instance_eval_with_args(actual, &@match_block)
          true
        rescue @expected_exception => @rescued_exception
          false
        end
      else
        begin
          instance_eval_with_args(actual, &@match_block)
        rescue RSpec::Expectations::ExpectationNotMetError
          false
        end
      end
    end

respond_to?(method, include_private=false) click to toggle source

    # File lib/rspec/matchers/matcher.rb, line 226
    def respond_to?(method, include_private=false)
      super || matcher_execution_context.respond_to?(method, include_private)
    end

[Validate]

Generated with the Darkfish Rdoc Generator 2.