Module Test::Unit::Assertions
In: lib/test/unit/assertions.rb

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 is easy to add your own assertions based on assert_block().

@example 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

Methods

Classes and Modules

Class Test::Unit::Assertions::AssertExceptionHelper
Class Test::Unit::Assertions::AssertionMessage
Class Test::Unit::Assertions::ThrowTagExtractor

Constants

NOT_SPECIFIED = Object.new   @private

Public Class methods

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 Instance methods

Called whenever an assertion is made. Define this in classes that include Test::Unit::Assertions to record assertion counts.

This is a public API for developers who extend test-unit.

@return [void]

@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]

Passes if object#alias_name is an alias method of object#original_name.

@example

  assert_alias_method([], :length, :size)  # -> pass
  assert_alias_method([], :size, :length)  # -> pass
  assert_alias_method([], :each, :size)    # -> fail

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

Passes if actual is a boolean value.

@example

  assert_boolean(true) # -> pass
  assert_boolean(nil)  # -> fail

Passes if expression "expected operator actual" is true.

@example

  assert_compare(1, "<", 10)  # -> pass
  assert_compare(1, ">=", 10) # -> fail

Passes if object.const_defined?(constant_name)

@example

  assert_const_defined(Test, :Unit)          # -> pass
  assert_const_defined(Object, :Nonexistent) # -> fail

Passes if object is empty.

@example

  assert_empty("")                       # -> pass
  assert_empty([])                       # -> pass
  assert_empty({})                       # -> pass
  assert_empty(" ")                      # -> fail
  assert_empty([nil])                    # -> fail
  assert_empty({1 => 2})                 # -> fail

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

Passes if assertion is failed in block.

@example

  assert_fail_assertion {assert_equal("A", "B")}  # -> pass
  assert_fail_assertion {assert_equal("A", "A")}  # -> fail

Passes if actual is false.

@example

  assert_false(false)  # -> pass
  assert_false(nil)    # -> fail

Passes if expected_float and actual_float are equal within delta tolerance.

@example

  assert_in_delta 0.05, (50000.0 / 10**6), 0.00001

Passes if expected_float and actual_float are equal within epsilon relative error of expected_float.

@example

  assert_in_epsilon(10000.0, 9900.0, 0.1) # -> pass
  assert_in_epsilon(10000.0, 9899.0, 0.1) # -> fail

Passes if collection includes object.

@example

  assert_include([1, 10], 1)            # -> pass
  assert_include(1..10, 5)              # -> pass
  assert_include([1, 10], 5)            # -> fail
  assert_include(1..10, 20)             # -> fail
assert_includes(collection, object, message=nil)

Alias for assert_include

Passes if object.instance_of?(klass). When klass is an array of classes, it passes if any class satisfies +object.instance_of?(class).

@example

  assert_instance_of(String, 'foo')            # -> pass
  assert_instance_of([Fixnum, NilClass], 100)  # -> pass
  assert_instance_of([Numeric, NilClass], 100) # -> fail

Passes if object.kind_of?(klass). When klass is an array of classes or modules, it passes if any class or module satisfies +object.kind_of?(class_or_module).

@example

  assert_kind_of(Object, 'foo')                # -> pass
  assert_kind_of([Fixnum, NilClass], 100)      # -> pass
  assert_kind_of([Fixnum, NilClass], "string") # -> fail

Passes if pattern =~ string.

@example

  assert_match(/\d+/, 'five, 6, seven')

Passes if object is nil.

@example

  assert_nil [1, 2].uniq!

Deprecated. Use assert_not_match instead.

Passes if regexp !~ string

@example

  assert_no_match(/two/, 'one 2 three')   # -> pass
  assert_no_match(/three/, 'one 2 three') # -> fail

Passes if !object.const_defined?(constant_name)

@example

  assert_not_const_defined(Object, :Nonexistent) # -> pass
  assert_not_const_defined(Test, :Unit)          # -> fail

Passes if object is not empty.

@example

  assert_not_empty(" ")                      # -> pass
  assert_not_empty([nil])                    # -> pass
  assert_not_empty({1 => 2})                 # -> pass
  assert_not_empty("")                       # -> fail
  assert_not_empty([])                       # -> fail
  assert_not_empty({})                       # -> fail

Passes if expected != actual

@example

  assert_not_equal 'some string', 5

Passes if expected_float and actual_float are not equal within delta tolerance.

@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

Passes if expected_float and actual_float are not equal within epsilon relative error of expected_float.

@example

  assert_not_in_epsilon(10000.0, 9900.0, 0.1) # -> fail
  assert_not_in_epsilon(10000.0, 9899.0, 0.1) # -> pass

Passes if collection doesn‘t include object.

@example

  assert_not_include([1, 10], 5)            # -> pass
  assert_not_include(1..10, 20)             # -> pass
  assert_not_include([1, 10], 1)            # -> fail
  assert_not_include(1..10, 5)              # -> fail
assert_not_includes(collection, object, message=nil)

Alias for assert_not_include

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

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

Passes if regexp !~ string

@example

  assert_not_match(/two/, 'one 2 three')   # -> pass
  assert_not_match(/three/, 'one 2 three') # -> fail

Passes if ! object .nil?

@example

  assert_not_nil '1 two 3'.sub!(/two/, '2')

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

Passes if object.predicate is not true.

@example

  assert_not_predicate([1], :empty?) # -> pass
  assert_not_predicate([], :empty?)  # -> fail

Passes if object does not .respond_to? method.

@example

  assert_not_respond_to('bugbear', :nonexistence) # -> pass
  assert_not_respond_to('bugbear', :size)         # -> fail

Passes if ! actual .equal? expected

@example

  assert_not_same Object.new, Object.new

Passes if the method send doesn‘t return a true value.

send_array is composed of:

  • A receiver
  • A method
  • Arguments to the method

@example

  assert_not_send([[1, 2], :member?, 1]) # -> fail
  assert_not_send([[1, 2], :member?, 4]) # -> pass

Passes if block does not raise an exception.

@example

  assert_nothing_raised do
    [1, 2].uniq
  end

Passes if block does not throw anything.

@example

 assert_nothing_thrown do
   [1, 2].uniq
 end

Compares the +object1+ with +object2+ using operator.

Passes if object1.send(operator, object2) is true.

@example

  assert_operator 5, :>=, 4

Passes if path exists.

@example

  assert_path_exist("/tmp")          # -> pass
  assert_path_exist("/bin/sh")       # -> pass
  assert_path_exist("/nonexistent")  # -> fail

Passes if path doesn‘t exist.

@example

  assert_path_not_exist("/nonexistent")  # -> pass
  assert_path_not_exist("/tmp")          # -> fail
  assert_path_not_exist("/bin/sh")       # -> fail

Passes if object.predicate is true.

@example

  assert_predicate([], :empty?)  # -> pass
  assert_predicate([1], :empty?) # -> fail

Passes if the block raises one of the expected exceptions. When an expected exception is an Exception object, passes if expected_exception == actual_exception.

@example

  assert_raise(RuntimeError, LoadError) do
    raise 'Boom!!!'
  end # -> pass

  assert_raise do
    raise Exception, 'Any exception should be raised!!!'
  end # -> pass

  assert_raise(RuntimeError.new("XXX")) {raise "XXX"} # -> pass
  assert_raise(MyError.new("XXX"))      {raise "XXX"} # -> fail
  assert_raise(RuntimeError.new("ZZZ")) {raise "XXX"} # -> fail

Passes if the block raises one of the given exceptions or sub exceptions of the given exceptions.

@example

  assert_raise_kind_of(SystemCallError) do
    raise Errno::EACCES
  end

Passes if an exception is raised in block and its message is expected.

@example

  assert_raise_message("exception") {raise "exception"}  # -> pass
  assert_raise_message(/exc/i) {raise "exception"}       # -> pass
  assert_raise_message("exception") {raise "EXCEPTION"}  # -> fail
  assert_raise_message("exception") {}                   # -> fail
assert_raises(*args, &block)

Alias for assert_raise

Passes if object .respond_to? method

@example

  assert_respond_to 'bugbear', :slice

Passes if actual .equal? expected (i.e. they are the same instance).

@example

  o = Object.new
  assert_same o, o

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], :member?, 1]) # -> pass
  assert_send([[1, 2], :member?, 4]) # -> fail

Passes if the block throws expected_object

@example

  assert_throw(:done) do
    throw(:done)
  end
assert_throws(expected_object, message="", &proc)

Alias for assert_throw

Passes if actual is true.

@example

  assert_true(true)  # -> pass
  assert_true(:true) # -> fail

Builds a failure message. head is added before the template and arguments replaces the ’?’s positionally in the template.

Flunk always fails.

@example

  flunk 'Not done testing yet.'

Asserts that object is false or nil.

@note Just for minitest compatibility. :<

@param [Object] object The object to be asserted. @return [void]

@example Pass patterns

  refute(false)    # => pass
  refute(nil)      # => pass

@example Failure patterns

  refute(true)     # => failure
  refute("string") # => failure

@since 2.5.3

refute_empty(object, message=nil)

Alias for assert_not_empty

refute_equal(expected, actual, message="")

Alias for assert_not_equal

refute_in_delta(expected_float, actual_float, delta=0.001, message="")
refute_in_epsilon(expected_float, actual_float, epsilon=0.001, message="")
refute_includes(collection, object, message=nil)

Alias for assert_not_include

refute_instance_of(klass, object, message="")
refute_kind_of(klass, object, message="")

Alias for assert_not_kind_of

refute_match(regexp, string, message="")

Alias for assert_not_match

refute_nil(object, message="")

Alias for assert_not_nil

refute_operator(object1, operator, object2, message="")
refute_predicate(object, predicate, message=nil)
refute_respond_to(object, method, message="")
refute_same(expected, actual, message="")

Alias for assert_not_same

[Validate]