mocktail 1.2.3 → 3.0.0

data/src/mocktail/collects_calls.rb

@@ -0,0 +1,18 @@
+# typed: strict
+
+module Mocktail
+  class CollectsCalls
+    extend T::Sig
+
+    sig { params(double: Object, method_name: T.nilable(Symbol)).returns(T::Array[Call]) }
+    def collect(double, method_name)
+      calls = ExplainsThing.new.explain(double).reference.calls
+
+      if method_name.nil?
+        calls
+      else
+        calls.select { |call| call.method.to_s == method_name.to_s }
+      end
+    end
+  end
+end

data/src/mocktail/debug.rb

@@ -0,0 +1,55 @@
+# typed: strict
+
+module Mocktail
+  module Debug
+    extend T::Sig
+
+    # It would be easy and bad for the mocktail lib to call something like
+    #
+    #   double == other_double
+    #
+    # But if it's a double, that means anyone who stubs that method could change
+    # the internal behavior of the library in unexpected ways (as happened here:
+    # https://github.com/testdouble/mocktail/issues/7 )
+    #
+    # For that reason when we run our tests, we also want to blow up if this
+    # happens unintentionally. This works in conjunction with the test
+    # MockingMethodfulClassesTest, because it mocks every defined method on the
+    # mocked BasicObject
+    sig { void }
+    def self.guard_against_mocktail_accidentally_calling_mocks_if_debugging!
+      return unless ENV["MOCKTAIL_DEBUG_ACCIDENTAL_INTERNAL_MOCK_CALLS"]
+      raise Mocktail::Error
+    rescue Mocktail::Error => e
+      base_path = Pathname.new(__FILE__).dirname.to_s
+      backtrace_minus_this_and_whoever_called_this = e.backtrace&.[](2..)
+      internal_call_sites = backtrace_minus_this_and_whoever_called_this&.take_while { |call_site|
+        # the "in `block"/"in 'block" (Ruby 3.4+ uses a single quote instead of a
+        # backtick) is very confusing but necessary to include lines after
+        # a stubs { blah.foo }.with { … } call, since that's when most of the
+        # good stuff happens
+        call_site.start_with?(base_path) || call_site.match?(/in [`']block/)
+      }&.reject { |call_site| call_site.match?(/in [`']block/) } || []
+
+      approved_call_sites = [
+        /fulfills_stubbing.rb:(16|20)/,
+        /validates_arguments.rb:(18|23)/,
+        /validates_arguments.rb:(21|26)/
+      ]
+      if internal_call_sites.any? && approved_call_sites.none? { |approved_call_site|
+        internal_call_sites.first&.match?(approved_call_site)
+      }
+        raise Error.new <<~MSG
+          Unauthorized internal call of a mock internally by Mocktail itself:
+
+          #{internal_call_sites.first}
+
+          Offending call's complete stack trace:
+
+          #{backtrace_minus_this_and_whoever_called_this&.join("\n")}
+          ==END OFFENDING TRACE==
+        MSG
+      end
+    end
+  end
+end

data/src/mocktail/dsl.rb

@@ -0,0 +1,46 @@
+# typed: strict
+
+module Mocktail
+  module DSL
+    extend T::Sig
+
+    sig {
+      type_parameters(:T)
+        .params(
+          ignore_block: T::Boolean,
+          ignore_extra_args: T::Boolean,
+          ignore_arity: T::Boolean,
+          times: T.nilable(Integer),
+          demo: T.proc.params(matchers: Mocktail::MatcherPresentation).returns(T.type_parameter(:T))
+        )
+        .returns(Mocktail::Stubbing[T.type_parameter(:T)])
+    }
+    def stubs(ignore_block: false, ignore_extra_args: false, ignore_arity: false, times: nil, &demo)
+      RegistersStubbing.new.register(demo, DemoConfig.new(
+        ignore_block: ignore_block,
+        ignore_extra_args: ignore_extra_args,
+        ignore_arity: ignore_arity,
+        times: times
+      ))
+    end
+
+    sig {
+      type_parameters(:T)
+        .params(
+          ignore_block: T::Boolean,
+          ignore_extra_args: T::Boolean,
+          ignore_arity: T::Boolean,
+          times: T.nilable(Integer),
+          demo: T.proc.params(matchers: Mocktail::MatcherPresentation).void
+        ).void
+    }
+    def verify(ignore_block: false, ignore_extra_args: false, ignore_arity: false, times: nil, &demo)
+      VerifiesCall.new.verify(demo, DemoConfig.new(
+        ignore_block: ignore_block,
+        ignore_extra_args: ignore_extra_args,
+        ignore_arity: ignore_arity,
+        times: times
+      ))
+    end
+  end
+end

data/src/mocktail/errors.rb

@@ -0,0 +1,19 @@
+# typed: strict
+
+module Mocktail
+  class Error < StandardError; end
+
+  class UnexpectedError < Error; end
+
+  class UnsupportedMocktail < Error; end
+
+  class MissingDemonstrationError < Error; end
+
+  class AmbiguousDemonstrationError < Error; end
+
+  class InvalidMatcherError < Error; end
+
+  class VerificationError < Error; end
+
+  class TypeCheckingError < Error; end
+end

data/src/mocktail/explains_nils.rb

@@ -0,0 +1,41 @@
+# typed: strict
+
+require_relative "share/stringifies_method_name"
+require_relative "share/stringifies_call"
+
+module Mocktail
+  class ExplainsNils
+    extend T::Sig
+
+    sig { void }
+    def initialize
+      @stringifies_method_name = T.let(StringifiesMethodName.new, StringifiesMethodName)
+      @stringifies_call = T.let(StringifiesCall.new, StringifiesCall)
+    end
+
+    sig { returns(T::Array[UnsatisfyingCallExplanation]) }
+    def explain
+      Mocktail.cabinet.unsatisfying_calls.map { |unsatisfying_call|
+        dry_call = unsatisfying_call.call
+        other_stubbings = unsatisfying_call.other_stubbings
+
+        UnsatisfyingCallExplanation.new(unsatisfying_call, <<~MSG)
+          `nil' was returned by a mocked `#{@stringifies_method_name.stringify(dry_call)}' method
+          because none of its configured stubbings were satisfied.
+
+          The actual call:
+
+            #{@stringifies_call.stringify(dry_call, always_parens: true)}
+
+          The call site:
+
+            #{unsatisfying_call.backtrace.first}
+
+          #{@stringifies_call.stringify_multiple(other_stubbings.map(&:recording),
+            nonzero_message: "Stubbings configured prior to this call but not satisfied by it",
+            zero_message: "No stubbings were configured on this method")}
+        MSG
+      }
+    end
+  end
+end

data/src/mocktail/explains_thing.rb

@@ -0,0 +1,137 @@
+# typed: strict
+
+require_relative "share/stringifies_method_name"
+require_relative "share/stringifies_call"
+
+module Mocktail
+  class ExplainsThing
+    extend T::Sig
+
+    sig { void }
+    def initialize
+      @stringifies_method_name = T.let(StringifiesMethodName.new, StringifiesMethodName)
+      @stringifies_call = T.let(StringifiesCall.new, StringifiesCall)
+    end
+
+    sig { params(thing: Object).returns(Explanation) }
+    def explain(thing)
+      if (double = Mocktail.cabinet.double_for_instance(thing))
+        double_explanation(double)
+      elsif (thing.is_a?(Module) || thing.is_a?(Class)) &&
+          (type_replacement = TopShelf.instance.type_replacement_if_exists_for(thing))
+        replaced_type_explanation(type_replacement)
+      elsif (fake_method_explanation = fake_method_explanation_for(thing))
+        fake_method_explanation
+      else
+        no_explanation(thing)
+      end
+    end
+
+    private
+
+    sig { params(thing: Object).returns(T.nilable(FakeMethodExplanation)) }
+    def fake_method_explanation_for(thing)
+      return unless thing.is_a?(Method)
+      method = thing
+      receiver = thing.receiver
+
+      receiver_data = if (double = Mocktail.cabinet.double_for_instance(receiver))
+        data_for_double(double)
+      elsif (type_replacement = TopShelf.instance.type_replacement_if_exists_for(receiver))
+        data_for_type_replacement(type_replacement)
+      end
+
+      if receiver_data
+        FakeMethodExplanation.new(FakeMethodData.new(
+          receiver: receiver,
+          calls: receiver_data.calls,
+          stubbings: receiver_data.stubbings
+        ), describe_dry_method(receiver_data, method.name))
+      end
+    end
+
+    sig { params(double: Double).returns(DoubleData) }
+    def data_for_double(double)
+      DoubleData.new(
+        type: double.original_type,
+        double: double.dry_instance,
+        calls: Mocktail.cabinet.calls_for_double(double),
+        stubbings: Mocktail.cabinet.stubbings_for_double(double)
+      )
+    end
+
+    sig { params(double: Double).returns(DoubleExplanation) }
+    def double_explanation(double)
+      double_data = data_for_double(double)
+
+      DoubleExplanation.new(double_data, <<~MSG)
+        This is a fake `#{double.original_type.name}' instance.
+
+        It has these mocked methods:
+        #{double.dry_methods.sort.map { |method| "  - #{method}" }.join("\n")}
+
+        #{double.dry_methods.sort.map { |method| describe_dry_method(double_data, method) }.join("\n")}
+      MSG
+    end
+
+    sig { params(type_replacement: TypeReplacement).returns(TypeReplacementData) }
+    def data_for_type_replacement(type_replacement)
+      TypeReplacementData.new(
+        type: type_replacement.type,
+        replaced_method_names: type_replacement.replacement_methods&.map(&:name)&.sort || [],
+        calls: Mocktail.cabinet.calls.select { |call|
+          call.double == type_replacement.type
+        },
+        stubbings: Mocktail.cabinet.stubbings.select { |stubbing|
+          stubbing.recording.double == type_replacement.type
+        }
+      )
+    end
+
+    sig { params(type_replacement: TypeReplacement).returns(ReplacedTypeExplanation) }
+    def replaced_type_explanation(type_replacement)
+      type_replacement_data = data_for_type_replacement(type_replacement)
+
+      ReplacedTypeExplanation.new(type_replacement_data, <<~MSG)
+        `#{type_replacement.type}' is a #{type_replacement.type.class.to_s.downcase} that has had its methods faked.
+
+        It has these mocked methods:
+        #{type_replacement_data.replaced_method_names.map { |method| "  - #{method}" }.join("\n")}
+
+        #{type_replacement_data.replaced_method_names.map { |method| describe_dry_method(type_replacement_data, method) }.join("\n")}
+      MSG
+    end
+
+    sig { params(double_data: T.any(DoubleData, TypeReplacementData), method: Symbol).returns(String) }
+    def describe_dry_method(double_data, method)
+      method_name = @stringifies_method_name.stringify(Call.new(
+        original_type: double_data.type,
+        singleton: double_data.type == double_data.double,
+        method: method
+      ))
+
+      [
+        @stringifies_call.stringify_multiple(
+          double_data.stubbings.map(&:recording).select { |call|
+            call.method == method
+          },
+          nonzero_message: "`#{method_name}' stubbings",
+          zero_message: "`#{method_name}' has no stubbings"
+        ),
+        @stringifies_call.stringify_multiple(
+          double_data.calls.select { |call|
+            call.method == method
+          },
+          nonzero_message: "`#{method_name}' calls",
+          zero_message: "`#{method_name}' has no calls"
+        )
+      ].join("\n")
+    end
+
+    sig { params(thing: Object).returns(NoExplanation) }
+    def no_explanation(thing)
+      NoExplanation.new(NoExplanationData.new(thing: thing),
+        "Unfortunately, Mocktail doesn't know what this thing is: #{thing.inspect}")
+    end
+  end
+end

data/src/mocktail/grabs_original_method_parameters.rb

@@ -0,0 +1,33 @@
+# typed: strict
+
+module Mocktail
+  class GrabsOriginalMethodParameters
+    extend T::Sig
+
+    # Sorbet wraps the original method in a sig wrapper, so we need to unwrap it.
+    # The value returned from `owner.instance_method(method_name)` does not have
+    # the real parameters values available, as they'll have been erased
+    #
+    # If the method isn't wrapped by Sorbet, this will return the #instance_method,
+    # per usual
+    sig { params(method: T.nilable(T.any(UnboundMethod, Method))).returns(T::Array[T::Array[Symbol]]) }
+    def grab(method)
+      return [] unless method
+
+      if (wrapped_method = sorbet_wrapped_method(method))
+        wrapped_method.parameters
+      else
+        method.parameters
+      end
+    end
+
+    private
+
+    sig { params(method: T.any(UnboundMethod, Method)).returns(T.nilable(T::Private::Methods::Signature)) }
+    def sorbet_wrapped_method(method)
+      return unless defined?(::T::Private::Methods)
+
+      T::Private::Methods.signature_for_method(method)
+    end
+  end
+end

data/src/mocktail/handles_dry_call/fulfills_stubbing/describes_unsatisfied_stubbing.rb

@@ -0,0 +1,27 @@
+# typed: strict
+
+require_relative "../../share/cleans_backtrace"
+require_relative "../../share/bind"
+
+module Mocktail
+  class DescribesUnsatisfiedStubbing
+    extend T::Sig
+
+    sig { void }
+    def initialize
+      @cleans_backtrace = T.let(CleansBacktrace.new, Mocktail::CleansBacktrace)
+    end
+
+    sig { params(dry_call: Mocktail::Call).returns(Mocktail::UnsatisfyingCall) }
+    def describe(dry_call)
+      UnsatisfyingCall.new(
+        call: dry_call,
+        other_stubbings: Mocktail.cabinet.stubbings.select { |stubbing|
+          Bind.call(dry_call.double, :==, stubbing.recording.double) &&
+            dry_call.method == stubbing.recording.method
+        },
+        backtrace: @cleans_backtrace.clean(Error.new).backtrace || []
+      )
+    end
+  end
+end

data/src/mocktail/handles_dry_call/fulfills_stubbing/finds_satisfaction.rb

@@ -0,0 +1,24 @@
+# typed: strict
+
+require_relative "../../share/determines_matching_calls"
+
+module Mocktail
+  class FindsSatisfaction
+    extend T::Sig
+
+    sig { void }
+    def initialize
+      @determines_matching_calls = T.let(DeterminesMatchingCalls.new, Mocktail::DeterminesMatchingCalls)
+    end
+
+    sig { params(dry_call: Call).returns(T.nilable(Stubbing[T.anything])) }
+    def find(dry_call)
+      Mocktail.cabinet.stubbings.reverse.find { |stubbing|
+        demo_config_times = stubbing.demo_config.times
+
+        @determines_matching_calls.determine(dry_call, stubbing.recording, stubbing.demo_config) &&
+          (demo_config_times.nil? || demo_config_times > stubbing.satisfaction_count)
+      }
+    end
+  end
+end

data/src/mocktail/handles_dry_call/fulfills_stubbing.rb

@@ -0,0 +1,45 @@
+# typed: strict
+
+require_relative "fulfills_stubbing/finds_satisfaction"
+require_relative "fulfills_stubbing/describes_unsatisfied_stubbing"
+
+module Mocktail
+  class FulfillsStubbing
+    extend T::Sig
+
+    sig { void }
+    def initialize
+      @finds_satisfaction = T.let(FindsSatisfaction.new, Mocktail::FindsSatisfaction)
+      @describes_unsatisfied_stubbing = T.let(DescribesUnsatisfiedStubbing.new, Mocktail::DescribesUnsatisfiedStubbing)
+    end
+
+    sig { params(dry_call: Call).returns(T.anything) }
+    def fulfill(dry_call)
+      if (stubbing = satisfaction(dry_call))
+        stubbing.satisfied!
+        stubbing.effect&.call(dry_call)
+      else
+        store_unsatisfying_call!(dry_call)
+        nil
+      end
+    end
+
+    sig { params(dry_call: Call).returns(T.nilable(Stubbing[T.anything])) }
+    def satisfaction(dry_call)
+      return if Mocktail.cabinet.demonstration_in_progress?
+
+      @finds_satisfaction.find(dry_call)
+    end
+
+    private
+
+    sig { params(dry_call: Call).void }
+    def store_unsatisfying_call!(dry_call)
+      return if Mocktail.cabinet.demonstration_in_progress?
+
+      Mocktail.cabinet.store_unsatisfying_call(
+        @describes_unsatisfied_stubbing.describe(dry_call)
+      )
+    end
+  end
+end

data/src/mocktail/handles_dry_call/logs_call.rb

@@ -0,0 +1,12 @@
+# typed: strict
+
+module Mocktail
+  class LogsCall
+    extend T::Sig
+
+    sig { params(dry_call: Call).void }
+    def log(dry_call)
+      Mocktail.cabinet.store_call(dry_call)
+    end
+  end
+end

data/src/mocktail/handles_dry_call/validates_arguments.rb

@@ -0,0 +1,45 @@
+# typed: strict
+
+module Mocktail
+  class ValidatesArguments
+    extend T::Sig
+    sig { void }
+    def self.disable!
+      Thread.current[:mocktail_arity_validation_disabled] = true
+    end
+
+    sig { void }
+    def self.enable!
+      Thread.current[:mocktail_arity_validation_disabled] = false
+    end
+
+    sig { returns(T::Boolean) }
+    def self.disabled?
+      !!Thread.current[:mocktail_arity_validation_disabled]
+    end
+
+    sig { params(disable: T.nilable(T::Boolean), blk: T.proc.returns(T.anything)).void }
+    def self.optional(disable, &blk)
+      return blk.call unless disable
+
+      disable!
+      ret = blk.call
+      enable!
+      ret
+    end
+
+    sig { void }
+    def initialize
+      @simulates_argument_error = T.let(SimulatesArgumentError.new, Mocktail::SimulatesArgumentError)
+    end
+
+    sig { params(dry_call: Call).returns(NilClass) }
+    def validate(dry_call)
+      return if self.class.disabled?
+
+      if (error = @simulates_argument_error.simulate(dry_call))
+        raise error
+      end
+    end
+  end
+end

data/src/mocktail/handles_dry_call.rb

@@ -0,0 +1,25 @@
+# typed: strict
+
+require_relative "handles_dry_call/fulfills_stubbing"
+require_relative "handles_dry_call/logs_call"
+require_relative "handles_dry_call/validates_arguments"
+
+module Mocktail
+  class HandlesDryCall
+    extend T::Sig
+
+    sig { void }
+    def initialize
+      @validates_arguments = T.let(ValidatesArguments.new, ValidatesArguments)
+      @logs_call = T.let(LogsCall.new, LogsCall)
+      @fulfills_stubbing = T.let(FulfillsStubbing.new, FulfillsStubbing)
+    end
+
+    sig { params(dry_call: Call).returns(T.anything) }
+    def handle(dry_call)
+      @validates_arguments.validate(dry_call)
+      @logs_call.log(dry_call)
+      @fulfills_stubbing.fulfill(dry_call)
+    end
+  end
+end

data/src/mocktail/handles_dry_new_call.rb

@@ -0,0 +1,42 @@
+# typed: strict
+
+module Mocktail
+  class HandlesDryNewCall
+    extend T::Sig
+
+    sig { void }
+    def initialize
+      @validates_arguments = T.let(ValidatesArguments.new, ValidatesArguments)
+      @logs_call = T.let(LogsCall.new, LogsCall)
+      @fulfills_stubbing = T.let(FulfillsStubbing.new, FulfillsStubbing)
+      @imitates_type = T.let(ImitatesType.new, ImitatesType)
+    end
+
+    sig { params(type: T::Class[T.all(T, Object)], args: T::Array[T.anything], kwargs: T::Hash[Symbol, T.anything], block: T.nilable(Proc)).returns(T.anything) }
+    def handle(type, args, kwargs, block)
+      @validates_arguments.validate(Call.new(
+        original_method: type.instance_method(:initialize),
+        args: args,
+        kwargs: kwargs,
+        block: block
+      ))
+
+      new_call = Call.new(
+        singleton: true,
+        double: type,
+        original_type: type,
+        dry_type: type,
+        method: :new,
+        args: args,
+        kwargs: kwargs,
+        block: block
+      )
+      @logs_call.log(new_call)
+      if @fulfills_stubbing.satisfaction(new_call)
+        @fulfills_stubbing.fulfill(new_call)
+      else
+        @imitates_type.imitate(type)
+      end
+    end
+  end
+end

data/src/mocktail/imitates_type/ensures_imitation_support.rb

@@ -0,0 +1,16 @@
+# typed: strict
+
+module Mocktail
+  class EnsuresImitationSupport
+    extend T::Sig
+
+    sig { params(type: T.any(T::Class[T.anything], Module)).void }
+    def ensure(type)
+      unless type.is_a?(Class) || type.is_a?(Module)
+        raise UnsupportedMocktail.new <<~MSG.tr("\n", " ")
+          Mocktail.of() can only mix mocktail instances of modules and classes.
+        MSG
+      end
+    end
+  end
+end

data/src/mocktail/imitates_type/makes_double/declares_dry_class/reconstructs_call.rb

@@ -0,0 +1,73 @@
+# typed: strict
+
+module Mocktail
+  class ReconstructsCall
+    extend T::Sig
+
+    sig {
+      params(
+        double: Object,
+        call_binding: Binding,
+        default_args: T.nilable(T::Hash[Symbol, T.anything]),
+        dry_class: T::Class[Object],
+        type: T.any(Module, T::Class[T.anything]),
+        method: Symbol,
+        original_method: T.any(UnboundMethod, Method),
+        signature: Signature
+      ).returns(Call)
+    }
+    def reconstruct(double:, call_binding:, default_args:, dry_class:, type:, method:, original_method:, signature:)
+      Call.new(
+        singleton: false,
+        double: double,
+        original_type: type,
+        dry_type: dry_class,
+        method: method,
+        original_method: original_method,
+        args: args_for(signature, call_binding, default_args),
+        kwargs: kwargs_for(signature, call_binding, default_args),
+        block: call_binding.local_variable_get(signature.block_param || ::Mocktail::Signature::DEFAULT_BLOCK_PARAM)
+      )
+    end
+
+    private
+
+    sig {
+      params(signature: Signature, call_binding: Binding, default_args: T.nilable(T::Hash[Symbol, T.anything]))
+        .returns(T::Array[T.anything])
+    }
+    def args_for(signature, call_binding, default_args)
+      arg_names, rest_name = non_default_args(signature.positional_params, default_args)
+
+      arg_values = arg_names.map { |p| call_binding.local_variable_get(p) }
+      rest_value = call_binding.local_variable_get(rest_name) if rest_name
+
+      arg_values + (rest_value || [])
+    end
+
+    sig {
+      params(signature: Signature, call_binding: Binding, default_args: T.nilable(T::Hash[Symbol, T.anything]))
+        .returns(T::Hash[Symbol, T.anything])
+    }
+    def kwargs_for(signature, call_binding, default_args)
+      kwarg_names, kwrest_name = non_default_args(signature.keyword_params, default_args)
+
+      kwarg_values = kwarg_names.to_h { |p| [p, call_binding.local_variable_get(p)] }
+      kwrest_value = call_binding.local_variable_get(kwrest_name) if kwrest_name
+
+      kwarg_values.merge(kwrest_value || {})
+    end
+
+    sig { params(params: Params, default_args: T.nilable(T::Hash[Symbol, T.anything])).returns([T::Array[Symbol], T.nilable(Symbol)]) }
+    def non_default_args(params, default_args)
+      named_args = params.allowed
+        .reject { |p| default_args&.key?(p) }
+      rest_param = params.rest
+      rest_arg = if rest_param && !default_args&.key?(rest_param)
+        params.rest
+      end
+
+      [named_args, rest_arg]
+    end
+  end
+end