mocktail 2.0.0 → 3.0.0

data/src/mocktail/matchers/captor.rb

@@ -0,0 +1,76 @@
+# typed: strict
+
+module Mocktail::Matchers
+  # Captors are conceptually complex implementations, but with a simple usage/purpose:
+  # They are values the user can create and hold onto that will return a matcher
+  # and then "capture" the value made by the real call, for later analysis & assertion.
+  #
+  # Unlike other matchers, these don't make any useful sense for stubbing, but are
+  # very useful when asserting complication call verifications
+  #
+  # The fact the user will need the reference outside the verification call is
+  # why this is a top-level method on Mocktail, and not included in the |m| block
+  # arg to stubs/verify
+  #
+  # See Mockito, which is the earliest implementation I know of:
+  # https://javadoc.io/doc/org.mockito/mockito-core/latest/org/mockito/Captor.html
+  class Captor
+    extend T::Sig
+
+    class Capture < Mocktail::Matchers::Base
+      extend T::Sig
+
+      sig { returns(Symbol) }
+      def self.matcher_name
+        :capture
+      end
+
+      sig { returns(T.untyped) }
+      attr_reader :value
+
+      sig { void }
+      def initialize
+        @value = T.let(nil, T.untyped)
+        @captured = T.let(false, T::Boolean)
+      end
+
+      sig { params(actual: T.untyped).returns(TrueClass) }
+      def match?(actual)
+        @value = actual
+        @captured = true
+        true
+      end
+
+      sig { returns(T::Boolean) }
+      def captured?
+        @captured
+      end
+
+      sig { returns(String) }
+      def inspect
+        "capture"
+      end
+    end
+
+    # This T.untyped is intentional. Even though a Capture is surely returned,
+    # in order for a verification demonstration to pass its own type check,
+    # it needs to think it's being returned whatever parameter is expected
+    sig { returns(T.untyped) }
+    attr_reader :capture
+
+    sig { void }
+    def initialize
+      @capture = T.let(Capture.new, Capture)
+    end
+
+    sig { returns(T::Boolean) }
+    def captured?
+      @capture.captured?
+    end
+
+    sig { returns(T.untyped) }
+    def value
+      @capture.value
+    end
+  end
+end

data/src/mocktail/matchers/includes.rb

@@ -0,0 +1,32 @@
+# typed: strict
+
+module Mocktail::Matchers
+  class Includes < Base
+    extend T::Sig
+
+    sig { returns(Symbol) }
+    def self.matcher_name
+      :includes
+    end
+
+    sig { params(expecteds: T.untyped).void }
+    def initialize(*expecteds)
+      @expecteds = T.let(expecteds, T::Array[T.untyped])
+    end
+
+    sig { params(actual: T.untyped).returns(T::Boolean) }
+    def match?(actual)
+      @expecteds.all? { |expected|
+        (actual.respond_to?(:include?) && actual.include?(expected)) ||
+          (actual.is_a?(Hash) && expected.is_a?(Hash) && expected.all? { |k, v| actual[k] == v })
+      }
+    rescue
+      false
+    end
+
+    sig { returns(String) }
+    def inspect
+      "#{self.class.matcher_name}(#{@expecteds.map(&:inspect).join(", ")})"
+    end
+  end
+end

data/src/mocktail/matchers/includes_hash.rb

@@ -0,0 +1,12 @@
+# typed: strict
+
+module Mocktail::Matchers
+  class IncludesHash < Includes
+    extend T::Sig
+
+    sig { returns(Symbol) }
+    def self.matcher_name
+      :includes_hash
+    end
+  end
+end

data/src/mocktail/matchers/includes_key.rb

@@ -0,0 +1,12 @@
+# typed: strict
+
+module Mocktail::Matchers
+  class IncludesKey < Includes
+    extend T::Sig
+
+    sig { returns(Symbol) }
+    def self.matcher_name
+      :includes_key
+    end
+  end
+end

data/src/mocktail/matchers/includes_string.rb

@@ -0,0 +1,12 @@
+# typed: strict
+
+module Mocktail::Matchers
+  class IncludesString < Includes
+    extend T::Sig
+
+    sig { returns(Symbol) }
+    def self.matcher_name
+      :includes_string
+    end
+  end
+end

data/src/mocktail/matchers/is_a.rb

@@ -0,0 +1,17 @@
+# typed: strict
+
+module Mocktail::Matchers
+  class IsA < Base
+    extend T::Sig
+
+    sig { returns(Symbol) }
+    def self.matcher_name
+      :is_a
+    end
+
+    sig { params(actual: T.untyped).returns(T::Boolean) }
+    def match?(actual)
+      actual.is_a?(@expected)
+    end
+  end
+end

data/src/mocktail/matchers/matches.rb

@@ -0,0 +1,19 @@
+# typed: strict
+
+module Mocktail::Matchers
+  class Matches < Base
+    extend T::Sig
+
+    sig { returns(Symbol) }
+    def self.matcher_name
+      :matches
+    end
+
+    sig { params(actual: T.untyped).returns(T::Boolean) }
+    def match?(actual)
+      actual.respond_to?(:match?) && actual.match?(@expected)
+    rescue
+      false
+    end
+  end
+end

data/src/mocktail/matchers/not.rb

@@ -0,0 +1,17 @@
+# typed: strict
+
+module Mocktail::Matchers
+  class Not < Base
+    extend T::Sig
+
+    sig { returns(Symbol) }
+    def self.matcher_name
+      :not
+    end
+
+    sig { params(actual: T.untyped).returns(T::Boolean) }
+    def match?(actual)
+      @expected != actual
+    end
+  end
+end

data/src/mocktail/matchers/numeric.rb

@@ -0,0 +1,27 @@
+# typed: strict
+
+module Mocktail::Matchers
+  class Numeric < Base
+    extend T::Sig
+
+    sig { returns(Symbol) }
+    def self.matcher_name
+      :numeric
+    end
+
+    sig { void }
+    def initialize
+      # Empty initialize is necessary b/c Base default expects an argument
+    end
+
+    sig { params(actual: T.untyped).returns(T::Boolean) }
+    def match?(actual)
+      actual.is_a?(::Numeric)
+    end
+
+    sig { returns(String) }
+    def inspect
+      "numeric"
+    end
+  end
+end

data/src/mocktail/matchers/that.rb

@@ -0,0 +1,32 @@
+# typed: strict
+
+module Mocktail::Matchers
+  class That < Base
+    extend T::Sig
+
+    sig { returns(Symbol) }
+    def self.matcher_name
+      :that
+    end
+
+    sig { params(blk: T.nilable(T.proc.params(actual: T.untyped).returns(T.untyped))).void }
+    def initialize(&blk)
+      if blk.nil?
+        raise ArgumentError.new("The `that` matcher must be passed a block (e.g. `that { |arg| … }`)")
+      end
+      @blk = T.let(blk, T.proc.params(actual: T.untyped).returns(T.untyped))
+    end
+
+    sig { params(actual: T.untyped).returns(T::Boolean) }
+    def match?(actual)
+      @blk.call(actual)
+    rescue
+      false
+    end
+
+    sig { returns(String) }
+    def inspect
+      "that {…}"
+    end
+  end
+end

data/src/mocktail/matchers.rb

@@ -0,0 +1,19 @@
+# typed: strict
+
+module Mocktail
+  module Matchers
+  end
+end
+
+require_relative "matchers/base"
+require_relative "matchers/any"
+require_relative "matchers/captor"
+require_relative "matchers/includes"
+require_relative "matchers/includes_string"
+require_relative "matchers/includes_hash"
+require_relative "matchers/includes_key"
+require_relative "matchers/is_a"
+require_relative "matchers/matches"
+require_relative "matchers/not"
+require_relative "matchers/numeric"
+require_relative "matchers/that"

data/src/mocktail/raises_neato_no_method_error.rb

@@ -0,0 +1,93 @@
+# typed: strict
+
+require_relative "share/stringifies_call"
+require_relative "share/stringifies_method_name"
+require_relative "share/creates_identifier"
+
+module Mocktail
+  class RaisesNeatoNoMethodError
+    extend T::Sig
+
+    sig { void }
+    def initialize
+      @stringifies_call = T.let(StringifiesCall.new, StringifiesCall)
+      @stringifies_method_name = T.let(StringifiesMethodName.new, StringifiesMethodName)
+      @creates_identifier = T.let(CreatesIdentifier.new, CreatesIdentifier)
+    end
+
+    sig { params(call: Call).void }
+    def call(call)
+      raise NoMethodError, <<~MSG, caller[1..]
+        No method `#{@stringifies_method_name.stringify(call)}' exists for call:
+
+          #{@stringifies_call.stringify(call, anonymous_blocks: true, always_parens: true)}
+
+        Need to define the method? Here's a sample definition:
+
+          def #{"self." if call.singleton}#{call.method}#{params(call)}
+          end
+        #{corrections(call)}
+      MSG
+    end
+
+    private
+
+    sig { params(call: Call).returns(T.nilable(String)) }
+    def params(call)
+      return if (params_lists = [
+        params_list(call.args),
+        kwparams_list(call.kwargs),
+        block_param(call.block)
+      ].compact).empty?
+
+      "(#{params_lists.join(", ")})"
+    end
+
+    sig { params(args: T::Array[T.anything]).returns(T.nilable(String)) }
+    def params_list(args)
+      return if args.empty?
+
+      count_repeats(args.map { |arg|
+        @creates_identifier.create(arg, default: "arg")
+      }).join(", ")
+    end
+
+    sig { params(kwargs: T::Hash[Symbol, T.anything]).returns(T.nilable(String)) }
+    def kwparams_list(kwargs)
+      return if kwargs.empty?
+
+      kwargs.keys.map { |key| "#{key}:" }.join(", ")
+    end
+
+    sig { params(block: T.nilable(Proc)).returns(T.nilable(String)) }
+    def block_param(block)
+      return if block.nil?
+
+      "&blk"
+    end
+
+    sig { params(identifiers: T::Array[String]).returns(T::Array[String]) }
+    def count_repeats(identifiers)
+      identifiers.map.with_index { |id, i|
+        if (preceding_matches = T.must(identifiers[0...i]).count { |other_id| id == other_id }) > 0
+          "#{id}#{preceding_matches + 1}"
+        else
+          id
+        end
+      }
+    end
+
+    sig { params(call: Call).returns(T.nilable(String)) }
+    def corrections(call)
+      return if (corrections = DidYouMean::SpellChecker.new(dictionary: T.must(call.original_type).instance_methods).correct(T.must(call.method))).empty?
+
+      <<~MSG
+
+        There #{(corrections.size == 1) ? "is" : "are"} also #{corrections.size} similar method#{"s" if corrections.size != 1} on #{T.must(call.original_type).name}.
+
+        Did you mean?
+        #{corrections.map { |c| "  #{c}" }.join("\n")}
+      MSG
+    end
+  end
+end

data/src/mocktail/records_demonstration.rb

@@ -0,0 +1,43 @@
+# typed: strict
+
+module Mocktail
+  class RecordsDemonstration
+    extend T::Sig
+
+    sig {
+      type_parameters(:T)
+        .params(
+          demonstration: T.proc.params(matchers: Mocktail::MatcherPresentation).returns(T.type_parameter(:T)),
+          demo_config: DemoConfig
+        ).returns(Call)
+    }
+    def record(demonstration, demo_config)
+      cabinet = Mocktail.cabinet
+      prior_call_count = Mocktail.cabinet.calls.dup.size
+
+      begin
+        cabinet.demonstration_in_progress = true
+        ValidatesArguments.optional(demo_config.ignore_arity) do
+          demonstration.call(Mocktail.matchers)
+        end
+      ensure
+        cabinet.demonstration_in_progress = false
+      end
+
+      if prior_call_count + 1 == cabinet.calls.size
+        T.must(cabinet.calls.pop)
+      elsif prior_call_count == cabinet.calls.size
+        raise MissingDemonstrationError.new <<~MSG.tr("\n", " ")
+          `stubs` & `verify` expect an invocation of a mocked method by a passed
+          block, but no invocation occurred.
+        MSG
+      else
+        raise AmbiguousDemonstrationError.new <<~MSG.tr("\n", " ")
+          `stubs` & `verify` expect exactly one invocation of a mocked method,
+          but #{cabinet.calls.size - prior_call_count} were detected. As a
+          result, Mocktail doesn't know which invocation to stub or verify.
+        MSG
+      end
+    end
+  end
+end

data/src/mocktail/registers_matcher.rb

@@ -0,0 +1,65 @@
+# typed: strict
+
+module Mocktail
+  class RegistersMatcher
+    extend T::Sig
+
+    sig { void }
+    def initialize
+      @grabs_original_method_parameters = T.let(GrabsOriginalMethodParameters.new, GrabsOriginalMethodParameters)
+    end
+
+    sig { params(matcher_type: T.class_of(Matchers::Base)).void }
+    def register(matcher_type)
+      if invalid_type?(matcher_type)
+        raise InvalidMatcherError.new <<~MSG.tr("\n", " ")
+          Matchers must be Ruby classes
+        MSG
+      elsif invalid_name?(matcher_type)
+        raise InvalidMatcherError.new <<~MSG.tr("\n", " ")
+          #{matcher_type.name}.matcher_name must return a valid method name
+        MSG
+      elsif invalid_match?(matcher_type)
+        raise InvalidMatcherError.new <<~MSG.tr("\n", " ")
+          #{matcher_type.name}#match? must be defined as a one-argument method
+        MSG
+      elsif invalid_flag?(matcher_type)
+        raise InvalidMatcherError.new <<~MSG.tr("\n", " ")
+          #{matcher_type.name}#is_mocktail_matcher? must be defined
+        MSG
+      else
+        MatcherRegistry.instance.add(matcher_type)
+      end
+    end
+
+    private
+
+    sig { params(matcher_type: T.class_of(Matchers::Base)).returns(T::Boolean) }
+    def invalid_type?(matcher_type)
+      !matcher_type.is_a?(Class)
+    end
+
+    sig { params(matcher_type: T.class_of(Matchers::Base)).returns(T::Boolean) }
+    def invalid_name?(matcher_type)
+      return true unless matcher_type.respond_to?(:matcher_name)
+      name = matcher_type.matcher_name
+
+      !name.respond_to?(:to_sym) || name.to_sym.inspect.start_with?(":\"")
+    end
+
+    sig { params(matcher_type: T.class_of(Matchers::Base)).returns(T::Boolean) }
+    def invalid_match?(matcher_type)
+      params = @grabs_original_method_parameters.grab(matcher_type.instance_method(:match?))
+      params.size > 1 || ![:req, :opt].include?(T.unsafe(params).first[0])
+    rescue NameError
+      true
+    end
+
+    sig { params(matcher_type: T.class_of(Matchers::Base)).returns(T::Boolean) }
+    def invalid_flag?(matcher_type)
+      !matcher_type.instance_method(:is_mocktail_matcher?)
+    rescue NameError
+      true
+    end
+  end
+end

data/src/mocktail/registers_stubbing.rb

@@ -0,0 +1,31 @@
+# typed: strict
+
+require_relative "records_demonstration"
+
+module Mocktail
+  class RegistersStubbing
+    extend T::Sig
+
+    sig { void }
+    def initialize
+      @records_demonstration = T.let(RecordsDemonstration.new, RecordsDemonstration)
+    end
+
+    sig {
+      type_parameters(:T)
+        .params(
+          demonstration: T.proc.params(matchers: Mocktail::MatcherPresentation).returns(T.type_parameter(:T)),
+          demo_config: DemoConfig
+        ).returns(Mocktail::Stubbing[T.type_parameter(:T)])
+    }
+    def register(demonstration, demo_config)
+      Stubbing.new(
+        demonstration: demonstration,
+        demo_config: demo_config,
+        recording: @records_demonstration.record(demonstration, demo_config)
+      ).tap do |stubbing|
+        Mocktail.cabinet.store_stubbing(stubbing)
+      end
+    end
+  end
+end

data/src/mocktail/replaces_next.rb

@@ -0,0 +1,55 @@
+# typed: strict
+
+module Mocktail
+  class ReplacesNext
+    extend T::Sig
+
+    sig { void }
+    def initialize
+      @top_shelf = T.let(TopShelf.instance, TopShelf)
+      @redefines_new = T.let(RedefinesNew.new, RedefinesNew)
+      @imitates_type = T.let(ImitatesType.new, ImitatesType)
+    end
+
+    sig {
+      type_parameters(:T)
+        .params(type: T::Class[T.all(T.type_parameter(:T), Object)])
+        .returns(T.type_parameter(:T))
+    }
+    def replace_once(type)
+      replace(type, 1).fetch(0)
+    end
+
+    sig {
+      type_parameters(:T)
+        .params(type: T::Class[T.all(T.type_parameter(:T), Object)], count: Integer)
+        .returns(T::Array[T.type_parameter(:T)])
+    }
+    def replace(type, count)
+      raise UnsupportedMocktail.new("Mocktail.of_next() only supports classes") unless T.unsafe(type).is_a?(Class)
+
+      mocktails = count.times.map { @imitates_type.imitate(type) }
+
+      @top_shelf.register_of_next_replacement!(type)
+      @redefines_new.redefine(type)
+      mocktails.reverse_each do |mocktail|
+        Mocktail.stubs(
+          ignore_extra_args: true,
+          ignore_block: true,
+          ignore_arity: true,
+          times: 1
+        ) {
+          type.new
+        }.with {
+          if mocktail == mocktails.last
+            @top_shelf.unregister_of_next_replacement!(type)
+          end
+
+          mocktail
+        }
+      end
+
+      mocktails
+    end
+  end
+end

data/src/mocktail/replaces_type/redefines_new.rb

@@ -0,0 +1,32 @@
+# typed: strict
+
+module Mocktail
+  class RedefinesNew
+    extend T::Sig
+
+    sig { void }
+    def initialize
+      @handles_dry_new_call = T.let(HandlesDryNewCall.new, HandlesDryNewCall)
+    end
+
+    sig { params(type: T.any(T::Class[T.anything], Module)).void }
+    def redefine(type)
+      type_replacement = TopShelf.instance.type_replacement_for(type)
+
+      if type_replacement.replacement_new.nil?
+        type_replacement.original_new = type.method(:new)
+        type.singleton_class.send(:undef_method, :new)
+        handles_dry_new_call = @handles_dry_new_call
+        type.define_singleton_method :new, ->(*args, **kwargs, &block) {
+          if TopShelf.instance.new_replaced?(type) ||
+              (type.is_a?(Class) && TopShelf.instance.of_next_registered?(type))
+            handles_dry_new_call.handle(T.cast(type, T::Class[T.all(T, Object)]), args, kwargs, block)
+          else
+            type_replacement.original_new.call(*args, **kwargs, &block)
+          end
+        }
+        type_replacement.replacement_new = type.singleton_method(:new)
+      end
+    end
+  end
+end

data/src/mocktail/replaces_type/redefines_singleton_methods.rb

@@ -0,0 +1,80 @@
+# typed: strict
+
+module Mocktail
+  class RedefinesSingletonMethods
+    extend T::Sig
+
+    sig { void }
+    def initialize
+      @handles_dry_call = T.let(HandlesDryCall.new, HandlesDryCall)
+    end
+
+    sig { params(type: T.any(T::Class[T.anything], Module)).void }
+    def redefine(type)
+      type_replacement = TopShelf.instance.type_replacement_for(type)
+      return unless type_replacement.replacement_methods.nil?
+
+      type_replacement.original_methods = type.singleton_methods.map { |name|
+        type.method(name)
+      }.reject { |method| sorbet_method_hook?(method) } - [type_replacement.replacement_new]
+
+      declare_singleton_method_missing_errors!(type)
+      handles_dry_call = @handles_dry_call
+      type_replacement.replacement_methods = type_replacement.original_methods&.map { |original_method|
+        type.singleton_class.send(:undef_method, original_method.name)
+        type.define_singleton_method original_method.name, ->(*args, **kwargs, &block) {
+          if TopShelf.instance.singleton_methods_replaced?(type)
+            handles_dry_call.handle(Call.new(
+              singleton: true,
+              double: type,
+              original_type: type,
+              dry_type: type,
+              method: original_method.name,
+              original_method: original_method,
+              args: args,
+              kwargs: kwargs,
+              block: block
+            ))
+          else
+            original_method.call(*args, **kwargs, &block)
+          end
+        }
+        type.singleton_method(original_method.name)
+      }
+    end
+
+    sig { params(type: T.any(T::Class[T.anything], Module)).void }
+    def declare_singleton_method_missing_errors!(type)
+      return if type.singleton_methods.include?(:method_missing)
+
+      raises_neato_no_method_error = RaisesNeatoNoMethodError.new
+      type.define_singleton_method :method_missing,
+        ->(name, *args, **kwargs, &block) {
+          raises_neato_no_method_error.call(
+            Call.new(
+              singleton: true,
+              double: self,
+              original_type: type,
+              dry_type: self.class,
+              method: name,
+              original_method: nil,
+              args: args,
+              kwargs: kwargs,
+              block: block
+            )
+          )
+        }
+    end
+
+    private
+
+    sig { params(method: Method).returns(T::Boolean) }
+    def sorbet_method_hook?(method)
+      [
+        T::Sig,
+        T::Private::Methods::MethodHooks,
+        T::Private::Methods::SingletonMethodHooks
+      ].include?(method.owner)
+    end
+  end
+end