1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29 """Utilities for unit test running from the command line or within the relax testing frame work.
30
31 Unit tests in the relax frame work are stored in a directory structure
32 rooted at <relax-root-directory>/test_suite/unit_tests. The directory
33 unit tests contains a directory structure that mirrors the relax directory
34 structure and which ideally contains one unit test file/module for each
35 file/module in the relax framework. The default convention is that the unit
36 test module for a relax module called <relax-module> is called
37 test_<relax-module> (stored in test_<relax-module>.py). The unit test module
38 test_<relax-module> should then contain a class called Test_<relax-module>
39 which is a child of TestCase and contains methods whose names start with
40 'test' and take no arguments other than self.
41
42 A concrete example: for class <relax-root-directory>/maths-fns/chi2.py FIXME:***complete***
43
44
45 The framework can discover sets of unit tests from the file system and add
46 them to TestSuites either from the command line or programmatically from
47 inside another program. It also has the ability to search for a root unit
48 test and system directory from a position anywhere inside the unit test
49 hierarchy.
50
51 TODO: Examine PEP 338 and runpy.run_module(modulename): Executing Modules as Scripts for a later
52 version of relax that is dependant on python 2.5.
53 TODO: Split out runner part from search part.
54 """
55
56 from copy import copy
57 import os, re, sys, unittest, traceback
58 from optparse import OptionParser
59 from textwrap import dedent
60
61
62 try:
63 from test_suite.relax_test_loader import RelaxTestLoader as TestLoader
64 except ImportError:
65 from unittest import TestLoader
66
67
68
69
70
71 PY_FILE_EXTENSION='.py'
72
73
74
75
76
77
79 """Get the path of the directory the program started from.
80
81 The startup path is the first path in sys.path (the internal PYTHONPATH) by convention. If the
82 first element of sys.path is an empty trying the current working directory is used instead.
83
84 @return: A file system path for the current operating system.
85 @rtype: str
86 """
87
88 startup_path = sys.path[0]
89 if startup_path == '':
90 startup_path = os.getcwd()
91 return startup_path
92
93
95 """Import the python module named by module_path.
96
97 @param module_path: A module path in python dot separated format. Note: this currently doesn't
98 support relative module paths as defined by pep328 and python 2.5.
99 @type module_path: str
100 @return: The module path as a list of module instances or None if the module path
101 cannot be found in the python path.
102 @rtype: list of class module instances or None
103 """
104
105 module = None
106 result = None
107
108
109 module = __import__(module_path)
110
111
112
113
114 if module != None:
115 result = [module]
116 components = module_path.split('.')
117 for component in components[1:]:
118 module = getattr(module, component)
119 result.append(module)
120 return result
121
122
124 """Find the relative path of a module to one of a set of root paths using a list of package paths and a module name.
125
126 As the module may match more than one path the first path that can contain it is chosen.
127
128 @param package_path: Path of a python packages leading to module_name.
129 @type package_path: str
130 @param module_name: The name of the module to load.
131 @type module_name: str
132 @keyword root_paths: A set of paths to search for the module in. If None is passed the list
133 is initialized from the internal PYTHONPATH sys.path. Elements which
134 are empty strings are replace with the current working directory
135 sys.getcwd().
136 @type root_paths: list of str
137 @return: A relative module path to one of the rootPaths which is separated by
138 '.'s if the modulePath is a subpath of one of the root paths, otherwise
139 None.
140 @rtype: str or None
141 """
142
143 relative_path = None
144 if root_paths == None:
145 root_paths = sys.path
146 for root_path in root_paths:
147 root_path = segment_path(os.path.abspath(root_path))
148
149
150 if not isinstance(package_path, list):
151 package_path = segment_path(os.path.abspath(package_path))
152
153 common_prefix = get_common_prefix(root_path, package_path)
154 if common_prefix == root_path:
155 relative_path = package_path[len(common_prefix):]
156 break
157
158 if relative_path != None:
159 relative_path = '.'.join(relative_path)
160
161 if relative_path != '':
162 relative_path = '.'.join((relative_path, module_name))
163 else:
164 relative_path = module_name
165
166
167
168 return relative_path
169
170
172 """Get the common prefix between two paths.
173
174 @param path1: The first path to be compared.
175 @type path1: list of str
176 @param path2: The second path to be compared.
177 @type path2: list of str
178 @return: The common path shared between the two paths starting from the root directory as
179 a list of segments. If there is no common path an empty list is returned.
180 @rtype: list of str
181 """
182
183 result_path = []
184 size = min(len(path1), len(path2))
185 for i in range(size):
186 if path1[i] == None or path2[i] == None:
187 break
188
189 if path1[i] == path2[i]:
190 result_path.append(path1[i])
191 return result_path
192
193
195 """Segment a path into a list of components (drives, files, directories etc).
196
197 @param path: The path to segment.
198 @type path: str
199 @param normalise: Whether to normalise the path before starting.
200 @type normalise: bool
201 @return: A list of path segments.
202 @rtype: list of str
203 """
204
205 if normalise:
206 path = os.path.normpath(path)
207
208 result = []
209 (head, tail) = os.path.split(path)
210 if head =='' or tail == '':
211 result.append(head+tail)
212 else:
213 while head != '' and tail != '':
214 result.append(tail)
215 head, tail = os.path.split(head)
216 result.append(head+tail)
217 result.reverse()
218 return result
219
220
222 """Join a list of path segments (drives, files, directories etc) into a path.
223
224 @param segments: The path segments to join into a path.
225 @type segments: a list of path segments
226 @return: The path containing the joined path segments.
227 @rtype: str
228 """
229
230 if len(segments) == 0:
231 result = ''
232 else:
233 segments_copy = segments[:]
234
235 segments_copy.reverse()
236
237 result = segments_copy.pop()
238 while len(segments_copy) > 0:
239 result = os.path.join(result, segments_copy.pop())
240
241 return result
242
243
244
246 """TestCase class for nicely handling import errors."""
247
248 - def __init__(self, module_name, message):
249 """Set up the import error class.
250
251 @param module_name: The module which could not be imported.
252 @type module_name: str
253 @param message: The formatted traceback message (e.g. from traceback.format_exc()).
254 @type message: str
255 """
256
257
258 super(ImportErrorTestCase, self).__init__('testImportError')
259
260
261 self.module_name = module_name
262 self.message = message
263
264
266 """Unit test module import."""
267
268
269 print("\nImport of the %s module.\n" % self.module_name)
270
271
272 self.fail(self.message)
273
274
276 """Load a testCase from the file system using a package path, file name and class name.
277
278 @param package_path: Full system path of the module file.
279 @type package_path: str
280 @param module_name: Name of the module to load the class from.
281 @type module_name: str
282 @param class_name: Name of the class to load.
283 @type class_name: str
284 @return: The suite of test cases.
285 @rtype: TestSuite instance
286 """
287
288
289 module = get_module_relative_path(package_path, module_name)
290
291
292 try:
293 packages = import_module(module)
294 except:
295
296 suite = unittest.TestSuite()
297
298
299 suite.addTest(ImportErrorTestCase(module, traceback.format_exc()))
300
301
302 return suite
303
304
305 if not packages:
306 return
307
308
309 if not hasattr(packages[-1], class_name):
310 return
311
312
313 clazz = getattr(packages[-1], class_name)
314
315
316 return TestLoader().loadTestsFromTestCase(clazz)
317
318
319
321 """Find and load unit test classes as a hierarchy of TestSuites and TestCases.
322
323 The class provides functions for running or returning the resulting TestSuite and requires a
324 root directory to start searching from.
325
326 TestCases are identified by the class name matching a pattern (pattern_string).
327 """
328
329 suite = unittest.TestSuite()
330 """The root test suite to which testSuites and cases are added."""
331
332 - def __init__(self, root_path=None, pattern_list=[]):
333 """Initialise the unit test finder.
334
335 @keyword root_path: The path to starts searching for unit tests from, all sub
336 directories and files are searched.
337 @type root_path: str
338 @keyword pattern_list: A list of regular expression patterns which identify a file as one
339 containing a unit test TestCase.
340 @type pattern_list: list of str
341 """
342
343 self.root_path = root_path
344 if self.root_path == None:
345 self.root_path = get_startup_path()
346 self.patterns=[]
347 for pattern in pattern_list:
348 self.patterns.append(re.compile(pattern))
349 self.paths_scanned = False
350
351
353 """Scan directories and paths for unit test classes and load them into TestSuites."""
354
355
356 self.suite = unittest.TestSuite()
357
358
359 for (dir_path, dir_names, file_names) in os.walk(self.root_path):
360
361 for file_name in file_names:
362
363 module_found = False
364 for pattern in self.patterns:
365 if pattern.match(file_name):
366 module_found = True
367 break
368
369
370 if not module_found:
371 continue
372
373
374 module_name = os.path.splitext(file_name)[0]
375 class_name = module_name[0].upper() + module_name[1:]
376
377
378 test_case = load_test_case(dir_path, module_name, class_name)
379 if test_case != None:
380 self.suite.addTest(test_case)
381
382
383
385 """Class to run a particular unit test or a directory of unit tests."""
386
387
388 system_path_pattern = ['test_suite' + os.sep + 'unit_tests', os.pardir + os.sep + os.pardir]
389 """@ivar: A search template for the directory in which relax is installed. The directory which relax is installed in is viewed as the the 'PYTHONPATH' of the classes to be tested. It must be unique and defined relative to the test suite. For the current setup in relax this is (\'test_suite\', /'..\'). The first string is a directory structure to match the second string is a relative path from that directory to the system directory. The search is started from the value of root_path in the file system.
390 @type: list of str
391 """
392
393 unit_test_path_pattern = ['test_suite' + os.sep + 'unit_tests', os.curdir]
394 """@ivar: A search template for the directory from which all unit module directories descend. For the current setup in relax this is (\'unit_tests\', \'.\'). The search is started from the value of root_path in the file system.
395 @type: list of str
396 """
397
398 test_case_patterns = ['test_.*\.py$']
399 """@ivar: A list of regex patterns against which files will be
400 tested to see if they are expected to contain unit tests. If
401 the file has the correct pattern the module contained inside the
402 file will be searched for testCases e.g in the case of test_float.py
403 the module to be searched for would be test_float.Test_float.
404 @type: list of str
405 """
406
407 - def __init__(self, root_path=os.curdir, test_module=None, search_for_root_path=True, search_for_unit_test_path=True, verbose=False):
408 """Initialise the unit test runner.
409
410 @keyword root_path: Root path to start searching for modules to unit test from. If the string contains '.' the search starts from the current working directory. Default current working directory.
411 @type root_path: str
412 @keyword test_module: The name of a module to unit test. If the variable is None a search for all unit tests using <test-pattern> will start from <root_path>, if the variable is '.' a search for all unit tests will commence from the current working directory, otherwise it will be used as a module path from the current root_path or CHECKME: ****module_directory_path****. The module name can be in the directory path format used by the current operating system or a unix style path with /'s including a final .py extension or a dotted moudle name.
413 @type test_module: str
414 @keyword search_for_root_path: Whether to carry out a search from the root_directory using self.system_path_pattern to find the directory self.system_directory if no search is carried out self.system_directory is set to None and it is the responsibility of code creating the class to set it before self.run is called.
415 @type search_for_root_path: bool
416 @keyword search_for_unit_test_path: Whether to carry out a search from the root_directory using self.unit_test_path_patter to find the directory self.unit_test_directory if no search is carried out self.unit_test_directory is set to None and it is the responsibility of code creating the class to set it before self.run is called.
417 @type search_for_unit_test_path: bool
418 @keyword verbose: Produce verbose output during testing e.g. directories searched root directories etc.
419 @type verbose: bool
420 """
421
422
423 if root_path == os.curdir:
424 root_path = os.getcwd()
425
426
427 self.root_path = root_path
428
429
430 if ((search_for_root_path) == True or (search_for_unit_test_path == True)) and verbose:
431 print('searching for paths')
432 print('-------------------')
433 print('')
434
435
436 if search_for_root_path:
437 self.system_directory = self.get_first_instance_path(root_path, self.system_path_pattern[0], self.system_path_pattern[1])
438
439 if self.system_directory == None:
440 raise Exception("can't find system directory start from %s" % root_path)
441 else:
442 if verbose:
443 print('search for system directory found: %s' % self.system_directory)
444 else:
445 self.system_directory = None
446
447 if search_for_unit_test_path:
448 self.unit_test_directory = self.get_first_instance_path(root_path, self.unit_test_path_pattern[0], self.unit_test_path_pattern[1])
449 if self.unit_test_directory == None:
450 raise Exception("can't find unit test directory start from %s" % root_path)
451 else:
452 if verbose:
453 print('search for unit test directory found: %s' % self.unit_test_directory)
454 else:
455 self.unit_test_directory = None
456
457
458 if test_module == None:
459 test_module = self.root_path
460 elif test_module == os.curdir:
461 test_module = os.getcwd()
462
463 self.test_module = test_module
464
465
466 self.verbose = verbose
467
468
470 """Get the minimal path searching up the file system to target_directory.
471
472 The algorithm is that we repeatedly chop the end off path and see if the tail of the path matches target_path If it doesn't match we search in the resulting directory by appending target_path and seeing if it exists in the file system. Finally once the required directory structure has been found the offset_path is appended to the found path and the resulting path normalised.
473
474 Note the algorithm understands .. and .
475
476
477 @param path: A directory path to search up.
478 @type path: str
479 @param target_path: A directory to find in the path or below one of the elements in the path.
480 @type target_path: str
481 @keyword offset_path: A relative path offset to add to the path that has been found to give the result directory.
482 @type offset_path: str
483 @return: The path that has been found or None if the path cannot be found by walking up and analysing the current directory structure.
484 @rtype: str
485 """
486
487 seg_path = segment_path(os.path.normpath(path))
488 seg_target_directory = segment_path(target_path)
489 seg_target_directory_len = len(seg_target_directory)
490
491 found_seg_path = None
492 while len(seg_path) > 0 and found_seg_path == None:
493 if seg_path[-seg_target_directory_len:] == seg_target_directory[-seg_target_directory_len:]:
494 found_seg_path = seg_path
495 break
496 else:
497 extended_seg_path = copy(seg_path)
498 extended_seg_path.extend(seg_target_directory)
499 if os.path.exists(os.path.join(*extended_seg_path)):
500 found_seg_path = extended_seg_path
501 break
502
503 seg_path.pop()
504
505 result = None
506 if found_seg_path != None and len(found_seg_path) != 0:
507 seg_offset_path = segment_path(offset_path)
508 found_seg_path.extend(seg_offset_path)
509 result = os.path.normpath(join_path_segments(found_seg_path))
510
511 return result
512
513
515 """Determine the possible paths of the test_module.
516
517 It is assumed that the test_module can be either a path or a python module or package name including dots.
518
519 The following heuristics are used:
520
521 1. If the test_module=None add the value '.'.
522 2. If the test_module ends with a PY_FILE_EXTENSION append test_module with the PY_FILE_EXTENSION removed.
523 3. Add the module_name with .'s converted to /'s and any elements of the form PY_FILE_EXTENSION removed.
524 4. Repeat 2 and 3 with the last element of the path repeated with the first letter capitalised.
525
526 Note: we can't deal with module methods...
527
528
529 @return: A set of possible module names in python '.' separated format.
530 @rtype: str
531 """
532
533 result = []
534
535
536 if test_module == None:
537 result.append(os.curdir)
538 else:
539
540 mpath = []
541 test_module_segments = segment_path(test_module)
542 for elem in test_module_segments:
543 if elem.endswith(PY_FILE_EXTENSION):
544 mpath.append(os.path.splitext(elem)[0])
545 else:
546 mpath.append(elem)
547
548 result.append(tuple(mpath))
549
550 mpath = copy(mpath)
551 mpath.append(mpath[-1].capitalize())
552 result.append(tuple(mpath))
553
554 module_path_elems = test_module.split('.')
555
556 module_norm_path = []
557 for elem in module_path_elems:
558 if elem != PY_FILE_EXTENSION[1:]:
559 module_norm_path.append(elem)
560
561
562
563 elems_ok = True
564 for elem in module_norm_path:
565 if len(segment_path(elem)) > 1:
566 elems_ok = False
567 break
568
569 if elems_ok:
570 result.append(tuple(module_norm_path))
571
572 mpath = copy(module_norm_path)
573 mpath.append(module_norm_path[-1].capitalize())
574 result.append(tuple(mpath))
575
576 return result
577
578
579 - def run(self, runner=None):
580 """Run a unit test or set of unit tests.
581
582 @keyword runner: A unit test runner such as TextTestRunner. None indicates use of the default unit test runner. For an example of how to write a test runner see the python documentation for TextTestRunner in the python source.
583 @type runner: Unit test runner instance (TextTestRunner, BaseGUITestRunner subclass, etc.)
584 @return: A string indicating success or failure of the unit tests run.
585 @rtype: str
586 """
587
588 msg = "Either set self.%s to a %s directory or set search_for_%s_path in self.__init__ to True"
589 if self.unit_test_directory == None:
590 raise Exception(msg % ('unit_test_directory', 'unit test', 'unit_test'))
591 if self.system_directory == None:
592 raise Exception(msg % ('system_directory', 'system', 'root'))
593
594
595 if self.verbose:
596 print('testing units...')
597 print('----------------')
598 print('')
599
600 module_paths = self.paths_from_test_module(self.test_module)
601 if self.verbose:
602 print('root path: ', self.root_path)
603 print('system directory: ', self.system_directory)
604 print('unit test directory:', self.unit_test_directory)
605 print('')
606 for i, elem in enumerate(module_paths):
607 print('module path %d: %s' % (i, elem))
608 print('')
609
610
611 sys.path.pop(0)
612 sys.path.insert(0, self.system_directory)
613
614 tests = None
615
616
617 for module_path in module_paths:
618 module_string = os.path.join(*module_path)
619
620 if os.path.isdir(module_string):
621
622 finder = Test_finder(module_string, self.test_case_patterns)
623 finder.scan_paths()
624 tests = finder.suite
625 break
626
627
628 if tests == None:
629 for module_path in module_paths:
630 print(module_path)
631 path_len = len(module_path)
632 if path_len <= 1:
633 continue
634 elif path_len == 2:
635 print('trying to load 2: ', module_path[0], module_path[1])
636 tests = load_test_case('', module_path[0], module_path[1])
637 else:
638 print('trying to load 3: ', os.path.join(*module_path[:-2]), module_path[-2], module_path[-1])
639 tests = load_test_case(os.path.join(*module_path[:-2]), module_path[-2], module_path[-1])
640 if tests != None:
641 break
642
643 if runner == None:
644 runner = unittest.TextTestRunner()
645
646 if self.verbose:
647 print('results')
648 print('-------')
649 print('')
650
651
652 if tests != None and tests.countTestCases() != 0:
653
654 results = runner.run(tests)
655 result_string = results.wasSuccessful()
656
657 elif tests == None:
658 results = None
659 result_string = 'Error: no test directories found for input module: %s' % self.test_module
660 print(result_string)
661 else:
662 results = None
663 result_string = 'note: no tests found for input module: %s' % self.test_module
664 print(result_string)
665
666
667 return result_string
668
669
670
671
672 if __name__ == '__main__':
673
674 parser = OptionParser()
675 parser.add_option("-v", "--verbose", dest="verbose", help="verbose test ouput", default=False, action='store_true')
676 parser.add_option("-u", "--system", dest="system_directory", help="path to relax top directory which contains test_suite", default=None)
677 parser.add_option("-s", "--utest", dest="unit_test_directory", help="default unit test directory", default=None)
678
679
680 usage = """
681 %%prog [options] [<file-or-dir>...]
682
683 a program to find and run subsets of the relax unit test suite using pyunit.
684 (details of how to write pyunit tests can be found in your python distributions
685 library reference)
686
687
688 arguments:
689 <file-or-dir> = <file-path> | <dir-path> is a list which can contain
690 inter-mixed directories and files
691
692 <file-path> = a file containing a test case class files of the same
693 name with the first letter capitalised
694
695 e.g. maths_fns/test_chi2.py will be assumed to contain
696 a test case class called Test_chi2
697
698 <dir-path> = a path which will be recursivley searched for <file-path>s
699 which end in "*.py".
700 """
701 parser.set_usage(dedent(usage))
702
703
704 (options, args) = parser.parse_args()
705
706
707 search_system = True
708 search_unit = True
709
710
711 if options.system_directory != None:
712 if not os.path.exists(options.system_directory):
713 print("The path to the system directory doeesn't exist")
714 print("provided path: %s" % options.system_directory)
715 print("exiting...")
716 sys.exit(0)
717 search_system = False
718
719
720 if options.unit_test_directory != None:
721 if not os.path.exists(options.unit_test_directory):
722 print("The path to the system directory doeesn't exist")
723 print("provided path: %s" % options.unit_test_directory)
724 print("exiting...")
725 sys.exit(0)
726 search_unit = False
727
728
729 if len(args) < 1:
730 args = [None]
731
732
733 for arg in args:
734
735 runner = Unit_test_runner(test_module=arg, verbose=options.verbose, search_for_unit_test_path=search_unit, search_for_root_path=search_system)
736
737
738 if not search_system:
739 runner.system_directory = options.system_directory
740
741
742 if not search_unit:
743 runner.unit_test_directory = options.unit_test_directory
744
745
746 runner.run()
747