How do you assert what your code wrote through a mock_open file handle?

When you patch `open` with `unittest.mock.mock_open`, you end up with a two-level record, and almost every mistake in this area comes from asserting at the wrong level. ## The two levels The mock you installed — call it `m` — stands in for `open`. Its own call record answers *was the file opened, with what path and mode*: `m.assert_called_once_with("/var/log/ingest.offsets", "w")`. Everything the code did *with* the file happened on `m.return_value`, the handle. `write`, `writelines`, `flush` and `close` are auto-created children of that handle, and each keeps its own `call_args_list`, `call_count` and `called`. ## Fetch the handle without disturbing the record The idiom you will see written both ways is: ```python handle = m.return_value # inert: just reads the attribute handle = m() # calls the mock — records an extra open() ``` Both give you the same object, because the handle *is* the return value. But `m()` registers a call to `open` with no arguments, so a later `m.assert_called_once_with(path, "w")` fails with "Called 2 times", and `m.call_count` is off by one. Use `m.return_value` whenever the test also asserts on how `open` was called. If you do use `m()`, at least assert on the open first and fetch the handle afterwards. ## Assert on content, not on chunking `handle.write` records one call per `write()` the code made, so two writes produce two entries in `call_args_list`. Asserting `handle.write.assert_called_once_with(whole_document)` therefore fails the moment the implementation writes a header and a body separately — the test is coupled to an irrelevant detail. The robust assertion rebuilds the document: ```python written = "".join(c.args[0] for c in handle.write.call_args_list) assert written == "shard=0 offset=41\nshard=1 offset=17\n" ``` `call_args_list` holds `call` objects, and each exposes `.args` and `.kwargs`, so `c.args[0]` is the string that was written. When the order of a few specific writes genuinely matters, `handle.write.assert_has_calls([...])` checks that those calls appear as a contiguous run; `assert_any_call` checks membership without order. ## writelines is a different child `f.writelines(lines)` does **not** fan out into individual `write` calls on a mock — the double implements nothing, it only records. `handle.write.call_args_list` stays empty and the single call lands on `handle.writelines` with the whole list as one argument. A test that only joins `write` calls will report an empty document and, if it asserts `written == ""` by accident, will pass. When the code path is not fixed, assert on both children or assert on `m.mock_calls`. ## The whole session in order `m.mock_calls` is the parent record and contains the interleaved script for every handle interaction, spelled with the `call()` prefix: ``` call('/var/log/ingest.offsets', 'w') call().__enter__() call().write('shard=0 offset=41\n') call().__exit__(None, None, None) call().close() ``` That is where to look when the question is ordering — was the file closed before the index was updated, did the code write after an exception — rather than content. Note that `mock_open`'s `__exit__` also triggers `close()`, so a test asserting the file was closed passes for free and proves little. Note too that `assert_has_calls` requires the expected calls to appear *consecutively* in that list, so mixing `__enter__` and `__exit__` into one `assert_has_calls` fails when writes sit between them; use `in m.mock_calls` for a membership check instead. ## The shared-handle trap Every call to the patched `open` returns the same handle, so if the function under test writes two different files, both sets of writes accumulate in one `call_args_list` with nothing to tell them apart. Options are to assert on the combined content when that is meaningful, to give `m` a `side_effect` that returns a distinct double per path, or to test the two writes separately. ## What the assertions cannot tell you The double never encodes, never buffers and never fails. A `str`/`bytes` mismatch, a file opened without the mode the code needs, a partial write, a disk full — none of them can surface here. These assertions verify *what your code asked for*, which is exactly their value and exactly their boundary.