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 



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

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

Instance Method Details

#assert(boolean, message = nil) ⇒ Object 



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

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:



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

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



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

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



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
598
 
# File 'lib/test/unit/assertions.rb', line 573

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 = "<?> \#{operator} <?> should be true\n<?> expected \#{operator_description}\n<?>.\n"
    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



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

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 



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

def assert_equal(expected, actual, message=nil)
  diff = AssertionMessage.delayed_diff(expected, actual)
  full_message = build_message(message, "<?> expected but was\n<?>.?\n", expected, actual, diff)
  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



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

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



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

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 



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

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, "<?> and\n<?> expected to be within\n<?> of each other.\n", expected_float, actual_float, delta)
    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 



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

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, "<?> expected to be an instance of\n<?> but was\n<?>.\n", object, klass, object.class)
    assert_block(full_message){object.instance_of?(klass)}
  end
end

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



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

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 



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

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 



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

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

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



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

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



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

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 



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

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 



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

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 



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

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

#assert_nothing_raised(*args) ⇒ Object 



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

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 



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

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 



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

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, "<?> expected to be\n?\n<?>.\n", object1, AssertionMessage.literal(operator), object2)
    assert_block(full_message) { object1.__send__(operator, object2) }
  end
end

#assert_raise(*args, &block) ⇒ Object 



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

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



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

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



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
660
 
# File 'lib/test/unit/assertions.rb', line 630

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 



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

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

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



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

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, "<?>\nof type <?>\nexpected to respond_to\\\\?<?>.\n", object, object.class, method)
    assert_block(full_message) { object.respond_to?(method) }
  end
end

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



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

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

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



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

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, "<?> expected to respond to\n<?(?)> with a true value.\n", send_array[0], AssertionMessage.literal(send_array[1].to_s), send_array[2..-1])
    assert_block(full_message) { send_array[0].__send__(send_array[1], *send_array[2..-1]) }
  end
end

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



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
434
 
# File 'lib/test/unit/assertions.rb', line 402

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.



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

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



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

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 



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

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

#flunk(message = "Flunked") ⇒ Object 



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

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