module Minitest::Assertions - minitest-5.25.5 Documentation (original) (raw)

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.

Public Class Methods

Source

def self.diff return @diff if defined? @diff

@diff = if (RbConfig::CONFIG["host_os"] =~ /mswin|mingw/ and system "diff.exe", FILE, FILE) then "diff.exe -u" elsif system "gdiff", FILE, FILE then "gdiff -u" elsif system "diff", FILE, FILE then "diff -u" else nil end end

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

Source

def self.diff= o @diff = o end

Set the diff command to use in diff.

Public Instance Methods

Source

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

Fails unless test is truthy.

Source

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 obj is empty.

Source

def assert_equal exp, act, msg = nil msg = message(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 warn "DEPRECATED: Use assert_nil if expecting nil from #{_where}. This will fail in Minitest 6." end end

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

For floats use assert_in_delta.

See also: assert_output

Source

def assert_throws sym, msg = nil default = "Expected #{mu_pp sym} to have been thrown" caught = true value = catch sym do begin yield rescue ThreadError => e
default += ", not :#{e.message[/uncaught throw `(\w+?)'/, 1]}" rescue ArgumentError => e
raise e unless e.message.include? "uncaught throw" default += ", not #{e.message.split(/ /).last}" rescue NameError => e
raise e unless e.name == sym default += ", not #{e.name.inspect}" end caught = false end

assert caught, message(msg) { default } value rescue Assertion raise rescue => e raise UnexpectedError, e end

Fails unless the block throws sym

Source

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

  orig_stdout, orig_stderr = <span class="katex"><span class="katex-mathml"><math xmlns="http://www.w3.org/1998/Math/MathML"><semantics><mrow><mi>s</mi><mi>t</mi><mi>d</mi><mi>o</mi><mi>u</mi><mi>t</mi><mo separator="true">,</mo></mrow><annotation encoding="application/x-tex">stdout, </annotation></semantics></math></span><span class="katex-html" aria-hidden="true"><span class="base"><span class="strut" style="height:0.8889em;vertical-align:-0.1944em;"></span><span class="mord mathnormal">s</span><span class="mord mathnormal">t</span><span class="mord mathnormal">d</span><span class="mord mathnormal">o</span><span class="mord mathnormal">u</span><span class="mord mathnormal">t</span><span class="mpunct">,</span></span></span></span>stderr
  <span class="katex"><span class="katex-mathml"><math xmlns="http://www.w3.org/1998/Math/MathML"><semantics><mrow><mi>s</mi><mi>t</mi><mi>d</mi><mi>o</mi><mi>u</mi><mi>t</mi><mo separator="true">,</mo></mrow><annotation encoding="application/x-tex">stdout, </annotation></semantics></math></span><span class="katex-html" aria-hidden="true"><span class="base"><span class="strut" style="height:0.8889em;vertical-align:-0.1944em;"></span><span class="mord mathnormal">s</span><span class="mord mathnormal">t</span><span class="mord mathnormal">d</span><span class="mord mathnormal">o</span><span class="mord mathnormal">u</span><span class="mord mathnormal">t</span><span class="mpunct">,</span></span></span></span>stderr         = captured_stdout, captured_stderr

  yield

  return captured_stdout.string, captured_stderr.string
ensure
  $stdout = orig_stdout
  $stderr = orig_stderr
end

end end

Captures stdoutandstdout and stdoutandstderr 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.

Source

def capture_subprocess_io _synchronize do begin require "tempfile"

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

  orig_stdout, orig_stderr = <span class="katex"><span class="katex-mathml"><math xmlns="http://www.w3.org/1998/Math/MathML"><semantics><mrow><mi>s</mi><mi>t</mi><mi>d</mi><mi>o</mi><mi>u</mi><mi>t</mi><mi mathvariant="normal">.</mi><mi>d</mi><mi>u</mi><mi>p</mi><mo separator="true">,</mo></mrow><annotation encoding="application/x-tex">stdout.dup, </annotation></semantics></math></span><span class="katex-html" aria-hidden="true"><span class="base"><span class="strut" style="height:0.8889em;vertical-align:-0.1944em;"></span><span class="mord mathnormal">s</span><span class="mord mathnormal">t</span><span class="mord mathnormal">d</span><span class="mord mathnormal">o</span><span class="mord mathnormal">u</span><span class="mord mathnormal">t</span><span class="mord">.</span><span class="mord mathnormal">d</span><span class="mord mathnormal">u</span><span class="mord mathnormal">p</span><span class="mpunct">,</span></span></span></span>stderr.dup
  $stdout.reopen captured_stdout
  $stderr.reopen captured_stderr

  yield

  $stdout.rewind
  $stderr.rewind

  return captured_stdout.read, captured_stderr.read
ensure
  $stdout.reopen orig_stdout
  $stderr.reopen orig_stderr

  orig_stdout.close
  orig_stderr.close
  captured_stdout.close!
  captured_stderr.close!
end

end end

Captures stdoutandstdout and stdoutandstderr 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.

Source

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

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.

Source

def exception_details e, msg [ msg, "Class: <#{e.class}>", "Message: <#{e.message.inspect}>", "---Backtrace---", Minitest.filter_backtrace(e.backtrace), "---------------", ].join "\n" end

Returns details for exception e

Source

def fail_after y, m, d, msg flunk msg if Time.now > Time.local(y, m, d) end

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.

Source

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

Fails with msg.

Source

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

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

Source

def mu_pp obj s = obj.inspect.encode Encoding.default_external

return s unless String === obj && (obj.encoding != Encoding.default_external || !obj.valid_encoding?)

enc = "# encoding: #{obj.encoding}" val = "# valid: #{obj.valid_encoding?}"

[enc, val, s].join "\n" end

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

See Minitest::Test.make_my_diffs_pretty!

Source

def mu_pp_for_diff obj str = mu_pp obj

single = str.match?(/(?<!\|^)\n/) double = str.match?(/(?<=\|^)\n/)

process = if single ^ double then if single then lambda { |s| s == "\n" ? "\n" : s } else lambda { |s| s == "\\n" ? "\n\n" : s } end else :itself
end

str .gsub(/\?\n/, &process) .gsub(/:0x[a-fA-F0-9]{4,}/m, ":0xXXXXXX") end

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.

Source

def pass _msg = nil assert true end

used for counting assertions

Source

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

Fails if test is truthy.

Source

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 obj is empty.

Source

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

Fails if exp == act.

For floats use refute_in_delta.

Source

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 is within delta of act.

refute_in_delta Math::PI, (22.0 / 7.0)

Source

def refute_in_epsilon a, b, epsilon = 0.001, msg = nil refute_in_delta a, b, a * epsilon, msg end

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

Source

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 collection includes obj.

Source

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 an instance of cls.

Source

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

Fails if obj is a kind of cls.

Source

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 matcher =~ obj.

Source

def refute_nil obj, msg = nil msg = message(msg) { "Expected #{mu_pp obj} to not be nil" } refute obj.nil?, msg end

Fails if obj is nil.

Source

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

Fails if o1 is not op o2. Eg:

refute_operator 1, :>, 2 refute_operator 1, :<, 2

Source

def refute_path_exists path, msg = nil msg = message(msg) { "Expected path '#{path}' to not exist" } refute File.exist?(path), msg end

Fails if path exists.

Source

def refute_pattern raise NotImplementedError, "only available in Ruby 3.0+" unless RUBY_VERSION >= "3.0" flunk "refute_pattern requires a block to capture errors." unless block_given?

begin yield flunk "NoMatchingPatternError expected, but nothing was raised." rescue NoMatchingPatternError pass end end

For testing with pattern matching (only supported with Ruby 3.0 and later)

refute_pattern { [1,2,3] => [String] }

refute_pattern { [1,2,3] => [Integer, Integer, Integer] }

This assertion expects a NoMatchingPatternError exception, and will fail if none is raised. Any other exceptions will be raised as normal and generate a test error.

Source

def refute_predicate o1, op, msg = nil msg = message(msg) { "Expected #{mu_pp o1} to not be #{op}" } refute o1.send(op), 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?

Source

def refute_respond_to obj, meth, msg = nil, include_all: false msg = message(msg) { "Expected #{mu_pp obj} to not respond to #{meth}" }

refute obj.respond_to?(meth, include_all), msg end

Fails if obj responds to the message meth. include_all defaults to false to match Object#respond_to?

Source

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

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

Source

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

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.

Source

def skip_until y, m, d, msg skip msg if Time.now < Time.local(y, m, d) where = caller(1..1).first.rpartition(":in").reject(&:empty?).first warn "Stale skip_until %p at %s" % [msg, where] end

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.

Source

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

Was this testcase skipped? Meant for teardown.

Source

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

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.