mocktail 2.0.0 → 3.0.0

data/docs/faq/mocking_http.md

@@ -0,0 +1,151 @@
+# Mocking out network requests by faking HTTP
+
+Mocktail does nothing to make faking HTTP requests easy. And if you care to try,
+know that it also does nothing to ensure mocked requests behave consistently
+across various HTTP libraries and gems (`Net::HTTP`, faraday, httparty, etc.).
+In fact, other gems are designed to do this and only this, most notably
+[webmock](https://github.com/bblimke/webmock).
+
+But, if you're reading this, there's a _small chance_ you're thinking about
+faking out the network in the context of something you're conceiving of as a
+unit test, and that's why you're looking to your mocking library for an answer.
+If that's the case, here's a quick note on why you might be trying to apply
+the wrong solution to the problem.
+
+Suppose you're writing a unit test and trying to control for the network and
+thinking about using a library like Mocktail as a result. To illustrate: imagine
+you're testing a method that makes a network request and does one thing if the
+response succeeds and another thing to handle failures.
+
+You might want to write these two test cases:
+
+```ruby
+def test_success
+  result = @subject.hack_computer("/school_sprinklers")
+
+  assert_equal "Mess with the best, die like the rest", result
+end
+
+def test_failure
+  assert_raises(CrashOverrideError) do
+    @subject.hack_computer("/the_gibson")
+  end
+end
+```
+
+But you may not have an easy way to force the first test case to always exercise
+the happy path in which the request succeeds. Similarly, you would need a way to
+ensure the other test case to consistently travels the sad path wherein the
+request fails. Short of spinning up a fake HTTP service, you don't have a lot
+of options, especially if your implementation looks anything like this:
+
+```ruby
+class Computer
+  SICK_BURN = "Mess with the best, die like the rest"
+
+  def hack_computer(target)
+    uri = URI.parse("https://example.com#{target}")
+    req = Net::HTTP::Post.new(uri)
+
+    Net::HTTP.start(uri.host, uri.port, use_ssl: true) do |http|
+      http.request(req) do |res|
+        if Net::HTTPSuccess === res
+          return SICK_BURN
+        else
+          raise CrashOverrideError
+        end
+      end
+    end
+  end
+end
+```
+
+This case is so simple that it may strain credulity, but instead of trying to
+introduce a network-layer mock to your application-layer concern, you might
+consider writing a [wrapper](../support/glossary.md#wrapper-object) around the
+`Net::HTTP` API that you don't control and can't change that your application
+can invoke wherever it needs to make a network request. Then, instead of your
+test needing to mock out the entire networking stack, it just needs to _mock out
+the wrapper_ instead.
+
+Here's what the refactored [subject](../support/glossary.md#subject-under-test)
+could look like if we extracted its usage of `Net::HTTP` into an `Http` wrapper
+that we own:
+
+```ruby
+class Computer
+  SICK_BURN = "Mess with the best, die like the rest"
+
+  def initialize
+    @http = Http.new
+  end
+
+  def hack_computer(target)
+    if @http.post("https://example.com#{target}").success?
+      return SICK_BURN
+    else
+      raise CrashOverrideError
+    end
+  end
+end
+
+class Http
+  Result = Data.define(:json, :success?)
+
+  def post(url)
+    uri = URI.parse(url)
+    req = Net::HTTP::Post.new(uri)
+
+    Net::HTTP.start(uri.host, uri.port, use_ssl: true) do |http|
+      http.request(req) do |res|
+        return Result.new(
+          data: JSON.parse(res.body),
+          success?: Net::HTTPSuccess === res
+        )
+      end
+    end
+  end
+end
+```
+
+Now, the test will be much easier to implement, because instead of trying to
+figure out how to mock out all of HTTP, we're simply mocking out an object that
+quacks just like any other object—leaving the fact that it crosses a spooky
+network boundary as a mere implementation detail that `Computer`'s test doesn't
+need to worry about.
+
+Now, a complete test could fully cover the subject with minimally-invasive
+mocking:
+
+```ruby
+def initialize
+  @http = Mocktail.of_next(Http)
+
+  @subject = Computer.new
+end
+
+def test_success
+  stubs { Http.post("/school_sprinklers") }.with { Computer::Result.new(data: nil, success?: true) }
+
+  result = @subject.hack_computer("/school_sprinklers")
+
+  assert_equal "Mess with the best, die like the rest", result
+end
+
+def test_failure
+  stubs { Http.post("/the_gibson") }.with { Computer::Result.new(data: nil, success?: false) }
+
+  assert_raises(CrashOverrideError) do
+    @subject.hack_computer("/the_gibson")
+  end
+end
+```
+
+Anyway, that's why you _probably_ don't want to fake out an HTTP interaction
+directly with Mocktail and should instead look to a purpose-built gem like
+[webmock](https://github.com/bblimke/webmock) or else consider alternative
+designs that make the code in question easier to test.
+
+**If you've heard enough, you can go back and consider [non-TDD use cases for Mocktail](../other_uses.md).**
+
+**Or if you're finally ready to walk the golden path, you can revisit [Mocktail as a TDD tool](../tdd.md).**

data/docs/faq/mocking_the_subject.md

@@ -0,0 +1,161 @@
+# Mocking methods on the subject being tested
+
+Once in a while, it may seem desirable to fake out a method on the [subject
+under test](../support/glossary.md#subject-under-test).
+
+The scenario usually looks something like this:
+
+```ruby
+class User < ApplicationRecord
+  # The method under test:
+  def best_promo
+    promos = CouponCode.active.flat_map { |coupon_code|
+      eligible_promotions(coupon_code)
+    }.max_by { |promo|
+      promo.percent_discount
+    }
+  end
+
+  # … 45 other methods
+
+  private
+
+  def eligible_promotions(coupon_code)
+    # 30 lines of gnarly queries and conditions
+  end
+end
+```
+
+Suppose a developer wants to  open up `user_spec.rb` and write a spec for
+`best_promo`. While `best_promo` might not be the simplest method in the world,
+one might imagine a straightforward test with two or three test cases based on
+the existence of different `CouponCode` records.
+
+But inevitably, during test setup, it becomes clear that the stuff going on in
+`eligible_promotions` is _intense_, and in order to get the database into the
+state it would need to be to exercise the logic in `best_promo`, the test would
+require fifteen lines of painful and confusing setup code.
+
+This gives rise to the idea: "I could just mock out `eligible_promotions` and
+this test would be far clearer and easier to write".
+
+Of course, if that idea led you to this page, I have bad news: Mocktail
+can't help you here and it's our opinion that getting into the habit of using
+mocking for this purpose is a _really_ bad idea.
+
+Why?
+
+First of all, to mock the `eligible_promotions` method in this case would be an
+example of a [partial mock](../support/glossary.md#partial-mock) (discussed
+[elsewhere](./partial_mocks.md)). Moreover, that partial mock would be the
+_subject itself_—meaning, a test to validate a subject's public API would fake
+out the subject's private implementation. As a result, no meaningful confidence
+would really be gained from such a test. At best, a test might tell you how the
+`best_promo` method would behave in the hypothetical scenario of however
+`eligible_promotions` was [stubbed](../support/glossary.md#stub), but that
+isn't a particularly interesting thing to know (much less codify in a test suite
+for perpetuity).
+
+Nevertheless, "mocking the subject" has been remarkably common in Rails
+applications since the mid-2000s. In 2010, [DHH
+tweeted](https://twitter.com/dhh/status/27444365459?s=20) something that was
+seen as controversial with respect to test runners (as RSpec had gained a
+massive following) but entirely mundane when it came to mocking libraries
+([mocha](https://github.com/freerange/mocha), in this case):
+
+> Q: What testing framework do you use at 37signals? A: test/unit with the occasional splash of mocha. (That's all you need for great testing)
+
+In the experience of the present author, that "splash of mocha" was almost
+always used in cases like the above: to fake out one method in an Active Record
+model in the service of testing another method in the same model. It made the
+initial writing of a test easier, but at the cost of its comprehensibility and
+long-term maintainability.
+
+So, if mocking out a method on the subject isn't the solution, what should you
+do instead?
+
+In almost every case, this situation is indicating that the subject is serving
+too many disparate purposes and the only workable answer is that the method
+being tested, the method being mocked, or perhaps _both_ should be extracted
+into classes of their own—complete with proper names and a clear
+[dependency](../support/glossary.md#dependency) relationship. Only _then_ might
+an isolated unit test with mocks be appropriate as a tool to help specify the
+terms of that relationship.
+
+To illustrate, we could carry through this refactor by extracting both methods
+into new classes and referencing them from the original `best_promo` entrypoint
+in the model:
+
+```ruby
+class User < ApplicationRecord
+  def best_promo
+    FindsBestPromo.new.find(CouponCode.active)
+  end
+end
+
+class FindsBestPromo
+  def initialize
+    @determines_eligible_promotions = DeterminesEligiblePromotions.new
+  end
+
+  def find(coupon_codes)
+    coupon_codes.flat_map { |coupon_code|
+      @determines_eligible_promotions.determine(coupon_code)
+    }.max_by { |promo|
+      promo.percent_discount
+    }
+  end
+end
+
+class DeterminesEligiblePromotions
+  def determine(coupon_code)
+    # 30 lines, still gnarly
+  end
+end
+```
+
+Finally, we could write a test of `FindsBestPromo` that used Mocktail:
+
+```ruby
+class FindsBestPromoTest < Minitest::Test
+  def setup
+    @determines_eligible_promotions = Mocktail.of_next(DeterminesEligiblePromotions)
+    @subject = FindsBestPromo.new
+  end
+
+  def test_max_discount
+    stubs { @determines_eligible_promotions.determine("NEAT25") }.with {
+      [
+        Promo.new(name: "A", percent_discount: 20),
+        Promo.new(name: "B", percent_discount: 25)
+      ]
+    }
+    stubs { @determines_eligible_promotions.determine("COOL15") }.with {
+      [Promo.new(name: "C", percent_discount: 15)]
+    }
+
+    result = @subject.find(["NEAT25", "COOL15"])
+
+    assert_equal "B", result.name
+  end
+end
+```
+
+Given the starting point, however, it's important to admit that nothing about
+this is easy. Extracting behavior from a years-old class that's juggling dozens
+of responsibilities where inter-dependencies abound is never as simple as
+cut-and-paste. And creating new, single-use classes in a codebase dominated by a
+handful of massive files will surely feel out of place and inconsistent.
+Finally, deviating from the perceived "Rails Way" requires thoughtful planning,
+and is likely to engender conflict without winning the buy-in of all interested
+parties. That said, there's no time like the present, because this work willl
+only become more difficult with time.
+
+If you've read this far and feel a little hopeless about how to make forward
+progress wrangling complexity of this scale, it may make sense to discuss
+bringing in outside help, like [the kind we offer at Test
+Double](https://testdouble.com/contact).
+
+**If you've heard enough, you can go back and consider [non-TDD use cases for Mocktail](../other_uses.md).**
+
+**Or if you're finally ready to walk the golden path, you can revisit [Mocktail as a TDD tool](../tdd.md).**

data/docs/faq/mocking_time.md

@@ -0,0 +1,34 @@
+# Mocking out time
+
+If you want to fake out time in a Ruby test, there are three things to think
+about:
+
+1. Editing the actual system time will prevent you from running tests in
+parallel, will break HTTPS/SSL certificate authentication, and will generally
+wreak havoc on most modern computers
+
+2. Editing the value of when "now" is for `Time` and `Date` in Ruby means that
+your Ruby code will have a very different time than your database, any network
+dependencies, and any binaries you shell out to
+
+3. _Freezing_ time to a specific, fixed value can open the door to bugs due to
+code that comes to depend on that fixedness. For example, two measurements of
+"now" equalling one another when that can never be guaranteed to happen in
+production
+
+Where does that leave you? I don't know, but Mocktail doesn't do anything to
+help you here.
+
+The best tool for this job is definitely the [timecop
+gem](https://github.com/travisjeffery/timecop). Just use its `travel` methods to
+shift the Ruby-time to where you want, and be mindful that the time will
+disagree with any network or system dependencies.
+
+Oh, and if you're looking at the [ActiveSupport time
+helpers](https://api.rubyonrails.org/v5.2.4/classes/ActiveSupport/Testing/TimeHelpers.html),
+just know that even when they _say_ `travel`, they're actually _freezing_ time,
+which creates the category of problems described in issue #3 above.
+
+**If you've heard enough, you can go back and consider [non-TDD use cases for Mocktail](../other_uses.md).**
+
+**Or if you're finally ready to walk the golden path, you can revisit [Mocktail as a TDD tool](../tdd.md).**

data/docs/faq/partial_mocks.md

@@ -0,0 +1,34 @@
+# Creating partial mocks that fake out a subset of methods
+
+If you've looked at Mocktail's APIs for [creating mock
+instances](../support/api.md#mocktailof) and [replacing class or module
+methods](../support/api.md#mocktailreplace), you'll find that it's an a bit of
+an _all or nothing_ affair.  You can get create an instance of a class with
+_all_ its methods replaced with `nil`-returning fakes and you can replace _all_
+a module's module methods, but **you can't tell Mocktail to only replace one or a
+handful of methods while continuing to call through to some other real methods**.
+
+Why?! Why would we do something so unfair as to withhold such obviously useful
+functionality?
+
+Well, the answer—like everything having to do with [test
+doubles](../support/glossary.md#test-double)—requires some nuance. In testing
+parlance, to replace some of the methods on a
+[dependency](../support/glossary.md#dependency) but not all of them is to create
+what is called a [partial mock](../support/glossary.md#partial-mock) (click
+through its glossary definition for some of the reasons partial mocks are
+considered to be an antipattern).
+
+Mocktail was written to promote test-driven development that specifies
+thoughtfully-designed classes that interact with other classes, but partial
+mocks actually detract from that purpose in practice. As a result Mocktail,
+doesn't offer a way to create partial mocks.
+
+If you find yourself wanting to reach for a partial mock, we'd encourage you to
+first take it as potential design feedback that a dependency is perhaps too big
+and its contract with [subject](../support/glossary.md#subject-under-test) too
+porous.
+
+**If you've heard enough, you can go back and consider [non-TDD use cases for Mocktail](../other_uses.md).**
+
+**Or if you're finally ready to walk the golden path, you can revisit [Mocktail as a TDD tool](../tdd.md).**

data/docs/faq/verifying_real_interactions.md

@@ -0,0 +1,52 @@
+# Recording interactions on real methods
+
+Okay, so imagine this situation: you have a unit test that, among other things,
+calls some API that doesn't return a meaningful
+[value](../support/glossary.md#value) and you want to make sure that you've
+covered it. Since your test can't observe the result of the call, you want to
+make sure it happened
+
+```ruby
+def roll_dice(dice)
+  @mouth.blow!(dice)
+  dice.roll
+end
+```
+
+If a developer were simultaneously very eager to achieve an extreme amount of
+code coverage and also superstitious that _actually_ blowing on the dice is very
+important, they could look at that `@mouth.blow!` invocation and ask "how can I
+verify that call happened while still calling through to its real
+implementation?"
+
+Well, the answer if you're using Mocktail is, "sorry, you can't."
+
+The primary reason this isn't supported is because Mocktail exists to facilitate
+test-driven development of code that's fully isolated from its
+[dependencies](../support/glossary.md#dependency) in order to design
+well-considered interactions, and calling through to a dependency's actual
+implementation naturally violates that isolation. Additionally, for any reason a
+tester might wish to call through to the actual implementation _other than
+superstition_, it stands to reason that at most one of the following is
+possible:
+
+1. An integrated test that doesn't use mocks could indirectly observe a
+dependency's side effect as evidence that a call occurred and therefore a
+mocking library isn't required to [proxy it](../support/glossary.md#proxy), _or_
+2. It's not possible for the side effect of the call to be observed by either
+the test or its [subject](../support/glossary.md#subject-under-test) and
+therefore it's safe to achieve proper isolation by replacing the real
+implementation with a fake one
+
+But both conditions can't be true.  As a result, the urge to add a test
+assertion that a call occurred in a particular way may represent an [unnecessary
+over-specification](https://blog.testdouble.com/posts/2020-02-25-necessary-and-sufficient/).
+
+That said, if you're unswayed and still set on having this functionality, you
+can find it in the [rr
+gem](https://github.com/rr/rr/blob/master/doc/03_api_overview.md#mockproxy)'s
+`mock.proxy` API.
+
+**If you've heard enough, you can go back and consider [non-TDD use cases for Mocktail](../other_uses.md).**
+
+**Or if you're finally ready to walk the golden path, you can revisit [Mocktail as a TDD tool](../tdd.md).**

data/docs/installation_sorbet.md

@@ -0,0 +1,99 @@
+# Installing Mocktail with Sorbet
+
+Alright, when you add a type checker to isolated unit tests, you're really
+cooking with gas. That's because tests that mock out
+[dependencies](support/glossary.md#dependency) to design the internal APIs
+a [subject](support/glossary.md#subject-under-test) will invoke to divide
+its job into smaller, focused sub-tasks is really about defining the _contracts_
+between units, and those contracts are most often defined by method signatures:
+parameters and return values.
+
+And what are type checkers most concerned with? Oh yeah, parameters and return
+values! Instead of potentially brittle tests that may keep passing even when the
+contract changes, tests that are strictly type-checked won't lie to you.
+Additionally, editors that support [red squiggles and
+autocorrections](https://sorbet.org/docs/vscode) for Sorbet can enable
+test-driven workflows you won't see elsewhere in Ruby: invoke a method as you
+wish it existed in your test, and a quickfix to update the method's definition
+is often just a keyboard shortcut away. The power you'll feel is intoxicating!
+
+All that is why topping your Mocktail with Sorbet is a match made in zero-proof
+testing heaven. All you need to do to install it is add this to your Gemfile:
+
+```ruby
+gem "mocktail", group: :test, require: "mocktail/sorbet"
+```
+
+Note the goofy `require: "mocktail/sorbet"` option above. We don't see that a
+lot in Ruby, because most gems have a single primary entrypoint to require, and
+it's almost always the same name as the gem. However, so that Mocktail can be
+used with and without [Sorbet's runtime type
+safety](https://sorbet.org/docs/runtime) enabled, it actually ships with two
+distributions:
+
+* `require "mocktail"` will load a version of the library that has [effectively
+erased](https://github.com/kddnewton/sorbet-eraser) all of its Sorbet types, so
+you'll never see a runtime type check
+* `require "mocktail/sorbet"` will load the library with all of its Sorbet
+signatures intact, so that Sorbet users can benefit from both static and runtime
+checks
+
+Be warned: it's all Sorbet or no Sorbet. **Do not cross the streams and require
+both of them** unless you like constant redefinition warnings. Mocktail may
+throw an error to try to fail fast if it detects both are required, since the
+resulting behavior is undefined.
+
+As for Sorbet, that's really all you need to know! Everything else is just the
+usual stack of tools like the [srb CLI](https://sorbet.org/docs/cli),
+[tapioca](https://github.com/Shopify/tapioca), and
+[spoom](https://github.com/Shopify/spoom), plus whatever editor integration you
+prefer.
+
+## Type checking your tests
+
+If you want to benefit from type checking in your tests, it means you'll have to
+enable type checking in your tests. Code examples you find in the rest of
+Mocktail's documentation won't show this, but a test listing might look like
+this to get all the benefits that Sorbet-flavored mocktail has to offer
+(Minitest below):
+
+```ruby
+# typed: strict
+
+require "test_helper"
+
+class StuffDoerTest < Minitest::Test
+  extend T::Sig
+
+  sig { params(name: String).void }
+  def initialize(name)
+    super
+    @loads_stuff = T.let(Mocktail.of_next(LoadsStuff), LoadsStuff)
+
+    @subject = T.let(StuffDoer.new, StuffDoer)
+  end
+
+  sig { void }
+  def test_doing_stuff
+    # tests go here
+  end
+end
+```
+
+It probably won't be a surprise to have to add `sig` to each test case when
+using `typed: strict`, but the `T.let` in the initializer is a definite bummer.
+This could probably be worked around with memoized helpers, but that's outside
+the scope of Mocktail for now, especially considering [Sorbet may obviate the
+need for explicit declaration of certain instance variables in the
+future](https://github.com/sorbet/sorbet/issues/3513).
+
+## Configuring your test runner
+
+But before we dive in and start writing tests, we need to configure Mocktail
+with your preferred test runner.
+
+**If you were glad to see the code example above was in Minitest, [keep the party going](configuring_minitest.md).**
+
+**If you're annoyed it wasn't in RSpec, [switch trains to go to RSpec-land](configuring_rspec.md).**
+
+

data/docs/installation_untyped.md

@@ -0,0 +1,29 @@
+# Installing Mocktail
+
+So, you want to get started with Mocktail Classic™, do you? Here's how to get it
+installed! (And if you're having second thoughts on passing on [the Sorbet
+edition](installation_sorbet.md), there's still time!)
+
+## Installation
+
+First thing's first, add this to your Gemfile:
+
+```ruby
+gem "mocktail", group: :test, require: "mocktail"
+```
+
+(That redundant `require` option is just a garnish and won't cause any harm;
+it's there to signal to future readers that you're _not_ using
+`mocktail/sorbet`.)
+
+Once installed, you can require Mocktail like you might expect:
+
+```ruby
+require "mocktail"
+```
+
+Next step: it's time to configure Mocktail with your test runner!
+
+**If you like to keep things classy, maybe [you use Minitest](configuring_minitest.md).**
+
+**Or maybe you'd rather express your intent [to use RSpec](configuring_rspec.md).**

data/docs/other_uses.md

@@ -0,0 +1,32 @@
+# Other uses for Mocktail
+
+If you're looking to accomplish something with Mocktail that doesn't involve
+test-driven development, let's get real. There's a very high likelihood that
+what you're looking to do is either:
+
+1. Not the best tool for the job
+2. Not a job worth doing
+
+But hey, could be wrong. The present author once did a [talk about all the ways
+people abuse mocking
+libraries](https://blog.testdouble.com/talks/2018-03-06-please-dont-mock-me/)
+and undermine the value of their tests, so there is a track record of bias here.
+
+By popular demand, here are some ways you might be thinking about using
+Mocktail:
+
+**Mocking out the system clock in a vain attempt to [master space and time](faq/mocking_time.md).**
+
+**Mocking an HTTP API by faking out [Ruby's built-in networking](faq/mocking_http.md).**
+
+**Mocking out _just one_ method on an [otherwise real object](faq/partial_mocks.md).**
+
+**Recording method invocations while [calling through to their real implementation](faq/verifying_real_interactions.md).**
+
+**Using Mocktail to fix an existing test that's [failing in a gnarly way you don't understand](faq/existing_tests.md).**
+
+**Mocking out a method on the subject under test, AKA [the thing you're testing itself](faq/mocking_the_subject.md).**
+
+---
+
+**Once you've seen enough, you can take a second look at [Mocktail as a TDD tool](tdd.md).**