Module: Minitest::Assertions

Included in:
Test
Defined in:
lib/minitest/assertions.rb,
lib/minitest/mock.rb

Overview

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

Protocol: Nearly everything here boils up to assert, which expects to be able to increment an instance accessor named assertions. This is not provided by Assertions and must be provided by the thing including Assertions. See Minitest::Runnable for an example.

Constant Summary collapse

UNDEFINED =

:nodoc:

Object.new
E =

:nodoc:

""

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.



29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
 
# File 'lib/minitest/assertions.rb', line 29

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

  @diff
end

.diff=(o) ⇒ Object

Set the diff command to use in #diff.



49
50
51
 
# File 'lib/minitest/assertions.rb', line 49

def self.diff= o
  @diff = o
end

Instance Method Details

#_synchronize ⇒ Object

:nodoc:



144
145
146
 
# File 'lib/minitest/assertions.rb', line 144

def _synchronize # :nodoc:
  yield
end

#assert(test, msg = nil) ⇒ Object

Fails unless test is truthy.



134
135
136
137
138
139
140
141
142
 
# File 'lib/minitest/assertions.rb', line 134

def assert test, msg = nil
  self.assertions += 1
  unless test then
    msg ||= "Expected #{mu_pp test} to be truthy."
    msg = msg.call if Proc === msg
    raise Minitest::Assertion, msg
  end
  true
end

#assert_empty(obj, msg = nil) ⇒ Object

Fails unless obj is empty.



151
152
153
154
155
 
# File 'lib/minitest/assertions.rb', line 151

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 nicer structural diffing, set Minitest::Test.make_my_diffs_pretty!

For floats use assert_in_delta.

See also: Minitest::Assertions.diff



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

def assert_equal exp, act, msg = nil
  msg = message(msg, E) { 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



183
184
185
186
187
188
189
 
# File 'lib/minitest/assertions.rb', line 183

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.



195
196
197
 
# File 'lib/minitest/assertions.rb', line 195

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.



202
203
204
205
206
207
208
 
# File 'lib/minitest/assertions.rb', line 202

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.



213
214
215
216
217
218
219
 
# File 'lib/minitest/assertions.rb', line 213

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.



224
225
226
227
228
229
 
# File 'lib/minitest/assertions.rb', line 224

def assert_kind_of cls, obj, msg = nil
  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.



234
235
236
237
238
239
 
# File 'lib/minitest/assertions.rb', line 234

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_mock(mock) ⇒ Object

Assert that the mock verifies correctly.



173
174
175
 
# File 'lib/minitest/mock.rb', line 173

def assert_mock mock
  assert mock.verify
end

#assert_nil(obj, msg = nil) ⇒ Object

Fails unless obj is nil



244
245
246
247
 
# File 'lib/minitest/assertions.rb', line 244

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

assert_operator 5, :<=, 4



254
255
256
257
258
 
# File 'lib/minitest/assertions.rb', line 254

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.

assert_output(/hey/) { method_with_output }

NOTE: this uses #capture_io, not #capture_subprocess_io.

See also: #assert_silent



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

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

assert_predicate str, :empty?

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

str.must_be :empty?



295
296
297
298
 
# File 'lib/minitest/assertions.rb', line 295

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.

exp takes an optional message on the end to help explain failures and defaults to StandardError if no exception class is passed.



308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
 
# File 'lib/minitest/assertions.rb', line 308

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

  begin
    yield
  rescue *exp => e
    pass # count assertion
    return e
  rescue Minitest::Skip, Minitest::Assertion
    # don't count assertion
    raise
  rescue SignalException, SystemExit
    raise
  rescue Exception => e
    flunk proc {
      exception_details(e, "#{msg}#{mu_pp(exp)} exception expected, not")
    }
  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.



336
337
338
339
340
341
 
# File 'lib/minitest/assertions.rb', line 336

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?



346
347
348
349
350
351
352
 
# File 'lib/minitest/assertions.rb', line 346

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



359
360
361
362
363
364
 
# File 'lib/minitest/assertions.rb', line 359

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



371
372
373
374
375
 
# File 'lib/minitest/assertions.rb', line 371

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

#assert_throws(sym, msg = nil) ⇒ Object

Fails unless the block throws sym



380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
 
# File 'lib/minitest/assertions.rb', line 380

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.



414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
 
# File 'lib/minitest/assertions.rb', line 414

def capture_io
  _synchronize do
    begin
      captured_stdout, captured_stderr = StringIO.new, StringIO.new

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

      yield

      return captured_stdout.string, captured_stderr.string
    ensure
      $stdout = orig_stdout
      $stderr = orig_stderr
    end
  end
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.



447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
 
# File 'lib/minitest/assertions.rb', line 447

def capture_subprocess_io
  _synchronize do
    begin
      require "tempfile"

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

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

      yield

      $stdout.rewind
      $stderr.rewind

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



59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
 
# File 'lib/minitest/assertions.rb', line 59

def diff exp, act
  expect = mu_pp_for_diff exp
  butwas = mu_pp_for_diff act
  result = nil

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

  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



476
477
478
479
480
481
482
483
484
485
 
# File 'lib/minitest/assertions.rb', line 476

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



490
491
492
493
 
# File 'lib/minitest/assertions.rb', line 490

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

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

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



498
499
500
501
502
503
504
 
# File 'lib/minitest/assertions.rb', line 498

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



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

def mu_pp obj
  s = obj.inspect

  if defined? Encoding then
    s = s.encode Encoding.default_external

    if String === obj && obj.encoding != Encoding.default_external then
      s = "# encoding: #{obj.encoding}\n#{s}"
    end
  end

  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.



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

def mu_pp_for_diff obj
  mu_pp(obj).gsub(/\\n/, "\n").gsub(/:0x[a-fA-F0-9]{4,}/m, ":0xXXXXXX")
end

#pass(_msg = nil) ⇒ Object

used for counting assertions



509
510
511
 
# File 'lib/minitest/assertions.rb', line 509

def pass _msg = nil
  assert true
end

#refute(test, msg = nil) ⇒ Object

Fails if test is truthy.



516
517
518
519
 
# File 'lib/minitest/assertions.rb', line 516

def refute test, msg = nil
  msg ||= message { "Expected #{mu_pp(test)} to not be truthy" }
  not assert !test, msg
end

#refute_empty(obj, msg = nil) ⇒ Object

Fails if obj is empty.



524
525
526
527
528
 
# File 'lib/minitest/assertions.rb', line 524

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.



535
536
537
538
539
540
 
# File 'lib/minitest/assertions.rb', line 535

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)



547
548
549
550
551
552
553
 
# File 'lib/minitest/assertions.rb', line 547

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.



559
560
561
 
# File 'lib/minitest/assertions.rb', line 559

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.



566
567
568
569
570
571
572
 
# File 'lib/minitest/assertions.rb', line 566

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.



577
578
579
580
581
582
 
# File 'lib/minitest/assertions.rb', line 577

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.



587
588
589
590
 
# File 'lib/minitest/assertions.rb', line 587

def refute_kind_of cls, obj, msg = nil
  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.



595
596
597
598
599
600
 
# File 'lib/minitest/assertions.rb', line 595

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.



605
606
607
608
 
# File 'lib/minitest/assertions.rb', line 605

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



616
617
618
619
620
 
# File 'lib/minitest/assertions.rb', line 616

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?



631
632
633
634
 
# File 'lib/minitest/assertions.rb', line 631

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.



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

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.



648
649
650
651
652
653
654
 
# File 'lib/minitest/assertions.rb', line 648

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 run. If run in verbose-mode, the skipped run gets listed at the end of the run but doesn’t cause a failure exit code.

Raises:



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

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

#skipped? ⇒ Boolean

Was this testcase skipped? Meant for #teardown.

Returns:

  • (Boolean) 


670
671
672
 
# File 'lib/minitest/assertions.rb', line 670

def skipped?
  defined?(@skip) and @skip
end