mocktail 1.1.3 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0aa187046d2e07280352ba6f0296f5573bda910acb111e06d0932f0e2518064e
-  data.tar.gz: c3e5e74d586969ea5dd88dc86c20a9d2e6f223f1bb8a438325583a8d8fb20bae
+  metadata.gz: 0c303d4fb9ecc3a03e30fcfb52425cec2c4f3b2ca2ad3dadda3f9a09c1b8785a
+  data.tar.gz: 90b573a3b6417d1c084fa7ced22af80b0533e36c45240d42c9627b3bfde2a032
 SHA512:
-  metadata.gz: 224a377d46c11b830b90a828e6a0c294e940c3492cde42fda9aa0f865b97cdc69773571d4464bd4bbe185aa29e6860c5a4c2b3b87a458382a84b330ddce5df3e
-  data.tar.gz: 10562536842265afc7f6bef9fa63a8ebab657e78941f13bc0e38cb49cf8f43785d1d926d0f5afe103165d337fe2163cba88aa4aee220004c8a2494e5f5493d4c
+  metadata.gz: f2aa7140202bfb3d5cadc45964f344cce19ba688d807b9c25b2033d27dd15710424fc00315633129429215892ea149160d2fbba2a8671bb2237867b12ce7c225
+  data.tar.gz: 95f1c02d8f23849f0a5932e8cddb3f811dc01962e13e0553f1964ebf9f77489b49ce375506e3f2a5f9132bcda7493b2ffc8a03dc61dd4f5018f84fe33995245f

data/CHANGELOG.md

@@ -1,3 +1,7 @@
+# 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 &

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    mocktail (1.1.3)
+    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/version.rb

@@ -1,3 +1,3 @@
 module Mocktail
-  VERSION = "1.1.3"
+  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.3
+  version: 1.2.0
 platform: ruby
 authors:
 - Justin Searls
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-06-28 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
@@ -119,7 +121,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.7
+rubygems_version: 3.3.20
 signing_key:
 specification_version: 4
 summary: Take your objects, and make them a double