Debian Codegraph @

Lib/unittest/loader.py

raw
1 """Loading unittests."""
2
3 import os
4 import re
5 import sys
6 import traceback
7 import types
8 import functools
9
10 from fnmatch import fnmatch, fnmatchcase
11
12 from . import case, suite, util
13
14 __unittest = True
15
16 # what about .pyc (etc)
17 # we would need to avoid loading the same tests multiple times
18 # from '.py', *and* '.pyc'
19 VALID_MODULE_NAME = re.compile(r'[_a-z]\w*\.py$', re.IGNORECASE)
20
21
22 class _FailedTest(case.TestCase):
23 _testMethodName = None
24
25 def __init__(self, method_name, exception):
26 self._exception = exception
27 super(_FailedTest, self).__init__(method_name)
28
29 def __getattr__(self, name):
30 if name != self._testMethodName:
31 return super(_FailedTest, self).__getattr__(name)
32 def testFailure():
33 raise self._exception
34 return testFailure
35
36
37 def _make_failed_import_test(name, suiteClass):
38 message = 'Failed to import test module: %s\n%s' % (
39 name, traceback.format_exc())
40 return _make_failed_test(name, ImportError(message), suiteClass, message)
41
42 def _make_failed_load_tests(name, exception, suiteClass):
43 message = 'Failed to call load_tests:\n%s' % (traceback.format_exc(),)
44 return _make_failed_test(
45 name, exception, suiteClass, message)
46
47 def _make_failed_test(methodname, exception, suiteClass, message):
48 test = _FailedTest(methodname, exception)
49 return suiteClass((test,)), message
50
51 def _make_skipped_test(methodname, exception, suiteClass):
52 @case.skip(str(exception))
53 def testSkipped(self):
54 pass
55 attrs = {methodname: testSkipped}
56 TestClass = type("ModuleSkipped", (case.TestCase,), attrs)
57 return suiteClass((TestClass(methodname),))
58
59 def _splitext(path):
60 return os.path.splitext(path)[0]
61
62
63 class TestLoader(object):
64 """
65 This class is responsible for loading tests according to various criteria
66 and returning them wrapped in a TestSuite
67 """
68 testMethodPrefix = 'test'
69 sortTestMethodsUsing = staticmethod(util.three_way_cmp)
70 testNamePatterns = None
71 suiteClass = suite.TestSuite
72 _top_level_dir = None
73
74 def __init__(self):
75 super(TestLoader, self).__init__()
76 self.errors = []
77 # Tracks packages which we have called into via load_tests, to
78 # avoid infinite re-entrancy.
79 self._loading_packages = set()
80
81 def loadTestsFromTestCase(self, testCaseClass):
82 """Return a suite of all test cases contained in testCaseClass"""
83 if issubclass(testCaseClass, suite.TestSuite):
84 raise TypeError("Test cases should not be derived from "
85 "TestSuite. Maybe you meant to derive from "
86 "TestCase?")
87 if testCaseClass in (case.TestCase, case.FunctionTestCase):
88 # We don't load any tests from base types that should not be loaded.
89 testCaseNames = []
90 else:
91 testCaseNames = self.getTestCaseNames(testCaseClass)
92 if not testCaseNames and hasattr(testCaseClass, 'runTest'):
93 testCaseNames = ['runTest']
94 loaded_suite = self.suiteClass(map(testCaseClass, testCaseNames))
95 return loaded_suite
96
97 def loadTestsFromModule(self, module, *, pattern=None):
98 """Return a suite of all test cases contained in the given module"""
99 tests = []
100 for name in dir(module):
101 obj = getattr(module, name)
102 if (
103 isinstance(obj, type)
104 and issubclass(obj, case.TestCase)
105 and obj not in (case.TestCase, case.FunctionTestCase)
106 ):
107 tests.append(self.loadTestsFromTestCase(obj))
108
109 load_tests = getattr(module, 'load_tests', None)
110 tests = self.suiteClass(tests)
111 if load_tests is not None:
112 try:
113 return load_tests(self, tests, pattern)
114 except Exception as e:
115 error_case, error_message = _make_failed_load_tests(
116 module.__name__, e, self.suiteClass)
117 self.errors.append(error_message)
118 return error_case
119 return tests
120
121 def loadTestsFromName(self, name, module=None):
122 """Return a suite of all test cases given a string specifier.
123
124 The name may resolve either to a module, a test case class, a
125 test method within a test case class, or a callable object which
126 returns a TestCase or TestSuite instance.
127
128 The method optionally resolves the names relative to a given module.
129 """
130 parts = name.split('.')
131 error_case, error_message = None, None
132 if module is None:
133 parts_copy = parts[:]
134 while parts_copy:
135 try:
136 module_name = '.'.join(parts_copy)
137 module = __import__(module_name)
138 break
139 except ImportError:
140 next_attribute = parts_copy.pop()
141 # Last error so we can give it to the user if needed.
142 error_case, error_message = _make_failed_import_test(
143 next_attribute, self.suiteClass)
144 if not parts_copy:
145 # Even the top level import failed: report that error.
146 self.errors.append(error_message)
147 return error_case
148 parts = parts[1:]
149 obj = module
150 for part in parts:
151 try:
152 parent, obj = obj, getattr(obj, part)
153 except AttributeError as e:
154 # We can't traverse some part of the name.
155 if (getattr(obj, '__path__', None) is not None
156 and error_case is not None):
157 # This is a package (no __path__ per importlib docs), and we
158 # encountered an error importing something. We cannot tell
159 # the difference between package.WrongNameTestClass and
160 # package.wrong_module_name so we just report the
161 # ImportError - it is more informative.
162 self.errors.append(error_message)
163 return error_case
164 else:
165 # Otherwise, we signal that an AttributeError has occurred.
166 error_case, error_message = _make_failed_test(
167 part, e, self.suiteClass,
168 'Failed to access attribute:\n%s' % (
169 traceback.format_exc(),))
170 self.errors.append(error_message)
171 return error_case
172
173 if isinstance(obj, types.ModuleType):
174 return self.loadTestsFromModule(obj)
175 elif (
176 isinstance(obj, type)
177 and issubclass(obj, case.TestCase)
178 and obj not in (case.TestCase, case.FunctionTestCase)
179 ):
180 return self.loadTestsFromTestCase(obj)
181 elif (isinstance(obj, types.FunctionType) and
182 isinstance(parent, type) and
183 issubclass(parent, case.TestCase)):
184 name = parts[-1]
185 inst = parent(name)
186 # static methods follow a different path
187 if not isinstance(getattr(inst, name), types.FunctionType):
188 return self.suiteClass([inst])
189 elif isinstance(obj, suite.TestSuite):
190 return obj
191 if callable(obj):
192 test = obj()
193 if isinstance(test, suite.TestSuite):
194 return test
195 elif isinstance(test, case.TestCase):
196 return self.suiteClass([test])
197 else:
198 raise TypeError("calling %s returned %s, not a test" %
199 (obj, test))
200 else:
201 raise TypeError("don't know how to make test from: %s" % obj)
202
203 def loadTestsFromNames(self, names, module=None):
204 """Return a suite of all test cases found using the given sequence
205 of string specifiers. See 'loadTestsFromName()'.
206 """
207 suites = [self.loadTestsFromName(name, module) for name in names]
208 return self.suiteClass(suites)
209
210 def getTestCaseNames(self, testCaseClass):
211 """Return a sorted sequence of method names found within testCaseClass
212 """
213 def shouldIncludeMethod(attrname):
214 if not attrname.startswith(self.testMethodPrefix):
215 return False
216 testFunc = getattr(testCaseClass, attrname)
217 if not callable(testFunc):
218 return False
219 fullName = f'%s.%s.%s' % (
220 testCaseClass.__module__, testCaseClass.__qualname__, attrname
221 )
222 return self.testNamePatterns is None or \
223 any(fnmatchcase(fullName, pattern) for pattern in self.testNamePatterns)
224 testFnNames = list(filter(shouldIncludeMethod, dir(testCaseClass)))
225 if self.sortTestMethodsUsing:
226 testFnNames.sort(key=functools.cmp_to_key(self.sortTestMethodsUsing))
227 return testFnNames
228
229 def discover(self, start_dir, pattern='test*.py', top_level_dir=None):
230 """Find and return all test modules from the specified start
231 directory, recursing into subdirectories to find them and return all
232 tests found within them. Only test files that match the pattern will
233 be loaded. (Using shell style pattern matching.)
234
235 All test modules must be importable from the top level of the project.
236 If the start directory is not the top level directory then the top
237 level directory must be specified separately.
238
239 If a test package name (directory with '__init__.py') matches the
240 pattern then the package will be checked for a 'load_tests' function. If
241 this exists then it will be called with (loader, tests, pattern) unless
242 the package has already had load_tests called from the same discovery
243 invocation, in which case the package module object is not scanned for
244 tests - this ensures that when a package uses discover to further
245 discover child tests that infinite recursion does not happen.
246
247 If load_tests exists then discovery does *not* recurse into the package,
248 load_tests is responsible for loading all tests in the package.
249
250 The pattern is deliberately not stored as a loader attribute so that
251 packages can continue discovery themselves. top_level_dir is stored so
252 load_tests does not need to pass this argument in to loader.discover().
253
254 Paths are sorted before being imported to ensure reproducible execution
255 order even on filesystems with non-alphabetical ordering like ext3/4.
256 """
257 original_top_level_dir = self._top_level_dir
258 set_implicit_top = False
259 if top_level_dir is None and self._top_level_dir is not None:
260 # make top_level_dir optional if called from load_tests in a package
261 top_level_dir = self._top_level_dir
262 elif top_level_dir is None:
263 set_implicit_top = True
264 top_level_dir = start_dir
265
266 top_level_dir = os.path.abspath(top_level_dir)
267
268 if not top_level_dir in sys.path:
269 # all test modules must be importable from the top level directory
270 # should we *unconditionally* put the start directory in first
271 # in sys.path to minimise likelihood of conflicts between installed
272 # modules and development versions?
273 sys.path.insert(0, top_level_dir)
274 self._top_level_dir = top_level_dir
275
276 is_not_importable = False
277 is_namespace = False
278 tests = []
279 if os.path.isdir(os.path.abspath(start_dir)):
280 start_dir = os.path.abspath(start_dir)
281 if start_dir != top_level_dir:
282 is_not_importable = not os.path.isfile(os.path.join(start_dir, '__init__.py'))
283 else:
284 # support for discovery from dotted module names
285 try:
286 __import__(start_dir)
287 except ImportError:
288 is_not_importable = True
289 else:
290 the_module = sys.modules[start_dir]
291 if not hasattr(the_module, "__file__") or the_module.__file__ is None:
292 # look for namespace packages
293 try:
294 spec = the_module.__spec__
295 except AttributeError:
296 spec = None
297
298 if spec and spec.submodule_search_locations is not None:
299 is_namespace = True
300
301 for path in the_module.__path__:
302 if (not set_implicit_top and
303 not path.startswith(top_level_dir)):
304 continue
305 self._top_level_dir = \
306 (path.split(the_module.__name__
307 .replace(".", os.path.sep))[0])
308 tests.extend(self._find_tests(path, pattern, namespace=True))
309 elif the_module.__name__ in sys.builtin_module_names:
310 # builtin module
311 raise TypeError('Can not use builtin modules '
312 'as dotted module names') from None
313 else:
314 raise TypeError(
315 f"don't know how to discover from {the_module!r}"
316 ) from None
317
318 else:
319 top_part = start_dir.split('.')[0]
320 start_dir = os.path.abspath(os.path.dirname((the_module.__file__)))
321
322 if set_implicit_top:
323 if not is_namespace:
324 if sys.modules[top_part].__file__ is None:
325 self._top_level_dir = os.path.dirname(the_module.__file__)
326 if self._top_level_dir not in sys.path:
327 sys.path.insert(0, self._top_level_dir)
328 else:
329 self._top_level_dir = \
330 self._get_directory_containing_module(top_part)
331 sys.path.remove(top_level_dir)
332
333 if is_not_importable:
334 raise ImportError('Start directory is not importable: %r' % start_dir)
335
336 if not is_namespace:
337 tests = list(self._find_tests(start_dir, pattern))
338
339 self._top_level_dir = original_top_level_dir
340 return self.suiteClass(tests)
341
342 def _get_directory_containing_module(self, module_name):
343 module = sys.modules[module_name]
344 full_path = os.path.abspath(module.__file__)
345
346 if os.path.basename(full_path).lower().startswith('__init__.py'):
347 return os.path.dirname(os.path.dirname(full_path))
348 else:
349 # here we have been given a module rather than a package - so
350 # all we can do is search the *same* directory the module is in
351 # should an exception be raised instead
352 return os.path.dirname(full_path)
353
354 def _get_name_from_path(self, path):
355 if path == self._top_level_dir:
356 return '.'
357 path = _splitext(os.path.normpath(path))
358
359 _relpath = os.path.relpath(path, self._top_level_dir)
360 assert not os.path.isabs(_relpath), "Path must be within the project"
361 assert not _relpath.startswith('..'), "Path must be within the project"
362
363 name = _relpath.replace(os.path.sep, '.')
364 return name
365
366 def _get_module_from_name(self, name):
367 __import__(name)
368 return sys.modules[name]
369
370 def _match_path(self, path, full_path, pattern):
371 # override this method to use alternative matching strategy
372 return fnmatch(path, pattern)
373
374 def _find_tests(self, start_dir, pattern, namespace=False):
375 """Used by discovery. Yields test suites it loads."""
376 # Handle the __init__ in this package
377 name = self._get_name_from_path(start_dir)
378 # name is '.' when start_dir == top_level_dir (and top_level_dir is by
379 # definition not a package).
380 if name != '.' and name not in self._loading_packages:
381 # name is in self._loading_packages while we have called into
382 # loadTestsFromModule with name.
383 tests, should_recurse = self._find_test_path(
384 start_dir, pattern, namespace)
385 if tests is not None:
386 yield tests
387 if not should_recurse:
388 # Either an error occurred, or load_tests was used by the
389 # package.
390 return
391 # Handle the contents.
392 paths = sorted(os.listdir(start_dir))
393 for path in paths:
394 full_path = os.path.join(start_dir, path)
395 tests, should_recurse = self._find_test_path(
396 full_path, pattern, False)
397 if tests is not None:
398 yield tests
399 if should_recurse:
400 # we found a package that didn't use load_tests.
401 name = self._get_name_from_path(full_path)
402 self._loading_packages.add(name)
403 try:
404 yield from self._find_tests(full_path, pattern, False)
405 finally:
406 self._loading_packages.discard(name)
407
408 def _find_test_path(self, full_path, pattern, namespace=False):
409 """Used by discovery.
410
411 Loads tests from a single file, or a directories' __init__.py when
412 passed the directory.
413
414 Returns a tuple (None_or_tests_from_file, should_recurse).
415 """
416 basename = os.path.basename(full_path)
417 if os.path.isfile(full_path):
418 if not VALID_MODULE_NAME.match(basename):
419 # valid Python identifiers only
420 return None, False
421 if not self._match_path(basename, full_path, pattern):
422 return None, False
423 # if the test file matches, load it
424 name = self._get_name_from_path(full_path)
425 try:
426 module = self._get_module_from_name(name)
427 except case.SkipTest as e:
428 return _make_skipped_test(name, e, self.suiteClass), False
429 except:
430 error_case, error_message = \
431 _make_failed_import_test(name, self.suiteClass)
432 self.errors.append(error_message)
433 return error_case, False
434 else:
435 mod_file = os.path.abspath(
436 getattr(module, '__file__', full_path))
437 realpath = _splitext(
438 os.path.realpath(mod_file))
439 fullpath_noext = _splitext(
440 os.path.realpath(full_path))
441 if realpath.lower() != fullpath_noext.lower():
442 module_dir = os.path.dirname(realpath)
443 mod_name = _splitext(
444 os.path.basename(full_path))
445 expected_dir = os.path.dirname(full_path)
446 msg = ("%r module incorrectly imported from %r. Expected "
447 "%r. Is this module globally installed?")
448 raise ImportError(
449 msg % (mod_name, module_dir, expected_dir))
450 return self.loadTestsFromModule(module, pattern=pattern), False
451 elif os.path.isdir(full_path):
452 if (not namespace and
453 not os.path.isfile(os.path.join(full_path, '__init__.py'))):
454 return None, False
455
456 load_tests = None
457 tests = None
458 name = self._get_name_from_path(full_path)
459 try:
460 package = self._get_module_from_name(name)
461 except case.SkipTest as e:
462 return _make_skipped_test(name, e, self.suiteClass), False
463 except:
464 error_case, error_message = \
465 _make_failed_import_test(name, self.suiteClass)
466 self.errors.append(error_message)
467 return error_case, False
468 else:
469 load_tests = getattr(package, 'load_tests', None)
470 # Mark this package as being in load_tests (possibly ;))
471 self._loading_packages.add(name)
472 try:
473 tests = self.loadTestsFromModule(package, pattern=pattern)
474 if load_tests is not None:
475 # loadTestsFromModule(package) has loaded tests for us.
476 return tests, False
477 return tests, True
478 finally:
479 self._loading_packages.discard(name)
480 else:
481 return None, False
482
483
484 defaultTestLoader = TestLoader()