mocktail 2.0.0 → 3.0.0

data/rbi/mocktail-pregenerated.rbi

@@ -4,6 +4,7 @@
 # This is an autogenerated file for types exported from the `mocktail` gem.
 # Please instead update this file by running `bin/tapioca gem mocktail`.
 
+
 # typed: true
 
 # DO NOT EDIT MANUALLY
@@ -24,6 +25,8 @@ module Mocktail
     # don't commit code that relies on it!
     #
     # source://mocktail//lib/mocktail/sorbet/mocktail.rb#149
+    # Stores most transactional state about calls & stubbing configurations
+    # Anything returned by this is undocumented and could change at any time, so
     sig { returns(::Mocktail::Cabinet) }
     def cabinet; end
 
@@ -32,6 +35,8 @@ module Mocktail
     # calls to that method
     #
     # source://mocktail//lib/mocktail/sorbet/mocktail.rb#141
+    # An alias for Mocktail.explain(double).reference.calls
+    # Takes an optional second parameter of the method name to filter only
     sig do
       params(
         double: ::Object,
@@ -71,6 +76,7 @@ module Mocktail
     # stubs its constructor to return that fake the next time klass.new is called
     #
     # source://mocktail//lib/mocktail/sorbet/mocktail.rb#63
+    # Returns an instance of `klass` whose implementation is mocked out AND
     sig do
       type_parameters(:T)
         .params(
@@ -100,6 +106,7 @@ module Mocktail
     # or included will also fake instance methods
     #
     # source://mocktail//lib/mocktail/sorbet/mocktail.rb#111
+    # Replaces every singleton method on `type` with a fake, and when instantiated
     sig { params(type: T.any(::Module, T::Class[T.anything])).void }
     def replace(type); end
 
@@ -200,6 +207,7 @@ class Mocktail::Call < ::T::Struct
   # to redefine the equality methods to compare the values of the attributes.
   #
   # source://mocktail//lib/mocktail/sorbet/mocktail/value/call.rb#27
+  # Because T::Struct compares with referential equality, we need
   sig { params(other: T.nilable(T.anything)).returns(T::Boolean) }
   def ==(other); end
 
@@ -212,6 +220,7 @@ class Mocktail::Call < ::T::Struct
   def hash; end
 
   class << self
+    # source://sorbet-runtime/0.5.11971/lib/types/struct.rb#13
     # source://sorbet-runtime/0.5.10983/lib/types/struct.rb#13
     def inherited(s); end
   end
@@ -292,6 +301,14 @@ module Mocktail::Debug
     # mocked BasicObject
     #
     # source://mocktail//lib/mocktail/sorbet/mocktail/debug.rb#20
+    # It would be easy and bad for the mocktail lib to call something like
+    #   double == other_double
+    # But if it's a double, that means anyone who stubs that method could change
+    # the internal behavior of the library in unexpected ways (as happened here:
+    # https://github.com/testdouble/mocktail/issues/7 )
+    # For that reason when we run our tests, we also want to blow up if this
+    # happens unintentionally. This works in conjunction with the test
+    # MockingMethodfulClassesTest, because it mocks every defined method on the
     sig { void }
     def guard_against_mocktail_accidentally_calling_mocks_if_debugging!; end
   end
@@ -320,6 +337,8 @@ class Mocktail::DeclaresDryClass
   # mocked methods. YMMV
   #
   # source://mocktail//lib/mocktail/sorbet/mocktail/imitates_type/makes_double/declares_dry_class.rb#55
+  # These have special implementations, but if the user defines
+  # any of them on the object itself, then they'll be replaced with normal
   sig do
     params(
       dry_class: T::Class[::Object],
@@ -372,6 +391,7 @@ class Mocktail::DemoConfig < ::T::Struct
   const :times, T.nilable(::Integer), default: T.unsafe(nil)
 
   class << self
+    # source://sorbet-runtime/0.5.11971/lib/types/struct.rb#13
     # source://sorbet-runtime/0.5.10983/lib/types/struct.rb#13
     def inherited(s); end
   end
@@ -445,6 +465,7 @@ class Mocktail::Double < ::T::Struct
   const :dry_methods, T::Array[::Symbol]
 
   class << self
+    # source://sorbet-runtime/0.5.11971/lib/types/struct.rb#13
     # source://sorbet-runtime/0.5.10983/lib/types/struct.rb#13
     def inherited(s); end
   end
@@ -460,6 +481,7 @@ class Mocktail::DoubleData < ::T::Struct
   const :stubbings, T::Array[Mocktail::Stubbing[T.anything]]
 
   class << self
+    # source://sorbet-runtime/0.5.11971/lib/types/struct.rb#13
     # source://sorbet-runtime/0.5.10983/lib/types/struct.rb#13
     def inherited(s); end
   end
@@ -592,6 +614,7 @@ class Mocktail::FakeMethodData < ::T::Struct
   const :stubbings, T::Array[Mocktail::Stubbing[T.anything]]
 
   class << self
+    # source://sorbet-runtime/0.5.11971/lib/types/struct.rb#13
     # source://sorbet-runtime/0.5.10983/lib/types/struct.rb#13
     def inherited(s); end
   end
@@ -683,6 +706,10 @@ class Mocktail::GrabsOriginalMethodParameters
   # per usual
   #
   # source://mocktail//lib/mocktail/sorbet/mocktail/grabs_original_method_parameters.rb#14
+  # Sorbet wraps the original method in a sig wrapper, so we need to unwrap it.
+  # The value returned from `owner.instance_method(method_name)` does not have
+  # the real parameters values available, as they'll have been erased
+  # If the method isn't wrapped by Sorbet, this will return the #instance_method,
   sig { params(method: T.nilable(T.any(::Method, ::UnboundMethod))).returns(T::Array[T::Array[::Symbol]]) }
   def grab(method); end
 
@@ -874,6 +901,7 @@ class Mocktail::Matchers::Base
   # single-argument, though, so that's defaulted here and in #insepct
   #
   # source://mocktail//lib/mocktail/sorbet/mocktail/matchers/base.rb#15
+  # Custom matchers can receive any args, kwargs, or block they want. Usually
   sig { params(expected: ::BasicObject).void }
   def initialize(expected); end
 
@@ -934,6 +962,8 @@ class Mocktail::Matchers::Captor
   # it needs to think it's being returned whatever parameter is expected
   #
   # source://mocktail//lib/mocktail/sorbet/mocktail/matchers/captor.rb#59
+  # This T.untyped is intentional. Even though a Capture is surely returned,
+  # in order for a verification demonstration to pass its own type check,
   sig { returns(T.untyped) }
   def capture; end
 
@@ -1139,6 +1169,7 @@ class Mocktail::NoExplanationData < ::T::Struct
   def stubbings; end
 
   class << self
+    # source://sorbet-runtime/0.5.11971/lib/types/struct.rb#13
     # source://sorbet-runtime/0.5.10983/lib/types/struct.rb#13
     def inherited(s); end
   end
@@ -1160,6 +1191,7 @@ class Mocktail::Params < ::T::Struct
   def rest?; end
 
   class << self
+    # source://sorbet-runtime/0.5.11971/lib/types/struct.rb#13
     # source://sorbet-runtime/0.5.10983/lib/types/struct.rb#13
     def inherited(s); end
   end
@@ -1484,6 +1516,20 @@ class Mocktail::RunsSorbetSigBlocksBeforeReplacement
   # It's very fun and confusing and a great time.
   #
   # source://mocktail//lib/mocktail/sorbet/mocktail/replaces_type/runs_sorbet_sig_blocks_before_replacement.rb#26
+  # This is necessary because when Sorbet runs a sig block of a singleton
+  # method, it has the net effect of unwrapping/redefining the method. If
+  # we try to use Mocktail.replace(Foo) and Foo.bar has a Sorbet sig block,
+  # then we'll end up with three "versions" of the same method and no way
+  # to keep straight which one == which:
+  #  A - Foo.bar, as defined in the original class
+  #  B - Foo.bar, as redefined by RedefinesSingletonMethods
+  #  C - Foo.bar, as wrapped by sorbet-runtime
+  # Initially, Foo.method(:bar) would == C, but after the type
+  # replacement, it would == B (with a reference back to C as the original),
+  # but after handling a single dry call, our invocation of
+  # GrabsOriginalMethodParameters.grab(Foo.method(:bar)) would invoke the
+  # Sorbet `sig` block, which has the net effect of redefining the method back
+  # to A.
   sig { params(type: T.any(::Module, T::Class[T.anything])).void }
   def run(type); end
 end
@@ -1498,6 +1544,7 @@ class Mocktail::Signature < ::T::Struct
   const :block_arg, T.nilable(::Proc), default: T.unsafe(nil)
 
   class << self
+    # source://sorbet-runtime/0.5.11971/lib/types/struct.rb#13
     # source://sorbet-runtime/0.5.10983/lib/types/struct.rb#13
     def inherited(s); end
   end
@@ -1543,30 +1590,37 @@ class Mocktail::StringifiesCall
 
   private
 
+  # source://mocktail//lib/mocktail/sorbet/mocktail/share/stringifies_call.rb#46
   # source://mocktail//lib/mocktail/sorbet/mocktail/share/stringifies_call.rb#47
   sig { params(args: T::Array[::Object]).returns(T.nilable(::String)) }
   def argify(args); end
 
+  # source://mocktail//lib/mocktail/sorbet/mocktail/share/stringifies_call.rb#29
   # source://mocktail//lib/mocktail/sorbet/mocktail/share/stringifies_call.rb#30
   sig { params(call: ::Mocktail::Call, parens: T::Boolean).returns(T.nilable(::String)) }
   def args_to_s(call, parens: T.unsafe(nil)); end
 
+  # source://mocktail//lib/mocktail/sorbet/mocktail/share/stringifies_call.rb#64
   # source://mocktail//lib/mocktail/sorbet/mocktail/share/stringifies_call.rb#65
   sig { params(block: T.nilable(::Proc), anonymous: T::Boolean).returns(T.nilable(::String)) }
   def blockify(block, anonymous:); end
 
+  # source://mocktail//lib/mocktail/sorbet/mocktail/share/stringifies_call.rb#52
   # source://mocktail//lib/mocktail/sorbet/mocktail/share/stringifies_call.rb#53
   sig { params(kwargs: T::Hash[::Symbol, ::Object]).returns(T.nilable(::String)) }
   def kwargify(kwargs); end
 
+  # source://mocktail//lib/mocktail/sorbet/mocktail/share/stringifies_call.rb#58
   # source://mocktail//lib/mocktail/sorbet/mocktail/share/stringifies_call.rb#59
   sig { params(block: T.nilable(::Proc)).returns(T.nilable(::String)) }
   def lambdafy(block); end
 
+  # source://mocktail//lib/mocktail/sorbet/mocktail/share/stringifies_call.rb#75
   # source://mocktail//lib/mocktail/sorbet/mocktail/share/stringifies_call.rb#76
   sig { params(block: ::Proc).returns(::String) }
   def source_locationify(block); end
 
+  # source://mocktail//lib/mocktail/sorbet/mocktail/share/stringifies_call.rb#80
   # source://mocktail//lib/mocktail/sorbet/mocktail/share/stringifies_call.rb#81
   sig { params(path: ::String).returns(::String) }
   def strip_pwd(path); end
@@ -1621,6 +1675,7 @@ class Mocktail::Stubbing < ::T::Struct
   def with(&block); end
 
   class << self
+    # source://sorbet-runtime/0.5.11971/lib/types/struct.rb#13
     # source://sorbet-runtime/0.5.10983/lib/types/struct.rb#13
     def inherited(s); end
   end
@@ -1722,6 +1777,7 @@ class Mocktail::TypeReplacement < ::T::Struct
   prop :replacement_new, T.nilable(::Method)
 
   class << self
+    # source://sorbet-runtime/0.5.11971/lib/types/struct.rb#13
     # source://sorbet-runtime/0.5.10983/lib/types/struct.rb#13
     def inherited(s); end
   end
@@ -1741,6 +1797,7 @@ class Mocktail::TypeReplacementData < ::T::Struct
   def double; end
 
   class << self
+    # source://sorbet-runtime/0.5.11971/lib/types/struct.rb#13
     # source://sorbet-runtime/0.5.10983/lib/types/struct.rb#13
     def inherited(s); end
   end
@@ -1756,6 +1813,7 @@ class Mocktail::UnsatisfyingCall < ::T::Struct
   const :backtrace, T::Array[::String]
 
   class << self
+    # source://sorbet-runtime/0.5.11971/lib/types/struct.rb#13
     # source://sorbet-runtime/0.5.10983/lib/types/struct.rb#13
     def inherited(s); end
   end

data/script/build

@@ -0,0 +1,47 @@
+#!/usr/bin/env bash
+
+set -xeuo pipefail
+
+echo "-----> Deleting lib/ and copying src/ to lib/"
+rm -rf lib
+cp -r src/ lib
+
+echo "-----> Erasing sorbet sigs from lib/ (for non-Sorbet users)"
+bundle exec sorbet-eraser "lib/**/*.rb"
+echo "-----> Overwriting Mocktail::TYPED constant for lib/"
+cat << RUBY > lib/mocktail/typed.rb
+module Mocktail
+  TYPED = false
+end
+RUBY
+
+echo "-----> Erasing sorbet 'typed: ' sigils from lib/mocktail"
+./script/strip_sigils
+
+echo "-----> Copying src/ to lib/mocktail/sorbet/ (for Sorbet users)"
+cp -r src/ lib/mocktail/sorbet
+
+echo "-----> Running Standard against all code"
+bundle exec rake standard:fix
+
+echo "-----> Generating RBIs to publish with the gems"
+
+echo "----------> ❶ Faking out mocktail.rb and pointing it to mocktail/sorbet"
+mv lib/mocktail.rb lib/mocktail.rb.nope
+cat << RUBY > lib/mocktail.rb
+require_relative "mocktail/sorbet"
+RUBY
+
+echo "----------> ❷ Generating sorbet sigs via tapioca in sub_projects/rbi_generator"
+cd sub_projects/rbi_generator
+rm -f rbi/mocktail-pregenerated.rbi
+rm -f sorbet/rbi/gems/mocktail@*.rbi
+bundle
+bundle exec tapioca gem --all --exclude=tapioca ast diff-lcs erubi netrc parser prettier_print racc rbi spoom syntax_tree thor unparser sorbet yard parallel yard-sorbet
+cd ../..
+
+echo "----------> ❸ Moving the generated RBI to rbi/mocktail-pregenerated.rbi"
+cp sub_projects/rbi_generator/sorbet/rbi/gems/mocktail@*.rbi rbi/mocktail-pregenerated.rbi
+mv lib/mocktail.rb.nope lib/mocktail.rb
+
+

data/script/setup

@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+
+set -xeuo pipefail
+
+bundle
+
+cd sub_projects/rbi_generator/
+bundle
+cd ../..
+
+cd sub_projects/sorbet_user/
+bundle
+cd ../..
+
+cd sub_projects/untyped_user/
+bundle
+cd ../..

data/script/spoom_me

@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+
+set -xeuo pipefail
+
+bundle exec spoom coverage --save
+bundle exec spoom coverage report
+bundle exec spoom coverage open

data/script/strip_sigils

@@ -0,0 +1,17 @@
+#!/bin/bash
+
+# Removes all the sigil comments from the top of our sorbet-free code
+
+# Find all files that start with "# typed" in the first line
+files=$(grep -rl '^# typed' --exclude-dir=lib/mocktail/sorbet lib/*)
+
+# Loop through each file and delete the first line
+for file in $files
+do
+    # Check if we're on a Mac
+    if [[ "$OSTYPE" == "darwin"* ]]; then
+        sed -i '' '1d' $file
+    else
+        sed -i '1d' $file
+    fi
+done

data/script/test

@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+
+set -xeuo pipefail
+
+echo "-----> Running Mocktail's test against src"
+COVER=true bundle exec rake
+
+echo "-----> Type-checking Mocktail source"
+bundle exec srb tc
+
+echo "-----> Building src/mocktail into lib/mocktail and lib/mocktail/sorbet"
+./script/build
+
+echo "-----> Running Mocktail's test against lib"
+MOCKTAIL_TEST_SRC_DIRECTORY="lib" bundle exec rake
+
+echo "-----> Running Mocktail's test against lib/mocktail/sorbet"
+MOCKTAIL_TEST_SRC_DIRECTORY="lib/mocktail/sorbet" bundle exec rake
+
+echo "-----> Ensuring that double-requiring Mocktail produces the right warning and bails out of redefining constants"
+script/test_double_require_warnings
+
+echo "-----> Type-checking the copy of Mocktail in lib/mocktail/sorbet"
+bundle exec srb tc --ignore src/ --dir lib/mocktail/sorbet
+
+echo "-----> Running sample project tests"
+cd sub_projects/sorbet_user
+./script/test
+cd ../..
+
+cd sub_projects/untyped_user
+./script/test
+cd ../..

data/script/test_double_require_warnings

@@ -0,0 +1,46 @@
+#!/usr/bin/env ruby
+
+require "open3"
+
+def assert_warning(command:, warning:)
+  stdout, stderr, status = Open3.capture3(command)
+  # Ignore incidental Ruby/RubyGems/Bundler runtime warnings (e.g. from a
+  # Ruby version shipping a newer RubyGems than an older pinned Bundler
+  # expects) -- they always follow Ruby's "path:line: warning: message"
+  # format, unlike Mocktail's own warning below.
+  relevant_stderr = stderr.lines.reject { |line| line.match?(/\A\S+:\d+: warning: /) }.join
+  if relevant_stderr != warning
+    fail <<~MSG
+      Expected the correct error message on STDERR but it was wrong"
+
+      Expected:
+      #{warning}
+
+      Actual:
+      #{stderr}
+    MSG
+
+  end
+  fail "Expected empty STDOUT, but was #{stdout.inspect}" unless stdout.empty?
+  fail "Expected command to exit 0, but was #{status.exitstatus}" unless status.success?
+end
+
+puts "Test requiring 'mocktail' and then 'mocktail/sorbet' gives the right warning"
+assert_warning(
+  command: <<~CMD,
+    bundle exec ruby -e 'require "#{Dir.pwd}/lib/mocktail/sorbet"; require "#{Dir.pwd}/lib/mocktail"'
+  CMD
+  warning: <<~WARN
+    `require "mocktail"' was called, but Mocktail was already required as `require "mocktail/sorbet"', so we're NOT going to load it to avoid constants from being redefined. If you want to use Mocktail WITHOUT sorbet runtime checks, remove whatever is requiring `mocktail/sorbet'.
+  WARN
+)
+
+puts "Test requiring 'mocktail/sorbet' and then 'mocktail' gives the right warning"
+assert_warning(
+  command: <<~CMD,
+    bundle exec ruby -e 'require "#{Dir.pwd}/lib/mocktail"; require "#{Dir.pwd}/lib/mocktail/sorbet"'
+  CMD
+  warning: <<~WARN
+    `require "mocktail/sorbet"' was called, but Mocktail was already required as `require "mocktail"', so we're NOT going to load it to avoid constants from being redefined. If you want to use Mocktail WITH sorbet runtime checks, remove whatever is requiring `mocktail'.
+  WARN
+)

data/script/update

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+
+set -xeuo pipefail
+
+echo "-----> Updating root gems"
+bundle update
+
+echo "-----> Updating 'sub_projects/rbi_generator' gems"
+cd sub_projects/rbi_generator
+bundle update
+cd ../..
+
+echo "-----> Updating 'sub_projects/sorbet_user' gems"
+cd sub_projects/sorbet_user
+bundle update
+cd ../..
+
+echo "-----> Updating 'sub_projects/untyped_user' gems"
+cd sub_projects/untyped_user
+bundle update
+cd ../..

data/sorbet/config

@@ -0,0 +1,12 @@
+--dir
+.
+--ignore=tmp/
+--ignore=Rakefile
+--ignore=vendor/
+--ignore=sub_projects/sorbet_user/
+--ignore=sub_projects/rbi_generator/
+--ignore=lib/
+# Ignore b/c these stubs will confuse the typechecker and generate a bunch of errors, even tho #typed: false
+--ignore=test/support/sorbet_stubs.rb
+# Ignore b/c this pregenerated rbi is for consumers of the gem, not the gem itself
+--ignore=rbi/mocktail-pregenerated.rbi