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.



82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
 
# File 'lib/minitest/unit.rb', line 82

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.



101
102
103
 
# File 'lib/minitest/unit.rb', line 101

def self.diff= o
  @diff = o
end

Instance Method Details

#_assertions ⇒ Object

:nodoc:



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

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

#_assertions=(n) ⇒ Object

:nodoc:



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

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

#assert(test, msg = nil) ⇒ Object

Fails unless test is a true value.



187
188
189
190
191
192
193
194
195
 
# File 'lib/minitest/unit.rb', line 187

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



203
204
205
206
207
 
# File 'lib/minitest/unit.rb', line 203

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.



212
213
214
215
216
 
# File 'lib/minitest/unit.rb', line 212

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



230
231
232
233
 
# File 'lib/minitest/unit.rb', line 230

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



241
242
243
244
245
 
# File 'lib/minitest/unit.rb', line 241

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.



251
252
253
 
# File 'lib/minitest/unit.rb', line 251

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.



258
259
260
261
262
263
264
 
# File 'lib/minitest/unit.rb', line 258

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.



269
270
271
272
273
274
275
 
# File 'lib/minitest/unit.rb', line 269

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.



280
281
282
283
284
285
 
# File 'lib/minitest/unit.rb', line 280

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.



290
291
292
293
294
295
 
# File 'lib/minitest/unit.rb', line 290

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



300
301
302
303
 
# File 'lib/minitest/unit.rb', line 300

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



310
311
312
313
314
 
# File 'lib/minitest/unit.rb', line 310

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



326
327
328
329
330
331
332
333
334
335
336
337
338
 
# File 'lib/minitest/unit.rb', line 326

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?



349
350
351
352
 
# File 'lib/minitest/unit.rb', line 349

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.



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

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

  should_raise = false
  begin
    yield
    should_raise = true
  rescue MiniTest::Skip => e
    details = "#{msg}#{mu_pp(exp)} exception expected, not"

    if exp.include? MiniTest::Skip then
      return e
    else
      raise e
    end
  rescue Exception => e
    details = "#{msg}#{mu_pp(exp)} exception expected, not"
    assert(exp.any? { |ex|
             ex.instance_of?(Module) ? e.kind_of?(ex) : ex == e.class
           }, exception_details(e, details))

    return e
  end

  exp = exp.first if exp.size == 1
  flunk "#{msg}#{mu_pp(exp)} expected but nothing was raised." if
    should_raise
end

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

Fails unless obj responds to meth.



390
391
392
393
394
395
 
# File 'lib/minitest/unit.rb', line 390

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?



400
401
402
403
404
405
406
 
# File 'lib/minitest/unit.rb', line 400

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



414
415
416
417
418
419
 
# File 'lib/minitest/unit.rb', line 414

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



426
427
428
429
430
 
# File 'lib/minitest/unit.rb', line 426

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

#assert_throws(sym, msg = nil) ⇒ Object

Fails unless the block throws sym



435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
 
# File 'lib/minitest/unit.rb', line 435

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.



469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
 
# File 'lib/minitest/unit.rb', line 469

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.



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

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.



111
112
113
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
 
# File 'lib/minitest/unit.rb', line 111

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.",
                  "You should look at your implementation of #{klass}#==.",
                  expect
                 ].join "\n"
      end
    end
  end

  result
end

#exception_details(e, msg) ⇒ Object

Returns details for exception e



533
534
535
536
537
538
539
540
541
542
 
# File 'lib/minitest/unit.rb', line 533

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



547
548
549
550
 
# File 'lib/minitest/unit.rb', line 547

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.



555
556
557
558
559
560
 
# File 'lib/minitest/unit.rb', line 555

def message msg = nil, ending = ".", &default
  proc {
    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.



160
161
162
163
164
 
# File 'lib/minitest/unit.rb', line 160

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.



172
173
174
 
# File 'lib/minitest/unit.rb', line 172

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



565
566
567
 
# File 'lib/minitest/unit.rb', line 565

def pass msg = nil
  assert true
end

#refute(test, msg = nil) ⇒ Object

Fails if test is a true value



572
573
574
575
 
# File 'lib/minitest/unit.rb', line 572

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.



580
581
582
583
584
 
# File 'lib/minitest/unit.rb', line 580

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.



591
592
593
594
595
596
 
# File 'lib/minitest/unit.rb', line 591

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)



603
604
605
606
607
608
609
 
# File 'lib/minitest/unit.rb', line 603

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.



615
616
617
 
# File 'lib/minitest/unit.rb', line 615

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.



622
623
624
625
626
627
628
 
# File 'lib/minitest/unit.rb', line 622

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.



633
634
635
636
637
638
 
# File 'lib/minitest/unit.rb', line 633

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.



643
644
645
646
 
# File 'lib/minitest/unit.rb', line 643

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.



651
652
653
654
655
656
 
# File 'lib/minitest/unit.rb', line 651

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.



661
662
663
664
 
# File 'lib/minitest/unit.rb', line 661

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



672
673
674
675
676
 
# File 'lib/minitest/unit.rb', line 672

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?



687
688
689
690
 
# File 'lib/minitest/unit.rb', line 687

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.



695
696
697
698
699
 
# File 'lib/minitest/unit.rb', line 695

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.



704
705
706
707
708
709
710
 
# File 'lib/minitest/unit.rb', line 704

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:



716
717
718
719
 
# File 'lib/minitest/unit.rb', line 716

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.



724
725
726
727
728
 
# File 'lib/minitest/unit.rb', line 724

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