How to use test_doctest method in green

Best Python code snippet using green

test_doctest.py

Source:test_doctest.py

1"""2Test script for doctest.3"""4from test import support5import doctest6import os7import sys8# NOTE: There are some additional tests relating to interaction with9# zipimport in the test_zipimport_support test module.10######################################################################11## Sample Objects (used by test cases)12######################################################################13def sample_func(v):14 """15 Blah blah16 >>> print(sample_func(22))17 4418 Yee ha!19 """20 return v+v21class SampleClass:22 """23 >>> print(1)24 125 >>> # comments get ignored. so are empty PS1 and PS2 prompts:26 >>>27 ...28 Multiline example:29 >>> sc = SampleClass(3)30 >>> for i in range(10):31 ... sc = sc.double()32 ... print(' ', sc.get(), sep='', end='')33 6 12 24 48 96 192 384 768 1536 307234 """35 def __init__(self, val):36 """37 >>> print(SampleClass(12).get())38 1239 """40 self.val = val41 def double(self):42 """43 >>> print(SampleClass(12).double().get())44 2445 """46 return SampleClass(self.val + self.val)47 def get(self):48 """49 >>> print(SampleClass(-5).get())50 -551 """52 return self.val53 def a_staticmethod(v):54 """55 >>> print(SampleClass.a_staticmethod(10))56 1157 """58 return v+159 a_staticmethod = staticmethod(a_staticmethod)60 def a_classmethod(cls, v):61 """62 >>> print(SampleClass.a_classmethod(10))63 1264 >>> print(SampleClass(0).a_classmethod(10))65 1266 """67 return v+268 a_classmethod = classmethod(a_classmethod)69 a_property = property(get, doc="""70 >>> print(SampleClass(22).a_property)71 2272 """)73 class NestedClass:74 """75 >>> x = SampleClass.NestedClass(5)76 >>> y = x.square()77 >>> print(y.get())78 2579 """80 def __init__(self, val=0):81 """82 >>> print(SampleClass.NestedClass().get())83 084 """85 self.val = val86 def square(self):87 return SampleClass.NestedClass(self.val*self.val)88 def get(self):89 return self.val90class SampleNewStyleClass(object):91 r"""92 >>> print('1\n2\n3')93 194 295 396 """97 def __init__(self, val):98 """99 >>> print(SampleNewStyleClass(12).get())100 12101 """102 self.val = val103 def double(self):104 """105 >>> print(SampleNewStyleClass(12).double().get())106 24107 """108 return SampleNewStyleClass(self.val + self.val)109 def get(self):110 """111 >>> print(SampleNewStyleClass(-5).get())112 -5113 """114 return self.val115######################################################################116## Fake stdin (for testing interactive debugging)117######################################################################118class _FakeInput:119 """120 A fake input stream for pdb's interactive debugger. Whenever a121 line is read, print it (to simulate the user typing it), and then122 return it. The set of lines to return is specified in the123 constructor; they should not have trailing newlines.124 """125 def __init__(self, lines):126 self.lines = lines127 def readline(self):128 line = self.lines.pop(0)129 print(line)130 return line+'\n'131######################################################################132## Test Cases133######################################################################134def test_Example(): r"""135Unit tests for the `Example` class.136Example is a simple container class that holds:137 - `source`: A source string.138 - `want`: An expected output string.139 - `exc_msg`: An expected exception message string (or None if no140 exception is expected).141 - `lineno`: A line number (within the docstring).142 - `indent`: The example's indentation in the input string.143 - `options`: An option dictionary, mapping option flags to True or144 False.145These attributes are set by the constructor. `source` and `want` are146required; the other attributes all have default values:147 >>> example = doctest.Example('print(1)', '1\n')148 >>> (example.source, example.want, example.exc_msg,149 ... example.lineno, example.indent, example.options)150 ('print(1)\n', '1\n', None, 0, 0, {})151The first three attributes (`source`, `want`, and `exc_msg`) may be152specified positionally; the remaining arguments should be specified as153keyword arguments:154 >>> exc_msg = 'IndexError: pop from an empty list'155 >>> example = doctest.Example('[].pop()', '', exc_msg,156 ... lineno=5, indent=4,157 ... options={doctest.ELLIPSIS: True})158 >>> (example.source, example.want, example.exc_msg,159 ... example.lineno, example.indent, example.options)160 ('[].pop()\n', '', 'IndexError: pop from an empty list\n', 5, 4, {8: True})161The constructor normalizes the `source` string to end in a newline:162 Source spans a single line: no terminating newline.163 >>> e = doctest.Example('print(1)', '1\n')164 >>> e.source, e.want165 ('print(1)\n', '1\n')166 >>> e = doctest.Example('print(1)\n', '1\n')167 >>> e.source, e.want168 ('print(1)\n', '1\n')169 Source spans multiple lines: require terminating newline.170 >>> e = doctest.Example('print(1);\nprint(2)\n', '1\n2\n')171 >>> e.source, e.want172 ('print(1);\nprint(2)\n', '1\n2\n')173 >>> e = doctest.Example('print(1);\nprint(2)', '1\n2\n')174 >>> e.source, e.want175 ('print(1);\nprint(2)\n', '1\n2\n')176 Empty source string (which should never appear in real examples)177 >>> e = doctest.Example('', '')178 >>> e.source, e.want179 ('\n', '')180The constructor normalizes the `want` string to end in a newline,181unless it's the empty string:182 >>> e = doctest.Example('print(1)', '1\n')183 >>> e.source, e.want184 ('print(1)\n', '1\n')185 >>> e = doctest.Example('print(1)', '1')186 >>> e.source, e.want187 ('print(1)\n', '1\n')188 >>> e = doctest.Example('print', '')189 >>> e.source, e.want190 ('print\n', '')191The constructor normalizes the `exc_msg` string to end in a newline,192unless it's `None`:193 Message spans one line194 >>> exc_msg = 'IndexError: pop from an empty list'195 >>> e = doctest.Example('[].pop()', '', exc_msg)196 >>> e.exc_msg197 'IndexError: pop from an empty list\n'198 >>> exc_msg = 'IndexError: pop from an empty list\n'199 >>> e = doctest.Example('[].pop()', '', exc_msg)200 >>> e.exc_msg201 'IndexError: pop from an empty list\n'202 Message spans multiple lines203 >>> exc_msg = 'ValueError: 1\n 2'204 >>> e = doctest.Example('raise ValueError("1\n 2")', '', exc_msg)205 >>> e.exc_msg206 'ValueError: 1\n 2\n'207 >>> exc_msg = 'ValueError: 1\n 2\n'208 >>> e = doctest.Example('raise ValueError("1\n 2")', '', exc_msg)209 >>> e.exc_msg210 'ValueError: 1\n 2\n'211 Empty (but non-None) exception message (which should never appear212 in real examples)213 >>> exc_msg = ''214 >>> e = doctest.Example('raise X()', '', exc_msg)215 >>> e.exc_msg216 '\n'217Compare `Example`:218 >>> example = doctest.Example('print 1', '1\n')219 >>> same_example = doctest.Example('print 1', '1\n')220 >>> other_example = doctest.Example('print 42', '42\n')221 >>> example == same_example222 True223 >>> example != same_example224 False225 >>> hash(example) == hash(same_example)226 True227 >>> example == other_example228 False229 >>> example != other_example230 True231"""232def test_DocTest(): r"""233Unit tests for the `DocTest` class.234DocTest is a collection of examples, extracted from a docstring, along235with information about where the docstring comes from (a name,236filename, and line number). The docstring is parsed by the `DocTest`237constructor:238 >>> docstring = '''239 ... >>> print(12)240 ... 12241 ...242 ... Non-example text.243 ...244 ... >>> print('another\example')245 ... another246 ... example247 ... '''248 >>> globs = {} # globals to run the test in.249 >>> parser = doctest.DocTestParser()250 >>> test = parser.get_doctest(docstring, globs, 'some_test',251 ... 'some_file', 20)252 >>> print(test)253 <DocTest some_test from some_file:20 (2 examples)>254 >>> len(test.examples)255 2256 >>> e1, e2 = test.examples257 >>> (e1.source, e1.want, e1.lineno)258 ('print(12)\n', '12\n', 1)259 >>> (e2.source, e2.want, e2.lineno)260 ("print('another\\example')\n", 'another\nexample\n', 6)261Source information (name, filename, and line number) is available as262attributes on the doctest object:263 >>> (test.name, test.filename, test.lineno)264 ('some_test', 'some_file', 20)265The line number of an example within its containing file is found by266adding the line number of the example and the line number of its267containing test:268 >>> test.lineno + e1.lineno269 21270 >>> test.lineno + e2.lineno271 26272If the docstring contains inconsistant leading whitespace in the273expected output of an example, then `DocTest` will raise a ValueError:274 >>> docstring = r'''275 ... >>> print('bad\nindentation')276 ... bad277 ... indentation278 ... '''279 >>> parser.get_doctest(docstring, globs, 'some_test', 'filename', 0)280 Traceback (most recent call last):281 ValueError: line 4 of the docstring for some_test has inconsistent leading whitespace: 'indentation'282If the docstring contains inconsistent leading whitespace on283continuation lines, then `DocTest` will raise a ValueError:284 >>> docstring = r'''285 ... >>> print(('bad indentation',286 ... ... 2))287 ... ('bad', 'indentation')288 ... '''289 >>> parser.get_doctest(docstring, globs, 'some_test', 'filename', 0)290 Traceback (most recent call last):291 ValueError: line 2 of the docstring for some_test has inconsistent leading whitespace: '... 2))'292If there's no blank space after a PS1 prompt ('>>>'), then `DocTest`293will raise a ValueError:294 >>> docstring = '>>>print(1)\n1'295 >>> parser.get_doctest(docstring, globs, 'some_test', 'filename', 0)296 Traceback (most recent call last):297 ValueError: line 1 of the docstring for some_test lacks blank after >>>: '>>>print(1)'298If there's no blank space after a PS2 prompt ('...'), then `DocTest`299will raise a ValueError:300 >>> docstring = '>>> if 1:\n...print(1)\n1'301 >>> parser.get_doctest(docstring, globs, 'some_test', 'filename', 0)302 Traceback (most recent call last):303 ValueError: line 2 of the docstring for some_test lacks blank after ...: '...print(1)'304Compare `DocTest`:305 >>> docstring = '''306 ... >>> print 12307 ... 12308 ... '''309 >>> test = parser.get_doctest(docstring, globs, 'some_test',310 ... 'some_test', 20)311 >>> same_test = parser.get_doctest(docstring, globs, 'some_test',312 ... 'some_test', 20)313 >>> test == same_test314 True315 >>> test != same_test316 False317 >>> hash(test) == hash(same_test)318 True319 >>> docstring = '''320 ... >>> print 42321 ... 42322 ... '''323 >>> other_test = parser.get_doctest(docstring, globs, 'other_test',324 ... 'other_file', 10)325 >>> test == other_test326 False327 >>> test != other_test328 True329Compare `DocTestCase`:330 >>> DocTestCase = doctest.DocTestCase331 >>> test_case = DocTestCase(test)332 >>> same_test_case = DocTestCase(same_test)333 >>> other_test_case = DocTestCase(other_test)334 >>> test_case == same_test_case335 True336 >>> test_case != same_test_case337 False338 >>> hash(test_case) == hash(same_test_case)339 True340 >>> test == other_test_case341 False342 >>> test != other_test_case343 True344"""345class test_DocTestFinder:346 def basics(): r"""347Unit tests for the `DocTestFinder` class.348DocTestFinder is used to extract DocTests from an object's docstring349and the docstrings of its contained objects. It can be used with350modules, functions, classes, methods, staticmethods, classmethods, and351properties.352Finding Tests in Functions353~~~~~~~~~~~~~~~~~~~~~~~~~~354For a function whose docstring contains examples, DocTestFinder.find()355will return a single test (for that function's docstring):356 >>> finder = doctest.DocTestFinder()357We'll simulate a __file__ attr that ends in pyc:358 >>> import test.test_doctest359 >>> old = test.test_doctest.__file__360 >>> test.test_doctest.__file__ = 'test_doctest.pyc'361 >>> tests = finder.find(sample_func)362 >>> print(tests) # doctest: +ELLIPSIS363 [<DocTest sample_func from ...:18 (1 example)>]364The exact name depends on how test_doctest was invoked, so allow for365leading path components.366 >>> tests[0].filename # doctest: +ELLIPSIS367 '...test_doctest.py'368 >>> test.test_doctest.__file__ = old369 >>> e = tests[0].examples[0]370 >>> (e.source, e.want, e.lineno)371 ('print(sample_func(22))\n', '44\n', 3)372By default, tests are created for objects with no docstring:373 >>> def no_docstring(v):374 ... pass375 >>> finder.find(no_docstring)376 []377However, the optional argument `exclude_empty` to the DocTestFinder378constructor can be used to exclude tests for objects with empty379docstrings:380 >>> def no_docstring(v):381 ... pass382 >>> excl_empty_finder = doctest.DocTestFinder(exclude_empty=True)383 >>> excl_empty_finder.find(no_docstring)384 []385If the function has a docstring with no examples, then a test with no386examples is returned. (This lets `DocTestRunner` collect statistics387about which functions have no tests -- but is that useful? And should388an empty test also be created when there's no docstring?)389 >>> def no_examples(v):390 ... ''' no doctest examples '''391 >>> finder.find(no_examples) # doctest: +ELLIPSIS392 [<DocTest no_examples from ...:1 (no examples)>]393Finding Tests in Classes394~~~~~~~~~~~~~~~~~~~~~~~~395For a class, DocTestFinder will create a test for the class's396docstring, and will recursively explore its contents, including397methods, classmethods, staticmethods, properties, and nested classes.398 >>> finder = doctest.DocTestFinder()399 >>> tests = finder.find(SampleClass)400 >>> for t in tests:401 ... print('%2s %s' % (len(t.examples), t.name))402 3 SampleClass403 3 SampleClass.NestedClass404 1 SampleClass.NestedClass.__init__405 1 SampleClass.__init__406 2 SampleClass.a_classmethod407 1 SampleClass.a_property408 1 SampleClass.a_staticmethod409 1 SampleClass.double410 1 SampleClass.get411New-style classes are also supported:412 >>> tests = finder.find(SampleNewStyleClass)413 >>> for t in tests:414 ... print('%2s %s' % (len(t.examples), t.name))415 1 SampleNewStyleClass416 1 SampleNewStyleClass.__init__417 1 SampleNewStyleClass.double418 1 SampleNewStyleClass.get419Finding Tests in Modules420~~~~~~~~~~~~~~~~~~~~~~~~421For a module, DocTestFinder will create a test for the class's422docstring, and will recursively explore its contents, including423functions, classes, and the `__test__` dictionary, if it exists:424 >>> # A module425 >>> import types426 >>> m = types.ModuleType('some_module')427 >>> def triple(val):428 ... '''429 ... >>> print(triple(11))430 ... 33431 ... '''432 ... return val*3433 >>> m.__dict__.update({434 ... 'sample_func': sample_func,435 ... 'SampleClass': SampleClass,436 ... '__doc__': '''437 ... Module docstring.438 ... >>> print('module')439 ... module440 ... ''',441 ... '__test__': {442 ... 'd': '>>> print(6)\n6\n>>> print(7)\n7\n',443 ... 'c': triple}})444 >>> finder = doctest.DocTestFinder()445 >>> # Use module=test.test_doctest, to prevent doctest from446 >>> # ignoring the objects since they weren't defined in m.447 >>> import test.test_doctest448 >>> tests = finder.find(m, module=test.test_doctest)449 >>> for t in tests:450 ... print('%2s %s' % (len(t.examples), t.name))451 1 some_module452 3 some_module.SampleClass453 3 some_module.SampleClass.NestedClass454 1 some_module.SampleClass.NestedClass.__init__455 1 some_module.SampleClass.__init__456 2 some_module.SampleClass.a_classmethod457 1 some_module.SampleClass.a_property458 1 some_module.SampleClass.a_staticmethod459 1 some_module.SampleClass.double460 1 some_module.SampleClass.get461 1 some_module.__test__.c462 2 some_module.__test__.d463 1 some_module.sample_func464Duplicate Removal465~~~~~~~~~~~~~~~~~466If a single object is listed twice (under different names), then tests467will only be generated for it once:468 >>> from test import doctest_aliases469 >>> assert doctest_aliases.TwoNames.f470 >>> assert doctest_aliases.TwoNames.g471 >>> tests = excl_empty_finder.find(doctest_aliases)472 >>> print(len(tests))473 2474 >>> print(tests[0].name)475 test.doctest_aliases.TwoNames476 TwoNames.f and TwoNames.g are bound to the same object.477 We can't guess which will be found in doctest's traversal of478 TwoNames.__dict__ first, so we have to allow for either.479 >>> tests[1].name.split('.')[-1] in ['f', 'g']480 True481Empty Tests482~~~~~~~~~~~483By default, an object with no doctests doesn't create any tests:484 >>> tests = doctest.DocTestFinder().find(SampleClass)485 >>> for t in tests:486 ... print('%2s %s' % (len(t.examples), t.name))487 3 SampleClass488 3 SampleClass.NestedClass489 1 SampleClass.NestedClass.__init__490 1 SampleClass.__init__491 2 SampleClass.a_classmethod492 1 SampleClass.a_property493 1 SampleClass.a_staticmethod494 1 SampleClass.double495 1 SampleClass.get496By default, that excluded objects with no doctests. exclude_empty=False497tells it to include (empty) tests for objects with no doctests. This feature498is really to support backward compatibility in what doctest.master.summarize()499displays.500 >>> tests = doctest.DocTestFinder(exclude_empty=False).find(SampleClass)501 >>> for t in tests:502 ... print('%2s %s' % (len(t.examples), t.name))503 3 SampleClass504 3 SampleClass.NestedClass505 1 SampleClass.NestedClass.__init__506 0 SampleClass.NestedClass.get507 0 SampleClass.NestedClass.square508 1 SampleClass.__init__509 2 SampleClass.a_classmethod510 1 SampleClass.a_property511 1 SampleClass.a_staticmethod512 1 SampleClass.double513 1 SampleClass.get514Turning off Recursion515~~~~~~~~~~~~~~~~~~~~~516DocTestFinder can be told not to look for tests in contained objects517using the `recurse` flag:518 >>> tests = doctest.DocTestFinder(recurse=False).find(SampleClass)519 >>> for t in tests:520 ... print('%2s %s' % (len(t.examples), t.name))521 3 SampleClass522Line numbers523~~~~~~~~~~~~524DocTestFinder finds the line number of each example:525 >>> def f(x):526 ... '''527 ... >>> x = 12528 ...529 ... some text530 ...531 ... >>> # examples are not created for comments & bare prompts.532 ... >>>533 ... ...534 ...535 ... >>> for x in range(10):536 ... ... print(x, end=' ')537 ... 0 1 2 3 4 5 6 7 8 9538 ... >>> x//2539 ... 6540 ... '''541 >>> test = doctest.DocTestFinder().find(f)[0]542 >>> [e.lineno for e in test.examples]543 [1, 9, 12]544"""545 if int.__doc__: # simple check for --without-doc-strings, skip if lacking546 def non_Python_modules(): r"""547Finding Doctests in Modules Not Written in Python548~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~549DocTestFinder can also find doctests in most modules not written in Python.550We'll use builtins as an example, since it almost certainly isn't written in551plain ol' Python and is guaranteed to be available.552 >>> import builtins553 >>> tests = doctest.DocTestFinder().find(builtins)554 >>> 790 < len(tests) < 800 # approximate number of objects with docstrings555 True556 >>> real_tests = [t for t in tests if len(t.examples) > 0]557 >>> len(real_tests) # objects that actually have doctests558 8559 >>> for t in real_tests:560 ... print('{} {}'.format(len(t.examples), t.name))561 ...562 1 builtins.bin563 3 builtins.float.as_integer_ratio564 2 builtins.float.fromhex565 2 builtins.float.hex566 1 builtins.hex567 1 builtins.int568 2 builtins.int.bit_length569 1 builtins.oct570Note here that 'bin', 'oct', and 'hex' are functions; 'float.as_integer_ratio',571'float.hex', and 'int.bit_length' are methods; 'float.fromhex' is a classmethod,572and 'int' is a type.573"""574def test_DocTestParser(): r"""575Unit tests for the `DocTestParser` class.576DocTestParser is used to parse docstrings containing doctest examples.577The `parse` method divides a docstring into examples and intervening578text:579 >>> s = '''580 ... >>> x, y = 2, 3 # no output expected581 ... >>> if 1:582 ... ... print(x)583 ... ... print(y)584 ... 2585 ... 3586 ...587 ... Some text.588 ... >>> x+y589 ... 5590 ... '''591 >>> parser = doctest.DocTestParser()592 >>> for piece in parser.parse(s):593 ... if isinstance(piece, doctest.Example):594 ... print('Example:', (piece.source, piece.want, piece.lineno))595 ... else:596 ... print(' Text:', repr(piece))597 Text: '\n'598 Example: ('x, y = 2, 3 # no output expected\n', '', 1)599 Text: ''600 Example: ('if 1:\n print(x)\n print(y)\n', '2\n3\n', 2)601 Text: '\nSome text.\n'602 Example: ('x+y\n', '5\n', 9)603 Text: ''604The `get_examples` method returns just the examples:605 >>> for piece in parser.get_examples(s):606 ... print((piece.source, piece.want, piece.lineno))607 ('x, y = 2, 3 # no output expected\n', '', 1)608 ('if 1:\n print(x)\n print(y)\n', '2\n3\n', 2)609 ('x+y\n', '5\n', 9)610The `get_doctest` method creates a Test from the examples, along with the611given arguments:612 >>> test = parser.get_doctest(s, {}, 'name', 'filename', lineno=5)613 >>> (test.name, test.filename, test.lineno)614 ('name', 'filename', 5)615 >>> for piece in test.examples:616 ... print((piece.source, piece.want, piece.lineno))617 ('x, y = 2, 3 # no output expected\n', '', 1)618 ('if 1:\n print(x)\n print(y)\n', '2\n3\n', 2)619 ('x+y\n', '5\n', 9)620"""621class test_DocTestRunner:622 def basics(): r"""623Unit tests for the `DocTestRunner` class.624DocTestRunner is used to run DocTest test cases, and to accumulate625statistics. Here's a simple DocTest case we can use:626 >>> def f(x):627 ... '''628 ... >>> x = 12629 ... >>> print(x)630 ... 12631 ... >>> x//2632 ... 6633 ... '''634 >>> test = doctest.DocTestFinder().find(f)[0]635The main DocTestRunner interface is the `run` method, which runs a636given DocTest case in a given namespace (globs). It returns a tuple637`(f,t)`, where `f` is the number of failed tests and `t` is the number638of tried tests.639 >>> doctest.DocTestRunner(verbose=False).run(test)640 TestResults(failed=0, attempted=3)641If any example produces incorrect output, then the test runner reports642the failure and proceeds to the next example:643 >>> def f(x):644 ... '''645 ... >>> x = 12646 ... >>> print(x)647 ... 14648 ... >>> x//2649 ... 6650 ... '''651 >>> test = doctest.DocTestFinder().find(f)[0]652 >>> doctest.DocTestRunner(verbose=True).run(test)653 ... # doctest: +ELLIPSIS654 Trying:655 x = 12656 Expecting nothing657 ok658 Trying:659 print(x)660 Expecting:661 14662 **********************************************************************663 File ..., line 4, in f664 Failed example:665 print(x)666 Expected:667 14668 Got:669 12670 Trying:671 x//2672 Expecting:673 6674 ok675 TestResults(failed=1, attempted=3)676"""677 def verbose_flag(): r"""678The `verbose` flag makes the test runner generate more detailed679output:680 >>> def f(x):681 ... '''682 ... >>> x = 12683 ... >>> print(x)684 ... 12685 ... >>> x//2686 ... 6687 ... '''688 >>> test = doctest.DocTestFinder().find(f)[0]689 >>> doctest.DocTestRunner(verbose=True).run(test)690 Trying:691 x = 12692 Expecting nothing693 ok694 Trying:695 print(x)696 Expecting:697 12698 ok699 Trying:700 x//2701 Expecting:702 6703 ok704 TestResults(failed=0, attempted=3)705If the `verbose` flag is unspecified, then the output will be verbose706iff `-v` appears in sys.argv:707 >>> # Save the real sys.argv list.708 >>> old_argv = sys.argv709 >>> # If -v does not appear in sys.argv, then output isn't verbose.710 >>> sys.argv = ['test']711 >>> doctest.DocTestRunner().run(test)712 TestResults(failed=0, attempted=3)713 >>> # If -v does appear in sys.argv, then output is verbose.714 >>> sys.argv = ['test', '-v']715 >>> doctest.DocTestRunner().run(test)716 Trying:717 x = 12718 Expecting nothing719 ok720 Trying:721 print(x)722 Expecting:723 12724 ok725 Trying:726 x//2727 Expecting:728 6729 ok730 TestResults(failed=0, attempted=3)731 >>> # Restore sys.argv732 >>> sys.argv = old_argv733In the remaining examples, the test runner's verbosity will be734explicitly set, to ensure that the test behavior is consistent.735 """736 def exceptions(): r"""737Tests of `DocTestRunner`'s exception handling.738An expected exception is specified with a traceback message. The739lines between the first line and the type/value may be omitted or740replaced with any other string:741 >>> def f(x):742 ... '''743 ... >>> x = 12744 ... >>> print(x//0)745 ... Traceback (most recent call last):746 ... ZeroDivisionError: integer division or modulo by zero747 ... '''748 >>> test = doctest.DocTestFinder().find(f)[0]749 >>> doctest.DocTestRunner(verbose=False).run(test)750 TestResults(failed=0, attempted=2)751An example may not generate output before it raises an exception; if752it does, then the traceback message will not be recognized as753signaling an expected exception, so the example will be reported as an754unexpected exception:755 >>> def f(x):756 ... '''757 ... >>> x = 12758 ... >>> print('pre-exception output', x//0)759 ... pre-exception output760 ... Traceback (most recent call last):761 ... ZeroDivisionError: integer division or modulo by zero762 ... '''763 >>> test = doctest.DocTestFinder().find(f)[0]764 >>> doctest.DocTestRunner(verbose=False).run(test)765 ... # doctest: +ELLIPSIS766 **********************************************************************767 File ..., line 4, in f768 Failed example:769 print('pre-exception output', x//0)770 Exception raised:771 ...772 ZeroDivisionError: integer division or modulo by zero773 TestResults(failed=1, attempted=2)774Exception messages may contain newlines:775 >>> def f(x):776 ... r'''777 ... >>> raise ValueError('multi\nline\nmessage')778 ... Traceback (most recent call last):779 ... ValueError: multi780 ... line781 ... message782 ... '''783 >>> test = doctest.DocTestFinder().find(f)[0]784 >>> doctest.DocTestRunner(verbose=False).run(test)785 TestResults(failed=0, attempted=1)786If an exception is expected, but an exception with the wrong type or787message is raised, then it is reported as a failure:788 >>> def f(x):789 ... r'''790 ... >>> raise ValueError('message')791 ... Traceback (most recent call last):792 ... ValueError: wrong message793 ... '''794 >>> test = doctest.DocTestFinder().find(f)[0]795 >>> doctest.DocTestRunner(verbose=False).run(test)796 ... # doctest: +ELLIPSIS797 **********************************************************************798 File ..., line 3, in f799 Failed example:800 raise ValueError('message')801 Expected:802 Traceback (most recent call last):803 ValueError: wrong message804 Got:805 Traceback (most recent call last):806 ...807 ValueError: message808 TestResults(failed=1, attempted=1)809However, IGNORE_EXCEPTION_DETAIL can be used to allow a mismatch in the810detail:811 >>> def f(x):812 ... r'''813 ... >>> raise ValueError('message') #doctest: +IGNORE_EXCEPTION_DETAIL814 ... Traceback (most recent call last):815 ... ValueError: wrong message816 ... '''817 >>> test = doctest.DocTestFinder().find(f)[0]818 >>> doctest.DocTestRunner(verbose=False).run(test)819 TestResults(failed=0, attempted=1)820IGNORE_EXCEPTION_DETAIL also ignores difference in exception formatting821between Python versions. For example, in Python 2.x, the module path of822the exception is not in the output, but this will fail under Python 3:823 >>> def f(x):824 ... r'''825 ... >>> from http.client import HTTPException826 ... >>> raise HTTPException('message')827 ... Traceback (most recent call last):828 ... HTTPException: message829 ... '''830 >>> test = doctest.DocTestFinder().find(f)[0]831 >>> doctest.DocTestRunner(verbose=False).run(test)832 ... # doctest: +ELLIPSIS833 **********************************************************************834 File ..., line 4, in f835 Failed example:836 raise HTTPException('message')837 Expected:838 Traceback (most recent call last):839 HTTPException: message840 Got:841 Traceback (most recent call last):842 ...843 http.client.HTTPException: message844 TestResults(failed=1, attempted=2)845But in Python 3 the module path is included, and therefore a test must look846like the following test to succeed in Python 3. But that test will fail under847Python 2.848 >>> def f(x):849 ... r'''850 ... >>> from http.client import HTTPException851 ... >>> raise HTTPException('message')852 ... Traceback (most recent call last):853 ... http.client.HTTPException: message854 ... '''855 >>> test = doctest.DocTestFinder().find(f)[0]856 >>> doctest.DocTestRunner(verbose=False).run(test)857 TestResults(failed=0, attempted=2)858However, with IGNORE_EXCEPTION_DETAIL, the module name of the exception859(or its unexpected absence) will be ignored:860 >>> def f(x):861 ... r'''862 ... >>> from http.client import HTTPException863 ... >>> raise HTTPException('message') #doctest: +IGNORE_EXCEPTION_DETAIL864 ... Traceback (most recent call last):865 ... HTTPException: message866 ... '''867 >>> test = doctest.DocTestFinder().find(f)[0]868 >>> doctest.DocTestRunner(verbose=False).run(test)869 TestResults(failed=0, attempted=2)870The module path will be completely ignored, so two different module paths will871still pass if IGNORE_EXCEPTION_DETAIL is given. This is intentional, so it can872be used when exceptions have changed module.873 >>> def f(x):874 ... r'''875 ... >>> from http.client import HTTPException876 ... >>> raise HTTPException('message') #doctest: +IGNORE_EXCEPTION_DETAIL877 ... Traceback (most recent call last):878 ... foo.bar.HTTPException: message879 ... '''880 >>> test = doctest.DocTestFinder().find(f)[0]881 >>> doctest.DocTestRunner(verbose=False).run(test)882 TestResults(failed=0, attempted=2)883But IGNORE_EXCEPTION_DETAIL does not allow a mismatch in the exception type:884 >>> def f(x):885 ... r'''886 ... >>> raise ValueError('message') #doctest: +IGNORE_EXCEPTION_DETAIL887 ... Traceback (most recent call last):888 ... TypeError: wrong type889 ... '''890 >>> test = doctest.DocTestFinder().find(f)[0]891 >>> doctest.DocTestRunner(verbose=False).run(test)892 ... # doctest: +ELLIPSIS893 **********************************************************************894 File ..., line 3, in f895 Failed example:896 raise ValueError('message') #doctest: +IGNORE_EXCEPTION_DETAIL897 Expected:898 Traceback (most recent call last):899 TypeError: wrong type900 Got:901 Traceback (most recent call last):902 ...903 ValueError: message904 TestResults(failed=1, attempted=1)905If the exception does not have a message, you can still use906IGNORE_EXCEPTION_DETAIL to normalize the modules between Python 2 and 3:907 >>> def f(x):908 ... r'''909 ... >>> from http.client import HTTPException910 ... >>> raise HTTPException() #doctest: +IGNORE_EXCEPTION_DETAIL911 ... Traceback (most recent call last):912 ... foo.bar.HTTPException913 ... '''914 >>> test = doctest.DocTestFinder().find(f)[0]915 >>> doctest.DocTestRunner(verbose=False).run(test)916 TestResults(failed=0, attempted=2)917Note that a trailing colon doesn't matter either:918 >>> def f(x):919 ... r'''920 ... >>> from http.client import HTTPException921 ... >>> raise HTTPException() #doctest: +IGNORE_EXCEPTION_DETAIL922 ... Traceback (most recent call last):923 ... foo.bar.HTTPException:924 ... '''925 >>> test = doctest.DocTestFinder().find(f)[0]926 >>> doctest.DocTestRunner(verbose=False).run(test)927 TestResults(failed=0, attempted=2)928If an exception is raised but not expected, then it is reported as an929unexpected exception:930 >>> def f(x):931 ... r'''932 ... >>> 1//0933 ... 0934 ... '''935 >>> test = doctest.DocTestFinder().find(f)[0]936 >>> doctest.DocTestRunner(verbose=False).run(test)937 ... # doctest: +ELLIPSIS938 **********************************************************************939 File ..., line 3, in f940 Failed example:941 1//0942 Exception raised:943 Traceback (most recent call last):944 ...945 ZeroDivisionError: integer division or modulo by zero946 TestResults(failed=1, attempted=1)947"""948 def displayhook(): r"""949Test that changing sys.displayhook doesn't matter for doctest.950 >>> import sys951 >>> orig_displayhook = sys.displayhook952 >>> def my_displayhook(x):953 ... print('hi!')954 >>> sys.displayhook = my_displayhook955 >>> def f():956 ... '''957 ... >>> 3958 ... 3959 ... '''960 >>> test = doctest.DocTestFinder().find(f)[0]961 >>> r = doctest.DocTestRunner(verbose=False).run(test)962 >>> post_displayhook = sys.displayhook963 We need to restore sys.displayhook now, so that we'll be able to test964 results.965 >>> sys.displayhook = orig_displayhook966 Ok, now we can check that everything is ok.967 >>> r968 TestResults(failed=0, attempted=1)969 >>> post_displayhook is my_displayhook970 True971"""972 def optionflags(): r"""973Tests of `DocTestRunner`'s option flag handling.974Several option flags can be used to customize the behavior of the test975runner. These are defined as module constants in doctest, and passed976to the DocTestRunner constructor (multiple constants should be ORed977together).978The DONT_ACCEPT_TRUE_FOR_1 flag disables matches between True/False979and 1/0:980 >>> def f(x):981 ... '>>> True\n1\n'982 >>> # Without the flag:983 >>> test = doctest.DocTestFinder().find(f)[0]984 >>> doctest.DocTestRunner(verbose=False).run(test)985 TestResults(failed=0, attempted=1)986 >>> # With the flag:987 >>> test = doctest.DocTestFinder().find(f)[0]988 >>> flags = doctest.DONT_ACCEPT_TRUE_FOR_1989 >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)990 ... # doctest: +ELLIPSIS991 **********************************************************************992 File ..., line 2, in f993 Failed example:994 True995 Expected:996 1997 Got:998 True999 TestResults(failed=1, attempted=1)1000The DONT_ACCEPT_BLANKLINE flag disables the match between blank lines1001and the '<BLANKLINE>' marker:1002 >>> def f(x):1003 ... '>>> print("a\\n\\nb")\na\n<BLANKLINE>\nb\n'1004 >>> # Without the flag:1005 >>> test = doctest.DocTestFinder().find(f)[0]1006 >>> doctest.DocTestRunner(verbose=False).run(test)1007 TestResults(failed=0, attempted=1)1008 >>> # With the flag:1009 >>> test = doctest.DocTestFinder().find(f)[0]1010 >>> flags = doctest.DONT_ACCEPT_BLANKLINE1011 >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)1012 ... # doctest: +ELLIPSIS1013 **********************************************************************1014 File ..., line 2, in f1015 Failed example:1016 print("a\n\nb")1017 Expected:1018 a1019 <BLANKLINE>1020 b1021 Got:1022 a1023 <BLANKLINE>1024 b1025 TestResults(failed=1, attempted=1)1026The NORMALIZE_WHITESPACE flag causes all sequences of whitespace to be1027treated as equal:1028 >>> def f(x):1029 ... '>>> print(1, 2, 3)\n 1 2\n 3'1030 >>> # Without the flag:1031 >>> test = doctest.DocTestFinder().find(f)[0]1032 >>> doctest.DocTestRunner(verbose=False).run(test)1033 ... # doctest: +ELLIPSIS1034 **********************************************************************1035 File ..., line 2, in f1036 Failed example:1037 print(1, 2, 3)1038 Expected:1039 1 21040 31041 Got:1042 1 2 31043 TestResults(failed=1, attempted=1)1044 >>> # With the flag:1045 >>> test = doctest.DocTestFinder().find(f)[0]1046 >>> flags = doctest.NORMALIZE_WHITESPACE1047 >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)1048 TestResults(failed=0, attempted=1)1049 An example from the docs:1050 >>> print(list(range(20))) #doctest: +NORMALIZE_WHITESPACE1051 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9,1052 10, 11, 12, 13, 14, 15, 16, 17, 18, 19]1053The ELLIPSIS flag causes ellipsis marker ("...") in the expected1054output to match any substring in the actual output:1055 >>> def f(x):1056 ... '>>> print(list(range(15)))\n[0, 1, 2, ..., 14]\n'1057 >>> # Without the flag:1058 >>> test = doctest.DocTestFinder().find(f)[0]1059 >>> doctest.DocTestRunner(verbose=False).run(test)1060 ... # doctest: +ELLIPSIS1061 **********************************************************************1062 File ..., line 2, in f1063 Failed example:1064 print(list(range(15)))1065 Expected:1066 [0, 1, 2, ..., 14]1067 Got:1068 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14]1069 TestResults(failed=1, attempted=1)1070 >>> # With the flag:1071 >>> test = doctest.DocTestFinder().find(f)[0]1072 >>> flags = doctest.ELLIPSIS1073 >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)1074 TestResults(failed=0, attempted=1)1075 ... also matches nothing:1076 >>> if 1:1077 ... for i in range(100):1078 ... print(i**2, end=' ') #doctest: +ELLIPSIS1079 ... print('!')1080 0 1...4...9 16 ... 36 49 64 ... 9801 !1081 ... can be surprising; e.g., this test passes:1082 >>> if 1: #doctest: +ELLIPSIS1083 ... for i in range(20):1084 ... print(i, end=' ')1085 ... print(20)1086 0 1 2 ...1...2...01087 Examples from the docs:1088 >>> print(list(range(20))) # doctest:+ELLIPSIS1089 [0, 1, ..., 18, 19]1090 >>> print(list(range(20))) # doctest: +ELLIPSIS1091 ... # doctest: +NORMALIZE_WHITESPACE1092 [0, 1, ..., 18, 19]1093The SKIP flag causes an example to be skipped entirely. I.e., the1094example is not run. It can be useful in contexts where doctest1095examples serve as both documentation and test cases, and an example1096should be included for documentation purposes, but should not be1097checked (e.g., because its output is random, or depends on resources1098which would be unavailable.) The SKIP flag can also be used for1099'commenting out' broken examples.1100 >>> import unavailable_resource # doctest: +SKIP1101 >>> unavailable_resource.do_something() # doctest: +SKIP1102 >>> unavailable_resource.blow_up() # doctest: +SKIP1103 Traceback (most recent call last):1104 ...1105 UncheckedBlowUpError: Nobody checks me.1106 >>> import random1107 >>> print(random.random()) # doctest: +SKIP1108 0.7212169238891109The REPORT_UDIFF flag causes failures that involve multi-line expected1110and actual outputs to be displayed using a unified diff:1111 >>> def f(x):1112 ... r'''1113 ... >>> print('\n'.join('abcdefg'))1114 ... a1115 ... B1116 ... c1117 ... d1118 ... f1119 ... g1120 ... h1121 ... '''1122 >>> # Without the flag:1123 >>> test = doctest.DocTestFinder().find(f)[0]1124 >>> doctest.DocTestRunner(verbose=False).run(test)1125 ... # doctest: +ELLIPSIS1126 **********************************************************************1127 File ..., line 3, in f1128 Failed example:1129 print('\n'.join('abcdefg'))1130 Expected:1131 a1132 B1133 c1134 d1135 f1136 g1137 h1138 Got:1139 a1140 b1141 c1142 d1143 e1144 f1145 g1146 TestResults(failed=1, attempted=1)1147 >>> # With the flag:1148 >>> test = doctest.DocTestFinder().find(f)[0]1149 >>> flags = doctest.REPORT_UDIFF1150 >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)1151 ... # doctest: +ELLIPSIS1152 **********************************************************************1153 File ..., line 3, in f1154 Failed example:1155 print('\n'.join('abcdefg'))1156 Differences (unified diff with -expected +actual):1157 @@ -1,7 +1,7 @@1158 a1159 -B1160 +b1161 c1162 d1163 +e1164 f1165 g1166 -h1167 TestResults(failed=1, attempted=1)1168The REPORT_CDIFF flag causes failures that involve multi-line expected1169and actual outputs to be displayed using a context diff:1170 >>> # Reuse f() from the REPORT_UDIFF example, above.1171 >>> test = doctest.DocTestFinder().find(f)[0]1172 >>> flags = doctest.REPORT_CDIFF1173 >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)1174 ... # doctest: +ELLIPSIS1175 **********************************************************************1176 File ..., line 3, in f1177 Failed example:1178 print('\n'.join('abcdefg'))1179 Differences (context diff with expected followed by actual):1180 ***************1181 *** 1,7 ****1182 a1183 ! B1184 c1185 d1186 f1187 g1188 - h1189 --- 1,7 ----1190 a1191 ! b1192 c1193 d1194 + e1195 f1196 g1197 TestResults(failed=1, attempted=1)1198The REPORT_NDIFF flag causes failures to use the difflib.Differ algorithm1199used by the popular ndiff.py utility. This does intraline difference1200marking, as well as interline differences.1201 >>> def f(x):1202 ... r'''1203 ... >>> print("a b c d e f g h i j k l m")1204 ... a b c d e f g h i j k 1 m1205 ... '''1206 >>> test = doctest.DocTestFinder().find(f)[0]1207 >>> flags = doctest.REPORT_NDIFF1208 >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)1209 ... # doctest: +ELLIPSIS1210 **********************************************************************1211 File ..., line 3, in f1212 Failed example:1213 print("a b c d e f g h i j k l m")1214 Differences (ndiff with -expected +actual):1215 - a b c d e f g h i j k 1 m1216 ? ^1217 + a b c d e f g h i j k l m1218 ? + ++ ^1219 TestResults(failed=1, attempted=1)1220The REPORT_ONLY_FIRST_FAILURE suppresses result output after the first1221failing example:1222 >>> def f(x):1223 ... r'''1224 ... >>> print(1) # first success1225 ... 11226 ... >>> print(2) # first failure1227 ... 2001228 ... >>> print(3) # second failure1229 ... 3001230 ... >>> print(4) # second success1231 ... 41232 ... >>> print(5) # third failure1233 ... 5001234 ... '''1235 >>> test = doctest.DocTestFinder().find(f)[0]1236 >>> flags = doctest.REPORT_ONLY_FIRST_FAILURE1237 >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)1238 ... # doctest: +ELLIPSIS1239 **********************************************************************1240 File ..., line 5, in f1241 Failed example:1242 print(2) # first failure1243 Expected:1244 2001245 Got:1246 21247 TestResults(failed=3, attempted=5)1248However, output from `report_start` is not suppressed:1249 >>> doctest.DocTestRunner(verbose=True, optionflags=flags).run(test)1250 ... # doctest: +ELLIPSIS1251 Trying:1252 print(1) # first success1253 Expecting:1254 11255 ok1256 Trying:1257 print(2) # first failure1258 Expecting:1259 2001260 **********************************************************************1261 File ..., line 5, in f1262 Failed example:1263 print(2) # first failure1264 Expected:1265 2001266 Got:1267 21268 TestResults(failed=3, attempted=5)1269The FAIL_FAST flag causes the runner to exit after the first failing example,1270so subsequent examples are not even attempted:1271 >>> flags = doctest.FAIL_FAST1272 >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)1273 ... # doctest: +ELLIPSIS1274 **********************************************************************1275 File ..., line 5, in f1276 Failed example:1277 print(2) # first failure1278 Expected:1279 2001280 Got:1281 21282 TestResults(failed=1, attempted=2)1283Specifying both FAIL_FAST and REPORT_ONLY_FIRST_FAILURE is equivalent to1284FAIL_FAST only:1285 >>> flags = doctest.FAIL_FAST | doctest.REPORT_ONLY_FIRST_FAILURE1286 >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)1287 ... # doctest: +ELLIPSIS1288 **********************************************************************1289 File ..., line 5, in f1290 Failed example:1291 print(2) # first failure1292 Expected:1293 2001294 Got:1295 21296 TestResults(failed=1, attempted=2)1297For the purposes of both REPORT_ONLY_FIRST_FAILURE and FAIL_FAST, unexpected1298exceptions count as failures:1299 >>> def f(x):1300 ... r'''1301 ... >>> print(1) # first success1302 ... 11303 ... >>> raise ValueError(2) # first failure1304 ... 2001305 ... >>> print(3) # second failure1306 ... 3001307 ... >>> print(4) # second success1308 ... 41309 ... >>> print(5) # third failure1310 ... 5001311 ... '''1312 >>> test = doctest.DocTestFinder().find(f)[0]1313 >>> flags = doctest.REPORT_ONLY_FIRST_FAILURE1314 >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)1315 ... # doctest: +ELLIPSIS1316 **********************************************************************1317 File ..., line 5, in f1318 Failed example:1319 raise ValueError(2) # first failure1320 Exception raised:1321 ...1322 ValueError: 21323 TestResults(failed=3, attempted=5)1324 >>> flags = doctest.FAIL_FAST1325 >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)1326 ... # doctest: +ELLIPSIS1327 **********************************************************************1328 File ..., line 5, in f1329 Failed example:1330 raise ValueError(2) # first failure1331 Exception raised:1332 ...1333 ValueError: 21334 TestResults(failed=1, attempted=2)1335New option flags can also be registered, via register_optionflag(). Here1336we reach into doctest's internals a bit.1337 >>> unlikely = "UNLIKELY_OPTION_NAME"1338 >>> unlikely in doctest.OPTIONFLAGS_BY_NAME1339 False1340 >>> new_flag_value = doctest.register_optionflag(unlikely)1341 >>> unlikely in doctest.OPTIONFLAGS_BY_NAME1342 True1343Before 2.4.4/2.5, registering a name more than once erroneously created1344more than one flag value. Here we verify that's fixed:1345 >>> redundant_flag_value = doctest.register_optionflag(unlikely)1346 >>> redundant_flag_value == new_flag_value1347 True1348Clean up.1349 >>> del doctest.OPTIONFLAGS_BY_NAME[unlikely]1350 """1351 def option_directives(): r"""1352Tests of `DocTestRunner`'s option directive mechanism.1353Option directives can be used to turn option flags on or off for a1354single example. To turn an option on for an example, follow that1355example with a comment of the form ``# doctest: +OPTION``:1356 >>> def f(x): r'''1357 ... >>> print(list(range(10))) # should fail: no ellipsis1358 ... [0, 1, ..., 9]1359 ...1360 ... >>> print(list(range(10))) # doctest: +ELLIPSIS1361 ... [0, 1, ..., 9]1362 ... '''1363 >>> test = doctest.DocTestFinder().find(f)[0]1364 >>> doctest.DocTestRunner(verbose=False).run(test)1365 ... # doctest: +ELLIPSIS1366 **********************************************************************1367 File ..., line 2, in f1368 Failed example:1369 print(list(range(10))) # should fail: no ellipsis1370 Expected:1371 [0, 1, ..., 9]1372 Got:1373 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]1374 TestResults(failed=1, attempted=2)1375To turn an option off for an example, follow that example with a1376comment of the form ``# doctest: -OPTION``:1377 >>> def f(x): r'''1378 ... >>> print(list(range(10)))1379 ... [0, 1, ..., 9]1380 ...1381 ... >>> # should fail: no ellipsis1382 ... >>> print(list(range(10))) # doctest: -ELLIPSIS1383 ... [0, 1, ..., 9]1384 ... '''1385 >>> test = doctest.DocTestFinder().find(f)[0]1386 >>> doctest.DocTestRunner(verbose=False,1387 ... optionflags=doctest.ELLIPSIS).run(test)1388 ... # doctest: +ELLIPSIS1389 **********************************************************************1390 File ..., line 6, in f1391 Failed example:1392 print(list(range(10))) # doctest: -ELLIPSIS1393 Expected:1394 [0, 1, ..., 9]1395 Got:1396 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]1397 TestResults(failed=1, attempted=2)1398Option directives affect only the example that they appear with; they1399do not change the options for surrounding examples:1400 >>> def f(x): r'''1401 ... >>> print(list(range(10))) # Should fail: no ellipsis1402 ... [0, 1, ..., 9]1403 ...1404 ... >>> print(list(range(10))) # doctest: +ELLIPSIS1405 ... [0, 1, ..., 9]1406 ...1407 ... >>> print(list(range(10))) # Should fail: no ellipsis1408 ... [0, 1, ..., 9]1409 ... '''1410 >>> test = doctest.DocTestFinder().find(f)[0]1411 >>> doctest.DocTestRunner(verbose=False).run(test)1412 ... # doctest: +ELLIPSIS1413 **********************************************************************1414 File ..., line 2, in f1415 Failed example:1416 print(list(range(10))) # Should fail: no ellipsis1417 Expected:1418 [0, 1, ..., 9]1419 Got:1420 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]1421 **********************************************************************1422 File ..., line 8, in f1423 Failed example:1424 print(list(range(10))) # Should fail: no ellipsis1425 Expected:1426 [0, 1, ..., 9]1427 Got:1428 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]1429 TestResults(failed=2, attempted=3)1430Multiple options may be modified by a single option directive. They1431may be separated by whitespace, commas, or both:1432 >>> def f(x): r'''1433 ... >>> print(list(range(10))) # Should fail1434 ... [0, 1, ..., 9]1435 ... >>> print(list(range(10))) # Should succeed1436 ... ... # doctest: +ELLIPSIS +NORMALIZE_WHITESPACE1437 ... [0, 1, ..., 9]1438 ... '''1439 >>> test = doctest.DocTestFinder().find(f)[0]1440 >>> doctest.DocTestRunner(verbose=False).run(test)1441 ... # doctest: +ELLIPSIS1442 **********************************************************************1443 File ..., line 2, in f1444 Failed example:1445 print(list(range(10))) # Should fail1446 Expected:1447 [0, 1, ..., 9]1448 Got:1449 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]1450 TestResults(failed=1, attempted=2)1451 >>> def f(x): r'''1452 ... >>> print(list(range(10))) # Should fail1453 ... [0, 1, ..., 9]1454 ... >>> print(list(range(10))) # Should succeed1455 ... ... # doctest: +ELLIPSIS,+NORMALIZE_WHITESPACE1456 ... [0, 1, ..., 9]1457 ... '''1458 >>> test = doctest.DocTestFinder().find(f)[0]1459 >>> doctest.DocTestRunner(verbose=False).run(test)1460 ... # doctest: +ELLIPSIS1461 **********************************************************************1462 File ..., line 2, in f1463 Failed example:1464 print(list(range(10))) # Should fail1465 Expected:1466 [0, 1, ..., 9]1467 Got:1468 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]1469 TestResults(failed=1, attempted=2)1470 >>> def f(x): r'''1471 ... >>> print(list(range(10))) # Should fail1472 ... [0, 1, ..., 9]1473 ... >>> print(list(range(10))) # Should succeed1474 ... ... # doctest: +ELLIPSIS, +NORMALIZE_WHITESPACE1475 ... [0, 1, ..., 9]1476 ... '''1477 >>> test = doctest.DocTestFinder().find(f)[0]1478 >>> doctest.DocTestRunner(verbose=False).run(test)1479 ... # doctest: +ELLIPSIS1480 **********************************************************************1481 File ..., line 2, in f1482 Failed example:1483 print(list(range(10))) # Should fail1484 Expected:1485 [0, 1, ..., 9]1486 Got:1487 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]1488 TestResults(failed=1, attempted=2)1489The option directive may be put on the line following the source, as1490long as a continuation prompt is used:1491 >>> def f(x): r'''1492 ... >>> print(list(range(10)))1493 ... ... # doctest: +ELLIPSIS1494 ... [0, 1, ..., 9]1495 ... '''1496 >>> test = doctest.DocTestFinder().find(f)[0]1497 >>> doctest.DocTestRunner(verbose=False).run(test)1498 TestResults(failed=0, attempted=1)1499For examples with multi-line source, the option directive may appear1500at the end of any line:1501 >>> def f(x): r'''1502 ... >>> for x in range(10): # doctest: +ELLIPSIS1503 ... ... print(' ', x, end='', sep='')1504 ... 0 1 2 ... 91505 ...1506 ... >>> for x in range(10):1507 ... ... print(' ', x, end='', sep='') # doctest: +ELLIPSIS1508 ... 0 1 2 ... 91509 ... '''1510 >>> test = doctest.DocTestFinder().find(f)[0]1511 >>> doctest.DocTestRunner(verbose=False).run(test)1512 TestResults(failed=0, attempted=2)1513If more than one line of an example with multi-line source has an1514option directive, then they are combined:1515 >>> def f(x): r'''1516 ... Should fail (option directive not on the last line):1517 ... >>> for x in range(10): # doctest: +ELLIPSIS1518 ... ... print(x, end=' ') # doctest: +NORMALIZE_WHITESPACE1519 ... 0 1 2...91520 ... '''1521 >>> test = doctest.DocTestFinder().find(f)[0]1522 >>> doctest.DocTestRunner(verbose=False).run(test)1523 TestResults(failed=0, attempted=1)1524It is an error to have a comment of the form ``# doctest:`` that is1525*not* followed by words of the form ``+OPTION`` or ``-OPTION``, where1526``OPTION`` is an option that has been registered with1527`register_option`:1528 >>> # Error: Option not registered1529 >>> s = '>>> print(12) #doctest: +BADOPTION'1530 >>> test = doctest.DocTestParser().get_doctest(s, {}, 's', 's.py', 0)1531 Traceback (most recent call last):1532 ValueError: line 1 of the doctest for s has an invalid option: '+BADOPTION'1533 >>> # Error: No + or - prefix1534 >>> s = '>>> print(12) #doctest: ELLIPSIS'1535 >>> test = doctest.DocTestParser().get_doctest(s, {}, 's', 's.py', 0)1536 Traceback (most recent call last):1537 ValueError: line 1 of the doctest for s has an invalid option: 'ELLIPSIS'1538It is an error to use an option directive on a line that contains no1539source:1540 >>> s = '>>> # doctest: +ELLIPSIS'1541 >>> test = doctest.DocTestParser().get_doctest(s, {}, 's', 's.py', 0)1542 Traceback (most recent call last):1543 ValueError: line 0 of the doctest for s has an option directive on a line with no example: '# doctest: +ELLIPSIS'1544"""1545def test_testsource(): r"""1546Unit tests for `testsource()`.1547The testsource() function takes a module and a name, finds the (first)1548test with that name in that module, and converts it to a script. The1549example code is converted to regular Python code. The surrounding1550words and expected output are converted to comments:1551 >>> import test.test_doctest1552 >>> name = 'test.test_doctest.sample_func'1553 >>> print(doctest.testsource(test.test_doctest, name))1554 # Blah blah1555 #1556 print(sample_func(22))1557 # Expected:1558 ## 441559 #1560 # Yee ha!1561 <BLANKLINE>1562 >>> name = 'test.test_doctest.SampleNewStyleClass'1563 >>> print(doctest.testsource(test.test_doctest, name))1564 print('1\n2\n3')1565 # Expected:1566 ## 11567 ## 21568 ## 31569 <BLANKLINE>1570 >>> name = 'test.test_doctest.SampleClass.a_classmethod'1571 >>> print(doctest.testsource(test.test_doctest, name))1572 print(SampleClass.a_classmethod(10))1573 # Expected:1574 ## 121575 print(SampleClass(0).a_classmethod(10))1576 # Expected:1577 ## 121578 <BLANKLINE>1579"""1580def test_debug(): r"""1581Create a docstring that we want to debug:1582 >>> s = '''1583 ... >>> x = 121584 ... >>> print(x)1585 ... 121586 ... '''1587Create some fake stdin input, to feed to the debugger:1588 >>> real_stdin = sys.stdin1589 >>> sys.stdin = _FakeInput(['next', 'print(x)', 'continue'])1590Run the debugger on the docstring, and then restore sys.stdin.1591 >>> try: doctest.debug_src(s)1592 ... finally: sys.stdin = real_stdin1593 > <string>(1)<module>()1594 (Pdb) next1595 121596 --Return--1597 > <string>(1)<module>()->None1598 (Pdb) print(x)1599 121600 (Pdb) continue1601"""1602if not hasattr(sys, 'gettrace') or not sys.gettrace():1603 def test_pdb_set_trace():1604 """Using pdb.set_trace from a doctest.1605 You can use pdb.set_trace from a doctest. To do so, you must1606 retrieve the set_trace function from the pdb module at the time1607 you use it. The doctest module changes sys.stdout so that it can1608 capture program output. It also temporarily replaces pdb.set_trace1609 with a version that restores stdout. This is necessary for you to1610 see debugger output.1611 >>> doc = '''1612 ... >>> x = 421613 ... >>> raise Exception('clé')1614 ... Traceback (most recent call last):1615 ... Exception: clé1616 ... >>> import pdb; pdb.set_trace()1617 ... '''1618 >>> parser = doctest.DocTestParser()1619 >>> test = parser.get_doctest(doc, {}, "foo-bar@baz", "foo-bar@baz.py", 0)1620 >>> runner = doctest.DocTestRunner(verbose=False)1621 To demonstrate this, we'll create a fake standard input that1622 captures our debugger input:1623 >>> import tempfile1624 >>> real_stdin = sys.stdin1625 >>> sys.stdin = _FakeInput([1626 ... 'print(x)', # print data defined by the example1627 ... 'continue', # stop debugging1628 ... ''])1629 >>> try: runner.run(test)1630 ... finally: sys.stdin = real_stdin1631 --Return--1632 > <doctest foo-bar@baz[2]>(1)<module>()->None1633 -> import pdb; pdb.set_trace()1634 (Pdb) print(x)1635 421636 (Pdb) continue1637 TestResults(failed=0, attempted=3)1638 You can also put pdb.set_trace in a function called from a test:1639 >>> def calls_set_trace():1640 ... y=21641 ... import pdb; pdb.set_trace()1642 >>> doc = '''1643 ... >>> x=11644 ... >>> calls_set_trace()1645 ... '''1646 >>> test = parser.get_doctest(doc, globals(), "foo-bar@baz", "foo-bar@baz.py", 0)1647 >>> real_stdin = sys.stdin1648 >>> sys.stdin = _FakeInput([1649 ... 'print(y)', # print data defined in the function1650 ... 'up', # out of function1651 ... 'print(x)', # print data defined by the example1652 ... 'continue', # stop debugging1653 ... ''])1654 >>> try:1655 ... runner.run(test)1656 ... finally:1657 ... sys.stdin = real_stdin1658 --Return--1659 > <doctest test.test_doctest.test_pdb_set_trace[8]>(3)calls_set_trace()->None1660 -> import pdb; pdb.set_trace()1661 (Pdb) print(y)1662 21663 (Pdb) up1664 > <doctest foo-bar@baz[1]>(1)<module>()1665 -> calls_set_trace()1666 (Pdb) print(x)1667 11668 (Pdb) continue1669 TestResults(failed=0, attempted=2)1670 During interactive debugging, source code is shown, even for1671 doctest examples:1672 >>> doc = '''1673 ... >>> def f(x):1674 ... ... g(x*2)1675 ... >>> def g(x):1676 ... ... print(x+3)1677 ... ... import pdb; pdb.set_trace()1678 ... >>> f(3)1679 ... '''1680 >>> test = parser.get_doctest(doc, globals(), "foo-bar@baz", "foo-bar@baz.py", 0)1681 >>> real_stdin = sys.stdin1682 >>> sys.stdin = _FakeInput([1683 ... 'list', # list source from example 21684 ... 'next', # return from g()1685 ... 'list', # list source from example 11686 ... 'next', # return from f()1687 ... 'list', # list source from example 31688 ... 'continue', # stop debugging1689 ... ''])1690 >>> try: runner.run(test)1691 ... finally: sys.stdin = real_stdin1692 ... # doctest: +NORMALIZE_WHITESPACE1693 --Return--1694 > <doctest foo-bar@baz[1]>(3)g()->None1695 -> import pdb; pdb.set_trace()1696 (Pdb) list1697 1 def g(x):1698 2 print(x+3)1699 3 -> import pdb; pdb.set_trace()1700 [EOF]1701 (Pdb) next1702 --Return--1703 > <doctest foo-bar@baz[0]>(2)f()->None1704 -> g(x*2)1705 (Pdb) list1706 1 def f(x):1707 2 -> g(x*2)1708 [EOF]1709 (Pdb) next1710 --Return--1711 > <doctest foo-bar@baz[2]>(1)<module>()->None1712 -> f(3)1713 (Pdb) list1714 1 -> f(3)1715 [EOF]1716 (Pdb) continue1717 **********************************************************************1718 File "foo-bar@baz.py", line 7, in foo-bar@baz1719 Failed example:1720 f(3)1721 Expected nothing1722 Got:1723 91724 TestResults(failed=1, attempted=3)1725 """1726 def test_pdb_set_trace_nested():1727 """This illustrates more-demanding use of set_trace with nested functions.1728 >>> class C(object):1729 ... def calls_set_trace(self):1730 ... y = 11731 ... import pdb; pdb.set_trace()1732 ... self.f1()1733 ... y = 21734 ... def f1(self):1735 ... x = 11736 ... self.f2()1737 ... x = 21738 ... def f2(self):1739 ... z = 11740 ... z = 21741 >>> calls_set_trace = C().calls_set_trace1742 >>> doc = '''1743 ... >>> a = 11744 ... >>> calls_set_trace()1745 ... '''1746 >>> parser = doctest.DocTestParser()1747 >>> runner = doctest.DocTestRunner(verbose=False)1748 >>> test = parser.get_doctest(doc, globals(), "foo-bar@baz", "foo-bar@baz.py", 0)1749 >>> real_stdin = sys.stdin1750 >>> sys.stdin = _FakeInput([1751 ... 'print(y)', # print data defined in the function1752 ... 'step', 'step', 'step', 'step', 'step', 'step', 'print(z)',1753 ... 'up', 'print(x)',1754 ... 'up', 'print(y)',1755 ... 'up', 'print(foo)',1756 ... 'continue', # stop debugging1757 ... ''])1758 >>> try:1759 ... runner.run(test)1760 ... finally:1761 ... sys.stdin = real_stdin1762 ... # doctest: +REPORT_NDIFF1763 > <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(5)calls_set_trace()1764 -> self.f1()1765 (Pdb) print(y)1766 11767 (Pdb) step1768 --Call--1769 > <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(7)f1()1770 -> def f1(self):1771 (Pdb) step1772 > <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(8)f1()1773 -> x = 11774 (Pdb) step1775 > <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(9)f1()1776 -> self.f2()1777 (Pdb) step1778 --Call--1779 > <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(11)f2()1780 -> def f2(self):1781 (Pdb) step1782 > <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(12)f2()1783 -> z = 11784 (Pdb) step1785 > <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(13)f2()1786 -> z = 21787 (Pdb) print(z)1788 11789 (Pdb) up1790 > <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(9)f1()1791 -> self.f2()1792 (Pdb) print(x)1793 11794 (Pdb) up1795 > <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(5)calls_set_trace()1796 -> self.f1()1797 (Pdb) print(y)1798 11799 (Pdb) up1800 > <doctest foo-bar@baz[1]>(1)<module>()1801 -> calls_set_trace()1802 (Pdb) print(foo)1803 *** NameError: name 'foo' is not defined1804 (Pdb) continue1805 TestResults(failed=0, attempted=2)1806 """1807def test_DocTestSuite():1808 """DocTestSuite creates a unittest test suite from a doctest.1809 We create a Suite by providing a module. A module can be provided1810 by passing a module object:1811 >>> import unittest1812 >>> import test.sample_doctest1813 >>> suite = doctest.DocTestSuite(test.sample_doctest)1814 >>> suite.run(unittest.TestResult())1815 <unittest.result.TestResult run=9 errors=0 failures=4>1816 We can also supply the module by name:1817 >>> suite = doctest.DocTestSuite('test.sample_doctest')1818 >>> suite.run(unittest.TestResult())1819 <unittest.result.TestResult run=9 errors=0 failures=4>1820 The module need not contain any doctest examples:1821 >>> suite = doctest.DocTestSuite('test.sample_doctest_no_doctests')1822 >>> suite.run(unittest.TestResult())1823 <unittest.result.TestResult run=0 errors=0 failures=0>1824 However, if DocTestSuite finds no docstrings, it raises an error:1825 >>> try:1826 ... doctest.DocTestSuite('test.sample_doctest_no_docstrings')1827 ... except ValueError as e:1828 ... error = e1829 >>> print(error.args[1])1830 has no docstrings1831 You can prevent this error by passing a DocTestFinder instance with1832 the `exclude_empty` keyword argument set to False:1833 >>> finder = doctest.DocTestFinder(exclude_empty=False)1834 >>> suite = doctest.DocTestSuite('test.sample_doctest_no_docstrings',1835 ... test_finder=finder)1836 >>> suite.run(unittest.TestResult())1837 <unittest.result.TestResult run=0 errors=0 failures=0>1838 We can use the current module:1839 >>> suite = test.sample_doctest.test_suite()1840 >>> suite.run(unittest.TestResult())1841 <unittest.result.TestResult run=9 errors=0 failures=4>1842 We can supply global variables. If we pass globs, they will be1843 used instead of the module globals. Here we'll pass an empty1844 globals, triggering an extra error:1845 >>> suite = doctest.DocTestSuite('test.sample_doctest', globs={})1846 >>> suite.run(unittest.TestResult())1847 <unittest.result.TestResult run=9 errors=0 failures=5>1848 Alternatively, we can provide extra globals. Here we'll make an1849 error go away by providing an extra global variable:1850 >>> suite = doctest.DocTestSuite('test.sample_doctest',1851 ... extraglobs={'y': 1})1852 >>> suite.run(unittest.TestResult())1853 <unittest.result.TestResult run=9 errors=0 failures=3>1854 You can pass option flags. Here we'll cause an extra error1855 by disabling the blank-line feature:1856 >>> suite = doctest.DocTestSuite('test.sample_doctest',1857 ... optionflags=doctest.DONT_ACCEPT_BLANKLINE)1858 >>> suite.run(unittest.TestResult())1859 <unittest.result.TestResult run=9 errors=0 failures=5>1860 You can supply setUp and tearDown functions:1861 >>> def setUp(t):1862 ... import test.test_doctest1863 ... test.test_doctest.sillySetup = True1864 >>> def tearDown(t):1865 ... import test.test_doctest1866 ... del test.test_doctest.sillySetup1867 Here, we installed a silly variable that the test expects:1868 >>> suite = doctest.DocTestSuite('test.sample_doctest',1869 ... setUp=setUp, tearDown=tearDown)1870 >>> suite.run(unittest.TestResult())1871 <unittest.result.TestResult run=9 errors=0 failures=3>1872 But the tearDown restores sanity:1873 >>> import test.test_doctest1874 >>> test.test_doctest.sillySetup1875 Traceback (most recent call last):1876 ...1877 AttributeError: 'module' object has no attribute 'sillySetup'1878 The setUp and tearDown funtions are passed test objects. Here1879 we'll use the setUp function to supply the missing variable y:1880 >>> def setUp(test):1881 ... test.globs['y'] = 11882 >>> suite = doctest.DocTestSuite('test.sample_doctest', setUp=setUp)1883 >>> suite.run(unittest.TestResult())1884 <unittest.result.TestResult run=9 errors=0 failures=3>1885 Here, we didn't need to use a tearDown function because we1886 modified the test globals, which are a copy of the1887 sample_doctest module dictionary. The test globals are1888 automatically cleared for us after a test.1889 """1890def test_DocFileSuite():1891 """We can test tests found in text files using a DocFileSuite.1892 We create a suite by providing the names of one or more text1893 files that include examples:1894 >>> import unittest1895 >>> suite = doctest.DocFileSuite('test_doctest.txt',1896 ... 'test_doctest2.txt',1897 ... 'test_doctest4.txt')1898 >>> suite.run(unittest.TestResult())1899 <unittest.result.TestResult run=3 errors=0 failures=2>1900 The test files are looked for in the directory containing the1901 calling module. A package keyword argument can be provided to1902 specify a different relative location.1903 >>> import unittest1904 >>> suite = doctest.DocFileSuite('test_doctest.txt',1905 ... 'test_doctest2.txt',1906 ... 'test_doctest4.txt',1907 ... package='test')1908 >>> suite.run(unittest.TestResult())1909 <unittest.result.TestResult run=3 errors=0 failures=2>1910 Support for using a package's __loader__.get_data() is also1911 provided.1912 >>> import unittest, pkgutil, test1913 >>> added_loader = False1914 >>> if not hasattr(test, '__loader__'):1915 ... test.__loader__ = pkgutil.get_loader(test)1916 ... added_loader = True1917 >>> try:1918 ... suite = doctest.DocFileSuite('test_doctest.txt',1919 ... 'test_doctest2.txt',1920 ... 'test_doctest4.txt',1921 ... package='test')1922 ... suite.run(unittest.TestResult())1923 ... finally:1924 ... if added_loader:1925 ... del test.__loader__1926 <unittest.result.TestResult run=3 errors=0 failures=2>1927 '/' should be used as a path separator. It will be converted1928 to a native separator at run time:1929 >>> suite = doctest.DocFileSuite('../test/test_doctest.txt')1930 >>> suite.run(unittest.TestResult())1931 <unittest.result.TestResult run=1 errors=0 failures=1>1932 If DocFileSuite is used from an interactive session, then files1933 are resolved relative to the directory of sys.argv[0]:1934 >>> import types, os.path, test.test_doctest1935 >>> save_argv = sys.argv1936 >>> sys.argv = [test.test_doctest.__file__]1937 >>> suite = doctest.DocFileSuite('test_doctest.txt',1938 ... package=types.ModuleType('__main__'))1939 >>> sys.argv = save_argv1940 By setting `module_relative=False`, os-specific paths may be1941 used (including absolute paths and paths relative to the1942 working directory):1943 >>> # Get the absolute path of the test package.1944 >>> test_doctest_path = os.path.abspath(test.test_doctest.__file__)1945 >>> test_pkg_path = os.path.split(test_doctest_path)[0]1946 >>> # Use it to find the absolute path of test_doctest.txt.1947 >>> test_file = os.path.join(test_pkg_path, 'test_doctest.txt')1948 >>> suite = doctest.DocFileSuite(test_file, module_relative=False)1949 >>> suite.run(unittest.TestResult())1950 <unittest.result.TestResult run=1 errors=0 failures=1>1951 It is an error to specify `package` when `module_relative=False`:1952 >>> suite = doctest.DocFileSuite(test_file, module_relative=False,1953 ... package='test')1954 Traceback (most recent call last):1955 ValueError: Package may only be specified for module-relative paths.1956 You can specify initial global variables:1957 >>> suite = doctest.DocFileSuite('test_doctest.txt',1958 ... 'test_doctest2.txt',1959 ... 'test_doctest4.txt',1960 ... globs={'favorite_color': 'blue'})1961 >>> suite.run(unittest.TestResult())1962 <unittest.result.TestResult run=3 errors=0 failures=1>1963 In this case, we supplied a missing favorite color. You can1964 provide doctest options:1965 >>> suite = doctest.DocFileSuite('test_doctest.txt',1966 ... 'test_doctest2.txt',1967 ... 'test_doctest4.txt',1968 ... optionflags=doctest.DONT_ACCEPT_BLANKLINE,1969 ... globs={'favorite_color': 'blue'})1970 >>> suite.run(unittest.TestResult())1971 <unittest.result.TestResult run=3 errors=0 failures=2>1972 And, you can provide setUp and tearDown functions:1973 >>> def setUp(t):1974 ... import test.test_doctest1975 ... test.test_doctest.sillySetup = True1976 >>> def tearDown(t):1977 ... import test.test_doctest1978 ... del test.test_doctest.sillySetup1979 Here, we installed a silly variable that the test expects:1980 >>> suite = doctest.DocFileSuite('test_doctest.txt',1981 ... 'test_doctest2.txt',1982 ... 'test_doctest4.txt',1983 ... setUp=setUp, tearDown=tearDown)1984 >>> suite.run(unittest.TestResult())1985 <unittest.result.TestResult run=3 errors=0 failures=1>1986 But the tearDown restores sanity:1987 >>> import test.test_doctest1988 >>> test.test_doctest.sillySetup1989 Traceback (most recent call last):1990 ...1991 AttributeError: 'module' object has no attribute 'sillySetup'1992 The setUp and tearDown funtions are passed test objects.1993 Here, we'll use a setUp function to set the favorite color in1994 test_doctest.txt:1995 >>> def setUp(test):1996 ... test.globs['favorite_color'] = 'blue'1997 >>> suite = doctest.DocFileSuite('test_doctest.txt', setUp=setUp)1998 >>> suite.run(unittest.TestResult())1999 <unittest.result.TestResult run=1 errors=0 failures=0>2000 Here, we didn't need to use a tearDown function because we2001 modified the test globals. The test globals are2002 automatically cleared for us after a test.2003 Tests in a file run using `DocFileSuite` can also access the2004 `__file__` global, which is set to the name of the file2005 containing the tests:2006 >>> suite = doctest.DocFileSuite('test_doctest3.txt')2007 >>> suite.run(unittest.TestResult())2008 <unittest.result.TestResult run=1 errors=0 failures=0>2009 If the tests contain non-ASCII characters, we have to specify which2010 encoding the file is encoded with. We do so by using the `encoding`2011 parameter:2012 >>> suite = doctest.DocFileSuite('test_doctest.txt',2013 ... 'test_doctest2.txt',2014 ... 'test_doctest4.txt',2015 ... encoding='utf-8')2016 >>> suite.run(unittest.TestResult())2017 <unittest.result.TestResult run=3 errors=0 failures=2>2018 """2019def test_trailing_space_in_test():2020 """2021 Trailing spaces in expected output are significant:2022 >>> x, y = 'foo', ''2023 >>> print(x, y)2024 foo \n2025 """2026def test_unittest_reportflags():2027 """Default unittest reporting flags can be set to control reporting2028 Here, we'll set the REPORT_ONLY_FIRST_FAILURE option so we see2029 only the first failure of each test. First, we'll look at the2030 output without the flag. The file test_doctest.txt file has two2031 tests. They both fail if blank lines are disabled:2032 >>> suite = doctest.DocFileSuite('test_doctest.txt',2033 ... optionflags=doctest.DONT_ACCEPT_BLANKLINE)2034 >>> import unittest2035 >>> result = suite.run(unittest.TestResult())2036 >>> print(result.failures[0][1]) # doctest: +ELLIPSIS2037 Traceback ...2038 Failed example:2039 favorite_color2040 ...2041 Failed example:2042 if 1:2043 ...2044 Note that we see both failures displayed.2045 >>> old = doctest.set_unittest_reportflags(2046 ... doctest.REPORT_ONLY_FIRST_FAILURE)2047 Now, when we run the test:2048 >>> result = suite.run(unittest.TestResult())2049 >>> print(result.failures[0][1]) # doctest: +ELLIPSIS2050 Traceback ...2051 Failed example:2052 favorite_color2053 Exception raised:2054 ...2055 NameError: name 'favorite_color' is not defined2056 <BLANKLINE>2057 <BLANKLINE>2058 We get only the first failure.2059 If we give any reporting options when we set up the tests,2060 however:2061 >>> suite = doctest.DocFileSuite('test_doctest.txt',2062 ... optionflags=doctest.DONT_ACCEPT_BLANKLINE | doctest.REPORT_NDIFF)2063 Then the default eporting options are ignored:2064 >>> result = suite.run(unittest.TestResult())2065 >>> print(result.failures[0][1]) # doctest: +ELLIPSIS2066 Traceback ...2067 Failed example:2068 favorite_color2069 ...2070 Failed example:2071 if 1:2072 print('a')2073 print()2074 print('b')2075 Differences (ndiff with -expected +actual):2076 a2077 - <BLANKLINE>2078 +2079 b2080 <BLANKLINE>2081 <BLANKLINE>2082 Test runners can restore the formatting flags after they run:2083 >>> ignored = doctest.set_unittest_reportflags(old)2084 """2085def test_testfile(): r"""2086Tests for the `testfile()` function. This function runs all the2087doctest examples in a given file. In its simple invokation, it is2088called with the name of a file, which is taken to be relative to the2089calling module. The return value is (#failures, #tests).2090We don't want `-v` in sys.argv for these tests.2091 >>> save_argv = sys.argv2092 >>> if '-v' in sys.argv:2093 ... sys.argv = [arg for arg in save_argv if arg != '-v']2094 >>> doctest.testfile('test_doctest.txt') # doctest: +ELLIPSIS2095 **********************************************************************2096 File "...", line 6, in test_doctest.txt2097 Failed example:2098 favorite_color2099 Exception raised:2100 ...2101 NameError: name 'favorite_color' is not defined2102 **********************************************************************2103 1 items had failures:2104 1 of 2 in test_doctest.txt2105 ***Test Failed*** 1 failures.2106 TestResults(failed=1, attempted=2)2107 >>> doctest.master = None # Reset master.2108(Note: we'll be clearing doctest.master after each call to2109`doctest.testfile`, to suppress warnings about multiple tests with the2110same name.)2111Globals may be specified with the `globs` and `extraglobs` parameters:2112 >>> globs = {'favorite_color': 'blue'}2113 >>> doctest.testfile('test_doctest.txt', globs=globs)2114 TestResults(failed=0, attempted=2)2115 >>> doctest.master = None # Reset master.2116 >>> extraglobs = {'favorite_color': 'red'}2117 >>> doctest.testfile('test_doctest.txt', globs=globs,2118 ... extraglobs=extraglobs) # doctest: +ELLIPSIS2119 **********************************************************************2120 File "...", line 6, in test_doctest.txt2121 Failed example:2122 favorite_color2123 Expected:2124 'blue'2125 Got:2126 'red'2127 **********************************************************************2128 1 items had failures:2129 1 of 2 in test_doctest.txt2130 ***Test Failed*** 1 failures.2131 TestResults(failed=1, attempted=2)2132 >>> doctest.master = None # Reset master.2133The file may be made relative to a given module or package, using the2134optional `module_relative` parameter:2135 >>> doctest.testfile('test_doctest.txt', globs=globs,2136 ... module_relative='test')2137 TestResults(failed=0, attempted=2)2138 >>> doctest.master = None # Reset master.2139Verbosity can be increased with the optional `verbose` parameter:2140 >>> doctest.testfile('test_doctest.txt', globs=globs, verbose=True)2141 Trying:2142 favorite_color2143 Expecting:2144 'blue'2145 ok2146 Trying:2147 if 1:2148 print('a')2149 print()2150 print('b')2151 Expecting:2152 a2153 <BLANKLINE>2154 b2155 ok2156 1 items passed all tests:2157 2 tests in test_doctest.txt2158 2 tests in 1 items.2159 2 passed and 0 failed.2160 Test passed.2161 TestResults(failed=0, attempted=2)2162 >>> doctest.master = None # Reset master.2163The name of the test may be specified with the optional `name`2164parameter:2165 >>> doctest.testfile('test_doctest.txt', name='newname')2166 ... # doctest: +ELLIPSIS2167 **********************************************************************2168 File "...", line 6, in newname2169 ...2170 TestResults(failed=1, attempted=2)2171 >>> doctest.master = None # Reset master.2172The summary report may be suppressed with the optional `report`2173parameter:2174 >>> doctest.testfile('test_doctest.txt', report=False)2175 ... # doctest: +ELLIPSIS2176 **********************************************************************2177 File "...", line 6, in test_doctest.txt2178 Failed example:2179 favorite_color2180 Exception raised:2181 ...2182 NameError: name 'favorite_color' is not defined2183 TestResults(failed=1, attempted=2)2184 >>> doctest.master = None # Reset master.2185The optional keyword argument `raise_on_error` can be used to raise an2186exception on the first error (which may be useful for postmortem2187debugging):2188 >>> doctest.testfile('test_doctest.txt', raise_on_error=True)2189 ... # doctest: +ELLIPSIS2190 Traceback (most recent call last):2191 doctest.UnexpectedException: ...2192 >>> doctest.master = None # Reset master.2193If the tests contain non-ASCII characters, the tests might fail, since2194it's unknown which encoding is used. The encoding can be specified2195using the optional keyword argument `encoding`:2196 >>> doctest.testfile('test_doctest4.txt', encoding='latin-1') # doctest: +ELLIPSIS2197 **********************************************************************2198 File "...", line 7, in test_doctest4.txt2199 Failed example:2200 '...'2201 Expected:2202 'f\xf6\xf6'2203 Got:2204 'f\xc3\xb6\xc3\xb6'2205 **********************************************************************2206 ...2207 **********************************************************************2208 1 items had failures:2209 2 of 2 in test_doctest4.txt2210 ***Test Failed*** 2 failures.2211 TestResults(failed=2, attempted=2)2212 >>> doctest.master = None # Reset master.2213 >>> doctest.testfile('test_doctest4.txt', encoding='utf-8')2214 TestResults(failed=0, attempted=2)2215 >>> doctest.master = None # Reset master.2216Test the verbose output:2217 >>> doctest.testfile('test_doctest4.txt', encoding='utf-8', verbose=True)2218 Trying:2219 'föö'2220 Expecting:2221 'f\xf6\xf6'2222 ok2223 Trying:2224 'bąr'2225 Expecting:2226 'b\u0105r'2227 ok2228 1 items passed all tests:2229 2 tests in test_doctest4.txt2230 2 tests in 1 items.2231 2 passed and 0 failed.2232 Test passed.2233 TestResults(failed=0, attempted=2)2234 >>> doctest.master = None # Reset master.2235 >>> sys.argv = save_argv2236"""2237def test_testmod(): r"""2238Tests for the testmod function. More might be useful, but for now we're just2239testing the case raised by Issue 6195, where trying to doctest a C module would2240fail with a UnicodeDecodeError because doctest tried to read the "source" lines2241out of the binary module.2242 >>> import unicodedata2243 >>> doctest.testmod(unicodedata, verbose=False)2244 TestResults(failed=0, attempted=0)2245"""2246try:2247 os.fsencode("foo-bär@baz.py")2248except UnicodeEncodeError:2249 # Skip the test: the filesystem encoding is unable to encode the filename2250 pass2251else:2252 def test_unicode(): """2253Check doctest with a non-ascii filename:2254 >>> doc = '''2255 ... >>> raise Exception('clé')2256 ... '''2257 ...2258 >>> parser = doctest.DocTestParser()2259 >>> test = parser.get_doctest(doc, {}, "foo-bär@baz", "foo-bär@baz.py", 0)2260 >>> test2261 <DocTest foo-bär@baz from foo-bär@baz.py:0 (1 example)>2262 >>> runner = doctest.DocTestRunner(verbose=False)2263 >>> runner.run(test) # doctest: +ELLIPSIS2264 **********************************************************************2265 File "foo-bär@baz.py", line 2, in foo-bär@baz2266 Failed example:2267 raise Exception('clé')2268 Exception raised:2269 Traceback (most recent call last):2270 File ...2271 compileflags, 1), test.globs)2272 File "<doctest foo-bär@baz[0]>", line 1, in <module>2273 raise Exception('clé')2274 Exception: clé2275 TestResults(failed=1, attempted=1)2276 """2277def test_CLI(): r"""2278The doctest module can be used to run doctests against an arbitrary file.2279These tests test this CLI functionality.2280We'll use the support module's script_helpers for this, and write a test files2281to a temp dir to run the command against. Due to a current limitation in2282script_helpers, though, we need a little utility function to turn the returned2283output into something we can doctest against:2284 >>> def normalize(s):2285 ... return '\n'.join(s.decode().splitlines())2286Note: we also pass TERM='' to all the assert_python calls to avoid a bug2287in the readline library that is triggered in these tests because we are2288running them in a new python process. See:2289 http://lists.gnu.org/archive/html/bug-readline/2013-06/msg00000.html2290With those preliminaries out of the way, we'll start with a file with two2291simple tests and no errors. We'll run both the unadorned doctest command, and2292the verbose version, and then check the output:2293 >>> from test import script_helper2294 >>> with script_helper.temp_dir() as tmpdir:2295 ... fn = os.path.join(tmpdir, 'myfile.doc')2296 ... with open(fn, 'w') as f:2297 ... _ = f.write('This is a very simple test file.\n')2298 ... _ = f.write(' >>> 1 + 1\n')2299 ... _ = f.write(' 2\n')2300 ... _ = f.write(' >>> "a"\n')2301 ... _ = f.write(" 'a'\n")2302 ... _ = f.write('\n')2303 ... _ = f.write('And that is it.\n')2304 ... rc1, out1, err1 = script_helper.assert_python_ok(2305 ... '-m', 'doctest', fn, TERM='')2306 ... rc2, out2, err2 = script_helper.assert_python_ok(2307 ... '-m', 'doctest', '-v', fn, TERM='')2308With no arguments and passing tests, we should get no output:2309 >>> rc1, out1, err12310 (0, b'', b'')2311With the verbose flag, we should see the test output, but no error output:2312 >>> rc2, err22313 (0, b'')2314 >>> print(normalize(out2))2315 Trying:2316 1 + 12317 Expecting:2318 22319 ok2320 Trying:2321 "a"2322 Expecting:2323 'a'2324 ok2325 1 items passed all tests:2326 2 tests in myfile.doc2327 2 tests in 1 items.2328 2 passed and 0 failed.2329 Test passed.2330Now we'll write a couple files, one with three tests, the other a python module2331with two tests, both of the files having "errors" in the tests that can be made2332non-errors by applying the appropriate doctest options to the run (ELLIPSIS in2333the first file, NORMALIZE_WHITESPACE in the second). This combination will2334allow to thoroughly test the -f and -o flags, as well as the doctest command's2335ability to process more than one file on the command line and, since the second2336file ends in '.py', its handling of python module files (as opposed to straight2337text files).2338 >>> from test import script_helper2339 >>> with script_helper.temp_dir() as tmpdir:2340 ... fn = os.path.join(tmpdir, 'myfile.doc')2341 ... with open(fn, 'w') as f:2342 ... _ = f.write('This is another simple test file.\n')2343 ... _ = f.write(' >>> 1 + 1\n')2344 ... _ = f.write(' 2\n')2345 ... _ = f.write(' >>> "abcdef"\n')2346 ... _ = f.write(" 'a...f'\n")2347 ... _ = f.write(' >>> "ajkml"\n')2348 ... _ = f.write(" 'a...l'\n")2349 ... _ = f.write('\n')2350 ... _ = f.write('And that is it.\n')2351 ... fn2 = os.path.join(tmpdir, 'myfile2.py')2352 ... with open(fn2, 'w') as f:2353 ... _ = f.write('def test_func():\n')2354 ... _ = f.write(' \"\"\"\n')2355 ... _ = f.write(' This is simple python test function.\n')2356 ... _ = f.write(' >>> 1 + 1\n')2357 ... _ = f.write(' 2\n')2358 ... _ = f.write(' >>> "abc def"\n')2359 ... _ = f.write(" 'abc def'\n")2360 ... _ = f.write("\n")2361 ... _ = f.write(' \"\"\"\n')2362 ... import shutil2363 ... rc1, out1, err1 = script_helper.assert_python_failure(2364 ... '-m', 'doctest', fn, fn2, TERM='')2365 ... rc2, out2, err2 = script_helper.assert_python_ok(2366 ... '-m', 'doctest', '-o', 'ELLIPSIS', fn, TERM='')2367 ... rc3, out3, err3 = script_helper.assert_python_ok(2368 ... '-m', 'doctest', '-o', 'ELLIPSIS',2369 ... '-o', 'NORMALIZE_WHITESPACE', fn, fn2, TERM='')2370 ... rc4, out4, err4 = script_helper.assert_python_failure(2371 ... '-m', 'doctest', '-f', fn, fn2, TERM='')2372 ... rc5, out5, err5 = script_helper.assert_python_ok(2373 ... '-m', 'doctest', '-v', '-o', 'ELLIPSIS',2374 ... '-o', 'NORMALIZE_WHITESPACE', fn, fn2, TERM='')2375Our first test run will show the errors from the first file (doctest stops if a2376file has errors). Note that doctest test-run error output appears on stdout,2377not stderr:2378 >>> rc1, err12379 (1, b'')2380 >>> print(normalize(out1)) # doctest: +ELLIPSIS2381 **********************************************************************2382 File "...myfile.doc", line 4, in myfile.doc2383 Failed example:2384 "abcdef"2385 Expected:2386 'a...f'2387 Got:2388 'abcdef'2389 **********************************************************************2390 File "...myfile.doc", line 6, in myfile.doc2391 Failed example:2392 "ajkml"2393 Expected:2394 'a...l'2395 Got:2396 'ajkml'2397 **********************************************************************2398 1 items had failures:2399 2 of 3 in myfile.doc2400 ***Test Failed*** 2 failures.2401With -o ELLIPSIS specified, the second run, against just the first file, should2402produce no errors, and with -o NORMALIZE_WHITESPACE also specified, neither2403should the third, which ran against both files:2404 >>> rc2, out2, err22405 (0, b'', b'')2406 >>> rc3, out3, err32407 (0, b'', b'')2408The fourth run uses FAIL_FAST, so we should see only one error:2409 >>> rc4, err42410 (1, b'')2411 >>> print(normalize(out4)) # doctest: +ELLIPSIS2412 **********************************************************************2413 File "...myfile.doc", line 4, in myfile.doc2414 Failed example:2415 "abcdef"2416 Expected:2417 'a...f'2418 Got:2419 'abcdef'2420 **********************************************************************2421 1 items had failures:2422 1 of 2 in myfile.doc2423 ***Test Failed*** 1 failures.2424The fifth test uses verbose with the two options, so we should get verbose2425success output for the tests in both files:2426 >>> rc5, err52427 (0, b'')2428 >>> print(normalize(out5))2429 Trying:2430 1 + 12431 Expecting:2432 22433 ok2434 Trying:2435 "abcdef"2436 Expecting:2437 'a...f'2438 ok2439 Trying:2440 "ajkml"2441 Expecting:2442 'a...l'2443 ok2444 1 items passed all tests:2445 3 tests in myfile.doc2446 3 tests in 1 items.2447 3 passed and 0 failed.2448 Test passed.2449 Trying:2450 1 + 12451 Expecting:2452 22453 ok2454 Trying:2455 "abc def"2456 Expecting:2457 'abc def'2458 ok2459 1 items had no tests:2460 myfile22461 1 items passed all tests:2462 2 tests in myfile2.test_func2463 2 tests in 2 items.2464 2 passed and 0 failed.2465 Test passed.2466We should also check some typical error cases.2467Invalid file name:2468 >>> rc, out, err = script_helper.assert_python_failure(2469 ... '-m', 'doctest', 'nosuchfile', TERM='')2470 >>> rc, out2471 (1, b'')2472 >>> print(normalize(err)) # doctest: +ELLIPSIS2473 Traceback (most recent call last):2474 ...2475 FileNotFoundError: [Errno ...] No such file or directory: 'nosuchfile'2476Invalid doctest option:2477 >>> rc, out, err = script_helper.assert_python_failure(2478 ... '-m', 'doctest', '-o', 'nosuchoption', TERM='')2479 >>> rc, out2480 (2, b'')2481 >>> print(normalize(err)) # doctest: +ELLIPSIS2482 usage...invalid...nosuchoption...2483"""2484######################################################################2485## Main2486######################################################################2487def test_main():2488 # Check the doctest cases in doctest itself:2489 support.run_doctest(doctest, verbosity=True)2490 # Check the doctest cases defined here:2491 from test import test_doctest2492 support.run_doctest(test_doctest, verbosity=True)2493import sys, re, io2494def test_coverage(coverdir):2495 trace = support.import_module('trace')2496 tracer = trace.Trace(ignoredirs=[sys.base_prefix, sys.base_exec_prefix,],2497 trace=0, count=1)2498 tracer.run('test_main()')2499 r = tracer.results()2500 print('Writing coverage results...')2501 r.write_results(show_missing=True, summary=True,2502 coverdir=coverdir)2503if __name__ == '__main__':2504 if '-c' in sys.argv:2505 test_coverage('/tmp/doctest.cover')2506 else:...

Automation Testing Tutorials

Learn to execute automation testing from scratch with LambdaTest Learning Hub. Right from setting up the prerequisites to run your first automation test, to following best practices and diving deeper into advanced test scenarios. LambdaTest Learning Hubs compile a list of step-by-step guides to help you be proficient with different test automation frameworks i.e. Selenium, Cypress, TestNG etc.

LambdaTest Learning Hubs:

• JUnit Tutorial
• TestNG Tutorial
• Webdriver Tutorial
• WebDriverIO Tutorial
• Protractor Tutorial
• Selenium 4 Tutorial
• Jenkins Tutorial
• NUnit Tutorial
• Jest Tutorial
• Playwright Tutorial
• Cypress Tutorial
• PyTest Tutorial

YouTube

You could also refer to video tutorials over LambdaTest YouTube channel to get step by step demonstration from industry experts.

Run green automation tests on LambdaTest cloud grid

Perform automation testing on 3000+ real desktop and mobile devices online.

View sample repo View DocumentationSign up Free

›

_