From d5a2139dfb854cf59192dfd36e16075786b9297e Mon Sep 17 00:00:00 2001 From: drbrain Date: Mon, 19 Jun 2006 18:24:46 +0000 Subject: Merge RDoc from HEAD git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/branches/ruby_1_8@10335 b2dd03c8-39d4-4d8f-98ff-823fe69b080e --- ChangeLog | 4 + lib/.document | 7 +- lib/test/unit/assertions.rb | 236 ++++++++++++++++++++++++++++++++++++-------- 3 files changed, 202 insertions(+), 45 deletions(-) diff --git a/ChangeLog b/ChangeLog index 7c3ec4c81c..52a87fcaf2 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,7 @@ +Sat Jun 19 11:21:46 2006 Eric Hodel + + * lib/test/unit/assertions.rb: Merge RDoc from HEAD. + Tue Jun 20 01:06:57 2006 Kouhei Sutou * lib/rss/rss.rb: diff --git a/lib/.document b/lib/.document index 4236a2a914..561fb1c900 100644 --- a/lib/.document +++ b/lib/.document @@ -6,20 +6,21 @@ # But for now +English.rb abbrev.rb base64.rb benchmark.rb -cgi.rb cgi +cgi.rb complex.rb date.rb delegate.rb erb.rb -English.rb fileutils.rb find.rb forwardable.rb generator.rb +getoptlong.rb logger.rb matrix.rb observer.rb @@ -27,11 +28,13 @@ optionparser.rb pathname.rb pstore.rb rational.rb +rinda set.rb shellwords.rb singleton.rb tempfile.rb test/unit.rb +test/unit/assertions.rb thread.rb thwait.rb time.rb diff --git a/lib/test/unit/assertions.rb b/lib/test/unit/assertions.rb index 6fc00df1d3..aa97799de8 100644 --- a/lib/test/unit/assertions.rb +++ b/lib/test/unit/assertions.rb @@ -8,21 +8,39 @@ require 'test/unit/util/backtracefilter' module Test module Unit - # 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. + # + # Example: + # assert_block "Couldn't do the thing" do + # do_the_thing + # end + public def assert_block(message="assert_block failed.") # :yields: _wrap_assertion do @@ -32,7 +50,12 @@ module Test end end - # Passes if boolean is true. + ## + # Asserts that +boolean+ is not false or nil. + # + # Example: + # assert [1, 2].include?(5) + public def assert(boolean, message=nil) _wrap_assertion do @@ -41,10 +64,16 @@ module Test 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. + # + # Example: + # assert_equal 'MY STRING', 'my string'.upcase + public def assert_equal(expected, actual, message=nil) full_message = build_message(message, <= klass, "Should expect a class of exception, #{klass}") @@ -64,12 +93,19 @@ EOT end private - def _expected_exception?(actual_exception, exceptions, modules) + def _expected_exception?(actual_exception, exceptions, modules) # :nodoc: exceptions.include?(actual_exception.class) or modules.any? {|mod| actual_exception.is_a?(mod)} end - # Passes if block raises one of the given exceptions. + ## + # Passes if the block raises one of the given exceptions. + # + # Example: + # assert_raise RuntimeError, LoadError do + # raise 'Boom!!!' + # end + public def assert_raise(*args) _wrap_assertion do @@ -96,13 +132,22 @@ EOT end end - # Alias of assert_raise. Will be deprecated in 1.9, and removed in 2.0. + ## + # Alias of assert_raise. + # + # Will be deprecated in 1.9, and removed in 2.0. + public def assert_raises(*args, &block) assert_raise(*args, &block) end - # Passes if object.class == klass. + ## + # Passes if +object+ .instance_of? +klass+ + # + # Example: + # assert_instance_of String, 'foo' + public def assert_instance_of(klass, object, message="") _wrap_assertion do @@ -116,13 +161,23 @@ EOT end end - # Passes if object.nil?. + ## + # Passes if +object+ is nil. + # + # Example: + # assert_nil [1, 2].uniq! + public def assert_nil(object, message="") assert_equal(nil, object, message) end - # Passes if object.kind_of?(klass). + ## + # Passes if +object+ .kind_of? +klass+ + # + # Example: + # assert_kind_of Object, 'foo' + public def assert_kind_of(klass, object, message="") _wrap_assertion do @@ -132,7 +187,12 @@ EOT end end - # Passes if object.respond_to?(method) is true. + ## + # Passes if +object+ .respond_to? +method+ + # + # Example: + # assert_respond_to 'bugbear', :slice + public def assert_respond_to(object, method, message="") _wrap_assertion do @@ -150,7 +210,12 @@ EOT end end - # Passes if string =~ pattern. + ## + # Passes if +string+ =~ +pattern+. + # + # Example: + # assert_match(/\d+/, 'five, 6, seven') + public def assert_match(pattern, string, message="") _wrap_assertion do @@ -165,8 +230,14 @@ EOT end end - # Passes if actual.equal?(expected) (i.e. they are the - # same instance). + ## + # Passes if +actual+ .equal? +expected+ (i.e. they are the same + # instance). + # + # Example: + # o = Object.new + # assert_same o, o + public def assert_same(expected, actual, message="") full_message = build_message(message, <=, 4 + public def assert_operator(object1, operator, object2, message="") _wrap_assertion do @@ -195,7 +271,14 @@ EOT end end + ## # Passes if block does not raise an exception. + # + # Example: + # assert_nothing_raised do + # [1, 2].uniq + # end + public def assert_nothing_raised(*args) _wrap_assertion do @@ -219,13 +302,23 @@ EOT end end - # Always fails. + ## + # Flunk always fails. + # + # Example: + # 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+ + # + # Example: + # 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? + # + # Example: + # 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+ + # + # Example: + # assert_no_match(/two/, 'one 2 three') + public def assert_no_match(regexp, string, message="") _wrap_assertion do @@ -264,7 +372,14 @@ EOT UncaughtThrow = {NameError => /^uncaught throw \`(.+)\'$/, ThreadError => /^uncaught throw \`(.+)\' in thread /} #` - # Passes if block throws symbol. + ## + # Passes if the block throws +expected_symbol+ + # + # Example: + # assert_throws :done do + # throw :done + # end + public def assert_throws(expected_symbol, message="", &proc) _wrap_assertion do @@ -288,7 +403,14 @@ EOT end end + ## # Passes if block does not throw anything. + # + # Example: + # assert_nothing_thrown do + # [1, 2].uniq + # end + public def assert_nothing_thrown(message="", &proc) _wrap_assertion do @@ -306,8 +428,13 @@ EOT 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. + # + # Example: + # 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 @@ -324,7 +451,17 @@ EOT 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 receiver + # * A method + # * Arguments to the method + # + # Example: + # assert_send [[1, 2], :include?, 4] + public def assert_send(send_array, message="") _wrap_assertion do @@ -338,6 +475,10 @@ EOT 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) template &&= template.chomp @@ -360,19 +501,25 @@ EOT 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 end + # :stopdoc: + class AssertionMessage @use_pp = true class << self @@ -467,6 +614,9 @@ EOM message_parts.join("\n") end end + + # :startdoc: + end end end -- cgit v1.2.3