Why does `python -m unittest discover` report zero tests in a directory full of `test_*.py` files?

Discovery is a directory walk plus an import, and almost every "it finds nothing" report is one of those two halves failing quietly. ### The algorithm `python -m unittest discover` takes three options that map onto `unittest.TestLoader.discover`: - `-s START` — where the walk begins. Default: the current directory. - `-p PATTERN` — the file-name glob. Default: `test*.py`. - `-t TOP` — the top-level directory of the project. Default: the same as the start directory. The top-level directory is placed on `sys.path` and every discovered file's module name is computed relative to it. Then the walk begins. For each entry in the start directory, sorted by name: a file matching the pattern is imported as a module and scanned for `unittest.TestCase` subclasses; a directory is descended into **only if it contains an `__init__.py`**. ### Cause one: the directory is not a package That last rule is the classic trap. Support for namespace packages in discovery was removed in Python 3.11 (it had been broken since 3.7), so a `tests/` directory with no `__init__.py` is not a candidate — it is skipped with no message at all, and the run prints `Ran 0 tests` and `NO TESTS RAN`. What makes this genuinely confusing is that the *import system* is perfectly happy with such a directory: `python -m unittest tests.test_csv_import` imports it as a namespace package and runs fine. So a suite can be runnable by name and invisible to discovery at the same time. Adding an empty `__init__.py` fixes it. The mirror-image failure is loud. Point the start directory somewhere below an explicit top level, as in `python -m unittest discover -s tests -t .`, and the two directories differ; discovery then insists the start directory be importable from the top level and raises `ImportError: Start directory is not importable` when `tests/__init__.py` is missing. Note the asymmetry: `-s tests` on its own does *not* raise, because with no `-t` the top-level defaults to the start directory, which is then simply put on `sys.path` and walked as a plain folder. ### Cause two: the file name does not match The default pattern is `test*.py`, matched with shell-glob semantics against the base name. `test_csv_import.py` matches; `csv_import_test.py`, `check_csv.py` and `tests.py` inside a package do not. Teams that use the suffix convention need `-p '*_test.py'` on every invocation, which is a good reason to wrap the command in a make target or a project script rather than relying on everyone remembering it. One more subtlety about the pattern: it is applied to files, never to directory names. A directory called `checks` full of `test_*.py` files is walked normally as long as it is a package, and a directory called `tests` earns no special treatment for its name alone. The `__init__.py` of a package is not itself matched against the pattern either — it is imported because the package is imported, which is what makes it a useful place to hook discovery for a whole subtree. ### What discovery does when a match fails to import A matched file that raises during import is not skipped. Discovery substitutes a placeholder test that re-raises the import error, so the run reports it as an **error** with the original traceback and exits non-zero. That is deliberate: a test module that cannot be imported is a failing test, not an absent one. Reading that traceback usually points straight at a missing dependency or a circular import in the module under test. ### Ordering and reproducibility Entries are sorted, and within a `unittest.TestCase` the method names are sorted too, so a discovery run is deterministic on a given tree. It is *not* stable against edits: adding `test_aaa_rates.py` changes what runs before what, which is how a latent inter-test dependency surfaces on an unrelated commit. ### Diagnosing it in practice Work the two halves in order. First check the walk: `python -m unittest discover -v` prints each test it loaded, so an empty list means nothing was matched or descended into. Then check the import by naming a module directly, `python -m unittest tests.test_csv_import` — if that works while discovery finds nothing, the difference is the missing `__init__.py`, because named loading tolerates a namespace package and the walk does not. If the direct name fails too, it is an import problem and the traceback tells you which. ### What to say in an interview Name the default pattern, the `__init__.py` requirement on every directory walked, and the `-s`/`-p`/`-t` split — especially that `-t` is the thing that lands on `sys.path` and anchors module names. Mentioning that namespace-package discovery was dropped in 3.11 shows you know why so much older advice on this is now wrong.