Module: MiniTest::Assertions

Included in:
Unit::TestCase
Defined in:
lib/minitest/unit.rb

Overview

MiniTest Assertions. All assertion methods accept a msg which is printed if the assertion fails.

Constant Summary collapse

UNDEFINED =

:nodoc:

Object.new

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.diff ⇒ Object

Returns the diff command to use in #diff. Tries to intelligently figure out what diff to use.



85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
 
# File 'lib/minitest/unit.rb', line 85

def self.diff
  @diff = if RbConfig::CONFIG['host_os'] =~ /mswin|mingw/ then
            "diff.exe -u"
          else
            if system("gdiff", __FILE__, __FILE__)
              "gdiff -u" # solaris and kin suck
            elsif system("diff", __FILE__, __FILE__)
              "diff -u"
            else
              nil
            end
          end unless defined? @diff

  @diff
end

.diff=(o) ⇒ Object

Set the diff command to use in #diff.



104
105
106
 
# File 'lib/minitest/unit.rb', line 104

def self.diff= o
  @diff = o
end

Instance Method Details

#_assertions ⇒ Object

:nodoc:



184
185
186
 
# File 'lib/minitest/unit.rb', line 184

def _assertions # :nodoc:
  @_assertions ||= 0
end

#_assertions=(n) ⇒ Object

:nodoc:



180
181
182
 
# File 'lib/minitest/unit.rb', line 180

def _assertions= n # :nodoc:
  @_assertions = n
end

#assert(test, msg = nil) ⇒ Object

Fails unless test is a true value.



191
192
193
194
195
196
197
198
199
 
# File 'lib/minitest/unit.rb', line 191

def assert test, msg = nil
  msg ||= "Failed assertion, no message given."
  self._assertions += 1
  unless test then
    msg = msg.call if Proc === msg
    raise MiniTest::Assertion, msg
  end
  true
end

#assert_block(msg = nil) ⇒ Object

Fails unless the block returns a true value.

NOTE: This method is deprecated, use assert. It will be removed on 2013-01-01.“



207
208
209
210
211
 
# File 'lib/minitest/unit.rb', line 207

def assert_block msg = nil
  warn "NOTE: MiniTest::Unit::TestCase#assert_block is deprecated, use assert. It will be removed on 2013-01-01. Called from #{caller.first}"
  msg = message(msg) { "Expected block to return true value" }
  assert yield, msg
end

#assert_empty(obj, msg = nil) ⇒ Object

Fails unless obj is empty.



216
217
218
219
220
 
# File 'lib/minitest/unit.rb', line 216

def assert_empty obj, msg = nil
  msg = message(msg) { "Expected #{mu_pp(obj)} to be empty" }
  assert_respond_to obj, :empty?
  assert obj.empty?, msg
end

#assert_equal(exp, act, msg = nil) ⇒ Object

Fails unless exp == act printing the difference between the two, if possible.

If there is no visible difference but the assertion fails, you should suspect that your #== is buggy, or your inspect output is missing crucial details.

For floats use assert_in_delta.

See also: MiniTest::Assertions.diff



234
235
236
237
 
# File 'lib/minitest/unit.rb', line 234

def assert_equal exp, act, msg = nil
  msg = message(msg, "") { diff exp, act }
  assert(exp == act, msg)
end

#assert_in_delta(exp, act, delta = 0.001, msg = nil) ⇒ Object

For comparing Floats. Fails unless exp and act are within delta of each other.

assert_in_delta Math::PI, (22.0 / 7.0), 0.01



245
246
247
248
249
 
# File 'lib/minitest/unit.rb', line 245

def assert_in_delta exp, act, delta = 0.001, msg = nil
  n = (exp - act).abs
  msg = message(msg) { "Expected |#{exp} - #{act}| (#{n}) to be < #{delta}"}
  assert delta >= n, msg
end

#assert_in_epsilon(a, b, epsilon = 0.001, msg = nil) ⇒ Object

For comparing Floats. Fails unless exp and act have a relative error less than epsilon.



255
256
257
 
# File 'lib/minitest/unit.rb', line 255

def assert_in_epsilon a, b, epsilon = 0.001, msg = nil
  assert_in_delta a, b, [a.abs, b.abs].min * epsilon, msg
end

#assert_includes(collection, obj, msg = nil) ⇒ Object

Fails unless collection includes obj.



262
263
264
265
266
267
268
 
# File 'lib/minitest/unit.rb', line 262

def assert_includes collection, obj, msg = nil
  msg = message(msg) {
    "Expected #{mu_pp(collection)} to include #{mu_pp(obj)}"
  }
  assert_respond_to collection, :include?
  assert collection.include?(obj), msg
end

#assert_instance_of(cls, obj, msg = nil) ⇒ Object

Fails unless obj is an instance of cls.



273
274
275
276
277
278
279
 
# File 'lib/minitest/unit.rb', line 273

def assert_instance_of cls, obj, msg = nil
  msg = message(msg) {
    "Expected #{mu_pp(obj)} to be an instance of #{cls}, not #{obj.class}"
  }

  assert obj.instance_of?(cls), msg
end

#assert_kind_of(cls, obj, msg = nil) ⇒ Object

Fails unless obj is a kind of cls.



284
285
286
287
288
289
 
# File 'lib/minitest/unit.rb', line 284

def assert_kind_of cls, obj, msg = nil # TODO: merge with instance_of
  msg = message(msg) {
    "Expected #{mu_pp(obj)} to be a kind of #{cls}, not #{obj.class}" }

  assert obj.kind_of?(cls), msg
end

#assert_match(matcher, obj, msg = nil) ⇒ Object

Fails unless matcher =~ obj.



294
295
296
297
298
299
 
# File 'lib/minitest/unit.rb', line 294

def assert_match matcher, obj, msg = nil
  msg = message(msg) { "Expected #{mu_pp matcher} to match #{mu_pp obj}" }
  assert_respond_to matcher, :"=~"
  matcher = Regexp.new Regexp.escape matcher if String === matcher
  assert matcher =~ obj, msg
end

#assert_nil(obj, msg = nil) ⇒ Object

Fails unless obj is nil



304
305
306
307
 
# File 'lib/minitest/unit.rb', line 304

def assert_nil obj, msg = nil
  msg = message(msg) { "Expected #{mu_pp(obj)} to be nil" }
  assert obj.nil?, msg
end

#assert_operator(o1, op, o2 = UNDEFINED, msg = nil) ⇒ Object

For testing with binary operators.

assert_operator 5, :<=, 4



314
315
316
317
318
 
# File 'lib/minitest/unit.rb', line 314

def assert_operator o1, op, o2 = UNDEFINED, msg = nil
  return assert_predicate o1, op, msg if UNDEFINED == o2
  msg = message(msg) { "Expected #{mu_pp(o1)} to be #{op} #{mu_pp(o2)}" }
  assert o1.__send__(op, o2), msg
end

#assert_output(stdout = nil, stderr = nil) ⇒ Object

Fails if stdout or stderr do not output the expected results. Pass in nil if you don’t care about that streams output. Pass in “” if you require it to be silent. Pass in a regexp if you want to pattern match.

NOTE: this uses #capture_io, not #capture_subprocess_io.

See also: #assert_silent



330
331
332
333
334
335
336
337
338
339
340
341
342
 
# File 'lib/minitest/unit.rb', line 330

def assert_output stdout = nil, stderr = nil
  out, err = capture_io do
    yield
  end

  err_msg = Regexp === stderr ? :assert_match : :assert_equal if stderr
  out_msg = Regexp === stdout ? :assert_match : :assert_equal if stdout

  y = send err_msg, stderr, err, "In stderr" if err_msg
  x = send out_msg, stdout, out, "In stdout" if out_msg

  (!stdout || x) && (!stderr || y)
end

#assert_predicate(o1, op, msg = nil) ⇒ Object

For testing with predicates.

assert_predicate str, :empty?

This is really meant for specs and is front-ended by assert_operator:

str.must_be :empty?



353
354
355
356
 
# File 'lib/minitest/unit.rb', line 353

def assert_predicate o1, op, msg = nil
  msg = message(msg) { "Expected #{mu_pp(o1)} to be #{op}" }
  assert o1.__send__(op), msg
end

#assert_raises(*exp) ⇒ Object

Fails unless the block raises one of exp. Returns the exception matched so you can check the message, attributes, etc.



362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
 
# File 'lib/minitest/unit.rb', line 362

def assert_raises *exp
  msg = "#{exp.pop}.\n" if String === exp.last

  begin
    yield
  rescue MiniTest::Skip => e
    return e if exp.include? MiniTest::Skip
    raise e
  rescue Exception => e
    expected = exp.any? { |ex|
      if ex.instance_of? Module then
        e.kind_of? ex
      else
        e.instance_of? ex
      end
    }

    assert expected, proc {
      exception_details(e, "#{msg}#{mu_pp(exp)} exception expected, not")
    }

    return e
  end

  exp = exp.first if exp.size == 1

  flunk "#{msg}#{mu_pp(exp)} expected but nothing was raised."
end

#assert_respond_to(obj, meth, msg = nil) ⇒ Object

Fails unless obj responds to meth.



394
395
396
397
398
399
 
# File 'lib/minitest/unit.rb', line 394

def assert_respond_to obj, meth, msg = nil
  msg = message(msg) {
    "Expected #{mu_pp(obj)} (#{obj.class}) to respond to ##{meth}"
  }
  assert obj.respond_to?(meth), msg
end

#assert_same(exp, act, msg = nil) ⇒ Object

Fails unless exp and act are #equal?



404
405
406
407
408
409
410
 
# File 'lib/minitest/unit.rb', line 404

def assert_same exp, act, msg = nil
  msg = message(msg) {
    data = [mu_pp(act), act.object_id, mu_pp(exp), exp.object_id]
    "Expected %s (oid=%d) to be the same as %s (oid=%d)" % data
  }
  assert exp.equal?(act), msg
end

#assert_send(send_ary, m = nil) ⇒ Object

send_ary is a receiver, message and arguments.

Fails unless the call returns a true value TODO: I should prolly remove this from specs



418
419
420
421
422
423
 
# File 'lib/minitest/unit.rb', line 418

def assert_send send_ary, m = nil
  recv, msg, *args = send_ary
  m = message(m) {
    "Expected #{mu_pp(recv)}.#{msg}(*#{mu_pp(args)}) to return true" }
  assert recv.__send__(msg, *args), m
end

#assert_silent ⇒ Object

Fails if the block outputs anything to stderr or stdout.

See also: #assert_output



430
431
432
433
434
 
# File 'lib/minitest/unit.rb', line 430

def assert_silent
  assert_output "", "" do
    yield
  end
end

#assert_throws(sym, msg = nil) ⇒ Object

Fails unless the block throws sym



439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
 
# File 'lib/minitest/unit.rb', line 439

def assert_throws sym, msg = nil
  default = "Expected #{mu_pp(sym)} to have been thrown"
  caught = true
  catch(sym) do
    begin
      yield
    rescue ThreadError => e       # wtf?!? 1.8 + threads == suck
      default += ", not \:#{e.message[/uncaught throw \`(\w+?)\'/, 1]}"
    rescue ArgumentError => e     # 1.9 exception
      default += ", not #{e.message.split(/ /).last}"
    rescue NameError => e         # 1.8 exception
      default += ", not #{e.name.inspect}"
    end
    caught = false
  end

  assert caught, message(msg) { default }
end

#capture_io ⇒ Object

Captures $stdout and $stderr into strings:

out, err = capture_io do
  puts "Some info"
  warn "You did a bad thing"
end

assert_match %r%info%, out
assert_match %r%bad%, err

NOTE: For efficiency, this method uses StringIO and does not capture IO for subprocesses. Use #capture_subprocess_io for that.



473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
 
# File 'lib/minitest/unit.rb', line 473

def capture_io
  require 'stringio'

  captured_stdout, captured_stderr = StringIO.new, StringIO.new

  synchronize do
    orig_stdout, orig_stderr = $stdout, $stderr
    $stdout, $stderr         = captured_stdout, captured_stderr

    begin
      yield
    ensure
      $stdout = orig_stdout
      $stderr = orig_stderr
    end
  end

  return captured_stdout.string, captured_stderr.string
end

#capture_subprocess_io ⇒ Object

Captures $stdout and $stderr into strings, using Tempfile to ensure that subprocess IO is captured as well.

out, err = capture_subprocess_io do
  system "echo Some info"
  system "echo You did a bad thing 1>&2"
end

assert_match %r%info%, out
assert_match %r%bad%, err

NOTE: This method is approximately 10x slower than #capture_io so only use it when you need to test the output of a subprocess.



508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
 
# File 'lib/minitest/unit.rb', line 508

def capture_subprocess_io
  require 'tempfile'

  captured_stdout, captured_stderr = Tempfile.new("out"), Tempfile.new("err")

  synchronize do
    orig_stdout, orig_stderr = $stdout.dup, $stderr.dup
    $stdout.reopen captured_stdout
    $stderr.reopen captured_stderr

    begin
      yield

      $stdout.rewind
      $stderr.rewind

      [captured_stdout.read, captured_stderr.read]
    ensure
      captured_stdout.unlink
      captured_stderr.unlink
      $stdout.reopen orig_stdout
      $stderr.reopen orig_stderr
    end
  end
end

#diff(exp, act) ⇒ Object

Returns a diff between exp and act. If there is no known diff command or if it doesn’t make sense to diff the output (single line, short output), then it simply returns a basic comparison between the two.



114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
 
# File 'lib/minitest/unit.rb', line 114

def diff exp, act
  require "tempfile"

  expect = mu_pp_for_diff exp
  butwas = mu_pp_for_diff act
  result = nil

  need_to_diff =
    MiniTest::Assertions.diff &&
    (expect.include?("\n")    ||
     butwas.include?("\n")    ||
     expect.size > 30         ||
     butwas.size > 30         ||
     expect == butwas)

  return "Expected: #{mu_pp exp}\n  Actual: #{mu_pp act}" unless
    need_to_diff

  Tempfile.open("expect") do |a|
    a.puts expect
    a.flush

    Tempfile.open("butwas") do |b|
      b.puts butwas
      b.flush

      result = `#{MiniTest::Assertions.diff} #{a.path} #{b.path}`
      result.sub!(/^\-\-\- .+/, "--- expected")
      result.sub!(/^\+\+\+ .+/, "+++ actual")

      if result.empty? then
        klass = exp.class
        result = [
                  "No visible difference in the #{klass}#inspect output.\n",
                  "You should look at the implementation of #== on ",
                  "#{klass} or its members.\n",
                  expect,
                 ].join
      end
    end
  end

  result
end

#exception_details(e, msg) ⇒ Object

Returns details for exception e



537
538
539
540
541
542
543
544
545
546
 
# File 'lib/minitest/unit.rb', line 537

def exception_details e, msg
  [
   "#{msg}",
   "Class: <#{e.class}>",
   "Message: <#{e.message.inspect}>",
   "---Backtrace---",
   "#{MiniTest::filter_backtrace(e.backtrace).join("\n")}",
   "---------------",
  ].join "\n"
end

#flunk(msg = nil) ⇒ Object

Fails with msg



551
552
553
554
 
# File 'lib/minitest/unit.rb', line 551

def flunk msg = nil
  msg ||= "Epic Fail!"
  assert false, msg
end

#message(msg = nil, ending = ".", &default) ⇒ Object

Returns a proc that will output msg along with the default message.



559
560
561
562
563
564
565
 
# File 'lib/minitest/unit.rb', line 559

def message msg = nil, ending = ".", &default
  proc {
    msg = msg.call.chomp(".") if Proc === msg
    custom_message = "#{msg}.\n" unless msg.nil? or msg.to_s.empty?
    "#{custom_message}#{default.call}#{ending}"
  }
end

#mu_pp(obj) ⇒ Object

This returns a human-readable version of obj. By default #inspect is called. You can override this to use #pretty_print if you want.



164
165
166
167
168
 
# File 'lib/minitest/unit.rb', line 164

def mu_pp obj
  s = obj.inspect
  s = s.encode Encoding.default_external if defined? Encoding
  s
end

#mu_pp_for_diff(obj) ⇒ Object

This returns a diff-able human-readable version of obj. This differs from the regular mu_pp because it expands escaped newlines and makes hex-values generic (like object_ids). This uses mu_pp to do the first pass and then cleans it up.



176
177
178
 
# File 'lib/minitest/unit.rb', line 176

def mu_pp_for_diff obj # TODO: possibly rename
  mu_pp(obj).gsub(/\\n/, "\n").gsub(/0x[a-f0-9]+/m, '0xXXXXXX')
end

#pass(msg = nil) ⇒ Object

used for counting assertions



570
571
572
 
# File 'lib/minitest/unit.rb', line 570

def pass msg = nil
  assert true
end

#refute(test, msg = nil) ⇒ Object

Fails if test is a true value



577
578
579
580
 
# File 'lib/minitest/unit.rb', line 577

def refute test, msg = nil
  msg ||= "Failed refutation, no message given"
  not assert(! test, msg)
end

#refute_empty(obj, msg = nil) ⇒ Object

Fails if obj is empty.



585
586
587
588
589
 
# File 'lib/minitest/unit.rb', line 585

def refute_empty obj, msg = nil
  msg = message(msg) { "Expected #{mu_pp(obj)} to not be empty" }
  assert_respond_to obj, :empty?
  refute obj.empty?, msg
end

#refute_equal(exp, act, msg = nil) ⇒ Object

Fails if exp == act.

For floats use refute_in_delta.



596
597
598
599
600
601
 
# File 'lib/minitest/unit.rb', line 596

def refute_equal exp, act, msg = nil
  msg = message(msg) {
    "Expected #{mu_pp(act)} to not be equal to #{mu_pp(exp)}"
  }
  refute exp == act, msg
end

#refute_in_delta(exp, act, delta = 0.001, msg = nil) ⇒ Object

For comparing Floats. Fails if exp is within delta of act.

refute_in_delta Math::PI, (22.0 / 7.0)



608
609
610
611
612
613
614
 
# File 'lib/minitest/unit.rb', line 608

def refute_in_delta exp, act, delta = 0.001, msg = nil
  n = (exp - act).abs
  msg = message(msg) {
    "Expected |#{exp} - #{act}| (#{n}) to not be < #{delta}"
  }
  refute delta > n, msg
end

#refute_in_epsilon(a, b, epsilon = 0.001, msg = nil) ⇒ Object

For comparing Floats. Fails if exp and act have a relative error less than epsilon.



620
621
622
 
# File 'lib/minitest/unit.rb', line 620

def refute_in_epsilon a, b, epsilon = 0.001, msg = nil
  refute_in_delta a, b, a * epsilon, msg
end

#refute_includes(collection, obj, msg = nil) ⇒ Object

Fails if collection includes obj.



627
628
629
630
631
632
633
 
# File 'lib/minitest/unit.rb', line 627

def refute_includes collection, obj, msg = nil
  msg = message(msg) {
    "Expected #{mu_pp(collection)} to not include #{mu_pp(obj)}"
  }
  assert_respond_to collection, :include?
  refute collection.include?(obj), msg
end

#refute_instance_of(cls, obj, msg = nil) ⇒ Object

Fails if obj is an instance of cls.



638
639
640
641
642
643
 
# File 'lib/minitest/unit.rb', line 638

def refute_instance_of cls, obj, msg = nil
  msg = message(msg) {
    "Expected #{mu_pp(obj)} to not be an instance of #{cls}"
  }
  refute obj.instance_of?(cls), msg
end

#refute_kind_of(cls, obj, msg = nil) ⇒ Object

Fails if obj is a kind of cls.



648
649
650
651
 
# File 'lib/minitest/unit.rb', line 648

def refute_kind_of cls, obj, msg = nil # TODO: merge with instance_of
  msg = message(msg) { "Expected #{mu_pp(obj)} to not be a kind of #{cls}" }
  refute obj.kind_of?(cls), msg
end

#refute_match(matcher, obj, msg = nil) ⇒ Object

Fails if matcher =~ obj.



656
657
658
659
660
661
 
# File 'lib/minitest/unit.rb', line 656

def refute_match matcher, obj, msg = nil
  msg = message(msg) {"Expected #{mu_pp matcher} to not match #{mu_pp obj}"}
  assert_respond_to matcher, :"=~"
  matcher = Regexp.new Regexp.escape matcher if String === matcher
  refute matcher =~ obj, msg
end

#refute_nil(obj, msg = nil) ⇒ Object

Fails if obj is nil.



666
667
668
669
 
# File 'lib/minitest/unit.rb', line 666

def refute_nil obj, msg = nil
  msg = message(msg) { "Expected #{mu_pp(obj)} to not be nil" }
  refute obj.nil?, msg
end

#refute_operator(o1, op, o2 = UNDEFINED, msg = nil) ⇒ Object

Fails if o1 is not op o2. Eg:

refute_operator 1, :>, 2 #=> pass
refute_operator 1, :<, 2 #=> fail



677
678
679
680
681
 
# File 'lib/minitest/unit.rb', line 677

def refute_operator o1, op, o2 = UNDEFINED, msg = nil
  return refute_predicate o1, op, msg if UNDEFINED == o2
  msg = message(msg) { "Expected #{mu_pp(o1)} to not be #{op} #{mu_pp(o2)}"}
  refute o1.__send__(op, o2), msg
end

#refute_predicate(o1, op, msg = nil) ⇒ Object

For testing with predicates.

refute_predicate str, :empty?

This is really meant for specs and is front-ended by refute_operator:

str.wont_be :empty?



692
693
694
695
 
# File 'lib/minitest/unit.rb', line 692

def refute_predicate o1, op, msg = nil
  msg = message(msg) { "Expected #{mu_pp(o1)} to not be #{op}" }
  refute o1.__send__(op), msg
end

#refute_respond_to(obj, meth, msg = nil) ⇒ Object

Fails if obj responds to the message meth.



700
701
702
703
704
 
# File 'lib/minitest/unit.rb', line 700

def refute_respond_to obj, meth, msg = nil
  msg = message(msg) { "Expected #{mu_pp(obj)} to not respond to #{meth}" }

  refute obj.respond_to?(meth), msg
end

#refute_same(exp, act, msg = nil) ⇒ Object

Fails if exp is the same (by object identity) as act.



709
710
711
712
713
714
715
 
# File 'lib/minitest/unit.rb', line 709

def refute_same exp, act, msg = nil
  msg = message(msg) {
    data = [mu_pp(act), act.object_id, mu_pp(exp), exp.object_id]
    "Expected %s (oid=%d) to not be the same as %s (oid=%d)" % data
  }
  refute exp.equal?(act), msg
end

#skip(msg = nil, bt = caller) ⇒ Object

Skips the current test. Gets listed at the end of the run but doesn’t cause a failure exit code.

Raises:



721
722
723
724
 
# File 'lib/minitest/unit.rb', line 721

def skip msg = nil, bt = caller
  msg ||= "Skipped, no message given"
  raise MiniTest::Skip, msg, bt
end

#synchronize ⇒ Object

Takes a block and wraps it with the runner’s shared mutex.



729
730
731
732
733
 
# File 'lib/minitest/unit.rb', line 729

def synchronize
  Minitest::Unit.runner.synchronize do
    yield
  end
end