feat: all extra arguments to be ignored (#61)

Closes #60

Author: mcous

decoy/__init__.py

@@ -87,16 +87,24 @@ def create_decoy_func(
         spy = self._core.mock(spec=spec, is_async=is_async)
         return cast(FuncT, spy)
 
-    def when(self, _rehearsal_result: ReturnT) -> "Stub[ReturnT]":
+    def when(
+        self,
+        _rehearsal_result: ReturnT,
+        *,
+        ignore_extra_args: bool = False,
+    ) -> "Stub[ReturnT]":
         """Create a [Stub][decoy.Stub] configuration using a rehearsal call.
 
         See [stubbing usage guide](../usage/when/) for more details.
 
         Arguments:
             _rehearsal_result: The return value of a rehearsal, used for typechecking.
+            ignore_extra_args: Allow the rehearsal to specify fewer arguments than
+                the actual call. Decoy will compare and match any given arguments,
+                ignoring unspecified arguments.
 
         Returns:
-            A stub to configure using `then_return` or `then_raise`.
+            A stub to configure using `then_return`, `then_raise`, or `then_do`.
 
         Example:
             ```python
@@ -110,10 +118,18 @@ def when(self, _rehearsal_result: ReturnT) -> "Stub[ReturnT]":
             is a rehearsal for stub configuration purposes rather than a call
             from the code-under-test.
         """
-        stub_core = self._core.when(_rehearsal_result)
+        stub_core = self._core.when(
+            _rehearsal_result,
+            ignore_extra_args=ignore_extra_args,
+        )
         return Stub(core=stub_core)
 
-    def verify(self, *_rehearsal_results: Any, times: Optional[int] = None) -> None:
+    def verify(
+        self,
+        *_rehearsal_results: Any,
+        times: Optional[int] = None,
+        ignore_extra_args: bool = False,
+    ) -> None:
         """Verify a decoy was called using one or more rehearsals.
 
         See [verification usage guide](../usage/verify/) for more details.
@@ -125,6 +141,9 @@ def verify(self, *_rehearsal_results: Any, times: Optional[int] = None) -> None:
                 the call count must match exactly, otherwise the call must appear
                 at least once. The `times` argument must be used with exactly one
                 rehearsal.
+            ignore_extra_args: Allow the rehearsal to specify fewer arguments than
+                the actual call. Decoy will compare and match any given arguments,
+                ignoring unspecified arguments.
 
         Example:
             ```python
@@ -142,7 +161,11 @@ def test_create_something(decoy: Decoy):
             API sugar. Decoy will pop the last call(s) to _any_ fake off its
             call stack, which will end up being the call inside `verify`.
         """
-        self._core.verify(*_rehearsal_results, times=times)
+        self._core.verify(
+            *_rehearsal_results,
+            times=times,
+            ignore_extra_args=ignore_extra_args,
+        )
 
     def reset(self) -> None:
         """Reset all decoy state.

decoy/call_stack.py

@@ -16,7 +16,7 @@ def push(self, spy_call: SpyCall) -> None:
         """Add a new spy call to the stack."""
         self._stack.append(spy_call)
 
-    def consume_when_rehearsal(self) -> WhenRehearsal:
+    def consume_when_rehearsal(self, ignore_extra_args: bool) -> WhenRehearsal:
         """Consume the last call to a Spy as a `when` rehearsal.
 
         This marks a call as a rehearsal but does not remove it from the stack.
@@ -28,11 +28,15 @@ def consume_when_rehearsal(self) -> WhenRehearsal:
         if not isinstance(call, SpyCall):
             raise MissingRehearsalError()
 
-        rehearsal = WhenRehearsal(*call)
+        rehearsal = WhenRehearsal(*call)._replace(ignore_extra_args=ignore_extra_args)
         self._stack[-1] = rehearsal
         return rehearsal
 
-    def consume_verify_rehearsals(self, count: int) -> List[VerifyRehearsal]:
+    def consume_verify_rehearsals(
+        self,
+        count: int,
+        ignore_extra_args: bool,
+    ) -> List[VerifyRehearsal]:
         """Consume the last `count` calls to Spies as rehearsals.
 
         This marks calls as rehearsals but does not remove them from the stack.
@@ -42,7 +46,10 @@ def consume_verify_rehearsals(self, count: int) -> List[VerifyRehearsal]:
         if len(calls) != count or not all(isinstance(call, SpyCall) for call in calls):
             raise MissingRehearsalError()
 
-        rehearsals = [VerifyRehearsal(*call) for call in calls]
+        rehearsals = [
+            VerifyRehearsal(*call)._replace(ignore_extra_args=ignore_extra_args)
+            for call in calls
+        ]
         self._stack[-count:] = rehearsals
         return rehearsals
 

decoy/core.py

@@ -43,14 +43,24 @@ def mock(self, *, spec: Optional[Any] = None, is_async: bool = False) -> Any:
         )
         return self._create_spy(config)
 
-    def when(self, _rehearsal: ReturnT) -> "StubCore":
+    def when(self, _rehearsal: ReturnT, *, ignore_extra_args: bool) -> "StubCore":
         """Create a new stub from the last spy rehearsal."""
-        rehearsal = self._call_stack.consume_when_rehearsal()
+        rehearsal = self._call_stack.consume_when_rehearsal(
+            ignore_extra_args=ignore_extra_args
+        )
         return StubCore(rehearsal=rehearsal, stub_store=self._stub_store)
 
-    def verify(self, *_rehearsals: ReturnT, times: Optional[int] = None) -> None:
+    def verify(
+        self,
+        *_rehearsals: ReturnT,
+        times: Optional[int],
+        ignore_extra_args: bool,
+    ) -> None:
         """Verify that a Spy or Spies were called."""
-        rehearsals = self._call_stack.consume_verify_rehearsals(count=len(_rehearsals))
+        rehearsals = self._call_stack.consume_verify_rehearsals(
+            count=len(_rehearsals),
+            ignore_extra_args=ignore_extra_args,
+        )
         calls = self._call_stack.get_by_rehearsals(rehearsals)
 
         self._verifier.verify(rehearsals=rehearsals, calls=calls, times=times)

decoy/spy_calls.py

@@ -12,12 +12,15 @@ class BaseSpyCall(NamedTuple):
         spy_name: String name of the spy.
         args: Arguments list of the call.
         kwargs: Keyword arguments list of the call.
+        ignore_extra_args: Whether extra arguments to the call should
+            be ignored during comparison. Only used by rehearsals.
     """
 
     spy_id: int
     spy_name: str
     args: Tuple[Any, ...]
     kwargs: Dict[str, Any]
+    ignore_extra_args: bool = False
 
 
 class BaseSpyRehearsal(BaseSpyCall):
@@ -45,3 +48,25 @@ class VerifyRehearsal(BaseSpyRehearsal):
     """A call that has been used as a rehearsal for `when`."""
 
     pass
+
+
+def match_call(call: BaseSpyCall, rehearsal: BaseSpyRehearsal) -> bool:
+    """Check if a call matches a given rehearsal."""
+    if call.spy_id != rehearsal.spy_id:
+        return False
+
+    if rehearsal.ignore_extra_args:
+        try:
+            args_match = all(
+                call.args[i] == value for i, value in enumerate(rehearsal.args)
+            )
+            kwargs_match = all(
+                call.kwargs[key] == value for key, value in rehearsal.kwargs.items()
+            )
+
+            return args_match and kwargs_match
+
+        except (IndexError, KeyError):
+            return False
+
+    return call.args == rehearsal.args and call.kwargs == rehearsal.kwargs

decoy/stringify.py

@@ -13,8 +13,10 @@ def stringify_call(call: BaseSpyCall) -> str:
     """
     args_list = [repr(arg) for arg in call.args]
     kwargs_list = [f"{key}={repr(val)}" for key, val in call.kwargs.items()]
-
-    return f"{call.spy_name}({', '.join(args_list + kwargs_list)})"
+    extra_args_msg = (
+        " - ignoring unspecified arguments" if call.ignore_extra_args else ""
+    )
+    return f"{call.spy_name}({', '.join(args_list + kwargs_list)}){extra_args_msg}"
 
 
 def stringify_call_list(calls: Sequence[BaseSpyCall]) -> str:

decoy/stub_store.py

@@ -1,7 +1,7 @@
 """Stub creation and storage."""
 from typing import Any, Callable, List, NamedTuple, Optional
 
-from .spy_calls import SpyCall, WhenRehearsal
+from .spy_calls import SpyCall, WhenRehearsal, match_call
 
 
 class StubBehavior(NamedTuple):
@@ -38,7 +38,7 @@ def get_by_call(self, call: SpyCall) -> StubBehavior:
         for i in reversed_indices:
             stub = self._stubs[i]
 
-            if stub.rehearsal == call:
+            if match_call(call, stub.rehearsal):
                 if stub.behavior.once:
                     self._stubs.pop(i)
 

decoy/verifier.py

@@ -1,7 +1,7 @@
 """Spy call verification."""
 from typing import Optional, Sequence
 
-from .spy_calls import SpyCall, VerifyRehearsal
+from .spy_calls import SpyCall, VerifyRehearsal, match_call
 from .errors import VerifyError
 
 
@@ -30,8 +30,9 @@ def verify(
 
         for i in range(len(calls)):
             calls_subset = calls[i : i + len(rehearsals)]
+            matches = [match_call(c, r) for c, r in zip(calls_subset, rehearsals)]
 
-            if calls_subset == rehearsals:
+            if all(matches) and len(calls_subset) == len(rehearsals):
                 match_count = match_count + 1
 
         calls_verified = match_count != 0 if times is None else match_count == times

decoy/warning_checker.py

@@ -2,7 +2,7 @@
 from typing import Dict, List, Sequence
 from warnings import warn
 
-from .spy_calls import BaseSpyCall, SpyCall, WhenRehearsal, VerifyRehearsal
+from .spy_calls import BaseSpyCall, SpyCall, WhenRehearsal, VerifyRehearsal, match_call
 from .warnings import MiscalledStubWarning, RedundantVerifyWarning
 
 
@@ -33,12 +33,12 @@ def _check_no_miscalled_stubs(all_calls: Sequence[BaseSpyCall]) -> None:
                 wr for wr in spy_calls[0:index] if isinstance(wr, WhenRehearsal)
             ]
 
-            matched_past_stubs = [wr for wr in past_stubs if wr == call]
+            matched_past_stubs = [wr for wr in past_stubs if match_call(call, wr)]
 
             matched_future_verifies = [
                 vr
                 for vr in spy_calls[index + 1 :]
-                if isinstance(vr, VerifyRehearsal) and vr == call
+                if isinstance(vr, VerifyRehearsal) and match_call(call, vr)
             ]
 
             if (

docs/usage/verify.md

@@ -75,3 +75,25 @@ decoy.verify(
 ```
 
 You may only use the `times` argument with single rehearsal.
+
+## Only specify some arguments
+
+If you don't care about some (or any) of the arguments passed to a spy, you can use the `ignore_extra_args` argument to tell Decoy to only check the arguments you pass.
+
+```python
+def log(message: str, meta: Optional[dict] = None) -> None:
+    ...
+
+# ...
+log("hello world", meta={"foo": "bar"})
+# ...
+
+decoy.verify(log("hello world"), ignore_extra_args=True)
+```
+
+This can be combined with `times=0` to say "this dependency was never called," but your typechecker may complain about this:
+
+```python
+# verify that something was never called in any way
+decoy.verify(do_something(), times=0, ignore_extra_args=True)
+```

docs/usage/when.md

@@ -130,3 +130,24 @@ async def test_my_async_thing(decoy: Decoy) -> None:
 
     assert result == Model(id="some-id")
 ```
+
+## Only specify some arguments
+
+If you don't care about some (or any) of the arguments passed to a stub, you can yse the `ignore_extra_args` argument to tell Decoy to only check the arguments you pass.
+
+```python
+database = decoy.mock(cls=Database)
+
+decoy.when(
+    database.get("some-id"),
+    ignore_extra_args=True,
+).then_return(
+    Model(id="some-id")
+)
+
+# get_model_by_id called with more args than specified
+result = database.get("some-id", SomeDefaultModel())
+
+# stubbed behavior still works
+assert result == Model(id="some-id")
+```