subTest and Parametrization

## The failure path a plain loop gives you A `unittest.TestCase` method is one unit of reporting. When an assertion inside it fails, the assertion helper raises `AssertionError`; that exception unwinds out of the method, unittest's outcome machinery catches it, records one failure against the method's id, and moves on to the next method. **Nothing after the raise executes.** That is exactly right when the method tests one thing, and exactly wrong when the method loops over a table of inputs — the first bad row masks every row behind it, so a twenty-row table with four bugs costs four full edit-and-rerun cycles to drain. The other reflex fix — collecting mismatches into a list and asserting the list is empty at the end — restores the coverage but destroys the diagnosis. You get one `AssertionError` whose message you had to format by hand, no per-case traceback, and nothing the runner can count. ## What subTest actually does `TestCase.subTest` is a context manager, in the standard library since Python 3.4 and semantically unchanged through 3.14. Around its body it reuses the same execution machinery unittest applies to a test method, but tagged as a *sub*test: - it builds a lightweight test-like object carrying the parent test's id plus the keyword arguments you passed; - it runs the body in an executor that catches everything except `KeyboardInterrupt`; - if the body raised, it passes the exception to the result object's `addSubTest` and then exits the `with` normally, so the loop's next iteration starts; - if the body passed, `addSubTest` is still called with no exception, which is how a verbose runner can account for successful cases. The load-bearing consequence is the third bullet: control comes back to the loop after a failure, so a single run reports every bad case at once. ```python CASES = [("1.5", 1.5), ("1,5", 15.0), ("2.5", 25.0)] class ParseTest(unittest.TestCase): def test_all(self): for text, expected in CASES: with self.subTest(text=text): self.assertEqual(parse_qty(text), expected) ``` ## Failure versus error, per case Classification follows the exception type, not the wrapper. If the block raises the test case's `failureException` — `AssertionError` — the case is recorded as a **failure**; any other exception is recorded as an **error** for that case. Either way the loop continues. That surprises people who assume `subTest` only guards assertions: a row that makes the code under test raise `ValueError` is reported against that row and the remaining rows still run. ## What it does not change Three things stay exactly as they were: 1. **The run total counts methods.** A method with fifty cases still prints `Ran 1 test`. Only the failure and error lists grow, and they can hold several entries pointing at the same method. 2. **Fixtures run once.** `setUp` and `tearDown` bracket the whole method, not each case; `addCleanup` callbacks fire after the method finishes. `subTest` is a reporting boundary, not an isolation boundary. 3. **The method's own code is not protected.** Only what is lexically inside the `with` block is guarded; an exception in the loop header or between cases still aborts the method. ## Building the table as data The idiom pairs naturally with a case table declared as data — a list of tuples, dicts or `namedtuple`s at module level or in a class attribute — because the loop body then stays a single assertion and the table is the thing reviewers read. Pass the identifying fields as keyword arguments so the report can name the row, and keep any per-case setup inside the `with` block so a failure cannot half-mutate state the next row reads. ## When to reach for something else `subTest` is the right tool when the same assertion runs over varying data. It is the wrong tool when each case needs its own fixture (build real methods from the table instead, so `setUp` re-runs), or when the cases are genuinely different behaviours rather than different inputs — those deserve separate methods with names that say what they check, because a name is the cheapest documentation a suite has. Other runners offer a decorator that generates one test per row; inside the standard library, `subTest` is the mechanism you have, and it is enough.