Merge pull request #110 from kaste/stub-order

Author: kaste

mockito/invocation.py

@@ -24,6 +24,7 @@
 import inspect
 import operator
 from collections import deque
+from functools import cached_property
 from typing import TYPE_CHECKING
 
 from . import matchers, signature
@@ -114,12 +115,11 @@ def __call__(self, *params: Any, **named_params: Any) -> Any | None:
         self._remember_params(params_without_first_arg, named_params)
         self.mock.remember(self)
 
-        for matching_invocation in self.mock.stubbed_invocations:
-            if matching_invocation.matches(self):
-                matching_invocation.should_answer(self)
-                matching_invocation.capture_arguments(self)
-                return matching_invocation.answer_first(
-                    *params, **named_params)
+        matching_invocation = self._find_best_matching_stubbed_invocation()
+        if matching_invocation is not None:
+            matching_invocation.should_answer(self)
+            matching_invocation.capture_arguments(self)
+            return matching_invocation.answer_first(*params, **named_params)
 
         if self.strict:
             stubbed_invocations = [
@@ -148,6 +148,21 @@ def __call__(self, *params: Any, **named_params: Any) -> Any | None:
 
         return None
 
+    def _find_best_matching_stubbed_invocation(self) -> StubbedInvocation | None:
+        candidates = [
+            candidate
+            for candidate in self.mock.stubbed_invocations
+            if candidate.matches(self)
+        ]
+
+        if not candidates:
+            return None
+
+        if len(candidates) == 1:
+            return candidates[0]
+
+        return max(candidates, key=lambda candidate: candidate.specificity_score)
+
 
 class RememberedPropertyAccess(RememberedInvocation):
     def ensure_mocked_object_has_method(self, method_name):
@@ -478,6 +493,33 @@ def __call__(self, *params: Any, **named_params: Any) -> AnswerSelector:
         self.mock.finish_stubbing(self)
         return AnswerSelector(self, self.refers_coroutine, self.discard_first_arg)
 
+    @cached_property
+    def specificity_score(self) -> tuple[int, int]:
+        quality = 0
+
+        for value in self.params:
+            if value is not matchers.ARGS_SENTINEL:
+                quality += self._specificity_score(value)
+
+        for key, value in self.named_params.items():
+            if key is not matchers.KWARGS_SENTINEL:
+                quality += self._specificity_score(value)
+
+        coverage = len(self.params) + len(self.named_params)
+        return coverage, quality
+
+    def _specificity_score(self, value: object) -> int:
+        if value is Ellipsis:
+            return 0
+
+        if isinstance(value, matchers.Any) and value.wanted_type is None:
+            return 0
+
+        if isinstance(value, matchers.Matcher):
+            return 1
+
+        return 3
+
     def forget_self(self) -> None:
         if self in self.mock.stubbed_invocations:
             self.mock.forget_stubbed_invocation(self)

tests/stub_specificity_test.py

@@ -0,0 +1,88 @@
+import pytest
+
+from mockito import any, args, kwargs, mock, when
+
+
+pytestmark = pytest.mark.usefixtures("unstub")
+
+
+class _Path:
+    def exists(self, location):
+        return f"orig:{location}"
+
+
+def test_literal_stub_beats_ellipsis_even_if_ellipsis_added_last():
+    path = mock(_Path)
+
+    when(path).exists(".flake8").thenReturn("stubbed")
+    when(path).exists(...).thenCallOriginalImplementation()
+
+    assert path.exists(".flake8") == "stubbed"
+    assert path.exists("README.rst") == "orig:README.rst"
+
+
+def test_literal_stub_beats_ellipsis_even_if_literal_added_last():
+    path = mock(_Path)
+
+    when(path).exists(...).thenCallOriginalImplementation()
+    when(path).exists(".flake8").thenReturn("stubbed")
+
+    assert path.exists(".flake8") == "stubbed"
+    assert path.exists("README.rst") == "orig:README.rst"
+
+
+def test_typed_any_is_more_specific_than_any_and_ellipsis():
+    path = mock()
+
+    when(path).exists(...).thenReturn("ellipsis")
+    when(path).exists(any()).thenReturn("any")
+    when(path).exists(any(str)).thenReturn("typed-any")
+
+    assert path.exists(".flake8") == "typed-any"
+    assert path.exists(1) == "any"
+
+
+def test_any_and_ellipsis_have_same_specificity_and_keep_last_wins_tie_break():
+    path = mock()
+
+    when(path).exists(any()).thenReturn("any")
+    when(path).exists(...).thenReturn("ellipsis")
+    assert path.exists(1) == "ellipsis"
+
+    other = mock()
+    when(other).exists(...).thenReturn("ellipsis")
+    when(other).exists(any()).thenReturn("any")
+    assert other.exists(1) == "any"
+
+
+def test_coverage_beats_quality_when_both_match():
+    subject = mock()
+
+    when(subject).f("x", ...).thenReturn("prefix")
+    when(subject).f(..., retry=..., headers=...).thenReturn("kwargs-shape")
+
+    assert subject.f("x", retry=5, headers={}) == "kwargs-shape"
+
+
+def test_literal_beats_matchers_when_coverage_is_equal():
+    subject = mock()
+
+    when(subject).f("x", ...).thenReturn("prefix-fallback")
+    when(subject).f(any(str), any(int)).thenReturn("typed-exact")
+
+    assert subject.f("x", 1) == "prefix-fallback"
+
+
+def test_args_and_kwargs_sentinels_have_same_weight_as_ellipsis():
+    subject = mock()
+
+    when(subject).f(...).thenReturn("ellipsis")
+    when(subject).f(*args).thenReturn("args")
+
+    assert subject.f(1) == "args"
+
+    other = mock()
+    when(other).g(...).thenReturn("ellipsis")
+    when(other).g(**kwargs).thenReturn("kwargs")
+
+    assert other.g(retry=1) == "kwargs"