Module: RSpec::Matchers::DSL::Macros

### Home Classes Methods

### In Files

- lib/rspec/matchers/dsl.rb

### Namespace

- MODULE RSpec::Matchers::DSL::Macros::Deprecated

### Methods

- #chain
- #description
- #diffable
- #failure_message
- #failure_message_when_negated
- #match
- #match_unless_raises
- #match_when_negated
- #supports_block_expectations

### Class/Module Index

Quicksearch

- RSpec
- RSpec::Expectations
- RSpec::Expectations::BlockExpectationTarget
- RSpec::Expectations::Configuration
- RSpec::Expectations::ExpectationHelper
- RSpec::Expectations::ExpectationNotMetError
- RSpec::Expectations::ExpectationTarget
- RSpec::Expectations::FailureAggregator
- RSpec::Expectations::LegacyMacherAdapter
- RSpec::Expectations::LegacyMatcherAdapter
- RSpec::Expectations::LegacyMatcherAdapter::RSpec1
- RSpec::Expectations::LegacyMatcherAdapter::RSpec2
- RSpec::Expectations::MultipleExpectationsNotMetError
- RSpec::Expectations::NegativeExpectationHandler
- RSpec::Expectations::PositiveExpectationHandler
- RSpec::Expectations::Syntax
- RSpec::Expectations::Version
- RSpec::Matchers
- RSpec::Matchers::AliasedMatcher
- RSpec::Matchers::AliasedMatcherWithOperatorSupport
- RSpec::Matchers::AliasedNegatedMatcher
- RSpec::Matchers::BuiltIn
- RSpec::Matchers::BuiltIn::All
- RSpec::Matchers::BuiltIn::BaseMatcher
- RSpec::Matchers::BuiltIn::BaseMatcher::DefaultFailureMessages
- RSpec::Matchers::BuiltIn::BaseMatcher::HashFormatting
- RSpec::Matchers::BuiltIn::Be
- RSpec::Matchers::BuiltIn::BeAKindOf
- RSpec::Matchers::BuiltIn::BeAnInstanceOf
- RSpec::Matchers::BuiltIn::BeBetween
- RSpec::Matchers::BuiltIn::BeComparedTo
- RSpec::Matchers::BuiltIn::BeFalsey
- RSpec::Matchers::BuiltIn::BeHelpers
- RSpec::Matchers::BuiltIn::BeNil
- RSpec::Matchers::BuiltIn::BePredicate
- RSpec::Matchers::BuiltIn::BeTruthy
- RSpec::Matchers::BuiltIn::BeWithin
- RSpec::Matchers::BuiltIn::CaptureStderr
- RSpec::Matchers::BuiltIn::CaptureStdout
- RSpec::Matchers::BuiltIn::CaptureStreamToTempfile
- RSpec::Matchers::BuiltIn::Change
- RSpec::Matchers::BuiltIn::ChangeDetails
- RSpec::Matchers::BuiltIn::ChangeFromValue
- RSpec::Matchers::BuiltIn::ChangeRelatively
- RSpec::Matchers::BuiltIn::ChangeToValue
- RSpec::Matchers::BuiltIn::Compound
- RSpec::Matchers::BuiltIn::Compound::And
- RSpec::Matchers::BuiltIn::Compound::NestedEvaluator
- RSpec::Matchers::BuiltIn::Compound::Or
- RSpec::Matchers::BuiltIn::Compound::SequentialEvaluator
- RSpec::Matchers::BuiltIn::ContainExactly
- RSpec::Matchers::BuiltIn::ContainExactly::PairingsMaximizer
- 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::Exist::ExistenceTest
- RSpec::Matchers::BuiltIn::Has
- RSpec::Matchers::BuiltIn::HaveAttributes
- RSpec::Matchers::BuiltIn::Include
- RSpec::Matchers::BuiltIn::Match
- RSpec::Matchers::BuiltIn::NegativeOperatorMatcher
- RSpec::Matchers::BuiltIn::NullCapture
- RSpec::Matchers::BuiltIn::OperatorMatcher
- RSpec::Matchers::BuiltIn::Output
- RSpec::Matchers::BuiltIn::PositiveOperatorMatcher
- RSpec::Matchers::BuiltIn::RaiseError
- RSpec::Matchers::BuiltIn::RespondTo
- RSpec::Matchers::BuiltIn::Satisfy
- RSpec::Matchers::BuiltIn::SpecificValuesChange
- RSpec::Matchers::BuiltIn::StartAndEndWith
- RSpec::Matchers::BuiltIn::StartOrEndWith
- 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::Composable
- RSpec::Matchers::DSL
- RSpec::Matchers::DSL::DefaultImplementations
- RSpec::Matchers::DSL::Macros
- RSpec::Matchers::DSL::Macros::Deprecated
- RSpec::Matchers::DSL::Matcher
- RSpec::Matchers::EnglishPhrasing
- RSpec::Matchers::ExpectedsForMultipleDiffs
- RSpec::Matchers::FailMatchers
- RSpec::Matchers::MatcherDelegator
- RSpec::Matchers::MatcherProtocol
- BasicObject
- Object

No matching classes.

# RSpec::Matchers::DSL::Macros

Contains the methods that are available from within the `RSpec::Matchers.define` DSL for creating custom matchers.

### Constants

RAISE_NOTIFIER

  @private

### Public Instance Methods

chain(method_name, *attr_names, &definition) 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. 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")

    # File lib/rspec/matchers/dsl.rb, line 212
    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

description(&definition) 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 { your_match_logic }

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

@yield [Object] actual the actual object (i.e. the value wrapped by `expect`)

    # File lib/rspec/matchers/dsl.rb, line 167
    def description(&definition)
      define_user_override(__method__, definition)
    end

diffable() click to toggle source

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

    # File lib/rspec/matchers/dsl.rb, line 173
    def diffable
      define_method(:diffable?) { true }
    end

failure_message(&definition) click to toggle source

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

    # File lib/rspec/matchers/dsl.rb, line 130
    def failure_message(&definition)
      define_user_override(__method__, definition)
    end

failure_message_when_negated(&definition) click to toggle source

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

    # File lib/rspec/matchers/dsl.rb, line 149
    def failure_message_when_negated(&definition)
      define_user_override(__method__, definition)
    end

match(&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 `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`)

    # File lib/rspec/matchers/dsl.rb, line 59
    def match(&match_block)
      define_user_override(:matches?, match_block) do |actual|
        begin
          @actual = actual
          RSpec::Support.with_failure_notifier(RAISE_NOTIFIER) do
            super(*actual_arg_for(match_block))
          end
        rescue RSpec::Expectations::ExpectationNotMetError
          false
        end
      end
    end

match_unless_raises(expected_exception=Exception, &match_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

    expect(email_validator).to accept_as_valid("person@company.com")

@yield [Object] actual the actual object (i.e. the value wrapped by `expect`)

    # File lib/rspec/matchers/dsl.rb, line 102
    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

match_when_negated(&match_block) click to toggle source

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

    # File lib/rspec/matchers/dsl.rb, line 81
    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

supports_block_expectations() click to toggle source

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`).

    # File lib/rspec/matchers/dsl.rb, line 181
    def supports_block_expectations
      define_method(:supports_block_expectations?) { true }
    end

[Validate]

Generated with the Darkfish Rdoc Generator 2.