Object
Provides the context in which the block passed to RSpec::Matchers.define will be evaluated.
@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
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
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
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
@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
@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
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
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
@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
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
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
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
@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
# File lib/rspec/matchers/matcher.rb, line 267 267: def cache(key, &block) 268: @messages[key] = block 269: end
# 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
# 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
# File lib/rspec/matchers/matcher.rb, line 279 279: def default_description 280: "#{name_to_sentence}#{expected_to_sentence}" 281: end
# 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
# 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
# File lib/rspec/matchers/matcher.rb, line 243 243: def define_method(name, &block) 244: singleton_class.__send__(:define_method, name, &block) 245: end
# File lib/rspec/matchers/matcher.rb, line 239 239: def include(*args) 240: singleton_class.__send__(:include, *args) 241: end
# 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
# 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
Disabled; run with --debug to generate this.
Generated with the Darkfish Rdoc Generator 1.1.6.