mocktail 1.1.2 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7eb64f90875e53a9bfd5b4d995f8526eb6695dd9bd8a88c850b02eed851cb96d
-  data.tar.gz: ae2b4443a3740c375c70e7e490cbe3463d9672f17665ae47930b6ee614e9891d
+  metadata.gz: 0c303d4fb9ecc3a03e30fcfb52425cec2c4f3b2ca2ad3dadda3f9a09c1b8785a
+  data.tar.gz: 90b573a3b6417d1c084fa7ced22af80b0533e36c45240d42c9627b3bfde2a032
 SHA512:
-  metadata.gz: de8d47071e93c4d406391a1155dea9b6a1a9ac89f56422ae29e6dda5f134c9e5e724ec8006aba833b5ff19d9d2dff4550384bc349506f5ab9cefe3fd2185af1d
-  data.tar.gz: 5bf88d0aadc08fe9a9380312cf491146439e72e335091e2e79849196b74e93aba20b0fac2d122152a4661008ee243b5b3b39cb6408fc776b2cc2567ffca0924f
+  metadata.gz: f2aa7140202bfb3d5cadc45964f344cce19ba688d807b9c25b2033d27dd15710424fc00315633129429215892ea149160d2fbba2a8671bb2237867b12ce7c225
+  data.tar.gz: 95f1c02d8f23849f0a5932e8cddb3f811dc01962e13e0553f1964ebf9f77489b49ce375506e3f2a5f9132bcda7493b2ffc8a03dc61dd4f5018f84fe33995245f

data/CHANGELOG.md

@@ -1,3 +1,19 @@
+# 1.2.0
+
+* Introduce the Mocktail.calls() API https://github.com/testdouble/mocktail/pull/16
+
+# 1.1.3
+
+* Improve the robustness of how we call the original methods on doubles &
+  replaced class methods on mocks internally by Mocktail to avoid behavior being
+  altered by how users configure mock objects
+
+# 1.1.2
+
+* Fix cases where classes that redefine built-in methods could cause issues when
+  Mocktail in turn called those methods internally
+  [#15](https://github.com/testdouble/mocktail/pull/15)
+
 # 1.1.1
 
 * Improve output for undefined singleton methods

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    mocktail (1.1.2)
+    mocktail (1.2.0)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -12,7 +12,7 @@ and even safely override class methods.
 
 If you'd prefer a voice & video introduction to Mocktail aside from this README,
 you might enjoy this ⚡️[Lightning
-Talk](https://blog.testdouble.com/talks/2022-05-18-please-mock-me?utm_source=twitter&utm_medium=organic-social&utm_campaign=conf-talk)⚡️ 
+Talk](https://blog.testdouble.com/talks/2022-05-18-please-mock-me?utm_source=twitter&utm_medium=organic-social&utm_campaign=conf-talk)⚡️
 from RailsConf 2022.
 
 ## An aperitif
@@ -404,6 +404,10 @@ verify { |m| auditor.record!("ok", user_id: 1) { |block| block.call.is_a?(Date)
 * `ignore_block` will similarly allow the demonstration to forego specifying a
   block, even if the actual call receives one
 
+Note that if you want to verify a method _wasn't_ called at all or called a
+specific number of times—especially if you don't care about the parameters, you
+may want to look at the [Mocktail.calls()](#mocktailcalls) API.
+
 ### Mocktail.matchers
 
 You'll probably never need to call `Mocktail.matchers` directly, because it's
@@ -807,6 +811,54 @@ The `reference` object will have details of the `call` itself, an array of
 `other_stubbings` defined on the faked method, and a `backtrace` to determine
 which call site produced the unexpected `nil` value.
 
+### Mocktail.calls
+
+When practicing test-driven development, you may want to ensure that a
+dependency wasn't called at all, and don't particularly care about the
+parameters. To provide a terse way to express this, Mocktail offers a top-level
+`calls(double, method_name = nil)` method that returns an array of the calls to
+the mock (optionally filtered to a particular method name) in the order they
+were called.
+
+Suppose you were writing a test of this method for example:
+
+```ruby
+def import_users
+  users_response = @gets_users.get
+  if users_response.success?
+    @upserts_users.upsert(users_response.data)
+  end
+end
+```
+
+A test case of the negative branch of that `if` statement (when `success?` is
+false) might simply want to assert that `@upserts_users.upsert` wasn't called at
+all, regardless of its parameters.
+
+The easiest way to do this is to use `Mocktail.calls()` method, which is an
+alias of [Mocktail.explain(double).reference.calls](#mocktailexplain) that can
+filter to a specific method name. In the case of a test of the above method, you
+could assert:
+
+```ruby
+# Assert that the `upsert` method on the mock was never called
+assert_equal 0, Mocktail.calls(@upserts_users, :upsert).size
+
+# Assert that NO METHODS on the mock were called at all:
+assert_equal 0, Mocktail.calls(@upserts_users).size
+```
+
+If you're interested in doing more complicated introspection in the nature of
+the calls, their ordering, and so forth, the `calls` method will return
+`Mocktail::Call` values with the args, kwargs, block, and information about the
+original class and method being mocked.
+
+(While this behavior can technically be accomplished with `verify(times: 0) { …
+}`, it's verbose and error prone to do so. Because `verify` is careful to only
+assert exact argument matches, it can get pretty confusing to remember to tack
+on `ignore_extra_args: true` and to call the method with zero args to cover all
+cases.)
+
 ### Mocktail.reset
 
 This one's simple: you probably want to call `Mocktail.reset` after each test,

data/bin/rake

@@ -0,0 +1,29 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'rake' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require "pathname"
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+bundle_binstub = File.expand_path("../bundle", __FILE__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 300) =~ /This file was generated by Bundler/
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("rake", "rake")

data/lib/mocktail/collects_calls.rb

@@ -0,0 +1,13 @@
+module Mocktail
+  class CollectsCalls
+    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/lib/mocktail/handles_dry_call/fulfills_stubbing/describes_unsatisfied_stubbing.rb

@@ -1,19 +1,18 @@
 require_relative "../../share/cleans_backtrace"
-require_relative "../../share/compares_safely"
+require_relative "../../share/bind"
 
 module Mocktail
   class DescribesUnsatisfiedStubbing
     def initialize
       @cleans_backtrace = CleansBacktrace.new
-      @compares_safely = ComparesSafely.new
     end
 
     def describe(dry_call)
       UnsatisfyingCall.new(
         call: dry_call,
         other_stubbings: Mocktail.cabinet.stubbings.select { |stubbing|
-          @compares_safely.compare(dry_call.double, stubbing.recording.double) &&
-            @compares_safely.compare(dry_call.method, stubbing.recording.method)
+          Bind.call(dry_call.double, :==, stubbing.recording.double) &&
+            dry_call.method == stubbing.recording.method
         },
         backtrace: @cleans_backtrace.clean(Error.new).backtrace
       )

data/lib/mocktail/share/bind.rb

@@ -0,0 +1,14 @@
+module Mocktail
+  module Bind
+    def self.call(mock, method_name, *args, **kwargs, &blk)
+      if Mocktail.cabinet.double_for_instance(mock)
+        Object.instance_method(method_name).bind_call(mock, *args, **kwargs, &blk)
+      elsif (type_replacement = TopShelf.instance.type_replacement_if_exists_for(mock)) &&
+          (og_method = type_replacement.original_methods&.find { |m| m.name == method_name })
+        og_method.call(*args, **kwargs, &blk)
+      else
+        mock.__send__(method_name, *args, **kwargs, &blk)
+      end
+    end
+  end
+end

data/lib/mocktail/share/determines_matching_calls.rb

@@ -1,14 +1,10 @@
-require_relative "compares_safely"
+require_relative "bind"
 
 module Mocktail
   class DeterminesMatchingCalls
-    def initialize
-      @compares_safely = ComparesSafely.new
-    end
-
     def determine(real_call, demo_call, demo_config)
-      @compares_safely.compare(real_call.double, demo_call.double) &&
-        @compares_safely.compare(real_call.method, demo_call.method) &&
+      Bind.call(real_call.double, :==, demo_call.double) &&
+        real_call.method == demo_call.method &&
 
         # Matcher implementation will replace this:
         args_match?(real_call.args, demo_call.args, demo_config.ignore_extra_args) &&
@@ -55,11 +51,11 @@ module Mocktail
     end
 
     def match?(real_arg, demo_arg)
-      if demo_arg.respond_to?(:is_mocktail_matcher?) &&
+      if Bind.call(demo_arg, :respond_to?, :is_mocktail_matcher?) &&
           demo_arg.is_mocktail_matcher?
         demo_arg.match?(real_arg)
       else
-        demo_arg == real_arg # TODO <-- test if mock object and call safe compare if so, otherwise ==
+        Bind.call(demo_arg, :==, real_arg)
       end
     end
   end

data/lib/mocktail/simulates_argument_error/transforms_params.rb

@@ -1,22 +1,18 @@
-require_relative "../share/compares_safely"
+require_relative "../share/bind"
 
 module Mocktail
   class TransformsParams
-    def initialize
-      @compares_safely = ComparesSafely.new
-    end
-
     def transform(dry_call)
       params = dry_call.original_method.parameters
 
       Signature.new(
         positional_params: Params.new(
           all: params.select { |t, _|
-            [:req, :opt, :rest].any? { |param_type| @compares_safely.compare(t, param_type) }
+            [:req, :opt, :rest].any? { |param_type| Bind.call(t, :==, param_type) }
           }.map { |_, name| name },
-          required: params.select { |t, _| @compares_safely.compare(t, :req) }.map { |_, n| n },
-          optional: params.select { |t, _| @compares_safely.compare(t, :opt) }.map { |_, n| n },
-          rest: params.find { |t, _| @compares_safely.compare(t, :rest) } & [1]
+          required: params.select { |t, _| Bind.call(t, :==, :req) }.map { |_, n| n },
+          optional: params.select { |t, _| Bind.call(t, :==, :opt) }.map { |_, n| n },
+          rest: params.find { |t, _| Bind.call(t, :==, :rest) } & [1]
         ),
         positional_args: dry_call.args,
 
@@ -24,13 +20,13 @@ module Mocktail
           all: params.select { |type, _|
             [:keyreq, :key, :keyrest].include?(type)
           }.map { |_, name| name },
-          required: params.select { |t, _| @compares_safely.compare(t, :keyreq) }.map { |_, n| n },
-          optional: params.select { |t, _| @compares_safely.compare(t, :key) }.map { |_, n| n },
-          rest: params.find { |t, _| @compares_safely.compare(t, :keyrest) } & [1]
+          required: params.select { |t, _| Bind.call(t, :==, :keyreq) }.map { |_, n| n },
+          optional: params.select { |t, _| Bind.call(t, :==, :key) }.map { |_, n| n },
+          rest: params.find { |t, _| Bind.call(t, :==, :keyrest) } & [1]
         ),
         keyword_args: dry_call.kwargs,
 
-        block_param: params.find { |t, _| @compares_safely.compare(t, :block) } & [1],
+        block_param: params.find { |t, _| Bind.call(t, :==, :block) } & [1],
         block_arg: dry_call.block
       )
     end

data/lib/mocktail/value/cabinet.rb

@@ -1,4 +1,4 @@
-require_relative "../share/compares_safely"
+require_relative "../share/bind"
 
 # The Cabinet stores all thread-local state, so anything that goes here
 # is guaranteed by Mocktail to be local to the currently-running thread
@@ -8,7 +8,6 @@ module Mocktail
     attr_reader :calls, :stubbings, :unsatisfying_calls
 
     def initialize
-      @compares_safely = ComparesSafely.new
       @doubles = []
       @calls = []
       @stubbings = []
@@ -48,18 +47,21 @@ module Mocktail
     end
 
     def double_for_instance(thing)
-      @doubles.find { |double| @compares_safely.compare(double.dry_instance, thing) }
+      @doubles.find { |double|
+        # Intentionally calling directly to avoid an infinite recursion in Bind.call
+        Object.instance_method(:==).bind_call(double.dry_instance, thing)
+      }
     end
 
     def stubbings_for_double(double)
       @stubbings.select { |stubbing|
-        @compares_safely.compare(stubbing.recording.double, double.dry_instance)
+        Bind.call(stubbing.recording.double, :==, double.dry_instance)
       }
     end
 
     def calls_for_double(double)
       @calls.select { |call|
-        @compares_safely.compare(call.double, double.dry_instance)
+        Bind.call(call.double, :==, double.dry_instance)
       }
     end
   end

data/lib/mocktail/version.rb

@@ -1,3 +1,3 @@
 module Mocktail
-  VERSION = "1.1.2"
+  VERSION = "1.2.0"
 end

data/lib/mocktail.rb

@@ -1,3 +1,4 @@
+require_relative "mocktail/collects_calls"
 require_relative "mocktail/debug"
 require_relative "mocktail/dsl"
 require_relative "mocktail/errors"
@@ -67,6 +68,13 @@ module Mocktail
     ExplainsNils.new.explain
   end
 
+  # An alias for Mocktail.explain(double).reference.calls
+  # Takes an optional second parameter of the method name to filter only
+  # calls to that method
+  def self.calls(double, method_name = nil)
+    CollectsCalls.new.collect(double, method_name)
+  end
+
   # Stores most transactional state about calls & stubbing configurations
   # Anything returned by this is undocumented and could change at any time, so
   # don't commit code that relies on it!

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mocktail
 version: !ruby/object:Gem::Version
-  version: 1.1.2
+  version: 1.2.0
 platform: ruby
 authors:
 - Justin Searls
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-06-25 00:00:00.000000000 Z
+date: 2022-09-21 00:00:00.000000000 Z
 dependencies: []
 description:
 email:
@@ -27,8 +27,10 @@ files:
 - README.md
 - Rakefile
 - bin/console
+- bin/rake
 - bin/setup
 - lib/mocktail.rb
+- lib/mocktail/collects_calls.rb
 - lib/mocktail/debug.rb
 - lib/mocktail/dsl.rb
 - lib/mocktail/errors.rb
@@ -67,8 +69,8 @@ files:
 - lib/mocktail/replaces_type/redefines_new.rb
 - lib/mocktail/replaces_type/redefines_singleton_methods.rb
 - lib/mocktail/resets_state.rb
+- lib/mocktail/share/bind.rb
 - lib/mocktail/share/cleans_backtrace.rb
-- lib/mocktail/share/compares_safely.rb
 - lib/mocktail/share/creates_identifier.rb
 - lib/mocktail/share/determines_matching_calls.rb
 - lib/mocktail/share/stringifies_call.rb
@@ -119,7 +121,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.6
+rubygems_version: 3.3.20
 signing_key:
 specification_version: 4
 summary: Take your objects, and make them a double

data/lib/mocktail/share/compares_safely.rb

@@ -1,7 +0,0 @@
-module Mocktail
-  class ComparesSafely
-    def compare(thing, other_thing)
-      Object.instance_method(:==).bind_call(thing, other_thing)
-    end
-  end
-end