Module: Minitest::Assertions
Relationships & Source Files | |
Extension / Inclusion / Inheritance Descendants | |
Included In:
| |
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 Runnable for an example.
Class Attribute Summary
Instance Attribute Summary
-
#skipped? ⇒ Boolean
readonly
Was this testcase skipped? Meant for
#teardown
.
Instance Method Summary
-
#assert(test, msg = nil)
Fails unless
test
is truthy. -
#assert_empty(obj, msg = nil)
Fails unless
obj
is empty. -
#assert_equal(exp, act, msg = nil)
Fails unless
exp == act
printing the difference between the two, if possible. -
#assert_in_delta(exp, act, delta = 0.001, msg = nil)
For comparing Floats.
-
#assert_in_epsilon(exp, act, epsilon = 0.001, msg = nil)
For comparing Floats.
-
#assert_includes(collection, obj, msg = nil)
Fails unless
collection
includesobj
. -
#assert_instance_of(cls, obj, msg = nil)
Fails unless
obj
is an instance ofcls
. -
#assert_kind_of(cls, obj, msg = nil)
Fails unless
obj
is a kind ofcls
. -
#assert_match(matcher, obj, msg = nil)
Fails unless
matcher
=~
obj
. -
#assert_mock(mock)
Assert that the mock verifies correctly.
-
#assert_nil(obj, msg = nil)
Fails unless
obj
is nil. -
#assert_operator(o1, op, o2 = UNDEFINED, msg = nil)
For testing with binary operators.
-
#assert_output(stdout = nil, stderr = nil)
Fails if stdout or stderr do not output the expected results.
-
#assert_path_exists(path, msg = nil)
Fails unless
path
exists. -
#assert_predicate(o1, op, msg = nil)
For testing with predicates.
-
#assert_raises(*exp)
Fails unless the block raises one of
exp
. -
#assert_respond_to(obj, meth, msg = nil)
Fails unless
obj
responds tometh
. -
#assert_same(exp, act, msg = nil)
Fails unless
exp
andact
are#equal?
-
#assert_send(send_ary, m = nil)
send_ary
is a receiver, message and arguments. -
#assert_silent
Fails if the block outputs anything to stderr or stdout.
-
#assert_throws(sym, msg = nil)
Fails unless the block throws
sym
-
#capture_io
Captures $stdout and $stderr into strings:
-
#capture_subprocess_io
Captures $stdout and $stderr into strings, using Tempfile to ensure that subprocess IO is captured as well.
-
#diff(exp, act)
Returns a diff between
exp
andact
. -
#exception_details(e, msg)
Returns details for exception
e
-
#fail_after(y, m, d, msg)
Fails after a given date (in the local time zone).
-
#flunk(msg = nil)
Fails with
msg
. -
#message(msg = nil, ending = nil, &default)
Returns a proc that will output
msg
along with the default message. -
#mu_pp(obj)
This returns a human-readable version of
obj
. -
#mu_pp_for_diff(obj)
This returns a diff-able more human-readable version of
obj
. -
#pass(_msg = nil)
used for counting assertions.
-
#refute(test, msg = nil)
Fails if
test
is truthy. -
#refute_empty(obj, msg = nil)
Fails if
obj
is empty. -
#refute_equal(exp, act, msg = nil)
Fails if
exp == act
. -
#refute_in_delta(exp, act, delta = 0.001, msg = nil)
For comparing Floats.
-
#refute_in_epsilon(a, b, epsilon = 0.001, msg = nil)
For comparing Floats.
-
#refute_includes(collection, obj, msg = nil)
Fails if
collection
includesobj
. -
#refute_instance_of(cls, obj, msg = nil)
Fails if
obj
is an instance ofcls
. -
#refute_kind_of(cls, obj, msg = nil)
Fails if
obj
is a kind ofcls
. -
#refute_match(matcher, obj, msg = nil)
Fails if
matcher
=~
obj
. -
#refute_nil(obj, msg = nil)
Fails if
obj
is nil. -
#refute_operator(o1, op, o2 = UNDEFINED, msg = nil)
Fails if
o1
is notop
o2
. -
#refute_path_exists(path, msg = nil)
Fails if
path
exists. -
#refute_predicate(o1, op, msg = nil)
For testing with predicates.
-
#refute_respond_to(obj, meth, msg = nil)
Fails if
obj
responds to the messagemeth
. -
#refute_same(exp, act, msg = nil)
Fails if
exp
is the same (by object identity) asact
. -
#skip(msg = nil, bt = caller)
Skips the current run.
-
#skip_until(y, m, d, msg)
Skips the current run until a given date (in the local time zone).
-
#things_to_diff(exp, act)
Returns things to diff [expect, butwas], or [nil, nil] if nothing to diff.
Class Attribute Details
.diff (rw)
Returns the diff command to use in #diff. Tries to intelligently figure out what diff to use.
# File 'lib/minitest/assertions.rb', line 29
def self.diff return @diff if defined? @diff @diff = if (RbConfig::CONFIG["host_os"] =~ /mswin|mingw/ && system("diff.exe", __FILE__, __FILE__)) then "diff.exe -u" elsif system("gdiff", __FILE__, __FILE__) "gdiff -u" # solaris and kin suck elsif system("diff", __FILE__, __FILE__) "diff -u" else nil end end
.diff=(o) (rw)
Set the diff command to use in #diff.
# File 'lib/minitest/assertions.rb', line 47
def self.diff= o @diff = o end
Instance Attribute Details
#skipped? ⇒ Boolean
(readonly)
Was this testcase skipped? Meant for #teardown
.
# File 'lib/minitest/assertions.rb', line 803
def skipped? defined?(@skip) and @skip end
Instance Method Details
#assert(test, msg = nil)
Fails unless test
is truthy.
#assert_empty(obj, msg = nil)
Fails unless obj
is empty.
# File 'lib/minitest/assertions.rb', line 195
def assert_empty obj, msg = nil msg = (msg) { "Expected #{mu_pp(obj)} to be empty" } assert_respond_to obj, :empty? assert obj.empty?, msg end
#assert_equal(exp, act, msg = nil)
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 Test.make_my_diffs_pretty!
For floats use assert_in_delta.
See also: .diff
# File 'lib/minitest/assertions.rb', line 216
def assert_equal exp, act, msg = nil msg = (msg, E) { diff exp, act } result = assert exp == act, msg if nil == exp then if Minitest::VERSION =~ /^6/ then refute_nil exp, "Use assert_nil if expecting nil." else where = Minitest.filter_backtrace(caller).first where = where.split(/:in /, 2).first # clean up noise warn "DEPRECATED: Use assert_nil if expecting nil from #{where}. This will fail in Minitest 6." end end result end
#assert_in_delta(exp, act, delta = 0.001, msg = nil)
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/assertions.rb', line 240
def assert_in_delta exp, act, delta = 0.001, msg = nil n = (exp - act).abs msg = (msg) { "Expected |#{exp} - #{act}| (#{n}) to be <= #{delta}" } assert delta >= n, msg end
#assert_in_epsilon(exp, act, epsilon = 0.001, msg = nil)
For comparing Floats. Fails unless exp
and act
have a relative error less than epsilon
.
# File 'lib/minitest/assertions.rb', line 252
def assert_in_epsilon exp, act, epsilon = 0.001, msg = nil assert_in_delta exp, act, [exp.abs, act.abs].min * epsilon, msg end
#assert_includes(collection, obj, msg = nil)
Fails unless collection
includes obj
.
# File 'lib/minitest/assertions.rb', line 259
def assert_includes collection, obj, msg = nil msg = (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)
Fails unless obj
is an instance of cls
.
#assert_kind_of(cls, obj, msg = nil)
Fails unless obj
is a kind of cls
.
#assert_match(matcher, obj, msg = nil)
Fails unless matcher
=~
obj
.
# File 'lib/minitest/assertions.rb', line 291
def assert_match matcher, obj, msg = nil msg = (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)
Assert that the mock verifies correctly.
# File 'lib/minitest/mock.rb', line 184
def assert_mock mock assert mock.verify end
#assert_nil(obj, msg = nil)
Fails unless obj
is nil
#assert_operator(o1, op, o2 = UNDEFINED, msg = nil)
For testing with binary operators. Eg:
assert_operator 5, :<=, 4
#assert_output(stdout = nil, stderr = nil)
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
# File 'lib/minitest/assertions.rb', line 329
def assert_output stdout = nil, stderr = nil flunk "assert_output requires a block to capture output." unless block_given? 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) rescue Assertion raise rescue => e raise UnexpectedError, e end
#assert_path_exists(path, msg = nil)
Fails unless path
exists.
# File 'lib/minitest/assertions.rb', line 353
def assert_path_exists path, msg = nil msg = (msg) { "Expected path '#{path}' to exist" } assert File.exist?(path), msg end
#assert_predicate(o1, op, msg = nil)
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?
#assert_raises(*exp)
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. Eg:
assert_raises(CustomError) { method_with_custom_error }
With custom error message:
assert_raises(CustomError, 'This should have raised CustomError') { method_with_custom_error }
Using the returned object:
error = assert_raises(CustomError) do
raise CustomError, 'This is really bad'
end
assert_equal 'This is really bad', error.
# File 'lib/minitest/assertions.rb', line 394
def assert_raises *exp flunk "assert_raises requires a block to capture errors." unless block_given? 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::Assertion # incl Skip & UnexpectedError # 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)
Fails unless obj
responds to meth
.
#assert_same(exp, act, msg = nil)
Fails unless exp
and act
are #equal?
#assert_send(send_ary, m = nil)
send_ary
is a receiver, message and arguments.
Fails unless the call returns a true value
# File 'lib/minitest/assertions.rb', line 448
def assert_send send_ary, m = nil where = Minitest.filter_backtrace(caller).first where = where.split(/:in /, 2).first # clean up noise warn "DEPRECATED: assert_send. From #{where}" recv, msg, *args = send_ary m = (m) { "Expected #{mu_pp(recv)}.#{msg}(*#{mu_pp(args)}) to return true" } assert recv.__send__(msg, *args), m end
#assert_silent
Fails if the block outputs anything to stderr or stdout.
See also: #assert_output
# File 'lib/minitest/assertions.rb', line 464
def assert_silent assert_output "", "" do yield end end
#assert_throws(sym, msg = nil)
Fails unless the block throws sym
# File 'lib/minitest/assertions.rb', line 473
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. [/uncaught throw \`(\w+?)\'/, 1]}" rescue ArgumentError => e # 1.9 exception raise e unless e. .include?("uncaught throw") default += ", not #{e. .split(/ /).last}" rescue NameError => e # 1.8 exception raise e unless e.name == sym default += ", not #{e.name.inspect}" end caught = false end assert caught, (msg) { default } rescue Assertion raise rescue => e raise UnexpectedError, e end
#capture_io
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/assertions.rb', line 513
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
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/assertions.rb', line 546
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 orig_stdout.close orig_stderr.close captured_stdout.close captured_stderr.close end end end
#diff(exp, act)
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.
See #things_to_diff for more info.
# File 'lib/minitest/assertions.rb', line 59
def diff exp, act result = nil expect, butwas = things_to_diff(exp, act) return "Expected: #{mu_pp exp}\n Actual: #{mu_pp act}" unless expect 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)
Returns details for exception e
# File 'lib/minitest/assertions.rb', line 580
def exception_details e, msg [ "#{msg}", "Class: <#{e.class}>", "Message: <#{e. .inspect}>", "---Backtrace---", "#{Minitest.filter_backtrace(e.backtrace).join("\n")}", "---------------", ].join "\n" end
#fail_after(y, m, d, msg)
Fails after a given date (in the local time zone). This allows you to put time-bombs in your tests if you need to keep something around until a later date lest you forget about it.
# File 'lib/minitest/assertions.rb', line 596
def fail_after y,m,d,msg flunk msg if Time.now > Time.local(y, m, d) end
#flunk(msg = nil)
Fails with msg
.
# File 'lib/minitest/assertions.rb', line 603
def flunk msg = nil msg ||= "Epic Fail!" assert false, msg end
#message(msg = nil, ending = nil, &default)
Returns a proc that will output msg
along with the default message.
# File 'lib/minitest/assertions.rb', line 611
def msg = nil, ending = nil, &default proc { msg = msg.call.chomp(".") if Proc === msg = "#{msg}.\n" unless msg.nil? or msg.to_s.empty? "#{}#{default.call}#{ending || "."}" } end
#mu_pp(obj)
This returns a human-readable version of obj
. By default #inspect
is called. You can override this to use #pretty_inspect
if you want.
# File 'lib/minitest/assertions.rb', line 129
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 || !obj.valid_encoding?) then enc = "# encoding: #{obj.encoding}" val = "# valid: #{obj.valid_encoding?}" s = "#{enc}\n#{val}\n#{s}" end end s end
#mu_pp_for_diff(obj)
This returns a diff-able more human-readable version of obj
. This differs from the regular mu_pp because it expands escaped newlines and makes hex-values (like object_ids) generic. This uses mu_pp to do the first pass and then cleans it up.
# File 'lib/minitest/assertions.rb', line 152
def mu_pp_for_diff obj str = mu_pp obj # both '\n' & '\\n' (_after_ mu_pp (aka inspect)) single = !!str.match(/(?<!\\|^)\\n/) double = !!str.match(/(?<=\\|^)\\n/) process = if single ^ double then if single then lambda { |s| s == "\\n" ? "\n" : s } # unescape else lambda { |s| s == "\\\\n" ? "\\n\n" : s } # unescape a bit, add nls end else :itself # leave it alone end str. gsub(/\\?\\n/, &process). gsub(/:0x[a-fA-F0-9]{4,}/m, ":0xXXXXXX") # anonymize hex values end
#pass(_msg = nil)
used for counting assertions
# File 'lib/minitest/assertions.rb', line 622
def pass _msg = nil assert true end
#refute(test, msg = nil)
Fails if test
is truthy.
#refute_empty(obj, msg = nil)
Fails if obj
is empty.
# File 'lib/minitest/assertions.rb', line 637
def refute_empty obj, msg = nil msg = (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)
Fails if exp == act
.
For floats use refute_in_delta.
#refute_in_delta(exp, act, delta = 0.001, msg = nil)
For comparing Floats. Fails if exp
is within delta
of act
.
refute_in_delta Math::PI, (22.0 / 7.0)
# File 'lib/minitest/assertions.rb', line 660
def refute_in_delta exp, act, delta = 0.001, msg = nil n = (exp - act).abs msg = (msg) { "Expected |#{exp} - #{act}| (#{n}) to not be <= #{delta}" } refute delta >= n, msg end
#refute_in_epsilon(a, b, epsilon = 0.001, msg = nil)
For comparing Floats. Fails if exp
and act
have a relative error less than epsilon
.
# File 'lib/minitest/assertions.rb', line 672
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)
Fails if collection
includes obj
.
# File 'lib/minitest/assertions.rb', line 679
def refute_includes collection, obj, msg = nil msg = (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)
Fails if obj
is an instance of cls
.
#refute_kind_of(cls, obj, msg = nil)
Fails if obj
is a kind of cls
.
#refute_match(matcher, obj, msg = nil)
Fails if matcher
=~
obj
.
# File 'lib/minitest/assertions.rb', line 708
def refute_match matcher, obj, msg = nil msg = (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)
Fails if obj
is nil.
#refute_operator(o1, op, o2 = UNDEFINED, msg = nil)
Fails if o1
is not op
o2
. Eg:
refute_operator 1, :>, 2 #=> pass
refute_operator 1, :<, 2 #=> fail
#refute_path_exists(path, msg = nil)
Fails if path
exists.
# File 'lib/minitest/assertions.rb', line 738
def refute_path_exists path, msg = nil msg = (msg) { "Expected path '#{path}' to not exist" } refute File.exist?(path), msg end
#refute_predicate(o1, op, msg = nil)
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?
#refute_respond_to(obj, meth, msg = nil)
Fails if obj
responds to the message meth
.
#refute_same(exp, act, msg = nil)
Fails if exp
is the same (by object identity) as act
.
#skip(msg = nil, bt = caller)
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.
#skip_until(y, m, d, msg)
Skips the current run until a given date (in the local time zone). This allows you to put some fixes on hold until a later date, but still holds you accountable and prevents you from forgetting it.
# File 'lib/minitest/assertions.rb', line 794
def skip_until y,m,d,msg skip msg if Time.now < Time.local(y, m, d) where = caller.first.split(/:/, 3).first(2).join ":" warn "Stale skip_until %p at %s" % [msg, where] end
#things_to_diff(exp, act)
Returns things to diff [expect, butwas], or [nil, nil] if nothing to diff.
Criterion:
-
Strings include newlines or escaped newlines, but not both.
-
or: String lengths are > 30 characters.
-
or: Strings are equal to each other (but maybe different encodings?).
-
and: we found a diff executable.
# File 'lib/minitest/assertions.rb', line 104
def things_to_diff exp, act expect = mu_pp_for_diff exp butwas = mu_pp_for_diff act e1, e2 = expect.include?("\n"), expect.include?("\\n") b1, b2 = butwas.include?("\n"), butwas.include?("\\n") need_to_diff = (e1 ^ e2 || b1 ^ b2 || expect.size > 30 || butwas.size > 30 || expect == butwas) && Minitest::Assertions.diff need_to_diff && [expect, butwas] end