grift 0.1.0 → 1.0.0

data/lib/grift/mock_method/mock_executions.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module Grift
+  class MockMethod
+    ##
+    # An Array wrapper that tracks the calls and results for a {Grift::MockMethod}.
+    #
+    class MockExecutions
+      ##
+      # A new instance of MockExecutions.
+      #
+      # @return [Grift::MockMethod::MockExectuions]
+      #
+      def initialize
+        @executions = []
+      end
+
+      ##
+      # Returns an array of the args used in each call to the mocked method
+      #
+      # @example
+      #   my_mock = Grift.spy_on(Number, :+)
+      #   x = (3 + 4) + 5
+      #   my_mock.mock.calls
+      #   #=> [[4], [5]]
+      #
+      # @return [Array<Array>] an array of arrays of args
+      #
+      def calls
+        @executions.map do |exec|
+          exec[:args]
+        end
+      end
+
+      ##
+      # Returns true if there have been no calls tracked.
+      #
+      # @example
+      #   my_mock = Grift.mock(String, :upcase)
+      #   my_mock.mock.empty?
+      #   #=> true
+      #   "apple".upcase
+      #   #=> "APPLE"
+      #   my_mock.mock.empty?
+      #   #=> false
+      #
+      # @return [Boolean] if the executions are empty
+      #
+      def empty?
+        @executions.empty?
+      end
+
+      ##
+      # Returns the count of executions.
+      #
+      # @example
+      #   my_mock = Grift.mock(String, :upcase)
+      #   my_mock.mock.count
+      #   #=> 0
+      #   "apple".upcase
+      #   #=> "APPLE"
+      #   my_mock.mock.count
+      #   #=> 1
+      #
+      # @return [Number] the number of executions
+      #
+      def count
+        @executions.count
+      end
+
+      ##
+      # Returns an array of the results of each call to the mocked method
+      #
+      # @example
+      #   my_mock = Grift.spy_on(Number, :+)
+      #   x = (3 + 4) + 5
+      #   my_mock.mock.results
+      #   #=> [7, 12]
+      #
+      # @return [Array] an array of results
+      #
+      def results
+        @executions.map do |exec|
+          exec[:result]
+        end
+      end
+
+      ##
+      # Stores an args and result pair to the executions array.
+      #
+      # @example
+      #   mock_store = Grift::MockMethod::MockExecutions.new
+      #   mock_store.store([1, 1], [2])
+      #
+      # @return [Array] an array of results
+      #
+      def store(args, result)
+        @executions.push({ args: args, result: result })
+      end
+    end
+  end
+end

data/lib/grift/mock_method.rb

@@ -0,0 +1,284 @@
+# frozen_string_literal: true
+
+module Grift
+  ##
+  # A mock for a given class and method. This is the core of Grift. Mocking or spying
+  # usually returns a {Grift::MockMethod}.
+  #
+  class MockMethod
+    attr_reader :true_method_cached, :klass, :method_name
+
+    CACHE_METHOD_PREFIX = 'grift_cache'
+    private_constant :CACHE_METHOD_PREFIX
+
+    ##
+    # A new instance of MockMethod. Should be initialized via {Grift.mock} or {Grift.spy_on}
+    #
+    # @see Grift.mock
+    # @see Grift.spy_on
+    #
+    # @example
+    #   Grift.spy_on(MyClass, :my_method)
+    #   #=> MockMethod instance with the method being watched
+    #
+    # @param klass [Class] the class to be mocked
+    # @param method_name [Symbol] the method to be mocked
+    # @param watch [Boolean] whether to start watching the method
+    #
+    # @return [Grift::MockMethod]
+    #
+    def initialize(klass, method_name, watch: true)
+      if Grift.restricted_method?(klass, method_name)
+        raise(Grift::Error, "Cannont mock restricted method #{method_name} for class #{klass}")
+      end
+
+      @klass = klass
+      @method_name = method_name
+      @true_method_cached = false
+      @mock_executions = MockExecutions.new
+      @cache_method_name = "#{CACHE_METHOD_PREFIX}_#{method_name}".to_sym
+
+      # class methods are really instance methods of the singleton class
+      @class_method = klass.singleton_class.instance_methods(true).include?(method_name)
+
+      unless class_instance.instance_methods(true).include?(method_name)
+        raise(Grift::Error, "Cannont mock unknown method #{method_name} for class #{klass}")
+      end
+
+      if class_instance.instance_methods.include?(@cache_method_name)
+        raise(Grift::Error, "Cannot mock already mocked method #{method_name} for class #{klass}")
+      end
+
+      watch_method if watch
+    end
+
+    ##
+    # Gets the data for the mock results and calls for this mock.
+    #
+    # @see Grift::MockMethod::MockExecutions#calls
+    # @see Grift::MockMethod::MockExecutions#results
+    #
+    # @example
+    #   my_mock = Grift.spy_on(String, :upcase)
+    #   "banana".upcase
+    #   #=> 'BANANA'
+    #   my_mock.mock.calls
+    #   #=> [[]]
+    #   my_mock.mock.results
+    #   #=> [['BANANA']]
+    #
+    # @return [Grift::MockMethod::MockExecutions]
+    #
+    def mock
+      @mock_executions
+    end
+
+    ##
+    # Clears the mock execution and calls data for this mock, but
+    # keep the method mocked as before.
+    #
+    # @return [Grift::MockMethod::MockExecutions]
+    #
+    def mock_clear
+      @mock_executions = MockExecutions.new
+    end
+
+    ##
+    # Clears the mock execution and calls data for this mock, and
+    # mocks the method to return `nil`.
+    #
+    # @return [Grift::MockMethod::MockExecutions]
+    #
+    def mock_reset
+      executions = mock_clear
+      mock_return_value(nil)
+      executions
+    end
+
+    ##
+    # Clears the mock execution and calls data for this mock, and
+    # restores the method to its original behavior. By default it
+    # also stops watching the method. This cleans up the mocking
+    # and restores expected behavior.
+    #
+    # @param watch [Boolean] whether or not to keep watching the method
+    #
+    # @return [Grift::MockMethod::MockExecutions]
+    #
+    def mock_restore(watch: false)
+      executions = mock_clear
+      unmock_method if @true_method_cached
+      watch_method if watch
+      executions
+    end
+
+    ##
+    # Accepts a block and mocks the method to execute that block instead
+    # of the original behavior whenever called while mocked.
+    #
+    # @example
+    #   my_mock = Grift.spy_on(String, :downcase).mock_implementation do
+    #       x = 3 + 4
+    #       x.to_s
+    #   end
+    #   "Banana".downcase
+    #   #=> '7'
+    #
+    # @example
+    #   my_mock = Grift.spy_on(MyClass, :my_method).mock_implementation do |first, second|
+    #       [second, first]
+    #   end
+    #   MyClass.my_method(1, 2)
+    #   #=> [2, 1]
+    #
+    # @return [Grift::MockMethod] the mock itself
+    #
+    def mock_implementation(&block)
+      premock_setup
+      mock_executions = @mock_executions # required to access inside class instance block
+
+      class_instance.remove_method(@method_name)
+      class_instance.define_method @method_name do |*args|
+        return_value = block.call(*args)
+
+        # record the args passed in the call to the method and the result
+        mock_executions.store(args, return_value)
+        return return_value
+      end
+
+      self
+    end
+
+    ##
+    # Accepts a value and mocks the method to return that value instead
+    # of executing its original behavior while mocked.
+    #
+    # @see Grift#mock
+    #
+    # @example
+    #   my_mock = Grift.spy_on(String, :upcase).mock_return_value('BANANA')
+    #   "apple".upcase
+    #   #=> 'BANANA'
+    #
+    # @param return_value the value to return from the method
+    #
+    # @return [Grift::MockMethod] 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)
+      class_instance.define_method @method_name do |*args|
+        # record the args passed in the call to the method and the result
+        mock_executions.store(args, return_value)
+        return return_value
+      end
+
+      self
+    end
+
+    ##
+    # String representation of the MockMethod
+    #
+    # @see Grift::MockMethod.hash_key
+    #
+    # @return [String]
+    #
+    def to_s
+      Grift::MockMethod.hash_key(@klass, @method_name)
+    end
+
+    ##
+    # Hashes the class and method for tracking mocks.
+    #
+    # @example
+    #   Grift::MockMethod.hash_key(String, :upcase)
+    #   #=> 'String#upcase'
+    #
+    # @param klass [Class]
+    # @param method_name [Symbol]
+    #
+    # @return [String] the hash of the class and method
+    #
+    def self.hash_key(klass, method_name)
+      "#{klass}\##{method_name}"
+    end
+
+    private
+
+    ##
+    # Watches the method without mocking its impelementation or return value.
+    #
+    # @return [Grift::MockMethod] 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)
+      class_instance.define_method @method_name do |*args|
+        return_value = send(cache_method_name, *args)
+
+        # record the args passed in the call to the method and the result
+        mock_executions.store(args, return_value)
+        return return_value
+      end
+
+      self
+    end
+
+    ##
+    # Unmocks the method and restores the true method
+    #
+    # @raise [Grift:Error] if method not mocked
+    #
+    def unmock_method
+      raise(Grift::Error, 'Method is not cached') unless @true_method_cached
+
+      class_instance.remove_method(@method_name)
+      class_instance.alias_method(@method_name, @cache_method_name)
+      class_instance.remove_method(@cache_method_name)
+
+      @true_method_cached = false
+    end
+
+    ##
+    # Caches the method
+    #
+    # @raise [Grift::Error] if method already cached
+    #
+    def cache_method
+      raise(Grift::Error, 'Method already cached') if @true_method_cached
+
+      class_instance.alias_method(@cache_method_name, @method_name)
+      @true_method_cached = true
+    end
+
+    ##
+    # Sets up mock actions by caching the method and storing it in the
+    # Grift global store.
+    #
+    def premock_setup
+      cache_method unless @true_method_cached
+      send_to_store
+    end
+
+    ##
+    # Adds the mock to the global store
+    #
+    def send_to_store
+      Grift.mock_store.store(self) unless Grift.mock_store.include?(self)
+    end
+
+    ##
+    # Returns the appropriate class instance
+    #
+    # @return [Class]
+    #
+    def class_instance
+      @class_method ? @klass.singleton_class : @klass
+    end
+  end
+end

data/lib/grift/mock_store.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+module Grift
+  ##
+  # A hash wrapper that tracks what methods are mocked and facilitates cleanup of mocks.
+  # This class is meant for internal use and should generally not be called explcitly.
+  #
+  class MockStore
+    # A new instance of MockStore
+    # @return [Grift::MockStore]
+    def initialize
+      @mocks = {}
+    end
+
+    ##
+    # Add the given mock to the mock store.
+    #
+    # @example
+    #   mock_store = Grift::MockStore.new
+    #   mock_method = Grift.mock(MyClass, :my_method)
+    #   mock_store.store(mock_method)
+    #
+    # @param mock_method [Grift::MockMethod] the mock method to add to the store
+    #
+    # @raise [Grift::Error] if mock_method is not of type {Grift::MockMethod}
+    # @raise [Grift::Error] if the store already contains that mock or an equivalent mock
+    #
+    # @return [Grift::MockMethod] the mock method that was added
+    #
+    def store(mock_method)
+      raise(Grift::Error, 'Must only store Grift Mocks') unless mock_method.instance_of?(Grift::MockMethod)
+      raise(Grift::Error, 'Store aready contains that mock') if include?(mock_method)
+
+      @mocks[mock_method.to_s] = mock_method
+    end
+
+    ##
+    # Searches for the mock in the store. Optional filtering by class/method.
+    # If no parameters are passed in, this returns all mocks in the store.
+    #
+    # @param klass [Class] the class to filter by, if nil all classes are included
+    # @param method [Symbol] the method to filter by, if nil all symbols are included
+    #
+    # @return [Array] the mocks in the store that match the criteria
+    #
+    def mocks(klass: nil, method: nil)
+      search(klass: klass, method: method).values
+    end
+
+    ##
+    # Unmocks and removes mocks in the store. Optional filtering by class/method.
+    # If no parameters are passed in, cleans up all mocks in the store.
+    #
+    # @param klass [Class] the class to filter by, if nil all classes are included
+    # @param method [Symbol] the method to filter by, if nil all symbols are included
+    #
+    # @return [Grift::MockStore] the updated mock store itself
+    #
+    def remove(klass: nil, method: nil)
+      to_remove = search(klass: klass, method: method)
+      to_remove.each do |key, mock|
+        mock.mock_restore(watch: false)
+        @mocks.delete(key)
+      end
+
+      self
+    end
+
+    ##
+    # Unmocks and removes the mock in the store. If the mock is not in the store,
+    # nothing will change.
+    #
+    # @param mock_method [Grift::MockMethod, String] the mock to remove or its hash key
+    #
+    # @return [Grift::MockStore] the updated mock store itself
+    #
+    def delete(mock_method)
+      if include?(mock_method)
+        mock_method.mock_restore(watch: false)
+        @mocks.delete(mock_method.to_s)
+      end
+
+      self
+    end
+
+    ##
+    # Checks if the mock store includes the given mock method.
+    #
+    # @example
+    #   mock_store = Grift::MockStore.new
+    #   mock_method = Grift.mock(MyClass, :my_method)
+    #   mock_store.include?(mock_method)
+    #   #=> false
+    #   mock_store.store(mock_method)
+    #   mock_store.include?(mock_method)
+    #   #=> true
+    #
+    # @param mock_method [Grift::MockMethod, String] the mock to search for or its hash key
+    #
+    # @return [Boolean] if the mock store includes that mock method
+    #
+    def include?(mock_method)
+      @mocks.include?(mock_method.to_s)
+    end
+
+    ##
+    # Checks if the mock store is empty.
+    #
+    # @example
+    #   mock_store = Grift::MockStore.new
+    #   mock_store.empty?
+    #   #=> true
+    #   mock_method = Grift.mock(MyClass, :my_method)
+    #   mock_store.store(mock_method)
+    #   mock_store.empty?
+    #   #=> false
+    #
+    # @return [Boolean] if the mock store is empty
+    #
+    def empty?
+      @mocks.empty?
+    end
+
+    private
+
+    ##
+    # Searches for the mock in the store. Optional filtering by class/method.
+    #
+    # @param klass [Class] the class to filter by, if nil all classes are included
+    # @param method [Symbol] the method to filter by, if nil all symbols are included
+    #
+    # @return [Hash] the key, mock pairs in the store that match the criteria
+    #
+    def search(klass: nil, method: nil)
+      return @mocks unless klass || method
+
+      pattern = Regexp.new(Grift::MockMethod.hash_key(klass, method))
+      @mocks.select { |k| pattern.match?(k) }
+    end
+  end
+end

data/lib/grift/version.rb

@@ -1,3 +1,7 @@
+# frozen_string_literal: true
+
 module Grift
-  VERSION = "0.1.0"
+  # gem version
+  VERSION = '1.0.0'
+  public_constant :VERSION
 end