Module: Test::Unit::Assertions

Included in:
TestCase
Defined in:
lib/test/unit/assertions.rb

Overview

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

Defined Under Namespace

Classes: AssertExceptionHelper, AssertionMessage

Constant Summary collapse

UncaughtThrow = 
{
  NameError => /^uncaught throw \`(.+)\'$/,
  ArgumentError => /^uncaught throw (.+)$/,
  ThreadError => /^uncaught throw \`(.+)\' in thread /
}

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.use_pp=(value) ⇒ Object 



734
735
736
 
# File 'lib/test/unit/assertions.rb', line 734

def self.use_pp=(value)
  AssertionMessage.use_pp = value
end

Instance Method Details

#assert(boolean, message = nil) ⇒ Object 



61
62
63
64
65
66
 
# File 'lib/test/unit/assertions.rb', line 61

def assert(boolean, message=nil)
  _wrap_assertion do
    assert_block("assert should not be called with a block.") { !block_given? }
    assert_block(build_message(message, "<?> is not true.", boolean)) { boolean }
  end
end

#assert_block(message = "assert_block failed.") ⇒ Object

:yields:



46
47
48
49
50
51
52
 
# File 'lib/test/unit/assertions.rb', line 46

def assert_block(message="assert_block failed.") # :yields: 
  _wrap_assertion do
    if (! yield)
      raise AssertionFailedError.new(message.to_s)
    end
  end
end

#assert_boolean(actual, message = nil) ⇒ Object

Passes if actual is a boolean value.

Example:

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



523
524
525
526
527
528
529
530
531
 
# File 'lib/test/unit/assertions.rb', line 523

def assert_boolean(actual, message=nil)
  _wrap_assertion do
    assert_block(build_message(message,
                               "<true> or <false> expected but was\n<?>",
                               actual)) do
      [true, false].include?(actual)
    end
  end
end

#assert_compare(expected, operator, actual, message = nil) ⇒ Object

Passes if expression “expected operator actual” is true.

Example:

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



572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
 
# File 'lib/test/unit/assertions.rb', line 572

def assert_compare(expected, operator, actual, message=nil)
  _wrap_assertion do
    assert_send([["<", "<=", ">", ">="], :include?, operator.to_s])
    case operator.to_s
    when "<"
      operator_description = "less than"
    when "<="
      operator_description = "less than or equal to"
    when ">"
      operator_description = "greater than"
    when ">="
      operator_description = "greater than or equal to"
    end
    template = <<-EOT
<?> #{operator} <?> should be true
<?> expected #{operator_description}
<?>.
EOT
    full_message = build_message(message, template,
                                 expected, actual,
                                 expected, actual)
    assert_block(full_message) do
      expected.send(operator, actual)
    end
  end
end

#assert_const_defined(object, constant_name, message = nil) ⇒ Object

Passes if object.const_defined?(constant_name)

Example:

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



667
668
669
670
671
672
673
674
675
676
 
# File 'lib/test/unit/assertions.rb', line 667

def assert_const_defined(object, constant_name, message=nil)
  _wrap_assertion do
    full_message = build_message(message,
                                 "<?>.const_defined\\?(<?>) expected.",
                                 object, constant_name)
    assert_block(full_message) do
      object.const_defined?(constant_name)
    end
  end
end

#assert_equal(expected, actual, message = nil) ⇒ Object 



79
80
81
82
83
84
85
86
 
# File 'lib/test/unit/assertions.rb', line 79

def assert_equal(expected, actual, message=nil)
  diff = AssertionMessage.delayed_diff(expected, actual)
  full_message = build_message(message, <<EOT, expected, actual, diff)
<?> expected but was
<?>.?
EOT
  assert_block(full_message) { expected == actual }
end

#assert_fail_assertion(message = nil) ⇒ Object

Passes if assertion is failed in block.

Example:

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



605
606
607
608
609
610
611
612
613
614
615
616
617
618
 
# File 'lib/test/unit/assertions.rb', line 605

def assert_fail_assertion(message=nil)
  _wrap_assertion do
    full_message = build_message(message,
                                 "Failed assertion was expected.")
    assert_block(full_message) do
      begin
        yield
        false
      rescue AssertionFailedError
        true
      end
    end
  end
end

#assert_false(actual, message = nil) ⇒ Object

Passes if actual is false.

Example:

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



555
556
557
558
559
560
561
562
563
 
# File 'lib/test/unit/assertions.rb', line 555

def assert_false(actual, message=nil)
  _wrap_assertion do
    assert_block(build_message(message,
                               "<false> expected but was\n<?>",
                               actual)) do
      actual == false
    end
  end
end

#assert_in_delta(expected_float, actual_float, delta, message = "") ⇒ Object 



478
479
480
481
482
483
484
485
486
487
488
489
490
491
 
# File 'lib/test/unit/assertions.rb', line 478

def assert_in_delta(expected_float, actual_float, delta, message="")
  _wrap_assertion do
    {expected_float => "first float", actual_float => "second float", delta => "delta"}.each do |float, name|
      assert_respond_to(float, :to_f, "The arguments must respond to to_f; the #{name} did not")
    end
    assert_operator(delta, :>=, 0.0, "The delta should not be negative")
    full_message = build_message(message, <<EOT, expected_float, actual_float, delta)
<?> and
<?> expected to be within
<?> of each other.
EOT
    assert_block(full_message) { (expected_float.to_f - actual_float.to_f).abs <= delta.to_f }
  end
end

#assert_instance_of(klass, object, message = "") ⇒ Object 



161
162
163
164
165
166
167
168
169
170
171
 
# File 'lib/test/unit/assertions.rb', line 161

def assert_instance_of(klass, object, message="")
  _wrap_assertion do
    assert_equal(Class, klass.class, "assert_instance_of takes a Class as its first argument")
    full_message = build_message(message, <<EOT, object, klass, object.class)
<?> expected to be an instance of
<?> but was
<?>.
EOT
    assert_block(full_message){object.instance_of?(klass)}
  end
end

#assert_kind_of(klass, object, message = "") ⇒ Object 



194
195
196
197
198
199
200
 
# File 'lib/test/unit/assertions.rb', line 194

def assert_kind_of(klass, object, message="")
  _wrap_assertion do
    assert(klass.kind_of?(Module), "The first parameter to assert_kind_of should be a kind_of Module.")
    full_message = build_message(message, "<?>\nexpected to be kind_of\\?\n<?> but was\n<?>.", object, klass, object.class)
    assert_block(full_message){object.kind_of?(klass)}
  end
end

#assert_match(pattern, string, message = "") ⇒ Object 



232
233
234
235
236
237
238
239
240
241
242
243
 
# File 'lib/test/unit/assertions.rb', line 232

def assert_match(pattern, string, message="")
  _wrap_assertion do
    pattern = case(pattern)
      when String
        Regexp.new(Regexp.escape(pattern))
      else
        pattern
    end
    full_message = build_message(message, "<?> expected to be =~\n<?>.", string, pattern)
    assert_block(full_message) { string =~ pattern }
  end
end

#assert_nil(object, message = "") ⇒ Object 



180
181
182
183
184
185
 
# File 'lib/test/unit/assertions.rb', line 180

def assert_nil(object, message="")
  full_message = build_message(message, <<EOT, object)
<?> expected to be nil.
EOT
  assert_block(full_message) { object.nil? }
end

#assert_no_match(regexp, string, message = "") ⇒ Object 



378
379
380
381
382
383
384
 
# File 'lib/test/unit/assertions.rb', line 378

def assert_no_match(regexp, string, message="")
  _wrap_assertion do
    assert_instance_of(Regexp, regexp, "The first argument to assert_no_match should be a Regexp.")
    full_message = build_message(message, "<?> expected to not match\n<?>.", regexp, string)
    assert_block(full_message) { regexp !~ string }
  end
end

#assert_not_const_defined(object, constant_name, message = nil) ⇒ Object

Passes if !object.const_defined?(constant_name)

Example:

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



684
685
686
687
688
689
690
691
692
693
 
# File 'lib/test/unit/assertions.rb', line 684

def assert_not_const_defined(object, constant_name, message=nil)
  _wrap_assertion do
    full_message = build_message(message,
                                 "!<?>.const_defined\\?(<?>) expected.",
                                 object, constant_name)
    assert_block(full_message) do
      !object.const_defined?(constant_name)
    end
  end
end

#assert_not_equal(expected, actual, message = "") ⇒ Object 



354
355
356
357
 
# File 'lib/test/unit/assertions.rb', line 354

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 }
end

#assert_not_nil(object, message = "") ⇒ Object 



366
367
368
369
 
# File 'lib/test/unit/assertions.rb', line 366

def assert_not_nil(object, message="")
  full_message = build_message(message, "<?> expected to not be nil.", object)
  assert_block(full_message){!object.nil?}
end

#assert_not_same(expected, actual, message = "") ⇒ Object 



337
338
339
340
341
342
343
344
345
 
# File 'lib/test/unit/assertions.rb', line 337

def assert_not_same(expected, actual, message="")
  full_message = build_message(message, <<EOT, expected, expected.__id__, actual, actual.__id__)
<?>
with id <?> expected to not be equal\\? to
<?>
with id <?>.
EOT
  assert_block(full_message) { !actual.equal?(expected) }
end

#assert_nothing_raised(*args) ⇒ Object 



295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
 
# File 'lib/test/unit/assertions.rb', line 295

def assert_nothing_raised(*args)
  _wrap_assertion do
    if args.last.is_a?(String)
      message = args.pop
    else
      message = ""
    end

    assert_exception_helper = AssertExceptionHelper.new(self, args)
    begin
      yield
    rescue Exception => e
      if ((args.empty? && !e.instance_of?(AssertionFailedError)) ||
          assert_exception_helper.expected?(e))
        failure_message = build_message(message, "Exception raised:\n?", e)
        assert_block(failure_message) {false}
      else
        raise
      end
    end
    nil
  end
end

#assert_nothing_thrown(message = "", &proc) ⇒ Object 



452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
 
# File 'lib/test/unit/assertions.rb', line 452

def assert_nothing_thrown(message="", &proc)
  _wrap_assertion do
    assert(block_given?, "Should have passed a block to assert_nothing_thrown")
    begin
      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] == ":"
      full_message = build_message(message,
                                   "<?> was thrown when nothing was expected",
                                   tag)
      flunk(full_message)
    end
    assert(true, "Expected nothing to be thrown")
  end
end

#assert_operator(object1, operator, object2, message = "") ⇒ Object 



273
274
275
276
277
278
279
280
281
282
283
284
 
# File 'lib/test/unit/assertions.rb', line 273

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)
    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 be
?
<?>.
EOT
    assert_block(full_message) { object1.__send__(operator, object2) }
  end
end

#assert_raise(*args, &block) ⇒ Object 



106
107
108
109
110
111
112
113
114
115
116
117
118
 
# File 'lib/test/unit/assertions.rb', line 106

def assert_raise(*args, &block)
  assert_expected_exception = Proc.new do |*_args|
    message, assert_exception_helper, actual_exception = _args
    expected = assert_exception_helper.expected_exceptions
    full_message = build_message(message,
                                 "<?> exception expected but was\n?",
                                 expected, actual_exception)
    assert_block(full_message) do
      expected == [] or assert_exception_helper.expected?(actual_exception)
    end
  end
  _assert_raise(assert_expected_exception, *args, &block)
end

#assert_raise_kind_of(*args, &block) ⇒ Object

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



138
139
140
141
142
143
144
145
146
147
148
149
150
151
 
# File 'lib/test/unit/assertions.rb', line 138

def assert_raise_kind_of(*args, &block)
  assert_expected_exception = Proc.new do |*_args|
    message, assert_exception_helper, actual_exception = _args
    expected = assert_exception_helper.expected_exceptions
    full_message = build_message(message,
                                 "<?> family exception expected " +
                                 "but was\n?",
                                 expected, actual_exception)
    assert_block(full_message) do
      assert_exception_helper.expected?(actual_exception, :kind_of?)
    end
  end
  _assert_raise(assert_expected_exception, *args, &block)
end

#assert_raise_message(expected, message = nil) ⇒ Object

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



629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
 
# File 'lib/test/unit/assertions.rb', line 629

def assert_raise_message(expected, message=nil)
  _wrap_assertion do
    full_message = build_message(message,
                                 "<?> exception message expected " +
                                 "but none was thrown.",
                                 expected)
    exception = nil
    assert_block(full_message) do
      begin
        yield
        false
      rescue Exception => exception
        true
      end
    end

    actual = exception.message
    diff = AssertionMessage.delayed_diff(expected, actual)
    full_message =
      build_message(message,
                    "<?> exception message expected but was\n" +
                    "<?>.?", expected, actual, diff)
    assert_block(full_message) do
      if expected.is_a?(Regexp)
        expected =~ actual
      else
        expected == actual
      end
    end
  end
end

#assert_raises(*args, &block) ⇒ Object 



126
127
128
 
# File 'lib/test/unit/assertions.rb', line 126

def assert_raises(*args, &block)
  assert_raise(*args, &block)
end

#assert_respond_to(object, method, message = "") ⇒ Object 



209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
 
# File 'lib/test/unit/assertions.rb', line 209

def assert_respond_to(object, method, message="")
  _wrap_assertion do
    full_message = build_message(nil, "<?>\ngiven as the method name argument to #assert_respond_to must be a Symbol or #respond_to\\?(:to_str).", method)

    assert_block(full_message) do
      method.kind_of?(Symbol) || method.respond_to?(:to_str)
    end
    full_message = build_message(message, <<EOT, object, object.class, method)
<?>
of type <?>
expected to respond_to\\?<?>.
EOT
    assert_block(full_message) { object.respond_to?(method) }
  end
end

#assert_same(expected, actual, message = "") ⇒ Object 



254
255
256
257
258
259
260
261
262
 
# File 'lib/test/unit/assertions.rb', line 254

def assert_same(expected, actual, message="")
  full_message = build_message(message, <<EOT, expected, expected.__id__, actual, actual.__id__)
<?>
with id <?> expected to be equal\\? to
<?>
with id <?>.
EOT
  assert_block(full_message) { actual.equal?(expected) }
end

#assert_send(send_array, message = "") ⇒ Object 



505
506
507
508
509
510
511
512
513
514
515
 
# File 'lib/test/unit/assertions.rb', line 505

def assert_send(send_array, message="")
  _wrap_assertion do
    assert_instance_of(Array, send_array, "assert_send requires an array of send information")
    assert(send_array.size >= 2, "assert_send requires at least a receiver and a message name")
    full_message = build_message(message, <<EOT, send_array[0], AssertionMessage.literal(send_array[1].to_s), send_array[2..-1])
<?> expected to respond to
<?(?)> with a true value.
EOT
    assert_block(full_message) { send_array[0].__send__(send_array[1], *send_array[2..-1]) }
  end
end

#assert_throw(expected_object, message = "", &proc) ⇒ Object 



401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
 
# File 'lib/test/unit/assertions.rb', line 401

def assert_throw(expected_object, message="", &proc)
  _wrap_assertion do
    begin
      catch([]) {}
    rescue TypeError
      assert_instance_of(Symbol, expected_object,
                         "assert_throws expects the symbol that should be thrown for its first argument")
    end
    assert_block("Should have passed a block to assert_throw.") do
      block_given?
    end
    caught = true
    begin
      catch(expected_object) do
        proc.call
        caught = false
      end
      full_message = build_message(message,
                                   "<?> should have been thrown.",
                                   expected_object)
      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] == ":"
      full_message = build_message(message,
                                   "<?> expected to be thrown but\n" +
                                   "<?> was thrown.",
                                   expected_object, tag)
      flunk(full_message)
    end
  end
end

#assert_throws(*args, &block) ⇒ Object

Alias of assert_throw.

Will be deprecated in 1.9, and removed in 2.0.



439
440
441
 
# File 'lib/test/unit/assertions.rb', line 439

def assert_throws(*args, &block)
  assert_throw(*args, &block)
end

#assert_true(actual, message = nil) ⇒ Object

Passes if actual is true.

Example:

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



539
540
541
542
543
544
545
546
547
 
# File 'lib/test/unit/assertions.rb', line 539

def assert_true(actual, message=nil)
  _wrap_assertion do
    assert_block(build_message(message,
                               "<true> expected but was\n<?>",
                               actual)) do
      actual == true
    end
  end
end

#build_message(head, template = nil, *arguments) ⇒ Object 



700
701
702
703
 
# File 'lib/test/unit/assertions.rb', line 700

def build_message(head, template=nil, *arguments)
  template &&= template.chomp
  return AssertionMessage.new(head, template, arguments)
end

#flunk(message = "Flunked") ⇒ Object 



326
327
328
 
# File 'lib/test/unit/assertions.rb', line 326

def flunk(message="Flunked")
  assert_block(build_message(message)){false}
end