Back to index

python3.2  3.2.2
Public Member Functions
test.test_doctest.test_DocTestRunner Class Reference

List of all members.

Public Member Functions

def basics
def verbose_flag
def exceptions
def displayhook
def optionflags
def option_directives

Detailed Description

Definition at line 644 of file test_doctest.py.


Member Function Documentation

Definition at line 645 of file test_doctest.py.

00645 
00646     def basics(): r"""
00647 Unit tests for the `DocTestRunner` class.
00648 
00649 DocTestRunner is used to run DocTest test cases, and to accumulate
00650 statistics.  Here's a simple DocTest case we can use:
00651 
00652     >>> def f(x):
00653     ...     '''
00654     ...     >>> x = 12
00655     ...     >>> print(x)
00656     ...     12
00657     ...     >>> x//2
00658     ...     6
00659     ...     '''
00660     >>> test = doctest.DocTestFinder().find(f)[0]
00661 
00662 The main DocTestRunner interface is the `run` method, which runs a
00663 given DocTest case in a given namespace (globs).  It returns a tuple
00664 `(f,t)`, where `f` is the number of failed tests and `t` is the number
00665 of tried tests.
00666 
00667     >>> doctest.DocTestRunner(verbose=False).run(test)
00668     TestResults(failed=0, attempted=3)
00669 
00670 If any example produces incorrect output, then the test runner reports
00671 the failure and proceeds to the next example:
00672 
00673     >>> def f(x):
00674     ...     '''
00675     ...     >>> x = 12
00676     ...     >>> print(x)
00677     ...     14
00678     ...     >>> x//2
00679     ...     6
00680     ...     '''
00681     >>> test = doctest.DocTestFinder().find(f)[0]
00682     >>> doctest.DocTestRunner(verbose=True).run(test)
00683     ... # doctest: +ELLIPSIS
00684     Trying:
00685         x = 12
00686     Expecting nothing
00687     ok
00688     Trying:
00689         print(x)
00690     Expecting:
00691         14
00692     **********************************************************************
00693     File ..., line 4, in f
00694     Failed example:
00695         print(x)
00696     Expected:
00697         14
00698     Got:
00699         12
00700     Trying:
00701         x//2
00702     Expecting:
00703         6
00704     ok
00705     TestResults(failed=1, attempted=3)
"""

Definition at line 984 of file test_doctest.py.

00984 
00985     def displayhook(): r"""
00986 Test that changing sys.displayhook doesn't matter for doctest.
00987 
00988     >>> import sys
00989     >>> orig_displayhook = sys.displayhook
00990     >>> def my_displayhook(x):
00991     ...     print('hi!')
00992     >>> sys.displayhook = my_displayhook
00993     >>> def f():
00994     ...     '''
00995     ...     >>> 3
00996     ...     3
00997     ...     '''
00998     >>> test = doctest.DocTestFinder().find(f)[0]
00999     >>> r = doctest.DocTestRunner(verbose=False).run(test)
01000     >>> post_displayhook = sys.displayhook
01001 
01002     We need to restore sys.displayhook now, so that we'll be able to test
01003     results.
01004 
01005     >>> sys.displayhook = orig_displayhook
01006 
01007     Ok, now we can check that everything is ok.
01008 
01009     >>> r
01010     TestResults(failed=0, attempted=1)
01011     >>> post_displayhook is my_displayhook
01012     True
"""

Definition at line 773 of file test_doctest.py.

00773 
00774     def exceptions(): r"""
00775 Tests of `DocTestRunner`'s exception handling.
00776 
00777 An expected exception is specified with a traceback message.  The
00778 lines between the first line and the type/value may be omitted or
00779 replaced with any other string:
00780 
00781     >>> def f(x):
00782     ...     '''
00783     ...     >>> x = 12
00784     ...     >>> print(x//0)
00785     ...     Traceback (most recent call last):
00786     ...     ZeroDivisionError: integer division or modulo by zero
00787     ...     '''
00788     >>> test = doctest.DocTestFinder().find(f)[0]
00789     >>> doctest.DocTestRunner(verbose=False).run(test)
00790     TestResults(failed=0, attempted=2)
00791 
00792 An example may not generate output before it raises an exception; if
00793 it does, then the traceback message will not be recognized as
00794 signaling an expected exception, so the example will be reported as an
00795 unexpected exception:
00796 
00797     >>> def f(x):
00798     ...     '''
00799     ...     >>> x = 12
00800     ...     >>> print('pre-exception output', x//0)
00801     ...     pre-exception output
00802     ...     Traceback (most recent call last):
00803     ...     ZeroDivisionError: integer division or modulo by zero
00804     ...     '''
00805     >>> test = doctest.DocTestFinder().find(f)[0]
00806     >>> doctest.DocTestRunner(verbose=False).run(test)
00807     ... # doctest: +ELLIPSIS
00808     **********************************************************************
00809     File ..., line 4, in f
00810     Failed example:
00811         print('pre-exception output', x//0)
00812     Exception raised:
00813         ...
00814         ZeroDivisionError: integer division or modulo by zero
00815     TestResults(failed=1, attempted=2)
00816 
00817 Exception messages may contain newlines:
00818 
00819     >>> def f(x):
00820     ...     r'''
00821     ...     >>> raise ValueError('multi\nline\nmessage')
00822     ...     Traceback (most recent call last):
00823     ...     ValueError: multi
00824     ...     line
00825     ...     message
00826     ...     '''
00827     >>> test = doctest.DocTestFinder().find(f)[0]
00828     >>> doctest.DocTestRunner(verbose=False).run(test)
00829     TestResults(failed=0, attempted=1)
00830 
00831 If an exception is expected, but an exception with the wrong type or
00832 message is raised, then it is reported as a failure:
00833 
00834     >>> def f(x):
00835     ...     r'''
00836     ...     >>> raise ValueError('message')
00837     ...     Traceback (most recent call last):
00838     ...     ValueError: wrong message
00839     ...     '''
00840     >>> test = doctest.DocTestFinder().find(f)[0]
00841     >>> doctest.DocTestRunner(verbose=False).run(test)
00842     ... # doctest: +ELLIPSIS
00843     **********************************************************************
00844     File ..., line 3, in f
00845     Failed example:
00846         raise ValueError('message')
00847     Expected:
00848         Traceback (most recent call last):
00849         ValueError: wrong message
00850     Got:
00851         Traceback (most recent call last):
00852         ...
00853         ValueError: message
00854     TestResults(failed=1, attempted=1)
00855 
00856 However, IGNORE_EXCEPTION_DETAIL can be used to allow a mismatch in the
00857 detail:
00858 
00859     >>> def f(x):
00860     ...     r'''
00861     ...     >>> raise ValueError('message') #doctest: +IGNORE_EXCEPTION_DETAIL
00862     ...     Traceback (most recent call last):
00863     ...     ValueError: wrong message
00864     ...     '''
00865     >>> test = doctest.DocTestFinder().find(f)[0]
00866     >>> doctest.DocTestRunner(verbose=False).run(test)
00867     TestResults(failed=0, attempted=1)
00868 
00869 IGNORE_EXCEPTION_DETAIL also ignores difference in exception formatting
00870 between Python versions. For example, in Python 2.x, the module path of
00871 the exception is not in the output, but this will fail under Python 3:
00872 
00873     >>> def f(x):
00874     ...     r'''
00875     ...     >>> from http.client import HTTPException
00876     ...     >>> raise HTTPException('message')
00877     ...     Traceback (most recent call last):
00878     ...     HTTPException: message
00879     ...     '''
00880     >>> test = doctest.DocTestFinder().find(f)[0]
00881     >>> doctest.DocTestRunner(verbose=False).run(test)
00882     ... # doctest: +ELLIPSIS
00883     **********************************************************************
00884     File ..., line 4, in f
00885     Failed example:
00886         raise HTTPException('message')
00887     Expected:
00888         Traceback (most recent call last):
00889         HTTPException: message
00890     Got:
00891         Traceback (most recent call last):
00892         ...
00893         http.client.HTTPException: message
00894     TestResults(failed=1, attempted=2)
00895 
00896 But in Python 3 the module path is included, and therefore a test must look
00897 like the following test to succeed in Python 3. But that test will fail under
00898 Python 2.
00899 
00900     >>> def f(x):
00901     ...     r'''
00902     ...     >>> from http.client import HTTPException
00903     ...     >>> raise HTTPException('message')
00904     ...     Traceback (most recent call last):
00905     ...     http.client.HTTPException: message
00906     ...     '''
00907     >>> test = doctest.DocTestFinder().find(f)[0]
00908     >>> doctest.DocTestRunner(verbose=False).run(test)
00909     TestResults(failed=0, attempted=2)
00910 
00911 However, with IGNORE_EXCEPTION_DETAIL, the module name of the exception
00912 (or its unexpected absence) will be ignored:
00913 
00914     >>> def f(x):
00915     ...     r'''
00916     ...     >>> from http.client import HTTPException
00917     ...     >>> raise HTTPException('message') #doctest: +IGNORE_EXCEPTION_DETAIL
00918     ...     Traceback (most recent call last):
00919     ...     HTTPException: message
00920     ...     '''
00921     >>> test = doctest.DocTestFinder().find(f)[0]
00922     >>> doctest.DocTestRunner(verbose=False).run(test)
00923     TestResults(failed=0, attempted=2)
00924 
00925 The module path will be completely ignored, so two different module paths will
00926 still pass if IGNORE_EXCEPTION_DETAIL is given. This is intentional, so it can
00927 be used when exceptions have changed module.
00928 
00929     >>> def f(x):
00930     ...     r'''
00931     ...     >>> from http.client import HTTPException
00932     ...     >>> raise HTTPException('message') #doctest: +IGNORE_EXCEPTION_DETAIL
00933     ...     Traceback (most recent call last):
00934     ...     foo.bar.HTTPException: message
00935     ...     '''
00936     >>> test = doctest.DocTestFinder().find(f)[0]
00937     >>> doctest.DocTestRunner(verbose=False).run(test)
00938     TestResults(failed=0, attempted=2)
00939 
00940 But IGNORE_EXCEPTION_DETAIL does not allow a mismatch in the exception type:
00941 
00942     >>> def f(x):
00943     ...     r'''
00944     ...     >>> raise ValueError('message') #doctest: +IGNORE_EXCEPTION_DETAIL
00945     ...     Traceback (most recent call last):
00946     ...     TypeError: wrong type
00947     ...     '''
00948     >>> test = doctest.DocTestFinder().find(f)[0]
00949     >>> doctest.DocTestRunner(verbose=False).run(test)
00950     ... # doctest: +ELLIPSIS
00951     **********************************************************************
00952     File ..., line 3, in f
00953     Failed example:
00954         raise ValueError('message') #doctest: +IGNORE_EXCEPTION_DETAIL
00955     Expected:
00956         Traceback (most recent call last):
00957         TypeError: wrong type
00958     Got:
00959         Traceback (most recent call last):
00960         ...
00961         ValueError: message
00962     TestResults(failed=1, attempted=1)
00963 
00964 If an exception is raised but not expected, then it is reported as an
00965 unexpected exception:
00966 
00967     >>> def f(x):
00968     ...     r'''
00969     ...     >>> 1//0
00970     ...     0
00971     ...     '''
00972     >>> test = doctest.DocTestFinder().find(f)[0]
00973     >>> doctest.DocTestRunner(verbose=False).run(test)
00974     ... # doctest: +ELLIPSIS
00975     **********************************************************************
00976     File ..., line 3, in f
00977     Failed example:
00978         1//0
00979     Exception raised:
00980         Traceback (most recent call last):
00981         ...
00982         ZeroDivisionError: integer division or modulo by zero
00983     TestResults(failed=1, attempted=1)
"""

Definition at line 1403 of file test_doctest.py.

01403 
01404     def option_directives(): r"""
01405 Tests of `DocTestRunner`'s option directive mechanism.
01406 
01407 Option directives can be used to turn option flags on or off for a
01408 single example.  To turn an option on for an example, follow that
01409 example with a comment of the form ``# doctest: +OPTION``:
01410 
01411     >>> def f(x): r'''
01412     ...     >>> print(list(range(10)))      # should fail: no ellipsis
01413     ...     [0, 1, ..., 9]
01414     ...
01415     ...     >>> print(list(range(10)))      # doctest: +ELLIPSIS
01416     ...     [0, 1, ..., 9]
01417     ...     '''
01418     >>> test = doctest.DocTestFinder().find(f)[0]
01419     >>> doctest.DocTestRunner(verbose=False).run(test)
01420     ... # doctest: +ELLIPSIS
01421     **********************************************************************
01422     File ..., line 2, in f
01423     Failed example:
01424         print(list(range(10)))      # should fail: no ellipsis
01425     Expected:
01426         [0, 1, ..., 9]
01427     Got:
01428         [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
01429     TestResults(failed=1, attempted=2)
01430 
01431 To turn an option off for an example, follow that example with a
01432 comment of the form ``# doctest: -OPTION``:
01433 
01434     >>> def f(x): r'''
01435     ...     >>> print(list(range(10)))
01436     ...     [0, 1, ..., 9]
01437     ...
01438     ...     >>> # should fail: no ellipsis
01439     ...     >>> print(list(range(10)))      # doctest: -ELLIPSIS
01440     ...     [0, 1, ..., 9]
01441     ...     '''
01442     >>> test = doctest.DocTestFinder().find(f)[0]
01443     >>> doctest.DocTestRunner(verbose=False,
01444     ...                       optionflags=doctest.ELLIPSIS).run(test)
01445     ... # doctest: +ELLIPSIS
01446     **********************************************************************
01447     File ..., line 6, in f
01448     Failed example:
01449         print(list(range(10)))      # doctest: -ELLIPSIS
01450     Expected:
01451         [0, 1, ..., 9]
01452     Got:
01453         [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
01454     TestResults(failed=1, attempted=2)
01455 
01456 Option directives affect only the example that they appear with; they
01457 do not change the options for surrounding examples:
01458 
01459     >>> def f(x): r'''
01460     ...     >>> print(list(range(10)))      # Should fail: no ellipsis
01461     ...     [0, 1, ..., 9]
01462     ...
01463     ...     >>> print(list(range(10)))      # doctest: +ELLIPSIS
01464     ...     [0, 1, ..., 9]
01465     ...
01466     ...     >>> print(list(range(10)))      # Should fail: no ellipsis
01467     ...     [0, 1, ..., 9]
01468     ...     '''
01469     >>> test = doctest.DocTestFinder().find(f)[0]
01470     >>> doctest.DocTestRunner(verbose=False).run(test)
01471     ... # doctest: +ELLIPSIS
01472     **********************************************************************
01473     File ..., line 2, in f
01474     Failed example:
01475         print(list(range(10)))      # Should fail: no ellipsis
01476     Expected:
01477         [0, 1, ..., 9]
01478     Got:
01479         [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
01480     **********************************************************************
01481     File ..., line 8, in f
01482     Failed example:
01483         print(list(range(10)))      # Should fail: no ellipsis
01484     Expected:
01485         [0, 1, ..., 9]
01486     Got:
01487         [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
01488     TestResults(failed=2, attempted=3)
01489 
01490 Multiple options may be modified by a single option directive.  They
01491 may be separated by whitespace, commas, or both:
01492 
01493     >>> def f(x): r'''
01494     ...     >>> print(list(range(10)))      # Should fail
01495     ...     [0, 1,  ...,   9]
01496     ...     >>> print(list(range(10)))      # Should succeed
01497     ...     ... # doctest: +ELLIPSIS +NORMALIZE_WHITESPACE
01498     ...     [0, 1,  ...,   9]
01499     ...     '''
01500     >>> test = doctest.DocTestFinder().find(f)[0]
01501     >>> doctest.DocTestRunner(verbose=False).run(test)
01502     ... # doctest: +ELLIPSIS
01503     **********************************************************************
01504     File ..., line 2, in f
01505     Failed example:
01506         print(list(range(10)))      # Should fail
01507     Expected:
01508         [0, 1,  ...,   9]
01509     Got:
01510         [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
01511     TestResults(failed=1, attempted=2)
01512 
01513     >>> def f(x): r'''
01514     ...     >>> print(list(range(10)))      # Should fail
01515     ...     [0, 1,  ...,   9]
01516     ...     >>> print(list(range(10)))      # Should succeed
01517     ...     ... # doctest: +ELLIPSIS,+NORMALIZE_WHITESPACE
01518     ...     [0, 1,  ...,   9]
01519     ...     '''
01520     >>> test = doctest.DocTestFinder().find(f)[0]
01521     >>> doctest.DocTestRunner(verbose=False).run(test)
01522     ... # doctest: +ELLIPSIS
01523     **********************************************************************
01524     File ..., line 2, in f
01525     Failed example:
01526         print(list(range(10)))      # Should fail
01527     Expected:
01528         [0, 1,  ...,   9]
01529     Got:
01530         [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
01531     TestResults(failed=1, attempted=2)
01532 
01533     >>> def f(x): r'''
01534     ...     >>> print(list(range(10)))      # Should fail
01535     ...     [0, 1,  ...,   9]
01536     ...     >>> print(list(range(10)))      # Should succeed
01537     ...     ... # doctest: +ELLIPSIS, +NORMALIZE_WHITESPACE
01538     ...     [0, 1,  ...,   9]
01539     ...     '''
01540     >>> test = doctest.DocTestFinder().find(f)[0]
01541     >>> doctest.DocTestRunner(verbose=False).run(test)
01542     ... # doctest: +ELLIPSIS
01543     **********************************************************************
01544     File ..., line 2, in f
01545     Failed example:
01546         print(list(range(10)))      # Should fail
01547     Expected:
01548         [0, 1,  ...,   9]
01549     Got:
01550         [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
01551     TestResults(failed=1, attempted=2)
01552 
01553 The option directive may be put on the line following the source, as
01554 long as a continuation prompt is used:
01555 
01556     >>> def f(x): r'''
01557     ...     >>> print(list(range(10)))
01558     ...     ... # doctest: +ELLIPSIS
01559     ...     [0, 1, ..., 9]
01560     ...     '''
01561     >>> test = doctest.DocTestFinder().find(f)[0]
01562     >>> doctest.DocTestRunner(verbose=False).run(test)
01563     TestResults(failed=0, attempted=1)
01564 
01565 For examples with multi-line source, the option directive may appear
01566 at the end of any line:
01567 
01568     >>> def f(x): r'''
01569     ...     >>> for x in range(10): # doctest: +ELLIPSIS
01570     ...     ...     print(' ', x, end='', sep='')
01571     ...      0 1 2 ... 9
01572     ...
01573     ...     >>> for x in range(10):
01574     ...     ...     print(' ', x, end='', sep='') # doctest: +ELLIPSIS
01575     ...      0 1 2 ... 9
01576     ...     '''
01577     >>> test = doctest.DocTestFinder().find(f)[0]
01578     >>> doctest.DocTestRunner(verbose=False).run(test)
01579     TestResults(failed=0, attempted=2)
01580 
01581 If more than one line of an example with multi-line source has an
01582 option directive, then they are combined:
01583 
01584     >>> def f(x): r'''
01585     ...     Should fail (option directive not on the last line):
01586     ...         >>> for x in range(10): # doctest: +ELLIPSIS
01587     ...         ...     print(x, end=' ') # doctest: +NORMALIZE_WHITESPACE
01588     ...         0  1    2...9
01589     ...     '''
01590     >>> test = doctest.DocTestFinder().find(f)[0]
01591     >>> doctest.DocTestRunner(verbose=False).run(test)
01592     TestResults(failed=0, attempted=1)
01593 
01594 It is an error to have a comment of the form ``# doctest:`` that is
01595 *not* followed by words of the form ``+OPTION`` or ``-OPTION``, where
01596 ``OPTION`` is an option that has been registered with
01597 `register_option`:
01598 
01599     >>> # Error: Option not registered
01600     >>> s = '>>> print(12)  #doctest: +BADOPTION'
01601     >>> test = doctest.DocTestParser().get_doctest(s, {}, 's', 's.py', 0)
01602     Traceback (most recent call last):
01603     ValueError: line 1 of the doctest for s has an invalid option: '+BADOPTION'
01604 
01605     >>> # Error: No + or - prefix
01606     >>> s = '>>> print(12)  #doctest: ELLIPSIS'
01607     >>> test = doctest.DocTestParser().get_doctest(s, {}, 's', 's.py', 0)
01608     Traceback (most recent call last):
01609     ValueError: line 1 of the doctest for s has an invalid option: 'ELLIPSIS'
01610 
01611 It is an error to use an option directive on a line that contains no
01612 source:
01613 
01614     >>> s = '>>> # doctest: +ELLIPSIS'
01615     >>> test = doctest.DocTestParser().get_doctest(s, {}, 's', 's.py', 0)
01616     Traceback (most recent call last):
01617     ValueError: line 0 of the doctest for s has an option directive on a line with no example: '# doctest: +ELLIPSIS'
01618 """

Definition at line 1013 of file test_doctest.py.

01013 
01014     def optionflags(): r"""
01015 Tests of `DocTestRunner`'s option flag handling.
01016 
01017 Several option flags can be used to customize the behavior of the test
01018 runner.  These are defined as module constants in doctest, and passed
01019 to the DocTestRunner constructor (multiple constants should be ORed
01020 together).
01021 
01022 The DONT_ACCEPT_TRUE_FOR_1 flag disables matches between True/False
01023 and 1/0:
01024 
01025     >>> def f(x):
01026     ...     '>>> True\n1\n'
01027 
01028     >>> # Without the flag:
01029     >>> test = doctest.DocTestFinder().find(f)[0]
01030     >>> doctest.DocTestRunner(verbose=False).run(test)
01031     TestResults(failed=0, attempted=1)
01032 
01033     >>> # With the flag:
01034     >>> test = doctest.DocTestFinder().find(f)[0]
01035     >>> flags = doctest.DONT_ACCEPT_TRUE_FOR_1
01036     >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
01037     ... # doctest: +ELLIPSIS
01038     **********************************************************************
01039     File ..., line 2, in f
01040     Failed example:
01041         True
01042     Expected:
01043         1
01044     Got:
01045         True
01046     TestResults(failed=1, attempted=1)
01047 
01048 The DONT_ACCEPT_BLANKLINE flag disables the match between blank lines
01049 and the '<BLANKLINE>' marker:
01050 
01051     >>> def f(x):
01052     ...     '>>> print("a\\n\\nb")\na\n<BLANKLINE>\nb\n'
01053 
01054     >>> # Without the flag:
01055     >>> test = doctest.DocTestFinder().find(f)[0]
01056     >>> doctest.DocTestRunner(verbose=False).run(test)
01057     TestResults(failed=0, attempted=1)
01058 
01059     >>> # With the flag:
01060     >>> test = doctest.DocTestFinder().find(f)[0]
01061     >>> flags = doctest.DONT_ACCEPT_BLANKLINE
01062     >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
01063     ... # doctest: +ELLIPSIS
01064     **********************************************************************
01065     File ..., line 2, in f
01066     Failed example:
01067         print("a\n\nb")
01068     Expected:
01069         a
01070         <BLANKLINE>
01071         b
01072     Got:
01073         a
01074     <BLANKLINE>
01075         b
01076     TestResults(failed=1, attempted=1)
01077 
01078 The NORMALIZE_WHITESPACE flag causes all sequences of whitespace to be
01079 treated as equal:
01080 
01081     >>> def f(x):
01082     ...     '>>> print(1, 2, 3)\n  1   2\n 3'
01083 
01084     >>> # Without the flag:
01085     >>> test = doctest.DocTestFinder().find(f)[0]
01086     >>> doctest.DocTestRunner(verbose=False).run(test)
01087     ... # doctest: +ELLIPSIS
01088     **********************************************************************
01089     File ..., line 2, in f
01090     Failed example:
01091         print(1, 2, 3)
01092     Expected:
01093           1   2
01094          3
01095     Got:
01096         1 2 3
01097     TestResults(failed=1, attempted=1)
01098 
01099     >>> # With the flag:
01100     >>> test = doctest.DocTestFinder().find(f)[0]
01101     >>> flags = doctest.NORMALIZE_WHITESPACE
01102     >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
01103     TestResults(failed=0, attempted=1)
01104 
01105     An example from the docs:
01106     >>> print(list(range(20))) #doctest: +NORMALIZE_WHITESPACE
01107     [0,   1,  2,  3,  4,  5,  6,  7,  8,  9,
01108     10,  11, 12, 13, 14, 15, 16, 17, 18, 19]
01109 
01110 The ELLIPSIS flag causes ellipsis marker ("...") in the expected
01111 output to match any substring in the actual output:
01112 
01113     >>> def f(x):
01114     ...     '>>> print(list(range(15)))\n[0, 1, 2, ..., 14]\n'
01115 
01116     >>> # Without the flag:
01117     >>> test = doctest.DocTestFinder().find(f)[0]
01118     >>> doctest.DocTestRunner(verbose=False).run(test)
01119     ... # doctest: +ELLIPSIS
01120     **********************************************************************
01121     File ..., line 2, in f
01122     Failed example:
01123         print(list(range(15)))
01124     Expected:
01125         [0, 1, 2, ..., 14]
01126     Got:
01127         [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14]
01128     TestResults(failed=1, attempted=1)
01129 
01130     >>> # With the flag:
01131     >>> test = doctest.DocTestFinder().find(f)[0]
01132     >>> flags = doctest.ELLIPSIS
01133     >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
01134     TestResults(failed=0, attempted=1)
01135 
01136     ... also matches nothing:
01137 
01138     >>> if 1:
01139     ...     for i in range(100):
01140     ...         print(i**2, end=' ') #doctest: +ELLIPSIS
01141     ...     print('!')
01142     0 1...4...9 16 ... 36 49 64 ... 9801 !
01143 
01144     ... can be surprising; e.g., this test passes:
01145 
01146     >>> if 1:  #doctest: +ELLIPSIS
01147     ...     for i in range(20):
01148     ...         print(i, end=' ')
01149     ...     print(20)
01150     0 1 2 ...1...2...0
01151 
01152     Examples from the docs:
01153 
01154     >>> print(list(range(20))) # doctest:+ELLIPSIS
01155     [0, 1, ..., 18, 19]
01156 
01157     >>> print(list(range(20))) # doctest: +ELLIPSIS
01158     ...                 # doctest: +NORMALIZE_WHITESPACE
01159     [0,    1, ...,   18,    19]
01160 
01161 The SKIP flag causes an example to be skipped entirely.  I.e., the
01162 example is not run.  It can be useful in contexts where doctest
01163 examples serve as both documentation and test cases, and an example
01164 should be included for documentation purposes, but should not be
01165 checked (e.g., because its output is random, or depends on resources
01166 which would be unavailable.)  The SKIP flag can also be used for
01167 'commenting out' broken examples.
01168 
01169     >>> import unavailable_resource           # doctest: +SKIP
01170     >>> unavailable_resource.do_something()   # doctest: +SKIP
01171     >>> unavailable_resource.blow_up()        # doctest: +SKIP
01172     Traceback (most recent call last):
01173         ...
01174     UncheckedBlowUpError:  Nobody checks me.
01175 
01176     >>> import random
01177     >>> print(random.random()) # doctest: +SKIP
01178     0.721216923889
01179 
01180 The REPORT_UDIFF flag causes failures that involve multi-line expected
01181 and actual outputs to be displayed using a unified diff:
01182 
01183     >>> def f(x):
01184     ...     r'''
01185     ...     >>> print('\n'.join('abcdefg'))
01186     ...     a
01187     ...     B
01188     ...     c
01189     ...     d
01190     ...     f
01191     ...     g
01192     ...     h
01193     ...     '''
01194 
01195     >>> # Without the flag:
01196     >>> test = doctest.DocTestFinder().find(f)[0]
01197     >>> doctest.DocTestRunner(verbose=False).run(test)
01198     ... # doctest: +ELLIPSIS
01199     **********************************************************************
01200     File ..., line 3, in f
01201     Failed example:
01202         print('\n'.join('abcdefg'))
01203     Expected:
01204         a
01205         B
01206         c
01207         d
01208         f
01209         g
01210         h
01211     Got:
01212         a
01213         b
01214         c
01215         d
01216         e
01217         f
01218         g
01219     TestResults(failed=1, attempted=1)
01220 
01221     >>> # With the flag:
01222     >>> test = doctest.DocTestFinder().find(f)[0]
01223     >>> flags = doctest.REPORT_UDIFF
01224     >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
01225     ... # doctest: +ELLIPSIS
01226     **********************************************************************
01227     File ..., line 3, in f
01228     Failed example:
01229         print('\n'.join('abcdefg'))
01230     Differences (unified diff with -expected +actual):
01231         @@ -1,7 +1,7 @@
01232          a
01233         -B
01234         +b
01235          c
01236          d
01237         +e
01238          f
01239          g
01240         -h
01241     TestResults(failed=1, attempted=1)
01242 
01243 The REPORT_CDIFF flag causes failures that involve multi-line expected
01244 and actual outputs to be displayed using a context diff:
01245 
01246     >>> # Reuse f() from the REPORT_UDIFF example, above.
01247     >>> test = doctest.DocTestFinder().find(f)[0]
01248     >>> flags = doctest.REPORT_CDIFF
01249     >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
01250     ... # doctest: +ELLIPSIS
01251     **********************************************************************
01252     File ..., line 3, in f
01253     Failed example:
01254         print('\n'.join('abcdefg'))
01255     Differences (context diff with expected followed by actual):
01256         ***************
01257         *** 1,7 ****
01258           a
01259         ! B
01260           c
01261           d
01262           f
01263           g
01264         - h
01265         --- 1,7 ----
01266           a
01267         ! b
01268           c
01269           d
01270         + e
01271           f
01272           g
01273     TestResults(failed=1, attempted=1)
01274 
01275 
01276 The REPORT_NDIFF flag causes failures to use the difflib.Differ algorithm
01277 used by the popular ndiff.py utility.  This does intraline difference
01278 marking, as well as interline differences.
01279 
01280     >>> def f(x):
01281     ...     r'''
01282     ...     >>> print("a b  c d e f g h i   j k l m")
01283     ...     a b c d e f g h i j k 1 m
01284     ...     '''
01285     >>> test = doctest.DocTestFinder().find(f)[0]
01286     >>> flags = doctest.REPORT_NDIFF
01287     >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
01288     ... # doctest: +ELLIPSIS
01289     **********************************************************************
01290     File ..., line 3, in f
01291     Failed example:
01292         print("a b  c d e f g h i   j k l m")
01293     Differences (ndiff with -expected +actual):
01294         - a b c d e f g h i j k 1 m
01295         ?                       ^
01296         + a b  c d e f g h i   j k l m
01297         ?     +              ++    ^
01298     TestResults(failed=1, attempted=1)
01299 
01300 The REPORT_ONLY_FIRST_FAILURE suppresses result output after the first
01301 failing example:
01302 
01303     >>> def f(x):
01304     ...     r'''
01305     ...     >>> print(1) # first success
01306     ...     1
01307     ...     >>> print(2) # first failure
01308     ...     200
01309     ...     >>> print(3) # second failure
01310     ...     300
01311     ...     >>> print(4) # second success
01312     ...     4
01313     ...     >>> print(5) # third failure
01314     ...     500
01315     ...     '''
01316     >>> test = doctest.DocTestFinder().find(f)[0]
01317     >>> flags = doctest.REPORT_ONLY_FIRST_FAILURE
01318     >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
01319     ... # doctest: +ELLIPSIS
01320     **********************************************************************
01321     File ..., line 5, in f
01322     Failed example:
01323         print(2) # first failure
01324     Expected:
01325         200
01326     Got:
01327         2
01328     TestResults(failed=3, attempted=5)
01329 
01330 However, output from `report_start` is not suppressed:
01331 
01332     >>> doctest.DocTestRunner(verbose=True, optionflags=flags).run(test)
01333     ... # doctest: +ELLIPSIS
01334     Trying:
01335         print(1) # first success
01336     Expecting:
01337         1
01338     ok
01339     Trying:
01340         print(2) # first failure
01341     Expecting:
01342         200
01343     **********************************************************************
01344     File ..., line 5, in f
01345     Failed example:
01346         print(2) # first failure
01347     Expected:
01348         200
01349     Got:
01350         2
01351     TestResults(failed=3, attempted=5)
01352 
01353 For the purposes of REPORT_ONLY_FIRST_FAILURE, unexpected exceptions
01354 count as failures:
01355 
01356     >>> def f(x):
01357     ...     r'''
01358     ...     >>> print(1) # first success
01359     ...     1
01360     ...     >>> raise ValueError(2) # first failure
01361     ...     200
01362     ...     >>> print(3) # second failure
01363     ...     300
01364     ...     >>> print(4) # second success
01365     ...     4
01366     ...     >>> print(5) # third failure
01367     ...     500
01368     ...     '''
01369     >>> test = doctest.DocTestFinder().find(f)[0]
01370     >>> flags = doctest.REPORT_ONLY_FIRST_FAILURE
01371     >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
01372     ... # doctest: +ELLIPSIS
01373     **********************************************************************
01374     File ..., line 5, in f
01375     Failed example:
01376         raise ValueError(2) # first failure
01377     Exception raised:
01378         ...
01379         ValueError: 2
01380     TestResults(failed=3, attempted=5)
01381 
01382 New option flags can also be registered, via register_optionflag().  Here
01383 we reach into doctest's internals a bit.
01384 
01385     >>> unlikely = "UNLIKELY_OPTION_NAME"
01386     >>> unlikely in doctest.OPTIONFLAGS_BY_NAME
01387     False
01388     >>> new_flag_value = doctest.register_optionflag(unlikely)
01389     >>> unlikely in doctest.OPTIONFLAGS_BY_NAME
01390     True
01391 
01392 Before 2.4.4/2.5, registering a name more than once erroneously created
01393 more than one flag value.  Here we verify that's fixed:
01394 
01395     >>> redundant_flag_value = doctest.register_optionflag(unlikely)
01396     >>> redundant_flag_value == new_flag_value
01397     True
01398 
01399 Clean up.
01400     >>> del doctest.OPTIONFLAGS_BY_NAME[unlikely]
01401 
01402     """

Definition at line 706 of file test_doctest.py.

00706 
00707     def verbose_flag(): r"""
00708 The `verbose` flag makes the test runner generate more detailed
00709 output:
00710 
00711     >>> def f(x):
00712     ...     '''
00713     ...     >>> x = 12
00714     ...     >>> print(x)
00715     ...     12
00716     ...     >>> x//2
00717     ...     6
00718     ...     '''
00719     >>> test = doctest.DocTestFinder().find(f)[0]
00720 
00721     >>> doctest.DocTestRunner(verbose=True).run(test)
00722     Trying:
00723         x = 12
00724     Expecting nothing
00725     ok
00726     Trying:
00727         print(x)
00728     Expecting:
00729         12
00730     ok
00731     Trying:
00732         x//2
00733     Expecting:
00734         6
00735     ok
00736     TestResults(failed=0, attempted=3)
00737 
00738 If the `verbose` flag is unspecified, then the output will be verbose
00739 iff `-v` appears in sys.argv:
00740 
00741     >>> # Save the real sys.argv list.
00742     >>> old_argv = sys.argv
00743 
00744     >>> # If -v does not appear in sys.argv, then output isn't verbose.
00745     >>> sys.argv = ['test']
00746     >>> doctest.DocTestRunner().run(test)
00747     TestResults(failed=0, attempted=3)
00748 
00749     >>> # If -v does appear in sys.argv, then output is verbose.
00750     >>> sys.argv = ['test', '-v']
00751     >>> doctest.DocTestRunner().run(test)
00752     Trying:
00753         x = 12
00754     Expecting nothing
00755     ok
00756     Trying:
00757         print(x)
00758     Expecting:
00759         12
00760     ok
00761     Trying:
00762         x//2
00763     Expecting:
00764         6
00765     ok
00766     TestResults(failed=0, attempted=3)
00767 
00768     >>> # Restore sys.argv
00769     >>> sys.argv = old_argv
00770 
00771 In the remaining examples, the test runner's verbosity will be
00772 explicitly set, to ensure that the test behavior is consistent.
    """

The documentation for this class was generated from the following file: