feat(matchers): add argument captor matcher (#19)

Closes #17

Author: mcous

README.md

@@ -198,3 +198,41 @@ def test_log_warning(decoy: Decoy):
         logger.warn(matchers.StringMatching("request ID abc123efg456"))
     )
 ```
+
+#### Capturing values with `matchers.captor`
+
+When testing certain APIs, especially callback APIs, it can be helpful to capture the values of arguments passed to a given decoy.
+
+For example, our test subject may register an anonymous event listener handler with a dependency, and we want to test our subject's behavior when the event listener is triggered.
+
+```py
+import pytest
+from typing import cast, Optional
+from decoy import Decoy, matchers
+
+from .event_source import EventSource
+from .event_consumer import EventConsumer
+
+
+def test_event_listener(decoy: Decoy):
+    event_source = decoy.create_decoy(spec=EventSource)
+    subject = EventConsumer(event_source=event_source)
+    captor = matchers.Captor()
+
+    # subject registers its listener when started
+    subject.start_consuming()
+
+    # verify listener attached and capture the listener
+    decoy.verify(event_source.register(event_listener=captor))
+
+    # trigger the listener
+    event_handler = captor.value  # or, equivalently, captor.values[0]
+
+    assert subject.has_heard_event is False
+    event_handler()
+    assert subject.has_heard_event is True
+```
+
+This is a pretty verbose way of writing a test, so in general, you may want to approach using `matchers.captor` as a form of potential code smell / test pain. There are often better ways to structure your code for these sorts of interactions that don't involve anonymous / private functions.
+
+For further reading on when (or rather, when not) to use argument captors, check out [testdouble's documentation on its argument captor matcher](https://github.com/testdouble/testdouble.js/blob/main/docs/6-verifying-invocations.md#tdmatcherscaptor).

decoy/matchers.py

@@ -25,7 +25,7 @@ def test_logger_called(decoy: Decoy):
     equality comparisons for stubbing and verification.
 """
 from re import compile as compile_re
-from typing import cast, Any, Optional, Pattern, Type
+from typing import cast, Any, List, Optional, Pattern, Type
 
 
 __all__ = [
@@ -34,6 +34,7 @@ def test_logger_called(decoy: Decoy):
     "IsNot",
     "StringMatching",
     "ErrorMatching",
+    "Captor",
 ]
 
 
@@ -197,3 +198,52 @@ def ErrorMatching(error: Type[Exception], match: Optional[str] = None) -> Except
         ```
     """
     return cast(Exception, _ErrorMatching(error, match))
+
+
+class _Captor:
+    def __init__(self) -> None:
+        self._values: List[Any] = []
+
+    def __eq__(self, target: object) -> bool:
+        """Capture compared value, always returning True."""
+        self._values.append(target)
+        return True
+
+    def __repr__(self) -> str:
+        """Return a string representation of the matcher."""
+        return "<Captor>"
+
+    @property
+    def value(self) -> Any:
+        """Get the captured value.
+
+        Raises:
+            AssertionError: if no value was captured.
+        """
+        if len(self._values) == 0:
+            raise AssertionError("No value captured by captor.")
+
+        return self._values[-1]
+
+    @property
+    def values(self) -> List[Any]:
+        """Get all captured values."""
+        return self._values
+
+
+def Captor() -> Any:
+    """Match anything, capturing its value.
+
+    The last captured value will be set to `captor.value`. All captured
+    values will be placed in the `captor.values` list, which can be
+    helpful if a captor needs to be triggered multiple times.
+
+    Example:
+        ```python
+        captor = Captor()
+        assert "foobar" == captor
+        print(captor.value)  # "foobar"
+        print(captor.values)  # ["foobar"]
+        ```
+    """
+    return _Captor()

decoy/mypy/__init__.py

@@ -0,0 +1,4 @@
+"""Decoy mypy plugin entrypoint."""
+from .plugin import plugin
+
+__all__ = ["plugin"]

decoy/mypy.py renamed to decoy/mypy/plugin.py

@@ -83,7 +83,7 @@ def __getattr__(self, name: str) -> Any:
                 # according to Python, `get_type_hints` will raise.
                 # Rather than fail to create a spy with an inscrutable error,
                 # gracefully fallback to a specification-less spy.
-                hints = get_type_hints(self._spec)  # type: ignore[arg-type]
+                hints = get_type_hints(self._spec)
                 child_spec = getattr(
                     self._spec,
                     name,

decoy/spy.py

@@ -2,4 +2,4 @@
 files = decoy,tests
 strict = True
 show_error_codes = True
-plugins = decoy.mypy
+plugins = decoy/mypy/plugin.py