Why does unittest's assertWarns see a warning that a plain catch_warnings block misses?

### The machinery under `warnings.warn` A warning is not an exception being raised — it is a message passed through a filter chain. `warnings.warn(message, category, stacklevel=...)` walks `warnings.filters`, a list of `(action, message, category, module, lineno)` tuples, and the first match decides the fate of the call: `"error"` turns it into a raised exception, `"ignore"` drops it, `"always"` shows it every time, `"once"` shows it once per process, `"module"` once per module, and `"default"` — the one that matters here — shows it **once per unique (message text, category, module, line number)**. That "once" has to be remembered somewhere, and it is remembered in the calling module's `__warningregistry__` dictionary. It is per-module, per-process, and nothing clears it between tests. This is the entire mechanism behind the interview question, and behind a whole family of order-dependent test failures: run `test_a` first and the warning is recorded; run `test_b`, which exercises the same line, and the warning is suppressed, so a `catch_warnings(record=True)` block sees an empty list and the assertion fails — but only when the tests run in that order, or only on the second run in a long-lived process. ### What `catch_warnings` actually does `warnings.catch_warnings()` is a save/restore context manager and nothing more: it snapshots `warnings.filters` and the `showwarning` hook on entry and puts them back on exit. It does **not** change any filter by itself. With `record=True` it additionally redirects warnings into a list, which it returns, of `WarningMessage` objects carrying `message` (the warning instance), `category`, `filename` and `lineno`. So a correct hand-rolled capture always has two statements, not one: ```python with warnings.catch_warnings(record=True) as seen: warnings.simplefilter("always") call_the_code() ``` Drop the `simplefilter` line and you inherit whatever filters the process happens to carry — including the interpreter's default suppression of `DeprecationWarning` outside `__main__`, and including the once-per-location registry above. Since **Python 3.11** you can fold the two into one call: `catch_warnings(record=True, action="always")` takes the same keyword arguments `simplefilter` does (`action`, `category`, `module`, `lineno`, `append`). One caveat worth stating out loud in an interview: `catch_warnings` mutates **process-global** state, so it is documented as not thread-safe. Two threads inside overlapping blocks will trample each other's filters. ### What `assertWarns` adds `unittest.TestCase.assertWarns(category)` wraps all of that and closes both holes. On entry it iterates `sys.modules` and empties every module's `__warningregistry__`, so no earlier test can hide the warning; it then enters `catch_warnings(record=True)` and calls `simplefilter("always", category)`. On exit it scans the captured list for an instance of the expected category and fails with `<Category> not triggered` if none matched. Unlike `assertLogs`, it has a callable form too — `self.assertWarns(DeprecationWarning, func, arg)` — though the context-manager form reads better. Because it stores the match, the block gives you the warning itself: ```python with self.assertWarns(DeprecationWarning) as caught: encode(93) self.assertEqual(str(caught.warning), "quality above 92 blows the budget") ``` `caught.warning` is the warning **instance** (so a custom warning subclass keeps its attributes), and `caught.filename` / `caught.lineno` are the source location the warning was attributed to — which is why the code under test should pass `stacklevel=2` when warning on behalf of its caller. `assertWarnsRegex(category, pattern)` is the same thing with a `re.search` over `str(warning)`; it is the right tool when the message embeds a value, and the wrong one when you would be re-testing your own format string. The symmetric negative does not exist as public API: there is no supported "assert no warnings" method on `TestCase`, so the honest way to express it is a `catch_warnings(record=True)` block with an `"always"` filter and `assertEqual(seen, [])`, or an `"error"` filter that turns any warning into a test failure. ### Running the suite `unittest`'s own runner sets the warning filters to `"default"` for the duration of a run unless you pass `-W` or set `PYTHONWARNINGS`, which is why `DeprecationWarning`s that are invisible in normal execution suddenly appear in test output. Treating deprecations as errors in CI (`-W error::DeprecationWarning`) is a common hardening step — and it interacts with everything above, since an `"error"` filter inside a plain `catch_warnings` block will raise rather than record. ### Reading the filter list Filters are consulted in order and the **first** match wins, which is why `simplefilter` — which inserts its rule at the front of the list — reliably overrides whatever sits behind it, while `warnings.filterwarnings(..., append=True)` puts a rule at the back where an earlier entry may shadow it. The `-W` command-line option and the `PYTHONWARNINGS` environment variable each prepend entries at startup in the same `action:message:category:module:lineno` form, so `-W error::DeprecationWarning` is simply an `"error"` rule at the head of the list. Knowing the ordering is what lets you explain why a filter set in one place appears to have no effect: something more specific, or something inserted later at the front, matched first. The other half of a good deprecation story is `stacklevel`. A warning raised with the default `stacklevel=1` is attributed to the line inside your own function, so both the user-visible location and the `.filename` / `.lineno` that `assertWarns` exposes point at library internals. Passing `stacklevel=2` blames the caller, which is what makes the notice actionable — and it is worth asserting on, because it silently regresses whenever the warning is moved into a helper.