Class RSpec::Matchers::DSL::Matcher
In: lib/rspec/matchers/matcher.rb
Parent: Object

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

Methods

Included Modules

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

Constants

PERSISTENT_INSTANCE_VARIABLES = [ :@name, :@declarations, :@diffable, :@match_block, :@match_for_should_not_block, :@expected_exception

Attributes

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

Public Class methods

Public Instance methods

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")

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

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

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

@api private Used internally by should_not

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

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

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)

match_for_should(&block)

Alias for match

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)

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")

@api private Used internally by should and should_not.

[Validate]