How do you build and run a unittest suite programmatically with TestLoader and TextTestRunner?

`python -m unittest` is convenience over an ordinary object API, and knowing that API is what lets you build a harness when the command line runs out. ### The three roles **`unittest.TestLoader` produces tests.** Its methods differ only in what they accept: `loadTestsFromTestCase(cls)` takes a `unittest.TestCase` subclass and returns a suite of its `test`-prefixed methods; `loadTestsFromModule(mod)` takes an imported module; `loadTestsFromName(name, module=None)` takes the same dotted string the command line accepts; `discover(start_dir, pattern, top_level_dir)` runs the directory walk. Two class attributes tune it: `testMethodPrefix`, which defaults to `'test'`, and `sortTestMethodsUsing`, which decides the order of methods within a class. `unittest.defaultTestLoader` is a ready-made shared instance. **`unittest.TestSuite` holds them.** It is a composite: it contains tests *and* other suites, and iterating one yields the leaves. Build it with `addTest` for one item or `addTests` for an iterable. Nothing about a suite runs anything — it is a plan. **`unittest.TextTestRunner` executes.** Construct it with options such as `verbosity=2`, `failfast=True` and `buffer=True` — the direct equivalents of `-v`, `-f` and `-b` — then call `run(suite)`. It returns a `unittest.TestResult` carrying counts and the collected failures and errors, and exposing `wasSuccessful()`. The runner writes its report to stderr and never exits the process, which is the important difference from the next section. ### Versus `unittest.main()` `unittest.main()` is a full command-line program in a function: it parses `sys.argv`, applies `-v`, `-k` and friends, loads tests from the calling module by default, runs them, and then calls `sys.exit` with a status derived from the result. That last step is why embedding `unittest.main()` inside a larger program is a trap — it will terminate the process. Driving the loader, suite and runner yourself gives you the result object and lets you decide what to do with it, including exiting with your own code. ### When to use each Prefer the command line. Reach for the object API only when it buys something real: - Building a suite from data — for example, a payroll import checked against a table of CSV fixtures, where the cases are rows rather than hand-written methods. - Running tests from inside another program, such as a self-check subcommand of a tool. - Wrapping the run with setup or reporting that has to happen in the same process. When the customisation logically belongs to a *test module* rather than to a driver script, use the `load_tests` protocol instead. Define `load_tests(loader, standard_tests, pattern)` at module level, return the suite you want, and both discovery and `unittest.main()` will call it in place of the default scan. Placed in a package `__init__.py`, the same hook customises discovery for that whole package. It keeps the customisation next to the tests and preserves one entry point, which a bespoke runner script does not. ### Pitfalls The suite is a plan, so a mistake there is silent: adding a `unittest.TestCase` *class* instead of the suite returned by `loadTestsFromTestCase` gives you something that does not run as you expect. Forgetting to check `wasSuccessful()` gives a script that exits zero on a red suite, which is worse than no script at all. And a hand-rolled runner drifts from what CI runs unless it is the same code path — if you build one, make it the only entry point rather than a second one. ### What to say in an interview Name the three objects and their one job each, note that `run` returns a result rather than exiting, and say when you would use `load_tests` instead of a script. The senior signal is arguing *against* a custom runner in most cases: the standard entry point keeps local runs and CI identical, and every bespoke harness is a thing to maintain.