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



601
602
603
 
# File 'lib/test/unit/assertions.rb', line 601

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



520
521
522
523
524
525
526
527
528
 
# File 'lib/test/unit/assertions.rb', line 520

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_equal(expected, actual, message = nil) ⇒ Object 



79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
 
# File 'lib/test/unit/assertions.rb', line 79

def assert_equal(expected, actual, message=nil)
  diff = AssertionMessage.delayed_literal do
    if !expected.is_a?(String) or !actual.is_a?(String)
      expected = AssertionMessage.convert(expected)
      actual = AssertionMessage.convert(actual)
    end
    diff = Diff.readable(expected, actual)
    if /^[-+]/ !~ diff
      diff = ""
    elsif /^[ ?]/ =~ diff or /(?:.*\n){2,}/ =~ diff
      diff = "\n\ndiff:\n#{diff}"
    else
      diff = ""
    end
    diff
  end
  full_message = build_message(message, <<EOT, expected, actual, diff)
<?> expected but was
<?>.?
EOT
  assert_block(full_message) { expected == actual }
end

#assert_false(actual, message = nil) ⇒ Object

Passes if actual is false.

Example:

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



552
553
554
555
556
557
558
559
560
 
# File 'lib/test/unit/assertions.rb', line 552

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 



475
476
477
478
479
480
481
482
483
484
485
486
487
488
 
# File 'lib/test/unit/assertions.rb', line 475

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 



168
169
170
171
172
173
174
175
176
177
178
 
# File 'lib/test/unit/assertions.rb', line 168

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 



201
202
203
204
205
206
207
 
# File 'lib/test/unit/assertions.rb', line 201

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 



239
240
241
242
243
244
245
246
247
248
249
250
 
# File 'lib/test/unit/assertions.rb', line 239

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 



187
188
189
190
191
192
 
# File 'lib/test/unit/assertions.rb', line 187

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 



383
384
385
386
387
388
389
 
# File 'lib/test/unit/assertions.rb', line 383

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_equal(expected, actual, message = "") ⇒ Object 



359
360
361
362
 
# File 'lib/test/unit/assertions.rb', line 359

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 



371
372
373
374
 
# File 'lib/test/unit/assertions.rb', line 371

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 



342
343
344
345
346
347
348
349
350
 
# File 'lib/test/unit/assertions.rb', line 342

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 



302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
 
# File 'lib/test/unit/assertions.rb', line 302

def assert_nothing_raised(*args)
  _wrap_assertion do
    if Module === args.last
      message = ""
    else
      message = args.pop
    end
    exceptions, modules = _check_exception_class(args)
    begin
      yield
    rescue Exception => e
      if ((args.empty? && !e.instance_of?(AssertionFailedError)) ||
          _expected_exception?(e, exceptions, modules))
        assert_block(build_message(message, "Exception raised:\n?", e)){false}
      else
        raise
      end
    end
    nil
  end
end

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



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

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 



280
281
282
283
284
285
286
287
288
289
290
291
 
# File 'lib/test/unit/assertions.rb', line 280

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) ⇒ Object 



126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
 
# File 'lib/test/unit/assertions.rb', line 126

def assert_raise(*args)
  _wrap_assertion do
    if Module === args.last
      message = ""
    else
      message = args.pop
    end
    exceptions, modules = _check_exception_class(args)
    expected = args.size == 1 ? args.first : args
    actual_exception = nil
    full_message = build_message(message, "<?> exception expected but none was thrown.", expected)
    assert_block(full_message) do
      begin
        yield
      rescue Exception => actual_exception
        break
      end
      false
    end
    full_message = build_message(message, "<?> exception expected but was\n?", expected, actual_exception)
    assert_block(full_message) {_expected_exception?(actual_exception, exceptions, modules)}
    actual_exception
  end
end

#assert_raises(*args, &block) ⇒ Object 



157
158
159
 
# File 'lib/test/unit/assertions.rb', line 157

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

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



216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
 
# File 'lib/test/unit/assertions.rb', line 216

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 



261
262
263
264
265
266
267
268
269
 
# File 'lib/test/unit/assertions.rb', line 261

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 



502
503
504
505
506
507
508
509
510
511
512
 
# File 'lib/test/unit/assertions.rb', line 502

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_throws(expected_object, message = "", &proc) ⇒ Object 



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
435
436
437
438
 
# File 'lib/test/unit/assertions.rb', line 406

def assert_throws(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_throws.") 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_true(actual, message = nil) ⇒ Object

Passes if actual is true.

Example:

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



536
537
538
539
540
541
542
543
544
 
# File 'lib/test/unit/assertions.rb', line 536

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 



567
568
569
570
 
# File 'lib/test/unit/assertions.rb', line 567

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

#flunk(message = "Flunked") ⇒ Object 



331
332
333
 
# File 'lib/test/unit/assertions.rb', line 331

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