docs: split usage guide into multiple sections

Author: mcous

README.md

@@ -14,15 +14,15 @@
         </a>
     </p>
     <p>
-        <a href="https://mike.cousins.io/decoy/">https://mike.cousins.io/decoy/</a>
+        <a href="https://mike.cousins.io/decoy/">Usage guide and documentation</a>
     </p>
 </div>
 
-The Decoy library allows you to create, stub, and verify test double objects for your Python unit tests, so your tests are:
+The Decoy library allows you to create, stub, and verify fully-typed, async/await friendly mocks in 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
+-   Covered by typechecking
 
 The Decoy API is heavily inspired by / stolen from the excellent [testdouble.js][] and [Mockito][] projects.
 
@@ -41,7 +41,7 @@ poetry add --dev decoy
 
 ## Setup
 
-### Pytest
+### Pytest setup
 
 Decoy ships with its own [pytest][] plugin, so once Decoy is installed, you're ready to start using it via its pytest fixture, called `decoy`.
 
@@ -59,9 +59,7 @@ The `decoy` fixture is function-scoped and will ensure that all stub and spy sta
 
 ### Mypy Setup
 
-Decoy's rehearsal syntax can be a bit confusing to [mypy][] if a function is supposed to return `None`. Normally, [mypy will complain][] if you try to use a `None`-returning expression as a value, because this is almost always a mistake.
-
-In Decoy, however, it's an intentional part of the API and _not_ a mistake. To suppress these errors, Decoy provides a mypy plugin that you should add to your configuration file:
+Decoy's API can be a bit confusing to [mypy][]. To suppress mypy errors that may be emitted during valid usage of the Decoy API, we have a mypy plugin that you should add to your configuration file:
 
 ```ini
 # mypi.ini
@@ -72,166 +70,3 @@ plugins = decoy.mypy
 ```
 
 [mypy]: https://mypy.readthedocs.io/
-[mypy will complain]: https://mypy.readthedocs.io/en/stable/error_code_list.html#check-that-called-function-returns-a-value-func-returns-value
-
-## Usage
-
-### Stubbing
-
-A stub is an object used in a test that is pre-configured to return a result or raise an error if called according to a specification. In Decoy, you specify a stub's call conditions with a "rehearsal", which is simply a call to the stub inside of a `decoy.when` wrapper.
-
-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
-
-```python
-import pytest
-from typing import cast, Optional
-from decoy import Decoy
-
-from .database import Database, Model
-
-def get_item(uid: str, db: Database) -> Optional[Model]:
-  return db.get_by_id(uid)
-
-def test_get_item(decoy: Decoy):
-    mock_item = cast(Model, { "foo": "bar" })
-    mock_db = decoy.create_decoy(spec=Database)
-
-    # arrange stub using rehearsals
-    decoy.when(mock_db.get_by_id("some-id")).then_return(mock_item)
-
-    # call code under test
-    some_result = get_item("some-id")
-    other_result = get_item("other-id")
-
-    # assert code result
-    assert some_result == mock_item
-    assert other_result is None
-```
-
-### Verifying interactions
-
-If you're coming from `unittest.mock`, you're probably used to calling your code under test and _then_ verifying that your dependency was called correctly. Decoy provides similar call verification using the same "rehearsal" mechanism that the stubbing API uses.
-
-```python
-import pytest
-from typing import cast, Optional
-from decoy import Decoy, verify
-
-from .logger import Logger
-
-def log_warning(msg: str, logger: Logger) -> None:
-    logger.warn(msg)
-
-def test_log_warning(decoy: Decoy):
-    logger = decoy.create_decoy(spec=Logger)
-
-    # call code under test
-    some_result = log_warning("oh no!", logger)
-
-    # verify double called correctly with a rehearsal
-    decoy.verify(logger.warn("oh no!"))
-```
-
-Asserting that calls happened after the fact can be useful, but **should only be used if the dependency is being called solely for its side-effect(s)**. Verification of interactions in this manner should be considered a last resort, because:
-
--   If you're calling a dependency to get 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
-
-#### Verifying order of multiple calls
-
-If your code under test must call several dependencies in order, you may pass multiple rehearsals to `verify`. Decoy will search through the list of all calls made to the given spies and look for the exact rehearsal sequence given, in order.
-
-```python
-decoy.verify(
-    handler.call_first_procedure("hello"),
-    handler.call_second_procedure("world"),
-)
-```
-
-### Usage with async/await
-
-Decoy supports async/await out of the box! Pass your async function or class with async methods to `spec` in `decoy.create_decoy_func` or `decoy.create_decoy`, respectively, and Decoy will figure out the rest.
-
-When writing rehearsals on async functions and methods, remember to include the `await` with your rehearsal call:
-
-```py
-decoy.when(await mock_db.get_by_id("some-id")).then_return(mock_item)
-```
-
-### Matchers
-
-Sometimes, when you're stubbing or verifying calls (or really when you're doing any sort of equality assertion in a test), you need to loosen a given assertion. For example, you may want to assert that a dependency is called with a string, but you don't care about the full contents of that string.
-
-Decoy includes a set of matchers, which are simply Python classes with `__eq__` methods defined, that you can use in rehearsals and/or assertions.
-
-```python
-import pytest
-from typing import cast, Optional
-from decoy import Decoy, matchers
-
-from .logger import Logger
-
-def log_warning(msg: str, logger: Logger) -> None:
-    logger.warn(msg)
-
-def test_log_warning(decoy: Decoy):
-    logger = decoy.create_decoy(spec=Logger)
-
-    # call code under test
-    some_result = log_warning(
-        "Oh no, something went wrong with request ID abc123efg456",
-        logger=logger
-    )
-
-    # verify double called correctly
-    decoy.verify(
-        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/__init__.py

@@ -64,6 +64,8 @@ def create_decoy(
     ) -> ClassT:
         """Create a class decoy for `spec`.
 
+        See [decoy creation usage guide](../usage/create) for more details.
+
         Arguments:
             spec: A class definition that the decoy should mirror.
             is_async: Force the returned spy to be asynchronous. In most cases,
@@ -93,6 +95,8 @@ def create_decoy_func(
     ) -> FuncT:
         """Create a function decoy for `spec`.
 
+        See [decoy creation usage guide](../usage/create) for more details.
+
         Arguments:
             spec: A function that the decoy should mirror.
             is_async: Force the returned spy to be asynchronous. In most cases,
@@ -119,7 +123,7 @@ def test_create_something(decoy: Decoy):
     def when(self, _rehearsal_result: ReturnT) -> Stub[ReturnT]:
         """Create a [Stub][decoy.stub.Stub] configuration using a rehearsal call.
 
-        See [stubbing](index.md#stubbing) for more details.
+        See [stubbing usage guide](../usage/when) for more details.
 
         Arguments:
             _rehearsal_result: The return value of a rehearsal, used for typechecking.
@@ -149,7 +153,7 @@ def when(self, _rehearsal_result: ReturnT) -> Stub[ReturnT]:
     def verify(self, *_rehearsal_results: Any) -> None:
         """Verify a decoy was called using one or more rehearsals.
 
-        See [verification](index.md#verification) for more details.
+        See [verification usage guide](../usage/verify) for more details.
 
         Arguments:
             _rehearsal_results: The return value of rehearsals, unused except

decoy/stub.py

@@ -26,7 +26,7 @@ def __init__(self, rehearsal: SpyCall) -> None:
     def then_return(self, *values: ReturnT) -> None:
         """Set the stub's return value(s).
 
-        See [stubbing](/#stubbing) for more details.
+        See [stubbing usage guide](../usage/when) for more details.
 
         Arguments:
             *values: Zero or more return values. Multiple values will result
@@ -39,7 +39,7 @@ def then_return(self, *values: ReturnT) -> None:
     def then_raise(self, error: Exception) -> None:
         """Set the stub's error value.
 
-        See [stubbing](/#stubbing) for more details.
+        See [stubbing usage guide](../usage/when) for more details.
 
         Arguments:
             error: The error to raise.

docs/usage/create.md

@@ -0,0 +1,29 @@
+# Creating mocks
+
+Decoy can create two kinds of mocks:
+
+-   Mocks of a class instance
+-   Mocks of a function
+
+## Mocking a class
+
+The [`create_decoy` method][decoy.Decoy.create_decoy] is used to create mock class instances. Decoy will inspect type annotations and method signatures to automatically configure methods as synchronous or asynchronous. Decoy mocks are automatically deep.
+
+To typecheckers, the mock will appear to have the exact same type as the `spec` argument. The mock will also pass `isinstance` checks.
+
+```python
+def test_my_thing(decoy: Decoy) -> None:
+    some_dependency = decoy.create_decoy(spec=SomeDependency)
+```
+
+## Mocking a function
+
+The [`create_decoy_func` method][decoy.Decoy.create_decoy_func] is used to create a mock function instance. Decoy can inspect a `spec` function signature to automatically configure the function as syncronous or asynchronous. Otherwise, the `is_async` argument can force the mock to be asynchronous.
+
+To typecheckers, the mock will appear to have the exact same type as the `spec` argument, if used.
+
+```python
+def test_my_thing(decoy: Decoy) -> None:
+    mock_function = decoy.create_decoy_func(spec=some_function)
+    free_async_function = decoy.create_decoy_func(is_async=True)
+```

docs/usage/matchers.md

@@ -0,0 +1,69 @@
+# Loosening assertions with matchers
+
+Sometimes, when you're stubbing or verifying calls (or really when you're doing any sort of equality assertion in a test), you need to loosen a given assertion. For example, you may want to assert that a dependency is called with a string, but you don't care about the full contents of that string.
+
+Decoy includes a [`matchers` module][decoy.matchers], which has a set of Python classes with `__eq__` methods defined that you can use in rehearsals and/or assertions in place of actual values
+
+## Basic usage
+
+To use, import `decoy.matchers` and use a matcher wherever you would normally use a value.
+
+```python
+import pytest
+from typing import cast, Optional
+from decoy import Decoy, matchers
+
+from .logger import Logger
+from .my_thing import MyThing
+
+def test_log_warning(decoy: Decoy):
+    logger = decoy.create_decoy(spec=Logger)
+
+    subject = MyThing(logger=logger)
+
+    # call code under test
+    subject.log_warning("Oh no, something went wrong with request abc123efg456")
+
+    # verify double called correctly
+    decoy.verify(
+        logger.warn(matchers.StringMatching("request abc123efg456"))
+    )
+```
+
+## Capturing values
+
+When testing certain APIs, especially callback APIs, it can be helpful to capture the values of arguments passed to a given dependency. For this, Decoy provides [`matchers.Captor`][decoy.matchers.captor].
+
+For example, our test subject may register an event listener handler, 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 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).