mocktail 0.0.2 → 0.0.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d5a4729eb601d9f3ed3ece213a460dd0881105a505a812c4d035c14cec252223
-  data.tar.gz: f4b3a3352f63de7de812ce8db616b570de740f1ce7550f8677eb47ecb99305fb
+  metadata.gz: 67768c396af3e99d7ef7649d2afecf023f1dbdc0e361d960bebbf6befe908d3b
+  data.tar.gz: 196930b31afa82713bf68469c6d3cb434ce67f22f6cc4c7393c7c438201550c9
 SHA512:
-  metadata.gz: 469b39914d0d887b7cd8d25006f5dc6f3ca8a1a3b5594f39bfae5e3c21f36f2983a30ec2849c916129e216dd9fb731f476abbdc5a41ad0f80c740d7106793a7d
-  data.tar.gz: d7c24487a15c7ddc9b540d6c9d5c2b3f07da3599eba61eee128a79f5faa3fd5f6c4e54b7ea4318119a86737ead855f30d814a7f39e30c1e20a6f3880f0c21ce2
+  metadata.gz: e8b1974f7c8068044c95b4113937aa5cd39972722244ff81bd60038cfe56ff2148a87c8b89bf5487e5b195fa25df1e23f31f667c618e2c375f27615e487d77f7
+  data.tar.gz: b0cf6ae9e2e1b7b2ce0d23144753d7dde66af999c110da1ac8815b2a95b4bdd6ad0ac1e7555fd4a1333bbc983811fd5fa32a052ea22bda01395a24dfb96eb6da

data/CHANGELOG.md

@@ -1,3 +1,31 @@
+# 0.0.6
+
+* Require pathname, which I missed because `bundle exec` loads it. Wups!
+
+# 0.0.5
+
+* Fix concurrency [#6](https://github.com/testdouble/mocktail/pull/6)
+
+# 0.0.4
+
+* Introduce Mocktail.explain(), which will return a message & reference object
+  for any of:
+  * A class that has been passed to Mocktail.replace()
+  * An instance created by Mocktail.of() or of_next()
+  * A nil value returned by an unsatisfied stubbing invocation
+* Fix some minor printing issue with the improved NoMethodError released in
+  0.0.3
+
+
+# 0.0.3
+
+* Implement method_missing on all mocked instance methods to print out useful
+  information, like the target type, the attempted call, an example method
+  definition that would match the call (for paint-by-numbers-like TDD), and
+  did_you_mean gem integration of similar method names in case it was just a
+  miss
+* Cleans artificially-generated argument errors of gem-internal backtraces
+
 # 0.0.2
 
 * Drop Ruby 2.7 support. Unbeknownst to me (since I developed mocktail using

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    mocktail (0.0.2)
+    mocktail (0.0.6)
 
 GEM
   remote: https://rubygems.org/
@@ -60,4 +60,4 @@ DEPENDENCIES
   standard
 
 BUNDLED WITH
-   2.2.15
+   2.2.30

data/README.md

@@ -50,26 +50,37 @@ assert_equal "🎉", result
 verify { glass.pour!(:a_drink) }
 ```
 
-## Why order?
-
-Besides a lack of hangover, Mocktail offers several advantages over other
-mocking libraries:
-
-* **Fewer hoops to jump through**: [`Mocktail.of_next(type)`] avoids the need
-  for dependency injection by returning a Mocktail of the type the next time
-  `Type.new` is called. You can inject a fake into production code in one
-  line.
-* **Fewer false test passes**: Arity of arguments and keyword arguments of faked
-  methods is enforced—no more tests that keep passing after an API changes
-* **Super-duper detailed error messages when verifications fail**
-* **Fake class methods**: Singleton methods on classes and modules can be
-  replaced with [`Mocktail.replace(type)`](#mocktailreplace) while still
-  preserving thread safety
-* **Less test setup**: Dynamic stubbings based on the arguments passed to the actual call
+## Why Mocktail?
+
+Besides helping you avoid a hangover, Mocktail offers several advantages over
+Ruby's other mocking libraries:
+
+* **Simpler test recipes**: [Mocktail.of_next(type)](#mocktailof_next) both
+  creates your mock and supplies to your subject under test in a single
+  one-liner. No more forcing dependency injection for the sake of your tests
+* **WYSIWYG API**: Want to know how to stub a call to `phone.dial(911)`? You
+  just demonstrate the call with `stubs { phone.dial(911) }.with { :operator }`.
+  Because stubbing & verifying looks just like the actual call, your tests
+  becomes a sounding board for your APIs as you invent them
+* **Argument validation**: Ever see a test pass after a change to a mocked
+  method should have broken it? Not with Mocktail, you haven't
+* **Mocked class methods**: Singleton methods on modules and classes can be
+  faked out using [`Mocktail.replace(type)`](#mocktailreplace) without
+  sacrificing thread safety
+* **Super-duper detailed error messages** A good mocking library should make
+  coding feel like
+  [paint-by-number](https://en.wikipedia.org/wiki/Paint_by_number), thoughtfully
+  guiding you from one step to the next. Calling a method that doesn't exist
+  will print a sample definition you can copy-paste. Verification failures will
+  print every call that _did_ occur. And [Mocktail.explain()](#mocktailexplain)
+  provides even more introspection
 * **Expressive**: Built-in [argument matchers](#mocktailmatchers) and a simple
-  API for adding [custom matchers](#custom-matchers)
+  API for adding [custom matchers](#custom-matchers) allow you to tune your
+  stubbing configuration and call verification to match _exactly_ what your test
+  intends
 * **Powerful**: [Argument captors](#mocktailcaptor) for assertions of very
-  complex arguments
+  complex arguments, as well as advanced configuration options for stubbing &
+  verification
 
 ## Ready to order?
 
@@ -539,6 +550,154 @@ down bugs. (If this concerns you, then the fact that class methods are
 effectively global state may be a great reason not to rely too heavily on
 them!)]
 
+### Mocktail.explain
+
+Test debugging is hard enough when there _aren't_ fake objects flying every
+which way, so Mocktail tries to make it a little easier by way of better
+messages throughout the library.
+
+#### Undefined methods
+
+One message you'll see automatically if you try to call a method
+that doesn't exist is this one, which gives a sample definition of the method
+you had attempted to call:
+
+```ruby
+class IceTray
+end
+
+ice_tray = Mocktail.of(IceTray)
+
+ice_tray.fill(:water_type, 30)
+# => No method `IceTray#fill' exists for call: (NoMethodError)
+#
+#      fill(:water_type, 30)
+#
+#    Need to define the method? Here's a sample definition:
+#
+#      def fill(water_type, arg)
+#      end
+```
+
+From there, you can just copy-paste the provided method stub as a starting point
+for your new method.
+
+#### `nil` values returned by faked methods
+
+Suppose you go ahead and implement the `fill` method above and configure a
+stubbing:
+
+```ruby
+ice_tray = Mocktail.of(IceTray)
+
+stubs { ice_tray.fill(:tap_water, 30) }.with { :normal_ice }
+```
+
+But then you find that your subject under test is just getting `nil` back and
+you don't understand why:
+
+```ruby
+def prep
+  ice = ice_tray.fill(:tap_water, 50) # => nil
+  glass.add(ice)
+end
+```
+
+You can pass that `nil` value to `Mocktail.explain` and get an
+`UnsatisfiedStubExplanation` that will include both a `reference` object to explore
+ as well a summary message:
+
+```ruby
+def prep
+  ice = ice_tray.fill(:tap_water, 50).tap do |wat|
+    puts Mocktail.explain(wat).message
+  end
+  glass.add(ice)
+end
+```
+
+Which will print:
+
+```
+This `nil' was returned by a mocked `IceTray#fill' method
+because none of its configured stubbings were satisfied.
+
+The actual call:
+
+  fill(:tap_water, 50)
+
+Stubbings configured prior to this call but not satisfied by it:
+
+  fill(:tap_water, 30)
+```
+
+#### Fake instances created by Mocktail
+
+Any instances created by `Mocktail.of` or `Mocktail.of_next` can also be passed
+to `Mocktail.explain`, and they will list out all the calls and stubbings made
+for each of their fake methods.
+
+Calling `Mocktail.explain(ice_tray).message` following the example above will
+yield:
+
+```
+This is a fake `IceTray' instance.
+
+It has these mocked methods:
+  - fill
+
+`IceTray#fill' stubbings:
+
+  fill(:tap_water, 30)
+
+`IceTray#fill' calls:
+
+  fill(:tap_water, 50)
+```
+
+#### Modules and classes with singleton methods replaced
+
+If you've called `Mocktail.replace()` on a class or module, it can also be
+passed to `Mocktail.explain()` for a summary of all the stubbing configurations
+and calls made against its faked singleton methods for the currently running
+thread.
+
+```ruby
+Mocktail.replace(Shop)
+
+stubs { |m| Shop.open!(m.numeric) }.with { :a_bar }
+
+Shop.open!(42)
+
+Shop.close!(42)
+
+puts Mocktail.explain(Shop).message
+```
+
+Will print:
+
+```ruby
+`Shop' is a class that has had its singleton methods faked.
+
+It has these mocked methods:
+  - close!
+  - open!
+
+`Shop.close!' has no stubbings.
+
+`Shop.close!' calls:
+
+  close!(42)
+
+`Shop.open!' stubbings:
+
+  open!(numeric)
+
+`Shop.open!' calls:
+
+  open!(42)
+```
+
 ### Mocktail.reset
 
 This one's simple: you probably want to call `Mocktail.reset` after each test,
@@ -572,3 +731,4 @@ including (but not limited to) one-on-one communications, public posts/comments,
 code reviews, pull requests, and GitHub issues. If violations occur, Test Double
 will take any action they deem appropriate for the infraction, up to and
 including blocking a user from the organization's repositories.
+

data/bin/console

@@ -56,6 +56,26 @@ class Bartender
   end
 end
 
-# (If you use this, don't forget to add pry to your Gemfile!)
+class IceTray
+  def fill(water_type, amount)
+  end
+end
+
+class Shop
+  def self.open!(bar_id)
+  end
+
+  def self.close!(bar_id)
+  end
+end
+
+Mocktail.replace(Shop)
+
+stubs { |m| Shop.open!(m.numeric) }.with { :a_bar }
+
+Shop.open!(42)
+
+Shop.close!(42)
+
 require "pry"
 Pry.start

data/lib/mocktail/explains_thing.rb

@@ -0,0 +1,132 @@
+require_relative "share/stringifies_method_name"
+require_relative "share/stringifies_call"
+
+module Mocktail
+  class ExplainsThing
+    def initialize
+      @stringifies_method_name = StringifiesMethodName.new
+      @stringifies_call = StringifiesCall.new
+    end
+
+    def explain(thing)
+      if is_stub_returned_nil?(thing)
+        unsatisfied_stub_explanation(thing)
+      elsif (double = Mocktail.cabinet.double_for_instance(thing))
+        double_explanation(double)
+      elsif (type_replacement = TopShelf.instance.type_replacement_if_exists_for(thing))
+        replaced_type_explanation(type_replacement)
+      else
+        no_explanation(thing)
+      end
+    end
+
+    private
+
+    # Our fake nil doesn't even implement respond_to?, instead quacking like nil
+    def is_stub_returned_nil?(thing)
+      thing.was_returned_by_unsatisfied_stub?
+    rescue NoMethodError
+    end
+
+    def unsatisfied_stub_explanation(stub_returned_nil)
+      unsatisfied_stubbing = stub_returned_nil.unsatisfied_stubbing
+      dry_call = unsatisfied_stubbing.call
+      other_stubbings = unsatisfied_stubbing.other_stubbings
+
+      UnsatisfiedStubExplanation.new(unsatisfied_stubbing, <<~MSG)
+        This `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)}
+
+        #{describe_multiple_calls(other_stubbings.map(&:recording),
+          "Stubbings configured prior to this call but not satisfied by it",
+          "No stubbings were configured on this method")}
+      MSG
+    end
+
+    def double_explanation(double)
+      double_data = DoubleData.new(
+        type: double.original_type,
+        double: double.dry_instance,
+        calls: Mocktail.cabinet.calls_for_double(double),
+        stubbings: Mocktail.cabinet.stubbings_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
+
+    def replaced_type_explanation(type_replacement)
+      type_replacement_data = 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
+        }
+      )
+
+      ReplacedTypeExplanation.new(type_replacement_data, <<~MSG)
+        `#{type_replacement.type}' is a #{type_replacement.type.class.to_s.downcase} that has had its singleton 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
+
+    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
+      ))
+
+      [
+        describe_multiple_calls(
+          double_data.stubbings.map(&:recording).select { |call|
+            call.method == method
+          },
+          "`#{method_name}' stubbings",
+          "`#{method_name}' has no stubbings"
+        ),
+        describe_multiple_calls(
+          double_data.calls.select { |call|
+            call.method == method
+          },
+          "`#{method_name}' calls",
+          "`#{method_name}' has no calls"
+        )
+      ].join("\n")
+    end
+
+    def describe_multiple_calls(calls, nonzero_message, zero_message)
+      if calls.empty?
+        "#{zero_message}.\n"
+      else
+        <<~MSG
+          #{nonzero_message}:
+
+          #{calls.map { |call| "  " + @stringifies_call.stringify(call) }.join("\n\n")}
+        MSG
+      end
+    end
+
+    def no_explanation(thing)
+      NoExplanation.new(thing,
+        "Unfortunately, Mocktail doesn't know what this thing is: #{thing.inspect}")
+    end
+  end
+end

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

@@ -0,0 +1,13 @@
+module Mocktail
+  class DescribesUnsatisfiedStubbing
+    def describe(dry_call)
+      UnsatisfiedStubbing.new(
+        call: dry_call,
+        other_stubbings: Mocktail.cabinet.stubbings.select { |stubbing|
+                           dry_call.double == stubbing.recording.double &&
+                             dry_call.method == stubbing.recording.method
+                         }
+      )
+    end
+  end
+end

data/lib/mocktail/handles_dry_call/fulfills_stubbing.rb

@@ -1,15 +1,19 @@
 require_relative "fulfills_stubbing/finds_satisfaction"
+require_relative "fulfills_stubbing/describes_unsatisfied_stubbing"
 
 module Mocktail
   class FulfillsStubbing
     def initialize
       @finds_satisfaction = FindsSatisfaction.new
+      @describes_unsatisfied_stubbing = DescribesUnsatisfiedStubbing.new
     end
 
     def fulfill(dry_call)
       if (stubbing = satisfaction(dry_call))
         stubbing.satisfied!
         stubbing.effect&.call(dry_call)
+      else
+        StubReturnedNil.new(@describes_unsatisfied_stubbing.describe(dry_call))
       end
     end
 

data/lib/mocktail/handles_dry_call/validates_arguments.rb

@@ -1,5 +1,3 @@
-require_relative "../share/simulates_argument_error"
-
 module Mocktail
   class ValidatesArguments
     def self.disable!
@@ -30,28 +28,9 @@ module Mocktail
     def validate(dry_call)
       return if self.class.disabled?
 
-      arg_params, kwarg_params = dry_call.original_method.parameters.reject { |type, _|
-        type == :block
-      }.partition { |type, _|
-        [:req, :opt, :rest].include?(type)
-      }
-
-      unless args_match?(arg_params, dry_call.args) &&
-          kwargs_match?(kwarg_params, dry_call.kwargs)
-        raise @simulates_argument_error.simulate(arg_params, dry_call.args, kwarg_params, dry_call.kwargs)
+      if (error = @simulates_argument_error.simulate(dry_call))
+        raise error
       end
     end
-
-    private
-
-    def args_match?(arg_params, args)
-      args.size >= arg_params.count { |type, _| type == :req } &&
-        (arg_params.any? { |type, _| type == :rest } || args.size <= arg_params.size)
-    end
-
-    def kwargs_match?(kwarg_params, kwargs)
-      kwarg_params.select { |type, _| type == :keyreq }.all? { |_, name| kwargs.key?(name) } &&
-        (kwarg_params.any? { |type, _| type == :keyrest } || kwargs.keys.all? { |name| kwarg_params.any? { |_, key| name == key } })
-    end
   end
 end

data/lib/mocktail/imitates_type/makes_double/declares_dry_class.rb

@@ -2,13 +2,12 @@ module Mocktail
   class DeclaresDryClass
     def initialize
       @handles_dry_call = HandlesDryCall.new
+      @raises_neato_no_method_error = RaisesNeatoNoMethodError.new
     end
 
-    def declare(type)
-      type_type = type_of(type)
-      instance_methods = instance_methods_on(type)
+    def declare(type, instance_methods)
       dry_class = Class.new(Object) {
-        include type if type_type == :module
+        include type if type.instance_of?(Module)
 
         def initialize(*args, **kwargs, &blk)
         end
@@ -18,15 +17,19 @@ module Mocktail
         }
         alias_method :kind_of?, :is_a?
 
-        if type_type == :class
+        if type.instance_of?(Class)
           define_method :instance_of?, ->(thing) {
             type == thing
           }
         end
       }
 
-      add_stringify_methods!(dry_class, :to_s, type, type_type, instance_methods)
-      add_stringify_methods!(dry_class, :inspect, type, type_type, instance_methods)
+      # These have special implementations, but if the user defines
+      # any of them on the object itself, then they'll be replaced with normal
+      # mocked methods. YMMV
+      add_stringify_methods!(dry_class, :to_s, type, instance_methods)
+      add_stringify_methods!(dry_class, :inspect, type, instance_methods)
+      define_method_missing_errors!(dry_class, type, instance_methods)
 
       define_double_methods!(dry_class, type, instance_methods)
 
@@ -43,7 +46,7 @@ module Mocktail
             singleton: false,
             double: self,
             original_type: type,
-            dry_type: self.class,
+            dry_type: dry_class,
             method: method,
             original_method: type.instance_method(method),
             args: args,
@@ -54,7 +57,7 @@ module Mocktail
       end
     end
 
-    def add_stringify_methods!(dry_class, method_name, type, type_type, instance_methods)
+    def add_stringify_methods!(dry_class, method_name, type, instance_methods)
       dry_class.define_singleton_method method_name, -> {
         if (id_matches = super().match(/:([0-9a-fx]+)>$/))
           "#<Class #{"including module " if type.instance_of?(Module)}for mocktail of #{type.name}:#{id_matches[1]}>"
@@ -74,22 +77,25 @@ module Mocktail
       end
     end
 
-    def type_of(type)
-      if type.is_a?(Class)
-        :class
-      elsif type.is_a?(Module)
-        :module
-      end
-    end
+    def define_method_missing_errors!(dry_class, type, instance_methods)
+      return if instance_methods.include?(:method_missing)
 
-    def instance_methods_on(type)
-      type.instance_methods.reject { |m|
-        ignored_ancestors.include?(type.instance_method(m).owner)
+      raises_neato_no_method_error = @raises_neato_no_method_error
+      dry_class.define_method :method_missing, ->(name, *args, **kwargs, &block) {
+        raises_neato_no_method_error.call(
+          Call.new(
+            singleton: false,
+            double: self,
+            original_type: type,
+            dry_type: self.class,
+            method: name,
+            original_method: nil,
+            args: args,
+            kwargs: kwargs,
+            block: block
+          )
+        )
       }
     end
-
-    def ignored_ancestors
-      Object.ancestors
-    end
   end
 end

data/lib/mocktail/imitates_type/makes_double/gathers_fakeable_instance_methods.rb

@@ -0,0 +1,21 @@
+module Mocktail
+  class GathersFakeableInstanceMethods
+    def gather(type)
+      methods = type.instance_methods + [
+        (:respond_to_missing? if type.private_method_defined?(:respond_to_missing?))
+      ].compact
+
+      methods.reject { |m|
+        ignore?(type, m)
+      }
+    end
+
+    def ignore?(type, method_name)
+      ignored_ancestors.include?(type.instance_method(method_name).owner)
+    end
+
+    def ignored_ancestors
+      Object.ancestors
+    end
+  end
+end

data/lib/mocktail/imitates_type/makes_double.rb

@@ -1,17 +1,21 @@
 require_relative "makes_double/declares_dry_class"
+require_relative "makes_double/gathers_fakeable_instance_methods"
 
 module Mocktail
   class MakesDouble
     def initialize
       @declares_dry_class = DeclaresDryClass.new
+      @gathers_fakeable_instance_methods = GathersFakeableInstanceMethods.new
     end
 
-    def make(klass)
-      dry_type = @declares_dry_class.declare(klass)
+    def make(type)
+      dry_methods = @gathers_fakeable_instance_methods.gather(type)
+      dry_type = @declares_dry_class.declare(type, dry_methods)
       Double.new(
-        original_type: klass,
+        original_type: type,
         dry_type: dry_type,
-        dry_instance: dry_type.new
+        dry_instance: dry_type.new,
+        dry_methods: dry_methods
       )
     end
   end