Provides the context in which the block passed to RSpec::Matchers.define will be evaluated.
@api private
# File lib/rspec/matchers/matcher.rb, line 13 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 = { :description => lambda {"#{name_to_sentence}#{expected_to_sentence}"}, :failure_message_for_should => lambda {|actual| "expected #{actual.inspect} to #{name_to_sentence}#{expected_to_sentence}"}, :failure_message_for_should_not => lambda {|actual| "expected #{actual.inspect} not to #{name_to_sentence}#{expected_to_sentence}"} } 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 193 def chain(method, &block) define_method method do |*args| block.call(*args) self end 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 165 def description(&block) cache_or_call_cached(:description, &block) end
Tells the matcher to diff the actual and expected values in the failure message.
# File lib/rspec/matchers/matcher.rb, line 171 def diffable @diffable = true end
@api private Used internally by objects returns by should
and
should_not
.
# File lib/rspec/matchers/matcher.rb, line 202 def diffable? @diffable end
@api private Used internally by should_not
# File lib/rspec/matchers/matcher.rb, line 208 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
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 128 def failure_message_for_should(&block) cache_or_call_cached(:failure_message_for_should, &block) 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 148 def failure_message_for_should_not(&block) cache_or_call_cached(:failure_message_for_should_not, &block) end
@api private
# File lib/rspec/matchers/matcher.rb, line 29 def for_expected(*expected) @expected = expected making_declared_methods_public do instance_eval_with_args(*@expected, &@declarations) end self 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 80 def match(&block) @match_block = block 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 92 def match_for_should_not(&block) @match_for_should_not_block = block 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 108 def match_unless_raises(exception=Exception, &block) @expected_exception = exception match(&block) end
@api private Used internally by should
and
should_not
.
# File lib/rspec/matchers/matcher.rb, line 39 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