mocktail 0.0.1 → 0.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8792bd9f9b3ccc36c01046557e63c390eccd97c53e25b54da6c54ca2690f839d
-  data.tar.gz: 13c9444150fd0bd4098660f5960d268d37d67c8a27058834259dd2f1717933b6
+  metadata.gz: 8e043c9a28687502f8933593acca4a4860a11088b51a7f31ea726e2b80b8eb92
+  data.tar.gz: d406fcd7610fb29f2a6c964b777f0e77c770d273c87216872d2feeb9bcda39eb
 SHA512:
-  metadata.gz: 43a3c90e6edcbc9f04f2d4eb26e930a43dd8ac685f50d98d95f2c6128edd873776d02123258aa5e12766a1940e77e1704a252a18e5541bd52e8be3e5c6605d91
-  data.tar.gz: 6c872542db03bc16e548c5d1f48b18229638f2553612c4e9897443e9f43d01d6056428eca76da9814a4c82823d658ce434ec88316d579b6aab7741d8dcbeff1c
+  metadata.gz: '09b7f3e7931069bfd62993b8e91d08a92f6e11b51c5b6d21698a0f1773a72786d55d78db1c649aa9a1e935dc72e81042dd2127f15a09e0296c00dbdcb1937423'
+  data.tar.gz: d0ffd4f421f76afab828a426c9246a31794341fc7c5a8af862ab8f726eafad1324b3e2caa9ad2dae6ed79a34066fcd5e27be53e6dd7c70544bb3d75c900d725f

data/.github/workflows/main.yml

@@ -4,15 +4,21 @@ on: [push,pull_request]
 
 jobs:
   build:
-    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        os: [ ubuntu-latest ]
+        ruby-version: [3.0.1]
+
+    runs-on: ${{ matrix.os }}
+
     steps:
     - uses: actions/checkout@v2
     - name: Set up Ruby
       uses: ruby/setup-ruby@v1
       with:
-        ruby-version: 3.0.1
+        ruby-version: ${{ matrix.ruby-version }}
     - name: Run the default task
       run: |
-        gem install bundler -v 2.2.15
+        gem install bundler
         bundle install
         bundle exec rake

data/CHANGELOG.md

@@ -1,3 +1,41 @@
+# 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
+  ruby 3.0), the entire approach to using `define_method` with `*args` and
+  `**kwargs` splats only further confuses the [arg
+  splitting](https://www.ruby-lang.org/en/news/2019/12/12/separation-of-positional-and-keyword-arguments-in-ruby-3-0/)
+  behavior in Ruby 2.x. So in the event that someone calls a method with an
+  ambiguous hash-as-last arg (either in a mock demonstration or call), it will
+  be functionally impossible to either (a) validate the args against the
+  parameters or (b) compare two calls as being a match for one another. These
+  problems could be overcome (by using `eval` instead of `define_method` for
+  mocked methods and by expanding the call-matching logic dramatically), but
+  who's got the time. Upgrade to 3.0!
+
 # 0.0.1
 
 Initial release

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    mocktail (0.0.1)
+    mocktail (0.0.5)
 
 GEM
   remote: https://rubygems.org/
@@ -49,6 +49,7 @@ GEM
 
 PLATFORMS
   arm64-darwin-20
+  ruby
 
 DEPENDENCIES
   minitest

data/README.md

@@ -6,73 +6,85 @@ width="90%"/>
 
 Mocktail is a [test
 double](https://github.com/testdouble/contributing-tests/wiki/Test-Double)
-library for Ruby. It offers a simple API and robust feature-set.
+library for Ruby that provides a terse and robust API for creating mocks,
+getting them in the hands of the code you're testing, stub & verify behavior,
+and even safely override class methods.
 
-## First, an aperitif
+## An aperitif
 
 Before getting into the details, let's demonstrate what Mocktail's API looks
-like. Suppose you have a class `Negroni`:
+like. Suppose you want to test a `Bartender` class:
 
 ```ruby
-class Negroni
-  def self.ingredients
-    [:gin, :campari, :sweet_vermouth]
-  end
-
-  def shake!(shaker)
-    shaker.mix(self.class.ingredients)
+class Bartender
+  def initialize
+    @shaker = Shaker.new
+    @glass = Glass.new
+    @bar = Bar.new
   end
 
-  def sip(amount)
-    raise "unimplemented"
+  def make_drink(name, customer:)
+    if name == :negroni
+      drink = @shaker.combine(:gin, :campari, :sweet_vermouth)
+      @glass.pour!(drink)
+      @bar.pass(@glass, to: customer)
+    end
   end
 end
 ```
 
-1. Create a mocked instance: `negroni = Mocktail.of(Negroni)`
-2. Stub a response with `stubs { negroni.sip(4) }.with { :ahh }`
-    * Calling `negroni.sip(4)` will subsequently return `:ahh`
-    * Another example: `stubs { |m| negroni.sip(m.numeric) }.with { :nice }`
-3. Verify a call with `verify { negroni.shake!(:some_shaker) }`
-    * `verify` will raise an error unless `negroni.shake!(:some_shaker)` has
-      been called
-    * Another example: `verify { |m| negroni.shake!(m.that { |arg|
-      arg.respond_to?(:mix) }) }`
-4. Deliver a mock to your code under test with `negroni =
-Mocktail.of_next(Negroni)`
-    * `of_next` will return a fake `Negroni`
-    * The next call to `Negroni.new` will return _exactly the same_ fake
-      instance, allowing the code being tested to seamlessly instantiate and
-      interact with it
-    * This means no dependency injection is necessary, nor is a sweeping
-      override like
-      [any_instance](https://relishapp.com/rspec/rspec-mocks/docs/working-with-legacy-code/any-instance)
-    * `Negroni.new` will be unaffected on other threads and will continue
-      behaving like normal as soon as the next `new` call
-
-Mocktail can do a whole lot more than this, and was also designed with
-descriptive error messages and common edge cases in mind:
-
-* Entire classes and modules can be replaced with `Mocktail.replace(type)` while
-  preserving thread safety
-* Arity of arguments and keyword arguments is enforced on faked methods to
-  prevent isolated unit tests from continuing to pass after an API contract
-  changes
-* For mocked methods that take a block, `stubs` & `verify` can inspect and
-  invoke the passed block to determine whether the call satisfies their
-  conditions
-* Dynamic stubbings that return a value based on how the mocked method was
-  called
-* Advanced stubbing and verification options like specifying the number of
-  `times` a stub can be satisfied or a call should be verified, allowing tests
-  to forego specifying arguments and blocks, and temporarily disabling arity
-  validation
-* Built-in matchers as well as custom matcher support
-* Argument captors for complex, multi-step call verifications
-
-## Getting started
-
-### Install
+You could write an isolated unit test with Mocktail like this:
+
+```ruby
+shaker = Mocktail.of_next(Shaker)
+glass = Mocktail.of_next(Glass)
+bar = Mocktail.of_next(Bar)
+subject = Bartender.new
+stubs { shaker.combine(:gin, :campari, :sweet_vermouth) }.with { :a_drink }
+stubs { bar.pass(glass, to: "Eileen") }.with { "🎉" }
+
+result = subject.make_drink(:negroni, customer: "Eileen")
+
+assert_equal "🎉", result
+# Oh yeah, and make sure the drink got poured! Silly side effects!
+verify { glass.pour!(:a_drink) }
+```
+
+## 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) 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, as well as advanced configuration options for stubbing &
+  verification
+
+## Ready to order?
+
+### Install the gem
 
 The main ingredient to add to your Gemfile:
 
@@ -80,7 +92,7 @@ The main ingredient to add to your Gemfile:
 gem "mocktail", group: :test
 ```
 
-### Add the DSL
+### Sprinkle in the DSL
 
 Then, in each of your tests or in a test helper, you'll probably want to include
 Mocktail's DSL. (This is optional, however, as every method in the DSL is also
@@ -102,11 +114,10 @@ RSpec.configure do |config|
 end
 ```
 
-### Clean up after each test
+### Clean up when you're done
 
-When making so many concoctions, it's important to keep a clean bar! To reset
-Mocktail's internal state between tests and avoid test pollution, you should
-also call `Mocktail.reset` after each test:
+To reset Mocktail's internal state between tests and avoid test pollution, you
+should also call `Mocktail.reset` after each test:
 
 In Minitest:
 
@@ -131,8 +142,8 @@ end
 
 ## API
 
-The public API is a pretty quick read of the [top-level module's
-source](lib/mocktail.rb). Here's a longer menu to explain what goes into each
+The entire public API is listed in the [top-level module's
+source](lib/mocktail.rb). Below is a longer menu to explain what goes into each
 feature.
 
 ### Mocktail.of
@@ -284,7 +295,7 @@ user_repository.find(1) # => :not_found
 `ignore_extra_args` will allow a demonstration to be considered satisfied even
 if it fails to specify arguments and keyword arguments made by the actual call:
 
-```
+```ruby
 stubs { user_repository.find(4) }.with { :a_person }
 user_repository.find(4, debug: true) # => nil
 
@@ -490,7 +501,7 @@ verify { big_api.send(payload_captor.capture) } # => nil!
 The `verify` above will pass because _a_ call did happen, but we haven't
 asserted anything beyond that yet. What really happened is that
 `payload_captor.capture` actually returned a matcher that will return true for
-any argument _while also sneakily storing a copy of the argument value_. 
+any argument _while also sneakily storing a copy of the argument value_.
 
 That's why we instantiated `payload_captor` with `Mocktail.captor` outside the
 demonstration block, so we can inspect its `value` after the `verify` call:
@@ -513,6 +524,24 @@ When you call `Mocktail.replace(type)`, all of the singleton methods on the
 provided type are replaced with fake methods available for stubbing and
 verification. It's really that simple.
 
+For example, if our `Bartender` class has a class method:
+
+```ruby
+class Bartender
+  def self.cliche_greeting
+    ["It's 5 o'clock somewhere!", "Norm!"].sample
+  end
+end
+```
+
+We can replace the behavior of the overall class, and then stub how we'd like it
+to respond, in our test:
+
+```ruby
+Mocktail.replace(Bartender)
+stubs { Bartender.cliche_greeting }.with { "Norm!" }
+```
+
 [**Obligatory warning:** Mocktail does its best to ensure that other threads
 won't be affected when you replace the singleton methods on a type, but your
 mileage may very! Singleton methods are global and code that introspects or
@@ -521,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,

data/bin/console

@@ -29,7 +29,53 @@ class Auditor
   def record!(message, user:, action: nil); end
 end
 
+class Shaker
+  def combine(*args); end
+end
+class Glass
+  def pour!(drink); end
+end
+class Bar
+  def pass(glass, to:)
+  end
+end
+
+class Bartender
+  def initialize
+    @shaker = Shaker.new
+    @glass = Glass.new
+    @bar = Bar.new
+  end
+
+  def make_drink(name, customer:)
+    if name == :negroni
+      drink = @shaker.combine(:gin, :campari, :sweet_vermouth)
+      @glass.pour!(drink)
+      @bar.pass(@glass, to: customer)
+    end
+  end
+end
+
+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)
 
-# (If you use this, don't forget to add pry to your Gemfile!)
 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