Parent

Class Index [+]

Quicksearch

RSpec::Matchers::DSL::Matcher

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

Constants

PERSISTENT_INSTANCE_VARIABLES

Attributes

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

Public Class Methods

new(name, &declarations) click to toggle source

@api private

    # File lib/rspec/matchers/matcher.rb, line 17
17:         def initialize(name, &declarations)
18:           @name         = name
19:           @declarations = declarations
20:           @actual       = nil
21:           @diffable     = false
22:           @expected_exception, @rescued_exception = nil, nil
23:           @match_for_should_not_block = nil
24:           @messages = {}
25:         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 203
203:         def chain(method, &block)
204:           define_method method do |*args|
205:             block.call(*args)
206:             self
207:           end
208:         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 175
175:         def description(&block)
176:           cache_or_call_cached(:description, &block)
177:         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 181
181:         def diffable
182:           @diffable = true
183:         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 212
212:         def diffable?
213:           @diffable
214:         end
does_not_match?(actual) click to toggle source

@api private Used internally by should_not

     # File lib/rspec/matchers/matcher.rb, line 218
218:         def does_not_match?(actual)
219:           @actual = actual
220:           @match_for_should_not_block ?
221:             instance_eval_with_args(actual, &@match_for_should_not_block) :
222:             !matches?(actual)
223:         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 138
138:         def failure_message_for_should(&block)
139:           cache_or_call_cached(:failure_message_for_should, &block)
140:         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 158
158:         def failure_message_for_should_not(&block)
159:           cache_or_call_cached(:failure_message_for_should_not, &block)
160:         end
for_expected(*expected) click to toggle source

@api private

    # File lib/rspec/matchers/matcher.rb, line 34
34:         def for_expected(*expected)
35:           @expected = expected
36:           dup.instance_eval do
37:             instance_variables.map {|ivar| ivar.intern}.each do |ivar|
38:               instance_variable_set(ivar, nil) unless (PERSISTENT_INSTANCE_VARIABLES + [:@expected]).include?(ivar)
39:             end
40:             making_declared_methods_public do
41:               instance_eval_with_args(*@expected, &@declarations)
42:             end
43:             self
44:           end
45:         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 90
90:         def match(&block)
91:           @match_block = block
92:         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 102
102:         def match_for_should_not(&block)
103:           @match_for_should_not_block = block
104:         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 118
118:         def match_unless_raises(exception=Exception, &block)
119:           @expected_exception = exception
120:           match(&block)
121:         end
matches?(actual) click to toggle source

@api private Used internally by should and should_not.

    # File lib/rspec/matchers/matcher.rb, line 49
49:         def matches?(actual)
50:           @actual = actual
51:           if @expected_exception
52:             begin
53:               instance_eval_with_args(actual, &@match_block)
54:               true
55:             rescue @expected_exception => @rescued_exception
56:               false
57:             end
58:           else
59:             begin
60:               instance_eval_with_args(actual, &@match_block)
61:             rescue RSpec::Expectations::ExpectationNotMetError
62:               false
63:             end
64:           end
65:         end
respond_to?(method, include_private=false) click to toggle source
     # File lib/rspec/matchers/matcher.rb, line 225
225:         def respond_to?(method, include_private=false)
226:           super || matcher_execution_context.respond_to?(method, include_private)
227:         end

Private Instance Methods

cache(key, &block) click to toggle source
     # File lib/rspec/matchers/matcher.rb, line 267
267:         def cache(key, &block)
268:           @messages[key] = block
269:         end
cache_or_call_cached(key, &block) click to toggle source
     # File lib/rspec/matchers/matcher.rb, line 263
263:         def cache_or_call_cached(key, &block)
264:           block ? cache(key, &block) : call_cached(key)
265:         end
call_cached(key) click to toggle source
     # File lib/rspec/matchers/matcher.rb, line 271
271:         def call_cached(key)
272:           if @messages.has_key?(key)
273:             @messages[key].arity == 1 ? @messages[key].call(@actual) : @messages[key].call
274:           else
275:             send("default_#{key}")
276:           end
277:         end
default_description() click to toggle source
     # File lib/rspec/matchers/matcher.rb, line 279
279:         def default_description
280:           "#{name_to_sentence}#{expected_to_sentence}"
281:         end
default_failure_message_for_should() click to toggle source
     # File lib/rspec/matchers/matcher.rb, line 283
283:         def default_failure_message_for_should
284:           "expected #{actual.inspect} to #{name_to_sentence}#{expected_to_sentence}"
285:         end
default_failure_message_for_should_not() click to toggle source
     # File lib/rspec/matchers/matcher.rb, line 287
287:         def default_failure_message_for_should_not
288:           "expected #{actual.inspect} not to #{name_to_sentence}#{expected_to_sentence}"
289:         end
define_method(name, &block) click to toggle source
     # File lib/rspec/matchers/matcher.rb, line 243
243:         def define_method(name, &block)
244:           singleton_class.__send__(:define_method, name, &block)
245:         end
include(*args) click to toggle source
     # File lib/rspec/matchers/matcher.rb, line 239
239:         def include(*args)
240:           singleton_class.__send__(:include, *args)
241:         end
making_declared_methods_public() click to toggle source
     # File lib/rspec/matchers/matcher.rb, line 247
247:         def making_declared_methods_public
248:           # Our home-grown instance_exec in ruby 1.8.6 results in any methods
249:           # declared in the block eval'd by instance_exec in the block to which we
250:           # are yielding here are scoped private. This is NOT the case for Ruby
251:           # 1.8.7 or 1.9.
252:           #
253:           # Also, due some crazy scoping that I don't understand, these methods
254:           # are actually available in the specs (something about the matcher being
255:           # defined in the scope of RSpec::Matchers or within an example), so not
256:           # doing the following will not cause specs to fail, but they *will*
257:           # cause features to fail and that will make users unhappy. So don't.
258:           orig_private_methods = private_methods
259:           yield
260:           (private_methods - orig_private_methods).each {|m| singleton_class.__send__ :public, m}
261:         end
method_missing(method, *args, &block) click to toggle source
     # File lib/rspec/matchers/matcher.rb, line 231
231:         def method_missing(method, *args, &block)
232:           if matcher_execution_context.respond_to?(method)
233:             matcher_execution_context.send method, *args, &block
234:           else
235:             super(method, *args, &block)
236:           end
237:         end
singleton_class() click to toggle source
     # File lib/rspec/matchers/matcher.rb, line 292
292:           def singleton_class
293:             class << self; self; end
294:           end

Disabled; run with --debug to generate this.

[Validate]

Generated with the Darkfish Rdoc Generator 1.1.6.