minitest-mock 5.27.0.beta.1.beta.1

data/Manifest.txt

@@ -0,0 +1,7 @@
+History.rdoc
+Manifest.txt
+README.rdoc
+Rakefile
+lib/minitest/mock.rb
+test/minitest/metametameta.rb
+test/minitest/test_minitest_mock.rb

data/README.rdoc

@@ -0,0 +1,139 @@
+= minitest/mock
+
+home :: https://minite.st/
+code :: https://github.com/minitest/minitest-mock
+bugs :: https://github.com/minitest/minitest-mock/issues
+rdoc :: https://docs.seattlerb.org/minitest-mock
+clog :: https://github.com/minitest/minitest-mock/blob/main/History.rdoc
+
+== DESCRIPTION:
+
+minitest/mock, by Steven Baker, is a beautifully tiny mock (and stub)
+object framework.
+
+The minitest-mock gem is an extraction of minitest/mock.rb from
+minitest in order to make it easier to maintain independent of
+minitest.
+
+== FEATURES/PROBLEMS:
+
+* minitest/mock - a simple and clean mock/stub system.
+* Written by squishy human beings. Software can never be perfect. We will all eventually die.
+
+== SYNOPSIS:
+
+=== Mocks
+
+Mocks and stubs defined using terminology by Fowler & Meszaros at
+https://www.martinfowler.com/bliki/TestDouble.html:
+
+"Mocks are pre-programmed with expectations which form a specification
+of the calls they are expected to receive. They can throw an exception
+if they receive a call they don't expect and are checked during
+verification to ensure they got all the calls they were expecting."
+
+  class MemeAsker
+    def initialize(meme)
+      @meme = meme
+    end
+
+    def ask(question)
+      method = question.tr(" ", "_") + "?"
+      @meme.__send__(method)
+    end
+  end
+
+  require "minitest/autorun"
+
+  describe MemeAsker, :ask do
+    describe "when passed an unpunctuated question" do
+      it "should invoke the appropriate predicate method on the meme" do
+        @meme = Minitest::Mock.new
+        @meme_asker = MemeAsker.new @meme
+        @meme.expect :will_it_blend?, :return_value
+
+        @meme_asker.ask "will it blend"
+
+        @meme.verify
+      end
+    end
+  end
+
+==== Multi-threading and Mocks
+
+Minitest mocks do not support multi-threading. If it works, fine, if it doesn't
+you can use regular ruby patterns and facilities like local variables. Here's
+an example of asserting that code inside a thread is run:
+
+  def test_called_inside_thread
+    called = false
+    pr = Proc.new { called = true }
+    thread = Thread.new(&pr)
+    thread.join
+    assert called, "proc not called"
+  end
+
+=== Stubs
+
+Mocks and stubs are defined using terminology by Fowler & Meszaros at
+https://www.martinfowler.com/bliki/TestDouble.html:
+
+"Stubs provide canned answers to calls made during the test".
+
+Minitest's stub method overrides a single method for the duration of
+the block.
+
+  def test_stale_eh
+    obj_under_test = Something.new
+
+    refute obj_under_test.stale?
+
+    Time.stub :now, Time.at(0) do   # stub goes away once the block is done
+      assert obj_under_test.stale?
+    end
+  end
+
+A note on stubbing: In order to stub a method, the method must
+actually exist prior to stubbing. Use a singleton method to create a
+new non-existing method:
+
+  def obj_under_test.fake_method
+    ...
+  end
+
+== REQUIREMENTS:
+
+* Ruby 3+. No magic is involved. I hope.
+
+== INSTALL:
+
+  gem install minitest-mock
+
+or
+
+  bundle add minitest-mock
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) Ryan Davis, seattle.rb
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,31 @@
+# -*- ruby -*-
+
+require "hoe"
+$:.unshift "lib" # to pick up lib/minitest/test_task.rb when minitest not installed
+
+Hoe.plugin :minitest, :history, :email # seattlerb - perforce
+Hoe.plugin :rdoc
+Hoe.plugin :isolate
+Hoe.plugin :halostatue
+
+require "hoe/halostatue" # minor hack - I hate gemspec2's output
+Hoe.plugins.delete :gemspec2
+
+Hoe.spec "minitest-mock" do
+  developer "Ryan Davis", "ryand-ruby@zenspider.com"
+
+  license "MIT"
+
+  dependency "hoe-halostatue", "~> 2.1", :dev
+
+  require_ruby_version ">= 3.1"
+
+  self.checklist.clear
+end
+
+Minitest::TestTask.create :testW0 do |t|
+  t.warning = false
+  t.test_prelude = "$-w = nil"
+end
+
+# vim: syntax=Ruby

data/lib/minitest/mock.rb

@@ -0,0 +1,329 @@
+class MockExpectationError < StandardError; end # :nodoc:
+
+module Minitest # :nodoc:
+
+  ##
+  # A simple and clean mock object framework.
+  #
+  # All mock objects are an instance of Mock
+
+  class Mock
+    VERSION = "5.27.0.beta.1" # :nodoc:
+
+    alias __respond_to? respond_to?
+
+    overridden_methods = %i[
+      ===
+      class
+      inspect
+      instance_eval
+      instance_variables
+      object_id
+      public_send
+      respond_to_missing?
+      send
+      to_s
+    ]
+
+    overridden_methods << :singleton_method_added if defined?(::DEBUGGER__)
+
+    instance_methods.each do |m|
+      undef_method m unless overridden_methods.include?(m) || m =~ /^__/
+    end
+
+    overridden_methods.map(&:to_sym).each do |method_id|
+      old_w, $-w = $-w, nil
+      define_method method_id do |*args, **kwargs, &b|
+        if @expected_calls.key? method_id then
+          method_missing(method_id, *args, **kwargs, &b)
+        else
+          super(*args, **kwargs, &b)
+        end
+      end
+    ensure
+      $-w = old_w
+    end
+
+    def initialize delegator = nil # :nodoc:
+      @delegator = delegator
+      @expected_calls = Hash.new { |calls, name| calls[name] = [] }
+      @actual_calls   = Hash.new { |calls, name| calls[name] = [] }
+    end
+
+    @@KW_WARNED = false # :nodoc:
+
+    ##
+    # Expect that method +name+ is called, optionally with +args+ (and
+    # +kwargs+ or a +blk+), and returns +retval+.
+    #
+    #   @mock.expect(:meaning_of_life, 42)
+    #   @mock.meaning_of_life # => 42
+    #
+    #   @mock.expect(:do_something_with, true, [some_obj, true])
+    #   @mock.do_something_with(some_obj, true) # => true
+    #
+    #   @mock.expect(:do_something_else, true) do |a1, a2|
+    #     a1 == "buggs" && a2 == :bunny
+    #   end
+    #
+    # +args+ is compared to the expected args using case equality (ie, the
+    # '===' operator), allowing for less specific expectations.
+    #
+    #   @mock.expect(:uses_any_string, true, [String])
+    #   @mock.uses_any_string("foo") # => true
+    #   @mock.verify  # => true
+    #
+    #   @mock.expect(:uses_one_string, true, ["foo"])
+    #   @mock.uses_one_string("bar") # => raises MockExpectationError
+    #
+    # If a method will be called multiple times, specify a new expect for each one.
+    # They will be used in the order you define them.
+    #
+    #   @mock.expect(:ordinal_increment, 'first')
+    #   @mock.expect(:ordinal_increment, 'second')
+    #
+    #   @mock.ordinal_increment # => 'first'
+    #   @mock.ordinal_increment # => 'second'
+    #   @mock.ordinal_increment # => raises MockExpectationError "No more expects available for :ordinal_increment"
+    #
+
+    def expect name, retval, args = [], **kwargs, &blk
+      name = name.to_sym
+
+      if blk then
+        raise ArgumentError, "args ignored when block given" unless args.empty?
+        raise ArgumentError, "kwargs ignored when block given" unless kwargs.empty?
+        @expected_calls[name] << { :retval => retval, :block => blk }
+      else
+        raise ArgumentError, "args must be an array" unless Array === args
+
+        if ENV["MT_KWARGS_HAC\K"] && (Hash === args.last ||
+                                      Hash ==  args.last) then
+          if kwargs.empty? then
+            kwargs = args.pop
+          else
+            unless @@KW_WARNED then
+              from = caller(1..1).first
+              warn "Using MT_KWARGS_HAC\K yet passing kwargs. From #{from}"
+              @@KW_WARNED = true
+            end
+          end
+        end
+
+        @expected_calls[name] <<
+          { :retval => retval, :args => args, :kwargs => kwargs }
+      end
+      self
+    end
+
+    def __call name, data # :nodoc:
+      case data
+      when Hash then
+        args   = data[:args].inspect[1..-2]
+        kwargs = data[:kwargs]
+        if kwargs && !kwargs.empty? then
+          args << ", " unless args.empty?
+          args << kwargs.inspect[1..-2]
+        end
+        "#{name}(#{args}) => #{data[:retval].inspect}"
+      else
+        data.map { |d| __call name, d }.join ", "
+      end
+    end
+
+    ##
+    # Verify that all methods were called as expected. Raises
+    # +MockExpectationError+ if the mock object was not called as
+    # expected.
+
+    def verify
+      @expected_calls.each do |name, expected|
+        actual = @actual_calls.fetch name, nil # defaults to []
+        raise MockExpectationError, "Expected #{__call name, expected[0]}" unless actual
+        raise MockExpectationError, "Expected #{__call name, expected[actual.size]}, got [#{__call name, actual}]" if
+          actual.size < expected.size
+      end
+      true
+    end
+
+    def method_missing sym, *args, **kwargs, &block # :nodoc:
+      unless @expected_calls.key? sym then
+        if @delegator && @delegator.respond_to?(sym)
+          return @delegator.public_send(sym, *args, **kwargs, &block)
+        else
+          raise NoMethodError, "unmocked method %p, expected one of %p" %
+            [sym, @expected_calls.keys.sort_by(&:to_s)]
+        end
+      end
+
+      index = @actual_calls[sym].length
+      expected_call = @expected_calls[sym][index]
+
+      unless expected_call then
+        raise MockExpectationError, "No more expects available for %p: %p %p" %
+          [sym, args, kwargs]
+      end
+
+      expected_args, expected_kwargs, retval, val_block =
+        expected_call.values_at :args, :kwargs, :retval, :block
+
+      expected_kwargs = kwargs.to_h { |ak, av| [ak, Object] } if
+        Hash == expected_kwargs
+
+      if val_block then
+        # keep "verify" happy
+        @actual_calls[sym] << expected_call
+
+        raise MockExpectationError, "mocked method %p failed block w/ %p %p" %
+          [sym, args, kwargs] unless val_block.call(*args, **kwargs, &block)
+
+        return retval
+      end
+
+      if expected_args.size != args.size then
+        raise ArgumentError, "mocked method %p expects %d arguments, got %p" %
+          [sym, expected_args.size, args]
+      end
+
+      if expected_kwargs.size != kwargs.size then
+        raise ArgumentError, "mocked method %p expects %d keyword arguments, got %p" %
+          [sym, expected_kwargs.size, kwargs]
+      end
+
+      zipped_args = expected_args.zip args
+      fully_matched = zipped_args.all? { |mod, a|
+        mod === a or mod == a
+      }
+
+      unless fully_matched then
+        fmt = "mocked method %p called with unexpected arguments %p"
+        raise MockExpectationError, fmt % [sym, args]
+      end
+
+      unless expected_kwargs.keys.sort == kwargs.keys.sort then
+        fmt = "mocked method %p called with unexpected keywords %p vs %p"
+        raise MockExpectationError, fmt % [sym, expected_kwargs.keys, kwargs.keys]
+      end
+
+      zipped_kwargs = expected_kwargs.to_h { |ek, ev|
+        av = kwargs[ek]
+        [ek, [ev, av]]
+      }
+
+      fully_matched = zipped_kwargs.all? { |ek, (ev, av)|
+        ev === av or ev == av
+      }
+
+      unless fully_matched then
+        fmt = "mocked method %p called with unexpected keyword arguments %p vs %p"
+        raise MockExpectationError, fmt % [sym, expected_kwargs, kwargs]
+      end
+
+      @actual_calls[sym] << {
+        :retval => retval,
+        :args   => zipped_args.map { |e, a| e === a ? e : a },
+        :kwargs => zipped_kwargs.to_h { |k, (e, a)| [k, e === a ? e : a] },
+      }
+
+      retval
+    end
+
+    def respond_to? sym, include_private = false # :nodoc:
+      return true if @expected_calls.key? sym.to_sym
+      return true if @delegator && @delegator.respond_to?(sym, include_private)
+      __respond_to? sym, include_private
+    end
+  end
+end
+
+module Minitest::Assertions
+  ##
+  # Assert that the mock verifies correctly and fail if not.
+
+  def assert_mock mock, msg = nil
+    assert mock.verify
+  rescue MockExpectationError => e
+    msg = message(msg) { e.message }
+    flunk msg
+  end
+end
+
+module Minitest::Expectations
+  ##
+  # See Minitest::Assertions#assert_mock.
+  #
+  #    _(collection).must_verify
+  #
+  # :method: must_verify
+
+  infect_an_assertion :assert_mock, :must_verify, :unary if
+    defined?(infect_an_assertion)
+end
+
+##
+# Object extensions for Minitest::Mock.
+
+class Object
+
+  ##
+  # Add a temporary stubbed method replacing +name+ for the duration
+  # of the +block+. If +val_or_callable+ responds to #call, then it
+  # returns the result of calling it, otherwise returns the value
+  # as-is. If stubbed method yields a block, +block_args+ will be
+  # passed along. Cleans up the stub at the end of the +block+. The
+  # method +name+ must exist before stubbing.
+  #
+  #     def test_stale_eh
+  #       obj_under_test = Something.new
+  #       refute obj_under_test.stale?
+  #
+  #       Time.stub :now, Time.at(0) do
+  #         assert obj_under_test.stale?
+  #       end
+  #     end
+  #--
+  # NOTE: keyword args in callables are NOT checked for correctness
+  # against the existing method. Too many edge cases to be worth it.
+
+  def stub name, val_or_callable, *block_args, **block_kwargs, &block
+    new_name = "__minitest_stub__#{name}"
+
+    metaclass = class << self; self; end
+
+    if respond_to? name and not methods.map(&:to_s).include? name.to_s then
+      metaclass.send :define_method, name do |*args, **kwargs|
+        super(*args, **kwargs)
+      end
+    end
+
+    metaclass.send :alias_method, new_name, name
+
+    if ENV["MT_KWARGS_HAC\K"] then
+      metaclass.send :define_method, name do |*args, &blk|
+        if val_or_callable.respond_to? :call then
+          val_or_callable.call(*args, &blk)
+        else
+          blk.call(*block_args, **block_kwargs) if blk
+          val_or_callable
+        end
+      end
+    else
+      metaclass.send :define_method, name do |*args, **kwargs, &blk|
+        if val_or_callable.respond_to? :call then
+          val_or_callable.call(*args, **kwargs, &blk)
+        else
+          if blk then
+            blk.call(*block_args, **block_kwargs)
+          end
+          val_or_callable
+        end
+      end
+    end
+
+    block[self]
+  ensure
+    metaclass.send :undef_method, name
+    metaclass.send :alias_method, name, new_name
+    metaclass.send :undef_method, new_name
+  end
+end

data/test/minitest/metametameta.rb

@@ -0,0 +1,150 @@
+require "tempfile"
+require "stringio"
+require "minitest/autorun"
+
+class Minitest::Test
+  def with_empty_backtrace_filter
+    with_backtrace_filter Minitest::BacktraceFilter.new %r%.% do
+      yield
+    end
+  end
+
+  def with_backtrace_filter filter
+    original = Minitest.backtrace_filter
+
+    Minitest::Test.io_lock.synchronize do # try not to trounce in parallel
+      begin
+        Minitest.backtrace_filter = filter
+        yield
+      ensure
+        Minitest.backtrace_filter = original
+      end
+    end
+  end
+
+  def error_on_warn?
+    defined?(Minitest::ErrorOnWarning)
+  end
+
+  def assert_deprecation re = /DEPRECATED/
+    re = // if $-w.nil? # "skip" if running `rake testW0`
+    assert_output "", re do
+      yield
+    end
+  rescue Minitest::UnexpectedWarning => e # raised if -Werror was used
+    assert_match re, e.message
+  end
+end
+
+class FakeNamedTest < Minitest::Test
+  @@count = 0
+
+  def self.name
+    @fake_name ||= begin
+                     @@count += 1
+                     "FakeNamedTest%02d" % @@count
+                   end
+  end
+end
+
+module MyModule; end
+class AnError < StandardError; include MyModule; end
+
+class MetaMetaMetaTestCase < Minitest::Test
+  attr_accessor :reporter, :output, :tu
+
+  def with_stderr err
+    old = $stderr
+    $stderr = err
+    yield
+  ensure
+    $stderr = old
+  end
+
+  def run_tu_with_fresh_reporter flags = %w[--seed 42]
+    options = Minitest.process_args flags
+
+    @output = StringIO.new(+"")
+
+    self.reporter = Minitest::CompositeReporter.new
+    reporter << Minitest::SummaryReporter.new(@output, options)
+    reporter << Minitest::ProgressReporter.new(@output, options)
+
+    with_stderr @output do
+      reporter.start
+
+      yield reporter if block_given?
+
+      @tus ||= [@tu]
+      @tus.each do |tu|
+        Minitest::Runnable.runnables.delete tu
+
+        tu.run reporter, options
+      end
+
+      reporter.report
+    end
+  end
+
+  def first_reporter
+    reporter.reporters.first
+  end
+
+  def assert_report expected, flags = %w[--seed 42], &block
+    header = <<~EOM
+      Run options: #{flags.map { |s| s.include?("|") ? s.inspect : s }.join " "}
+
+      # Running:
+
+    EOM
+
+    run_tu_with_fresh_reporter flags, &block
+
+    output = normalize_output @output.string.dup
+
+    assert_equal header + expected, output
+  end
+
+  def normalize_output output
+    output.sub!(/Finished in .*/, "Finished in 0.00")
+    output.sub!(/Loaded suite .*/, "Loaded suite blah")
+
+    output.gsub!(/FakeNamedTest\d+/, "FakeNamedTestXX")
+    output.gsub!(/ = \d+.\d\d s = /, " = 0.00 s = ")
+    output.gsub!(/0x[A-Fa-f0-9]+/, "0xXXX")
+    output.gsub!(/ +$/, "")
+
+    file = ->(s) { s.start_with?("/") ? "FULLFILE" : "FILE" }
+
+    if windows? then
+      output.gsub!(/\[(?:[A-Za-z]:)?[^\]:]+:\d+\]/, "[FILE:LINE]")
+      output.gsub!(/^(\s+)(?:[A-Za-z]:)?[^:]+:\d+:in [`']/, '\1FILE:LINE:in \'')
+    else
+      output.gsub!(/\[([^\]:]+):\d+\]/)         {     "[#{file[$1]}:LINE]"   }
+      output.gsub!(/^(\s+)([^:]+):\d+:in [`']/) { "#{$1}#{file[$2]}:LINE:in '" }
+    end
+
+    output.gsub!(/in [`']block in (?:([^']+)[#.])?/, "in 'block in")
+    output.gsub!(/in [`'](?:([^']+)[#.])?/, "in '")
+
+    output.gsub!(/( at )([^:]+):\d+/) { "#{$1}[#{file[$2]}:LINE]" } # eval?
+
+    output
+  end
+
+  def restore_env
+    old_value = ENV["MT_NO_SKIP_MSG"]
+    ENV.delete "MT_NO_SKIP_MSG"
+
+    yield
+  ensure
+    ENV["MT_NO_SKIP_MSG"] = old_value
+  end
+
+  def setup
+    super
+    Minitest.seed = 42
+    Minitest::Test.reset
+    @tu = nil
+  end
+end