Extract and strengthen signature-compatibility logic

Move continuation signature-compatibility checks into a dedicated
mockito.sameish subsystem and make Mock delegate to it.

The new logic compares signatures structurally (including matcher
internals) instead of calling matcher .matches() across stub signatures.
This avoids executing user arg_that predicates during bookkeeping and
prevents side effects/crashes from predicate evaluation against matcher
objects.

Add focused unit coverage in tests/sameish_test.py.

Add chaining regressions that assert branch sharing for equivalent
any_(int) signatures and reused arg_that predicates.  These were the
original fatal regressions that motivated the effort.

Author: kaste

mockito/mocking.py

@@ -28,7 +28,7 @@
 from dataclasses import dataclass
 from typing import Any, AsyncIterator, Callable, Iterable, Iterator, cast
 
-from . import invocation, signature, utils
+from . import invocation, sameish, signature, utils
 from . import verification as verificationModule
 from .mock_registry import mock_registry
 from .patching import Patch, patcher
@@ -407,12 +407,12 @@ def set_continuation(self, continuation: invocation.ConfiguredContinuation) -> N
     def _sameish_invocations(
         self, same: invocation.StubbedInvocation
     ) -> list[invocation.StubbedInvocation]:
-        """Find prior stubs that are *mutually* signature-compatible.
+        """Find prior stubs that are signature-compatible.
 
         This is used only for continuation bookkeeping (value-vs-chain mode),
-        not for runtime call dispatch. We intentionally do a symmetric check
-        (`a.matches(b)` and `b.matches(a)`) to approximate "same signature"
-        despite one-way matchers like `any()`.
+        not for runtime call dispatch. The comparison is structural and avoids
+        executing matcher predicates, so `arg_that(...)` and other custom
+        matchers cannot crash internal equivalence probing.
 
         Why this exists: repeated selectors such as
 
@@ -439,13 +439,7 @@ def _invocations_are_sameish(
         left: invocation.StubbedInvocation,
         right: invocation.StubbedInvocation,
     ) -> bool:
-        # Be conservative in internal equivalence probing: user predicates from
-        # `arg_that` can throw when evaluated against matcher/sentinel objects.
-        # In this phase, exceptions should mean "not equivalent", not failure.
-        try:
-            return left.matches(right) and right.matches(left)
-        except Exception:
-            return False
+        return sameish.invocations_are_sameish(left, right)
 
     def get_original_method(self, method_name: str) -> object | None:
         return self._original_methods.get(method_name, None)

mockito/sameish.py

@@ -0,0 +1,128 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from . import matchers
+
+if TYPE_CHECKING:
+    from .invocation import StubbedInvocation
+
+
+def invocations_are_sameish(
+    left: StubbedInvocation,
+    right: StubbedInvocation,
+) -> bool:
+    """Structural signature-compatibility checks for continuation bookkeeping.
+
+    Intentionally avoids executing user-provided matcher predicates
+    (e.g. `arg_that(...)) while comparing stub signatures.
+    """
+
+    return (
+        _params_are_sameish(left.params, right.params)
+        and _named_params_are_sameish(
+            left.named_params,
+            right.named_params,
+        )
+    )
+
+
+def _params_are_sameish(left: tuple, right: tuple) -> bool:
+    if len(left) != len(right):
+        return False
+
+    return all(
+        _values_are_sameish(left_value, right_value)
+        for left_value, right_value in zip(left, right)
+    )
+
+
+def _named_params_are_sameish(left: dict, right: dict) -> bool:
+    if set(left) != set(right):
+        return False
+
+    return all(
+        _values_are_sameish(left[key], right[key])
+        for key in left
+    )
+
+
+def _values_are_sameish(left: object, right: object) -> bool:
+    if left is right:
+        return True
+
+    if left is Ellipsis or right is Ellipsis:
+        return left is right
+
+    if isinstance(left, matchers.Matcher) and isinstance(right, matchers.Matcher):
+        return _matchers_are_sameish(left, right)
+
+    if isinstance(left, matchers.Matcher) or isinstance(right, matchers.Matcher):
+        return False
+
+    return _equals_or_identity(left, right)
+
+
+def _matchers_are_sameish(  # noqa: C901
+    left: matchers.Matcher,
+    right: matchers.Matcher,
+) -> bool:
+    if left is right:
+        return True
+
+    if type(left) is not type(right):
+        return False
+
+    if isinstance(left, matchers.Any) and isinstance(right, matchers.Any):
+        return _equals_or_identity(left.wanted_type, right.wanted_type)
+
+    if (
+        isinstance(left, matchers.ValueMatcher)
+        and isinstance(right, matchers.ValueMatcher)
+    ):
+        return _values_are_sameish(left.value, right.value)
+
+    if (
+        isinstance(left, (matchers.And, matchers.Or))
+        and isinstance(right, (matchers.And, matchers.Or))
+    ):
+        return _params_are_sameish(
+            tuple(left.matchers),
+            tuple(right.matchers),
+        )
+
+    if isinstance(left, matchers.Not) and isinstance(right, matchers.Not):
+        return _values_are_sameish(left.matcher, right.matcher)
+
+    if isinstance(left, matchers.ArgThat) and isinstance(right, matchers.ArgThat):
+        return left.predicate is right.predicate
+
+    if isinstance(left, matchers.Contains) and isinstance(right, matchers.Contains):
+        return _values_are_sameish(left.sub, right.sub)
+
+    if isinstance(left, matchers.Matches) and isinstance(right, matchers.Matches):
+        return (
+            left.regex.pattern == right.regex.pattern
+            and left.flags == right.flags
+        )
+
+    if (
+        isinstance(left, matchers.ArgumentCaptor)
+        and isinstance(right, matchers.ArgumentCaptor)
+    ):
+        return _values_are_sameish(left.matcher, right.matcher)
+
+    if (
+        isinstance(left, matchers.CallCaptor)
+        and isinstance(right, matchers.CallCaptor)
+    ):
+        return False
+
+    return _equals_or_identity(left, right)
+
+
+def _equals_or_identity(left: object, right: object) -> bool:
+    try:
+        return left == right
+    except Exception:
+        return left is right

tests/chaining_test.py

@@ -37,6 +37,29 @@ def test_multiple_chain_branches_on_same_root_are_supported():
     assert cat_that_meowed.roll() == "playful"
 
 
+def test_multiple_chain_branches_with_equivalent_typed_any_matchers_share_root():
+    cat = mock()
+
+    when(cat).meow(any_(int)).purr().thenReturn("friendly")
+    when(cat).meow(any_(int)).roll().thenReturn("playful")
+
+    cat_that_meowed = cat.meow(1)
+    assert cat_that_meowed.purr() == "friendly"
+    assert cat_that_meowed.roll() == "playful"
+
+
+def test_multiple_chain_branches_with_same_arg_that_matcher_share_root():
+    cat = mock()
+    pred = arg_that(lambda value: value > 0)
+
+    when(cat).meow(pred).purr().thenReturn("friendly")
+    when(cat).meow(pred).roll().thenReturn("playful")
+
+    cat_that_meowed = cat.meow(1)
+    assert cat_that_meowed.purr() == "friendly"
+    assert cat_that_meowed.roll() == "playful"
+
+
 def test_unstub_child_chain_then_reconfigure_does_not_leave_stale_root_stub():
     cat = mock()
 

tests/sameish_test.py

@@ -0,0 +1,140 @@
+from dataclasses import dataclass, field
+
+from mockito import and_, any as any_, arg_that, call_captor, eq, gt, neq, or_
+from mockito import sameish
+
+
+@dataclass
+class FakeInvocation:
+    params: tuple = ()
+    named_params: dict = field(default_factory=dict)
+
+
+def bar(*params, **named_params):
+    return FakeInvocation(params=params, named_params=named_params)
+
+
+def test_concrete_values_must_match_exactly():
+    assert sameish.invocations_are_sameish(
+        bar(1, "x"),
+        bar(1, "x"),
+    )
+    assert not sameish.invocations_are_sameish(
+        bar(1, "x"),
+        bar(2, "x"),
+    )
+
+
+def test_keyword_names_must_match_independent_of_order():
+    assert sameish.invocations_are_sameish(
+        bar(a=1, b=2),
+        bar(b=2, a=1),
+    )
+    assert not sameish.invocations_are_sameish(
+        bar(a=1),
+        bar(a=1, b=2),
+    )
+
+
+def test_any_matchers_are_compared_structurally():
+    assert sameish.invocations_are_sameish(
+        bar(any_(int)),
+        bar(any_(int)),
+    )
+    assert not sameish.invocations_are_sameish(
+        bar(any_(int)),
+        bar(any_()),
+    )
+    assert not sameish.invocations_are_sameish(
+        bar(any_()),
+        bar(1),
+    )
+
+
+def test_composite_matchers_are_compared_recursively():
+    assert sameish.invocations_are_sameish(
+        bar(and_(any_(int), gt(1))),
+        bar(and_(any_(int), gt(1))),
+    )
+    assert not sameish.invocations_are_sameish(
+        bar(and_(any_(int), gt(1))),
+        bar(and_(any_(int), gt(2))),
+    )
+
+
+def test_distinct_matcher_types_are_not_sameish_even_with_equal_payload():
+    assert not sameish.invocations_are_sameish(
+        bar(eq(1)),
+        bar(neq(1)),
+    )
+    assert not sameish.invocations_are_sameish(
+        bar(and_(any_(int), gt(1))),
+        bar(or_(any_(int), gt(1))),
+    )
+
+
+def test_arg_that_uses_predicate_identity_and_does_not_execute_predicate():
+    calls = []
+
+    def predicate(value):
+        calls.append(value)
+        raise RuntimeError("must not be executed")
+
+    assert sameish.invocations_are_sameish(
+        bar(arg_that(predicate)),
+        bar(arg_that(predicate)),
+    )
+    assert calls == []
+
+
+def test_arg_that_with_different_predicates_is_not_sameish():
+    assert not sameish.invocations_are_sameish(
+        bar(arg_that(lambda value: value > 0)),
+        bar(arg_that(lambda value: value > 0)),
+    )
+
+
+def test_arg_that_predicate_side_effects_are_not_triggered():
+    seen = []
+
+    def predicate(value):
+        seen.append(value)
+        return True
+
+    assert sameish.invocations_are_sameish(
+        bar(arg_that(predicate)),
+        bar(arg_that(predicate)),
+    )
+    assert seen == []
+
+
+def test_call_captor_instances_are_not_interchangeable():
+    left = call_captor()
+    right = call_captor()
+
+    assert sameish.invocations_are_sameish(
+        bar(left),
+        bar(left),
+    )
+    assert not sameish.invocations_are_sameish(
+        bar(left),
+        bar(right),
+    )
+
+
+def test_eq_failures_fallback_to_identity():
+    class EqBoom:
+        def __eq__(self, other):
+            raise RuntimeError("boom")
+
+    first = EqBoom()
+    second = EqBoom()
+
+    assert sameish.invocations_are_sameish(
+        bar(first),
+        bar(first),
+    )
+    assert not sameish.invocations_are_sameish(
+        bar(first),
+        bar(second),
+    )