feat(warnings): add RedundantVerifyWarning (#36)

Closes #34

Author: mcous

decoy/call_handler.py

@@ -3,7 +3,7 @@
 
 from .call_stack import CallStack
 from .stub_store import StubStore
-from .spy import SpyCall
+from .spy_calls import SpyCall
 
 
 class CallHandler:

decoy/call_stack.py

@@ -1,7 +1,7 @@
 """Spy creation and storage."""
 from typing import List, Sequence
 
-from .spy import SpyCall, SpyRehearsal
+from .spy_calls import BaseSpyCall, SpyCall, WhenRehearsal, VerifyRehearsal
 from .errors import MissingRehearsalError
 
 
@@ -10,43 +10,52 @@ class CallStack:
 
     def __init__(self) -> None:
         """Initialize a stack for all SpyCalls."""
-        self._stack: List[SpyCall] = []
+        self._stack: List[BaseSpyCall] = []
 
     def push(self, spy_call: SpyCall) -> None:
         """Add a new spy call to the stack."""
         self._stack.append(spy_call)
 
-    def consume_rehearsal(self) -> SpyRehearsal:
-        """Consume the last call to a Spy as a rehearsal.
+    def consume_when_rehearsal(self) -> 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.
         """
-        return self.consume_rehearsals(count=1)[0]
+        try:
+            call = self._stack[-1]
+        except KeyError:
+            raise MissingRehearsalError()
+        if not isinstance(call, SpyCall):
+            raise MissingRehearsalError()
+
+        rehearsal = WhenRehearsal(*call)
+        self._stack[-1] = rehearsal
+        return rehearsal
 
-    def consume_rehearsals(self, count: int) -> List[SpyRehearsal]:
+    def consume_verify_rehearsals(self, count: int) -> List[VerifyRehearsal]:
         """Consume the last `count` calls to Spies as rehearsals.
 
         This marks calls as rehearsals but does not remove them from the stack.
         """
         calls = self._stack[-count:]
 
-        if len(calls) != count or any(isinstance(call, SpyRehearsal) for call in calls):
+        if len(calls) != count or not all(isinstance(call, SpyCall) for call in calls):
             raise MissingRehearsalError()
 
-        rehearsals = [SpyRehearsal(*call) for call in calls]
+        rehearsals = [VerifyRehearsal(*call) for call in calls]
         self._stack[-count:] = rehearsals
         return rehearsals
 
-    def get_by_rehearsals(self, rehearsals: Sequence[SpyRehearsal]) -> List[SpyCall]:
+    def get_by_rehearsals(self, rehearsals: Sequence[VerifyRehearsal]) -> List[SpyCall]:
         """Get a list of all non-rehearsal calls to the given Spy IDs."""
         return [
             call
             for call in self._stack
-            if not isinstance(call, SpyRehearsal)
+            if isinstance(call, SpyCall)
             and any(rehearsal == call for rehearsal in rehearsals)
         ]
 
-    def get_all(self) -> List[SpyCall]:
+    def get_all(self) -> List[BaseSpyCall]:
         """Get a list of all calls and rehearsals made."""
         return list(self._stack)
 

decoy/core.py

@@ -2,11 +2,13 @@
 from __future__ import annotations
 from typing import Any, Optional
 
+from .spy import SpyConfig, SpyFactory, create_spy as default_create_spy
+from .spy_calls import WhenRehearsal
 from .call_stack import CallStack
 from .stub_store import StubStore, StubBehavior
-from .spy import SpyConfig, SpyFactory, SpyRehearsal, create_spy as default_create_spy
 from .call_handler import CallHandler
 from .verifier import Verifier
+from .warning_checker import WarningChecker
 from .types import ReturnT
 
 
@@ -17,13 +19,15 @@ def __init__(
         self,
         create_spy: Optional[SpyFactory] = None,
         verifier: Optional[Verifier] = None,
+        warning_checker: Optional[WarningChecker] = None,
         stub_store: Optional[StubStore] = None,
         call_stack: Optional[CallStack] = None,
         call_handler: Optional[CallHandler] = None,
     ) -> None:
         """Initialize the DecoyCore with its dependencies."""
         self._create_spy = create_spy or default_create_spy
         self._verifier = verifier or Verifier()
+        self._warning_checker = warning_checker or WarningChecker()
         self._stub_store = stub_store or StubStore()
         self._call_stack = call_stack or CallStack()
         self._call_hander = call_handler or CallHandler(
@@ -42,28 +46,28 @@ def mock(self, *, spec: Optional[Any] = None, is_async: bool = False) -> Any:
 
     def when(self, _rehearsal: ReturnT) -> StubCore:
         """Create a new stub from the last spy rehearsal."""
-        rehearsal = self._call_stack.consume_rehearsal()
+        rehearsal = self._call_stack.consume_when_rehearsal()
         return StubCore(rehearsal=rehearsal, stub_store=self._stub_store)
 
     def verify(self, *_rehearsals: ReturnT, times: Optional[int] = None) -> None:
         """Verify that a Spy or Spies were called."""
-        rehearsals = self._call_stack.consume_rehearsals(count=len(_rehearsals))
+        rehearsals = self._call_stack.consume_verify_rehearsals(count=len(_rehearsals))
         calls = self._call_stack.get_by_rehearsals(rehearsals)
 
         self._verifier.verify(rehearsals=rehearsals, calls=calls, times=times)
 
     def reset(self) -> None:
         """Reset and remove all stored spies and stubs."""
         calls = self._call_stack.get_all()
-        self._verifier.verify_no_miscalled_stubs(calls)
+        self._warning_checker.check(calls)
         self._call_stack.clear()
         self._stub_store.clear()
 
 
 class StubCore:
     """The StubCore class implements the main logic of a Decoy Stub."""
 
-    def __init__(self, rehearsal: SpyRehearsal, stub_store: StubStore) -> None:
+    def __init__(self, rehearsal: WhenRehearsal, stub_store: StubStore) -> None:
         """Initialize the Stub with a configuration."""
         self._rehearsal = rehearsal
         self._stub_store = stub_store

decoy/errors.py

@@ -1,15 +1,25 @@
-"""Error value objects."""
+"""Errors raised by Decoy.
+
+See the [errors guide][] for more details.
+
+[errors guide]: ../usage/errors-and-warnings/#errors
+"""
 from typing import Optional, Sequence
 
-from .spy import SpyCall, SpyRehearsal
+from .spy_calls import SpyCall, VerifyRehearsal
 from .stringify import stringify_error_message, count
 
 
 class MissingRehearsalError(ValueError):
     """An error raised when `when` or `verify` is called without rehearsal(s).
 
-    This error can also be triggered if you forget to include `await` with
-    the rehearsal of an asynchronous mock.
+    This error is raised if you use Decoy incorrectly in your tests. When
+    using async/await, this error can be triggered if you forget to include
+    `await` with your rehearsal.
+
+    See the [MissingRehearsalError guide][] for more details.
+
+    [MissingRehearsalError guide]: ../usage/errors-and-warnings/#missingrehearsalerror
     """
 
     def __init__(self) -> None:
@@ -19,19 +29,23 @@ def __init__(self) -> None:
 class VerifyError(AssertionError):
     """An error raised when actual calls do not match rehearsals given to `verify`.
 
+    See [spying with verify][] for more details.
+
+    [spying with verify]: ../usage/verify/
+
     Attributes:
         rehearsals: Rehearsals that were being verified.
         calls: Actual calls to the mock(s).
         times: The expected number of calls to the mock, if any.
     """
 
-    rehearsals: Sequence[SpyRehearsal]
+    rehearsals: Sequence[VerifyRehearsal]
     calls: Sequence[SpyCall]
     times: Optional[int]
 
     def __init__(
         self,
-        rehearsals: Sequence[SpyRehearsal],
+        rehearsals: Sequence[VerifyRehearsal],
         calls: Sequence[SpyCall],
         times: Optional[int],
     ) -> None:

decoy/spy.py

@@ -6,29 +6,9 @@
 from __future__ import annotations
 from inspect import isclass, iscoroutinefunction, isfunction, signature
 from functools import partial
-from typing import get_type_hints, Any, Callable, Dict, NamedTuple, Optional, Tuple
+from typing import get_type_hints, Any, Callable, Dict, NamedTuple, Optional
 
-
-class SpyCall(NamedTuple):
-    """A value object representing a call to a spy.
-
-    Attributes:
-        spy_id: Identifier of the spy that made the call.
-        spy_name: String name of the spy.
-        args: Arguments list of the call.
-        kwargs: Keyword arguments list of the call.
-    """
-
-    spy_id: int
-    spy_name: str
-    args: Tuple[Any, ...]
-    kwargs: Dict[str, Any]
-
-
-class SpyRehearsal(SpyCall):
-    """A SpyCall that has been used as a rehearsal."""
-
-    pass
+from .spy_calls import SpyCall
 
 
 CallHandler = Callable[[SpyCall], Any]

decoy/spy_calls.py

@@ -0,0 +1,47 @@
+"""Spy call value objects."""
+from typing import Any, Dict, NamedTuple, Tuple
+
+
+class BaseSpyCall(NamedTuple):
+    """A value object representing a call to a spy.
+
+    This base class should not be used directly.
+
+    Attributes:
+        spy_id: Identifier of the spy that made the call.
+        spy_name: String name of the spy.
+        args: Arguments list of the call.
+        kwargs: Keyword arguments list of the call.
+    """
+
+    spy_id: int
+    spy_name: str
+    args: Tuple[Any, ...]
+    kwargs: Dict[str, Any]
+
+
+class BaseSpyRehearsal(BaseSpyCall):
+    """A base class for rehearsals made to `when` or `verify`.
+
+    This base class should not be used directly.
+    """
+
+    pass
+
+
+class SpyCall(BaseSpyCall):
+    """An call made to the spy by the code under test."""
+
+    pass
+
+
+class WhenRehearsal(BaseSpyRehearsal):
+    """A call that has been used as a rehearsal for `when`."""
+
+    pass
+
+
+class VerifyRehearsal(BaseSpyRehearsal):
+    """A call that has been used as a rehearsal for `when`."""
+
+    pass

decoy/stringify.py

@@ -1,10 +1,11 @@
 """Message string generation."""
 import os
 from typing import Sequence
-from .spy import SpyCall, SpyRehearsal
 
+from .spy_calls import BaseSpyCall, BaseSpyRehearsal, SpyCall
 
-def stringify_call(call: SpyCall) -> str:
+
+def stringify_call(call: BaseSpyCall) -> str:
     """Stringify the call to something human readable.
 
     `SpyCall(spy_id=42, spy_name="name", args=(1,), kwargs={"foo": False})`
@@ -16,7 +17,7 @@ def stringify_call(call: SpyCall) -> str:
     return f"{call.spy_name}({', '.join(args_list + kwargs_list)})"
 
 
-def stringify_call_list(calls: Sequence[SpyCall]) -> str:
+def stringify_call_list(calls: Sequence[BaseSpyCall]) -> str:
     """Stringify a sequence of calls into an ordered list."""
     return os.linesep.join(
         f"{i + 1}.\t{stringify_call(call)}" for i, call in enumerate(calls)
@@ -30,7 +31,7 @@ def count(count: int, noun: str) -> str:
 
 def stringify_error_message(
     heading: str,
-    rehearsals: Sequence[SpyRehearsal],
+    rehearsals: Sequence[BaseSpyRehearsal],
     calls: Sequence[SpyCall],
     include_calls: bool = True,
 ) -> str:

decoy/stub_store.py

@@ -1,7 +1,7 @@
 """Stub creation and storage."""
 from typing import Any, List, NamedTuple, Optional
 
-from .spy import SpyCall, SpyRehearsal
+from .spy_calls import SpyCall, WhenRehearsal
 
 
 class StubBehavior(NamedTuple):
@@ -15,7 +15,7 @@ class StubBehavior(NamedTuple):
 class StubEntry(NamedTuple):
     """An entry in the StubStore for later behavior lookup."""
 
-    rehearsal: SpyRehearsal
+    rehearsal: WhenRehearsal
     behavior: StubBehavior
 
 
@@ -26,7 +26,7 @@ def __init__(self) -> None:
         """Initialize a StubStore with an empty stubbings list."""
         self._stubs: List[StubEntry] = []
 
-    def add(self, rehearsal: SpyRehearsal, behavior: StubBehavior) -> None:
+    def add(self, rehearsal: WhenRehearsal, behavior: StubBehavior) -> None:
         """Create and add a new StubBehavior to the store."""
         self._stubs.append(StubEntry(rehearsal=rehearsal, behavior=behavior))