From: Eric Hodel Date: 2006-04-12T13:17:13+09:00 Subject: [PATCH] Test::Unit::Assertions RDoc --Apple-Mail-18--995501824 Content-Transfer-Encoding: 7bit Content-Type: text/plain; charset=US-ASCII; delsp=yes; format=flowed This patch contains some spiffy RDoc for Test::Unit::Assertions. No longer will people have to grope in the dark for what Test::Unit's assertions are. --Apple-Mail-18--995501824 Content-Transfer-Encoding: 7bit Content-Type: application/octet-stream; x-unix-mode=0644; name="assertions.rb.patch" Content-Disposition: attachment; filename=assertions.rb.patch Index: lib/.document =================================================================== RCS file: /src/ruby/lib/.document,v retrieving revision 1.12 diff -u -r1.12 .document --- lib/.document 15 Dec 2005 03:41:12 -0000 1.12 +++ lib/.document 12 Apr 2006 04:15:59 -0000 @@ -35,6 +35,7 @@ singleton.rb tempfile.rb test/unit.rb +test/unit/assertions.rb thread.rb thwait.rb time.rb Index: lib/test/unit/assertions.rb =================================================================== RCS file: /src/ruby/lib/test/unit/assertions.rb,v retrieving revision 1.16 diff -u -r1.16 assertions.rb --- lib/test/unit/assertions.rb 24 Dec 2003 05:08:03 -0000 1.16 +++ lib/test/unit/assertions.rb 12 Apr 2006 04:15:59 -0000 @@ -1,5 +1,3 @@ -# :nodoc: -# # Author:: Nathaniel Talbott. # Copyright:: Copyright (c) 2000-2003 Nathaniel Talbott. All rights reserved. # License:: Ruby license. @@ -10,21 +8,39 @@ module Test # :nodoc: module Unit # :nodoc: - # Contains all of the standard Test::Unit assertions. Mixed in - # to Test::Unit::TestCase. To mix it in and use its - # functionality, you simply need to rescue - # Test::Unit::AssertionFailedError, and you can additionally - # override add_assertion to be notified whenever an assertion - # is made. + ## + # Test::Unit::Assertions contains the standard Test::Unit assertions. + # Assertions is included in Test::Unit::TestCase. + # + # To include it in your own code and use its functionality, you simply + # need to rescue Test::Unit::AssertionFailedError. Additionally you may + # override add_assertion to get notified whenever an assertion is made. # # Notes: - # * The message to each assertion, if given, will be - # propagated with the failure. - # * It's easy to add your own assertions based on assert_block(). + # * The message to each assertion, if given, will be propagated with the + # failure. + # * It is easy to add your own assertions based on assert_block(). + # + # = Example Custom Assertion + # + # def deny(boolean, message = nil) + # message = build_message message, ' is not false or nil.', boolean + # assert_block message do + # not boolean + # end + # end + module Assertions - # The assertion upon which all other assertions are - # based. Passes if the block yields true. + ## + # The assertion upon which all other assertions are based. Passes if the + # block yields true. + # + # Test: + # assert_block "Couldn't do the thing" do + # do_the_thing + # end + public def assert_block(message="assert_block failed.") # :yields: _wrap_assertion do @@ -34,7 +50,12 @@ end end - # Passes if boolean is true. + ## + # Asserts that +boolean+ is not false or nil. + # + # Test: + # assert [1, 2].include?(5) + public def assert(boolean, message=nil) _wrap_assertion do @@ -43,10 +64,16 @@ end end - # Passes if expected == actual. Note that the ordering of - # arguments is important, since a helpful error message is - # generated when this one fails that tells you the values - # of expected and actual. + ## + # Passes if +expected+ == +actual. + # + # Note that the ordering of arguments is important, since a helpful + # error message is generated when this one fails that tells you the + # values of expected and actual. + # + # Test: + # assert_equal 'MY STRING', 'my string'.upcase + public def assert_equal(expected, actual, message=nil) full_message = build_message(message, <=, 4 + public def assert_operator(object1, operator, object2, message="") _wrap_assertion do @@ -197,7 +271,14 @@ end end + ## # Passes if block does not raise an exception. + # + # Test: + # assert_nothing_raised do + # [1, 2].uniq + # end + public def assert_nothing_raised(*args) _wrap_assertion do @@ -221,13 +302,23 @@ end end - # Always fails. + ## + # Flunk always fails. + # + # Test: + # flunk 'Not done testing yet.' + public def flunk(message="Flunked") assert_block(build_message(message)){false} end - # Passes if !actual.equal?(expected). + ## + # Passes if ! +actual+ .equal? +expected+ + # + # Test: + # assert_not_same Object.new, Object.new + public def assert_not_same(expected, actual, message="") full_message = build_message(message, < expected to be != to\n.", expected, actual) assert_block(full_message) { expected != actual } end - # Passes if !object.nil?. + ## + # Passes if ! +object+ .nil? + # + # Test: + # assert_not_nil '1 two 3'.sub!(/two/, '2') + public def assert_not_nil(object, message="") full_message = build_message(message, " expected to not be nil.", object) assert_block(full_message){!object.nil?} end - # Passes if string !~ regularExpression. + ## + # Passes if +regexp+ !~ +string+ + # + # Test: + # assert_no_match(/two/, 'one 2 three') + public def assert_no_match(regexp, string, message="") _wrap_assertion do @@ -266,7 +372,14 @@ UncaughtThrow = {NameError => /^uncaught throw \`(.+)\'$/, ThreadError => /^uncaught throw \`(.+)\' in thread /} #` - # Passes if block throws symbol. + ## + # Passes if the block throws +expected_symbol+ + # + # Test: + # assert_throws :done do + # throw :done + # end + public def assert_throws(expected_symbol, message="", &proc) _wrap_assertion do @@ -290,7 +403,14 @@ end end + ## # Passes if block does not throw anything. + # + # Test: + # assert_nothing_thrown do + # [1, 2].uniq + # end + public def assert_nothing_thrown(message="", &proc) _wrap_assertion do @@ -308,8 +428,13 @@ end end - # Passes if expected_float and actual_float are equal - # within delta tolerance. + ## + # Passes if +expected_float+ and +actual_float+ are equal + # within +delta+ tolerance. + # + # Test: + # assert_in_delta 0.05, (50000.0 / 10**6), 0.00001 + public def assert_in_delta(expected_float, actual_float, delta, message="") _wrap_assertion do @@ -326,7 +451,17 @@ end end - # Passes if the method sent returns a true value. + ## + # Passes if the method send returns a true value. + # + # +send_array+ is composed of: + # * A reciever + # * A method + # * Arguments to the method + # + # Test: + # assert_send [[1, 2], :include?, 4] + public def assert_send(send_array, message="") _wrap_assertion do @@ -340,6 +475,10 @@ end end + ## + # Builds a failure message. +head+ is added before the +template+ and + # +arguments+ replaces the '?'s positionally in the template. + public def build_message(head, template=nil, *arguments) # :nodoc: template &&= template.chomp @@ -362,14 +501,18 @@ end end - # Called whenever an assertion is made. + ## + # Called whenever an assertion is made. Define this in classes that + # include Test::Unit::Assertions to record assertion counts. + private def add_assertion end - # Select whether or not to use the prettyprinter. If this - # option is set to false before any assertions are made, the - # prettyprinter will not be required at all. + ## + # Select whether or not to use the pretty-printer. If this option is set + # to false before any assertions are made, pp.rb will not be required. + public def self.use_pp=(value) AssertionMessage.use_pp = value --Apple-Mail-18--995501824 Content-Transfer-Encoding: 7bit Content-Type: text/plain; charset=US-ASCII; format=flowed -- Eric Hodel - drbrain@segment7.net - http://blog.segment7.net This implementation is HODEL-HASH-9600 compliant http://trackmap.robotcoop.com --Apple-Mail-18--995501824--