mocktail 2.0.0 → 3.0.0

data/docs/tdd/poro/dependency_inception.md

@@ -0,0 +1,136 @@
+# Dependency _inception_ by magically instantiating mocks with `Mocktail.of_next(SomeClass)`
+
+Perhaps your typical [subject](/docs/support/glossary.md#subject-under-test)
+instantiates its own [dependencies](/docs/support/glossary.md#dependency):
+
+```ruby
+class ThingHaver
+  def initialize
+    @thing_1 = Thing1.new
+    @thing_2 = Thing2.new
+  end
+end
+```
+
+Or, for the sake of testability, follows a
+dependency injection pattern like the following:
+
+```ruby
+class ThingHaver
+  def initialize(thing_1 = Thing1.new, thing_2 = Thing2.new)
+    @thing_1 = thing_1
+    @thing_2 = thing_2
+  end
+end
+```
+
+Where, in the universe imagined above, production code always instantiates
+`ThingHaver` with no arguments passed to `new` (meaning that `ThingHaver` is
+invoking `Thing1.new` and `Thing2.new` itself via default argument assignment),
+but unit test code  creates mocks of `Thing1` and `Thing2` and passes them in.
+This is a clever pattern, but if our code coverage tools were stricter, we'd see
+this actually results in unit tests that fail to cover the execution of each
+default assignment, which can lead to surprising bugs if you ever stray from
+plain, no-arg constructors.
+
+If either of these cases look familiar, then you may find a lot to like with the
+[Mocktail.of_next](/docs/support/api.md#mocktailof_next) convenience function.
+
+Here's the first example and a test listing:
+
+```ruby
+class ThingHaver
+  def initialize
+    @thing_1 = Thing1.new
+    @thing_2 = Thing2.new
+  end
+
+  def have_things
+    [@thing_1, @thing_2].map(&:name)
+  end
+end
+
+# Elsewhere, in a test:
+thing_1 = Mocktail.of_next(Thing1)
+thing_2 = Mocktail.of_next(Thing2)
+subject = ThingHaver.new
+stubs { thing_1.name }.with { :alpha }
+stubs { thing_2.name }.with { :omega }
+
+result = subject.have_things
+
+assert_equal [:alpha, :omega], result
+```
+
+In the above setup, the value of the `subject`'s `@thing_1` instance variable
+will reference the same mock instance as the test's `thing_1` local variable.
+The same goes for the subject's `@thing_2` and test's `thing_2`.
+
+Perfectly testable. No goofy dependency injection mechanics necessary.
+
+Here's what is going on under the hood:
+
+1. When passed `Thing1`, `Mocktail.of_next` does two things:
+  a. Makes a fake `Thing1` instance and returns it
+  b. Overwrites the `Thing1.new` method with an alternate implementation that
+     returns the same fake `Thing1` instance
+2. The next time `Thing1.new` is called and the fake `Thing1` instance is returned,
+Mocktail removes its fake `Thing1.new` method and restores the original, meaning
+subsequent calls to `Thing1.new` will once again return real `Thing1` instances
+
+Sneaky!
+
+## Handling dependencies instantiated more than once
+
+Wait, there's more! In the rare event your subject needs multiple instances of
+the same dependency at a time (suppose one for each element in an array), you
+can generate more than one with [Mocktail.of_next_with_count(type, count)](/docs/support/api.md#mocktailof_next_with_count).
+
+Suppose we rewrite the above example with a single `Thing` class instead of
+`Thing1` and `Thing2`. We could use `of_next_with_count` to create both the
+fakes in one go, without losing track of the references:
+
+```ruby
+class ThingHaver
+  def initialize
+    @thing_1 = Thing.new
+    @thing_2 = Thing.new
+  end
+
+  def have_things
+    [@thing_1, @thing_2].map(&:name)
+  end
+end
+
+# Elsewhere, in a test:
+thing_1, thing_2 = Mocktail.of_next_with_count(Thing, 2)
+subject = ThingHaver.new
+stubs { thing_1.name }.with { :alpha }
+stubs { thing_2.name }.with { :omega }
+
+result = subject.have_things
+
+assert_equal [:alpha, :omega], result
+```
+
+## This doesn't work for modules
+
+If you want Mocktail to create a mock instance from a reference to a module,
+however, `Mocktail.of_next` won't work—there's no `new` method for it to
+override or for the subject to reference! The best way to do it is either to
+create a test-scoped class that includes the module yourself first (and passing
+that class to the subject somehow so it can call `new` on it) or to give up on
+trying to use `of_next` in favor of
+[Mocktail.of](/docs/support/api.md#mocktailof), which can accept a module and
+return a mock instance.
+
+## Behold your awesome power!
+
+If your coding style supports it, maximizing `Mocktail.of_next` usage in your
+test setup is a great way to mop up redundant test setup boilerplate while
+potentially eliminating uncovered dependency instantiations from your production
+code.
+
+**Keep the magic flowing by [stubbing and verifying some interactions](../../stubbing_and_verifying.md).**
+
+**Go back and learn of less magical ways to [create mocks](../../tdd.md).**

data/docs/tdd/poro/dependency_injection.md

@@ -0,0 +1,82 @@
+# Dependency injection by manually instantiating mocks with `Mocktail.of(SomeClassOrModule)`
+
+The method we use to instantiate instances of mocks for a given class or module
+is [Mocktail.of](/docs/support/api.md#mocktailof).
+
+Assuming you're passing a [dependency](/docs/support/glossary.md#dependency) to
+your [subject's](/docs/support/glossary.md#subject-under-test) initializer,
+here's an example of how you might do that with `Mocktail.of()`.
+
+Given the following subject:
+
+```ruby
+class CashRegister
+  def initialize(payment_processor)
+    @payment_processor = payment_processor
+  end
+
+  def boot!
+    @payment_processor.establish_connection
+  end
+end
+```
+
+And this dependency:
+
+```ruby
+class PaymentProcessor
+  def establish_connection
+    # ⚡️ NETWORKING ⚡️
+  end
+end
+```
+
+You could write a little test with Mocktail like this, using
+[Mocktail.verify](/docs/support/api.md#mocktailverify) for the assertion:
+
+```ruby
+payment_processor = Mocktail.of(PaymentProcessor)
+subject = CashRegister.new(payment_processor)
+
+subject.boot!
+
+verify { payment_processor.establish_connection }
+```
+
+In the above example, `Mocktail.of(PaymentProcessor)` returns a fake instance of
+a `PaymentProcessor`, replete with fake instance methods in place of all its
+real ones (and also retaining their parameter signatures). Those fake methods
+will return `nil` by default (unless stubbed with
+[Mocktail.stubs](/docs/support/api.md#mocktailstubs)). As shown above, we can
+assert that the fake `payment_processor`'s `establish_connection` method using
+[Mocktail.verify](/docs/support/api.md#mocktailverify).
+
+## Creating mocks of a given module
+
+It's worth noting that `Mocktail.of` will gladly receive a module as an argument
+and then create a one-off class only for the purpose of faking it:
+
+``` ruby
+module Currency
+  def convert(from)
+  end
+end
+
+currency = Mocktail.of(Currency)
+=> #<Mocktail of Currency:0x0000000104a36510>
+
+currency.class
+=> #<Class including module for mocktail of Currency:0x00000001077d4620>
+```
+
+The above `currency` mock object will have a fake `convert` method on it, just
+as an instance of a class including the `Currency` module would.
+
+## You did it!
+
+So there you go, you've got what you need to create mock instances and pass them
+to your subjects.
+
+**Delve deeper and explore more about [stubbing and verifying interactions](../../stubbing_and_verifying.md).**
+
+**Go back and consider other ways to [create mocks](../../tdd.md).**

data/docs/tdd/poro.md

@@ -0,0 +1,15 @@
+# Creating mocked instances of classes you own
+
+Good news! You find yourself on the golden path of Mocktail usage. Creating
+mocks of instances of classes that you or your team have authored and can
+readily change is right in the crosshairs of what the library was made to do!
+(If you're just starting out you should probably target >90% of your Mocktail
+usage to be of this variety.)
+
+Exactly _how_ you create these mocked instances depends on how you prefer to
+get [dependencies](/docs/support/glossary.md#dependency) into the hands of your
+[subject under test](/docs/support/glossary.md#subject-under-test).
+
+**Manually pass instances of dependencies to your test subject, AKA [dependency injection](poro/dependency_injection.md).**
+
+**Allow your subject to instantiate its dependencies by wielding ✨mocking magic✨, AKA [dependency inception](poro/dependency_inception.md).**

data/docs/tdd/third_party.md

@@ -0,0 +1,220 @@
+# Mocking third-party code and gems
+
+A common way people use mocking libraries is to isolate the
+[subject](../support/glossary.md#subject-under-test) from third-party code in a
+gem. The reason for this is straightforward enough: gems and standard library
+classes are often used to broker communication between an application's domain
+logic and the outside world via I/O, and one meaningful way to delineate "unit"
+and "integration" tests is to establish boundaries like "unit tests don't
+interact with the file system, or standard I/O, or the network", then use a
+mocking library to enforce that boundary.
+
+Take this example code that writes recipes to a CSV file:
+
+```ruby
+Recipe = Struct.new(:name, :ingredients, :instructions, keyword_init: true)
+
+require "csv"
+
+class RecipeWriter
+  def write_csv(filename, recipes)
+    CSV.open(filename, "w") do |csv|
+      csv << ["Name", "Ingredients", "Instructions"]
+
+      recipes.each do |recipe|
+        csv << [recipe.name, recipe.ingredients, recipe.instructions]
+      end
+    end
+  end
+end
+```
+
+Suppose you wanted to take this method and write a unit test afterward that
+didn't interact with the file system. You could use a mocking library like
+Mocktail to accomplish this.
+
+Because `CSV.open` is a class method, we can pass `CSV` to
+[Mocktail.replace](../support/api.md#mocktailreplace) to replace it with a fake:
+
+```ruby
+Mocktail.replace(CSV)
+subject = RecipeWriter.new
+csv = Mocktail.of(CSV)
+stubs { CSV.open("some_file.csv", "w") { |blk| blk.call(csv) } }.with { nil }
+
+subject.write_csv("some_file.csv", [
+  Recipe.new(
+    name: "Mojito",
+    ingredients: "mint, lime, rum",
+    instructions: "muddle the mint then go nuts"
+  ),
+  Recipe.new(
+    name: "Negroni",
+    ingredients: "gin, campari, sweet vermouth",
+    instructions: "pour in a glass"
+  )
+])
+
+verify { csv << ["Name", "Ingredients", "Instructions"] }
+verify { csv << ["Mojito", "mint, lime, rum", "muddle the mint then go nuts"] }
+verify { csv << ["Negroni", "gin, campari, sweet vermouth", "pour in a glass"] }
+```
+
+The above is, indeed, an isolated test of the `write_csv` method, as written.
+But, somehow, writing it felt kind of painful!
+
+Let us count the pains:
+
+1. The test is forced to replace a [global class method](class_methods.md)
+(`CSV.open`) when an instance would have been simpler and less far-reaching
+2. Regardless, we had to create a mock instance of `CSV` anyway, because that's
+the type passed to `CSV.open`'s block param. This could confuse readers skimming
+the test, since now we've faked `CSV`'s class methods as well as creating a fake
+`CSV` instance
+3. That fake `CSV` instance gets worse, because the way the subject receives the
+value is through a block param, which requires us to invoke the `blk.call(csv)` to pass it in during our stubbing [demonstration](../support/glossary.md#demonstration). This won't
+be clear to anyone who isn't familiar with how Mocktail is being used
+4. The best assertion we can manage is to verify that the expected calls to
+`CSV#<<` occurred, but it means the dependency's contract is limited to a side
+effect instead of a return value—which would be easier to debug and compose.
+5. Finally, those `verify` calls do nothing to ensure they were called in the
+correct order or even inside the `CSV.open` block—both of which are necessary
+for the file to be written correctly—indicating a logical gap in the test's
+coverage (a custom assertion could be written to validate call-order using
+[Mocktail.calls](../support/api.md#mocktailcalls), but it wouldn't be pretty)
+
+That's five pain points we encountered in the writing of a single test of a
+pretty simple method!
+
+What could we have done to avoid that pain? Well, because we're mocking a
+third-party API (Ruby's standard library [csv](https://github.com/ruby/csv)
+gem), all that pain was unavoidable!  If it turns out to be hard to mock out
+interactions with third-party code, it's not like we can easily change it to be
+easier to work with.
+
+Zooming out, the primary intended benefit of practicing [isolation
+testing](../support/glossary.md#isolated-unit-testing) is to improve our code's
+design. If we listen to testing pain as we design the interaction between the
+subject and its [dependencies](../support/glossary.md#dependency) and respond to
+the pain we experience in our tests by changing the API of the _production_
+code, it improves that code's usability for everyone, not just a test.
+Easier-to-fake code is inherently simpler and therefore easier-to-use code, so
+isolated TDD really serves as a useful proxy to put a healthy pressure on
+developers to arrive at simple designs.
+
+So, if a core tenet of isolated testing with mocks is to listen to testing pain
+as a prompt to improve the design of our subjects' dependencies and we can't
+change the design of third-party code when it proves painful, then it stands to
+reason we're not getting the most out of the practice of isolated test-driven
+development when we mock code we don't own. All we're doing in this case is
+subjecting ourselves to unnecessary, useless pain.
+
+So, what can we do instead? One strategy is to introduce a [wrapper
+object](../support/glossary.md#wrapper-object) that we _do own_ and use it to
+house our dependence on the `csv` gem. Then we can update our code to depend on
+the wrapper and once again use [test
+doubles](../support/glossary.md#test-double) for their intended purpose: to
+improve the design of the wrapper's API.
+
+In this example, that extract refactor might look like this:
+
+```ruby
+require "csv"
+module Wrap
+  class Csv
+    def write(filename, header, rows)
+      CSV.open(filename, "w") do |csv|
+        csv << header
+        rows.each do |row|
+          csv << row
+        end
+      end
+    end
+  end
+end
+
+class RecipeWriter
+  def initialize
+    @csv = Wrap::Csv.new
+  end
+
+  def write_csv(filename, recipes)
+    @csv.write(
+      filename,
+      ["Name", "Ingredients", "Instructions"],
+      recipes.map { |recipe|
+        [recipe.name, recipe.ingredients, recipe.instructions]
+      }
+    )
+  end
+end
+```
+
+This refactor would result in a much simpler test of `RecipeWriter#write_csv`
+if we took a second stab at it:
+
+```ruby
+csv = Mocktail.of_next(Wrap::Csv)
+subject = RecipeWriter.new
+
+subject.write_csv("some_file.csv", [
+  Recipe.new(
+    name: "Mojito",
+    ingredients: "mint, lime, rum",
+    instructions: "muddle the mint then go nuts"
+  ),
+  Recipe.new(
+    name: "Negroni",
+    ingredients: "gin, campari, sweet vermouth",
+    instructions: "pour in a glass"
+  )
+])
+
+verify {
+  csv.write(
+    "some_file.csv",
+    ["Name", "Ingredients", "Instructions"],
+    [
+      ["Mojito", "mint, lime, rum", "muddle the mint then go nuts"],
+      ["Negroni", "gin, campari, sweet vermouth", "pour in a glass"]
+    ]
+  )
+}
+```
+
+Much more straightforward. It also resolves #1, #2, #3, and #5 on our hit list
+of pain points above. The only issue the new factoring doesn't address is the
+fact that the `Wrap::Csv#write` has a side effect instead of a return value, but
+because our ultimate dependency (`CSV.open`) is effectively a fire-and-forget
+method, it's not clear what return value we might want to introduce here without
+knowing more about the needs of the caller.
+
+Still, not bad at all. The new class is much more straightforward and its style
+more consistent with the rest of our application code that was guided by tests.
+
+## Testing wrapper objects
+
+You might be asking, "but who's testing the wrapper objects", and that's a
+question worth asking! In general, if a wrapper is sufficiently simple—meaning,
+without logical branching—then it's usually sufficient to rely on your
+end-to-end testing to test your wrappers, as they would surely fail if things
+didn't work. Testing them on their own in earnest often veers towards [testing
+the
+framework](https://web.archive.org/web/20210124184231/https://bignerdranch.com/blog/what-does-dont-test-the-framework-mean/).
+
+## Also, mocking gems doesn't always work
+
+Additionally, Mocktail can't warrant that its methods will work on every class
+in every gem out there. If you try to mock a third-party API directly and
+something goes wrong, we can't offer support if you open an issue. Instead, we'd
+encourage you to try introducing a wrapper as shown above and mock that instead.
+
+## Restarting the first party
+
+Okay, now that we've covered some details on how to mock third-party code, let's
+keep up the tempo.
+
+**Head back onto the golden path and use Mocktail to create [fake instances of Ruby classes](./poro.md).**
+
+**Wield your newfound gem-faking wizardry to [stub and verify their methods](../stubbing_and_verifying.md).**
+

data/docs/tdd.md

@@ -0,0 +1,15 @@
+# Using Mocktail for test-driven development
+
+If you plan to use this mocking library as a tool in your test-driven
+development workflow, you've come to the right place—it's what Mocktail was
+designed for!
+
+There are several flavors of test-driven development, but the relevant
+distinction for figuring out which direction you want to take Mocktail lies
+before you:
+
+**Use Mocktail to create [fake instances of Ruby classes](tdd/poro.md) you own.**
+
+**Use Mocktail to [fake out class and module methods](tdd/class_methods.md) of types you own.**
+
+**Use Mocktail to [fake out third-party code](tdd/third_party.md) you can't readily change yourself.**

data/lib/mocktail/debug.rb

@@ -22,11 +22,12 @@ module Mocktail
       base_path = Pathname.new(__FILE__).dirname.to_s
       backtrace_minus_this_and_whoever_called_this = e.backtrace&.[](2..)
       internal_call_sites = backtrace_minus_this_and_whoever_called_this&.take_while { |call_site|
-        # the "in `block" is very confusing but necessary to include lines after
+        # the "in `block"/"in 'block" (Ruby 3.4+ uses a single quote instead of a
+        # backtick) is very confusing but necessary to include lines after
         # a stubs { blah.foo }.with { … } call, since that's when most of the
         # good stuff happens
-        call_site.start_with?(base_path) || call_site.include?("in `block")
-      }&.reject { |call_site| call_site.include?("in `block") } || []
+        call_site.start_with?(base_path) || call_site.match?(/in [`']block/)
+      }&.reject { |call_site| call_site.match?(/in [`']block/) } || []
 
       approved_call_sites = [
         /fulfills_stubbing.rb:(16|20)/,

data/lib/mocktail/share/stringifies_call.rb

@@ -8,7 +8,6 @@ module Mocktail
 
     def stringify_multiple(calls, nonzero_message:, zero_message:,
       anonymous_blocks: false, always_parens: false)
-
       if calls.empty?
         "#{zero_message}.\n"
       else

data/lib/mocktail/simulates_argument_error/transforms_params.rb

@@ -24,7 +24,7 @@ module Mocktail
         positional_args: dry_call.args,
 
         keyword_params: Params.new(
-          all: params.select { |type, _|
+          all: params.select { |type, _| # standard:disable Style/HashSlice
             [:keyreq, :key, :keyrest].include?(type)
           }.map { |pair| pair.fetch(1) },
           required: params.select { |t, _| Bind.call(t, :==, :keyreq) }.map { |pair| pair.fetch(1) },
@@ -43,7 +43,7 @@ module Mocktail
     def name_unnamed_params(params)
       params.map.with_index { |param, i|
         if param.size == 1
-          param + ["unnamed_arg_#{i + 1}".to_sym]
+          param + [:"unnamed_arg_#{i + 1}"]
         else
           param
         end

data/lib/mocktail/sorbet/mocktail/debug.rb

@@ -24,11 +24,12 @@ module Mocktail
       base_path = Pathname.new(__FILE__).dirname.to_s
       backtrace_minus_this_and_whoever_called_this = e.backtrace&.[](2..)
       internal_call_sites = backtrace_minus_this_and_whoever_called_this&.take_while { |call_site|
-        # the "in `block" is very confusing but necessary to include lines after
+        # the "in `block"/"in 'block" (Ruby 3.4+ uses a single quote instead of a
+        # backtick) is very confusing but necessary to include lines after
         # a stubs { blah.foo }.with { … } call, since that's when most of the
         # good stuff happens
-        call_site.start_with?(base_path) || call_site.include?("in `block")
-      }&.reject { |call_site| call_site.include?("in `block") } || []
+        call_site.start_with?(base_path) || call_site.match?(/in [`']block/)
+      }&.reject { |call_site| call_site.match?(/in [`']block/) } || []
 
       approved_call_sites = [
         /fulfills_stubbing.rb:(16|20)/,

data/lib/mocktail/sorbet/mocktail/share/stringifies_call.rb

@@ -12,7 +12,6 @@ module Mocktail
     sig { params(calls: T::Array[Call], nonzero_message: String, zero_message: String, anonymous_blocks: T::Boolean, always_parens: T::Boolean).returns(String) }
     def stringify_multiple(calls, nonzero_message:, zero_message:,
       anonymous_blocks: false, always_parens: false)
-
       if calls.empty?
         "#{zero_message}.\n"
       else

data/lib/mocktail/sorbet/mocktail/simulates_argument_error/transforms_params.rb

@@ -28,7 +28,7 @@ module Mocktail
         positional_args: dry_call.args,
 
         keyword_params: Params.new(
-          all: params.select { |type, _|
+          all: params.select { |type, _| # standard:disable Style/HashSlice
             [:keyreq, :key, :keyrest].include?(type)
           }.map { |pair| pair.fetch(1) },
           required: params.select { |t, _| Bind.call(t, :==, :keyreq) }.map { |pair| pair.fetch(1) },
@@ -48,7 +48,7 @@ module Mocktail
     def name_unnamed_params(params)
       params.map.with_index { |param, i|
         if param.size == 1
-          param + ["unnamed_arg_#{i + 1}".to_sym]
+          param + [:"unnamed_arg_#{i + 1}"]
         else
           param
         end

data/lib/mocktail/sorbet/mocktail/value/call.rb

@@ -36,7 +36,7 @@ module Mocktail
           :singleton, :double, :original_type, :dry_type,
           :method, :original_method, :args, :kwargs, :block
         ].all? { |attr|
-          instance_variable_get("@#{attr}") == other.send(attr)
+          instance_variable_get(:"@#{attr}") == other.send(attr)
         }
       else
         false

data/lib/mocktail/sorbet/mocktail/version.rb

@@ -8,5 +8,5 @@ module Mocktail
     Mocktail.send(:remove_const, :VERSION)
   end
 
-  VERSION = "2.0.0"
+  VERSION = "3.0.0"
 end

data/lib/mocktail/value/call.rb

@@ -32,7 +32,7 @@ module Mocktail
           :singleton, :double, :original_type, :dry_type,
           :method, :original_method, :args, :kwargs, :block
         ].all? { |attr|
-          instance_variable_get("@#{attr}") == other.send(attr)
+          instance_variable_get(:"@#{attr}") == other.send(attr)
         }
       else
         false

data/lib/mocktail/version.rb

@@ -6,5 +6,5 @@ module Mocktail
     Mocktail.send(:remove_const, :VERSION)
   end
 
-  VERSION = "2.0.0"
+  VERSION = "3.0.0"
 end

data/mocktail.gemspec

@@ -12,7 +12,7 @@ Gem::Specification.new do |spec|
 
   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")
+  spec.required_ruby_version = Gem::Requirement.new(">= 3.1.0")
 
   spec.metadata["homepage_uri"] = spec.homepage
   spec.metadata["source_code_uri"] = spec.homepage
@@ -22,7 +22,7 @@ Gem::Specification.new do |spec|
   # Specify which files should be added to the gem when it is released.
   # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
   spec.files = Dir.chdir(File.expand_path(__dir__)) do
-    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{\A(?:test|spec|features|src|sub_projects|spoom_data|sorbet|script|docs)/}) }
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{\A(?:test|spec|features)/}) }
   end
   spec.bindir = "exe"
   spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }