module 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 lib/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
Public Instance Methods
Fails unless test
is a true value.
# File lib/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 lib/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 lib/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 lib/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 lib/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 lib/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 lib/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 lib/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 lib/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 lib/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 lib/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 lib/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 lib/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 lib/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 lib/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 lib/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 lib/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 lib/minitest/unit.rb, line 425 def assert_silent assert_output "", "" do yield end end
Fails unless the block throws sym
# File lib/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 lib/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 lib/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 lib/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 lib/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 lib/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 lib/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 lib/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 lib/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 lib/minitest/unit.rb, line 565 def pass msg = nil assert true end
Fails if test
is a true value
# File lib/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 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
Fails if exp == act
.
For floats use refute_in_delta.
# 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
For comparing Floats. Fails if exp
is within
delta
of act
.
refute_in_delta Math::PI, (22.0 / 7.0)
# 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
For comparing Floats. Fails if exp
and act
have
a relative error less than epsilon
.
# 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
Fails if collection
includes obj
.
# 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
Fails if obj
is an instance of cls
.
# 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
Fails if obj
is a kind of cls
.
# 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
Fails if matcher
=~
obj
.
# 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
Fails if obj
is nil.
# 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
Fails if o1
is not op
o2
. Eg:
refute_operator 1, :>, 2 #=> pass refute_operator 1, :<, 2 #=> fail
# 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
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 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
Fails if obj
responds to the message meth
.
# 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
Fails if exp
is the same (by object identity) as
act
.
# 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
Skips the current test. Gets listed at the end of the run but doesn't cause a failure exit code.
# File lib/minitest/unit.rb, line 716 def skip msg = nil, bt = caller msg ||= "Skipped, no message given" @skip = true raise MiniTest::Skip, msg, bt end
Was this testcase skipped? Meant for teardown.
# File lib/minitest/unit.rb, line 725 def skipped? defined?(@skip) and @skip end
Takes a block and wraps it with the runner's shared mutex.
# File lib/minitest/unit.rb, line 732 def synchronize Minitest::Unit.runner.synchronize do yield end end