Maintenance of Ruby 2.0.0 ended on February 24, 2016. Read more

In Files

  • minitest/unit.rb

MiniTest::Assertions

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

Public Class Methods

diff() click to toggle source

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

 
               # File minitest/unit.rb, line 88
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) click to toggle source

Set the diff command to use in diff.

 
               # File minitest/unit.rb, line 107
def self.diff= o
  @diff = o
end

Public Instance Methods

assert(test, msg = nil) click to toggle source

Fails unless test is a true value.

 
               # File minitest/unit.rb, line 194
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) click to toggle source

Fails unless the block returns a true value.

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

 
               # File minitest/unit.rb, line 210
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) click to toggle source

Fails unless obj is empty.

 
               # File minitest/unit.rb, line 219
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) click to toggle source

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

 
               # File minitest/unit.rb, line 237
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) click to toggle source

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

 
               # File minitest/unit.rb, line 248
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) click to toggle source

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

 
               # File minitest/unit.rb, line 258
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) click to toggle source

Fails unless collection includes obj.

 
               # File minitest/unit.rb, line 265
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) click to toggle source

Fails unless obj is an instance of cls.

 
               # File minitest/unit.rb, line 276
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) click to toggle source

Fails unless obj is a kind of cls.

 
               # File minitest/unit.rb, line 287
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) click to toggle source

Fails unless matcher =~ obj.

 
               # File minitest/unit.rb, line 297
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) click to toggle source

Fails unless obj is nil

 
               # File minitest/unit.rb, line 307
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) click to toggle source

For testing with binary operators.

assert_operator 5, :<=, 4

 
               # File minitest/unit.rb, line 317
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) click to toggle source

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

 
               # File minitest/unit.rb, line 333
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) click to toggle source

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?

 
               # File minitest/unit.rb, line 356
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) click to toggle source

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

 
               # File minitest/unit.rb, line 365
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) click to toggle source

Fails unless obj responds to meth.

 
               # File minitest/unit.rb, line 397
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) click to toggle source

Fails unless exp and act are equal?

 
               # File minitest/unit.rb, line 407
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) click to toggle source

send_ary is a receiver, message and arguments.

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

 
               # File minitest/unit.rb, line 421
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() click to toggle source

Fails if the block outputs anything to stderr or stdout.

See also: assert_output

 
               # File minitest/unit.rb, line 433
def assert_silent
  assert_output "", "" do
    yield
  end
end
assert_throws(sym, msg = nil) click to toggle source

Fails unless the block throws sym

 
               # File minitest/unit.rb, line 442
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() click to toggle source

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.

 
               # File minitest/unit.rb, line 476
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() click to toggle source

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.

 
               # File minitest/unit.rb, line 511
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) click to toggle source

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.

 
               # File minitest/unit.rb, line 117
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) click to toggle source

Returns details for exception e

 
               # File minitest/unit.rb, line 540
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) click to toggle source

Fails with msg

 
               # File minitest/unit.rb, line 554
def flunk msg = nil
  msg ||= "Epic Fail!"
  assert false, msg
end
message(msg = nil, ending = ".", &default) click to toggle source

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

 
               # File minitest/unit.rb, line 562
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) click to toggle source

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

 
               # File minitest/unit.rb, line 167
def mu_pp obj
  s = obj.inspect
  s = s.encode Encoding.default_external if defined? Encoding
  s
end
mu_pp_for_diff(obj) click to toggle source

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.

 
               # File minitest/unit.rb, line 179
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) click to toggle source

used for counting assertions

 
               # File minitest/unit.rb, line 572
def pass msg = nil
  assert true
end
refute(test, msg = nil) click to toggle source

Fails if test is a true value

 
               # File minitest/unit.rb, line 579
def refute test, msg = nil
  msg ||= "Failed refutation, no message given"
  not assert(! test, msg)
end
refute_empty(obj, msg = nil) click to toggle source

Fails if obj is empty.

 
               # File minitest/unit.rb, line 587
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) click to toggle source

Fails if exp == act.

For floats use refute_in_delta.

 
               # File minitest/unit.rb, line 598
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) click to toggle source

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

refute_in_delta Math::PI, (22.0 / 7.0)

 
               # File minitest/unit.rb, line 610
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) click to toggle source

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

 
               # File minitest/unit.rb, line 622
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) click to toggle source

Fails if collection includes obj.

 
               # File minitest/unit.rb, line 629
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) click to toggle source

Fails if obj is an instance of cls.

 
               # File minitest/unit.rb, line 640
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) click to toggle source

Fails if obj is a kind of cls.

 
               # File minitest/unit.rb, line 650
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) click to toggle source

Fails if matcher =~ obj.

 
               # File minitest/unit.rb, line 658
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) click to toggle source

Fails if obj is nil.

 
               # File minitest/unit.rb, line 668
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) click to toggle source

Fails if o1 is not op o2. Eg:

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

 
               # File minitest/unit.rb, line 679
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) click to toggle source

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?

 
               # File minitest/unit.rb, line 694
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) click to toggle source

Fails if obj responds to the message meth.

 
               # File minitest/unit.rb, line 702
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) click to toggle source

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

 
               # File minitest/unit.rb, line 711
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) click to toggle source

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

 
               # File minitest/unit.rb, line 723
def skip msg = nil, bt = caller
  msg ||= "Skipped, no message given"
  raise MiniTest::Skip, msg, bt
end
synchronize() click to toggle source

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

 
               # File minitest/unit.rb, line 731
def synchronize
  Minitest::Unit.runner.synchronize do
    yield
  end
end