Find and return all test modules from the specified start
directory, recursing into subdirectories to find them and return all
tests found within them. Only test files that match the pattern will
be loaded. (Using shell style pattern matching.)
All test modules must be importable from the top level of the project.
If the start directory is not the top level directory then the top
level directory must be specified separately.
If a test package name (directory with '__init__.py') matches the
pattern then the package will be checked for a 'load_tests' function. If
this exists then it will be called with (loader, tests, pattern) unless
the package has already had load_tests called from the same discovery
invocation, in which case the package module object is not scanned for
tests - this ensures that when a package uses discover to further
discover child tests that infinite recursion does not happen.
If load_tests exists then discovery does *not* recurse into the package,
load_tests is responsible for loading all tests in the package.
The pattern is deliberately not stored as a loader attribute so that
packages can continue discovery themselves. top_level_dir is stored so
load_tests does not need to pass this argument in to loader.discover().
Paths are sorted before being imported to ensure reproducible execution
order even on filesystems with non-alphabetical ordering like ext3/4.
3.4: Modules that raise SkipTest on import are recorded as skips, not errors. start_dir can be a namespace packages. Paths are sorted before being imported so that execution order is the same even if the underlying file system’s ordering is not dependent on file name.
3.5: Found packages are now checked for load_tests regardless of whether their path matches pattern, because it is impossible for a package name to match the default pattern.
3.11: start_dir can not be a namespace packages. It has been broken since Python 3.7, and Python 3.11 officially removes it.
3.13: top_level_dir is only stored for the duration of discover call.
3.14: start_dir can once again be a namespace package.