In Files
- minitest/unit.rb
Methods
- ::diff
- ::diff=
- #assert
- #assert_empty
- #assert_equal
- #assert_in_delta
- #assert_in_epsilon
- #assert_includes
- #assert_instance_of
- #assert_kind_of
- #assert_match
- #assert_nil
- #assert_operator
- #assert_output
- #assert_predicate
- #assert_raises
- #assert_respond_to
- #assert_same
- #assert_send
- #assert_silent
- #assert_throws
- #capture_io
- #capture_subprocess_io
- #diff
- #exception_details
- #flunk
- #message
- #mu_pp
- #mu_pp_for_diff
- #pass
- #refute
- #refute_empty
- #refute_equal
- #refute_in_delta
- #refute_in_epsilon
- #refute_includes
- #refute_instance_of
- #refute_kind_of
- #refute_match
- #refute_nil
- #refute_operator
- #refute_predicate
- #refute_respond_to
- #refute_same
- #skip
- #skipped?
- #synchronize
![[+]](../images/find.png "show/hide quicksearch"){kind=small}
MiniTest::Assertions
MiniTest Assertions. All assertion methods accept a
msg which is printed if the assertion fails.
Public Class Methods
Returns the diff command to use in diff. Tries to intelligently figure out what diff to use.
# File minitest/unit.rb, line 89
def self.diff
@diff = if (RbConfig::CONFIG['host_os'] =~ /mswin|mingw/ &&
system("diff.exe", __FILE__, __FILE__)) then
"diff.exe -u"
elsif Minitest::Unit::Guard.maglev? then # HACK
"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
Set the diff command to use in diff.
# File minitest/unit.rb, line 109
def self.diff= o
@diff = o
end
Public Instance Methods
Fails unless test is a true value.
# File minitest/unit.rb, line 196
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
Fails unless obj is empty.
# File minitest/unit.rb, line 209
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
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 227
def assert_equal exp, act, msg = nil
msg = message(msg, "") { diff exp, act }
assert exp == act, msg
end
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 238
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
For comparing Floats. Fails unless exp and act
have a relative error less than epsilon.
# File minitest/unit.rb, line 250
def assert_in_epsilon a, b, epsilon = 0.001, msg = nil
assert_in_delta a, b, [a.abs, b.abs].min * epsilon, msg
end
Fails unless collection includes obj.
# File minitest/unit.rb, line 257
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
Fails unless obj is an instance of cls.
# File minitest/unit.rb, line 268
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
Fails unless obj is a kind of cls.
# File minitest/unit.rb, line 279
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
Fails unless matcher =~ obj.
# File minitest/unit.rb, line 289
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
Fails unless obj is nil
# File minitest/unit.rb, line 299
def assert_nil obj, msg = nil
msg = message(msg) { "Expected #{mu_pp(obj)} to be nil" }
assert obj.nil?, msg
end
For testing with binary operators.
assert_operator 5, :<=, 4
# File minitest/unit.rb, line 309
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
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 325
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
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 348
def assert_predicate o1, op, msg = nil
msg = message(msg) { "Expected #{mu_pp(o1)} to be #{op}" }
assert o1.__send__(op), msg
end
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 357
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
Fails unless obj responds to meth.
# File minitest/unit.rb, line 389
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
Fails unless exp and act are equal?
# File minitest/unit.rb, line 399
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
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 413
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
Fails if the block outputs anything to stderr or stdout.
See also: assert_output
# File minitest/unit.rb, line 425
def assert_silent
assert_output "", "" do
yield
end
end
Fails unless the block throws sym
# File minitest/unit.rb, line 434
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
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 468
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
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 503
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
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 119
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 = %x#{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
Returns details for exception e
# File minitest/unit.rb, line 532
def exception_details e, msg
[
"#{msg}",
"Class: <#{e.class}>",
"Message: <#{e.message.inspect}>",
"---Backtrace---",
"#{MiniTest::filter_backtrace(e.backtrace).join("\n")}",
"---------------",
].join "\n"
end
Fails with msg
# File minitest/unit.rb, line 546
def flunk msg = nil
msg ||= "Epic Fail!"
assert false, msg
end
Returns a proc that will output msg along with the default
message.
# File minitest/unit.rb, line 554
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
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 169
def mu_pp obj
s = obj.inspect
s = s.encode Encoding.default_external if defined? Encoding
s
end
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 181
def mu_pp_for_diff obj
mu_pp(obj).gsub(/\n/, "\n").gsub(/:0x[a-fA-F0-9]{4,}/m, ':0xXXXXXX')
end
used for counting assertions
# File minitest/unit.rb, line 565
def pass msg = nil
assert true
end
Fails if test is a true value
# File minitest/unit.rb, line 572
def refute test, msg = nil
msg ||= "Failed refutation, no message given"
not assert(! test, msg)
end
Fails if obj is empty.
# File 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
Fails if exp == act.
For floats use refute_in_delta.
# File 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
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 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
For comparing Floats. Fails if exp and act have
a relative error less than epsilon.
# File 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
Fails if collection includes obj.
# File 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
Fails if obj is an instance of cls.
# File 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
Fails if obj is a kind of cls.
# File 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
Fails if matcher =~ obj.
# File 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
Fails if obj is nil.
# File 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
Fails if o1 is not op o2. Eg:
refute_operator 1, :>, 2 #=> pass refute_operator 1, :<, 2 #=> fail
# File 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
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 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
Fails if obj responds to the message meth.
# File 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
Fails if exp is the same (by object identity) as
act.
# File 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
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 716
def skip msg = nil, bt = caller
msg ||= "Skipped, no message given"
@skip = true
raise MiniTest::Skip, msg, bt
end
Commenting is here to help enhance the documentation. For example, code samples, or clarification of the documentation.
If you have questions about Ruby or the documentation, please post to one of the Ruby mailing lists. You will get better, faster, help that way.
If you wish to post a correction of the docs, please do so, but also file bug report so that it can be corrected for the next release. Thank you.
If you want to help improve the Ruby documentation, please visit Documenting-ruby.org.