| # -*- coding: utf-8 -*-
|
| """
|
| Test script for doctest.
|
| """
|
|
|
| import sys
|
| from test import test_support
|
| import doctest
|
|
|
| # NOTE: There are some additional tests relating to interaction with
|
| # zipimport in the test_zipimport_support test module.
|
|
|
| ######################################################################
|
| ## Sample Objects (used by test cases)
|
| ######################################################################
|
|
|
| def sample_func(v):
|
| """
|
| Blah blah
|
|
|
| >>> print sample_func(22)
|
| 44
|
|
|
| Yee ha!
|
| """
|
| return v+v
|
|
|
| class SampleClass:
|
| """
|
| >>> print 1
|
| 1
|
|
|
| >>> # comments get ignored. so are empty PS1 and PS2 prompts:
|
| >>>
|
| ...
|
|
|
| Multiline example:
|
| >>> sc = SampleClass(3)
|
| >>> for i in range(10):
|
| ... sc = sc.double()
|
| ... print sc.get(),
|
| 6 12 24 48 96 192 384 768 1536 3072
|
| """
|
| def __init__(self, val):
|
| """
|
| >>> print SampleClass(12).get()
|
| 12
|
| """
|
| self.val = val
|
|
|
| def double(self):
|
| """
|
| >>> print SampleClass(12).double().get()
|
| 24
|
| """
|
| return SampleClass(self.val + self.val)
|
|
|
| def get(self):
|
| """
|
| >>> print SampleClass(-5).get()
|
| -5
|
| """
|
| return self.val
|
|
|
| def a_staticmethod(v):
|
| """
|
| >>> print SampleClass.a_staticmethod(10)
|
| 11
|
| """
|
| return v+1
|
| a_staticmethod = staticmethod(a_staticmethod)
|
|
|
| def a_classmethod(cls, v):
|
| """
|
| >>> print SampleClass.a_classmethod(10)
|
| 12
|
| >>> print SampleClass(0).a_classmethod(10)
|
| 12
|
| """
|
| return v+2
|
| a_classmethod = classmethod(a_classmethod)
|
|
|
| a_property = property(get, doc="""
|
| >>> print SampleClass(22).a_property
|
| 22
|
| """)
|
|
|
| class NestedClass:
|
| """
|
| >>> x = SampleClass.NestedClass(5)
|
| >>> y = x.square()
|
| >>> print y.get()
|
| 25
|
| """
|
| def __init__(self, val=0):
|
| """
|
| >>> print SampleClass.NestedClass().get()
|
| 0
|
| """
|
| self.val = val
|
| def square(self):
|
| return SampleClass.NestedClass(self.val*self.val)
|
| def get(self):
|
| return self.val
|
|
|
| class SampleNewStyleClass(object):
|
| r"""
|
| >>> print '1\n2\n3'
|
| 1
|
| 2
|
| 3
|
| """
|
| def __init__(self, val):
|
| """
|
| >>> print SampleNewStyleClass(12).get()
|
| 12
|
| """
|
| self.val = val
|
|
|
| def double(self):
|
| """
|
| >>> print SampleNewStyleClass(12).double().get()
|
| 24
|
| """
|
| return SampleNewStyleClass(self.val + self.val)
|
|
|
| def get(self):
|
| """
|
| >>> print SampleNewStyleClass(-5).get()
|
| -5
|
| """
|
| return self.val
|
|
|
| ######################################################################
|
| ## Fake stdin (for testing interactive debugging)
|
| ######################################################################
|
|
|
| class _FakeInput:
|
| """
|
| A fake input stream for pdb's interactive debugger. Whenever a
|
| line is read, print it (to simulate the user typing it), and then
|
| return it. The set of lines to return is specified in the
|
| constructor; they should not have trailing newlines.
|
| """
|
| def __init__(self, lines):
|
| self.lines = lines
|
|
|
| def readline(self):
|
| line = self.lines.pop(0)
|
| print line
|
| return line+'\n'
|
|
|
| ######################################################################
|
| ## Test Cases
|
| ######################################################################
|
|
|
| def test_Example(): r"""
|
| Unit tests for the `Example` class.
|
|
|
| Example is a simple container class that holds:
|
| - `source`: A source string.
|
| - `want`: An expected output string.
|
| - `exc_msg`: An expected exception message string (or None if no
|
| exception is expected).
|
| - `lineno`: A line number (within the docstring).
|
| - `indent`: The example's indentation in the input string.
|
| - `options`: An option dictionary, mapping option flags to True or
|
| False.
|
|
|
| These attributes are set by the constructor. `source` and `want` are
|
| required; the other attributes all have default values:
|
|
|
| >>> example = doctest.Example('print 1', '1\n')
|
| >>> (example.source, example.want, example.exc_msg,
|
| ... example.lineno, example.indent, example.options)
|
| ('print 1\n', '1\n', None, 0, 0, {})
|
|
|
| The first three attributes (`source`, `want`, and `exc_msg`) may be
|
| specified positionally; the remaining arguments should be specified as
|
| keyword arguments:
|
|
|
| >>> exc_msg = 'IndexError: pop from an empty list'
|
| >>> example = doctest.Example('[].pop()', '', exc_msg,
|
| ... lineno=5, indent=4,
|
| ... options={doctest.ELLIPSIS: True})
|
| >>> (example.source, example.want, example.exc_msg,
|
| ... example.lineno, example.indent, example.options)
|
| ('[].pop()\n', '', 'IndexError: pop from an empty list\n', 5, 4, {8: True})
|
|
|
| The constructor normalizes the `source` string to end in a newline:
|
|
|
| Source spans a single line: no terminating newline.
|
| >>> e = doctest.Example('print 1', '1\n')
|
| >>> e.source, e.want
|
| ('print 1\n', '1\n')
|
|
|
| >>> e = doctest.Example('print 1\n', '1\n')
|
| >>> e.source, e.want
|
| ('print 1\n', '1\n')
|
|
|
| Source spans multiple lines: require terminating newline.
|
| >>> e = doctest.Example('print 1;\nprint 2\n', '1\n2\n')
|
| >>> e.source, e.want
|
| ('print 1;\nprint 2\n', '1\n2\n')
|
|
|
| >>> e = doctest.Example('print 1;\nprint 2', '1\n2\n')
|
| >>> e.source, e.want
|
| ('print 1;\nprint 2\n', '1\n2\n')
|
|
|
| Empty source string (which should never appear in real examples)
|
| >>> e = doctest.Example('', '')
|
| >>> e.source, e.want
|
| ('\n', '')
|
|
|
| The constructor normalizes the `want` string to end in a newline,
|
| unless it's the empty string:
|
|
|
| >>> e = doctest.Example('print 1', '1\n')
|
| >>> e.source, e.want
|
| ('print 1\n', '1\n')
|
|
|
| >>> e = doctest.Example('print 1', '1')
|
| >>> e.source, e.want
|
| ('print 1\n', '1\n')
|
|
|
| >>> e = doctest.Example('print', '')
|
| >>> e.source, e.want
|
| ('print\n', '')
|
|
|
| The constructor normalizes the `exc_msg` string to end in a newline,
|
| unless it's `None`:
|
|
|
| Message spans one line
|
| >>> exc_msg = 'IndexError: pop from an empty list'
|
| >>> e = doctest.Example('[].pop()', '', exc_msg)
|
| >>> e.exc_msg
|
| 'IndexError: pop from an empty list\n'
|
|
|
| >>> exc_msg = 'IndexError: pop from an empty list\n'
|
| >>> e = doctest.Example('[].pop()', '', exc_msg)
|
| >>> e.exc_msg
|
| 'IndexError: pop from an empty list\n'
|
|
|
| Message spans multiple lines
|
| >>> exc_msg = 'ValueError: 1\n 2'
|
| >>> e = doctest.Example('raise ValueError("1\n 2")', '', exc_msg)
|
| >>> e.exc_msg
|
| 'ValueError: 1\n 2\n'
|
|
|
| >>> exc_msg = 'ValueError: 1\n 2\n'
|
| >>> e = doctest.Example('raise ValueError("1\n 2")', '', exc_msg)
|
| >>> e.exc_msg
|
| 'ValueError: 1\n 2\n'
|
|
|
| Empty (but non-None) exception message (which should never appear
|
| in real examples)
|
| >>> exc_msg = ''
|
| >>> e = doctest.Example('raise X()', '', exc_msg)
|
| >>> e.exc_msg
|
| '\n'
|
| """
|
|
|
| def test_DocTest(): r"""
|
| Unit tests for the `DocTest` class.
|
|
|
| DocTest is a collection of examples, extracted from a docstring, along
|
| with information about where the docstring comes from (a name,
|
| filename, and line number). The docstring is parsed by the `DocTest`
|
| constructor:
|
|
|
| >>> docstring = '''
|
| ... >>> print 12
|
| ... 12
|
| ...
|
| ... Non-example text.
|
| ...
|
| ... >>> print 'another\example'
|
| ... another
|
| ... example
|
| ... '''
|
| >>> globs = {} # globals to run the test in.
|
| >>> parser = doctest.DocTestParser()
|
| >>> test = parser.get_doctest(docstring, globs, 'some_test',
|
| ... 'some_file', 20)
|
| >>> print test
|
| <DocTest some_test from some_file:20 (2 examples)>
|
| >>> len(test.examples)
|
| 2
|
| >>> e1, e2 = test.examples
|
| >>> (e1.source, e1.want, e1.lineno)
|
| ('print 12\n', '12\n', 1)
|
| >>> (e2.source, e2.want, e2.lineno)
|
| ("print 'another\\example'\n", 'another\nexample\n', 6)
|
|
|
| Source information (name, filename, and line number) is available as
|
| attributes on the doctest object:
|
|
|
| >>> (test.name, test.filename, test.lineno)
|
| ('some_test', 'some_file', 20)
|
|
|
| The line number of an example within its containing file is found by
|
| adding the line number of the example and the line number of its
|
| containing test:
|
|
|
| >>> test.lineno + e1.lineno
|
| 21
|
| >>> test.lineno + e2.lineno
|
| 26
|
|
|
| If the docstring contains inconsistant leading whitespace in the
|
| expected output of an example, then `DocTest` will raise a ValueError:
|
|
|
| >>> docstring = r'''
|
| ... >>> print 'bad\nindentation'
|
| ... bad
|
| ... indentation
|
| ... '''
|
| >>> parser.get_doctest(docstring, globs, 'some_test', 'filename', 0)
|
| Traceback (most recent call last):
|
| ValueError: line 4 of the docstring for some_test has inconsistent leading whitespace: 'indentation'
|
|
|
| If the docstring contains inconsistent leading whitespace on
|
| continuation lines, then `DocTest` will raise a ValueError:
|
|
|
| >>> docstring = r'''
|
| ... >>> print ('bad indentation',
|
| ... ... 2)
|
| ... ('bad', 'indentation')
|
| ... '''
|
| >>> parser.get_doctest(docstring, globs, 'some_test', 'filename', 0)
|
| Traceback (most recent call last):
|
| ValueError: line 2 of the docstring for some_test has inconsistent leading whitespace: '... 2)'
|
|
|
| If there's no blank space after a PS1 prompt ('>>>'), then `DocTest`
|
| will raise a ValueError:
|
|
|
| >>> docstring = '>>>print 1\n1'
|
| >>> parser.get_doctest(docstring, globs, 'some_test', 'filename', 0)
|
| Traceback (most recent call last):
|
| ValueError: line 1 of the docstring for some_test lacks blank after >>>: '>>>print 1'
|
|
|
| If there's no blank space after a PS2 prompt ('...'), then `DocTest`
|
| will raise a ValueError:
|
|
|
| >>> docstring = '>>> if 1:\n...print 1\n1'
|
| >>> parser.get_doctest(docstring, globs, 'some_test', 'filename', 0)
|
| Traceback (most recent call last):
|
| ValueError: line 2 of the docstring for some_test lacks blank after ...: '...print 1'
|
|
|
| """
|
|
|
| def test_DocTestFinder(): r"""
|
| Unit tests for the `DocTestFinder` class.
|
|
|
| DocTestFinder is used to extract DocTests from an object's docstring
|
| and the docstrings of its contained objects. It can be used with
|
| modules, functions, classes, methods, staticmethods, classmethods, and
|
| properties.
|
|
|
| Finding Tests in Functions
|
| ~~~~~~~~~~~~~~~~~~~~~~~~~~
|
| For a function whose docstring contains examples, DocTestFinder.find()
|
| will return a single test (for that function's docstring):
|
|
|
| >>> finder = doctest.DocTestFinder()
|
|
|
| We'll simulate a __file__ attr that ends in pyc:
|
|
|
| >>> import test.test_doctest
|
| >>> old = test.test_doctest.__file__
|
| >>> test.test_doctest.__file__ = 'test_doctest.pyc'
|
|
|
| >>> tests = finder.find(sample_func)
|
|
|
| >>> print tests # doctest: +ELLIPSIS
|
| [<DocTest sample_func from ...:17 (1 example)>]
|
|
|
| The exact name depends on how test_doctest was invoked, so allow for
|
| leading path components.
|
|
|
| >>> tests[0].filename # doctest: +ELLIPSIS
|
| '...test_doctest.py'
|
|
|
| >>> test.test_doctest.__file__ = old
|
|
|
|
|
| >>> e = tests[0].examples[0]
|
| >>> (e.source, e.want, e.lineno)
|
| ('print sample_func(22)\n', '44\n', 3)
|
|
|
| By default, tests are created for objects with no docstring:
|
|
|
| >>> def no_docstring(v):
|
| ... pass
|
| >>> finder.find(no_docstring)
|
| []
|
|
|
| However, the optional argument `exclude_empty` to the DocTestFinder
|
| constructor can be used to exclude tests for objects with empty
|
| docstrings:
|
|
|
| >>> def no_docstring(v):
|
| ... pass
|
| >>> excl_empty_finder = doctest.DocTestFinder(exclude_empty=True)
|
| >>> excl_empty_finder.find(no_docstring)
|
| []
|
|
|
| If the function has a docstring with no examples, then a test with no
|
| examples is returned. (This lets `DocTestRunner` collect statistics
|
| about which functions have no tests -- but is that useful? And should
|
| an empty test also be created when there's no docstring?)
|
|
|
| >>> def no_examples(v):
|
| ... ''' no doctest examples '''
|
| >>> finder.find(no_examples) # doctest: +ELLIPSIS
|
| [<DocTest no_examples from ...:1 (no examples)>]
|
|
|
| Finding Tests in Classes
|
| ~~~~~~~~~~~~~~~~~~~~~~~~
|
| For a class, DocTestFinder will create a test for the class's
|
| docstring, and will recursively explore its contents, including
|
| methods, classmethods, staticmethods, properties, and nested classes.
|
|
|
| >>> finder = doctest.DocTestFinder()
|
| >>> tests = finder.find(SampleClass)
|
| >>> for t in tests:
|
| ... print '%2s %s' % (len(t.examples), t.name)
|
| 3 SampleClass
|
| 3 SampleClass.NestedClass
|
| 1 SampleClass.NestedClass.__init__
|
| 1 SampleClass.__init__
|
| 2 SampleClass.a_classmethod
|
| 1 SampleClass.a_property
|
| 1 SampleClass.a_staticmethod
|
| 1 SampleClass.double
|
| 1 SampleClass.get
|
|
|
| New-style classes are also supported:
|
|
|
| >>> tests = finder.find(SampleNewStyleClass)
|
| >>> for t in tests:
|
| ... print '%2s %s' % (len(t.examples), t.name)
|
| 1 SampleNewStyleClass
|
| 1 SampleNewStyleClass.__init__
|
| 1 SampleNewStyleClass.double
|
| 1 SampleNewStyleClass.get
|
|
|
| Finding Tests in Modules
|
| ~~~~~~~~~~~~~~~~~~~~~~~~
|
| For a module, DocTestFinder will create a test for the class's
|
| docstring, and will recursively explore its contents, including
|
| functions, classes, and the `__test__` dictionary, if it exists:
|
|
|
| >>> # A module
|
| >>> import types
|
| >>> m = types.ModuleType('some_module')
|
| >>> def triple(val):
|
| ... '''
|
| ... >>> print triple(11)
|
| ... 33
|
| ... '''
|
| ... return val*3
|
| >>> m.__dict__.update({
|
| ... 'sample_func': sample_func,
|
| ... 'SampleClass': SampleClass,
|
| ... '__doc__': '''
|
| ... Module docstring.
|
| ... >>> print 'module'
|
| ... module
|
| ... ''',
|
| ... '__test__': {
|
| ... 'd': '>>> print 6\n6\n>>> print 7\n7\n',
|
| ... 'c': triple}})
|
|
|
| >>> finder = doctest.DocTestFinder()
|
| >>> # Use module=test.test_doctest, to prevent doctest from
|
| >>> # ignoring the objects since they weren't defined in m.
|
| >>> import test.test_doctest
|
| >>> tests = finder.find(m, module=test.test_doctest)
|
| >>> for t in tests:
|
| ... print '%2s %s' % (len(t.examples), t.name)
|
| 1 some_module
|
| 3 some_module.SampleClass
|
| 3 some_module.SampleClass.NestedClass
|
| 1 some_module.SampleClass.NestedClass.__init__
|
| 1 some_module.SampleClass.__init__
|
| 2 some_module.SampleClass.a_classmethod
|
| 1 some_module.SampleClass.a_property
|
| 1 some_module.SampleClass.a_staticmethod
|
| 1 some_module.SampleClass.double
|
| 1 some_module.SampleClass.get
|
| 1 some_module.__test__.c
|
| 2 some_module.__test__.d
|
| 1 some_module.sample_func
|
|
|
| Duplicate Removal
|
| ~~~~~~~~~~~~~~~~~
|
| If a single object is listed twice (under different names), then tests
|
| will only be generated for it once:
|
|
|
| >>> from test import doctest_aliases
|
| >>> assert doctest_aliases.TwoNames.f
|
| >>> assert doctest_aliases.TwoNames.g
|
| >>> tests = excl_empty_finder.find(doctest_aliases)
|
| >>> print len(tests)
|
| 2
|
| >>> print tests[0].name
|
| test.doctest_aliases.TwoNames
|
|
|
| TwoNames.f and TwoNames.g are bound to the same object.
|
| We can't guess which will be found in doctest's traversal of
|
| TwoNames.__dict__ first, so we have to allow for either.
|
|
|
| >>> tests[1].name.split('.')[-1] in ['f', 'g']
|
| True
|
|
|
| Empty Tests
|
| ~~~~~~~~~~~
|
| By default, an object with no doctests doesn't create any tests:
|
|
|
| >>> tests = doctest.DocTestFinder().find(SampleClass)
|
| >>> for t in tests:
|
| ... print '%2s %s' % (len(t.examples), t.name)
|
| 3 SampleClass
|
| 3 SampleClass.NestedClass
|
| 1 SampleClass.NestedClass.__init__
|
| 1 SampleClass.__init__
|
| 2 SampleClass.a_classmethod
|
| 1 SampleClass.a_property
|
| 1 SampleClass.a_staticmethod
|
| 1 SampleClass.double
|
| 1 SampleClass.get
|
|
|
| By default, that excluded objects with no doctests. exclude_empty=False
|
| tells it to include (empty) tests for objects with no doctests. This feature
|
| is really to support backward compatibility in what doctest.master.summarize()
|
| displays.
|
|
|
| >>> tests = doctest.DocTestFinder(exclude_empty=False).find(SampleClass)
|
| >>> for t in tests:
|
| ... print '%2s %s' % (len(t.examples), t.name)
|
| 3 SampleClass
|
| 3 SampleClass.NestedClass
|
| 1 SampleClass.NestedClass.__init__
|
| 0 SampleClass.NestedClass.get
|
| 0 SampleClass.NestedClass.square
|
| 1 SampleClass.__init__
|
| 2 SampleClass.a_classmethod
|
| 1 SampleClass.a_property
|
| 1 SampleClass.a_staticmethod
|
| 1 SampleClass.double
|
| 1 SampleClass.get
|
|
|
| Turning off Recursion
|
| ~~~~~~~~~~~~~~~~~~~~~
|
| DocTestFinder can be told not to look for tests in contained objects
|
| using the `recurse` flag:
|
|
|
| >>> tests = doctest.DocTestFinder(recurse=False).find(SampleClass)
|
| >>> for t in tests:
|
| ... print '%2s %s' % (len(t.examples), t.name)
|
| 3 SampleClass
|
|
|
| Line numbers
|
| ~~~~~~~~~~~~
|
| DocTestFinder finds the line number of each example:
|
|
|
| >>> def f(x):
|
| ... '''
|
| ... >>> x = 12
|
| ...
|
| ... some text
|
| ...
|
| ... >>> # examples are not created for comments & bare prompts.
|
| ... >>>
|
| ... ...
|
| ...
|
| ... >>> for x in range(10):
|
| ... ... print x,
|
| ... 0 1 2 3 4 5 6 7 8 9
|
| ... >>> x//2
|
| ... 6
|
| ... '''
|
| >>> test = doctest.DocTestFinder().find(f)[0]
|
| >>> [e.lineno for e in test.examples]
|
| [1, 9, 12]
|
| """
|
|
|
| def test_DocTestParser(): r"""
|
| Unit tests for the `DocTestParser` class.
|
|
|
| DocTestParser is used to parse docstrings containing doctest examples.
|
|
|
| The `parse` method divides a docstring into examples and intervening
|
| text:
|
|
|
| >>> s = '''
|
| ... >>> x, y = 2, 3 # no output expected
|
| ... >>> if 1:
|
| ... ... print x
|
| ... ... print y
|
| ... 2
|
| ... 3
|
| ...
|
| ... Some text.
|
| ... >>> x+y
|
| ... 5
|
| ... '''
|
| >>> parser = doctest.DocTestParser()
|
| >>> for piece in parser.parse(s):
|
| ... if isinstance(piece, doctest.Example):
|
| ... print 'Example:', (piece.source, piece.want, piece.lineno)
|
| ... else:
|
| ... print ' Text:', `piece`
|
| Text: '\n'
|
| Example: ('x, y = 2, 3 # no output expected\n', '', 1)
|
| Text: ''
|
| Example: ('if 1:\n print x\n print y\n', '2\n3\n', 2)
|
| Text: '\nSome text.\n'
|
| Example: ('x+y\n', '5\n', 9)
|
| Text: ''
|
|
|
| The `get_examples` method returns just the examples:
|
|
|
| >>> for piece in parser.get_examples(s):
|
| ... print (piece.source, piece.want, piece.lineno)
|
| ('x, y = 2, 3 # no output expected\n', '', 1)
|
| ('if 1:\n print x\n print y\n', '2\n3\n', 2)
|
| ('x+y\n', '5\n', 9)
|
|
|
| The `get_doctest` method creates a Test from the examples, along with the
|
| given arguments:
|
|
|
| >>> test = parser.get_doctest(s, {}, 'name', 'filename', lineno=5)
|
| >>> (test.name, test.filename, test.lineno)
|
| ('name', 'filename', 5)
|
| >>> for piece in test.examples:
|
| ... print (piece.source, piece.want, piece.lineno)
|
| ('x, y = 2, 3 # no output expected\n', '', 1)
|
| ('if 1:\n print x\n print y\n', '2\n3\n', 2)
|
| ('x+y\n', '5\n', 9)
|
| """
|
|
|
| class test_DocTestRunner:
|
| def basics(): r"""
|
| Unit tests for the `DocTestRunner` class.
|
|
|
| DocTestRunner is used to run DocTest test cases, and to accumulate
|
| statistics. Here's a simple DocTest case we can use:
|
|
|
| >>> def f(x):
|
| ... '''
|
| ... >>> x = 12
|
| ... >>> print x
|
| ... 12
|
| ... >>> x//2
|
| ... 6
|
| ... '''
|
| >>> test = doctest.DocTestFinder().find(f)[0]
|
|
|
| The main DocTestRunner interface is the `run` method, which runs a
|
| given DocTest case in a given namespace (globs). It returns a tuple
|
| `(f,t)`, where `f` is the number of failed tests and `t` is the number
|
| of tried tests.
|
|
|
| >>> doctest.DocTestRunner(verbose=False).run(test)
|
| TestResults(failed=0, attempted=3)
|
|
|
| If any example produces incorrect output, then the test runner reports
|
| the failure and proceeds to the next example:
|
|
|
| >>> def f(x):
|
| ... '''
|
| ... >>> x = 12
|
| ... >>> print x
|
| ... 14
|
| ... >>> x//2
|
| ... 6
|
| ... '''
|
| >>> test = doctest.DocTestFinder().find(f)[0]
|
| >>> doctest.DocTestRunner(verbose=True).run(test)
|
| ... # doctest: +ELLIPSIS
|
| Trying:
|
| x = 12
|
| Expecting nothing
|
| ok
|
| Trying:
|
| print x
|
| Expecting:
|
| 14
|
| **********************************************************************
|
| File ..., line 4, in f
|
| Failed example:
|
| print x
|
| Expected:
|
| 14
|
| Got:
|
| 12
|
| Trying:
|
| x//2
|
| Expecting:
|
| 6
|
| ok
|
| TestResults(failed=1, attempted=3)
|
| """
|
| def verbose_flag(): r"""
|
| The `verbose` flag makes the test runner generate more detailed
|
| output:
|
|
|
| >>> def f(x):
|
| ... '''
|
| ... >>> x = 12
|
| ... >>> print x
|
| ... 12
|
| ... >>> x//2
|
| ... 6
|
| ... '''
|
| >>> test = doctest.DocTestFinder().find(f)[0]
|
|
|
| >>> doctest.DocTestRunner(verbose=True).run(test)
|
| Trying:
|
| x = 12
|
| Expecting nothing
|
| ok
|
| Trying:
|
| print x
|
| Expecting:
|
| 12
|
| ok
|
| Trying:
|
| x//2
|
| Expecting:
|
| 6
|
| ok
|
| TestResults(failed=0, attempted=3)
|
|
|
| If the `verbose` flag is unspecified, then the output will be verbose
|
| iff `-v` appears in sys.argv:
|
|
|
| >>> # Save the real sys.argv list.
|
| >>> old_argv = sys.argv
|
|
|
| >>> # If -v does not appear in sys.argv, then output isn't verbose.
|
| >>> sys.argv = ['test']
|
| >>> doctest.DocTestRunner().run(test)
|
| TestResults(failed=0, attempted=3)
|
|
|
| >>> # If -v does appear in sys.argv, then output is verbose.
|
| >>> sys.argv = ['test', '-v']
|
| >>> doctest.DocTestRunner().run(test)
|
| Trying:
|
| x = 12
|
| Expecting nothing
|
| ok
|
| Trying:
|
| print x
|
| Expecting:
|
| 12
|
| ok
|
| Trying:
|
| x//2
|
| Expecting:
|
| 6
|
| ok
|
| TestResults(failed=0, attempted=3)
|
|
|
| >>> # Restore sys.argv
|
| >>> sys.argv = old_argv
|
|
|
| In the remaining examples, the test runner's verbosity will be
|
| explicitly set, to ensure that the test behavior is consistent.
|
| """
|
| def exceptions(): r"""
|
| Tests of `DocTestRunner`'s exception handling.
|
|
|
| An expected exception is specified with a traceback message. The
|
| lines between the first line and the type/value may be omitted or
|
| replaced with any other string:
|
|
|
| >>> def f(x):
|
| ... '''
|
| ... >>> x = 12
|
| ... >>> print x//0
|
| ... Traceback (most recent call last):
|
| ... ZeroDivisionError: integer division or modulo by zero
|
| ... '''
|
| >>> test = doctest.DocTestFinder().find(f)[0]
|
| >>> doctest.DocTestRunner(verbose=False).run(test)
|
| TestResults(failed=0, attempted=2)
|
|
|
| An example may not generate output before it raises an exception; if
|
| it does, then the traceback message will not be recognized as
|
| signaling an expected exception, so the example will be reported as an
|
| unexpected exception:
|
|
|
| >>> def f(x):
|
| ... '''
|
| ... >>> x = 12
|
| ... >>> print 'pre-exception output', x//0
|
| ... pre-exception output
|
| ... Traceback (most recent call last):
|
| ... ZeroDivisionError: integer division or modulo by zero
|
| ... '''
|
| >>> test = doctest.DocTestFinder().find(f)[0]
|
| >>> doctest.DocTestRunner(verbose=False).run(test)
|
| ... # doctest: +ELLIPSIS
|
| **********************************************************************
|
| File ..., line 4, in f
|
| Failed example:
|
| print 'pre-exception output', x//0
|
| Exception raised:
|
| ...
|
| ZeroDivisionError: integer division or modulo by zero
|
| TestResults(failed=1, attempted=2)
|
|
|
| Exception messages may contain newlines:
|
|
|
| >>> def f(x):
|
| ... r'''
|
| ... >>> raise ValueError, 'multi\nline\nmessage'
|
| ... Traceback (most recent call last):
|
| ... ValueError: multi
|
| ... line
|
| ... message
|
| ... '''
|
| >>> test = doctest.DocTestFinder().find(f)[0]
|
| >>> doctest.DocTestRunner(verbose=False).run(test)
|
| TestResults(failed=0, attempted=1)
|
|
|
| If an exception is expected, but an exception with the wrong type or
|
| message is raised, then it is reported as a failure:
|
|
|
| >>> def f(x):
|
| ... r'''
|
| ... >>> raise ValueError, 'message'
|
| ... Traceback (most recent call last):
|
| ... ValueError: wrong message
|
| ... '''
|
| >>> test = doctest.DocTestFinder().find(f)[0]
|
| >>> doctest.DocTestRunner(verbose=False).run(test)
|
| ... # doctest: +ELLIPSIS
|
| **********************************************************************
|
| File ..., line 3, in f
|
| Failed example:
|
| raise ValueError, 'message'
|
| Expected:
|
| Traceback (most recent call last):
|
| ValueError: wrong message
|
| Got:
|
| Traceback (most recent call last):
|
| ...
|
| ValueError: message
|
| TestResults(failed=1, attempted=1)
|
|
|
| However, IGNORE_EXCEPTION_DETAIL can be used to allow a mismatch in the
|
| detail:
|
|
|
| >>> def f(x):
|
| ... r'''
|
| ... >>> raise ValueError, 'message' #doctest: +IGNORE_EXCEPTION_DETAIL
|
| ... Traceback (most recent call last):
|
| ... ValueError: wrong message
|
| ... '''
|
| >>> test = doctest.DocTestFinder().find(f)[0]
|
| >>> doctest.DocTestRunner(verbose=False).run(test)
|
| TestResults(failed=0, attempted=1)
|
|
|
| IGNORE_EXCEPTION_DETAIL also ignores difference in exception formatting
|
| between Python versions. For example, in Python 3.x, the module path of
|
| the exception is in the output, but this will fail under Python 2:
|
|
|
| >>> def f(x):
|
| ... r'''
|
| ... >>> from httplib import HTTPException
|
| ... >>> raise HTTPException('message')
|
| ... Traceback (most recent call last):
|
| ... httplib.HTTPException: message
|
| ... '''
|
| >>> test = doctest.DocTestFinder().find(f)[0]
|
| >>> doctest.DocTestRunner(verbose=False).run(test)
|
| ... # doctest: +ELLIPSIS
|
| **********************************************************************
|
| File ..., line 4, in f
|
| Failed example:
|
| raise HTTPException('message')
|
| Expected:
|
| Traceback (most recent call last):
|
| httplib.HTTPException: message
|
| Got:
|
| Traceback (most recent call last):
|
| ...
|
| HTTPException: message
|
| TestResults(failed=1, attempted=2)
|
|
|
| But in Python 2 the module path is not included, an therefore a test must look
|
| like the following test to succeed in Python 2. But that test will fail under
|
| Python 3.
|
|
|
| >>> def f(x):
|
| ... r'''
|
| ... >>> from httplib import HTTPException
|
| ... >>> raise HTTPException('message')
|
| ... Traceback (most recent call last):
|
| ... HTTPException: message
|
| ... '''
|
| >>> test = doctest.DocTestFinder().find(f)[0]
|
| >>> doctest.DocTestRunner(verbose=False).run(test)
|
| TestResults(failed=0, attempted=2)
|
|
|
| However, with IGNORE_EXCEPTION_DETAIL, the module name of the exception
|
| (if any) will be ignored:
|
|
|
| >>> def f(x):
|
| ... r'''
|
| ... >>> from httplib import HTTPException
|
| ... >>> raise HTTPException('message') #doctest: +IGNORE_EXCEPTION_DETAIL
|
| ... Traceback (most recent call last):
|
| ... HTTPException: message
|
| ... '''
|
| >>> test = doctest.DocTestFinder().find(f)[0]
|
| >>> doctest.DocTestRunner(verbose=False).run(test)
|
| TestResults(failed=0, attempted=2)
|
|
|
| The module path will be completely ignored, so two different module paths will
|
| still pass if IGNORE_EXCEPTION_DETAIL is given. This is intentional, so it can
|
| be used when exceptions have changed module.
|
|
|
| >>> def f(x):
|
| ... r'''
|
| ... >>> from httplib import HTTPException
|
| ... >>> raise HTTPException('message') #doctest: +IGNORE_EXCEPTION_DETAIL
|
| ... Traceback (most recent call last):
|
| ... foo.bar.HTTPException: message
|
| ... '''
|
| >>> test = doctest.DocTestFinder().find(f)[0]
|
| >>> doctest.DocTestRunner(verbose=False).run(test)
|
| TestResults(failed=0, attempted=2)
|
|
|
| But IGNORE_EXCEPTION_DETAIL does not allow a mismatch in the exception type:
|
|
|
| >>> def f(x):
|
| ... r'''
|
| ... >>> raise ValueError, 'message' #doctest: +IGNORE_EXCEPTION_DETAIL
|
| ... Traceback (most recent call last):
|
| ... TypeError: wrong type
|
| ... '''
|
| >>> test = doctest.DocTestFinder().find(f)[0]
|
| >>> doctest.DocTestRunner(verbose=False).run(test)
|
| ... # doctest: +ELLIPSIS
|
| **********************************************************************
|
| File ..., line 3, in f
|
| Failed example:
|
| raise ValueError, 'message' #doctest: +IGNORE_EXCEPTION_DETAIL
|
| Expected:
|
| Traceback (most recent call last):
|
| TypeError: wrong type
|
| Got:
|
| Traceback (most recent call last):
|
| ...
|
| ValueError: message
|
| TestResults(failed=1, attempted=1)
|
|
|
| If an exception is raised but not expected, then it is reported as an
|
| unexpected exception:
|
|
|
| >>> def f(x):
|
| ... r'''
|
| ... >>> 1//0
|
| ... 0
|
| ... '''
|
| >>> test = doctest.DocTestFinder().find(f)[0]
|
| >>> doctest.DocTestRunner(verbose=False).run(test)
|
| ... # doctest: +ELLIPSIS
|
| **********************************************************************
|
| File ..., line 3, in f
|
| Failed example:
|
| 1//0
|
| Exception raised:
|
| Traceback (most recent call last):
|
| ...
|
| ZeroDivisionError: integer division or modulo by zero
|
| TestResults(failed=1, attempted=1)
|
| """
|
| def displayhook(): r"""
|
| Test that changing sys.displayhook doesn't matter for doctest.
|
|
|
| >>> import sys
|
| >>> orig_displayhook = sys.displayhook
|
| >>> def my_displayhook(x):
|
| ... print('hi!')
|
| >>> sys.displayhook = my_displayhook
|
| >>> def f():
|
| ... '''
|
| ... >>> 3
|
| ... 3
|
| ... '''
|
| >>> test = doctest.DocTestFinder().find(f)[0]
|
| >>> r = doctest.DocTestRunner(verbose=False).run(test)
|
| >>> post_displayhook = sys.displayhook
|
|
|
| We need to restore sys.displayhook now, so that we'll be able to test
|
| results.
|
|
|
| >>> sys.displayhook = orig_displayhook
|
|
|
| Ok, now we can check that everything is ok.
|
|
|
| >>> r
|
| TestResults(failed=0, attempted=1)
|
| >>> post_displayhook is my_displayhook
|
| True
|
| """
|
| def optionflags(): r"""
|
| Tests of `DocTestRunner`'s option flag handling.
|
|
|
| Several option flags can be used to customize the behavior of the test
|
| runner. These are defined as module constants in doctest, and passed
|
| to the DocTestRunner constructor (multiple constants should be ORed
|
| together).
|
|
|
| The DONT_ACCEPT_TRUE_FOR_1 flag disables matches between True/False
|
| and 1/0:
|
|
|
| >>> def f(x):
|
| ... '>>> True\n1\n'
|
|
|
| >>> # Without the flag:
|
| >>> test = doctest.DocTestFinder().find(f)[0]
|
| >>> doctest.DocTestRunner(verbose=False).run(test)
|
| TestResults(failed=0, attempted=1)
|
|
|
| >>> # With the flag:
|
| >>> test = doctest.DocTestFinder().find(f)[0]
|
| >>> flags = doctest.DONT_ACCEPT_TRUE_FOR_1
|
| >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
|
| ... # doctest: +ELLIPSIS
|
| **********************************************************************
|
| File ..., line 2, in f
|
| Failed example:
|
| True
|
| Expected:
|
| 1
|
| Got:
|
| True
|
| TestResults(failed=1, attempted=1)
|
|
|
| The DONT_ACCEPT_BLANKLINE flag disables the match between blank lines
|
| and the '<BLANKLINE>' marker:
|
|
|
| >>> def f(x):
|
| ... '>>> print "a\\n\\nb"\na\n<BLANKLINE>\nb\n'
|
|
|
| >>> # Without the flag:
|
| >>> test = doctest.DocTestFinder().find(f)[0]
|
| >>> doctest.DocTestRunner(verbose=False).run(test)
|
| TestResults(failed=0, attempted=1)
|
|
|
| >>> # With the flag:
|
| >>> test = doctest.DocTestFinder().find(f)[0]
|
| >>> flags = doctest.DONT_ACCEPT_BLANKLINE
|
| >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
|
| ... # doctest: +ELLIPSIS
|
| **********************************************************************
|
| File ..., line 2, in f
|
| Failed example:
|
| print "a\n\nb"
|
| Expected:
|
| a
|
| <BLANKLINE>
|
| b
|
| Got:
|
| a
|
| <BLANKLINE>
|
| b
|
| TestResults(failed=1, attempted=1)
|
|
|
| The NORMALIZE_WHITESPACE flag causes all sequences of whitespace to be
|
| treated as equal:
|
|
|
| >>> def f(x):
|
| ... '>>> print 1, 2, 3\n 1 2\n 3'
|
|
|
| >>> # Without the flag:
|
| >>> test = doctest.DocTestFinder().find(f)[0]
|
| >>> doctest.DocTestRunner(verbose=False).run(test)
|
| ... # doctest: +ELLIPSIS
|
| **********************************************************************
|
| File ..., line 2, in f
|
| Failed example:
|
| print 1, 2, 3
|
| Expected:
|
| 1 2
|
| 3
|
| Got:
|
| 1 2 3
|
| TestResults(failed=1, attempted=1)
|
|
|
| >>> # With the flag:
|
| >>> test = doctest.DocTestFinder().find(f)[0]
|
| >>> flags = doctest.NORMALIZE_WHITESPACE
|
| >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
|
| TestResults(failed=0, attempted=1)
|
|
|
| An example from the docs:
|
| >>> print range(20) #doctest: +NORMALIZE_WHITESPACE
|
| [0, 1, 2, 3, 4, 5, 6, 7, 8, 9,
|
| 10, 11, 12, 13, 14, 15, 16, 17, 18, 19]
|
|
|
| The ELLIPSIS flag causes ellipsis marker ("...") in the expected
|
| output to match any substring in the actual output:
|
|
|
| >>> def f(x):
|
| ... '>>> print range(15)\n[0, 1, 2, ..., 14]\n'
|
|
|
| >>> # Without the flag:
|
| >>> test = doctest.DocTestFinder().find(f)[0]
|
| >>> doctest.DocTestRunner(verbose=False).run(test)
|
| ... # doctest: +ELLIPSIS
|
| **********************************************************************
|
| File ..., line 2, in f
|
| Failed example:
|
| print range(15)
|
| Expected:
|
| [0, 1, 2, ..., 14]
|
| Got:
|
| [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14]
|
| TestResults(failed=1, attempted=1)
|
|
|
| >>> # With the flag:
|
| >>> test = doctest.DocTestFinder().find(f)[0]
|
| >>> flags = doctest.ELLIPSIS
|
| >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
|
| TestResults(failed=0, attempted=1)
|
|
|
| ... also matches nothing:
|
|
|
| >>> for i in range(100):
|
| ... print i**2, #doctest: +ELLIPSIS
|
| 0 1...4...9 16 ... 36 49 64 ... 9801
|
|
|
| ... can be surprising; e.g., this test passes:
|
|
|
| >>> for i in range(21): #doctest: +ELLIPSIS
|
| ... print i,
|
| 0 1 2 ...1...2...0
|
|
|
| Examples from the docs:
|
|
|
| >>> print range(20) # doctest:+ELLIPSIS
|
| [0, 1, ..., 18, 19]
|
|
|
| >>> print range(20) # doctest: +ELLIPSIS
|
| ... # doctest: +NORMALIZE_WHITESPACE
|
| [0, 1, ..., 18, 19]
|
|
|
| The SKIP flag causes an example to be skipped entirely. I.e., the
|
| example is not run. It can be useful in contexts where doctest
|
| examples serve as both documentation and test cases, and an example
|
| should be included for documentation purposes, but should not be
|
| checked (e.g., because its output is random, or depends on resources
|
| which would be unavailable.) The SKIP flag can also be used for
|
| 'commenting out' broken examples.
|
|
|
| >>> import unavailable_resource # doctest: +SKIP
|
| >>> unavailable_resource.do_something() # doctest: +SKIP
|
| >>> unavailable_resource.blow_up() # doctest: +SKIP
|
| Traceback (most recent call last):
|
| ...
|
| UncheckedBlowUpError: Nobody checks me.
|
|
|
| >>> import random
|
| >>> print random.random() # doctest: +SKIP
|
| 0.721216923889
|
|
|
| The REPORT_UDIFF flag causes failures that involve multi-line expected
|
| and actual outputs to be displayed using a unified diff:
|
|
|
| >>> def f(x):
|
| ... r'''
|
| ... >>> print '\n'.join('abcdefg')
|
| ... a
|
| ... B
|
| ... c
|
| ... d
|
| ... f
|
| ... g
|
| ... h
|
| ... '''
|
|
|
| >>> # Without the flag:
|
| >>> test = doctest.DocTestFinder().find(f)[0]
|
| >>> doctest.DocTestRunner(verbose=False).run(test)
|
| ... # doctest: +ELLIPSIS
|
| **********************************************************************
|
| File ..., line 3, in f
|
| Failed example:
|
| print '\n'.join('abcdefg')
|
| Expected:
|
| a
|
| B
|
| c
|
| d
|
| f
|
| g
|
| h
|
| Got:
|
| a
|
| b
|
| c
|
| d
|
| e
|
| f
|
| g
|
| TestResults(failed=1, attempted=1)
|
|
|
| >>> # With the flag:
|
| >>> test = doctest.DocTestFinder().find(f)[0]
|
| >>> flags = doctest.REPORT_UDIFF
|
| >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
|
| ... # doctest: +ELLIPSIS
|
| **********************************************************************
|
| File ..., line 3, in f
|
| Failed example:
|
| print '\n'.join('abcdefg')
|
| Differences (unified diff with -expected +actual):
|
| @@ -1,7 +1,7 @@
|
| a
|
| -B
|
| +b
|
| c
|
| d
|
| +e
|
| f
|
| g
|
| -h
|
| TestResults(failed=1, attempted=1)
|
|
|
| The REPORT_CDIFF flag causes failures that involve multi-line expected
|
| and actual outputs to be displayed using a context diff:
|
|
|
| >>> # Reuse f() from the REPORT_UDIFF example, above.
|
| >>> test = doctest.DocTestFinder().find(f)[0]
|
| >>> flags = doctest.REPORT_CDIFF
|
| >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
|
| ... # doctest: +ELLIPSIS
|
| **********************************************************************
|
| File ..., line 3, in f
|
| Failed example:
|
| print '\n'.join('abcdefg')
|
| Differences (context diff with expected followed by actual):
|
| ***************
|
| *** 1,7 ****
|
| a
|
| ! B
|
| c
|
| d
|
| f
|
| g
|
| - h
|
| --- 1,7 ----
|
| a
|
| ! b
|
| c
|
| d
|
| + e
|
| f
|
| g
|
| TestResults(failed=1, attempted=1)
|
|
|
|
|
| The REPORT_NDIFF flag causes failures to use the difflib.Differ algorithm
|
| used by the popular ndiff.py utility. This does intraline difference
|
| marking, as well as interline differences.
|
|
|
| >>> def f(x):
|
| ... r'''
|
| ... >>> print "a b c d e f g h i j k l m"
|
| ... a b c d e f g h i j k 1 m
|
| ... '''
|
| >>> test = doctest.DocTestFinder().find(f)[0]
|
| >>> flags = doctest.REPORT_NDIFF
|
| >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
|
| ... # doctest: +ELLIPSIS
|
| **********************************************************************
|
| File ..., line 3, in f
|
| Failed example:
|
| print "a b c d e f g h i j k l m"
|
| Differences (ndiff with -expected +actual):
|
| - a b c d e f g h i j k 1 m
|
| ? ^
|
| + a b c d e f g h i j k l m
|
| ? + ++ ^
|
| TestResults(failed=1, attempted=1)
|
|
|
| The REPORT_ONLY_FIRST_FAILURE suppresses result output after the first
|
| failing example:
|
|
|
| >>> def f(x):
|
| ... r'''
|
| ... >>> print 1 # first success
|
| ... 1
|
| ... >>> print 2 # first failure
|
| ... 200
|
| ... >>> print 3 # second failure
|
| ... 300
|
| ... >>> print 4 # second success
|
| ... 4
|
| ... >>> print 5 # third failure
|
| ... 500
|
| ... '''
|
| >>> test = doctest.DocTestFinder().find(f)[0]
|
| >>> flags = doctest.REPORT_ONLY_FIRST_FAILURE
|
| >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
|
| ... # doctest: +ELLIPSIS
|
| **********************************************************************
|
| File ..., line 5, in f
|
| Failed example:
|
| print 2 # first failure
|
| Expected:
|
| 200
|
| Got:
|
| 2
|
| TestResults(failed=3, attempted=5)
|
|
|
| However, output from `report_start` is not suppressed:
|
|
|
| >>> doctest.DocTestRunner(verbose=True, optionflags=flags).run(test)
|
| ... # doctest: +ELLIPSIS
|
| Trying:
|
| print 1 # first success
|
| Expecting:
|
| 1
|
| ok
|
| Trying:
|
| print 2 # first failure
|
| Expecting:
|
| 200
|
| **********************************************************************
|
| File ..., line 5, in f
|
| Failed example:
|
| print 2 # first failure
|
| Expected:
|
| 200
|
| Got:
|
| 2
|
| TestResults(failed=3, attempted=5)
|
|
|
| For the purposes of REPORT_ONLY_FIRST_FAILURE, unexpected exceptions
|
| count as failures:
|
|
|
| >>> def f(x):
|
| ... r'''
|
| ... >>> print 1 # first success
|
| ... 1
|
| ... >>> raise ValueError(2) # first failure
|
| ... 200
|
| ... >>> print 3 # second failure
|
| ... 300
|
| ... >>> print 4 # second success
|
| ... 4
|
| ... >>> print 5 # third failure
|
| ... 500
|
| ... '''
|
| >>> test = doctest.DocTestFinder().find(f)[0]
|
| >>> flags = doctest.REPORT_ONLY_FIRST_FAILURE
|
| >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
|
| ... # doctest: +ELLIPSIS
|
| **********************************************************************
|
| File ..., line 5, in f
|
| Failed example:
|
| raise ValueError(2) # first failure
|
| Exception raised:
|
| ...
|
| ValueError: 2
|
| TestResults(failed=3, attempted=5)
|
|
|
| New option flags can also be registered, via register_optionflag(). Here
|
| we reach into doctest's internals a bit.
|
|
|
| >>> unlikely = "UNLIKELY_OPTION_NAME"
|
| >>> unlikely in doctest.OPTIONFLAGS_BY_NAME
|
| False
|
| >>> new_flag_value = doctest.register_optionflag(unlikely)
|
| >>> unlikely in doctest.OPTIONFLAGS_BY_NAME
|
| True
|
|
|
| Before 2.4.4/2.5, registering a name more than once erroneously created
|
| more than one flag value. Here we verify that's fixed:
|
|
|
| >>> redundant_flag_value = doctest.register_optionflag(unlikely)
|
| >>> redundant_flag_value == new_flag_value
|
| True
|
|
|
| Clean up.
|
| >>> del doctest.OPTIONFLAGS_BY_NAME[unlikely]
|
|
|
| """
|
|
|
| def option_directives(): r"""
|
| Tests of `DocTestRunner`'s option directive mechanism.
|
|
|
| Option directives can be used to turn option flags on or off for a
|
| single example. To turn an option on for an example, follow that
|
| example with a comment of the form ``# doctest: +OPTION``:
|
|
|
| >>> def f(x): r'''
|
| ... >>> print range(10) # should fail: no ellipsis
|
| ... [0, 1, ..., 9]
|
| ...
|
| ... >>> print range(10) # doctest: +ELLIPSIS
|
| ... [0, 1, ..., 9]
|
| ... '''
|
| >>> test = doctest.DocTestFinder().find(f)[0]
|
| >>> doctest.DocTestRunner(verbose=False).run(test)
|
| ... # doctest: +ELLIPSIS
|
| **********************************************************************
|
| File ..., line 2, in f
|
| Failed example:
|
| print range(10) # should fail: no ellipsis
|
| Expected:
|
| [0, 1, ..., 9]
|
| Got:
|
| [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
|
| TestResults(failed=1, attempted=2)
|
|
|
| To turn an option off for an example, follow that example with a
|
| comment of the form ``# doctest: -OPTION``:
|
|
|
| >>> def f(x): r'''
|
| ... >>> print range(10)
|
| ... [0, 1, ..., 9]
|
| ...
|
| ... >>> # should fail: no ellipsis
|
| ... >>> print range(10) # doctest: -ELLIPSIS
|
| ... [0, 1, ..., 9]
|
| ... '''
|
| >>> test = doctest.DocTestFinder().find(f)[0]
|
| >>> doctest.DocTestRunner(verbose=False,
|
| ... optionflags=doctest.ELLIPSIS).run(test)
|
| ... # doctest: +ELLIPSIS
|
| **********************************************************************
|
| File ..., line 6, in f
|
| Failed example:
|
| print range(10) # doctest: -ELLIPSIS
|
| Expected:
|
| [0, 1, ..., 9]
|
| Got:
|
| [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
|
| TestResults(failed=1, attempted=2)
|
|
|
| Option directives affect only the example that they appear with; they
|
| do not change the options for surrounding examples:
|
|
|
| >>> def f(x): r'''
|
| ... >>> print range(10) # Should fail: no ellipsis
|
| ... [0, 1, ..., 9]
|
| ...
|
| ... >>> print range(10) # doctest: +ELLIPSIS
|
| ... [0, 1, ..., 9]
|
| ...
|
| ... >>> print range(10) # Should fail: no ellipsis
|
| ... [0, 1, ..., 9]
|
| ... '''
|
| >>> test = doctest.DocTestFinder().find(f)[0]
|
| >>> doctest.DocTestRunner(verbose=False).run(test)
|
| ... # doctest: +ELLIPSIS
|
| **********************************************************************
|
| File ..., line 2, in f
|
| Failed example:
|
| print range(10) # Should fail: no ellipsis
|
| Expected:
|
| [0, 1, ..., 9]
|
| Got:
|
| [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
|
| **********************************************************************
|
| File ..., line 8, in f
|
| Failed example:
|
| print range(10) # Should fail: no ellipsis
|
| Expected:
|
| [0, 1, ..., 9]
|
| Got:
|
| [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
|
| TestResults(failed=2, attempted=3)
|
|
|
| Multiple options may be modified by a single option directive. They
|
| may be separated by whitespace, commas, or both:
|
|
|
| >>> def f(x): r'''
|
| ... >>> print range(10) # Should fail
|
| ... [0, 1, ..., 9]
|
| ... >>> print range(10) # Should succeed
|
| ... ... # doctest: +ELLIPSIS +NORMALIZE_WHITESPACE
|
| ... [0, 1, ..., 9]
|
| ... '''
|
| >>> test = doctest.DocTestFinder().find(f)[0]
|
| >>> doctest.DocTestRunner(verbose=False).run(test)
|
| ... # doctest: +ELLIPSIS
|
| **********************************************************************
|
| File ..., line 2, in f
|
| Failed example:
|
| print range(10) # Should fail
|
| Expected:
|
| [0, 1, ..., 9]
|
| Got:
|
| [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
|
| TestResults(failed=1, attempted=2)
|
|
|
| >>> def f(x): r'''
|
| ... >>> print range(10) # Should fail
|
| ... [0, 1, ..., 9]
|
| ... >>> print range(10) # Should succeed
|
| ... ... # doctest: +ELLIPSIS,+NORMALIZE_WHITESPACE
|
| ... [0, 1, ..., 9]
|
| ... '''
|
| >>> test = doctest.DocTestFinder().find(f)[0]
|
| >>> doctest.DocTestRunner(verbose=False).run(test)
|
| ... # doctest: +ELLIPSIS
|
| **********************************************************************
|
| File ..., line 2, in f
|
| Failed example:
|
| print range(10) # Should fail
|
| Expected:
|
| [0, 1, ..., 9]
|
| Got:
|
| [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
|
| TestResults(failed=1, attempted=2)
|
|
|
| >>> def f(x): r'''
|
| ... >>> print range(10) # Should fail
|
| ... [0, 1, ..., 9]
|
| ... >>> print range(10) # Should succeed
|
| ... ... # doctest: +ELLIPSIS, +NORMALIZE_WHITESPACE
|
| ... [0, 1, ..., 9]
|
| ... '''
|
| >>> test = doctest.DocTestFinder().find(f)[0]
|
| >>> doctest.DocTestRunner(verbose=False).run(test)
|
| ... # doctest: +ELLIPSIS
|
| **********************************************************************
|
| File ..., line 2, in f
|
| Failed example:
|
| print range(10) # Should fail
|
| Expected:
|
| [0, 1, ..., 9]
|
| Got:
|
| [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
|
| TestResults(failed=1, attempted=2)
|
|
|
| The option directive may be put on the line following the source, as
|
| long as a continuation prompt is used:
|
|
|
| >>> def f(x): r'''
|
| ... >>> print range(10)
|
| ... ... # doctest: +ELLIPSIS
|
| ... [0, 1, ..., 9]
|
| ... '''
|
| >>> test = doctest.DocTestFinder().find(f)[0]
|
| >>> doctest.DocTestRunner(verbose=False).run(test)
|
| TestResults(failed=0, attempted=1)
|
|
|
| For examples with multi-line source, the option directive may appear
|
| at the end of any line:
|
|
|
| >>> def f(x): r'''
|
| ... >>> for x in range(10): # doctest: +ELLIPSIS
|
| ... ... print x,
|
| ... 0 1 2 ... 9
|
| ...
|
| ... >>> for x in range(10):
|
| ... ... print x, # doctest: +ELLIPSIS
|
| ... 0 1 2 ... 9
|
| ... '''
|
| >>> test = doctest.DocTestFinder().find(f)[0]
|
| >>> doctest.DocTestRunner(verbose=False).run(test)
|
| TestResults(failed=0, attempted=2)
|
|
|
| If more than one line of an example with multi-line source has an
|
| option directive, then they are combined:
|
|
|
| >>> def f(x): r'''
|
| ... Should fail (option directive not on the last line):
|
| ... >>> for x in range(10): # doctest: +ELLIPSIS
|
| ... ... print x, # doctest: +NORMALIZE_WHITESPACE
|
| ... 0 1 2...9
|
| ... '''
|
| >>> test = doctest.DocTestFinder().find(f)[0]
|
| >>> doctest.DocTestRunner(verbose=False).run(test)
|
| TestResults(failed=0, attempted=1)
|
|
|
| It is an error to have a comment of the form ``# doctest:`` that is
|
| *not* followed by words of the form ``+OPTION`` or ``-OPTION``, where
|
| ``OPTION`` is an option that has been registered with
|
| `register_option`:
|
|
|
| >>> # Error: Option not registered
|
| >>> s = '>>> print 12 #doctest: +BADOPTION'
|
| >>> test = doctest.DocTestParser().get_doctest(s, {}, 's', 's.py', 0)
|
| Traceback (most recent call last):
|
| ValueError: line 1 of the doctest for s has an invalid option: '+BADOPTION'
|
|
|
| >>> # Error: No + or - prefix
|
| >>> s = '>>> print 12 #doctest: ELLIPSIS'
|
| >>> test = doctest.DocTestParser().get_doctest(s, {}, 's', 's.py', 0)
|
| Traceback (most recent call last):
|
| ValueError: line 1 of the doctest for s has an invalid option: 'ELLIPSIS'
|
|
|
| It is an error to use an option directive on a line that contains no
|
| source:
|
|
|
| >>> s = '>>> # doctest: +ELLIPSIS'
|
| >>> test = doctest.DocTestParser().get_doctest(s, {}, 's', 's.py', 0)
|
| Traceback (most recent call last):
|
| ValueError: line 0 of the doctest for s has an option directive on a line with no example: '# doctest: +ELLIPSIS'
|
|
|
| """
|
|
|
| def test_unicode_output(self): r"""
|
|
|
| Check that unicode output works:
|
|
|
| >>> u'\xe9'
|
| u'\xe9'
|
|
|
| If we return unicode, SpoofOut's buf variable becomes automagically
|
| converted to unicode. This means all subsequent output becomes converted
|
| to unicode, and if the output contains non-ascii characters that failed.
|
| It used to be that this state change carried on between tests, meaning
|
| tests would fail if unicode has been output previously in the testrun.
|
| This test tests that this is no longer so:
|
|
|
| >>> print u'abc'
|
| abc
|
|
|
| And then return a string with non-ascii characters:
|
|
|
| >>> print u'\xe9'.encode('utf-8')
|
| é
|
|
|
| """
|
|
|
|
|
| def test_testsource(): r"""
|
| Unit tests for `testsource()`.
|
|
|
| The testsource() function takes a module and a name, finds the (first)
|
| test with that name in that module, and converts it to a script. The
|
| example code is converted to regular Python code. The surrounding
|
| words and expected output are converted to comments:
|
|
|
| >>> import test.test_doctest
|
| >>> name = 'test.test_doctest.sample_func'
|
| >>> print doctest.testsource(test.test_doctest, name)
|
| # Blah blah
|
| #
|
| print sample_func(22)
|
| # Expected:
|
| ## 44
|
| #
|
| # Yee ha!
|
| <BLANKLINE>
|
|
|
| >>> name = 'test.test_doctest.SampleNewStyleClass'
|
| >>> print doctest.testsource(test.test_doctest, name)
|
| print '1\n2\n3'
|
| # Expected:
|
| ## 1
|
| ## 2
|
| ## 3
|
| <BLANKLINE>
|
|
|
| >>> name = 'test.test_doctest.SampleClass.a_classmethod'
|
| >>> print doctest.testsource(test.test_doctest, name)
|
| print SampleClass.a_classmethod(10)
|
| # Expected:
|
| ## 12
|
| print SampleClass(0).a_classmethod(10)
|
| # Expected:
|
| ## 12
|
| <BLANKLINE>
|
| """
|
|
|
| def test_debug(): r"""
|
|
|
| Create a docstring that we want to debug:
|
|
|
| >>> s = '''
|
| ... >>> x = 12
|
| ... >>> print x
|
| ... 12
|
| ... '''
|
|
|
| Create some fake stdin input, to feed to the debugger:
|
|
|
| >>> import tempfile
|
| >>> real_stdin = sys.stdin
|
| >>> sys.stdin = _FakeInput(['next', 'print x', 'continue'])
|
|
|
| Run the debugger on the docstring, and then restore sys.stdin.
|
|
|
| >>> try: doctest.debug_src(s)
|
| ... finally: sys.stdin = real_stdin
|
| > <string>(1)<module>()
|
| (Pdb) next
|
| 12
|
| --Return--
|
| > <string>(1)<module>()->None
|
| (Pdb) print x
|
| 12
|
| (Pdb) continue
|
|
|
| """
|
|
|
| def test_pdb_set_trace():
|
| """Using pdb.set_trace from a doctest.
|
|
|
| You can use pdb.set_trace from a doctest. To do so, you must
|
| retrieve the set_trace function from the pdb module at the time
|
| you use it. The doctest module changes sys.stdout so that it can
|
| capture program output. It also temporarily replaces pdb.set_trace
|
| with a version that restores stdout. This is necessary for you to
|
| see debugger output.
|
|
|
| >>> doc = '''
|
| ... >>> x = 42
|
| ... >>> raise Exception('clé')
|
| ... Traceback (most recent call last):
|
| ... Exception: clé
|
| ... >>> import pdb; pdb.set_trace()
|
| ... '''
|
| >>> parser = doctest.DocTestParser()
|
| >>> test = parser.get_doctest(doc, {}, "foo-bär@baz", "foo-bär@baz.py", 0)
|
| >>> runner = doctest.DocTestRunner(verbose=False)
|
|
|
| To demonstrate this, we'll create a fake standard input that
|
| captures our debugger input:
|
|
|
| >>> import tempfile
|
| >>> real_stdin = sys.stdin
|
| >>> sys.stdin = _FakeInput([
|
| ... 'print x', # print data defined by the example
|
| ... 'continue', # stop debugging
|
| ... ''])
|
|
|
| >>> try: runner.run(test)
|
| ... finally: sys.stdin = real_stdin
|
| --Return--
|
| > <doctest foo-bär@baz[2]>(1)<module>()->None
|
| -> import pdb; pdb.set_trace()
|
| (Pdb) print x
|
| 42
|
| (Pdb) continue
|
| TestResults(failed=0, attempted=3)
|
|
|
| You can also put pdb.set_trace in a function called from a test:
|
|
|
| >>> def calls_set_trace():
|
| ... y=2
|
| ... import pdb; pdb.set_trace()
|
|
|
| >>> doc = '''
|
| ... >>> x=1
|
| ... >>> calls_set_trace()
|
| ... '''
|
| >>> test = parser.get_doctest(doc, globals(), "foo-bär@baz", "foo-bär@baz.py", 0)
|
| >>> real_stdin = sys.stdin
|
| >>> sys.stdin = _FakeInput([
|
| ... 'print y', # print data defined in the function
|
| ... 'up', # out of function
|
| ... 'print x', # print data defined by the example
|
| ... 'continue', # stop debugging
|
| ... ''])
|
|
|
| >>> try:
|
| ... runner.run(test)
|
| ... finally:
|
| ... sys.stdin = real_stdin
|
| --Return--
|
| > <doctest test.test_doctest.test_pdb_set_trace[8]>(3)calls_set_trace()->None
|
| -> import pdb; pdb.set_trace()
|
| (Pdb) print y
|
| 2
|
| (Pdb) up
|
| > <doctest foo-bär@baz[1]>(1)<module>()
|
| -> calls_set_trace()
|
| (Pdb) print x
|
| 1
|
| (Pdb) continue
|
| TestResults(failed=0, attempted=2)
|
|
|
| During interactive debugging, source code is shown, even for
|
| doctest examples:
|
|
|
| >>> doc = '''
|
| ... >>> def f(x):
|
| ... ... g(x*2)
|
| ... >>> def g(x):
|
| ... ... print x+3
|
| ... ... import pdb; pdb.set_trace()
|
| ... >>> f(3)
|
| ... '''
|
| >>> test = parser.get_doctest(doc, globals(), "foo-bär@baz", "foo-bär@baz.py", 0)
|
| >>> real_stdin = sys.stdin
|
| >>> sys.stdin = _FakeInput([
|
| ... 'list', # list source from example 2
|
| ... 'next', # return from g()
|
| ... 'list', # list source from example 1
|
| ... 'next', # return from f()
|
| ... 'list', # list source from example 3
|
| ... 'continue', # stop debugging
|
| ... ''])
|
| >>> try: runner.run(test)
|
| ... finally: sys.stdin = real_stdin
|
| ... # doctest: +NORMALIZE_WHITESPACE
|
| --Return--
|
| > <doctest foo-bär@baz[1]>(3)g()->None
|
| -> import pdb; pdb.set_trace()
|
| (Pdb) list
|
| 1 def g(x):
|
| 2 print x+3
|
| 3 -> import pdb; pdb.set_trace()
|
| [EOF]
|
| (Pdb) next
|
| --Return--
|
| > <doctest foo-bär@baz[0]>(2)f()->None
|
| -> g(x*2)
|
| (Pdb) list
|
| 1 def f(x):
|
| 2 -> g(x*2)
|
| [EOF]
|
| (Pdb) next
|
| --Return--
|
| > <doctest foo-bär@baz[2]>(1)<module>()->None
|
| -> f(3)
|
| (Pdb) list
|
| 1 -> f(3)
|
| [EOF]
|
| (Pdb) continue
|
| **********************************************************************
|
| File "foo-bär@baz.py", line 7, in foo-bär@baz
|
| Failed example:
|
| f(3)
|
| Expected nothing
|
| Got:
|
| 9
|
| TestResults(failed=1, attempted=3)
|
| """
|
|
|
| def test_pdb_set_trace_nested():
|
| """This illustrates more-demanding use of set_trace with nested functions.
|
|
|
| >>> class C(object):
|
| ... def calls_set_trace(self):
|
| ... y = 1
|
| ... import pdb; pdb.set_trace()
|
| ... self.f1()
|
| ... y = 2
|
| ... def f1(self):
|
| ... x = 1
|
| ... self.f2()
|
| ... x = 2
|
| ... def f2(self):
|
| ... z = 1
|
| ... z = 2
|
|
|
| >>> calls_set_trace = C().calls_set_trace
|
|
|
| >>> doc = '''
|
| ... >>> a = 1
|
| ... >>> calls_set_trace()
|
| ... '''
|
| >>> parser = doctest.DocTestParser()
|
| >>> runner = doctest.DocTestRunner(verbose=False)
|
| >>> test = parser.get_doctest(doc, globals(), "foo-bär@baz", "foo-bär@baz.py", 0)
|
| >>> real_stdin = sys.stdin
|
| >>> sys.stdin = _FakeInput([
|
| ... 'print y', # print data defined in the function
|
| ... 'step', 'step', 'step', 'step', 'step', 'step', 'print z',
|
| ... 'up', 'print x',
|
| ... 'up', 'print y',
|
| ... 'up', 'print foo',
|
| ... 'continue', # stop debugging
|
| ... ''])
|
|
|
| >>> try:
|
| ... runner.run(test)
|
| ... finally:
|
| ... sys.stdin = real_stdin
|
| > <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(5)calls_set_trace()
|
| -> self.f1()
|
| (Pdb) print y
|
| 1
|
| (Pdb) step
|
| --Call--
|
| > <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(7)f1()
|
| -> def f1(self):
|
| (Pdb) step
|
| > <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(8)f1()
|
| -> x = 1
|
| (Pdb) step
|
| > <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(9)f1()
|
| -> self.f2()
|
| (Pdb) step
|
| --Call--
|
| > <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(11)f2()
|
| -> def f2(self):
|
| (Pdb) step
|
| > <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(12)f2()
|
| -> z = 1
|
| (Pdb) step
|
| > <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(13)f2()
|
| -> z = 2
|
| (Pdb) print z
|
| 1
|
| (Pdb) up
|
| > <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(9)f1()
|
| -> self.f2()
|
| (Pdb) print x
|
| 1
|
| (Pdb) up
|
| > <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(5)calls_set_trace()
|
| -> self.f1()
|
| (Pdb) print y
|
| 1
|
| (Pdb) up
|
| > <doctest foo-bär@baz[1]>(1)<module>()
|
| -> calls_set_trace()
|
| (Pdb) print foo
|
| *** NameError: name 'foo' is not defined
|
| (Pdb) continue
|
| TestResults(failed=0, attempted=2)
|
| """
|
|
|
| def test_DocTestSuite():
|
| """DocTestSuite creates a unittest test suite from a doctest.
|
|
|
| We create a Suite by providing a module. A module can be provided
|
| by passing a module object:
|
|
|
| >>> import unittest
|
| >>> import test.sample_doctest
|
| >>> suite = doctest.DocTestSuite(test.sample_doctest)
|
| >>> suite.run(unittest.TestResult())
|
| <unittest.result.TestResult run=9 errors=0 failures=4>
|
|
|
| We can also supply the module by name:
|
|
|
| >>> suite = doctest.DocTestSuite('test.sample_doctest')
|
| >>> suite.run(unittest.TestResult())
|
| <unittest.result.TestResult run=9 errors=0 failures=4>
|
|
|
| We can use the current module:
|
|
|
| >>> suite = test.sample_doctest.test_suite()
|
| >>> suite.run(unittest.TestResult())
|
| <unittest.result.TestResult run=9 errors=0 failures=4>
|
|
|
| We can supply global variables. If we pass globs, they will be
|
| used instead of the module globals. Here we'll pass an empty
|
| globals, triggering an extra error:
|
|
|
| >>> suite = doctest.DocTestSuite('test.sample_doctest', globs={})
|
| >>> suite.run(unittest.TestResult())
|
| <unittest.result.TestResult run=9 errors=0 failures=5>
|
|
|
| Alternatively, we can provide extra globals. Here we'll make an
|
| error go away by providing an extra global variable:
|
|
|
| >>> suite = doctest.DocTestSuite('test.sample_doctest',
|
| ... extraglobs={'y': 1})
|
| >>> suite.run(unittest.TestResult())
|
| <unittest.result.TestResult run=9 errors=0 failures=3>
|
|
|
| You can pass option flags. Here we'll cause an extra error
|
| by disabling the blank-line feature:
|
|
|
| >>> suite = doctest.DocTestSuite('test.sample_doctest',
|
| ... optionflags=doctest.DONT_ACCEPT_BLANKLINE)
|
| >>> suite.run(unittest.TestResult())
|
| <unittest.result.TestResult run=9 errors=0 failures=5>
|
|
|
| You can supply setUp and tearDown functions:
|
|
|
| >>> def setUp(t):
|
| ... import test.test_doctest
|
| ... test.test_doctest.sillySetup = True
|
|
|
| >>> def tearDown(t):
|
| ... import test.test_doctest
|
| ... del test.test_doctest.sillySetup
|
|
|
| Here, we installed a silly variable that the test expects:
|
|
|
| >>> suite = doctest.DocTestSuite('test.sample_doctest',
|
| ... setUp=setUp, tearDown=tearDown)
|
| >>> suite.run(unittest.TestResult())
|
| <unittest.result.TestResult run=9 errors=0 failures=3>
|
|
|
| But the tearDown restores sanity:
|
|
|
| >>> import test.test_doctest
|
| >>> test.test_doctest.sillySetup
|
| Traceback (most recent call last):
|
| ...
|
| AttributeError: 'module' object has no attribute 'sillySetup'
|
|
|
| The setUp and tearDown funtions are passed test objects. Here
|
| we'll use the setUp function to supply the missing variable y:
|
|
|
| >>> def setUp(test):
|
| ... test.globs['y'] = 1
|
|
|
| >>> suite = doctest.DocTestSuite('test.sample_doctest', setUp=setUp)
|
| >>> suite.run(unittest.TestResult())
|
| <unittest.result.TestResult run=9 errors=0 failures=3>
|
|
|
| Here, we didn't need to use a tearDown function because we
|
| modified the test globals, which are a copy of the
|
| sample_doctest module dictionary. The test globals are
|
| automatically cleared for us after a test.
|
| """
|
|
|
| def test_DocFileSuite():
|
| """We can test tests found in text files using a DocFileSuite.
|
|
|
| We create a suite by providing the names of one or more text
|
| files that include examples:
|
|
|
| >>> import unittest
|
| >>> suite = doctest.DocFileSuite('test_doctest.txt',
|
| ... 'test_doctest2.txt',
|
| ... 'test_doctest4.txt')
|
| >>> suite.run(unittest.TestResult())
|
| <unittest.result.TestResult run=3 errors=0 failures=3>
|
|
|
| The test files are looked for in the directory containing the
|
| calling module. A package keyword argument can be provided to
|
| specify a different relative location.
|
|
|
| >>> import unittest
|
| >>> suite = doctest.DocFileSuite('test_doctest.txt',
|
| ... 'test_doctest2.txt',
|
| ... 'test_doctest4.txt',
|
| ... package='test')
|
| >>> suite.run(unittest.TestResult())
|
| <unittest.result.TestResult run=3 errors=0 failures=3>
|
|
|
| Support for using a package's __loader__.get_data() is also
|
| provided.
|
|
|
| >>> import unittest, pkgutil, test
|
| >>> added_loader = False
|
| >>> if not hasattr(test, '__loader__'):
|
| ... test.__loader__ = pkgutil.get_loader(test)
|
| ... added_loader = True
|
| >>> try:
|
| ... suite = doctest.DocFileSuite('test_doctest.txt',
|
| ... 'test_doctest2.txt',
|
| ... 'test_doctest4.txt',
|
| ... package='test')
|
| ... suite.run(unittest.TestResult())
|
| ... finally:
|
| ... if added_loader:
|
| ... del test.__loader__
|
| <unittest.result.TestResult run=3 errors=0 failures=3>
|
|
|
| '/' should be used as a path separator. It will be converted
|
| to a native separator at run time:
|
|
|
| >>> suite = doctest.DocFileSuite('../test/test_doctest.txt')
|
| >>> suite.run(unittest.TestResult())
|
| <unittest.result.TestResult run=1 errors=0 failures=1>
|
|
|
| If DocFileSuite is used from an interactive session, then files
|
| are resolved relative to the directory of sys.argv[0]:
|
|
|
| >>> import types, os.path, test.test_doctest
|
| >>> save_argv = sys.argv
|
| >>> sys.argv = [test.test_doctest.__file__]
|
| >>> suite = doctest.DocFileSuite('test_doctest.txt',
|
| ... package=types.ModuleType('__main__'))
|
| >>> sys.argv = save_argv
|
|
|
| By setting `module_relative=False`, os-specific paths may be
|
| used (including absolute paths and paths relative to the
|
| working directory):
|
|
|
| >>> # Get the absolute path of the test package.
|
| >>> test_doctest_path = os.path.abspath(test.test_doctest.__file__)
|
| >>> test_pkg_path = os.path.split(test_doctest_path)[0]
|
|
|
| >>> # Use it to find the absolute path of test_doctest.txt.
|
| >>> test_file = os.path.join(test_pkg_path, 'test_doctest.txt')
|
|
|
| >>> suite = doctest.DocFileSuite(test_file, module_relative=False)
|
| >>> suite.run(unittest.TestResult())
|
| <unittest.result.TestResult run=1 errors=0 failures=1>
|
|
|
| It is an error to specify `package` when `module_relative=False`:
|
|
|
| >>> suite = doctest.DocFileSuite(test_file, module_relative=False,
|
| ... package='test')
|
| Traceback (most recent call last):
|
| ValueError: Package may only be specified for module-relative paths.
|
|
|
| You can specify initial global variables:
|
|
|
| >>> suite = doctest.DocFileSuite('test_doctest.txt',
|
| ... 'test_doctest2.txt',
|
| ... 'test_doctest4.txt',
|
| ... globs={'favorite_color': 'blue'})
|
| >>> suite.run(unittest.TestResult())
|
| <unittest.result.TestResult run=3 errors=0 failures=2>
|
|
|
| In this case, we supplied a missing favorite color. You can
|
| provide doctest options:
|
|
|
| >>> suite = doctest.DocFileSuite('test_doctest.txt',
|
| ... 'test_doctest2.txt',
|
| ... 'test_doctest4.txt',
|
| ... optionflags=doctest.DONT_ACCEPT_BLANKLINE,
|
| ... globs={'favorite_color': 'blue'})
|
| >>> suite.run(unittest.TestResult())
|
| <unittest.result.TestResult run=3 errors=0 failures=3>
|
|
|
| And, you can provide setUp and tearDown functions:
|
|
|
| >>> def setUp(t):
|
| ... import test.test_doctest
|
| ... test.test_doctest.sillySetup = True
|
|
|
| >>> def tearDown(t):
|
| ... import test.test_doctest
|
| ... del test.test_doctest.sillySetup
|
|
|
| Here, we installed a silly variable that the test expects:
|
|
|
| >>> suite = doctest.DocFileSuite('test_doctest.txt',
|
| ... 'test_doctest2.txt',
|
| ... 'test_doctest4.txt',
|
| ... setUp=setUp, tearDown=tearDown)
|
| >>> suite.run(unittest.TestResult())
|
| <unittest.result.TestResult run=3 errors=0 failures=2>
|
|
|
| But the tearDown restores sanity:
|
|
|
| >>> import test.test_doctest
|
| >>> test.test_doctest.sillySetup
|
| Traceback (most recent call last):
|
| ...
|
| AttributeError: 'module' object has no attribute 'sillySetup'
|
|
|
| The setUp and tearDown funtions are passed test objects.
|
| Here, we'll use a setUp function to set the favorite color in
|
| test_doctest.txt:
|
|
|
| >>> def setUp(test):
|
| ... test.globs['favorite_color'] = 'blue'
|
|
|
| >>> suite = doctest.DocFileSuite('test_doctest.txt', setUp=setUp)
|
| >>> suite.run(unittest.TestResult())
|
| <unittest.result.TestResult run=1 errors=0 failures=0>
|
|
|
| Here, we didn't need to use a tearDown function because we
|
| modified the test globals. The test globals are
|
| automatically cleared for us after a test.
|
|
|
| Tests in a file run using `DocFileSuite` can also access the
|
| `__file__` global, which is set to the name of the file
|
| containing the tests:
|
|
|
| >>> suite = doctest.DocFileSuite('test_doctest3.txt')
|
| >>> suite.run(unittest.TestResult())
|
| <unittest.result.TestResult run=1 errors=0 failures=0>
|
|
|
| If the tests contain non-ASCII characters, we have to specify which
|
| encoding the file is encoded with. We do so by using the `encoding`
|
| parameter:
|
|
|
| >>> suite = doctest.DocFileSuite('test_doctest.txt',
|
| ... 'test_doctest2.txt',
|
| ... 'test_doctest4.txt',
|
| ... encoding='utf-8')
|
| >>> suite.run(unittest.TestResult())
|
| <unittest.result.TestResult run=3 errors=0 failures=2>
|
|
|
| """
|
|
|
| def test_trailing_space_in_test():
|
| """
|
| Trailing spaces in expected output are significant:
|
|
|
| >>> x, y = 'foo', ''
|
| >>> print x, y
|
| foo \n
|
| """
|
|
|
|
|
| def test_unittest_reportflags():
|
| """Default unittest reporting flags can be set to control reporting
|
|
|
| Here, we'll set the REPORT_ONLY_FIRST_FAILURE option so we see
|
| only the first failure of each test. First, we'll look at the
|
| output without the flag. The file test_doctest.txt file has two
|
| tests. They both fail if blank lines are disabled:
|
|
|
| >>> suite = doctest.DocFileSuite('test_doctest.txt',
|
| ... optionflags=doctest.DONT_ACCEPT_BLANKLINE)
|
| >>> import unittest
|
| >>> result = suite.run(unittest.TestResult())
|
| >>> print result.failures[0][1] # doctest: +ELLIPSIS
|
| Traceback ...
|
| Failed example:
|
| favorite_color
|
| ...
|
| Failed example:
|
| if 1:
|
| ...
|
|
|
| Note that we see both failures displayed.
|
|
|
| >>> old = doctest.set_unittest_reportflags(
|
| ... doctest.REPORT_ONLY_FIRST_FAILURE)
|
|
|
| Now, when we run the test:
|
|
|
| >>> result = suite.run(unittest.TestResult())
|
| >>> print result.failures[0][1] # doctest: +ELLIPSIS
|
| Traceback ...
|
| Failed example:
|
| favorite_color
|
| Exception raised:
|
| ...
|
| NameError: name 'favorite_color' is not defined
|
| <BLANKLINE>
|
| <BLANKLINE>
|
|
|
| We get only the first failure.
|
|
|
| If we give any reporting options when we set up the tests,
|
| however:
|
|
|
| >>> suite = doctest.DocFileSuite('test_doctest.txt',
|
| ... optionflags=doctest.DONT_ACCEPT_BLANKLINE | doctest.REPORT_NDIFF)
|
|
|
| Then the default eporting options are ignored:
|
|
|
| >>> result = suite.run(unittest.TestResult())
|
| >>> print result.failures[0][1] # doctest: +ELLIPSIS
|
| Traceback ...
|
| Failed example:
|
| favorite_color
|
| ...
|
| Failed example:
|
| if 1:
|
| print 'a'
|
| print
|
| print 'b'
|
| Differences (ndiff with -expected +actual):
|
| a
|
| - <BLANKLINE>
|
| +
|
| b
|
| <BLANKLINE>
|
| <BLANKLINE>
|
|
|
|
|
| Test runners can restore the formatting flags after they run:
|
|
|
| >>> ignored = doctest.set_unittest_reportflags(old)
|
|
|
| """
|
|
|
| def test_testfile(): r"""
|
| Tests for the `testfile()` function. This function runs all the
|
| doctest examples in a given file. In its simple invokation, it is
|
| called with the name of a file, which is taken to be relative to the
|
| calling module. The return value is (#failures, #tests).
|
|
|
| We don't want `-v` in sys.argv for these tests.
|
|
|
| >>> save_argv = sys.argv
|
| >>> if '-v' in sys.argv:
|
| ... sys.argv = [arg for arg in save_argv if arg != '-v']
|
|
|
|
|
| >>> doctest.testfile('test_doctest.txt') # doctest: +ELLIPSIS
|
| **********************************************************************
|
| File "...", line 6, in test_doctest.txt
|
| Failed example:
|
| favorite_color
|
| Exception raised:
|
| ...
|
| NameError: name 'favorite_color' is not defined
|
| **********************************************************************
|
| 1 items had failures:
|
| 1 of 2 in test_doctest.txt
|
| ***Test Failed*** 1 failures.
|
| TestResults(failed=1, attempted=2)
|
| >>> doctest.master = None # Reset master.
|
|
|
| (Note: we'll be clearing doctest.master after each call to
|
| `doctest.testfile`, to suppress warnings about multiple tests with the
|
| same name.)
|
|
|
| Globals may be specified with the `globs` and `extraglobs` parameters:
|
|
|
| >>> globs = {'favorite_color': 'blue'}
|
| >>> doctest.testfile('test_doctest.txt', globs=globs)
|
| TestResults(failed=0, attempted=2)
|
| >>> doctest.master = None # Reset master.
|
|
|
| >>> extraglobs = {'favorite_color': 'red'}
|
| >>> doctest.testfile('test_doctest.txt', globs=globs,
|
| ... extraglobs=extraglobs) # doctest: +ELLIPSIS
|
| **********************************************************************
|
| File "...", line 6, in test_doctest.txt
|
| Failed example:
|
| favorite_color
|
| Expected:
|
| 'blue'
|
| Got:
|
| 'red'
|
| **********************************************************************
|
| 1 items had failures:
|
| 1 of 2 in test_doctest.txt
|
| ***Test Failed*** 1 failures.
|
| TestResults(failed=1, attempted=2)
|
| >>> doctest.master = None # Reset master.
|
|
|
| The file may be made relative to a given module or package, using the
|
| optional `module_relative` parameter:
|
|
|
| >>> doctest.testfile('test_doctest.txt', globs=globs,
|
| ... module_relative='test')
|
| TestResults(failed=0, attempted=2)
|
| >>> doctest.master = None # Reset master.
|
|
|
| Verbosity can be increased with the optional `verbose` parameter:
|
|
|
| >>> doctest.testfile('test_doctest.txt', globs=globs, verbose=True)
|
| Trying:
|
| favorite_color
|
| Expecting:
|
| 'blue'
|
| ok
|
| Trying:
|
| if 1:
|
| print 'a'
|
| print
|
| print 'b'
|
| Expecting:
|
| a
|
| <BLANKLINE>
|
| b
|
| ok
|
| 1 items passed all tests:
|
| 2 tests in test_doctest.txt
|
| 2 tests in 1 items.
|
| 2 passed and 0 failed.
|
| Test passed.
|
| TestResults(failed=0, attempted=2)
|
| >>> doctest.master = None # Reset master.
|
|
|
| The name of the test may be specified with the optional `name`
|
| parameter:
|
|
|
| >>> doctest.testfile('test_doctest.txt', name='newname')
|
| ... # doctest: +ELLIPSIS
|
| **********************************************************************
|
| File "...", line 6, in newname
|
| ...
|
| TestResults(failed=1, attempted=2)
|
| >>> doctest.master = None # Reset master.
|
|
|
| The summary report may be suppressed with the optional `report`
|
| parameter:
|
|
|
| >>> doctest.testfile('test_doctest.txt', report=False)
|
| ... # doctest: +ELLIPSIS
|
| **********************************************************************
|
| File "...", line 6, in test_doctest.txt
|
| Failed example:
|
| favorite_color
|
| Exception raised:
|
| ...
|
| NameError: name 'favorite_color' is not defined
|
| TestResults(failed=1, attempted=2)
|
| >>> doctest.master = None # Reset master.
|
|
|
| The optional keyword argument `raise_on_error` can be used to raise an
|
| exception on the first error (which may be useful for postmortem
|
| debugging):
|
|
|
| >>> doctest.testfile('test_doctest.txt', raise_on_error=True)
|
| ... # doctest: +ELLIPSIS
|
| Traceback (most recent call last):
|
| UnexpectedException: ...
|
| >>> doctest.master = None # Reset master.
|
|
|
| If the tests contain non-ASCII characters, the tests might fail, since
|
| it's unknown which encoding is used. The encoding can be specified
|
| using the optional keyword argument `encoding`:
|
|
|
| >>> doctest.testfile('test_doctest4.txt') # doctest: +ELLIPSIS
|
| **********************************************************************
|
| File "...", line 7, in test_doctest4.txt
|
| Failed example:
|
| u'...'
|
| Expected:
|
| u'f\xf6\xf6'
|
| Got:
|
| u'f\xc3\xb6\xc3\xb6'
|
| **********************************************************************
|
| ...
|
| **********************************************************************
|
| 1 items had failures:
|
| 2 of 4 in test_doctest4.txt
|
| ***Test Failed*** 2 failures.
|
| TestResults(failed=2, attempted=4)
|
| >>> doctest.master = None # Reset master.
|
|
|
| >>> doctest.testfile('test_doctest4.txt', encoding='utf-8')
|
| TestResults(failed=0, attempted=4)
|
| >>> doctest.master = None # Reset master.
|
|
|
| Switch the module encoding to 'utf-8' to test the verbose output without
|
| bothering with the current sys.stdout encoding.
|
|
|
| >>> doctest._encoding, saved_encoding = 'utf-8', doctest._encoding
|
| >>> doctest.testfile('test_doctest4.txt', encoding='utf-8', verbose=True)
|
| Trying:
|
| u'föö'
|
| Expecting:
|
| u'f\xf6\xf6'
|
| ok
|
| Trying:
|
| u'bąr'
|
| Expecting:
|
| u'b\u0105r'
|
| ok
|
| Trying:
|
| 'föö'
|
| Expecting:
|
| 'f\xc3\xb6\xc3\xb6'
|
| ok
|
| Trying:
|
| 'bąr'
|
| Expecting:
|
| 'b\xc4\x85r'
|
| ok
|
| 1 items passed all tests:
|
| 4 tests in test_doctest4.txt
|
| 4 tests in 1 items.
|
| 4 passed and 0 failed.
|
| Test passed.
|
| TestResults(failed=0, attempted=4)
|
| >>> doctest._encoding = saved_encoding
|
| >>> doctest.master = None # Reset master.
|
| >>> sys.argv = save_argv
|
| """
|
|
|
| # old_test1, ... used to live in doctest.py, but cluttered it. Note
|
| # that these use the deprecated doctest.Tester, so should go away (or
|
| # be rewritten) someday.
|
|
|
| def old_test1(): r"""
|
| >>> from doctest import Tester
|
| >>> t = Tester(globs={'x': 42}, verbose=0)
|
| >>> t.runstring(r'''
|
| ... >>> x = x * 2
|
| ... >>> print x
|
| ... 42
|
| ... ''', 'XYZ')
|
| **********************************************************************
|
| Line 3, in XYZ
|
| Failed example:
|
| print x
|
| Expected:
|
| 42
|
| Got:
|
| 84
|
| TestResults(failed=1, attempted=2)
|
| >>> t.runstring(">>> x = x * 2\n>>> print x\n84\n", 'example2')
|
| TestResults(failed=0, attempted=2)
|
| >>> t.summarize()
|
| **********************************************************************
|
| 1 items had failures:
|
| 1 of 2 in XYZ
|
| ***Test Failed*** 1 failures.
|
| TestResults(failed=1, attempted=4)
|
| >>> t.summarize(verbose=1)
|
| 1 items passed all tests:
|
| 2 tests in example2
|
| **********************************************************************
|
| 1 items had failures:
|
| 1 of 2 in XYZ
|
| 4 tests in 2 items.
|
| 3 passed and 1 failed.
|
| ***Test Failed*** 1 failures.
|
| TestResults(failed=1, attempted=4)
|
| """
|
|
|
| def old_test2(): r"""
|
| >>> from doctest import Tester
|
| >>> t = Tester(globs={}, verbose=1)
|
| >>> test = r'''
|
| ... # just an example
|
| ... >>> x = 1 + 2
|
| ... >>> x
|
| ... 3
|
| ... '''
|
| >>> t.runstring(test, "Example")
|
| Running string Example
|
| Trying:
|
| x = 1 + 2
|
| Expecting nothing
|
| ok
|
| Trying:
|
| x
|
| Expecting:
|
| 3
|
| ok
|
| 0 of 2 examples failed in string Example
|
| TestResults(failed=0, attempted=2)
|
| """
|
|
|
| def old_test3(): r"""
|
| >>> from doctest import Tester
|
| >>> t = Tester(globs={}, verbose=0)
|
| >>> def _f():
|
| ... '''Trivial docstring example.
|
| ... >>> assert 2 == 2
|
| ... '''
|
| ... return 32
|
| ...
|
| >>> t.rundoc(_f) # expect 0 failures in 1 example
|
| TestResults(failed=0, attempted=1)
|
| """
|
|
|
| def old_test4(): """
|
| >>> import types
|
| >>> m1 = types.ModuleType('_m1')
|
| >>> m2 = types.ModuleType('_m2')
|
| >>> test_data = \"""
|
| ... def _f():
|
| ... '''>>> assert 1 == 1
|
| ... '''
|
| ... def g():
|
| ... '''>>> assert 2 != 1
|
| ... '''
|
| ... class H:
|
| ... '''>>> assert 2 > 1
|
| ... '''
|
| ... def bar(self):
|
| ... '''>>> assert 1 < 2
|
| ... '''
|
| ... \"""
|
| >>> exec test_data in m1.__dict__
|
| >>> exec test_data in m2.__dict__
|
| >>> m1.__dict__.update({"f2": m2._f, "g2": m2.g, "h2": m2.H})
|
|
|
| Tests that objects outside m1 are excluded:
|
|
|
| >>> from doctest import Tester
|
| >>> t = Tester(globs={}, verbose=0)
|
| >>> t.rundict(m1.__dict__, "rundict_test", m1) # f2 and g2 and h2 skipped
|
| TestResults(failed=0, attempted=4)
|
|
|
| Once more, not excluding stuff outside m1:
|
|
|
| >>> t = Tester(globs={}, verbose=0)
|
| >>> t.rundict(m1.__dict__, "rundict_test_pvt") # None are skipped.
|
| TestResults(failed=0, attempted=8)
|
|
|
| The exclusion of objects from outside the designated module is
|
| meant to be invoked automagically by testmod.
|
|
|
| >>> doctest.testmod(m1, verbose=False)
|
| TestResults(failed=0, attempted=4)
|
| """
|
|
|
| ######################################################################
|
| ## Main
|
| ######################################################################
|
|
|
| def test_main():
|
| # Check the doctest cases in doctest itself:
|
| test_support.run_doctest(doctest, verbosity=True)
|
|
|
| from test import test_doctest
|
|
|
| # Ignore all warnings about the use of class Tester in this module.
|
| deprecations = [("class Tester is deprecated", DeprecationWarning)]
|
| if sys.py3kwarning:
|
| deprecations += [("backquote not supported", SyntaxWarning),
|
| ("execfile.. not supported", DeprecationWarning)]
|
| with test_support.check_warnings(*deprecations):
|
| # Check the doctest cases defined here:
|
| test_support.run_doctest(test_doctest, verbosity=True)
|
|
|
| import sys
|
| def test_coverage(coverdir):
|
| trace = test_support.import_module('trace')
|
| tracer = trace.Trace(ignoredirs=[sys.prefix, sys.exec_prefix,],
|
| trace=0, count=1)
|
| tracer.run('reload(doctest); test_main()')
|
| r = tracer.results()
|
| print 'Writing coverage results...'
|
| r.write_results(show_missing=True, summary=True,
|
| coverdir=coverdir)
|
|
|
| if __name__ == '__main__':
|
| if '-c' in sys.argv:
|
| test_coverage('/tmp/doctest.cover')
|
| else:
|
| test_main()
|
