mocktail 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 05ec28e8027b6d73ee5b3f513ce4d5e23a60ea0266643e344e20e8f995410ce2
-  data.tar.gz: 7baf1cff682de031f3f25cebad265e59e598c4f4103968ea2dda61b6c7605c9c
+  metadata.gz: 6a9c74cd3ff5167b99c38892ee6411a1ac3f1379158c062076bfbe6d8479c7b7
+  data.tar.gz: 81dd2b80a78c162a9c4030fa8bc9be42741c3a8c053fa33c319dc13c404234a8
 SHA512:
-  metadata.gz: 4c5eef4fe5c68abd7d1e506bc59db58daa931fb484118e0ee4d6d286944d2834d0bb3107183102ac65110e12f32992b73fadbfcc26ed750bff060535e4eba5a2
-  data.tar.gz: cff11562ac6bc79475719f17f912ffc2fe8af6315ab90dbdc838143c237542ad788cba2d6c05ee15417799b2f597634244edf3c9f50dac5121adbac551602bdb
+  metadata.gz: bd1fbc482135e89dea00de9249d63b5e851d64ecb2f4afc898b4bb77abf5afc96303cfed6b59665d0e51ab4b2c8dd4c438dc2a7ab93d1c69e1d12d723797cf9a
+  data.tar.gz: 3af137dd6d1488b1ef41ac0b47178a224e160f11dce0ed0cbeb24418ae4a33c86a6e4fa8e3cabb20c8421c8ac1ac8c166045051d996d4aa1dc709e4fcc97ec3a

data/.github/workflows/main.yml

@@ -7,7 +7,7 @@ jobs:
     strategy:
       matrix:
         os: [ ubuntu-latest ]
-        ruby-version: [3.0.1]
+        ruby-version: ['3.0', '3.1']
 
     runs-on: ${{ matrix.os }}
 

data/CHANGELOG.md

@@ -1,3 +1,9 @@
+# 1.1.0
+
+* Feature: add support for passing methods to `Mocktail.explain()`
+* Fix 3.1 support by bypassing highlight_error for custom NoMethodError objects
+  raised by Mocktail [error_highlight#20](https://github.com/ruby/error_highlight/issues/20)
+
 # 1.0.0
 
 * First breaking change! 🎉

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    mocktail (1.0.0)
+    mocktail (1.1.0)
 
 GEM
   remote: https://rubygems.org/
@@ -12,27 +12,27 @@ GEM
     method_source (1.0.0)
     minitest (5.15.0)
     parallel (1.21.0)
-    parser (3.0.3.2)
+    parser (3.1.0.0)
       ast (~> 2.4.1)
     pry (0.14.1)
       coderay (~> 1.1)
       method_source (~> 1.0)
-    rainbow (3.0.0)
+    rainbow (3.1.1)
     rake (13.0.6)
     regexp_parser (2.2.0)
     rexml (3.2.5)
-    rubocop (1.23.0)
+    rubocop (1.25.0)
       parallel (~> 1.10)
-      parser (>= 3.0.0.0)
+      parser (>= 3.1.0.0)
       rainbow (>= 2.2.2, < 4.0)
       regexp_parser (>= 1.8, < 3.0)
       rexml
-      rubocop-ast (>= 1.12.0, < 2.0)
+      rubocop-ast (>= 1.15.1, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 1.4.0, < 3.0)
-    rubocop-ast (1.15.0)
+    rubocop-ast (1.15.1)
       parser (>= 3.0.1.1)
-    rubocop-performance (1.12.0)
+    rubocop-performance (1.13.2)
       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.5.0)
-      rubocop (= 1.23.0)
-      rubocop-performance (= 1.12.0)
+    standard (1.7.0)
+      rubocop (= 1.25.0)
+      rubocop-performance (= 1.13.2)
     unicode-display_width (2.1.0)
 
 PLATFORMS
@@ -60,4 +60,4 @@ DEPENDENCIES
   standard
 
 BUNDLED WITH
-   2.2.30
+   2.3.6

data/README.md

@@ -553,14 +553,160 @@ 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.
+which way, so Mocktail tries to make it a little easier on you. In addition to
+returning useful messages throughout the API, the gem also includes an
+introspection method `Mocktail.explain(thing)`, which returns a human-readable
+`message` and a `reference` object with useful attributes (that vary depending
+on the type of fake `thing` you pass in. Below are some things `explain()` can
+do.
+
+#### 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.
+
+Suppose these interactions have occurred:
+
+```ruby
+ice_tray = Mocktail.of(IceTray)
+
+Mocktail.stubs { ice_tray.fill(:tap_water, 30) }.with { :some_ice }
+
+ice_tray.fill(:tap_water, 50)
+```
+
+You can interrogate what's going on with the fake instance by passing it to
+`explain`:
+
+```ruby
+explanation = Mocktail.explain(ice_tray)
+
+explanation.reference.type      #=> IceTray
+explanation.reference.double    #=> The ice_tray instance
+explanation.reference.calls     #=> details on each invocation of each method
+explanation.reference.stubbings #=> all stubbings configured for each method
+```
+
+Calling `explanation.message` will return:
+
+```
+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)
+
+explanation = Mocktail.explain(Shop)
+
+explanation.reference.type      #=> Shop
+explanation.reference.replaced_method_names #=> [:close!, :open!]
+explanation.reference.calls     #=> details on each invocation of each method
+explanation.reference.stubbings #=> all stubbings configured for each method
+```
+
+And `explanation.message` will return:
+
+```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)
+
+  close!(42)
+
+`Shop.open!' stubbings:
+
+  open!(numeric)
+
+  open!(numeric)
+
+`Shop.open!' calls:
+
+  open!(42)
+
+  open!(42)
+```
+
+#### Methods on faked instances and replaced types
+
+In addition to passing the test double, you can also pass a reference to any
+fake method created by Mocktail to `Mocktail.explain`:
+
+```ruby
+ice_tray = Mocktail.of(IceTray)
+
+ice_tray.fill(:chilled, 50)
+
+explanation = Mocktail.explain(ice_tray.method(:fill))
+
+explanation.reference.receiver  #=> a reference to the `ice_tray` instance
+explanation.reference.calls     #=> details on each invocation of the method
+explanation.reference.stubbings #=> all stubbings configured for the method
+```
+
+The above may be handy in cases where you want to assert the number of calls of
+a method outside the `Mocktail.verify` API:
+
+```ruby
+assert_equal 1, explanation.reference.calls.size
+```
+
+The explanation will also contain a `message` like this:
+
+```
+`IceTray#fill' has no stubbings.
+
+`IceTray#fill' calls:
+
+  fill(:chilled, 50)
+```
+
+Replaced singleton methods can also be passed to `explain()`, so something like
+`Mocktail.explain(Shop.method(:open!))` from the earlier example would also work
+(with `Shop` being the `receiver` on the explanation's `reference`).
 
 #### 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:
+There's no API for this one, but Mocktail also offers explanations for methods
+that don't exist yet. You'll see this error message whenever you try to call a
+method that doesn't exist on a test double. The message is designed to
+facilitate "paint-by-numbers" TDD, by including a sample definition of the
+method you had attempted to call that can be copy-pasted into a source listing:
 
 ```ruby
 class IceTray
@@ -589,7 +735,7 @@ class IceTray
 end
 ```
 
-### Unexpected nils with Mocktail.explain_nils
+### Mocktail.explain_nils
 
 Is a faked method returning `nil` and you don't understand why?
 
@@ -656,75 +802,6 @@ 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,

data/lib/mocktail/explains_thing.rb

@@ -13,6 +13,8 @@ module Mocktail
         double_explanation(double)
       elsif (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
@@ -20,13 +22,37 @@ module Mocktail
 
     private
 
-    def double_explanation(double)
-      double_data = DoubleData.new(
+    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
+
+    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
+
+    def double_explanation(double)
+      double_data = data_for_double(double)
 
       DoubleExplanation.new(double_data, <<~MSG)
         This is a fake `#{double.original_type.name}' instance.
@@ -38,8 +64,8 @@ module Mocktail
       MSG
     end
 
-    def replaced_type_explanation(type_replacement)
-      type_replacement_data = TypeReplacementData.new(
+    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|
@@ -49,6 +75,10 @@ module Mocktail
           stubbing.recording.double == type_replacement.type
         }
       )
+    end
+
+    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 singleton methods faked.

data/lib/mocktail/raises_neato_no_method_error.rb

@@ -11,7 +11,7 @@ module Mocktail
     end
 
     def call(call)
-      raise NoMethodError.new <<~MSG
+      raise NoMethodError, <<~MSG, caller[1..]
         No method `#{@stringifies_method_name.stringify(call)}' exists for call:
 
           #{@stringifies_call.stringify(call, anonymous_blocks: true, always_parens: true)}

data/lib/mocktail/value/explanation.rb

@@ -23,4 +23,7 @@ module Mocktail
 
   class ReplacedTypeExplanation < Explanation
   end
+
+  class FakeMethodExplanation < Explanation
+  end
 end

data/lib/mocktail/value/fake_method_data.rb

@@ -0,0 +1,9 @@
+module Mocktail
+  class FakeMethodData < Struct.new(
+    :receiver,
+    :calls,
+    :stubbings,
+    keyword_init: true
+  )
+  end
+end

data/lib/mocktail/value.rb

@@ -4,6 +4,7 @@ require_relative "value/demo_config"
 require_relative "value/double"
 require_relative "value/double_data"
 require_relative "value/explanation"
+require_relative "value/fake_method_data"
 require_relative "value/matcher_registry"
 require_relative "value/signature"
 require_relative "value/stubbing"

data/lib/mocktail/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mocktail
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Justin Searls
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-12-20 00:00:00.000000000 Z
+date: 2022-01-27 00:00:00.000000000 Z
 dependencies: []
 description:
 email:
@@ -82,6 +82,7 @@ files:
 - lib/mocktail/value/double.rb
 - lib/mocktail/value/double_data.rb
 - lib/mocktail/value/explanation.rb
+- lib/mocktail/value/fake_method_data.rb
 - lib/mocktail/value/matcher_registry.rb
 - lib/mocktail/value/signature.rb
 - lib/mocktail/value/stubbing.rb
@@ -116,7 +117,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.22
+rubygems_version: 3.3.6
 signing_key:
 specification_version: 4
 summary: Take your objects, and make them a double