test-unit 2.5.5 → 3.0.0

data/lib/test/unit/assertions.rb

@@ -1,13 +1,18 @@
 # Author:: Nathaniel Talbott.
 # Copyright:: Copyright (c) 2000-2003 Nathaniel Talbott. All rights reserved.
-#             Copyright (c) 2009-2012 Kouhei Sutou. All rights reserved.
+#             Copyright (c) 2009-2013 Kouhei Sutou. All rights reserved.
 # License:: Ruby license.
 
-require 'test/unit/assertionfailederror'
+require 'test/unit/assertion-failed-error'
 require 'test/unit/util/backtracefilter'
 require 'test/unit/util/method-owner-finder'
 require 'test/unit/diff'
 
+begin
+  require 'power_assert'
+rescue LoadError, SyntaxError
+end
+
 module Test
   module Unit
 
@@ -20,11 +25,12 @@ module Test
     # 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 is easy to add your own assertions based on assert_block().
     #
-    # = Example Custom Assertion
+    # @example Example Custom Assertion
     #
     #   def deny(boolean, message = nil)
     #     message = build_message message, '<?> is not false or nil.', boolean
@@ -39,13 +45,11 @@ module Test
       # The assertion upon which all other assertions are based. Passes if the
       # block yields true.
       #
-      # Example:
+      # @example
       #   assert_block "Couldn't do the thing" do
       #     do_the_thing
       #   end
-
-      public
-      def assert_block(message="assert_block failed.") # :yields:
+      def assert_block(message="assert_block failed.")
         _wrap_assertion do
           if (! yield)
             raise AssertionFailedError.new(message.to_s)
@@ -53,34 +57,112 @@ module Test
         end
       end
 
-      ##
-      # Asserts that +boolean+ is not false or nil.
-      #
-      # Example:
-      #   assert [1, 2].include?(5)
-
-      public
-      def assert(boolean, message=nil)
+      # @private
+      NOT_SPECIFIED = Object.new
+
+      # @overload assert(object, message=nil)
+      #
+      #   Asserts that `object` is not false nor nil.
+      #
+      #   Normally, you don't need to use this assertion. Use more
+      #   specific assertions such as #assert_equal and
+      #   #assert_include.
+      #
+      #   @example Pass patterns
+      #     assert(true)               # => pass
+      #     assert([1, 2].include?(1)) # => pass
+      #
+      #   @example Failure patterns
+      #     assert(nil)                # => failure
+      #     assert(false)              # => failure
+      #     assert([1, 2].include?(5)) # => failure
+      #
+      #   @param [Object] object The check target.
+      #   @param [String] message The additional user message. It is
+      #     showed when the assertion is failed.
+      #   @return [void]
+      #
+      # @overload assert(message=nil) {}
+      #
+      #   Asserts that the givens block returns not false nor nil.
+      #
+      #   This style uses Power Assert. It means that you can see each
+      #   object values in method chains on failure. See the following
+      #   example about Power Assert.
+      #
+      #   @example Power Assert
+      #     coins = [1, 5, 50]
+      #     target_coin = 10
+      #     assert do
+      #       coins.include?(target_coin)
+      #     end
+      #     # =>
+      #     #  coins.include?(target_coin)
+      #     #  |     |        |
+      #     #  |     |        10
+      #     #  |     false
+      #     #  [1, 5, 50]
+      #
+      #   We recommend you to use Power Assert for predicate method
+      #   checks rather than existing assertions such as
+      #   #assert_include and #assert_predicate. Power Assert shows
+      #   useful message for debugging.
+      #
+      #   We don't recommend you use Power Assert for equality
+      #   check. You should use #assert_equal for the case. Because
+      #   #assert_equal shows more useful message for debugging.
+      #
+      #   @example Pass patterns
+      #     assert {true}               # => pass
+      #     assert {[1, 2].include?(1)} # => pass
+      #
+      #   @example Failure patterns
+      #     assert {nil}                # => failure
+      #     assert {false}              # => failure
+      #     assert {[1, 2].include?(5)} # => failure
+      #
+      #   @param [String] message The additional user message. It is
+      #     showed when the assertion is failed.
+      #   @yield [] Given no parameters to the block.
+      #   @yieldreturn [Object] The checked object.
+      #   @return [void]
+      def assert(object=NOT_SPECIFIED, message=nil, &block)
         _wrap_assertion do
-          assertion_message = nil
-          case message
-          when nil, String, Proc
-          when AssertionMessage
-            assertion_message = message
+          have_object = (object != NOT_SPECIFIED)
+          if block
+            message = object if have_object
+            if defined?(PowerAssert)
+              PowerAssert.start(block, assertion_method: __callee__) do |pa|
+                pa_message = AssertionMessage.delayed_literal(&pa.message_proc)
+                assertion_message = build_message(message, "?", pa_message)
+                assert_block(assertion_message) do
+                  pa.yield
+                end
+              end
+            else
+              assert(yield, message)
+            end
           else
-            error_message = "assertion message must be String, Proc or "
-            error_message << "#{AssertionMessage}: "
-            error_message << "<#{message.inspect}>(<#{message.class}>)"
-            raise ArgumentError, error_message, filter_backtrace(caller)
-          end
-          assert_block("assert should not be called with a block.") do
-            !block_given?
-          end
-          assertion_message ||= build_message(message,
-                                              "<?> is not true.",
-                                              boolean)
-          assert_block(assertion_message) do
-            boolean
+            unless have_object
+              raise ArgumentError, "wrong number of arguments (0 for 1..2)"
+            end
+            assertion_message = nil
+            case message
+            when nil, String, Proc
+            when AssertionMessage
+              assertion_message = message
+            else
+              error_message = "assertion message must be String, Proc or "
+              error_message << "#{AssertionMessage}: "
+              error_message << "<#{message.inspect}>(<#{message.class}>)"
+              raise ArgumentError, error_message, filter_backtrace(caller)
+            end
+            assertion_message ||= build_message(message,
+                                                "<?> is not true.",
+                                                object)
+            assert_block(assertion_message) do
+              object
+            end
           end
         end
       end
@@ -133,10 +215,8 @@ module Test
       # error message is generated when this one fails that tells you the
       # values of expected and actual.
       #
-      # Example:
+      # @example
       #   assert_equal 'MY STRING', 'my string'.upcase
-
-      public
       def assert_equal(expected, actual, message=nil)
         diff = AssertionMessage.delayed_diff(expected, actual)
         if expected.respond_to?(:encoding) and
@@ -169,7 +249,7 @@ EOT
       # exceptions. When an expected exception is an Exception
       # object, passes if expected_exception == actual_exception.
       #
-      # Example:
+      # @example
       #   assert_raise(RuntimeError, LoadError) do
       #     raise 'Boom!!!'
       #   end # -> pass
@@ -181,7 +261,6 @@ EOT
       #   assert_raise(RuntimeError.new("XXX")) {raise "XXX"} # -> pass
       #   assert_raise(MyError.new("XXX"))      {raise "XXX"} # -> fail
       #   assert_raise(RuntimeError.new("ZZZ")) {raise "XXX"} # -> fail
-      public
       def assert_raise(*args, &block)
         assert_expected_exception = Proc.new do |*_args|
           message, assert_exception_helper, actual_exception = _args
@@ -211,7 +290,7 @@ EOT
       # Passes if the block raises one of the given
       # exceptions or sub exceptions of the given exceptions.
       #
-      # Example:
+      # @example
       #   assert_raise_kind_of(SystemCallError) do
       #     raise Errno::EACCES
       #   end
@@ -236,49 +315,81 @@ EOT
       # an array of classes, it passes if any class
       # satisfies +object.instance_of?(class).
       #
-      # Example:
+      # @example
       #   assert_instance_of(String, 'foo')            # -> pass
       #   assert_instance_of([Fixnum, NilClass], 100)  # -> pass
       #   assert_instance_of([Numeric, NilClass], 100) # -> fail
-
-      public
       def assert_instance_of(klass, object, message="")
         _wrap_assertion do
-          klasses = nil
-          klasses = klass if klass.is_a?(Array)
+          if klass.is_a?(Array)
+            klasses = klass
+          else
+            klasses = [klass]
+          end
           assert_block("The first parameter to assert_instance_of should be " +
                        "a Class or an Array of Class.") do
-            if klasses
-              klasses.all? {|k| k.is_a?(Class)}
-            else
-              klass.is_a?(Class)
-            end
+            klasses.all? {|k| k.is_a?(Class)}
           end
           klass_message = AssertionMessage.maybe_container(klass) do |value|
             "<#{value}>"
           end
           full_message = build_message(message, <<EOT, object, klass_message, object.class)
-<?> expected to be an instance of
+<?> expected to be instance_of\\?
 ? but was
 <?>.
 EOT
           assert_block(full_message) do
-            if klasses
-              klasses.any? {|k| object.instance_of?(k)}
-            else
-              object.instance_of?(klass)
-            end
+            klasses.any? {|k| object.instance_of?(k)}
+          end
+        end
+      end
+
+      ##
+      # Passes if +object+.instance_of?(+klass+) does not hold.
+      # When +klass+ is an array of classes, it passes if no class
+      # satisfies +object.instance_of?(class).
+      #
+      # @example
+      #   assert_not_instance_of(String, 100)                # -> pass
+      #   assert_not_instance_of([Fixnum, NilClass], '100')  # -> pass
+      #   assert_not_instance_of([Numeric, NilClass], 100)   # -> fail
+      #
+      # @since 3.0.0
+      def assert_not_instance_of(klass, object, message="")
+        _wrap_assertion do
+          if klass.is_a?(Array)
+            klasses = klass
+          else
+            klasses = [klass]
+          end
+          assert_block("The first parameter to assert_not_instance_of should be " <<
+                       "a Class or an Array of Class.") do
+            klasses.all? {|k| k.is_a?(Class)}
+          end
+          klass_message = AssertionMessage.maybe_container(klass) do |value|
+            "<#{value}>"
+          end
+          full_message = build_message(message,
+                                       "<?> expected to not be instance_of\\?\n" +
+                                       "? but was.",
+                                       object,
+                                       klass_message)
+          assert_block(full_message) do
+            klasses.none? {|k| object.instance_of?(k)}
           end
         end
       end
 
+      # Just for minitest compatibility. :<
+      #
+      # @since 3.0.0
+      alias_method :refute_instance_of, :assert_not_instance_of
+
       ##
       # Passes if +object+ is nil.
       #
-      # Example:
+      # @example
       #   assert_nil [1, 2].uniq!
-
-      public
       def assert_nil(object, message="")
         full_message = build_message(message, <<EOT, object)
 <?> expected to be nil.
@@ -291,23 +402,20 @@ EOT
       # an array of classes or modules, it passes if any
       # class or module satisfies +object.kind_of?(class_or_module).
       #
-      # Example:
+      # @example
       #   assert_kind_of(Object, 'foo')                # -> pass
       #   assert_kind_of([Fixnum, NilClass], 100)      # -> pass
       #   assert_kind_of([Fixnum, NilClass], "string") # -> fail
-
-      public
       def assert_kind_of(klass, object, message="")
         _wrap_assertion do
-          klasses = nil
-          klasses = klass if klass.is_a?(Array)
+          if klass.is_a?(Array)
+            klasses = klass
+          else
+            klasses = [klass]
+          end
           assert_block("The first parameter to assert_kind_of should be " +
                        "a kind_of Module or an Array of a kind_of Module.") do
-            if klasses
-              klasses.all? {|k| k.kind_of?(Module)}
-            else
-              klass.kind_of?(Module)
-            end
+            klasses.all? {|k| k.kind_of?(Module)}
           end
           klass_message = AssertionMessage.maybe_container(klass) do |value|
             "<#{value}>"
@@ -320,22 +428,57 @@ EOT
                                        klass_message,
                                        object.class)
           assert_block(full_message) do
-            if klasses
-              klasses.any? {|k| object.kind_of?(k)}
-            else
-              object.kind_of?(klass)
-            end
+            klasses.any? {|k| object.kind_of?(k)}
+          end
+        end
+      end
+
+      ##
+      # Passes if +object+.kind_of?(+klass+) does not hold.
+      # When +klass+ is an array of classes or modules, it passes only if all
+      # classes (and modules) do not satisfy +object.kind_of?(class_or_module).
+      #
+      # @example
+      #   assert_not_kind_of(Fixnum, 'foo')           # -> pass
+      #   assert_not_kind_of([Fixnum, NilClass], '0') # -> pass
+      #   assert_not_kind_of([Fixnum, NilClass], 100) # -> fail
+      #
+      # @since 3.0.0
+      def assert_not_kind_of(klass, object, message="")
+        _wrap_assertion do
+          if klass.is_a?(Array)
+            klasses = klass
+          else
+            klasses = [klass]
+          end
+          assert_block("The first parameter to assert_not_kind_of should be " +
+                       "a kind_of Module or an Array of a kind_of Module.") do
+            klasses.all? {|k| k.kind_of?(Module)}
+          end
+          klass_message = AssertionMessage.maybe_container(klass) do |value|
+            "<#{value}>"
+          end
+          full_message = build_message(message,
+                                       "<?> expected to not be kind_of\\?\n" +
+                                       "? but was.",
+                                       object,
+                                       klass_message)
+          assert_block(full_message) do
+            klasses.none? {|k| object.kind_of?(k)}
           end
         end
       end
 
+      # Just for minitest compatibility. :<
+      #
+      # @since 3.0.0
+      alias_method :refute_kind_of, :assert_not_kind_of
+
       ##
       # Passes if +object+ .respond_to? +method+
       #
-      # Example:
+      # @example
       #   assert_respond_to 'bugbear', :slice
-
-      public
       def assert_respond_to(object, method, message="")
         _wrap_assertion do
           full_message = build_message(message,
@@ -356,11 +499,9 @@ EOT
       ##
       # Passes if +object+ does not .respond_to? +method+.
       #
-      # Example:
+      # @example
       #   assert_not_respond_to('bugbear', :nonexistence) # -> pass
       #   assert_not_respond_to('bugbear', :size)         # -> fail
-
-      public
       def assert_not_respond_to(object, method, message="")
         _wrap_assertion do
           full_message = build_message(message,
@@ -386,10 +527,8 @@ EOT
       ##
       # Passes if +string+ =~ +pattern+.
       #
-      # Example:
+      # @example
       #   assert_match(/\d+/, 'five, 6, seven')
-
-      public
       def assert_match(pattern, string, message="")
         _wrap_assertion do
           pattern = case(pattern)
@@ -407,11 +546,9 @@ EOT
       # Passes if +actual+ .equal? +expected+ (i.e. they are the same
       # instance).
       #
-      # Example:
+      # @example
       #   o = Object.new
       #   assert_same o, o
-
-      public
       def assert_same(expected, actual, message="")
         full_message = build_message(message, <<EOT, expected, expected.__id__, actual, actual.__id__)
 <?>
@@ -427,10 +564,8 @@ EOT
       #
       # Passes if object1.__send__(operator, object2) is true.
       #
-      # Example:
+      # @example
       #   assert_operator 5, :>=, 4
-
-      public
       def assert_operator(object1, operator, object2, message="")
         _wrap_assertion do
           full_message = build_message(nil, "<?>\ngiven as the operator for #assert_operator must be a Symbol or #respond_to\\?(:to_str).", operator)
@@ -444,15 +579,41 @@ EOT
         end
       end
 
+      ##
+      # Compares the +object1+ with +object2+ using +operator+.
+      #
+      # Passes if object1.__send__(operator, object2) is not true.
+      #
+      # @example
+      #   assert_not_operator(5, :<, 4) # => pass
+      #   assert_not_operator(5, :>, 4) # => fail
+      #
+      # @since 3.0.0
+      def assert_not_operator(object1, operator, object2, message="")
+        _wrap_assertion do
+          full_message = build_message(nil, "<?>\ngiven as the operator for #assert_not_operator must be a Symbol or #respond_to\\?(:to_str).", operator)
+          assert_block(full_message){operator.kind_of?(Symbol) || operator.respond_to?(:to_str)}
+          full_message = build_message(message, <<EOT, object1, AssertionMessage.literal(operator), object2)
+<?> expected to not be
+?
+<?>.
+EOT
+          assert_block(full_message) { ! object1.__send__(operator, object2) }
+        end
+      end
+
+      # Just for minitest compatibility. :<
+      #
+      # @since 3.0.0
+      alias_method :refute_operator, :assert_not_operator
+
       ##
       # Passes if block does not raise an exception.
       #
-      # Example:
+      # @example
       #   assert_nothing_raised do
       #     [1, 2].uniq
       #   end
-
-      public
       def assert_nothing_raised(*args)
         _wrap_assertion do
           if args.last.is_a?(String)
@@ -480,10 +641,8 @@ EOT
       ##
       # Flunk always fails.
       #
-      # Example:
+      # @example
       #   flunk 'Not done testing yet.'
-
-      public
       def flunk(message="Flunked")
         assert_block(build_message(message)){false}
       end
@@ -491,10 +650,8 @@ EOT
       ##
       # Passes if ! +actual+ .equal? +expected+
       #
-      # Example:
+      # @example
       #   assert_not_same Object.new, Object.new
-
-      public
       def assert_not_same(expected, actual, message="")
         full_message = build_message(message, <<EOT, expected, expected.__id__, actual, actual.__id__)
 <?>
@@ -513,10 +670,8 @@ EOT
       ##
       # Passes if +expected+ != +actual+
       #
-      # Example:
+      # @example
       #   assert_not_equal 'some string', 5
-
-      public
       def assert_not_equal(expected, actual, message="")
         full_message = build_message(message, "<?> expected to be != to\n<?>.", expected, actual)
         assert_block(full_message) { expected != actual }
@@ -530,10 +685,8 @@ EOT
       ##
       # Passes if ! +object+ .nil?
       #
-      # Example:
+      # @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?}
@@ -547,11 +700,9 @@ EOT
       ##
       # Passes if +regexp+ !~ +string+
       #
-      # Example:
+      # @example
       #   assert_not_match(/two/, 'one 2 three')   # -> pass
       #   assert_not_match(/three/, 'one 2 three') # -> fail
-
-      public
       def assert_not_match(regexp, string, message="")
         _wrap_assertion do
           assert_instance_of(Regexp, regexp,
@@ -574,11 +725,9 @@ EOT
       #
       # Passes if +regexp+ !~ +string+
       #
-      # Example:
+      # @example
       #   assert_no_match(/two/, 'one 2 three')   # -> pass
       #   assert_no_match(/three/, 'one 2 three') # -> fail
-
-      public
       def assert_no_match(regexp, string, message="")
         _wrap_assertion do
           assert_instance_of(Regexp, regexp,
@@ -588,21 +737,20 @@ EOT
         end
       end
 
+      # @private
       UncaughtThrow = {
-        NameError => /^uncaught throw \`(.+)\'$/, #`
-        ArgumentError => /^uncaught throw (.+)$/,
-        ThreadError => /^uncaught throw \`(.+)\' in thread / #`
+        NameError => /^uncaught throw `(.+)'$/,
+        ArgumentError => /^uncaught throw (`.+'|.+)$/,
+        ThreadError => /^uncaught throw `(.+)' in thread /,
       }
 
       ##
       # Passes if the block throws +expected_object+
       #
-      # Example:
+      # @example
       #   assert_throw(:done) do
       #     throw(:done)
       #   end
-
-      public
       def assert_throw(expected_object, message="", &proc)
         _wrap_assertion do
           begin
@@ -626,8 +774,7 @@ EOT
             assert_block(full_message) {caught}
           rescue NameError, ArgumentError, ThreadError => error
             raise unless UncaughtThrow[error.class] =~ error.message
-            tag = $1
-            tag = tag[1..-1].intern if tag[0, 1] == ":"
+            tag = AssertionMessage.normalize_tag($1)
             full_message = build_message(message,
                                          "<?> expected to be thrown but\n" +
                                          "<?> was thrown.",
@@ -645,12 +792,10 @@ EOT
       ##
       # Passes if block does not throw anything.
       #
-      # Example:
+      # @example
       #  assert_nothing_thrown do
       #    [1, 2].uniq
       #  end
-
-      public
       def assert_nothing_thrown(message="", &proc)
         _wrap_assertion do
           assert(block_given?, "Should have passed a block to assert_nothing_thrown")
@@ -658,8 +803,7 @@ EOT
             proc.call
           rescue NameError, ArgumentError, ThreadError => error
             raise unless UncaughtThrow[error.class] =~ error.message
-            tag = $1
-            tag = tag[1..-1].intern if tag[0, 1] == ":"
+            tag = AssertionMessage.normalize_tag($1)
             full_message = build_message(message,
                                          "<?> was thrown when nothing was expected",
                                          tag)
@@ -673,10 +817,8 @@ EOT
       # Passes if +expected_float+ and +actual_float+ are equal
       # within +delta+ tolerance.
       #
-      # Example:
+      # @example
       #   assert_in_delta 0.05, (50000.0 / 10**6), 0.00001
-
-      public
       def assert_in_delta(expected_float, actual_float, delta=0.001, message="")
         _wrap_assertion do
           _assert_in_delta_validate_arguments(expected_float,
@@ -696,11 +838,9 @@ EOT
       # Passes if +expected_float+ and +actual_float+ are
       # not equal within +delta+ tolerance.
       #
-      # Example:
+      # @example
       #   assert_not_in_delta(0.05, (50000.0 / 10**6), 0.00002) # -> pass
       #   assert_not_in_delta(0.05, (50000.0 / 10**6), 0.00001) # -> fail
-
-      public
       def assert_not_in_delta(expected_float, actual_float, delta=0.001, message="")
         _wrap_assertion do
           _assert_in_delta_validate_arguments(expected_float,
@@ -722,7 +862,6 @@ EOT
       # @since 2.5.3
       alias_method :refute_in_delta, :assert_not_in_delta
 
-      # :stopdoc:
       private
       def _assert_in_delta_validate_arguments(expected_float,
                                               actual_float,
@@ -795,17 +934,13 @@ EOT
       end
 
       public
-      # :startdoc:
-
       ##
       # Passes if +expected_float+ and +actual_float+ are equal
       # within +epsilon+ relative error of +expected_float+.
       #
-      # Example:
+      # @example
       #   assert_in_epsilon(10000.0, 9900.0, 0.1) # -> pass
       #   assert_in_epsilon(10000.0, 9899.0, 0.1) # -> fail
-
-      public
       def assert_in_epsilon(expected_float, actual_float, epsilon=0.001,
                             message="")
         _wrap_assertion do
@@ -834,11 +969,9 @@ EOT
       # not equal within +epsilon+ relative error of
       # +expected_float+.
       #
-      # Example:
+      # @example
       #   assert_not_in_epsilon(10000.0, 9900.0, 0.1) # -> fail
       #   assert_not_in_epsilon(10000.0, 9899.0, 0.1) # -> pass
-
-      public
       def assert_not_in_epsilon(expected_float, actual_float, epsilon=0.001,
                                 message="")
         _wrap_assertion do
@@ -858,7 +991,11 @@ EOT
         end
       end
 
-      # :stopdoc:
+      # Just for minitest compatibility. :<
+      #
+      # @since 3.0.0
+      alias_method :refute_in_epsilon, :assert_not_in_epsilon
+
       private
       def _assert_in_epsilon_validate_arguments(expected_float,
                                                 actual_float,
@@ -935,8 +1072,6 @@ EOT
       end
 
       public
-      # :startdoc:
-
       ##
       # Passes if the method send returns a true value.
       #
@@ -945,11 +1080,9 @@ EOT
       # * A method
       # * Arguments to the method
       #
-      # Example:
+      # @example
       #   assert_send([[1, 2], :member?, 1]) # -> pass
       #   assert_send([[1, 2], :member?, 4]) # -> fail
-
-      public
       def assert_send(send_array, message=nil)
         _wrap_assertion do
           assert_instance_of(Array, send_array,
@@ -987,7 +1120,7 @@ EOT
       # * A method
       # * Arguments to the method
       #
-      # Example:
+      # @example
       #   assert_not_send([[1, 2], :member?, 1]) # -> fail
       #   assert_not_send([[1, 2], :member?, 4]) # -> pass
       def assert_not_send(send_array, message=nil)
@@ -1022,7 +1155,7 @@ EOT
       ##
       # Passes if +actual+ is a boolean value.
       #
-      # Example:
+      # @example
       #   assert_boolean(true) # -> pass
       #   assert_boolean(nil)  # -> fail
       def assert_boolean(actual, message=nil)
@@ -1038,7 +1171,7 @@ EOT
       ##
       # Passes if +actual+ is true.
       #
-      # Example:
+      # @example
       #   assert_true(true)  # -> pass
       #   assert_true(:true) # -> fail
       def assert_true(actual, message=nil)
@@ -1054,7 +1187,7 @@ EOT
       ##
       # Passes if +actual+ is false.
       #
-      # Example:
+      # @example
       #   assert_false(false)  # -> pass
       #   assert_false(nil)    # -> fail
       def assert_false(actual, message=nil)
@@ -1071,7 +1204,7 @@ EOT
       # Passes if expression "+expected+ +operator+
       # +actual+" is true.
       #
-      # Example:
+      # @example
       #   assert_compare(1, "<", 10)  # -> pass
       #   assert_compare(1, ">=", 10) # -> fail
       def assert_compare(expected, operator, actual, message=nil)
@@ -1104,7 +1237,7 @@ EOT
       ##
       # Passes if assertion is failed in block.
       #
-      # Example:
+      # @example
       #   assert_fail_assertion {assert_equal("A", "B")}  # -> pass
       #   assert_fail_assertion {assert_equal("A", "A")}  # -> fail
       def assert_fail_assertion(message=nil)
@@ -1126,7 +1259,7 @@ EOT
       # Passes if an exception is raised in block and its
       # message is +expected+.
       #
-      # Example:
+      # @example
       #   assert_raise_message("exception") {raise "exception"}  # -> pass
       #   assert_raise_message(/exc/i) {raise "exception"}       # -> pass
       #   assert_raise_message("exception") {raise "EXCEPTION"}  # -> fail
@@ -1166,7 +1299,7 @@ EOT
       ##
       # Passes if +object+.const_defined?(+constant_name+)
       #
-      # Example:
+      # @example
       #   assert_const_defined(Test, :Unit)          # -> pass
       #   assert_const_defined(Object, :Nonexistent) # -> fail
       def assert_const_defined(object, constant_name, message=nil)
@@ -1183,7 +1316,7 @@ EOT
       ##
       # Passes if !+object+.const_defined?(+constant_name+)
       #
-      # Example:
+      # @example
       #   assert_not_const_defined(Object, :Nonexistent) # -> pass
       #   assert_not_const_defined(Test, :Unit)          # -> fail
       def assert_not_const_defined(object, constant_name, message=nil)
@@ -1200,7 +1333,7 @@ EOT
       ##
       # Passes if +object+.+predicate+ is _true_.
       #
-      # Example:
+      # @example
       #   assert_predicate([], :empty?)  # -> pass
       #   assert_predicate([1], :empty?) # -> fail
       def assert_predicate(object, predicate, message=nil)
@@ -1222,7 +1355,7 @@ EOT
       ##
       # Passes if +object+.+predicate+ is not _true_.
       #
-      # Example:
+      # @example
       #   assert_not_predicate([1], :empty?) # -> pass
       #   assert_not_predicate([], :empty?)  # -> fail
       def assert_not_predicate(object, predicate, message=nil)
@@ -1241,11 +1374,16 @@ EOT
         end
       end
 
+      # Just for minitest compatibility. :<
+      #
+      # @since 3.0.0
+      alias_method :refute_predicate, :assert_not_predicate
+
       ##
       # Passes if +object+#+alias_name+ is an alias method of
       # +object+#+original_name+.
       #
-      # Example:
+      # @example
       #   assert_alias_method([], :length, :size)  # -> pass
       #   assert_alias_method([], :size, :length)  # -> pass
       #   assert_alias_method([], :each, :size)    # -> fail
@@ -1292,7 +1430,7 @@ EOT
       ##
       # Passes if +path+ exists.
       #
-      # Example:
+      # @example
       #   assert_path_exist("/tmp")          # -> pass
       #   assert_path_exist("/bin/sh")       # -> pass
       #   assert_path_exist("/nonexistent")  # -> fail
@@ -1310,7 +1448,7 @@ EOT
       ##
       # Passes if +path+ doesn't exist.
       #
-      # Example:
+      # @example
       #   assert_path_not_exist("/nonexistent")  # -> pass
       #   assert_path_not_exist("/tmp")          # -> fail
       #   assert_path_not_exist("/bin/sh")       # -> fail
@@ -1328,7 +1466,7 @@ EOT
       ##
       # Passes if +collection+ includes +object+.
       #
-      # Example:
+      # @example
       #   assert_include([1, 10], 1)            # -> pass
       #   assert_include(1..10, 5)              # -> pass
       #   assert_include([1, 10], 5)            # -> fail
@@ -1355,7 +1493,7 @@ EOT
       ##
       # Passes if +collection+ doesn't include +object+.
       #
-      # Example:
+      # @example
       #   assert_not_include([1, 10], 5)            # -> pass
       #   assert_not_include(1..10, 20)             # -> pass
       #   assert_not_include([1, 10], 1)            # -> fail
@@ -1374,10 +1512,20 @@ EOT
         end
       end
 
+      # Just for minitest compatibility. :<
+      #
+      # @since 3.0.0
+      alias_method :assert_not_includes, :assert_not_include
+
+      # Just for minitest compatibility. :<
+      #
+      # @since 3.0.0
+      alias_method :refute_includes, :assert_not_include
+
       ##
       # Passes if +object+ is empty.
       #
-      # Example:
+      # @example
       #   assert_empty("")                       # -> pass
       #   assert_empty([])                       # -> pass
       #   assert_empty({})                       # -> pass
@@ -1400,7 +1548,7 @@ EOT
       ##
       # Passes if +object+ is not empty.
       #
-      # Example:
+      # @example
       #   assert_not_empty(" ")                      # -> pass
       #   assert_not_empty([nil])                    # -> pass
       #   assert_not_empty({1 => 2})                 # -> pass
@@ -1420,11 +1568,14 @@ EOT
         end
       end
 
+      # Just for minitest compatibility. :<
+      #
+      # @since 3.0.0
+      alias_method :refute_empty, :assert_not_empty
+
       ##
       # 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
         return AssertionMessage.new(head, template, arguments)
@@ -1460,13 +1611,10 @@ EOT
       ##
       # 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:
       private
       def _assert_raise(assert_expected_exception, *args, &block)
         _wrap_assertion do
@@ -1497,7 +1645,6 @@ EOT
         end
       end
 
-      private
       def _set_failed_information(failure, expected, actual, user_message)
         failure.expected = expected
         failure.actual = actual
@@ -1523,6 +1670,19 @@ EOT
             MaybeContainer.new(value, &formatter)
           end
 
+          def normalize_tag(tag)
+            case tag
+            when /\A:/
+              tag[1..-1].intern
+            when /\A`(.+)'\z/
+              $1.intern
+            when String
+              tag.intern
+            else
+              tag
+            end
+          end
+
           MAX_DIFF_TARGET_STRING_SIZE = 1000
           def max_diff_target_string_size
             return @@max_diff_target_string_size if @@max_diff_target_string_size
@@ -1680,6 +1840,33 @@ EOT
           end
         end
 
+        class NumericInspector
+          Inspector.register_inspector_class(self)
+
+          class << self
+            def target?(object)
+              object.is_a?(Numeric)
+            end
+          end
+
+          def initialize(numeric, inspected_objects)
+            @inspected_objects = inspected_objects
+            @numeric = numeric
+          end
+
+          def inspect
+            @numeric.to_s
+          end
+
+          def pretty_print(q)
+            q.text(@numeric.to_s)
+          end
+
+          def pretty_print_cycle(q)
+            q.text(@numeric.to_s)
+          end
+        end
+
         class HashInspector
           Inspector.register_inspector_class(self)