How does unittest.mock.PropertyMock fake an attribute that is backed by a property?

`PropertyMock` exists because attribute *access* is not a method call from the caller's point of view, and a normal mock can only intercept calls. ## Why an ordinary mock attribute is not enough `property` is a descriptor: an object defining `__get__` (and optionally `__set__`) that lives on the class. When you evaluate `obj.attr`, the interpreter checks `type(obj)` first, and a data descriptor — one defining `__set__` or `__delete__`, which `property` does — takes precedence over anything in the instance `__dict__`. So `obj.attr = Mock()` on a real object with a read-only property raises `AttributeError: property 'attr' of 'C' object has no setter`, and even where the assignment succeeds the class descriptor still governs the read. There is a second, subtler failure. If you set a plain `Mock` in place of a property that the code reads as a value, the code gets the mock object itself rather than a value, and comparisons, string formatting or arithmetic against it behave in surprising ways instead of failing loudly. ## What PropertyMock is `PropertyMock` is a subclass of `Mock` that defines `__get__` and `__set__`. Those hooks turn attribute traffic into calls on the mock: * reading the attribute calls the mock with **no** arguments and returns its `return_value`; * assigning to the attribute calls the mock with **one** argument, the assigned value. That is why `p.assert_called_once_with()` — empty parentheses — is the assertion for "the attribute was read once", and why an assignment shows up in `call_args_list` as `call("new value")`. It is also why `PropertyMock` must be attached to a **class**. Descriptor hooks are only honoured on the type; assigning `instance.attr = PropertyMock(...)` merely stores the mock object in the instance dictionary, and reading it back gives you a `PropertyMock` instance, not `"the value"`. ## Attaching it The supported spelling is to let `patch` do it: ```python with patch.object(IngestConfig, "source_dir", new_callable=PropertyMock) as p: p.return_value = "/var/log/staged" ``` `new_callable` tells `patch` which class to instantiate for the replacement, and because `patch.object` targets the class, the mock lands where a descriptor is honoured. Restoration on exit is automatic, which matters more here than usual: you have mutated a class, and every other test in the process shares that class. You can also attach one by hand — `type(obj).attr = PropertyMock(return_value=...)` — including on a `MagicMock`, where `type(m)` is a per-instance subclass so the patch does not bleed into other mocks. Keep the reference you assigned, because reading `type(obj).attr` back triggers `__get__` and returns the configured value rather than the mock, leaving you with no handle for assertions. Hand-attaching also means hand-removing with `del`. ## What it is good for The natural use is a property whose real implementation does something a test must not do — reads a mount point, opens a connection, consults a clock or a config file. Doubling the property keeps the object under test otherwise real. It is equally good for the negative case: `p.side_effect = OSError("mount unavailable")` makes the attribute *raise* on access, which is an awkward failure to provoke any other way and often the one the error-handling branch was written for. It also fits attributes that are not properties in production but whose access you want to count — a mock collaborator whose `encoding` or `closed` attribute the code reads, where the assertion is about *whether it was consulted*, not about the value. ## The gotchas worth naming Reading through the class rather than an instance still fires `__get__`, so `Cls.attr` gives a value and not the mock. A `PropertyMock` attached to a class is shared by every instance of it, so per-instance values need `side_effect` rather than `return_value`. And the recorded call for a read carries no arguments at all, which trips people who expect `assert_called_once_with(instance)` in the style of a descriptor's real `__get__` signature — the mock deliberately hides the descriptor plumbing and records the access, not the protocol.