0001 """ 0002 Test script for doctest. 0003 """ 0004 0005 from test import test_support 0006 import doctest 0007 import warnings 0008 0009 ###################################################################### 0010 ## Sample Objects (used by test cases) 0011 ###################################################################### 0012 0013 def sample_func(v): 0014 """ 0015 Blah blah 0016 0017 >>> print sample_func(22) 0018 44 0019 0020 Yee ha! 0021 """ 0022 return v+v 0023 0024 class SampleClass: 0025 """ 0026 >>> print 1 0027 1 0028 0029 >>> # comments get ignored. so are empty PS1 and PS2 prompts: 0030 >>> 0031 ... 0032 0033 Multiline example: 0034 >>> sc = SampleClass(3) 0035 >>> for i in range(10): 0036 ... sc = sc.double() 0037 ... print sc.get(), 0038 6 12 24 48 96 192 384 768 1536 3072 0039 """ 0040 def __init__(self, val): 0041 """ 0042 >>> print SampleClass(12).get() 0043 12 0044 """ 0045 self.val = val 0046 0047 def double(self): 0048 """ 0049 >>> print SampleClass(12).double().get() 0050 24 0051 """ 0052 return SampleClass(self.val + self.val) 0053 0054 def get(self): 0055 """ 0056 >>> print SampleClass(-5).get() 0057 -5 0058 """ 0059 return self.val 0060 0061 def a_staticmethod(v): 0062 """ 0063 >>> print SampleClass.a_staticmethod(10) 0064 11 0065 """ 0066 return v+1 0067 a_staticmethod = staticmethod(a_staticmethod) 0068 0069 def a_classmethod(cls, v): 0070 """ 0071 >>> print SampleClass.a_classmethod(10) 0072 12 0073 >>> print SampleClass(0).a_classmethod(10) 0074 12 0075 """ 0076 return v+2 0077 a_classmethod = classmethod(a_classmethod) 0078 0079 a_property = property(get, doc=""" 0080 >>> print SampleClass(22).a_property 0081 22 0082 """) 0083 0084 class NestedClass: 0085 """ 0086 >>> x = SampleClass.NestedClass(5) 0087 >>> y = x.square() 0088 >>> print y.get() 0089 25 0090 """ 0091 def __init__(self, val=0): 0092 """ 0093 >>> print SampleClass.NestedClass().get() 0094 0 0095 """ 0096 self.val = val 0097 def square(self): 0098 return SampleClass.NestedClass(self.val*self.val) 0099 def get(self): 0100 return self.val 0101 0102 class SampleNewStyleClass(object): 0103 r""" 0104 >>> print '1\n2\n3' 0105 1 0106 2 0107 3 0108 """ 0109 def __init__(self, val): 0110 """ 0111 >>> print SampleNewStyleClass(12).get() 0112 12 0113 """ 0114 self.val = val 0115 0116 def double(self): 0117 """ 0118 >>> print SampleNewStyleClass(12).double().get() 0119 24 0120 """ 0121 return SampleNewStyleClass(self.val + self.val) 0122 0123 def get(self): 0124 """ 0125 >>> print SampleNewStyleClass(-5).get() 0126 -5 0127 """ 0128 return self.val 0129 0130 ###################################################################### 0131 ## Fake stdin (for testing interactive debugging) 0132 ###################################################################### 0133 0134 class _FakeInput: 0135 """ 0136 A fake input stream for pdb's interactive debugger. Whenever a 0137 line is read, print it (to simulate the user typing it), and then 0138 return it. The set of lines to return is specified in the 0139 constructor; they should not have trailing newlines. 0140 """ 0141 def __init__(self, lines): 0142 self.lines = lines 0143 0144 def readline(self): 0145 line = self.lines.pop(0) 0146 print line 0147 return line+'\n' 0148 0149 ###################################################################### 0150 ## Test Cases 0151 ###################################################################### 0152 0153 def test_Example(): r""" 0154 Unit tests for the `Example` class. 0155 0156 Example is a simple container class that holds: 0157 - `source`: A source string. 0158 - `want`: An expected output string. 0159 - `exc_msg`: An expected exception message string (or None if no 0160 exception is expected). 0161 - `lineno`: A line number (within the docstring). 0162 - `indent`: The example's indentation in the input string. 0163 - `options`: An option dictionary, mapping option flags to True or 0164 False. 0165 0166 These attributes are set by the constructor. `source` and `want` are 0167 required; the other attributes all have default values: 0168 0169 >>> example = doctest.Example('print 1', '1\n') 0170 >>> (example.source, example.want, example.exc_msg, 0171 ... example.lineno, example.indent, example.options) 0172 ('print 1\n', '1\n', None, 0, 0, {}) 0173 0174 The first three attributes (`source`, `want`, and `exc_msg`) may be 0175 specified positionally; the remaining arguments should be specified as 0176 keyword arguments: 0177 0178 >>> exc_msg = 'IndexError: pop from an empty list' 0179 >>> example = doctest.Example('[].pop()', '', exc_msg, 0180 ... lineno=5, indent=4, 0181 ... options={doctest.ELLIPSIS: True}) 0182 >>> (example.source, example.want, example.exc_msg, 0183 ... example.lineno, example.indent, example.options) 0184 ('[].pop()\n', '', 'IndexError: pop from an empty list\n', 5, 4, {8: True}) 0185 0186 The constructor normalizes the `source` string to end in a newline: 0187 0188 Source spans a single line: no terminating newline. 0189 >>> e = doctest.Example('print 1', '1\n') 0190 >>> e.source, e.want 0191 ('print 1\n', '1\n') 0192 0193 >>> e = doctest.Example('print 1\n', '1\n') 0194 >>> e.source, e.want 0195 ('print 1\n', '1\n') 0196 0197 Source spans multiple lines: require terminating newline. 0198 >>> e = doctest.Example('print 1;\nprint 2\n', '1\n2\n') 0199 >>> e.source, e.want 0200 ('print 1;\nprint 2\n', '1\n2\n') 0201 0202 >>> e = doctest.Example('print 1;\nprint 2', '1\n2\n') 0203 >>> e.source, e.want 0204 ('print 1;\nprint 2\n', '1\n2\n') 0205 0206 Empty source string (which should never appear in real examples) 0207 >>> e = doctest.Example('', '') 0208 >>> e.source, e.want 0209 ('\n', '') 0210 0211 The constructor normalizes the `want` string to end in a newline, 0212 unless it's the empty string: 0213 0214 >>> e = doctest.Example('print 1', '1\n') 0215 >>> e.source, e.want 0216 ('print 1\n', '1\n') 0217 0218 >>> e = doctest.Example('print 1', '1') 0219 >>> e.source, e.want 0220 ('print 1\n', '1\n') 0221 0222 >>> e = doctest.Example('print', '') 0223 >>> e.source, e.want 0224 ('print\n', '') 0225 0226 The constructor normalizes the `exc_msg` string to end in a newline, 0227 unless it's `None`: 0228 0229 Message spans one line 0230 >>> exc_msg = 'IndexError: pop from an empty list' 0231 >>> e = doctest.Example('[].pop()', '', exc_msg) 0232 >>> e.exc_msg 0233 'IndexError: pop from an empty list\n' 0234 0235 >>> exc_msg = 'IndexError: pop from an empty list\n' 0236 >>> e = doctest.Example('[].pop()', '', exc_msg) 0237 >>> e.exc_msg 0238 'IndexError: pop from an empty list\n' 0239 0240 Message spans multiple lines 0241 >>> exc_msg = 'ValueError: 1\n 2' 0242 >>> e = doctest.Example('raise ValueError("1\n 2")', '', exc_msg) 0243 >>> e.exc_msg 0244 'ValueError: 1\n 2\n' 0245 0246 >>> exc_msg = 'ValueError: 1\n 2\n' 0247 >>> e = doctest.Example('raise ValueError("1\n 2")', '', exc_msg) 0248 >>> e.exc_msg 0249 'ValueError: 1\n 2\n' 0250 0251 Empty (but non-None) exception message (which should never appear 0252 in real examples) 0253 >>> exc_msg = '' 0254 >>> e = doctest.Example('raise X()', '', exc_msg) 0255 >>> e.exc_msg 0256 '\n' 0257 """ 0258 0259 def test_DocTest(): r""" 0260 Unit tests for the `DocTest` class. 0261 0262 DocTest is a collection of examples, extracted from a docstring, along 0263 with information about where the docstring comes from (a name, 0264 filename, and line number). The docstring is parsed by the `DocTest` 0265 constructor: 0266 0267 >>> docstring = ''' 0268 ... >>> print 12 0269 ... 12 0270 ... 0271 ... Non-example text. 0272 ... 0273 ... >>> print 'another\example' 0274 ... another 0275 ... example 0276 ... ''' 0277 >>> globs = {} # globals to run the test in. 0278 >>> parser = doctest.DocTestParser() 0279 >>> test = parser.get_doctest(docstring, globs, 'some_test', 0280 ... 'some_file', 20) 0281 >>> print test 0282 <DocTest some_test from some_file:20 (2 examples)> 0283 >>> len(test.examples) 0284 2 0285 >>> e1, e2 = test.examples 0286 >>> (e1.source, e1.want, e1.lineno) 0287 ('print 12\n', '12\n', 1) 0288 >>> (e2.source, e2.want, e2.lineno) 0289 ("print 'another\\example'\n", 'another\nexample\n', 6) 0290 0291 Source information (name, filename, and line number) is available as 0292 attributes on the doctest object: 0293 0294 >>> (test.name, test.filename, test.lineno) 0295 ('some_test', 'some_file', 20) 0296 0297 The line number of an example within its containing file is found by 0298 adding the line number of the example and the line number of its 0299 containing test: 0300 0301 >>> test.lineno + e1.lineno 0302 21 0303 >>> test.lineno + e2.lineno 0304 26 0305 0306 If the docstring contains inconsistant leading whitespace in the 0307 expected output of an example, then `DocTest` will raise a ValueError: 0308 0309 >>> docstring = r''' 0310 ... >>> print 'bad\nindentation' 0311 ... bad 0312 ... indentation 0313 ... ''' 0314 >>> parser.get_doctest(docstring, globs, 'some_test', 'filename', 0) 0315 Traceback (most recent call last): 0316 ValueError: line 4 of the docstring for some_test has inconsistent leading whitespace: 'indentation' 0317 0318 If the docstring contains inconsistent leading whitespace on 0319 continuation lines, then `DocTest` will raise a ValueError: 0320 0321 >>> docstring = r''' 0322 ... >>> print ('bad indentation', 0323 ... ... 2) 0324 ... ('bad', 'indentation') 0325 ... ''' 0326 >>> parser.get_doctest(docstring, globs, 'some_test', 'filename', 0) 0327 Traceback (most recent call last): 0328 ValueError: line 2 of the docstring for some_test has inconsistent leading whitespace: '... 2)' 0329 0330 If there's no blank space after a PS1 prompt ('>>>'), then `DocTest` 0331 will raise a ValueError: 0332 0333 >>> docstring = '>>>print 1\n1' 0334 >>> parser.get_doctest(docstring, globs, 'some_test', 'filename', 0) 0335 Traceback (most recent call last): 0336 ValueError: line 1 of the docstring for some_test lacks blank after >>>: '>>>print 1' 0337 0338 If there's no blank space after a PS2 prompt ('...'), then `DocTest` 0339 will raise a ValueError: 0340 0341 >>> docstring = '>>> if 1:\n...print 1\n1' 0342 >>> parser.get_doctest(docstring, globs, 'some_test', 'filename', 0) 0343 Traceback (most recent call last): 0344 ValueError: line 2 of the docstring for some_test lacks blank after ...: '...print 1' 0345 0346 """ 0347 0348 def test_DocTestFinder(): r""" 0349 Unit tests for the `DocTestFinder` class. 0350 0351 DocTestFinder is used to extract DocTests from an object's docstring 0352 and the docstrings of its contained objects. It can be used with 0353 modules, functions, classes, methods, staticmethods, classmethods, and 0354 properties. 0355 0356 Finding Tests in Functions 0357 ~~~~~~~~~~~~~~~~~~~~~~~~~~ 0358 For a function whose docstring contains examples, DocTestFinder.find() 0359 will return a single test (for that function's docstring): 0360 0361 >>> finder = doctest.DocTestFinder() 0362 0363 We'll simulate a __file__ attr that ends in pyc: 0364 0365 >>> import test.test_doctest 0366 >>> old = test.test_doctest.__file__ 0367 >>> test.test_doctest.__file__ = 'test_doctest.pyc' 0368 0369 >>> tests = finder.find(sample_func) 0370 0371 >>> print tests # doctest: +ELLIPSIS 0372 [<DocTest sample_func from ...:13 (1 example)>] 0373 0374 The exact name depends on how test_doctest was invoked, so allow for 0375 leading path components. 0376 0377 >>> tests[0].filename # doctest: +ELLIPSIS 0378 '...test_doctest.py' 0379 0380 >>> test.test_doctest.__file__ = old 0381 0382 0383 >>> e = tests[0].examples[0] 0384 >>> (e.source, e.want, e.lineno) 0385 ('print sample_func(22)\n', '44\n', 3) 0386 0387 By default, tests are created for objects with no docstring: 0388 0389 >>> def no_docstring(v): 0390 ... pass 0391 >>> finder.find(no_docstring) 0392 [] 0393 0394 However, the optional argument `exclude_empty` to the DocTestFinder 0395 constructor can be used to exclude tests for objects with empty 0396 docstrings: 0397 0398 >>> def no_docstring(v): 0399 ... pass 0400 >>> excl_empty_finder = doctest.DocTestFinder(exclude_empty=True) 0401 >>> excl_empty_finder.find(no_docstring) 0402 [] 0403 0404 If the function has a docstring with no examples, then a test with no 0405 examples is returned. (This lets `DocTestRunner` collect statistics 0406 about which functions have no tests -- but is that useful? And should 0407 an empty test also be created when there's no docstring?) 0408 0409 >>> def no_examples(v): 0410 ... ''' no doctest examples ''' 0411 >>> finder.find(no_examples) # doctest: +ELLIPSIS 0412 [<DocTest no_examples from ...:1 (no examples)>] 0413 0414 Finding Tests in Classes 0415 ~~~~~~~~~~~~~~~~~~~~~~~~ 0416 For a class, DocTestFinder will create a test for the class's 0417 docstring, and will recursively explore its contents, including 0418 methods, classmethods, staticmethods, properties, and nested classes. 0419 0420 >>> finder = doctest.DocTestFinder() 0421 >>> tests = finder.find(SampleClass) 0422 >>> tests.sort() 0423 >>> for t in tests: 0424 ... print '%2s %s' % (len(t.examples), t.name) 0425 3 SampleClass 0426 3 SampleClass.NestedClass 0427 1 SampleClass.NestedClass.__init__ 0428 1 SampleClass.__init__ 0429 2 SampleClass.a_classmethod 0430 1 SampleClass.a_property 0431 1 SampleClass.a_staticmethod 0432 1 SampleClass.double 0433 1 SampleClass.get 0434 0435 New-style classes are also supported: 0436 0437 >>> tests = finder.find(SampleNewStyleClass) 0438 >>> tests.sort() 0439 >>> for t in tests: 0440 ... print '%2s %s' % (len(t.examples), t.name) 0441 1 SampleNewStyleClass 0442 1 SampleNewStyleClass.__init__ 0443 1 SampleNewStyleClass.double 0444 1 SampleNewStyleClass.get 0445 0446 Finding Tests in Modules 0447 ~~~~~~~~~~~~~~~~~~~~~~~~ 0448 For a module, DocTestFinder will create a test for the class's 0449 docstring, and will recursively explore its contents, including 0450 functions, classes, and the `__test__` dictionary, if it exists: 0451 0452 >>> # A module 0453 >>> import new 0454 >>> m = new.module('some_module') 0455 >>> def triple(val): 0456 ... ''' 0457 ... >>> print triple(11) 0458 ... 33 0459 ... ''' 0460 ... return val*3 0461 >>> m.__dict__.update({ 0462 ... 'sample_func': sample_func, 0463 ... 'SampleClass': SampleClass, 0464 ... '__doc__': ''' 0465 ... Module docstring. 0466 ... >>> print 'module' 0467 ... module 0468 ... ''', 0469 ... '__test__': { 0470 ... 'd': '>>> print 6\n6\n>>> print 7\n7\n', 0471 ... 'c': triple}}) 0472 0473 >>> finder = doctest.DocTestFinder() 0474 >>> # Use module=test.test_doctest, to prevent doctest from 0475 >>> # ignoring the objects since they weren't defined in m. 0476 >>> import test.test_doctest 0477 >>> tests = finder.find(m, module=test.test_doctest) 0478 >>> tests.sort() 0479 >>> for t in tests: 0480 ... print '%2s %s' % (len(t.examples), t.name) 0481 1 some_module 0482 3 some_module.SampleClass 0483 3 some_module.SampleClass.NestedClass 0484 1 some_module.SampleClass.NestedClass.__init__ 0485 1 some_module.SampleClass.__init__ 0486 2 some_module.SampleClass.a_classmethod 0487 1 some_module.SampleClass.a_property 0488 1 some_module.SampleClass.a_staticmethod 0489 1 some_module.SampleClass.double 0490 1 some_module.SampleClass.get 0491 1 some_module.__test__.c 0492 2 some_module.__test__.d 0493 1 some_module.sample_func 0494 0495 Duplicate Removal 0496 ~~~~~~~~~~~~~~~~~ 0497 If a single object is listed twice (under different names), then tests 0498 will only be generated for it once: 0499 0500 >>> from test import doctest_aliases 0501 >>> tests = excl_empty_finder.find(doctest_aliases) 0502 >>> tests.sort() 0503 >>> print len(tests) 0504 2 0505 >>> print tests[0].name 0506 test.doctest_aliases.TwoNames 0507 0508 TwoNames.f and TwoNames.g are bound to the same object. 0509 We can't guess which will be found in doctest's traversal of 0510 TwoNames.__dict__ first, so we have to allow for either. 0511 0512 >>> tests[1].name.split('.')[-1] in ['f', 'g'] 0513 True 0514 0515 Filter Functions 0516 ~~~~~~~~~~~~~~~~ 0517 A filter function can be used to restrict which objects get examined, 0518 but this is temporary, undocumented internal support for testmod's 0519 deprecated isprivate gimmick. 0520 0521 >>> def namefilter(prefix, base): 0522 ... return base.startswith('a_') 0523 >>> tests = doctest.DocTestFinder(_namefilter=namefilter).find(SampleClass) 0524 >>> tests.sort() 0525 >>> for t in tests: 0526 ... print '%2s %s' % (len(t.examples), t.name) 0527 3 SampleClass 0528 3 SampleClass.NestedClass 0529 1 SampleClass.NestedClass.__init__ 0530 1 SampleClass.__init__ 0531 1 SampleClass.double 0532 1 SampleClass.get 0533 0534 By default, that excluded objects with no doctests. exclude_empty=False 0535 tells it to include (empty) tests for objects with no doctests. This feature 0536 is really to support backward compatibility in what doctest.master.summarize() 0537 displays. 0538 0539 >>> tests = doctest.DocTestFinder(_namefilter=namefilter, 0540 ... exclude_empty=False).find(SampleClass) 0541 >>> tests.sort() 0542 >>> for t in tests: 0543 ... print '%2s %s' % (len(t.examples), t.name) 0544 3 SampleClass 0545 3 SampleClass.NestedClass 0546 1 SampleClass.NestedClass.__init__ 0547 0 SampleClass.NestedClass.get 0548 0 SampleClass.NestedClass.square 0549 1 SampleClass.__init__ 0550 1 SampleClass.double 0551 1 SampleClass.get 0552 0553 If a given object is filtered out, then none of the objects that it 0554 contains will be added either: 0555 0556 >>> def namefilter(prefix, base): 0557 ... return base == 'NestedClass' 0558 >>> tests = doctest.DocTestFinder(_namefilter=namefilter).find(SampleClass) 0559 >>> tests.sort() 0560 >>> for t in tests: 0561 ... print '%2s %s' % (len(t.examples), t.name) 0562 3 SampleClass 0563 1 SampleClass.__init__ 0564 2 SampleClass.a_classmethod 0565 1 SampleClass.a_property 0566 1 SampleClass.a_staticmethod 0567 1 SampleClass.double 0568 1 SampleClass.get 0569 0570 The filter function apply to contained objects, and *not* to the 0571 object explicitly passed to DocTestFinder: 0572 0573 >>> def namefilter(prefix, base): 0574 ... return base == 'SampleClass' 0575 >>> tests = doctest.DocTestFinder(_namefilter=namefilter).find(SampleClass) 0576 >>> len(tests) 0577 9 0578 0579 Turning off Recursion 0580 ~~~~~~~~~~~~~~~~~~~~~ 0581 DocTestFinder can be told not to look for tests in contained objects 0582 using the `recurse` flag: 0583 0584 >>> tests = doctest.DocTestFinder(recurse=False).find(SampleClass) 0585 >>> tests.sort() 0586 >>> for t in tests: 0587 ... print '%2s %s' % (len(t.examples), t.name) 0588 3 SampleClass 0589 0590 Line numbers 0591 ~~~~~~~~~~~~ 0592 DocTestFinder finds the line number of each example: 0593 0594 >>> def f(x): 0595 ... ''' 0596 ... >>> x = 12 0597 ... 0598 ... some text 0599 ... 0600 ... >>> # examples are not created for comments & bare prompts. 0601 ... >>> 0602 ... ... 0603 ... 0604 ... >>> for x in range(10): 0605 ... ... print x, 0606 ... 0 1 2 3 4 5 6 7 8 9 0607 ... >>> x/2 0608 ... 6 0609 ... ''' 0610 >>> test = doctest.DocTestFinder().find(f)[0] 0611 >>> [e.lineno for e in test.examples] 0612 [1, 9, 12] 0613 """ 0614 0615 def test_DocTestParser(): r""" 0616 Unit tests for the `DocTestParser` class. 0617 0618 DocTestParser is used to parse docstrings containing doctest examples. 0619 0620 The `parse` method divides a docstring into examples and intervening 0621 text: 0622 0623 >>> s = ''' 0624 ... >>> x, y = 2, 3 # no output expected 0625 ... >>> if 1: 0626 ... ... print x 0627 ... ... print y 0628 ... 2 0629 ... 3 0630 ... 0631 ... Some text. 0632 ... >>> x+y 0633 ... 5 0634 ... ''' 0635 >>> parser = doctest.DocTestParser() 0636 >>> for piece in parser.parse(s): 0637 ... if isinstance(piece, doctest.Example): 0638 ... print 'Example:', (piece.source, piece.want, piece.lineno) 0639 ... else: 0640 ... print ' Text:', `piece` 0641 Text: '\n' 0642 Example: ('x, y = 2, 3 # no output expected\n', '', 1) 0643 Text: '' 0644 Example: ('if 1:\n print x\n print y\n', '2\n3\n', 2) 0645 Text: '\nSome text.\n' 0646 Example: ('x+y\n', '5\n', 9) 0647 Text: '' 0648 0649 The `get_examples` method returns just the examples: 0650 0651 >>> for piece in parser.get_examples(s): 0652 ... print (piece.source, piece.want, piece.lineno) 0653 ('x, y = 2, 3 # no output expected\n', '', 1) 0654 ('if 1:\n print x\n print y\n', '2\n3\n', 2) 0655 ('x+y\n', '5\n', 9) 0656 0657 The `get_doctest` method creates a Test from the examples, along with the 0658 given arguments: 0659 0660 >>> test = parser.get_doctest(s, {}, 'name', 'filename', lineno=5) 0661 >>> (test.name, test.filename, test.lineno) 0662 ('name', 'filename', 5) 0663 >>> for piece in test.examples: 0664 ... print (piece.source, piece.want, piece.lineno) 0665 ('x, y = 2, 3 # no output expected\n', '', 1) 0666 ('if 1:\n print x\n print y\n', '2\n3\n', 2) 0667 ('x+y\n', '5\n', 9) 0668 """ 0669 0670 class test_DocTestRunner: 0671 def basics(): r""" 0672 Unit tests for the `DocTestRunner` class. 0673 0674 DocTestRunner is used to run DocTest test cases, and to accumulate 0675 statistics. Here's a simple DocTest case we can use: 0676 0677 >>> def f(x): 0678 ... ''' 0679 ... >>> x = 12 0680 ... >>> print x 0681 ... 12 0682 ... >>> x/2 0683 ... 6 0684 ... ''' 0685 >>> test = doctest.DocTestFinder().find(f)[0] 0686 0687 The main DocTestRunner interface is the `run` method, which runs a 0688 given DocTest case in a given namespace (globs). It returns a tuple 0689 `(f,t)`, where `f` is the number of failed tests and `t` is the number 0690 of tried tests. 0691 0692 >>> doctest.DocTestRunner(verbose=False).run(test) 0693 (0, 3) 0694 0695 If any example produces incorrect output, then the test runner reports 0696 the failure and proceeds to the next example: 0697 0698 >>> def f(x): 0699 ... ''' 0700 ... >>> x = 12 0701 ... >>> print x 0702 ... 14 0703 ... >>> x/2 0704 ... 6 0705 ... ''' 0706 >>> test = doctest.DocTestFinder().find(f)[0] 0707 >>> doctest.DocTestRunner(verbose=True).run(test) 0708 ... # doctest: +ELLIPSIS 0709 Trying: 0710 x = 12 0711 Expecting nothing 0712 ok 0713 Trying: 0714 print x 0715 Expecting: 0716 14 0717 ********************************************************************** 0718 File ..., line 4, in f 0719 Failed example: 0720 print x 0721 Expected: 0722 14 0723 Got: 0724 12 0725 Trying: 0726 x/2 0727 Expecting: 0728 6 0729 ok 0730 (1, 3) 0731 """ 0732 def verbose_flag(): r""" 0733 The `verbose` flag makes the test runner generate more detailed 0734 output: 0735 0736 >>> def f(x): 0737 ... ''' 0738 ... >>> x = 12 0739 ... >>> print x 0740 ... 12 0741 ... >>> x/2 0742 ... 6 0743 ... ''' 0744 >>> test = doctest.DocTestFinder().find(f)[0] 0745 0746 >>> doctest.DocTestRunner(verbose=True).run(test) 0747 Trying: 0748 x = 12 0749 Expecting nothing 0750 ok 0751 Trying: 0752 print x 0753 Expecting: 0754 12 0755 ok 0756 Trying: 0757 x/2 0758 Expecting: 0759 6 0760 ok 0761 (0, 3) 0762 0763 If the `verbose` flag is unspecified, then the output will be verbose 0764 iff `-v` appears in sys.argv: 0765 0766 >>> # Save the real sys.argv list. 0767 >>> old_argv = sys.argv 0768 0769 >>> # If -v does not appear in sys.argv, then output isn't verbose. 0770 >>> sys.argv = ['test'] 0771 >>> doctest.DocTestRunner().run(test) 0772 (0, 3) 0773 0774 >>> # If -v does appear in sys.argv, then output is verbose. 0775 >>> sys.argv = ['test', '-v'] 0776 >>> doctest.DocTestRunner().run(test) 0777 Trying: 0778 x = 12 0779 Expecting nothing 0780 ok 0781 Trying: 0782 print x 0783 Expecting: 0784 12 0785 ok 0786 Trying: 0787 x/2 0788 Expecting: 0789 6 0790 ok 0791 (0, 3) 0792 0793 >>> # Restore sys.argv 0794 >>> sys.argv = old_argv 0795 0796 In the remaining examples, the test runner's verbosity will be 0797 explicitly set, to ensure that the test behavior is consistent. 0798 """ 0799 def exceptions(): r""" 0800 Tests of `DocTestRunner`'s exception handling. 0801 0802 An expected exception is specified with a traceback message. The 0803 lines between the first line and the type/value may be omitted or 0804 replaced with any other string: 0805 0806 >>> def f(x): 0807 ... ''' 0808 ... >>> x = 12 0809 ... >>> print x/0 0810 ... Traceback (most recent call last): 0811 ... ZeroDivisionError: integer division or modulo by zero 0812 ... ''' 0813 >>> test = doctest.DocTestFinder().find(f)[0] 0814 >>> doctest.DocTestRunner(verbose=False).run(test) 0815 (0, 2) 0816 0817 An example may not generate output before it raises an exception; if 0818 it does, then the traceback message will not be recognized as 0819 signaling an expected exception, so the example will be reported as an 0820 unexpected exception: 0821 0822 >>> def f(x): 0823 ... ''' 0824 ... >>> x = 12 0825 ... >>> print 'pre-exception output', x/0 0826 ... pre-exception output 0827 ... Traceback (most recent call last): 0828 ... ZeroDivisionError: integer division or modulo by zero 0829 ... ''' 0830 >>> test = doctest.DocTestFinder().find(f)[0] 0831 >>> doctest.DocTestRunner(verbose=False).run(test) 0832 ... # doctest: +ELLIPSIS 0833 ********************************************************************** 0834 File ..., line 4, in f 0835 Failed example: 0836 print 'pre-exception output', x/0 0837 Exception raised: 0838 ... 0839 ZeroDivisionError: integer division or modulo by zero 0840 (1, 2) 0841 0842 Exception messages may contain newlines: 0843 0844 >>> def f(x): 0845 ... r''' 0846 ... >>> raise ValueError, 'multi\nline\nmessage' 0847 ... Traceback (most recent call last): 0848 ... ValueError: multi 0849 ... line 0850 ... message 0851 ... ''' 0852 >>> test = doctest.DocTestFinder().find(f)[0] 0853 >>> doctest.DocTestRunner(verbose=False).run(test) 0854 (0, 1) 0855 0856 If an exception is expected, but an exception with the wrong type or 0857 message is raised, then it is reported as a failure: 0858 0859 >>> def f(x): 0860 ... r''' 0861 ... >>> raise ValueError, 'message' 0862 ... Traceback (most recent call last): 0863 ... ValueError: wrong message 0864 ... ''' 0865 >>> test = doctest.DocTestFinder().find(f)[0] 0866 >>> doctest.DocTestRunner(verbose=False).run(test) 0867 ... # doctest: +ELLIPSIS 0868 ********************************************************************** 0869 File ..., line 3, in f 0870 Failed example: 0871 raise ValueError, 'message' 0872 Expected: 0873 Traceback (most recent call last): 0874 ValueError: wrong message 0875 Got: 0876 Traceback (most recent call last): 0877 ... 0878 ValueError: message 0879 (1, 1) 0880 0881 However, IGNORE_EXCEPTION_DETAIL can be used to allow a mismatch in the 0882 detail: 0883 0884 >>> def f(x): 0885 ... r''' 0886 ... >>> raise ValueError, 'message' #doctest: +IGNORE_EXCEPTION_DETAIL 0887 ... Traceback (most recent call last): 0888 ... ValueError: wrong message 0889 ... ''' 0890 >>> test = doctest.DocTestFinder().find(f)[0] 0891 >>> doctest.DocTestRunner(verbose=False).run(test) 0892 (0, 1) 0893 0894 But IGNORE_EXCEPTION_DETAIL does not allow a mismatch in the exception type: 0895 0896 >>> def f(x): 0897 ... r''' 0898 ... >>> raise ValueError, 'message' #doctest: +IGNORE_EXCEPTION_DETAIL 0899 ... Traceback (most recent call last): 0900 ... TypeError: wrong type 0901 ... ''' 0902 >>> test = doctest.DocTestFinder().find(f)[0] 0903 >>> doctest.DocTestRunner(verbose=False).run(test) 0904 ... # doctest: +ELLIPSIS 0905 ********************************************************************** 0906 File ..., line 3, in f 0907 Failed example: 0908 raise ValueError, 'message' #doctest: +IGNORE_EXCEPTION_DETAIL 0909 Expected: 0910 Traceback (most recent call last): 0911 TypeError: wrong type 0912 Got: 0913 Traceback (most recent call last): 0914 ... 0915 ValueError: message 0916 (1, 1) 0917 0918 If an exception is raised but not expected, then it is reported as an 0919 unexpected exception: 0920 0921 >>> def f(x): 0922 ... r''' 0923 ... >>> 1/0 0924 ... 0 0925 ... ''' 0926 >>> test = doctest.DocTestFinder().find(f)[0] 0927 >>> doctest.DocTestRunner(verbose=False).run(test) 0928 ... # doctest: +ELLIPSIS 0929 ********************************************************************** 0930 File ..., line 3, in f 0931 Failed example: 0932 1/0 0933 Exception raised: 0934 Traceback (most recent call last): 0935 ... 0936 ZeroDivisionError: integer division or modulo by zero 0937 (1, 1) 0938 """ 0939 def optionflags(): r""" 0940 Tests of `DocTestRunner`'s option flag handling. 0941 0942 Several option flags can be used to customize the behavior of the test 0943 runner. These are defined as module constants in doctest, and passed 0944 to the DocTestRunner constructor (multiple constants should be or-ed 0945 together). 0946 0947 The DONT_ACCEPT_TRUE_FOR_1 flag disables matches between True/False 0948 and 1/0: 0949 0950 >>> def f(x): 0951 ... '>>> True\n1\n' 0952 0953 >>> # Without the flag: 0954 >>> test = doctest.DocTestFinder().find(f)[0] 0955 >>> doctest.DocTestRunner(verbose=False).run(test) 0956 (0, 1) 0957 0958 >>> # With the flag: 0959 >>> test = doctest.DocTestFinder().find(f)[0] 0960 >>> flags = doctest.DONT_ACCEPT_TRUE_FOR_1 0961 >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test) 0962 ... # doctest: +ELLIPSIS 0963 ********************************************************************** 0964 File ..., line 2, in f 0965 Failed example: 0966 True 0967 Expected: 0968 1 0969 Got: 0970 True 0971 (1, 1) 0972 0973 The DONT_ACCEPT_BLANKLINE flag disables the match between blank lines 0974 and the '<BLANKLINE>' marker: 0975 0976 >>> def f(x): 0977 ... '>>> print "a\\n\\nb"\na\n<BLANKLINE>\nb\n' 0978 0979 >>> # Without the flag: 0980 >>> test = doctest.DocTestFinder().find(f)[0] 0981 >>> doctest.DocTestRunner(verbose=False).run(test) 0982 (0, 1) 0983 0984 >>> # With the flag: 0985 >>> test = doctest.DocTestFinder().find(f)[0] 0986 >>> flags = doctest.DONT_ACCEPT_BLANKLINE 0987 >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test) 0988 ... # doctest: +ELLIPSIS 0989 ********************************************************************** 0990 File ..., line 2, in f 0991 Failed example: 0992 print "a\n\nb" 0993 Expected: 0994 a 0995 <BLANKLINE> 0996 b 0997 Got: 0998 a 0999 <BLANKLINE> 1000 b 1001 (1, 1) 1002 1003 The NORMALIZE_WHITESPACE flag causes all sequences of whitespace to be 1004 treated as equal: 1005 1006 >>> def f(x): 1007 ... '>>> print 1, 2, 3\n 1 2\n 3' 1008 1009 >>> # Without the flag: 1010 >>> test = doctest.DocTestFinder().find(f)[0] 1011 >>> doctest.DocTestRunner(verbose=False).run(test) 1012 ... # doctest: +ELLIPSIS 1013 ********************************************************************** 1014 File ..., line 2, in f 1015 Failed example: 1016 print 1, 2, 3 1017 Expected: 1018 1 2 1019 3 1020 Got: 1021 1 2 3 1022 (1, 1) 1023 1024 >>> # With the flag: 1025 >>> test = doctest.DocTestFinder().find(f)[0] 1026 >>> flags = doctest.NORMALIZE_WHITESPACE 1027 >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test) 1028 (0, 1) 1029 1030 An example from the docs: 1031 >>> print range(20) #doctest: +NORMALIZE_WHITESPACE 1032 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 1033 10, 11, 12, 13, 14, 15, 16, 17, 18, 19] 1034 1035 The ELLIPSIS flag causes ellipsis marker ("...") in the expected 1036 output to match any substring in the actual output: 1037 1038 >>> def f(x): 1039 ... '>>> print range(15)\n[0, 1, 2, ..., 14]\n' 1040 1041 >>> # Without the flag: 1042 >>> test = doctest.DocTestFinder().find(f)[0] 1043 >>> doctest.DocTestRunner(verbose=False).run(test) 1044 ... # doctest: +ELLIPSIS 1045 ********************************************************************** 1046 File ..., line 2, in f 1047 Failed example: 1048 print range(15) 1049 Expected: 1050 [0, 1, 2, ..., 14] 1051 Got: 1052 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14] 1053 (1, 1) 1054 1055 >>> # With the flag: 1056 >>> test = doctest.DocTestFinder().find(f)[0] 1057 >>> flags = doctest.ELLIPSIS 1058 >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test) 1059 (0, 1) 1060 1061 ... also matches nothing: 1062 1063 >>> for i in range(100): 1064 ... print i**2, #doctest: +ELLIPSIS 1065 0 1...4...9 16 ... 36 49 64 ... 9801 1066 1067 ... can be surprising; e.g., this test passes: 1068 1069 >>> for i in range(21): #doctest: +ELLIPSIS 1070 ... print i, 1071 0 1 2 ...1...2...0 1072 1073 Examples from the docs: 1074 1075 >>> print range(20) # doctest:+ELLIPSIS 1076 [0, 1, ..., 18, 19] 1077 1078 >>> print range(20) # doctest: +ELLIPSIS 1079 ... # doctest: +NORMALIZE_WHITESPACE 1080 [0, 1, ..., 18, 19] 1081 1082 The REPORT_UDIFF flag causes failures that involve multi-line expected 1083 and actual outputs to be displayed using a unified diff: 1084 1085 >>> def f(x): 1086 ... r''' 1087 ... >>> print '\n'.join('abcdefg') 1088 ... a 1089 ... B 1090 ... c 1091 ... d 1092 ... f 1093 ... g 1094 ... h 1095 ... ''' 1096 1097 >>> # Without the flag: 1098 >>> test = doctest.DocTestFinder().find(f)[0] 1099 >>> doctest.DocTestRunner(verbose=False).run(test) 1100 ... # doctest: +ELLIPSIS 1101 ********************************************************************** 1102 File ..., line 3, in f 1103 Failed example: 1104 print '\n'.join('abcdefg') 1105 Expected: 1106 a 1107 B 1108 c 1109 d 1110 f 1111 g 1112 h 1113 Got: 1114 a 1115 b 1116 c 1117 d 1118 e 1119 f 1120 g 1121 (1, 1) 1122 1123 >>> # With the flag: 1124 >>> test = doctest.DocTestFinder().find(f)[0] 1125 >>> flags = doctest.REPORT_UDIFF 1126 >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test) 1127 ... # doctest: +ELLIPSIS 1128 ********************************************************************** 1129 File ..., line 3, in f 1130 Failed example: 1131 print '\n'.join('abcdefg') 1132 Differences (unified diff with -expected +actual): 1133 @@ -1,7 +1,7 @@ 1134 a 1135 -B 1136 +b 1137 c 1138 d 1139 +e 1140 f 1141 g 1142 -h 1143 (1, 1) 1144 1145 The REPORT_CDIFF flag causes failures that involve multi-line expected 1146 and actual outputs to be displayed using a context diff: 1147 1148 >>> # Reuse f() from the REPORT_UDIFF example, above. 1149 >>> test = doctest.DocTestFinder().find(f)[0] 1150 >>> flags = doctest.REPORT_CDIFF 1151 >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test) 1152 ... # doctest: +ELLIPSIS 1153 ********************************************************************** 1154 File ..., line 3, in f 1155 Failed example: 1156 print '\n'.join('abcdefg') 1157 Differences (context diff with expected followed by actual): 1158 *************** 1159 *** 1,7 **** 1160 a 1161 ! B 1162 c 1163 d 1164 f 1165 g 1166 - h 1167 --- 1,7 ---- 1168 a 1169 ! b 1170 c 1171 d 1172 + e 1173 f 1174 g 1175 (1, 1) 1176 1177 1178 The REPORT_NDIFF flag causes failures to use the difflib.Differ algorithm 1179 used by the popular ndiff.py utility. This does intraline difference 1180 marking, as well as interline differences. 1181 1182 >>> def f(x): 1183 ... r''' 1184 ... >>> print "a b c d e f g h i j k l m" 1185 ... a b c d e f g h i j k 1 m 1186 ... ''' 1187 >>> test = doctest.DocTestFinder().find(f)[0] 1188 >>> flags = doctest.REPORT_NDIFF 1189 >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test) 1190 ... # doctest: +ELLIPSIS 1191 ********************************************************************** 1192 File ..., line 3, in f 1193 Failed example: 1194 print "a b c d e f g h i j k l m" 1195 Differences (ndiff with -expected +actual): 1196 - a b c d e f g h i j k 1 m 1197 ? ^ 1198 + a b c d e f g h i j k l m 1199 ? + ++ ^ 1200 (1, 1) 1201 1202 The REPORT_ONLY_FIRST_FAILURE supresses result output after the first 1203 failing example: 1204 1205 >>> def f(x): 1206 ... r''' 1207 ... >>> print 1 # first success 1208 ... 1 1209 ... >>> print 2 # first failure 1210 ... 200 1211 ... >>> print 3 # second failure 1212 ... 300 1213 ... >>> print 4 # second success 1214 ... 4 1215 ... >>> print 5 # third failure 1216 ... 500 1217 ... ''' 1218 >>> test = doctest.DocTestFinder().find(f)[0] 1219 >>> flags = doctest.REPORT_ONLY_FIRST_FAILURE 1220 >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test) 1221 ... # doctest: +ELLIPSIS 1222 ********************************************************************** 1223 File ..., line 5, in f 1224 Failed example: 1225 print 2 # first failure 1226 Expected: 1227 200 1228 Got: 1229 2 1230 (3, 5) 1231 1232 However, output from `report_start` is not supressed: 1233 1234 >>> doctest.DocTestRunner(verbose=True, optionflags=flags).run(test) 1235 ... # doctest: +ELLIPSIS 1236 Trying: 1237 print 1 # first success 1238 Expecting: 1239 1 1240 ok 1241 Trying: 1242 print 2 # first failure 1243 Expecting: 1244 200 1245 ********************************************************************** 1246 File ..., line 5, in f 1247 Failed example: 1248 print 2 # first failure 1249 Expected: 1250 200 1251 Got: 1252 2 1253 (3, 5) 1254 1255 For the purposes of REPORT_ONLY_FIRST_FAILURE, unexpected exceptions 1256 count as failures: 1257 1258 >>> def f(x): 1259 ... r''' 1260 ... >>> print 1 # first success 1261 ... 1 1262 ... >>> raise ValueError(2) # first failure 1263 ... 200 1264 ... >>> print 3 # second failure 1265 ... 300 1266 ... >>> print 4 # second success 1267 ... 4 1268 ... >>> print 5 # third failure 1269 ... 500 1270 ... ''' 1271 >>> test = doctest.DocTestFinder().find(f)[0] 1272 >>> flags = doctest.REPORT_ONLY_FIRST_FAILURE 1273 >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test) 1274 ... # doctest: +ELLIPSIS 1275 ********************************************************************** 1276 File ..., line 5, in f 1277 Failed example: 1278 raise ValueError(2) # first failure 1279 Exception raised: 1280 ... 1281 ValueError: 2 1282 (3, 5) 1283 1284 """ 1285 1286 def option_directives(): r""" 1287 Tests of `DocTestRunner`'s option directive mechanism. 1288 1289 Option directives can be used to turn option flags on or off for a 1290 single example. To turn an option on for an example, follow that 1291 example with a comment of the form ``# doctest: +OPTION``: 1292 1293 >>> def f(x): r''' 1294 ... >>> print range(10) # should fail: no ellipsis 1295 ... [0, 1, ..., 9] 1296 ... 1297 ... >>> print range(10) # doctest: +ELLIPSIS 1298 ... [0, 1, ..., 9] 1299 ... ''' 1300 >>> test = doctest.DocTestFinder().find(f)[0] 1301 >>> doctest.DocTestRunner(verbose=False).run(test) 1302 ... # doctest: +ELLIPSIS 1303 ********************************************************************** 1304 File ..., line 2, in f 1305 Failed example: 1306 print range(10) # should fail: no ellipsis 1307 Expected: 1308 [0, 1, ..., 9] 1309 Got: 1310 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] 1311 (1, 2) 1312 1313 To turn an option off for an example, follow that example with a 1314 comment of the form ``# doctest: -OPTION``: 1315 1316 >>> def f(x): r''' 1317 ... >>> print range(10) 1318 ... [0, 1, ..., 9] 1319 ... 1320 ... >>> # should fail: no ellipsis 1321 ... >>> print range(10) # doctest: -ELLIPSIS 1322 ... [0, 1, ..., 9] 1323 ... ''' 1324 >>> test = doctest.DocTestFinder().find(f)[0] 1325 >>> doctest.DocTestRunner(verbose=False, 1326 ... optionflags=doctest.ELLIPSIS).run(test) 1327 ... # doctest: +ELLIPSIS 1328 ********************************************************************** 1329 File ..., line 6, in f 1330 Failed example: 1331 print range(10) # doctest: -ELLIPSIS 1332 Expected: 1333 [0, 1, ..., 9] 1334 Got: 1335 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] 1336 (1, 2) 1337 1338 Option directives affect only the example that they appear with; they 1339 do not change the options for surrounding examples: 1340 1341 >>> def f(x): r''' 1342 ... >>> print range(10) # Should fail: no ellipsis 1343 ... [0, 1, ..., 9] 1344 ... 1345 ... >>> print range(10) # doctest: +ELLIPSIS 1346 ... [0, 1, ..., 9] 1347 ... 1348 ... >>> print range(10) # Should fail: no ellipsis 1349 ... [0, 1, ..., 9] 1350 ... ''' 1351 >>> test = doctest.DocTestFinder().find(f)[0] 1352 >>> doctest.DocTestRunner(verbose=False).run(test) 1353 ... # doctest: +ELLIPSIS 1354 ********************************************************************** 1355 File ..., line 2, in f 1356 Failed example: 1357 print range(10) # Should fail: no ellipsis 1358 Expected: 1359 [0, 1, ..., 9] 1360 Got: 1361 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] 1362 ********************************************************************** 1363 File ..., line 8, in f 1364 Failed example: 1365 print range(10) # Should fail: no ellipsis 1366 Expected: 1367 [0, 1, ..., 9] 1368 Got: 1369 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] 1370 (2, 3) 1371 1372 Multiple options may be modified by a single option directive. They 1373 may be separated by whitespace, commas, or both: 1374 1375 >>> def f(x): r''' 1376 ... >>> print range(10) # Should fail 1377 ... [0, 1, ..., 9] 1378 ... >>> print range(10) # Should succeed 1379 ... ... # doctest: +ELLIPSIS +NORMALIZE_WHITESPACE 1380 ... [0, 1, ..., 9] 1381 ... ''' 1382 >>> test = doctest.DocTestFinder().find(f)[0] 1383 >>> doctest.DocTestRunner(verbose=False).run(test) 1384 ... # doctest: +ELLIPSIS 1385 ********************************************************************** 1386 File ..., line 2, in f 1387 Failed example: 1388 print range(10) # Should fail 1389 Expected: 1390 [0, 1, ..., 9] 1391 Got: 1392 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] 1393 (1, 2) 1394 1395 >>> def f(x): r''' 1396 ... >>> print range(10) # Should fail 1397 ... [0, 1, ..., 9] 1398 ... >>> print range(10) # Should succeed 1399 ... ... # doctest: +ELLIPSIS,+NORMALIZE_WHITESPACE 1400 ... [0, 1, ..., 9] 1401 ... ''' 1402 >>> test = doctest.DocTestFinder().find(f)[0] 1403 >>> doctest.DocTestRunner(verbose=False).run(test) 1404 ... # doctest: +ELLIPSIS 1405 ********************************************************************** 1406 File ..., line 2, in f 1407 Failed example: 1408 print range(10) # Should fail 1409 Expected: 1410 [0, 1, ..., 9] 1411 Got: 1412 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] 1413 (1, 2) 1414 1415 >>> def f(x): r''' 1416 ... >>> print range(10) # Should fail 1417 ... [0, 1, ..., 9] 1418 ... >>> print range(10) # Should succeed 1419 ... ... # doctest: +ELLIPSIS, +NORMALIZE_WHITESPACE 1420 ... [0, 1, ..., 9] 1421 ... ''' 1422 >>> test = doctest.DocTestFinder().find(f)[0] 1423 >>> doctest.DocTestRunner(verbose=False).run(test) 1424 ... # doctest: +ELLIPSIS 1425 ********************************************************************** 1426 File ..., line 2, in f 1427 Failed example: 1428 print range(10) # Should fail 1429 Expected: 1430 [0, 1, ..., 9] 1431 Got: 1432 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] 1433 (1, 2) 1434 1435 The option directive may be put on the line following the source, as 1436 long as a continuation prompt is used: 1437 1438 >>> def f(x): r''' 1439 ... >>> print range(10) 1440 ... ... # doctest: +ELLIPSIS 1441 ... [0, 1, ..., 9] 1442 ... ''' 1443 >>> test = doctest.DocTestFinder().find(f)[0] 1444 >>> doctest.DocTestRunner(verbose=False).run(test) 1445 (0, 1) 1446 1447 For examples with multi-line source, the option directive may appear 1448 at the end of any line: 1449 1450 >>> def f(x): r''' 1451 ... >>> for x in range(10): # doctest: +ELLIPSIS 1452 ... ... print x, 1453 ... 0 1 2 ... 9 1454 ... 1455 ... >>> for x in range(10): 1456 ... ... print x, # doctest: +ELLIPSIS 1457 ... 0 1 2 ... 9 1458 ... ''' 1459 >>> test = doctest.DocTestFinder().find(f)[0] 1460 >>> doctest.DocTestRunner(verbose=False).run(test) 1461 (0, 2) 1462 1463 If more than one line of an example with multi-line source has an 1464 option directive, then they are combined: 1465 1466 >>> def f(x): r''' 1467 ... Should fail (option directive not on the last line): 1468 ... >>> for x in range(10): # doctest: +ELLIPSIS 1469 ... ... print x, # doctest: +NORMALIZE_WHITESPACE 1470 ... 0 1 2...9 1471 ... ''' 1472 >>> test = doctest.DocTestFinder().find(f)[0] 1473 >>> doctest.DocTestRunner(verbose=False).run(test) 1474 (0, 1) 1475 1476 It is an error to have a comment of the form ``# doctest:`` that is 1477 *not* followed by words of the form ``+OPTION`` or ``-OPTION``, where 1478 ``OPTION`` is an option that has been registered with 1479 `register_option`: 1480 1481 >>> # Error: Option not registered 1482 >>> s = '>>> print 12 #doctest: +BADOPTION' 1483 >>> test = doctest.DocTestParser().get_doctest(s, {}, 's', 's.py', 0) 1484 Traceback (most recent call last): 1485 ValueError: line 1 of the doctest for s has an invalid option: '+BADOPTION' 1486 1487 >>> # Error: No + or - prefix 1488 >>> s = '>>> print 12 #doctest: ELLIPSIS' 1489 >>> test = doctest.DocTestParser().get_doctest(s, {}, 's', 's.py', 0) 1490 Traceback (most recent call last): 1491 ValueError: line 1 of the doctest for s has an invalid option: 'ELLIPSIS' 1492 1493 It is an error to use an option directive on a line that contains no 1494 source: 1495 1496 >>> s = '>>> # doctest: +ELLIPSIS' 1497 >>> test = doctest.DocTestParser().get_doctest(s, {}, 's', 's.py', 0) 1498 Traceback (most recent call last): 1499 ValueError: line 0 of the doctest for s has an option directive on a line with no example: '# doctest: +ELLIPSIS' 1500 """ 1501 1502 def test_testsource(): r""" 1503 Unit tests for `testsource()`. 1504 1505 The testsource() function takes a module and a name, finds the (first) 1506 test with that name in that module, and converts it to a script. The 1507 example code is converted to regular Python code. The surrounding 1508 words and expected output are converted to comments: 1509 1510 >>> import test.test_doctest 1511 >>> name = 'test.test_doctest.sample_func' 1512 >>> print doctest.testsource(test.test_doctest, name) 1513 # Blah blah 1514 # 1515 print sample_func(22) 1516 # Expected: 1517 ## 44 1518 # 1519 # Yee ha! 1520 1521 >>> name = 'test.test_doctest.SampleNewStyleClass' 1522 >>> print doctest.testsource(test.test_doctest, name) 1523 print '1\n2\n3' 1524 # Expected: 1525 ## 1 1526 ## 2 1527 ## 3 1528 1529 >>> name = 'test.test_doctest.SampleClass.a_classmethod' 1530 >>> print doctest.testsource(test.test_doctest, name) 1531 print SampleClass.a_classmethod(10) 1532 # Expected: 1533 ## 12 1534 print SampleClass(0).a_classmethod(10) 1535 # Expected: 1536 ## 12 1537 """ 1538 1539 def test_debug(): r""" 1540 1541 Create a docstring that we want to debug: 1542 1543 >>> s = ''' 1544 ... >>> x = 12 1545 ... >>> print x 1546 ... 12 1547 ... ''' 1548 1549 Create some fake stdin input, to feed to the debugger: 1550 1551 >>> import tempfile 1552 >>> real_stdin = sys.stdin 1553 >>> sys.stdin = _FakeInput(['next', 'print x', 'continue']) 1554 1555 Run the debugger on the docstring, and then restore sys.stdin. 1556 1557 >>> try: doctest.debug_src(s) 1558 ... finally: sys.stdin = real_stdin 1559 > <string>(1)?() 1560 (Pdb) next 1561 12 1562 --Return-- 1563 > <string>(1)?()->None 1564 (Pdb) print x 1565 12 1566 (Pdb) continue 1567 1568 """ 1569 1570 def test_pdb_set_trace(): 1571 """Using pdb.set_trace from a doctest 1572 1573 You can use pdb.set_trace from a doctest. To do so, you must 1574 retrieve the set_trace function from the pdb module at the time 1575 you use it. The doctest module changes sys.stdout so that it can 1576 capture program output. It also temporarily replaces pdb.set_trace 1577 with a version that restores stdout. This is necessary for you to 1578 see debugger output. 1579 1580 >>> doc = ''' 1581 ... >>> x = 42 1582 ... >>> import pdb; pdb.set_trace() 1583 ... ''' 1584 >>> parser = doctest.DocTestParser() 1585 >>> test = parser.get_doctest(doc, {}, "foo", "foo.py", 0) 1586 >>> runner = doctest.DocTestRunner(verbose=False) 1587 1588 To demonstrate this, we'll create a fake standard input that 1589 captures our debugger input: 1590 1591 >>> import tempfile 1592 >>> real_stdin = sys.stdin 1593 >>> sys.stdin = _FakeInput([ 1594 ... 'print x', # print data defined by the example 1595 ... 'continue', # stop debugging 1596 ... '']) 1597 1598 >>> try: runner.run(test) 1599 ... finally: sys.stdin = real_stdin 1600 --Return-- 1601 > <doctest foo[1]>(1)?()->None 1602 -> import pdb; pdb.set_trace() 1603 (Pdb) print x 1604 42 1605 (Pdb) continue 1606 (0, 2) 1607 1608 You can also put pdb.set_trace in a function called from a test: 1609 1610 >>> def calls_set_trace(): 1611 ... y=2 1612 ... import pdb; pdb.set_trace() 1613 1614 >>> doc = ''' 1615 ... >>> x=1 1616 ... >>> calls_set_trace() 1617 ... ''' 1618 >>> test = parser.get_doctest(doc, globals(), "foo", "foo.py", 0) 1619 >>> real_stdin = sys.stdin 1620 >>> sys.stdin = _FakeInput([ 1621 ... 'print y', # print data defined in the function 1622 ... 'up', # out of function 1623 ... 'print x', # print data defined by the example 1624 ... 'continue', # stop debugging 1625 ... '']) 1626 1627 >>> try: runner.run(test) 1628 ... finally: sys.stdin = real_stdin 1629 --Return-- 1630 > <doctest test.test_doctest.test_pdb_set_trace[8]>(3)calls_set_trace()->None 1631 -> import pdb; pdb.set_trace() 1632 (Pdb) print y 1633 2 1634 (Pdb) up 1635 > <doctest foo[1]>(1)?() 1636 -> calls_set_trace() 1637 (Pdb) print x 1638 1 1639 (Pdb) continue 1640 (0, 2) 1641 1642 During interactive debugging, source code is shown, even for 1643 doctest examples: 1644 1645 >>> doc = ''' 1646 ... >>> def f(x): 1647 ... ... g(x*2) 1648 ... >>> def g(x): 1649 ... ... print x+3 1650 ... ... import pdb; pdb.set_trace() 1651 ... >>> f(3) 1652 ... ''' 1653 >>> test = parser.get_doctest(doc, globals(), "foo", "foo.py", 0) 1654 >>> real_stdin = sys.stdin 1655 >>> sys.stdin = _FakeInput([ 1656 ... 'list', # list source from example 2 1657 ... 'next', # return from g() 1658 ... 'list', # list source from example 1 1659 ... 'next', # return from f() 1660 ... 'list', # list source from example 3 1661 ... 'continue', # stop debugging 1662 ... '']) 1663 >>> try: runner.run(test) 1664 ... finally: sys.stdin = real_stdin 1665 ... # doctest: +NORMALIZE_WHITESPACE 1666 --Return-- 1667 > <doctest foo[1]>(3)g()->None 1668 -> import pdb; pdb.set_trace() 1669 (Pdb) list 1670 1 def g(x): 1671 2 print x+3 1672 3 -> import pdb; pdb.set_trace() 1673 [EOF] 1674 (Pdb) next 1675 --Return-- 1676 > <doctest foo[0]>(2)f()->None 1677 -> g(x*2) 1678 (Pdb) list 1679 1 def f(x): 1680 2 -> g(x*2) 1681 [EOF] 1682 (Pdb) next 1683 --Return-- 1684 > <doctest foo[2]>(1)?()->None 1685 -> f(3) 1686 (Pdb) list 1687 1 -> f(3) 1688 [EOF] 1689 (Pdb) continue 1690 ********************************************************************** 1691 File "foo.py", line 7, in foo 1692 Failed example: 1693 f(3) 1694 Expected nothing 1695 Got: 1696 9 1697 (1, 3) 1698 """ 1699 1700 def test_DocTestSuite(): 1701 """DocTestSuite creates a unittest test suite from a doctest. 1702 1703 We create a Suite by providing a module. A module can be provided 1704 by passing a module object: 1705 1706 >>> import unittest 1707 >>> import test.sample_doctest 1708 >>> suite = doctest.DocTestSuite(test.sample_doctest) 1709 >>> suite.run(unittest.TestResult()) 1710 <unittest.TestResult run=9 errors=0 failures=4> 1711 1712 We can also supply the module by name: 1713 1714 >>> suite = doctest.DocTestSuite('test.sample_doctest') 1715 >>> suite.run(unittest.TestResult()) 1716 <unittest.TestResult run=9 errors=0 failures=4> 1717 1718 We can use the current module: 1719 1720 >>> suite = test.sample_doctest.test_suite() 1721 >>> suite.run(unittest.TestResult()) 1722 <unittest.TestResult run=9 errors=0 failures=4> 1723 1724 We can supply global variables. If we pass globs, they will be 1725 used instead of the module globals. Here we'll pass an empty 1726 globals, triggering an extra error: 1727 1728 >>> suite = doctest.DocTestSuite('test.sample_doctest', globs={}) 1729 >>> suite.run(unittest.TestResult()) 1730 <unittest.TestResult run=9 errors=0 failures=5> 1731 1732 Alternatively, we can provide extra globals. Here we'll make an 1733 error go away by providing an extra global variable: 1734 1735 >>> suite = doctest.DocTestSuite('test.sample_doctest', 1736 ... extraglobs={'y': 1}) 1737 >>> suite.run(unittest.TestResult()) 1738 <unittest.TestResult run=9 errors=0 failures=3> 1739 1740 You can pass option flags. Here we'll cause an extra error 1741 by disabling the blank-line feature: 1742 1743 >>> suite = doctest.DocTestSuite('test.sample_doctest', 1744 ... optionflags=doctest.DONT_ACCEPT_BLANKLINE) 1745 >>> suite.run(unittest.TestResult()) 1746 <unittest.TestResult run=9 errors=0 failures=5> 1747 1748 You can supply setUp and tearDown functions: 1749 1750 >>> def setUp(t): 1751 ... import test.test_doctest 1752 ... test.test_doctest.sillySetup = True 1753 1754 >>> def tearDown(t): 1755 ... import test.test_doctest 1756 ... del test.test_doctest.sillySetup 1757 1758 Here, we installed a silly variable that the test expects: 1759 1760 >>> suite = doctest.DocTestSuite('test.sample_doctest', 1761 ... setUp=setUp, tearDown=tearDown) 1762 >>> suite.run(unittest.TestResult()) 1763 <unittest.TestResult run=9 errors=0 failures=3> 1764 1765 But the tearDown restores sanity: 1766 1767 >>> import test.test_doctest 1768 >>> test.test_doctest.sillySetup 1769 Traceback (most recent call last): 1770 ... 1771 AttributeError: 'module' object has no attribute 'sillySetup' 1772 1773 The setUp and tearDown funtions are passed test objects. Here 1774 we'll use the setUp function to supply the missing variable y: 1775 1776 >>> def setUp(test): 1777 ... test.globs['y'] = 1 1778 1779 >>> suite = doctest.DocTestSuite('test.sample_doctest', setUp=setUp) 1780 >>> suite.run(unittest.TestResult()) 1781 <unittest.TestResult run=9 errors=0 failures=3> 1782 1783 Here, we didn't need to use a tearDown function because we 1784 modified the test globals, which are a copy of the 1785 sample_doctest module dictionary. The test globals are 1786 automatically cleared for us after a test. 1787 1788 Finally, you can provide an alternate test finder. Here we'll 1789 use a custom test_finder to to run just the test named bar. 1790 However, the test in the module docstring, and the two tests 1791 in the module __test__ dict, aren't filtered, so we actually 1792 run three tests besides bar's. The filtering mechanisms are 1793 poorly conceived, and will go away someday. 1794 1795 >>> finder = doctest.DocTestFinder( 1796 ... _namefilter=lambda prefix, base: base!='bar') 1797 >>> suite = doctest.DocTestSuite('test.sample_doctest', 1798 ... test_finder=finder) 1799 >>> suite.run(unittest.TestResult()) 1800 <unittest.TestResult run=4 errors=0 failures=1> 1801 """ 1802 1803 def test_DocFileSuite(): 1804 """We can test tests found in text files using a DocFileSuite. 1805 1806 We create a suite by providing the names of one or more text 1807 files that include examples: 1808 1809 >>> import unittest 1810 >>> suite = doctest.DocFileSuite('test_doctest.txt', 1811 ... 'test_doctest2.txt') 1812 >>> suite.run(unittest.TestResult()) 1813 <unittest.TestResult run=2 errors=0 failures=2> 1814 1815 The test files are looked for in the directory containing the 1816 calling module. A package keyword argument can be provided to 1817 specify a different relative location. 1818 1819 >>> import unittest 1820 >>> suite = doctest.DocFileSuite('test_doctest.txt', 1821 ... 'test_doctest2.txt', 1822 ... package='test') 1823 >>> suite.run(unittest.TestResult()) 1824 <unittest.TestResult run=2 errors=0 failures=2> 1825 1826 '/' should be used as a path separator. It will be converted 1827 to a native separator at run time: 1828 1829 >>> suite = doctest.DocFileSuite('../test/test_doctest.txt') 1830 >>> suite.run(unittest.TestResult()) 1831 <unittest.TestResult run=1 errors=0 failures=1> 1832 1833 If DocFileSuite is used from an interactive session, then files 1834 are resolved relative to the directory of sys.argv[0]: 1835 1836 >>> import new, os.path, test.test_doctest 1837 >>> save_argv = sys.argv 1838 >>> sys.argv = [test.test_doctest.__file__] 1839 >>> suite = doctest.DocFileSuite('test_doctest.txt', 1840 ... package=new.module('__main__')) 1841 >>> sys.argv = save_argv 1842 1843 By setting `module_relative=False`, os-specific paths may be 1844 used (including absolute paths and paths relative to the 1845 working directory): 1846 1847 >>> # Get the absolute path of the test package. 1848 >>> test_doctest_path = os.path.abspath(test.test_doctest.__file__) 1849 >>> test_pkg_path = os.path.split(test_doctest_path)[0] 1850 1851 >>> # Use it to find the absolute path of test_doctest.txt. 1852 >>> test_file = os.path.join(test_pkg_path, 'test_doctest.txt') 1853 1854 >>> suite = doctest.DocFileSuite(test_file, module_relative=False) 1855 >>> suite.run(unittest.TestResult()) 1856 <unittest.TestResult run=1 errors=0 failures=1> 1857 1858 It is an error to specify `package` when `module_relative=False`: 1859 1860 >>> suite = doctest.DocFileSuite(test_file, module_relative=False, 1861 ... package='test') 1862 Traceback (most recent call last): 1863 ValueError: Package may only be specified for module-relative paths. 1864 1865 You can specify initial global variables: 1866 1867 >>> suite = doctest.DocFileSuite('test_doctest.txt', 1868 ... 'test_doctest2.txt', 1869 ... globs={'favorite_color': 'blue'}) 1870 >>> suite.run(unittest.TestResult()) 1871 <unittest.TestResult run=2 errors=0 failures=1> 1872 1873 In this case, we supplied a missing favorite color. You can 1874 provide doctest options: 1875 1876 >>> suite = doctest.DocFileSuite('test_doctest.txt', 1877 ... 'test_doctest2.txt', 1878 ... optionflags=doctest.DONT_ACCEPT_BLANKLINE, 1879 ... globs={'favorite_color': 'blue'}) 1880 >>> suite.run(unittest.TestResult()) 1881 <unittest.TestResult run=2 errors=0 failures=2> 1882 1883 And, you can provide setUp and tearDown functions: 1884 1885 You can supply setUp and teatDoen functions: 1886 1887 >>> def setUp(t): 1888 ... import test.test_doctest 1889 ... test.test_doctest.sillySetup = True 1890 1891 >>> def tearDown(t): 1892 ... import test.test_doctest 1893 ... del test.test_doctest.sillySetup 1894 1895 Here, we installed a silly variable that the test expects: 1896 1897 >>> suite = doctest.DocFileSuite('test_doctest.txt', 1898 ... 'test_doctest2.txt', 1899 ... setUp=setUp, tearDown=tearDown) 1900 >>> suite.run(unittest.TestResult()) 1901 <unittest.TestResult run=2 errors=0 failures=1> 1902 1903 But the tearDown restores sanity: 1904 1905 >>> import test.test_doctest 1906 >>> test.test_doctest.sillySetup 1907 Traceback (most recent call last): 1908 ... 1909 AttributeError: 'module' object has no attribute 'sillySetup' 1910 1911 The setUp and tearDown funtions are passed test objects. 1912 Here, we'll use a setUp function to set the favorite color in 1913 test_doctest.txt: 1914 1915 >>> def setUp(test): 1916 ... test.globs['favorite_color'] = 'blue' 1917 1918 >>> suite = doctest.DocFileSuite('test_doctest.txt', setUp=setUp) 1919 >>> suite.run(unittest.TestResult()) 1920 <unittest.TestResult run=1 errors=0 failures=0> 1921 1922 Here, we didn't need to use a tearDown function because we 1923 modified the test globals. The test globals are 1924 automatically cleared for us after a test. 1925 1926 """ 1927 1928 def test_trailing_space_in_test(): 1929 """ 1930 Trailing spaces in expected output are significant: 1931 1932 >>> x, y = 'foo', '' 1933 >>> print x, y 1934 foo \n 1935 """ 1936 1937 1938 def test_unittest_reportflags(): 1939 """Default unittest reporting flags can be set to control reporting 1940 1941 Here, we'll set the REPORT_ONLY_FIRST_FAILURE option so we see 1942 only the first failure of each test. First, we'll look at the 1943 output without the flag. The file test_doctest.txt file has two 1944 tests. They both fail if blank lines are disabled: 1945 1946 >>> suite = doctest.DocFileSuite('test_doctest.txt', 1947 ... optionflags=doctest.DONT_ACCEPT_BLANKLINE) 1948 >>> import unittest 1949 >>> result = suite.run(unittest.TestResult()) 1950 >>> print result.failures[0][1] # doctest: +ELLIPSIS 1951 Traceback ... 1952 Failed example: 1953 favorite_color 1954 ... 1955 Failed example: 1956 if 1: 1957 ... 1958 1959 Note that we see both failures displayed. 1960 1961 >>> old = doctest.set_unittest_reportflags( 1962 ... doctest.REPORT_ONLY_FIRST_FAILURE) 1963 1964 Now, when we run the test: 1965 1966 >>> result = suite.run(unittest.TestResult()) 1967 >>> print result.failures[0][1] # doctest: +ELLIPSIS 1968 Traceback ... 1969 Failed example: 1970 favorite_color 1971 Exception raised: 1972 ... 1973 NameError: name 'favorite_color' is not defined 1974 <BLANKLINE> 1975 <BLANKLINE> 1976 1977 We get only the first failure. 1978 1979 If we give any reporting options when we set up the tests, 1980 however: 1981 1982 >>> suite = doctest.DocFileSuite('test_doctest.txt', 1983 ... optionflags=doctest.DONT_ACCEPT_BLANKLINE | doctest.REPORT_NDIFF) 1984 1985 Then the default eporting options are ignored: 1986 1987 >>> result = suite.run(unittest.TestResult()) 1988 >>> print result.failures[0][1] # doctest: +ELLIPSIS 1989 Traceback ... 1990 Failed example: 1991 favorite_color 1992 ... 1993 Failed example: 1994 if 1: 1995 print 'a' 1996 print 1997 print 'b' 1998 Differences (ndiff with -expected +actual): 1999 a 2000 - <BLANKLINE> 2001 + 2002 b 2003 <BLANKLINE> 2004 <BLANKLINE> 2005 2006 2007 Test runners can restore the formatting flags after they run: 2008 2009 >>> ignored = doctest.set_unittest_reportflags(old) 2010 2011 """ 2012 2013 def test_testfile(): r""" 2014 Tests for the `testfile()` function. This function runs all the 2015 doctest examples in a given file. In its simple invokation, it is 2016 called with the name of a file, which is taken to be relative to the 2017 calling module. The return value is (#failures, #tests). 2018 2019 >>> doctest.testfile('test_doctest.txt') # doctest: +ELLIPSIS 2020 ********************************************************************** 2021 File "...", line 6, in test_doctest.txt 2022 Failed example: 2023 favorite_color 2024 Exception raised: 2025 ... 2026 NameError: name 'favorite_color' is not defined 2027 ********************************************************************** 2028 1 items had failures: 2029 1 of 2 in test_doctest.txt 2030 ***Test Failed*** 1 failures. 2031 (1, 2) 2032 >>> doctest.master = None # Reset master. 2033 2034 (Note: we'll be clearing doctest.master after each call to 2035 `doctest.testfile`, to supress warnings about multiple tests with the 2036 same name.) 2037 2038 Globals may be specified with the `globs` and `extraglobs` parameters: 2039 2040 >>> globs = {'favorite_color': 'blue'} 2041 >>> doctest.testfile('test_doctest.txt', globs=globs) 2042 (0, 2) 2043 >>> doctest.master = None # Reset master. 2044 2045 >>> extraglobs = {'favorite_color': 'red'} 2046 >>> doctest.testfile('test_doctest.txt', globs=globs, 2047 ... extraglobs=extraglobs) # doctest: +ELLIPSIS 2048 ********************************************************************** 2049 File "...", line 6, in test_doctest.txt 2050 Failed example: 2051 favorite_color 2052 Expected: 2053 'blue' 2054 Got: 2055 'red' 2056 ********************************************************************** 2057 1 items had failures: 2058 1 of 2 in test_doctest.txt 2059 ***Test Failed*** 1 failures. 2060 (1, 2) 2061 >>> doctest.master = None # Reset master. 2062 2063 The file may be made relative to a given module or package, using the 2064 optional `module_relative` parameter: 2065 2066 >>> doctest.testfile('test_doctest.txt', globs=globs, 2067 ... module_relative='test') 2068 (0, 2) 2069 >>> doctest.master = None # Reset master. 2070 2071 Verbosity can be increased with the optional `verbose` paremter: 2072 2073 >>> doctest.testfile('test_doctest.txt', globs=globs, verbose=True) 2074 Trying: 2075 favorite_color 2076 Expecting: 2077 'blue' 2078 ok 2079 Trying: 2080 if 1: 2081 print 'a' 2082 print 2083 print 'b' 2084 Expecting: 2085 a 2086 <BLANKLINE> 2087 b 2088 ok 2089 1 items passed all tests: 2090 2 tests in test_doctest.txt 2091 2 tests in 1 items. 2092 2 passed and 0 failed. 2093 Test passed. 2094 (0, 2) 2095 >>> doctest.master = None # Reset master. 2096 2097 The name of the test may be specified with the optional `name` 2098 parameter: 2099 2100 >>> doctest.testfile('test_doctest.txt', name='newname') 2101 ... # doctest: +ELLIPSIS 2102 ********************************************************************** 2103 File "...", line 6, in newname 2104 ... 2105 (1, 2) 2106 >>> doctest.master = None # Reset master. 2107 2108 The summary report may be supressed with the optional `report` 2109 parameter: 2110 2111 >>> doctest.testfile('test_doctest.txt', report=False) 2112 ... # doctest: +ELLIPSIS 2113 ********************************************************************** 2114 File "...", line 6, in test_doctest.txt 2115 Failed example: 2116 favorite_color 2117 Exception raised: 2118 ... 2119 NameError: name 'favorite_color' is not defined 2120 (1, 2) 2121 >>> doctest.master = None # Reset master. 2122 2123 The optional keyword argument `raise_on_error` can be used to raise an 2124 exception on the first error (which may be useful for postmortem 2125 debugging): 2126 2127 >>> doctest.testfile('test_doctest.txt', raise_on_error=True) 2128 ... # doctest: +ELLIPSIS 2129 Traceback (most recent call last): 2130 UnexpectedException: ... 2131 >>> doctest.master = None # Reset master. 2132 """ 2133 2134 # old_test1, ... used to live in doctest.py, but cluttered it. Note 2135 # that these use the deprecated doctest.Tester, so should go away (or 2136 # be rewritten) someday. 2137 2138 # Ignore all warnings about the use of class Tester in this module. 2139 # Note that the name of this module may differ depending on how it's 2140 # imported, so the use of __name__ is important. 2141 warnings.filterwarnings("ignore", "class Tester", DeprecationWarning, 2142 __name__, 0) 2143 2144 def old_test1(): r""" 2145 >>> from doctest import Tester 2146 >>> t = Tester(globs={'x': 42}, verbose=0) 2147 >>> t.runstring(r''' 2148 ... >>> x = x * 2 2149 ... >>> print x 2150 ... 42 2151 ... ''', 'XYZ') 2152 ********************************************************************** 2153 Line 3, in XYZ 2154 Failed example: 2155 print x 2156 Expected: 2157 42 2158 Got: 2159 84 2160 (1, 2) 2161 >>> t.runstring(">>> x = x * 2\n>>> print x\n84\n", 'example2') 2162 (0, 2) 2163 >>> t.summarize() 2164 ********************************************************************** 2165 1 items had failures: 2166 1 of 2 in XYZ 2167 ***Test Failed*** 1 failures. 2168 (1, 4) 2169 >>> t.summarize(verbose=1) 2170 1 items passed all tests: 2171 2 tests in example2 2172 ********************************************************************** 2173 1 items had failures: 2174 1 of 2 in XYZ 2175 4 tests in 2 items. 2176 3 passed and 1 failed. 2177 ***Test Failed*** 1 failures. 2178 (1, 4) 2179 """ 2180 2181 def old_test2(): r""" 2182 >>> from doctest import Tester 2183 >>> t = Tester(globs={}, verbose=1) 2184 >>> test = r''' 2185 ... # just an example 2186 ... >>> x = 1 + 2 2187 ... >>> x 2188 ... 3 2189 ... ''' 2190 >>> t.runstring(test, "Example") 2191 Running string Example 2192 Trying: 2193 x = 1 + 2 2194 Expecting nothing 2195 ok 2196 Trying: 2197 x 2198 Expecting: 2199 3 2200 ok 2201 0 of 2 examples failed in string Example 2202 (0, 2) 2203 """ 2204 2205 def old_test3(): r""" 2206 >>> from doctest import Tester 2207 >>> t = Tester(globs={}, verbose=0) 2208 >>> def _f(): 2209 ... '''Trivial docstring example. 2210 ... >>> assert 2 == 2 2211 ... ''' 2212 ... return 32 2213 ... 2214 >>> t.rundoc(_f) # expect 0 failures in 1 example 2215 (0, 1) 2216 """ 2217 2218 def old_test4(): """ 2219 >>> import new 2220 >>> m1 = new.module('_m1') 2221 >>> m2 = new.module('_m2') 2222 >>> test_data = \""" 2223 ... def _f(): 2224 ... '''>>> assert 1 == 1 2225 ... ''' 2226 ... def g(): 2227 ... '''>>> assert 2 != 1 2228 ... ''' 2229 ... class H: 2230 ... '''>>> assert 2 > 1 2231 ... ''' 2232 ... def bar(self): 2233 ... '''>>> assert 1 < 2 2234 ... ''' 2235 ... \""" 2236 >>> exec test_data in m1.__dict__ 2237 >>> exec test_data in m2.__dict__ 2238 >>> m1.__dict__.update({"f2": m2._f, "g2": m2.g, "h2": m2.H}) 2239 2240 Tests that objects outside m1 are excluded: 2241 2242 >>> from doctest import Tester 2243 >>> t = Tester(globs={}, verbose=0) 2244 >>> t.rundict(m1.__dict__, "rundict_test", m1) # f2 and g2 and h2 skipped 2245 (0, 4) 2246 2247 Once more, not excluding stuff outside m1: 2248 2249 >>> t = Tester(globs={}, verbose=0) 2250 >>> t.rundict(m1.__dict__, "rundict_test_pvt") # None are skipped. 2251 (0, 8) 2252 2253 The exclusion of objects from outside the designated module is 2254 meant to be invoked automagically by testmod. 2255 2256 >>> doctest.testmod(m1, verbose=False) 2257 (0, 4) 2258 """ 2259 2260 ###################################################################### 2261 ## Main 2262 ###################################################################### 2263 2264 def test_main(): 2265 # Check the doctest cases in doctest itself: 2266 test_support.run_doctest(doctest, verbosity=True) 2267 # Check the doctest cases defined here: 2268 from test import test_doctest 2269 test_support.run_doctest(test_doctest, verbosity=True) 2270 2271 import trace, sys, re, StringIO 2272 def test_coverage(coverdir): 2273 tracer = trace.Trace(ignoredirs=[sys.prefix, sys.exec_prefix,], 2274 trace=0, count=1) 2275 tracer.run('reload(doctest); test_main()') 2276 r = tracer.results() 2277 print 'Writing coverage results...' 2278 r.write_results(show_missing=True, summary=True, 2279 coverdir=coverdir) 2280 2281 if __name__ == '__main__': 2282 if '-c' in sys.argv: 2283 test_coverage('/tmp/doctest.cover') 2284 else: 2285 test_main() 2286
Generated by PyXR 0.9.4