module Minitest::Assertions - minitest-5.7.0 Documentation

# module Minitest::Assertions

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

diff() click to toggle source

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

    # File lib/minitest/assertions.rb, line 27
    def self.diff
      @diff = if (RbConfig::CONFIG["host_os"] =~ /mswin|mingw/ &&
                  system("diff.exe", __FILE__, __FILE__)) then
                "diff.exe -u"
              elsif Minitest::Test.maglev? then
                "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

diff=(o) click to toggle source

Set the diff command to use in diff.

    # File lib/minitest/assertions.rb, line 47
    def self.diff= o
      @diff = o
    end

### Public Instance Methods

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

Fails unless `test` is truthy.

    # File lib/minitest/assertions.rb, line 124
    def assert test, msg = nil
      self.assertions += 1
      unless test then
        msg ||= "Failed assertion, no message given."
        msg = msg.call if Proc === msg
        raise Minitest::Assertion, msg
      end
      true
    end

assert_empty(obj, msg = nil) click to toggle source

Fails unless `obj` is empty.

    # File lib/minitest/assertions.rb, line 141
    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 lib/minitest/assertions.rb, line 161
    def assert_equal exp, act, msg = nil
      msg = message(msg, E) { 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 lib/minitest/assertions.rb, line 172
    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 lib/minitest/assertions.rb, line 184
    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 lib/minitest/assertions.rb, line 191
    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 lib/minitest/assertions.rb, line 202
    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 lib/minitest/assertions.rb, line 213
    def assert_kind_of cls, obj, msg = nil
      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 lib/minitest/assertions.rb, line 223
    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 lib/minitest/assertions.rb, line 233
    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. Eg:

    assert_operator 5, :<=, 4

    # File lib/minitest/assertions.rb, line 243
    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 lib/minitest/assertions.rb, line 259
    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. Eg:

    assert_predicate str, :empty?

This is really meant for specs and is front-ended by #assert_operator:

    str.must_be :empty?

    # File lib/minitest/assertions.rb, line 282
    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.

`exp` takes an optional message on the end to help explain failures and defaults to StandardError if no exception class is passed.

    # File lib/minitest/assertions.rb, line 295
    def assert_raises *exp
      msg = "#{exp.pop}.\n" if String === exp.last
      exp << StandardError if exp.empty?

      begin
        yield
      rescue Minitest::Skip => e
        return e if exp.include? Minitest::Skip
        raise e
      rescue Exception => e
        expected = exp.any? { |ex| e.kind_of? ex }

        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 lib/minitest/assertions.rb, line 322
    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 lib/minitest/assertions.rb, line 332
    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

    # File lib/minitest/assertions.rb, line 345
    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 lib/minitest/assertions.rb, line 357
    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 lib/minitest/assertions.rb, line 366
    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 lib/minitest/assertions.rb, line 400
    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() { || ... } 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 lib/minitest/assertions.rb, line 433
    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
        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 lib/minitest/assertions.rb, line 57
    def diff exp, act
      expect = mu_pp_for_diff exp
      butwas = mu_pp_for_diff act
      result = nil

      need_to_diff =
        (expect.include?("\n")    ||
         butwas.include?("\n")    ||
         expect.size > 30         ||
         butwas.size > 30         ||
         expect == butwas)        &&
        Minitest::Assertions.diff

      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

exception_details(e, msg) click to toggle source

Returns details for exception `e`

    # File lib/minitest/assertions.rb, line 462
    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 lib/minitest/assertions.rb, line 476
    def flunk msg = nil
      msg ||= "Epic Fail!"
      assert false, msg
    end

message(msg = nil, ending = nil, &default) click to toggle source

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

    # File lib/minitest/assertions.rb, line 484
    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

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 lib/minitest/assertions.rb, line 105
    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 lib/minitest/assertions.rb, line 117
    def mu_pp_for_diff obj
      mu_pp(obj).gsub(/\n/, "\n").gsub(/:0x[a-fA-F0-9]{4,}/m, ":0xXXXXXX")
    end

pass(_msg = nil) click to toggle source

used for counting assertions

    # File lib/minitest/assertions.rb, line 495
    def pass _msg = nil
      assert true
    end

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

Fails if `test` is truthy.

    # File lib/minitest/assertions.rb, line 502
    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 lib/minitest/assertions.rb, line 510
    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 lib/minitest/assertions.rb, line 521
    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 lib/minitest/assertions.rb, line 533
    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 lib/minitest/assertions.rb, line 545
    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 lib/minitest/assertions.rb, line 552
    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 lib/minitest/assertions.rb, line 563
    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 lib/minitest/assertions.rb, line 573
    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

refute_match(matcher, obj, msg = nil) click to toggle source

Fails if `matcher` `=~` `obj`.

    # File lib/minitest/assertions.rb, line 581
    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 lib/minitest/assertions.rb, line 591
    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 lib/minitest/assertions.rb, line 602
    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 lib/minitest/assertions.rb, line 617
    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 lib/minitest/assertions.rb, line 625
    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 lib/minitest/assertions.rb, line 634
    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 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.

    # File lib/minitest/assertions.rb, line 647
    def skip msg = nil, bt = caller
      msg ||= "Skipped, no message given"
      @skip = true
      raise Minitest::Skip, msg, bt
    end

skipped?() click to toggle source

Was this testcase skipped? Meant for teardown.

    # File lib/minitest/assertions.rb, line 656
    def skipped?
      defined?(@skip) and @skip
    end