When does unittest.mock.create_autospec catch a bug that Mock(spec=...) misses?

## Where `spec=` stops `Mock(spec=SomeClass)` fences a double at the *name* level: - it copies the attribute names from the object you hand it, - raises AttributeError for anything else, - and fakes `__class__` so isinstance checks pass. That is where it stops. The mock's children are ordinary unconstrained mocks, and no call is ever checked against a signature. So `Mock(spec=Ledger).post(1, 2, 3, 4)` sails through even though `Ledger.post` takes `(self, amount, account)`, and `specced.post.anything_at_all` is invented as usual one level down. ## What `create_autospec` adds `unittest.mock.create_autospec` does the thing people usually think `spec=` does. It walks the target recursively and rebuilds it: every attribute becomes a mock specced from the corresponding real attribute, and every callable is created with the **real signature**, introspected with `inspect.signature`. Calls are then bound against that signature before they are recorded, so passing too many positional arguments, omitting a required one, or using a keyword the function does not accept raises `TypeError: too many positional arguments` / `missing a required argument: 'account'` at the call site. Methods are built with `self` already bound, so you write the call exactly as production writes it. Because the rebuild is recursive, the constraint survives one level down — child attributes are specced too, not bare mocks. ## Classes, instances and coroutines Autospeccing a *class* gives you a callable mock whose `return_value` is a `NonCallableMagicMock` specced as an instance of that class, which mirrors reality: calling the class constructor yields an instance, and the instance itself must not be callable. - When the code under test receives an already-constructed collaborator, pass `instance=True` so the double is non-callable from the start and an accidental `collaborator()` raises TypeError instead of quietly returning a mock. - Members defined with `async def` come back as `AsyncMock`, so awaiting them works and the double does not need special handling. `patch(target, autospec=True)` applies the same treatment in place: the replacement is built from the object it is replacing, so an arity mistake in the test raises TypeError instead of being recorded as a call. For a plain function this replacement is a real function object with a matching signature that delegates to the mock, which is what makes the signature error come from argument binding rather than from a mock-specific check; you still get `assert_called_once_with` and the rest of the assertion surface on it. ## The limits The limits matter as much as the capability, and are where a senior answer separates itself. 1. First, autospec can only see what is on the object at spec time. Attributes assigned in `__init__` do not exist on the class, so `create_autospec(Ledger).cache` raises AttributeError even though every real instance has one. Anything served dynamically through a `__getattr__` hook is invisible for the same reason. The workarounds are to autospec a live *instance* rather than the class, to configure the missing attribute explicitly on the double, or to introduce a narrow explicit interface — a `typing.Protocol` or an abstract base — and spec against that. 2. Second, autospec is not free. Building one is roughly an order of magnitude more expensive than `Mock(spec=...)` because it introspects the whole object graph — measurable, if not usually decisive, in a suite already running 27 minutes for a payment reconciliation job. Autospec the collaborators that carry your real contracts; you do not need it for a throwaway double whose only job is to be passed through. 3. Third, and most important: autospec validates the shape of the interface *as it exists in this process*. It says nothing about whether the object you are mocking behaves as your test pretends, nothing about the return-value shape, and nothing about a version of the dependency other than the one installed. A mocked collaborator whose real counterpart changed behaviour without changing its signature will still pass. That is a property of doubles in general, not a defect of autospec, and it is why **interface-level fidelity** and **behavioural fidelity** are separate problems. ## Choosing the double Rule of thumb: - reach for autospec by default when the double stands in for something you own a contract with; - use `instance=True` when the code receives an instance rather than a factory; - fall back to `Mock(spec_set=...)` when you only need a name-level fence cheaply; - and reach for a hand-built mock only when the collaborator has no importable interface at all — in which case seal it rather than leaving it open.