Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

simple_matcher rdoc

  • Loading branch information...
commit 0ab525e6be3415664883338749a38c20d54a13c3 1 parent 63d2edc
@dchelimsky authored
Showing with 75 additions and 47 deletions.
  1. +1 −1  Rakefile
  2. +74 −46 lib/spec/matchers/simple_matcher.rb
View
2  Rakefile
@@ -66,7 +66,7 @@ desc 'Generate RDoc'
rd = Rake::RDocTask.new do |rdoc|
rdoc.rdoc_dir = '../doc/output/rdoc'
rdoc.options << '--title' << 'RSpec' << '--line-numbers' << '--inline-source' << '--main' << 'README'
- rdoc.rdoc_files.include('README', 'CHANGES', 'MIT-LICENSE', 'UPGRADE', 'lib/**/*.rb')
+ rdoc.rdoc_files.include('README', 'CHANGES', 'MIT-LICENSE', 'lib/**/*.rb')
end
spec = Gem::Specification.new do |s|
View
120 lib/spec/matchers/simple_matcher.rb
@@ -35,68 +35,96 @@ def explanation
end
end
- # +simple_matcher()+ makes it easy for you to create your own custom
- # matchers in just a few lines of code when you don't need all the power
- # of a completely custom matcher object.
+ # simple_matcher makes it easy for you to create your own custom matchers
+ # in just a few lines of code when you don't need all the power of a
+ # completely custom matcher object.
#
- # The description argument will appear as part of any failure message.
+ # The <tt>description</tt> argument will appear as part of any failure
+ # message, and is also the source for auto-generated descriptions.
#
- # The match block can have arity of 1 or 2. The first argument will be the
- # given value. The second, if the block accepts it will be the matcher
- # itself, giving you access to set custom failure messages in favor of the
- # defaults.
+ # The <tt>match_block</tt> can have an arity of 1 or 2. The first block
+ # argument will be the given value. The second, if the block accepts it
+ # will be the matcher itself, giving you access to set custom failure
+ # messages in favor of the defaults.
#
- # If you set custom messages, you don't have to pass the description
- # argument to the simple_matcher method, but you must then provide any
- # messages that might get invoked directly to the matcher (see Example
- # with custom messages, below)
+ # The <tt>match_block</tt> should return a boolean: <tt>true</tt>
+ # indicates a match, which will pass if you use <tt>should</tt> and fail
+ # if you use <tt>should_not</tt>. false (or nil) indicates no match,
+ # which will do the reverse: fail if you use <tt>should</tt> and pass if
+ # you use <tt>should_not</tt>.
#
- # The match_block should return a boolean: true indicates a match, which
- # will pass if you use +should+ and fail if you use +should_not+. false
- # (or nil) indicates no match, which will do the reverse: fail if you use
- # +should+ and pass if you use +should_not+.
- #
- # An error in the +match_block+ will bubble up, resulting in a failure.
- # This includes ExpectationNotMet errors (raised by +should+ and
- # +should_not+), so you can wrap other expectations in a +simple_matcher+
- # and they'll "do the right thing."
+ # An error in the <tt>match_block</tt> will bubble up, resulting in a
+ # failure.
#
# == Example with default messages
#
- # def be_even
- # simple_matcher("an even number") { |given| given % 2 == 0 }
- # end
- #
- # describe 2 do
- # it "should be even" do
- # 2.should be_even
+ # def be_even
+ # simple_matcher("an even number") { |given| given % 2 == 0 }
+ # end
+ #
+ # describe 2 do
+ # it "should be even" do
+ # 2.should be_even
+ # end
# end
- # end
#
- # Given an odd number, this example would produce an error message stating
- # 'expected "an even number"", got 3'
+ # Given an odd number, this example would produce an error message stating:
+ # expected "an even number", got 3.
+ #
+ # Unfortunately, if you're a fan of auto-generated descriptions, this will
+ # produce "should an even number." Not the most desirable result. You can
+ # control that using custom messages:
#
# == Example with custom messages
#
- # def rhyme_with(expected)
- # simple_matcher do |given, matcher|
- # matcher.description = "string rhymer"
- # matcher.failure_message = "expected #{given.inspect} to rhyme with #{expected.inspect}"
- # matcher.negative_failure_message = "expected #{given.inspect} not to rhyme with #{expected.inspect}"
- # actual.rhymes_with? expected
+ # def rhyme_with(expected)
+ # simple_matcher("rhyme with #{expected.inspect}") do |given, matcher|
+ # matcher.failure_message = "expected #{given.inspect} to rhyme with #{expected.inspect}"
+ # matcher.negative_failure_message = "expected #{given.inspect} not to rhyme with #{expected.inspect}"
+ # actual.rhymes_with? expected
+ # end
+ # end
+ #
+ # # OR
+ #
+ # def rhyme_with(expected)
+ # simple_matcher do |given, matcher|
+ # matcher.description = "rhyme with #{expected.inspect}"
+ # matcher.failure_message = "expected #{given.inspect} to rhyme with #{expected.inspect}"
+ # matcher.negative_failure_message = "expected #{given.inspect} not to rhyme with #{expected.inspect}"
+ # actual.rhymes_with? expected
+ # end
# end
- # end
#
- # describe "pecan" do
- # it "should rhyme with 'be gone'" do
- # nut = "pecan"
- # nut.extend Rhymer
- # nut.should rhyme_with("be gone")
+ # describe "pecan" do
+ # it "should rhyme with 'be gone'" do
+ # nut = "pecan"
+ # nut.extend Rhymer
+ # nut.should rhyme_with("be gone")
+ # end
# end
- # end
#
- # The resulting failure message would be 'expected "pecan" to rhyme with
- # "be gone"'. (Grandma Rita would be proud!)
+ # The resulting messages would be:
+ # description: rhyme with "be gone"
+ # failure_message: expected "pecan" to rhyme with "be gone"
+ # negative failure_message: expected "pecan" not to rhyme with "be gone"
+ #
+ # == Wrapped Expectations
+ #
+ # Because errors will bubble up, it is possible to wrap other expectations
+ # in a SimpleMatcher.
+ #
+ # def be_even
+ # simple_matcher("an even number") { |given| (given % 2).should == 0 }
+ # end
+ #
+ # BE VERY CAREFUL when you do this. Only use wrapped expectations for
+ # matchers that will always be used in only the positive
+ # (<tt>should</tt>) or negative (<tt>should_not</tt>), but not both.
+ # The reason is that is you wrap a <tt>should</tt> and call the wrapper
+ # with <tt>should_not</tt>, the correct result (the <tt>should</tt>
+ # failing), will fail when you want it to pass.
+ #
def simple_matcher(description=nil, &match_block)
SimpleMatcher.new(description, &match_block)
end
Please sign in to comment.
Something went wrong with that request. Please try again.