fix: allow nested mocks and typing (#2)

Author: mcous

.editorconfig

@@ -0,0 +1,12 @@
+# https://editorconfig.org
+
+root = true
+
+[*]
+end_of_line = lf
+insert_final_newline = true
+
+[*.{py,md,yml,toml}]
+charset = utf-8
+indent_style = space
+indent_size = 4

.flake8

@@ -13,4 +13,4 @@ extend-ignore =
 
 # configure flake8-docstrings
 # https://pypi.org/project/flake8-docstrings/
-docstring-convention = pep257
+docstring-convention = google

.github/workflows/ci.yml

@@ -3,64 +3,64 @@ name: Continuous integration
 on: [push, pull_request]
 
 jobs:
-  test:
-    name: Test Python ${{ matrix.python-version }} on ${{ matrix.os }}
-    runs-on: ${{ matrix.os }}
-    strategy:
-      matrix:
-        os: [ubuntu-latest, windows-latest, macos-latest]
-        python-version: ["3.7", "3.8", "3.9"]
-    steps:
-      - uses: actions/checkout@v2
-      - uses: actions/setup-python@v2
-        with:
-          python-version: ${{ matrix.python-version }}
-      - name: Install dependencies
-        run: pip install poetry && poetry install
-      - name: Run tests
-        run: poetry run pytest
+    test:
+        name: Test Python ${{ matrix.python-version }} on ${{ matrix.os }}
+        runs-on: ${{ matrix.os }}
+        strategy:
+            matrix:
+                os: [ubuntu-latest, windows-latest, macos-latest]
+                python-version: ["3.7", "3.8", "3.9"]
+        steps:
+            - uses: actions/checkout@v2
+            - uses: actions/setup-python@v2
+              with:
+                  python-version: ${{ matrix.python-version }}
+            - name: Install dependencies
+              run: pip install poetry && poetry install
+            - name: Run tests
+              run: poetry run pytest
 
-  check:
-    name: Lint and type checks
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v2
-      - uses: actions/setup-python@v2
-        with:
-          python-version: "3.8"
-      - name: Install dependencies
-        run: pip install poetry && poetry install
-      - name: Format checks
-        run: poetry run black --check .
-      - name: Lint checks
-        run: poetry run flake8
-      - name: Type checks
-        run: poetry run mypy
+    check:
+        name: Lint and type checks
+        runs-on: ubuntu-latest
+        steps:
+            - uses: actions/checkout@v2
+            - uses: actions/setup-python@v2
+              with:
+                  python-version: "3.8"
+            - name: Install dependencies
+              run: pip install poetry && poetry install
+            - name: Format checks
+              run: poetry run black --check .
+            - name: Lint checks
+              run: poetry run flake8
+            - name: Type checks
+              run: poetry run mypy
 
-  build:
-    name: Build assets and deploy on tags
-    runs-on: ubuntu-latest
-    needs: [test, check]
-    steps:
-      - uses: actions/checkout@v2
-      - uses: actions/setup-python@v2
-        with:
-          python-version: "3.8"
-      - name: Install dependencies
-        run: pip install poetry && poetry install
-      - name: Build artifacts
-        run: |
-          poetry build
-          poetry run mkdocs build
-      - if: startsWith(github.ref, 'refs/tags/v')
-        name: Deploy to PyPI and GitHub Pages
-        env:
-          USER_NAME: ${{ github.actor }}
-          USER_ID: ${{ github.event.sender.id }}
-          PYPI_TOKEN: ${{ secrets.PYPI_TOKEN }}
-        run: |
-          git config user.name "$USER_NAME (GitHub Actions)"
-          git config user.email "[email protected]"
-          poetry config pypi-token.pypi $PYPI_TOKEN
-          poetry publish
-          poetry run mkdocs gh-deploy
+    build:
+        name: Build assets and deploy on tags
+        runs-on: ubuntu-latest
+        needs: [test, check]
+        steps:
+            - uses: actions/checkout@v2
+            - uses: actions/setup-python@v2
+              with:
+                  python-version: "3.8"
+            - name: Install dependencies
+              run: pip install poetry && poetry install
+            - name: Build artifacts
+              run: |
+                  poetry build
+                  poetry run mkdocs build
+            - if: startsWith(github.ref, 'refs/tags/v')
+              name: Deploy to PyPI and GitHub Pages
+              env:
+                  USER_NAME: ${{ github.actor }}
+                  USER_ID: ${{ github.event.sender.id }}
+                  PYPI_TOKEN: ${{ secrets.PYPI_TOKEN }}
+              run: |
+                  git config user.name "$USER_NAME (GitHub Actions)"
+                  git config user.email "[email protected]"
+                  poetry config pypi-token.pypi $PYPI_TOKEN
+                  poetry publish
+                  poetry run mkdocs gh-deploy --force

README.md

@@ -17,9 +17,9 @@
 
 The Decoy library allows you to create, stub, and verify test double objects for your Python unit tests, so your tests are:
 
-- Less prone to insufficient tests due to unconditional stubbing
-- Covered by typechecking
-- Easier to fit into the Arrange-Act-Assert pattern
+-   Less prone to insufficient tests due to unconditional stubbing
+-   Covered by typechecking
+-   Easier to fit into the Arrange-Act-Assert pattern
 
 The Decoy API is heavily inspired by / stolen from the excellent [testdouble.js][] and [Mockito][] projects.
 
@@ -63,9 +63,9 @@ A stub is a an object used in a test that is pre-configured to act in a certain
 
 By pre-configuring the stub with specific rehearsals, you get the following benefits:
 
-- Your test double will only return your mock value **if it is called correctly**
-- You avoid separate "set up mock return value" and "assert mock called correctly" steps
-- If you annotate your test double with an actual type, the rehearsal will fail typechecking if called incorrectly
+-   Your test double will only return your mock value **if it is called correctly**
+-   You avoid separate "set up mock return value" and "assert mock called correctly" steps
+-   If you annotate your test double with an actual type, the rehearsal will fail typechecking if called incorrectly
 
 ```python
 import pytest
@@ -99,13 +99,13 @@ If you're coming from `unittest.mock`, you're probably more used to calling your
 
 Verification of decoy calls after they have occurred be considered a last resort, because:
 
-- If you're calling a method/function to get its data, then you can more precisely describe that relationship using [stubbing](#stubbing)
-- Side-effects are harder to understand and maintain than pure functions, so in general you should try to side-effect sparingly
+-   If you're calling a method/function to get its data, then you can more precisely describe that relationship using [stubbing](#stubbing)
+-   Side-effects are harder to understand and maintain than pure functions, so in general you should try to side-effect sparingly
 
 Stubbing and verification of a decoy are **mutually exclusive** within a test. If you find yourself wanting to both stub and verify the same decoy, then one or more of these is true:
 
-- The assertions are redundant
-- The dependency is doing too much based on its input (e.g. side-effecting _and_ calculating complex data) and should be refactored
+-   The assertions are redundant
+-   The dependency is doing too much based on its input (e.g. side-effecting _and_ calculating complex data) and should be refactored
 
 ```python
 import pytest

decoy/__init__.py

@@ -1,8 +1,7 @@
 """Decoy test double stubbing and verification library."""
-
-from mock import AsyncMock, MagicMock
 from typing import cast, Any, Callable, Mapping, Optional, Sequence, Tuple, Type
 
+from .mock import create_decoy_mock, DecoyMock
 from .registry import Registry
 from .stub import Stub
 from .types import Call, ClassT, FuncT, ReturnT
@@ -15,8 +14,7 @@ class Decoy:
     _last_decoy_id: Optional[int]
 
     def __init__(self) -> None:
-        """
-        Initialize the state container for test doubles and stubs.
+        """Initialize the state container for test doubles and stubs.
 
         You should initialize a new Decoy instance for every test.
 
@@ -34,8 +32,7 @@ def decoy() -> Decoy:
         self._last_decoy_id = None
 
     def create_decoy(self, spec: Type[ClassT], *, is_async: bool = False) -> ClassT:
-        """
-        Create a class decoy for `spec`.
+        """Create a class decoy for `spec`.
 
         Arguments:
             spec: A class definition that the decoy should mirror.
@@ -52,25 +49,13 @@ def test_get_something(decoy: Decoy):
             ```
 
         """
-        decoy = MagicMock(spec=spec) if is_async is False else AsyncMock(spec=spec)
-        decoy_id = self._registry.register_decoy(decoy)
-        side_effect = self._create_track_call_and_act(decoy_id)
-
-        decoy.configure_mock(
-            **{
-                f"{method}.side_effect": side_effect
-                for method in dir(spec)
-                if not (method.startswith("__") and method.endswith("__"))
-            }
-        )
-
+        decoy = self._create_and_register_mock(spec=spec, is_async=is_async)
         return cast(ClassT, decoy)
 
     def create_decoy_func(
         self, spec: Optional[FuncT] = None, *, is_async: bool = False
     ) -> FuncT:
-        """
-        Create a function decoy for `spec`.
+        """Create a function decoy for `spec`.
 
         Arguments:
             spec: A function that the decoy should mirror.
@@ -86,16 +71,12 @@ def test_create_something(decoy: Decoy):
                 # ...
             ```
         """
-        decoy = MagicMock(spec=spec) if is_async is False else AsyncMock(spec=spec)
-        decoy_id = self._registry.register_decoy(decoy)
-
-        decoy.configure_mock(side_effect=self._create_track_call_and_act(decoy_id))
+        decoy = self._create_and_register_mock(spec=spec, is_async=is_async)
 
         return cast(FuncT, decoy)
 
     def when(self, _rehearsal_result: ReturnT) -> Stub[ReturnT]:
-        """
-        Create a [Stub][decoy.stub.Stub] configuration using a rehearsal call.
+        """Create a [Stub][decoy.stub.Stub] configuration using a rehearsal call.
 
         See [stubbing](/#stubbing) for more details.
 
@@ -118,9 +99,8 @@ def when(self, _rehearsal_result: ReturnT) -> Stub[ReturnT]:
 
         return stub
 
-    def verify(self, _rehearsal_result: ReturnT) -> None:
-        """
-        Verify a decoy was called using a rehearsal.
+    def verify(self, _rehearsal_result: Optional[ReturnT] = None) -> None:
+        """Verify a decoy was called using a rehearsal.
 
         See [verification](/#verification) for more details.
 
@@ -145,6 +125,15 @@ def test_create_something(decoy: Decoy):
 
         decoy.assert_has_calls([rehearsal])
 
+    def _create_and_register_mock(self, spec: Any, is_async: bool) -> DecoyMock:
+        decoy = create_decoy_mock(is_async=is_async, spec=spec)
+        decoy_id = self._registry.register_decoy(decoy)
+        side_effect = self._create_track_call_and_act(decoy_id)
+
+        decoy.configure_mock(side_effect=side_effect)
+
+        return decoy
+
     def _pop_last_rehearsal(self) -> Tuple[int, Call]:
         decoy_id = self._last_decoy_id
 

decoy/matchers.py

@@ -23,8 +23,7 @@ def __repr__(self) -> str:
 
 
 def Anything() -> Any:
-    """
-    Match anything except None.
+    """Match anything except None.
 
     Example:
         ```python
@@ -52,8 +51,7 @@ def __repr__(self) -> str:
 
 
 def IsA(match_type: type) -> Any:
-    """
-    Match anything that satisfies the passed in type.
+    """Match anything that satisfies the passed in type.
 
     Arguments:
         match_type: Type to match.
@@ -85,8 +83,7 @@ def __repr__(self) -> str:
 
 
 def IsNot(value: object) -> Any:
-    """
-    Match anything that isn't the passed in value.
+    """Match anything that isn't the passed in value.
 
     Arguments:
         value: Value to check against.
@@ -120,8 +117,7 @@ def __repr__(self) -> str:
 
 
 def StringMatching(match: str) -> str:
-    """
-    Match any string matching the passed in pattern.
+    """Match any string matching the passed in pattern.
 
     Arguments:
         match: Pattern to check against; will be compiled into an re.Pattern.
@@ -163,8 +159,7 @@ def __repr__(self) -> str:
 
 
 def ErrorMatching(error: Type[Exception], match: Optional[str] = None) -> Exception:
-    """
-    Match any error matching an Exception type and optional message matcher.
+    """Match any error matching an Exception type and optional message matcher.
 
     Arguments:
         error: Exception type to match against.

decoy/mock.py

@@ -0,0 +1,29 @@
+"""Custom unittest.mock subclasses."""
+
+from mock import AsyncMock, MagicMock
+from typing import Any, Union
+
+
+class SyncDecoyMock(MagicMock):
+    """MagicMock variant where all child mocks use the parent side_effect."""
+
+    def _get_child_mock(self, **kwargs: Any) -> Any:
+        return super()._get_child_mock(**kwargs, side_effect=self.side_effect)
+
+
+class AsyncDecoyMock(AsyncMock):  # type: ignore[misc]
+    """AsyncMock variant where all child mocks use the parent side_effect."""
+
+    def _get_child_mock(self, **kwargs: Any) -> Any:
+        return super()._get_child_mock(**kwargs, side_effect=self.side_effect)
+
+
+DecoyMock = Union[SyncDecoyMock, AsyncDecoyMock]
+
+
+def create_decoy_mock(is_async: bool, **kwargs: Any) -> DecoyMock:
+    """Create a MagicMock or AsyncMock."""
+    if is_async is False:
+        return SyncDecoyMock(**kwargs)
+    else:
+        return AsyncDecoyMock(**kwargs)