mocktail 0.0.3 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e719e2144c3da8a2569e2ef5e7cf2c78d054625011fcf0bdf8f98f300bdcd805
-  data.tar.gz: 3635b7210ac6d5a7c05c4000f100ac1e07f4c8d5de7de81586e41f3b81e11ce5
+  metadata.gz: 05ec28e8027b6d73ee5b3f513ce4d5e23a60ea0266643e344e20e8f995410ce2
+  data.tar.gz: 7baf1cff682de031f3f25cebad265e59e598c4f4103968ea2dda61b6c7605c9c
 SHA512:
-  metadata.gz: d84b7964c5fbe14e3ef2a8a881c1c328f0f4c37cbde2d1423965016fe26f153c6801032c5aa4a7018db6d98924aecbb031e3e473992178bb9d5fe46e53ac2ea5
-  data.tar.gz: 384e42b818b92ace165e975dafd1482e00a46fc3be4c4abf0bb54e2ff648f29da1b338a8845be5c64e1878abf738e4061345083c0e952206380119ecb82729cf
+  metadata.gz: 4c5eef4fe5c68abd7d1e506bc59db58daa931fb484118e0ee4d6d286944d2834d0bb3107183102ac65110e12f32992b73fadbfcc26ed750bff060535e4eba5a2
+  data.tar.gz: cff11562ac6bc79475719f17f912ffc2fe8af6315ab90dbdc838143c237542ad788cba2d6c05ee15417799b2f597634244edf3c9f50dac5121adbac551602bdb

data/CHANGELOG.md

@@ -1,3 +1,32 @@
+# 1.0.0
+
+* First breaking change! 🎉
+* Remove support for `Mocktail.explain(nil)` because fake nil values cannot be
+made falsey. Pretty big mistake
+* Add `Mocktail.explain_nils` which will return explanation objects of every
+call that didn't satisfy a stubbing since the last reset, including the call
+site where it happened and the backtrace to try to tease out which one you're
+looking for
+
+# 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

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    mocktail (0.0.3)
+    mocktail (1.0.0)
 
 GEM
   remote: https://rubygems.org/
@@ -10,29 +10,29 @@ GEM
     coderay (1.1.3)
     docile (1.4.0)
     method_source (1.0.0)
-    minitest (5.14.4)
+    minitest (5.15.0)
     parallel (1.21.0)
-    parser (3.0.2.0)
+    parser (3.0.3.2)
       ast (~> 2.4.1)
     pry (0.14.1)
       coderay (~> 1.1)
       method_source (~> 1.0)
     rainbow (3.0.0)
     rake (13.0.6)
-    regexp_parser (2.1.1)
+    regexp_parser (2.2.0)
     rexml (3.2.5)
-    rubocop (1.20.0)
+    rubocop (1.23.0)
       parallel (~> 1.10)
       parser (>= 3.0.0.0)
       rainbow (>= 2.2.2, < 4.0)
       regexp_parser (>= 1.8, < 3.0)
       rexml
-      rubocop-ast (>= 1.9.1, < 2.0)
+      rubocop-ast (>= 1.12.0, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 1.4.0, < 3.0)
-    rubocop-ast (1.11.0)
+    rubocop-ast (1.15.0)
       parser (>= 3.0.1.1)
-    rubocop-performance (1.11.5)
+    rubocop-performance (1.12.0)
       rubocop (>= 1.7.0, < 2.0)
       rubocop-ast (>= 0.4.0)
     ruby-progressbar (1.11.0)
@@ -42,9 +42,9 @@ GEM
       simplecov_json_formatter (~> 0.1)
     simplecov-html (0.12.3)
     simplecov_json_formatter (0.1.3)
-    standard (1.3.0)
-      rubocop (= 1.20.0)
-      rubocop-performance (= 1.11.5)
+    standard (1.5.0)
+      rubocop (= 1.23.0)
+      rubocop-performance (= 1.12.0)
     unicode-display_width (2.1.0)
 
 PLATFORMS
@@ -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,181 @@ 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:
+
+```ruby
+class IceTray
+  def fill(water_type, amount)
+  end
+end
+```
+
+### Unexpected nils with Mocktail.explain_nils
+
+Is a faked method returning `nil` and you don't understand why?
+
+By default, methods faked by Mocktail will return `nil` when no stubbing is
+satisfied. A frequent frustration, therefore, is when the way `stubs {}.with {}`
+is configured does not satisfy a call the way you expected. To try to make
+debugging this a little bit easier, the gem provides a top-level
+`Mocktail.explain_nils` method that will return an array of summaries of every
+call to a faked method that failed to satisfy any stubbings.
+
+For example, suppose you stub this `fill` method like so:
+
+```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)
+  glass.add(ice) # => why is `ice` nil?!
+end
+```
+
+Whenever you're confused by a nil, you can call `Mocktail.explain_nils` for an
+array containing `UnsatisfyingCallExplanation` objects (one for each call to
+a faked method that did not satisfy any configured stubbings).
+
+The returned explanation objects will include both a `reference` object to
+explore as well a summary `message`:
+
+```ruby
+def prep
+  ice = ice_tray.fill(:tap_water, 50)
+  puts Mocktail.explain_nils.first.message
+  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)
+
+The call site:
+
+  /path/to/your/code.rb:42:in `prep'
+
+Stubbings configured prior to this call but not satisfied by it:
+
+  fill(:tap_water, 30)
+```
+
+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.
+
+#### Fake instances created by Mocktail
+
+Any instances created by `Mocktail.of` or `Mocktail.of_next` can 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.
+
+Imagine a `Shop` class with `self.open!` and `self.close!` singleton methods:
+
+```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,
@@ -546,6 +732,10 @@ but you _definitely_ want to call it if you're using `Mocktail.replace` or
 `Mocktail.of_next` anywhere, since those will affect state that is shared across
 tests.
 
+Calling reset in a `teardown` or `after(:each)` hook will also improve the
+usefulness of messages returned by `Mocktail.explain` and
+`Mocktail.explain_nils`.
+
 ## Acknowledgements
 
 Mocktail is created & maintained by the software agency [Test
@@ -572,3 +762,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_nils.rb

@@ -0,0 +1,35 @@
+require_relative "share/stringifies_method_name"
+require_relative "share/stringifies_call"
+
+module Mocktail
+  class ExplainsNils
+    def initialize
+      @stringifies_method_name = StringifiesMethodName.new
+      @stringifies_call = StringifiesCall.new
+    end
+
+    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/lib/mocktail/explains_thing.rb

@@ -0,0 +1,93 @@
+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 (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
+
+    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
+      ))
+
+      [
+        @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
+
+    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,20 @@
+require_relative "../../share/cleans_backtrace"
+
+module Mocktail
+  class DescribesUnsatisfiedStubbing
+    def initialize
+      @cleans_backtrace = CleansBacktrace.new
+    end
+
+    def describe(dry_call)
+      UnsatisfyingCall.new(
+        call: dry_call,
+        other_stubbings: Mocktail.cabinet.stubbings.select { |stubbing|
+          dry_call.double == stubbing.recording.double &&
+            dry_call.method == stubbing.recording.method
+        },
+        backtrace: @cleans_backtrace.clean(Error.new).backtrace
+      )
+    end
+  end
+end

data/lib/mocktail/handles_dry_call/fulfills_stubbing.rb

@@ -1,21 +1,37 @@
 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
+        store_unsatisfying_call!(dry_call)
+        nil
       end
     end
 
     def satisfaction(dry_call)
       return if Mocktail.cabinet.demonstration_in_progress?
+
       @finds_satisfaction.find(dry_call)
     end
+
+    private
+
+    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/lib/mocktail/imitates_type/makes_double/declares_dry_class.rb

@@ -5,8 +5,7 @@ module Mocktail
       @raises_neato_no_method_error = RaisesNeatoNoMethodError.new
     end
 
-    def declare(type)
-      instance_methods = instance_methods_on(type)
+    def declare(type, instance_methods)
       dry_class = Class.new(Object) {
         include type if type.instance_of?(Module)
 
@@ -98,23 +97,5 @@ module Mocktail
         )
       }
     end
-
-    def instance_methods_on(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/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

data/lib/mocktail/matchers/captor.rb

@@ -34,6 +34,10 @@ module Mocktail::Matchers
       def captured?
         @captured
       end
+
+      def inspect
+        "capture"
+      end
     end
 
     attr_reader :capture

data/lib/mocktail/matchers/that.rb

@@ -6,7 +6,7 @@ module Mocktail::Matchers
 
     def initialize(&blk)
       if blk.nil?
-        raise "The `that` matcher must be passed a block (e.g. `that { |arg| … }`)"
+        raise ArgumentError.new("The `that` matcher must be passed a block (e.g. `that { |arg| … }`)")
       end
       @blk = blk
     end

data/lib/mocktail/raises_neato_no_method_error.rb

@@ -1,16 +1,18 @@
 require_relative "share/stringifies_call"
+require_relative "share/stringifies_method_name"
 require_relative "share/creates_identifier"
 
 module Mocktail
   class RaisesNeatoNoMethodError
     def initialize
       @stringifies_call = StringifiesCall.new
+      @stringifies_method_name = StringifiesMethodName.new
       @creates_identifier = CreatesIdentifier.new
     end
 
     def call(call)
       raise NoMethodError.new <<~MSG
-        No method `#{call.original_type.name}##{call.method}' exists for call:
+        No method `#{@stringifies_method_name.stringify(call)}' exists for call:
 
           #{@stringifies_call.stringify(call, anonymous_blocks: true, always_parens: true)}
 

data/lib/mocktail/{simulates_argument_error → share}/cleans_backtrace.rb

@@ -1,3 +1,5 @@
+require "pathname"
+
 module Mocktail
   class CleansBacktrace
     BASE_PATH = (Pathname.new(__FILE__) + "../../..").to_s

data/lib/mocktail/share/creates_identifier.rb

@@ -1,13 +1,28 @@
 module Mocktail
   class CreatesIdentifier
+    KEYWORDS = %w[__FILE__ __LINE__ alias and begin BEGIN break case class def defined? do else elsif end END ensure false for if in module next nil not or redo rescue retry return self super then true undef unless until when while yield]
+
     def create(s, default: "identifier", max_length: 24)
-      id = s.to_s.downcase.gsub(/[^\w\s]/, "").gsub(/^\d+/, "")[0...max_length].strip.gsub(/\s+/, "_")
+      id = s.to_s.downcase
+        .gsub(/:0x[0-9a-f]+/, "") # Lazy attempt to wipe any Object:0x802beef identifiers
+        .gsub(/[^\w\s]/, "")
+        .gsub(/^\d+/, "")[0...max_length]
+        .strip
+        .gsub(/\s+/, "_") # snake_case
 
       if id.empty?
         default
       else
-        id
+        unreserved(id, default)
       end
     end
+
+    private
+
+    def unreserved(id, default)
+      return id unless KEYWORDS.include?(id)
+
+      "#{id}_#{default}"
+    end
   end
 end

data/lib/mocktail/share/stringifies_call.rb

@@ -4,6 +4,20 @@ module Mocktail
       "#{call.method}#{args_to_s(call, parens: always_parens)}#{blockify(call.block, anonymous: anonymous_blocks)}"
     end
 
+    def stringify_multiple(calls, nonzero_message:, zero_message:,
+      anonymous_blocks: false, always_parens: false)
+
+      if calls.empty?
+        "#{zero_message}.\n"
+      else
+        <<~MSG
+          #{nonzero_message}:
+
+          #{calls.map { |call| "  " + stringify(call) }.join("\n\n")}
+        MSG
+      end
+    end
+
     private
 
     def args_to_s(call, parens: true)

data/lib/mocktail/share/stringifies_method_name.rb

@@ -0,0 +1,11 @@
+module Mocktail
+  class StringifiesMethodName
+    def stringify(call)
+      [
+        call.original_type.name,
+        call.singleton ? "." : "#",
+        call.method
+      ].join
+    end
+  end
+end

data/lib/mocktail/simulates_argument_error.rb

@@ -1,7 +1,7 @@
 require_relative "simulates_argument_error/transforms_params"
 require_relative "simulates_argument_error/reconciles_args_with_params"
 require_relative "simulates_argument_error/recreates_message"
-require_relative "simulates_argument_error/cleans_backtrace"
+require_relative "share/cleans_backtrace"
 require_relative "share/stringifies_call"
 
 module Mocktail

data/lib/mocktail/value/cabinet.rb

@@ -3,18 +3,20 @@
 module Mocktail
   class Cabinet
     attr_writer :demonstration_in_progress
-    attr_reader :calls, :stubbings
+    attr_reader :calls, :stubbings, :unsatisfying_calls
 
     def initialize
       @doubles = []
       @calls = []
       @stubbings = []
+      @unsatisfying_calls = []
       @demonstration_in_progress = false
     end
 
     def reset!
       @calls = []
       @stubbings = []
+      @unsatisfying_calls = []
       # Could cause an exception or prevent pollution—you decide!
       @demonstration_in_progress = false
       # note we don't reset doubles as they don't carry any
@@ -34,8 +36,24 @@ module Mocktail
       @stubbings << stubbing
     end
 
+    def store_unsatisfying_call(unsatisfying_call)
+      @unsatisfying_calls << unsatisfying_call
+    end
+
     def demonstration_in_progress?
       @demonstration_in_progress
     end
+
+    def double_for_instance(thing)
+      @doubles.find { |double| double.dry_instance == thing }
+    end
+
+    def stubbings_for_double(double)
+      @stubbings.select { |stubbing| stubbing.recording.double == double.dry_instance }
+    end
+
+    def calls_for_double(double)
+      @calls.select { |call| call.double == double.dry_instance }
+    end
   end
 end

data/lib/mocktail/value/double.rb

@@ -1,11 +1,10 @@
 module Mocktail
-  class Double
-    attr_reader :original_type, :dry_type, :dry_instance
-
-    def initialize(original_type:, dry_type:, dry_instance:)
-      @original_type = original_type
-      @dry_type = dry_type
-      @dry_instance = dry_instance
-    end
+  class Double < Struct.new(
+    :original_type,
+    :dry_type,
+    :dry_instance,
+    :dry_methods,
+    keyword_init: true
+  )
   end
 end

data/lib/mocktail/value/double_data.rb

@@ -0,0 +1,10 @@
+module Mocktail
+  class DoubleData < Struct.new(
+    :type,
+    :double,
+    :calls,
+    :stubbings,
+    keyword_init: true
+  )
+  end
+end

data/lib/mocktail/value/explanation.rb

@@ -0,0 +1,26 @@
+module Mocktail
+  class Explanation
+    attr_reader :reference, :message
+
+    def initialize(reference, message)
+      @reference = reference
+      @message = message
+    end
+
+    def type
+      self.class
+    end
+  end
+
+  class NoExplanation < Explanation
+  end
+
+  class UnsatisfyingCallExplanation < Explanation
+  end
+
+  class DoubleExplanation < Explanation
+  end
+
+  class ReplacedTypeExplanation < Explanation
+  end
+end

data/lib/mocktail/value/top_shelf.rb

@@ -1,61 +1,60 @@
-# The top shelf stores all cross-thread & thread-aware state, so anything that
-# goes here is on its own when it comes to ensuring thread safety.
 module Mocktail
   class TopShelf
     def self.instance
-      @self ||= new
+      Thread.current[:mocktail_top_shelf] ||= new
     end
 
+    @@type_replacements = {}
+    @@type_replacements_mutex = Mutex.new
+
     def initialize
-      @type_replacements = {}
-      @new_registrations = {}
-      @of_next_registrations = {}
-      @singleton_method_registrations = {}
+      @new_registrations = []
+      @of_next_registrations = []
+      @singleton_method_registrations = []
     end
 
     def type_replacement_for(type)
-      @type_replacements[type] ||= TypeReplacement.new(type: type)
+      @@type_replacements_mutex.synchronize {
+        @@type_replacements[type] ||= TypeReplacement.new(type: type)
+      }
+    end
+
+    def type_replacement_if_exists_for(type)
+      @@type_replacements_mutex.synchronize {
+        @@type_replacements[type]
+      }
     end
 
     def reset_current_thread!
-      @new_registrations[Thread.current] = []
-      @of_next_registrations[Thread.current] = []
-      @singleton_method_registrations[Thread.current] = []
+      Thread.current[:mocktail_top_shelf] = self.class.new
     end
 
     def register_new_replacement!(type)
-      @new_registrations[Thread.current] ||= []
-      @new_registrations[Thread.current] |= [type]
+      @new_registrations |= [type]
     end
 
     def new_replaced?(type)
-      @new_registrations[Thread.current] ||= []
-      @new_registrations[Thread.current].include?(type)
+      @new_registrations.include?(type)
     end
 
     def register_of_next_replacement!(type)
-      @of_next_registrations[Thread.current] ||= []
-      @of_next_registrations[Thread.current] |= [type]
+      @of_next_registrations |= [type]
     end
 
     def of_next_registered?(type)
-      @of_next_registrations[Thread.current] ||= []
-      @of_next_registrations[Thread.current].include?(type)
+      @of_next_registrations.include?(type)
     end
 
     def unregister_of_next_replacement!(type)
-      @of_next_registrations[Thread.current] ||= []
-      @of_next_registrations[Thread.current] -= [type]
+      @of_next_registrations -= [type]
     end
 
     def register_singleton_method_replacement!(type)
-      @singleton_method_registrations[Thread.current] ||= []
-      @singleton_method_registrations[Thread.current] |= [type]
+      @singleton_method_registrations |= [type]
     end
 
     def singleton_methods_replaced?(type)
-      @singleton_method_registrations[Thread.current] ||= []
-      @singleton_method_registrations[Thread.current].include?(type)
+      @singleton_method_registrations.include?(type)
     end
   end
 end

data/lib/mocktail/value/type_replacement_data.rb

@@ -0,0 +1,13 @@
+module Mocktail
+  class TypeReplacementData < Struct.new(
+    :type,
+    :replaced_method_names,
+    :calls,
+    :stubbings,
+    keyword_init: true
+  )
+    def double
+      type
+    end
+  end
+end

data/lib/mocktail/value/unsatisfying_call.rb

@@ -0,0 +1,9 @@
+module Mocktail
+  class UnsatisfyingCall < Struct.new(
+    :call,
+    :other_stubbings,
+    :backtrace,
+    keyword_init: true
+  )
+  end
+end

data/lib/mocktail/value.rb

@@ -2,8 +2,12 @@ require_relative "value/cabinet"
 require_relative "value/call"
 require_relative "value/demo_config"
 require_relative "value/double"
+require_relative "value/double_data"
+require_relative "value/explanation"
 require_relative "value/matcher_registry"
 require_relative "value/signature"
 require_relative "value/stubbing"
 require_relative "value/top_shelf"
 require_relative "value/type_replacement"
+require_relative "value/type_replacement_data"
+require_relative "value/unsatisfying_call"

data/lib/mocktail/verifies_call/raises_verification_error.rb

@@ -1,16 +1,18 @@
 require_relative "raises_verification_error/gathers_calls_of_method"
+require_relative "../share/stringifies_method_name"
 require_relative "../share/stringifies_call"
 
 module Mocktail
   class RaisesVerificationError
     def initialize
       @gathers_calls_of_method = GathersCallsOfMethod.new
+      @stringifies_method_name = StringifiesMethodName.new
       @stringifies_call = StringifiesCall.new
     end
 
     def raise(recording, verifiable_calls, demo_config)
       Kernel.raise VerificationError.new <<~MSG
-        Expected mocktail of #{recording.original_type.name}##{recording.method} to be called like:
+        Expected mocktail of `#{@stringifies_method_name.stringify(recording)}' to be called like:
 
           #{@stringifies_call.stringify(recording)}#{[
             (" [#{demo_config.times} #{pl("time", demo_config.times)}]" unless demo_config.times.nil?),

data/lib/mocktail/version.rb

@@ -1,3 +1,3 @@
 module Mocktail
-  VERSION = "0.0.3"
+  VERSION = "1.0.0"
 end

data/lib/mocktail.rb

@@ -1,5 +1,7 @@
 require_relative "mocktail/dsl"
 require_relative "mocktail/errors"
+require_relative "mocktail/explains_thing"
+require_relative "mocktail/explains_nils"
 require_relative "mocktail/handles_dry_call"
 require_relative "mocktail/handles_dry_new_call"
 require_relative "mocktail/imitates_type"
@@ -56,7 +58,17 @@ module Mocktail
     ResetsState.new.reset
   end
 
+  def self.explain(thing)
+    ExplainsThing.new.explain(thing)
+  end
+
+  def self.explain_nils
+    ExplainsNils.new.explain
+  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!
   def self.cabinet
     Thread.current[:mocktail_store] ||= Cabinet.new
   end

data/mocktail.gemspec

@@ -6,7 +6,7 @@ Gem::Specification.new do |spec|
   spec.authors = ["Justin Searls"]
   spec.email = ["searls@gmail.com"]
 
-  spec.summary = "your objects, less potency"
+  spec.summary = "Take your objects, and make them a double"
   spec.homepage = "https://github.com/testdouble/mocktail"
   spec.required_ruby_version = Gem::Requirement.new(">= 3.0.0")
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mocktail
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 1.0.0
 platform: ruby
 authors:
 - Justin Searls
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-10-04 00:00:00.000000000 Z
+date: 2021-12-20 00:00:00.000000000 Z
 dependencies: []
 description:
 email:
@@ -31,8 +31,11 @@ files:
 - lib/mocktail.rb
 - lib/mocktail/dsl.rb
 - lib/mocktail/errors.rb
+- lib/mocktail/explains_nils.rb
+- lib/mocktail/explains_thing.rb
 - lib/mocktail/handles_dry_call.rb
 - lib/mocktail/handles_dry_call/fulfills_stubbing.rb
+- lib/mocktail/handles_dry_call/fulfills_stubbing/describes_unsatisfied_stubbing.rb
 - lib/mocktail/handles_dry_call/fulfills_stubbing/finds_satisfaction.rb
 - lib/mocktail/handles_dry_call/logs_call.rb
 - lib/mocktail/handles_dry_call/validates_arguments.rb
@@ -41,6 +44,7 @@ files:
 - lib/mocktail/imitates_type/ensures_imitation_support.rb
 - lib/mocktail/imitates_type/makes_double.rb
 - lib/mocktail/imitates_type/makes_double/declares_dry_class.rb
+- lib/mocktail/imitates_type/makes_double/gathers_fakeable_instance_methods.rb
 - lib/mocktail/initializes_mocktail.rb
 - lib/mocktail/matcher_presentation.rb
 - lib/mocktail/matchers.rb
@@ -62,11 +66,12 @@ files:
 - lib/mocktail/replaces_type/redefines_new.rb
 - lib/mocktail/replaces_type/redefines_singleton_methods.rb
 - lib/mocktail/resets_state.rb
+- lib/mocktail/share/cleans_backtrace.rb
 - lib/mocktail/share/creates_identifier.rb
 - lib/mocktail/share/determines_matching_calls.rb
 - lib/mocktail/share/stringifies_call.rb
+- lib/mocktail/share/stringifies_method_name.rb
 - lib/mocktail/simulates_argument_error.rb
-- lib/mocktail/simulates_argument_error/cleans_backtrace.rb
 - lib/mocktail/simulates_argument_error/reconciles_args_with_params.rb
 - lib/mocktail/simulates_argument_error/recreates_message.rb
 - lib/mocktail/simulates_argument_error/transforms_params.rb
@@ -75,11 +80,15 @@ files:
 - lib/mocktail/value/call.rb
 - lib/mocktail/value/demo_config.rb
 - lib/mocktail/value/double.rb
+- lib/mocktail/value/double_data.rb
+- lib/mocktail/value/explanation.rb
 - lib/mocktail/value/matcher_registry.rb
 - lib/mocktail/value/signature.rb
 - lib/mocktail/value/stubbing.rb
 - lib/mocktail/value/top_shelf.rb
 - lib/mocktail/value/type_replacement.rb
+- lib/mocktail/value/type_replacement_data.rb
+- lib/mocktail/value/unsatisfying_call.rb
 - lib/mocktail/verifies_call.rb
 - lib/mocktail/verifies_call/finds_verifiable_calls.rb
 - lib/mocktail/verifies_call/raises_verification_error.rb
@@ -107,8 +116,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.15
+rubygems_version: 3.2.22
 signing_key:
 specification_version: 4
-summary: your objects, less potency
+summary: Take your objects, and make them a double
 test_files: []