Fail fast on captor identity clashes across chain root branches

When a chain branch resolves to an existing sameish root but binds
different captor instances, stubbing now raises an InvocationError with
guidance to reuse the same captor object. This avoids silent branch
shadowing where one leaf becomes unreachable while still preserving
strict behavior.

Tests were expanded to cover sameish semantics for typed and untyped
captor wrappers, as well as rejection of distinct typed
*captor(any_(int)) chain roots.

Author: kaste

mockito/invocation.py

@@ -27,7 +27,7 @@
 from collections import deque
 from typing import TYPE_CHECKING, Union
 
-from . import matchers, signature
+from . import matchers, sameish, signature
 from . import verification as verificationModule
 from .mock_registry import mock_registry
 from .utils import contains_strict
@@ -628,6 +628,21 @@ def transition_to_chain(self) -> ChainContinuation:
         continuation = self.get_continuation()
 
         if isinstance(continuation, ChainContinuation):
+            if (
+                continuation.invocation is not self
+                and sameish.invocations_have_distinct_captors(
+                    self,
+                    continuation.invocation,
+                )
+            ):
+                self.forget_self()
+                raise InvocationError(
+                    "'%s' is already configured with a different captor "
+                    "instance for the same selector. Reuse the same "
+                    "captor() / call_captor() object across chain branches."
+                    % self.method_name
+                )
+
             self.rollback_if_not_configured_by(continuation)
             return continuation
 

mockito/sameish.py

@@ -27,6 +27,26 @@ def invocations_are_sameish(
     )
 
 
+def invocations_have_distinct_captors(
+    left: StubbedInvocation,
+    right: StubbedInvocation,
+) -> bool:
+    """Return True when equivalent selectors bind different captor instances."""
+
+    for left_value, right_value in zip(left.params, right.params):
+        if _values_bind_distinct_captors(left_value, right_value):
+            return True
+
+    for key in set(left.named_params) & set(right.named_params):
+        if _values_bind_distinct_captors(
+            left.named_params[key],
+            right.named_params[key],
+        ):
+            return True
+
+    return False
+
+
 def _params_are_sameish(left: tuple, right: tuple) -> bool:
     if len(left) != len(right):
         return False
@@ -141,6 +161,33 @@ def _matchers_are_sameish(  # noqa: C901
     return _equals_or_identity(left, right)
 
 
+def _values_bind_distinct_captors(left: object, right: object) -> bool:
+    left_binding = _captor_binding(left)
+    right_binding = _captor_binding(right)
+
+    return (
+        left_binding is not None
+        and right_binding is not None
+        and left_binding is not right_binding
+    )
+
+
+def _captor_binding(value: object) -> object | None:
+    if matchers.is_call_captor(value):
+        return value
+
+    if isinstance(value, matchers.ArgumentCaptor):
+        return value
+
+    if matchers.is_captor_args_sentinel(value):
+        return value.captor
+
+    if matchers.is_captor_kwargs_sentinel(value):
+        return value.captor
+
+    return None
+
+
 def _equals_or_identity(left: object, right: object) -> bool:
     try:
         return left == right

tests/chaining_test.py

@@ -60,37 +60,76 @@ def test_multiple_chain_branches_with_same_arg_that_matcher_share_root():
     assert cat_that_meowed.roll() == "playful"
 
 
-def test_multiple_chain_branches_with_call_captor_roots_share_root():
+def test_multiple_chain_branches_with_same_call_captor_instance_share_root():
     cat = mock()
+    call = call_captor()
 
-    when(cat).meow(call_captor()).purr().thenReturn("friendly")
-    when(cat).meow(call_captor()).roll().thenReturn("playful")
+    when(cat).meow(call).purr().thenReturn("friendly")
+    when(cat).meow(call).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_args_captor_roots_share_root():
+def test_multiple_chain_branches_with_distinct_call_captor_roots_are_rejected():
+    cat = mock()
+
+    when(cat).meow(call_captor()).purr().thenReturn("friendly")
+
+    with pytest.raises(InvocationError) as exc:
+        when(cat).meow(call_captor()).roll().thenReturn("playful")
+
+    assert str(exc.value) == (
+        "'meow' is already configured with a different captor instance for "
+        "the same selector. Reuse the same captor() / call_captor() object "
+        "across chain branches."
+    )
+
+
+def test_multiple_chain_branches_with_distinct_args_captor_roots_are_rejected():
     cat = mock()
 
     when(cat).meow(*captor()).purr().thenReturn("friendly")
-    when(cat).meow(*captor()).roll().thenReturn("playful")
 
-    cat_that_meowed = cat.meow(1, 2)
-    assert cat_that_meowed.purr() == "friendly"
-    assert cat_that_meowed.roll() == "playful"
+    with pytest.raises(InvocationError) as exc:
+        when(cat).meow(*captor()).roll().thenReturn("playful")
+
+    assert str(exc.value) == (
+        "'meow' is already configured with a different captor instance for "
+        "the same selector. Reuse the same captor() / call_captor() object "
+        "across chain branches."
+    )
 
 
-def test_multiple_chain_branches_with_kwargs_captor_roots_share_root():
+def test_multiple_chain_branches_with_distinct_kwargs_captor_roots_are_rejected():
     cat = mock()
 
     when(cat).meow(**captor()).purr().thenReturn("friendly")
-    when(cat).meow(**captor()).roll().thenReturn("playful")
 
-    cat_that_meowed = cat.meow(volume=1)
-    assert cat_that_meowed.purr() == "friendly"
-    assert cat_that_meowed.roll() == "playful"
+    with pytest.raises(InvocationError) as exc:
+        when(cat).meow(**captor()).roll().thenReturn("playful")
+
+    assert str(exc.value) == (
+        "'meow' is already configured with a different captor instance for "
+        "the same selector. Reuse the same captor() / call_captor() object "
+        "across chain branches."
+    )
+
+
+def test_multiple_chain_branches_with_distinct_typed_args_captor_roots_are_rejected():
+    cat = mock()
+
+    when(cat).meow(*captor(any_(int))).purr().thenReturn("friendly")
+
+    with pytest.raises(InvocationError) as exc:
+        when(cat).meow(*captor(any_(int))).roll().thenReturn("playful")
+
+    assert str(exc.value) == (
+        "'meow' is already configured with a different captor instance for "
+        "the same selector. Reuse the same captor() / call_captor() object "
+        "across chain branches."
+    )
 
 
 def test_unstub_child_chain_then_reconfigure_does_not_leave_stale_root_stub():

tests/sameish_test.py

@@ -164,6 +164,34 @@ def test_kwargs_argument_captor_instances_are_sameish_for_root_deduping():
     )
 
 
+def test_star_argument_captors_with_different_matchers_are_not_sameish():
+    assert not sameish.invocations_are_sameish(
+        bar(1, *captor(any_(int))),
+        bar(1, *captor(any_(str))),
+    )
+
+
+def test_kwargs_argument_captors_with_different_matchers_are_not_sameish():
+    assert not sameish.invocations_are_sameish(
+        bar(1, **captor(any_(int))),
+        bar(1, **captor(any_(str))),
+    )
+
+
+def test_star_argument_captor_any_and_typed_any_are_not_sameish():
+    assert not sameish.invocations_are_sameish(
+        bar(1, *captor()),
+        bar(1, *captor(any_(int))),
+    )
+
+
+def test_kwargs_argument_captor_any_and_typed_any_are_not_sameish():
+    assert not sameish.invocations_are_sameish(
+        bar(1, **captor()),
+        bar(1, **captor(any_(int))),
+    )
+
+
 def test_argument_captor_instances_with_different_matchers_are_not_sameish():
     assert not sameish.invocations_are_sameish(
         bar(captor(any_(int))),