mocktail 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8792bd9f9b3ccc36c01046557e63c390eccd97c53e25b54da6c54ca2690f839d
-  data.tar.gz: 13c9444150fd0bd4098660f5960d268d37d67c8a27058834259dd2f1717933b6
+  metadata.gz: d5a4729eb601d9f3ed3ece213a460dd0881105a505a812c4d035c14cec252223
+  data.tar.gz: f4b3a3352f63de7de812ce8db616b570de740f1ce7550f8677eb47ecb99305fb
 SHA512:
-  metadata.gz: 43a3c90e6edcbc9f04f2d4eb26e930a43dd8ac685f50d98d95f2c6128edd873776d02123258aa5e12766a1940e77e1704a252a18e5541bd52e8be3e5c6605d91
-  data.tar.gz: 6c872542db03bc16e548c5d1f48b18229638f2553612c4e9897443e9f43d01d6056428eca76da9814a4c82823d658ce434ec88316d579b6aab7741d8dcbeff1c
+  metadata.gz: 469b39914d0d887b7cd8d25006f5dc6f3ca8a1a3b5594f39bfae5e3c21f36f2983a30ec2849c916129e216dd9fb731f476abbdc5a41ad0f80c740d7106793a7d
+  data.tar.gz: d7c24487a15c7ddc9b540d6c9d5c2b3f07da3599eba61eee128a79f5faa3fd5f6c4e54b7ea4318119a86737ead855f30d814a7f39e30c1e20a6f3880f0c21ce2

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,17 @@
+# 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.2)
 
 GEM
   remote: https://rubygems.org/
@@ -49,6 +49,7 @@ GEM
 
 PLATFORMS
   arm64-darwin-20
+  ruby
 
 DEPENDENCIES
   minitest

data/README.md

@@ -6,73 +6,74 @@ 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
+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 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
-* 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
+* **Less test setup**: Dynamic stubbings based on the arguments passed to the actual call
+* **Expressive**: Built-in [argument matchers](#mocktailmatchers) and a simple
+  API for adding [custom matchers](#custom-matchers)
+* **Powerful**: [Argument captors](#mocktailcaptor) for assertions of very
+  complex arguments
+
+## Ready to order?
+
+### Install the gem
 
 The main ingredient to add to your Gemfile:
 
@@ -80,7 +81,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 +103,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 +131,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 +284,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 +490,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 +513,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
@@ -554,4 +572,3 @@ 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

@@ -29,6 +29,32 @@ 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
 
 # (If you use this, don't forget to add pry to your Gemfile!)
 require "pry"

data/lib/mocktail/version.rb

@@ -1,3 +1,3 @@
 module Mocktail
-  VERSION = "0.0.1"
+  VERSION = "0.0.2"
 end

data/mocktail.gemspec

@@ -8,7 +8,7 @@ Gem::Specification.new do |spec|
 
   spec.summary = "your objects, less potency"
   spec.homepage = "https://github.com/testdouble/mocktail"
-  spec.required_ruby_version = Gem::Requirement.new(">= 2.7.0")
+  spec.required_ruby_version = Gem::Requirement.new(">= 3.0.0")
 
   spec.metadata["homepage_uri"] = spec.homepage
   spec.metadata["source_code_uri"] = spec.homepage

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mocktail
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - Justin Searls
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-09-22 00:00:00.000000000 Z
+date: 2021-10-02 00:00:00.000000000 Z
 dependencies: []
 description:
 email:
@@ -93,7 +93,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.7.0
+      version: 3.0.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="