fix: cannot watch methods with kwargs in ruby 3 (#72)

* reproduce bug in tests

* add MockArguments to support kwargs handling

* store kwargs in all mocking styles

* drop support for ruby 2.6

* update CHANGELOG and README with changes for new args access pattern

Author: clarkedb

.github/workflows/ci.yml

@@ -33,7 +33,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        ruby: ["2.6", "2.7", "3.0", "3.1"]
+        ruby: ["2.7", "3.0", "3.1"]
 
     steps:
       - uses: actions/checkout@v2

CHANGELOG.md

@@ -8,11 +8,16 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ### Changed
 
-* Dropped support for Ruby 2.5
+* Dropped support for Ruby 2.5 and Ruby 2.6
+* To support keyword arguments, records of call arguments are no longer stored in simple arrays but in a custom Enumerable
+  + This changes the way that your tests will interact with mock calls
+  + When before `calls` returned an array, it returns a `Grift::MockMethod::MockExecutions::MockArguments` object
+  + Migrating to maintain previous behavior just requires appending `.args` to `calls`
 
 ### Added
 
 * Support for mocking private instance and class methods
+* Support for mocking methods that take positional and keyword arguments
 
 ### Fixed
 

README.md

@@ -78,13 +78,22 @@ my_spy.mock_implementation do |arg1, arg2|
 end
 ```
 
+or for a method taking keyword arguments:
+
+```ruby
+my_spy = Grift.spy_on(MyClass, :my_method)
+my_spy.mock_implementation do |arg1, arg2, **kwargs|
+    x = do_something(arg1, arg2, kwargs[:arg3], kwargs[:arg4])
+    do_something_else(x) # the last line will be returned
+end
+
 ### Chaining
 
 You can chain `mock_return_value` and `mock_implementation` after initializing the mock.
 
 ```ruby
-my_mock = Grift.spy_on(MyClass, :my_method).mock_implementation do |*args|
-    do_something(*args)
+my_mock = Grift.spy_on(MyClass, :my_method).mock_implementation do |*args, **kwargs|
+    do_something(*args, **kwargs)
 end
 #=> Grift::MockMethod object is returned
 ```
@@ -99,8 +108,12 @@ my_mock.mock.count
 #=> 2
 
 # get args for each call to the method while mocked
-my_mock.mock.calls
-#=> [['first_arg1', 'second_arg1'], ['first_arg2', 'second_arg2']]
+my_mock.mock.calls[0].args
+#=> ['first_arg1', 'second_arg1']
+
+# get kwargs for each call to the method while mocked
+my_mock.mock.calls[0].kwargs
+#=> { first_arg1: 'value' }
 
 # get results (return value) for each call to the method while mocked
 my_mock.mock.results
@@ -109,7 +122,7 @@ my_mock.mock.results
 
 ## Requirements
 
-Grift supports all Ruby versions >= 2.5 (including 3.1).
+Grift supports all Ruby versions >= 2.7 (including 3.1).
 
 ## Development
 
@@ -119,7 +132,7 @@ When developing, to install Grift whith your changes onto your local machine, ru
 
 ### Docs
 
-The docs are generated using YARD. To build the docs, first `gem install yard`. Then run `yardoc` to build the new docs. This is always done before a release to update the docs that get published and made available with the gem.
+The docs are generated using YARD. To build the docs, first `gem install yard` . Then run `yardoc` to build the new docs. This is always done before a release to update the docs that get published and made available with the gem.
 
 ## Contributing
 

grift.gemspec

@@ -12,7 +12,7 @@ Gem::Specification.new do |spec|
   spec.description   = "A gem for simple mocking and spying in Ruby's MiniTest framework."
   spec.homepage      = 'https://github.com/clarkedb/grift'
   spec.license       = 'MIT'
-  spec.required_ruby_version = Gem::Requirement.new('>= 2.6.0')
+  spec.required_ruby_version = Gem::Requirement.new('>= 2.7.0')
 
   spec.metadata = {
     'bug_tracker_uri' => "#{spec.homepage}/issues",

lib/grift.rb

@@ -5,6 +5,7 @@
 require 'grift/minitest_plugin'
 require 'grift/mock_method'
 require 'grift/mock_method/mock_executions'
+require 'grift/mock_method/mock_executions/mock_arguments'
 require 'grift/mock_store'
 require 'grift/version'
 

lib/grift/mock_method.rb

@@ -125,24 +125,24 @@ def mock_restore(watch: false)
     #   #=> '7'
     #
     # @example
-    #   my_mock = Grift.spy_on(MyClass, :my_method).mock_implementation do |first, second|
-    #       [second, first]
+    #   my_mock = Grift.spy_on(MyClass, :my_method).mock_implementation do |first, second, **kwargs|
+    #       [second, kwargs[:third], first]
     #   end
-    #   MyClass.my_method(1, 2)
-    #   #=> [2, 1]
+    #   MyClass.my_method(1, 2, third: 3)
+    #   #=> [2, 3, 1]
     #
-    # @return [Grift::MockMethod] the mock itself
+    # @return [self] the mock itself
     #
     def mock_implementation(*)
       premock_setup
       mock_executions = @mock_executions # required to access inside class instance block
 
       class_instance.remove_method(@method_name) if !@inherited && method_defined?
-      class_instance.define_method @method_name do |*args|
-        return_value = yield(*args)
+      class_instance.define_method @method_name do |*args, **kwargs|
+        return_value = yield(*args, **kwargs)
 
         # record the args passed in the call to the method and the result
-        mock_executions.store(args, return_value)
+        mock_executions.store(args: args, result: return_value)
         return return_value
       end
       class_instance.send(@method_access, @method_name)
@@ -163,16 +163,16 @@ def mock_implementation(*)
     #
     # @param return_value the value to return from the method
     #
-    # @return [Grift::MockMethod] the mock itself
+    # @return [self] the mock itself
     #
     def mock_return_value(return_value = nil)
       premock_setup
       mock_executions = @mock_executions # required to access inside class instance block
 
       class_instance.remove_method(@method_name) if !@inherited && method_defined?
-      class_instance.define_method @method_name do |*args|
+      class_instance.define_method @method_name do |*args, **kwargs|
         # record the args passed in the call to the method and the result
-        mock_executions.store(args, return_value)
+        mock_executions.store(args: args, kwargs: kwargs, result: return_value)
         return return_value
       end
       class_instance.send(@method_access, @method_name)
@@ -212,19 +212,19 @@ def self.hash_key(klass, method_name)
     ##
     # Watches the method without mocking its impelementation or return value.
     #
-    # @return [Grift::MockMethod] the mock itself
+    # @return [self] the mock itself
     #
     def watch_method
       premock_setup
       mock_executions = @mock_executions # required to access inside class instance block
       cache_method_name = @cache_method_name
 
       class_instance.remove_method(@method_name) if !@inherited && method_defined?
-      class_instance.define_method @method_name do |*args|
-        return_value = send(cache_method_name, *args)
+      class_instance.define_method @method_name do |*args, **kwargs|
+        return_value = send(cache_method_name, *args, **kwargs)
 
         # record the args passed in the call to the method and the result
-        mock_executions.store(args, return_value)
+        mock_executions.store(args: args, kwargs: kwargs, result: return_value)
         return return_value
       end
       class_instance.send(@method_access, @method_name)

lib/grift/mock_method/mock_executions.rb

@@ -9,7 +9,7 @@ class MockExecutions
       ##
       # A new instance of MockExecutions.
       #
-      # @return [Grift::MockMethod::MockExectuions]
+      # @return [Grift::MockMethod::MockExecutions]
       #
       def initialize
         @executions = []
@@ -21,14 +21,14 @@ def initialize
       # @example
       #   my_mock = Grift.spy_on(Number, :+)
       #   x = (3 + 4) + 5
-      #   my_mock.mock.calls
+      #   my_mock.mock.calls.map(&:values)
       #   #=> [[4], [5]]
       #
-      # @return [Array<Array>] an array of arrays of args
+      # @return [Array<Grift::MockMethod::MockExecutions::MockArguments>] an array of MockArguments
       #
       def calls
         @executions.map do |exec|
-          exec[:args]
+          exec[:arguments]
         end
       end
 
@@ -89,13 +89,17 @@ def results
       # Stores an args and result pair to the executions array.
       #
       # @example
-      #   mock_store = Grift::MockMethod::MockExecutions.new
-      #   mock_store.store([1, 1], [2])
+      #   mock_executions = Grift::MockMethod::MockExecutions.new
+      #   mock_executions.store(args: [1, 1], kwargs: { test: true }, result: 2)
       #
-      # @return [Array] an array of results
+      # @param args [Array] the postitional args to store
+      # @param kwargs [Hash] the keyword args to store
+      # @param result the method result to store
+      #
+      # @return [Array] an updated array of executions
       #
-      def store(args, result)
-        @executions.push({ args: args, result: result })
+      def store(args: [], kwargs: {}, result: nil)
+        @executions.push({ arguments: MockArguments.new(args: args, kwargs: kwargs), result: result })
       end
     end
   end

lib/grift/mock_method/mock_executions/mock_arguments.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+module Grift
+  class MockMethod
+    class MockExecutions
+      ##
+      # An immutable Enumerable that stores the arguments used in a call for {Grift::MockMethod::MockExecutions}.
+      #
+      class MockArguments
+        include Enumerable
+
+        attr_reader :args, :kwargs
+
+        ##
+        # A new instance of MockArguments.
+        #
+        # @return [Grift::MockMethod::MockExecutions::MockArguments]
+        #
+        def initialize(args: [], kwargs: {})
+          @args = args.freeze
+          @kwargs = kwargs.freeze
+        end
+
+        ##
+        # Retrieves a stored argument by an accessor. For positional arguments this would be an integer
+        # corresponding to the arguments position in the method call signature. For keyword arguments
+        # this would be the key / parameter name as a symbol or string.
+        #
+        # @example
+        #   my_mock = Grift.mock(Request, :new)
+        #   request = Request.new('/users', method: 'GET')
+        #   #=> <Request object>
+        #   my_mock.mock.calls.last[0] # integer access for positional
+        #   #=> '/users'
+        #   my_mock.mock.calls.last[:method] # key access for keyword
+        #   #=> 'GET'
+        #
+        # @param index [Integer, Symbol, String] the accessor for the desired argument
+        #
+        # @raise [Grift::Error] exception if accessor is not a supported type
+        #
+        # @return the specified value
+        #
+        def [](index)
+          if index.instance_of?(Integer)
+            @args[index]
+          elsif index.instance_of?(Symbol)
+            @kwargs[index]
+          elsif index.instance_of?(String)
+            @kwargs[index.to_sym]
+          else
+            raise(Grift::Error, "Cannot access by type '#{index.class}'. Expected an Integer, Symbol, or String")
+          end
+        end
+
+        ##
+        # Calls the given block once for each argument value, passing that value
+        # as a parameter.
+        #
+        # @return [void]
+        #
+        def each(&block)
+          @args.each(&block)
+          @kwargs.each_value(&block)
+        end
+
+        ##
+        # @see Enumerable#first
+        #
+        # Returns the last argument passed in the call.
+        #
+        # @example
+        #   my_mock = Grift.mock(Request, :new)
+        #   request = Request.new('/users', method: 'GET')
+        #   #=> <Request object>
+        #   my_mock.mock.calls.last.last
+        #   #=> 'GET'
+        #
+        # @return [Any]
+        #
+        def last
+          @args.last || @kwargs.values.last
+        end
+
+        ##
+        # Returns the number of arguments passed in the call.
+        #
+        # @example
+        #   arr = [1, 2, 3]
+        #   my_mock = Grift.mock(Array, :count)
+        #   arr.count
+        #   #=> 3
+        #   my_mock.mock.calls.last.length
+        #   #=> 0
+        #   arr.count(3)
+        #   #=> 1
+        #   my_mock.mock.calls.last.length
+        #   #=> 1
+        #
+        # @return [Integer]
+        #
+        def length
+          @args.length + @kwargs.length
+        end
+
+        ##
+        # Returns true if the call included no arguments.
+        #
+        # @example
+        #   arr = [1, 2, 3]
+        #   my_mock = Grift.mock(Array, :count)
+        #   arr.count
+        #   #=> 3
+        #   my_mock.mock.calls.last.empty?
+        #   #=> true
+        #   arr.count(2)
+        #   #=> 1
+        #   my_mock.mock.calls.last.empty?
+        #   #=> false
+        #
+        # @return [Boolean] true if the no arguments were used
+        #
+        def empty?
+          @args.empty? && @kwargs.empty?
+        end
+
+        ##
+        # Returns the keyword parameter keys passed in the call.
+        #
+        # To get the values, use {Grift::MockMethod::MockExecutions::MockArguments#values}.
+        #
+        # @example
+        #   my_mock = Grift.mock(Request, :new)
+        #   request = Request.new('/users', method: 'GET')
+        #   #=> <Request object>
+        #   my_mock.mock.calls.last.keys
+        #   #=> [:method]
+        #
+        # @return [Array<Symbol>] the parameter keys
+        #
+        def keys
+          @kwargs.keys
+        end
+
+        ##
+        # Returns the arguments passed in the call.
+        #
+        # If a keyword argument was used, then only the value will be returned.
+        # To get the keys, use {Grift::MockMethod::MockExecutions::MockArguments#keys}.
+        #
+        # @example
+        #   my_mock = Grift.mock(Request, :new)
+        #   request = Request.new('/users', method: 'GET')
+        #   #=> <Request object>
+        #   my_mock.mock.calls.last.keys
+        #   #=> [:method]
+        #
+        # @return [Array] the argument values
+        #
+        def values
+          @args + @kwargs.values
+        end
+      end
+    end
+  end
+end