blob: f07da75011d650c71698b3114c7e626435e6139d [file] [log] [blame]
Tim Peters8485b562004-08-04 18:46:34 +00001"""
2Test script for doctest.
3"""
4
Benjamin Petersonee8712c2008-05-20 21:35:26 +00005from test import support
Tim Peters8485b562004-08-04 18:46:34 +00006import doctest
Tim Petersa7def722004-08-23 22:13:22 +00007import warnings
Tim Peters8485b562004-08-04 18:46:34 +00008
9######################################################################
10## Sample Objects (used by test cases)
11######################################################################
12
13def sample_func(v):
14 """
Tim Peters19397e52004-08-06 22:02:59 +000015 Blah blah
16
Guido van Rossum7131f842007-02-09 20:13:25 +000017 >>> print(sample_func(22))
Tim Peters8485b562004-08-04 18:46:34 +000018 44
Tim Peters19397e52004-08-06 22:02:59 +000019
20 Yee ha!
Tim Peters8485b562004-08-04 18:46:34 +000021 """
22 return v+v
23
24class SampleClass:
25 """
Guido van Rossum7131f842007-02-09 20:13:25 +000026 >>> print(1)
Tim Peters8485b562004-08-04 18:46:34 +000027 1
Edward Loper4ae900f2004-09-21 03:20:34 +000028
29 >>> # comments get ignored. so are empty PS1 and PS2 prompts:
30 >>>
31 ...
32
33 Multiline example:
34 >>> sc = SampleClass(3)
35 >>> for i in range(10):
36 ... sc = sc.double()
Guido van Rossum805365e2007-05-07 22:24:25 +000037 ... print(' ', sc.get(), sep='', end='')
38 6 12 24 48 96 192 384 768 1536 3072
Tim Peters8485b562004-08-04 18:46:34 +000039 """
40 def __init__(self, val):
41 """
Guido van Rossum7131f842007-02-09 20:13:25 +000042 >>> print(SampleClass(12).get())
Tim Peters8485b562004-08-04 18:46:34 +000043 12
44 """
45 self.val = val
46
47 def double(self):
48 """
Guido van Rossum7131f842007-02-09 20:13:25 +000049 >>> print(SampleClass(12).double().get())
Tim Peters8485b562004-08-04 18:46:34 +000050 24
51 """
52 return SampleClass(self.val + self.val)
53
54 def get(self):
55 """
Guido van Rossum7131f842007-02-09 20:13:25 +000056 >>> print(SampleClass(-5).get())
Tim Peters8485b562004-08-04 18:46:34 +000057 -5
58 """
59 return self.val
60
61 def a_staticmethod(v):
62 """
Guido van Rossum7131f842007-02-09 20:13:25 +000063 >>> print(SampleClass.a_staticmethod(10))
Tim Peters8485b562004-08-04 18:46:34 +000064 11
65 """
66 return v+1
67 a_staticmethod = staticmethod(a_staticmethod)
68
69 def a_classmethod(cls, v):
70 """
Guido van Rossum7131f842007-02-09 20:13:25 +000071 >>> print(SampleClass.a_classmethod(10))
Tim Peters8485b562004-08-04 18:46:34 +000072 12
Guido van Rossum7131f842007-02-09 20:13:25 +000073 >>> print(SampleClass(0).a_classmethod(10))
Tim Peters8485b562004-08-04 18:46:34 +000074 12
75 """
76 return v+2
77 a_classmethod = classmethod(a_classmethod)
78
79 a_property = property(get, doc="""
Guido van Rossum7131f842007-02-09 20:13:25 +000080 >>> print(SampleClass(22).a_property)
Tim Peters8485b562004-08-04 18:46:34 +000081 22
82 """)
83
84 class NestedClass:
85 """
86 >>> x = SampleClass.NestedClass(5)
87 >>> y = x.square()
Guido van Rossum7131f842007-02-09 20:13:25 +000088 >>> print(y.get())
Tim Peters8485b562004-08-04 18:46:34 +000089 25
90 """
91 def __init__(self, val=0):
92 """
Guido van Rossum7131f842007-02-09 20:13:25 +000093 >>> print(SampleClass.NestedClass().get())
Tim Peters8485b562004-08-04 18:46:34 +000094 0
95 """
96 self.val = val
97 def square(self):
98 return SampleClass.NestedClass(self.val*self.val)
99 def get(self):
100 return self.val
101
102class SampleNewStyleClass(object):
103 r"""
Guido van Rossum7131f842007-02-09 20:13:25 +0000104 >>> print('1\n2\n3')
Tim Peters8485b562004-08-04 18:46:34 +0000105 1
106 2
107 3
108 """
109 def __init__(self, val):
110 """
Guido van Rossum7131f842007-02-09 20:13:25 +0000111 >>> print(SampleNewStyleClass(12).get())
Tim Peters8485b562004-08-04 18:46:34 +0000112 12
113 """
114 self.val = val
115
116 def double(self):
117 """
Guido van Rossum7131f842007-02-09 20:13:25 +0000118 >>> print(SampleNewStyleClass(12).double().get())
Tim Peters8485b562004-08-04 18:46:34 +0000119 24
120 """
121 return SampleNewStyleClass(self.val + self.val)
122
123 def get(self):
124 """
Guido van Rossum7131f842007-02-09 20:13:25 +0000125 >>> print(SampleNewStyleClass(-5).get())
Tim Peters8485b562004-08-04 18:46:34 +0000126 -5
127 """
128 return self.val
129
130######################################################################
Edward Loper2de91ba2004-08-27 02:07:46 +0000131## Fake stdin (for testing interactive debugging)
132######################################################################
133
134class _FakeInput:
135 """
136 A fake input stream for pdb's interactive debugger. Whenever a
137 line is read, print it (to simulate the user typing it), and then
138 return it. The set of lines to return is specified in the
139 constructor; they should not have trailing newlines.
140 """
141 def __init__(self, lines):
142 self.lines = lines
143
144 def readline(self):
145 line = self.lines.pop(0)
Guido van Rossumbe19ed72007-02-09 05:37:30 +0000146 print(line)
Edward Loper2de91ba2004-08-27 02:07:46 +0000147 return line+'\n'
148
149######################################################################
Tim Peters8485b562004-08-04 18:46:34 +0000150## Test Cases
151######################################################################
152
153def test_Example(): r"""
154Unit tests for the `Example` class.
155
Edward Lopera6b68322004-08-26 00:05:43 +0000156Example is a simple container class that holds:
157 - `source`: A source string.
158 - `want`: An expected output string.
159 - `exc_msg`: An expected exception message string (or None if no
160 exception is expected).
161 - `lineno`: A line number (within the docstring).
162 - `indent`: The example's indentation in the input string.
163 - `options`: An option dictionary, mapping option flags to True or
164 False.
Tim Peters8485b562004-08-04 18:46:34 +0000165
Edward Lopera6b68322004-08-26 00:05:43 +0000166These attributes are set by the constructor. `source` and `want` are
167required; the other attributes all have default values:
Tim Peters8485b562004-08-04 18:46:34 +0000168
Guido van Rossumbdc36e42007-02-09 22:43:47 +0000169 >>> example = doctest.Example('print(1)', '1\n')
Edward Lopera6b68322004-08-26 00:05:43 +0000170 >>> (example.source, example.want, example.exc_msg,
171 ... example.lineno, example.indent, example.options)
Guido van Rossumbdc36e42007-02-09 22:43:47 +0000172 ('print(1)\n', '1\n', None, 0, 0, {})
Edward Lopera6b68322004-08-26 00:05:43 +0000173
174The first three attributes (`source`, `want`, and `exc_msg`) may be
175specified positionally; the remaining arguments should be specified as
176keyword arguments:
177
178 >>> exc_msg = 'IndexError: pop from an empty list'
179 >>> example = doctest.Example('[].pop()', '', exc_msg,
180 ... lineno=5, indent=4,
181 ... options={doctest.ELLIPSIS: True})
182 >>> (example.source, example.want, example.exc_msg,
183 ... example.lineno, example.indent, example.options)
184 ('[].pop()\n', '', 'IndexError: pop from an empty list\n', 5, 4, {8: True})
185
186The constructor normalizes the `source` string to end in a newline:
Tim Peters8485b562004-08-04 18:46:34 +0000187
Tim Petersbb431472004-08-09 03:51:46 +0000188 Source spans a single line: no terminating newline.
Guido van Rossumbdc36e42007-02-09 22:43:47 +0000189 >>> e = doctest.Example('print(1)', '1\n')
Tim Petersbb431472004-08-09 03:51:46 +0000190 >>> e.source, e.want
Guido van Rossumbdc36e42007-02-09 22:43:47 +0000191 ('print(1)\n', '1\n')
Tim Petersbb431472004-08-09 03:51:46 +0000192
Guido van Rossumbdc36e42007-02-09 22:43:47 +0000193 >>> e = doctest.Example('print(1)\n', '1\n')
Tim Petersbb431472004-08-09 03:51:46 +0000194 >>> e.source, e.want
Guido van Rossumbdc36e42007-02-09 22:43:47 +0000195 ('print(1)\n', '1\n')
Tim Peters8485b562004-08-04 18:46:34 +0000196
Tim Petersbb431472004-08-09 03:51:46 +0000197 Source spans multiple lines: require terminating newline.
Guido van Rossumbdc36e42007-02-09 22:43:47 +0000198 >>> e = doctest.Example('print(1);\nprint(2)\n', '1\n2\n')
Tim Petersbb431472004-08-09 03:51:46 +0000199 >>> e.source, e.want
Guido van Rossumbdc36e42007-02-09 22:43:47 +0000200 ('print(1);\nprint(2)\n', '1\n2\n')
Tim Peters8485b562004-08-04 18:46:34 +0000201
Guido van Rossumbdc36e42007-02-09 22:43:47 +0000202 >>> e = doctest.Example('print(1);\nprint(2)', '1\n2\n')
Tim Petersbb431472004-08-09 03:51:46 +0000203 >>> e.source, e.want
Guido van Rossumbdc36e42007-02-09 22:43:47 +0000204 ('print(1);\nprint(2)\n', '1\n2\n')
Tim Petersbb431472004-08-09 03:51:46 +0000205
Edward Lopera6b68322004-08-26 00:05:43 +0000206 Empty source string (which should never appear in real examples)
207 >>> e = doctest.Example('', '')
208 >>> e.source, e.want
209 ('\n', '')
Tim Peters8485b562004-08-04 18:46:34 +0000210
Edward Lopera6b68322004-08-26 00:05:43 +0000211The constructor normalizes the `want` string to end in a newline,
212unless it's the empty string:
213
Guido van Rossumbdc36e42007-02-09 22:43:47 +0000214 >>> e = doctest.Example('print(1)', '1\n')
Tim Petersbb431472004-08-09 03:51:46 +0000215 >>> e.source, e.want
Guido van Rossumbdc36e42007-02-09 22:43:47 +0000216 ('print(1)\n', '1\n')
Tim Petersbb431472004-08-09 03:51:46 +0000217
Guido van Rossumbdc36e42007-02-09 22:43:47 +0000218 >>> e = doctest.Example('print(1)', '1')
Tim Petersbb431472004-08-09 03:51:46 +0000219 >>> e.source, e.want
Guido van Rossumbdc36e42007-02-09 22:43:47 +0000220 ('print(1)\n', '1\n')
Tim Petersbb431472004-08-09 03:51:46 +0000221
Edward Lopera6b68322004-08-26 00:05:43 +0000222 >>> e = doctest.Example('print', '')
Tim Petersbb431472004-08-09 03:51:46 +0000223 >>> e.source, e.want
224 ('print\n', '')
Edward Lopera6b68322004-08-26 00:05:43 +0000225
226The constructor normalizes the `exc_msg` string to end in a newline,
227unless it's `None`:
228
229 Message spans one line
230 >>> exc_msg = 'IndexError: pop from an empty list'
231 >>> e = doctest.Example('[].pop()', '', exc_msg)
232 >>> e.exc_msg
233 'IndexError: pop from an empty list\n'
234
235 >>> exc_msg = 'IndexError: pop from an empty list\n'
236 >>> e = doctest.Example('[].pop()', '', exc_msg)
237 >>> e.exc_msg
238 'IndexError: pop from an empty list\n'
239
240 Message spans multiple lines
241 >>> exc_msg = 'ValueError: 1\n 2'
242 >>> e = doctest.Example('raise ValueError("1\n 2")', '', exc_msg)
243 >>> e.exc_msg
244 'ValueError: 1\n 2\n'
245
246 >>> exc_msg = 'ValueError: 1\n 2\n'
247 >>> e = doctest.Example('raise ValueError("1\n 2")', '', exc_msg)
248 >>> e.exc_msg
249 'ValueError: 1\n 2\n'
250
251 Empty (but non-None) exception message (which should never appear
252 in real examples)
253 >>> exc_msg = ''
254 >>> e = doctest.Example('raise X()', '', exc_msg)
255 >>> e.exc_msg
256 '\n'
Tim Peters8485b562004-08-04 18:46:34 +0000257"""
258
259def test_DocTest(): r"""
260Unit tests for the `DocTest` class.
261
262DocTest is a collection of examples, extracted from a docstring, along
263with information about where the docstring comes from (a name,
264filename, and line number). The docstring is parsed by the `DocTest`
265constructor:
266
267 >>> docstring = '''
Guido van Rossumbdc36e42007-02-09 22:43:47 +0000268 ... >>> print(12)
Tim Peters8485b562004-08-04 18:46:34 +0000269 ... 12
270 ...
271 ... Non-example text.
272 ...
Guido van Rossumbdc36e42007-02-09 22:43:47 +0000273 ... >>> print('another\example')
Tim Peters8485b562004-08-04 18:46:34 +0000274 ... another
275 ... example
276 ... '''
277 >>> globs = {} # globals to run the test in.
Edward Lopera1ef6112004-08-09 16:14:41 +0000278 >>> parser = doctest.DocTestParser()
279 >>> test = parser.get_doctest(docstring, globs, 'some_test',
280 ... 'some_file', 20)
Guido van Rossum7131f842007-02-09 20:13:25 +0000281 >>> print(test)
Tim Peters8485b562004-08-04 18:46:34 +0000282 <DocTest some_test from some_file:20 (2 examples)>
283 >>> len(test.examples)
284 2
285 >>> e1, e2 = test.examples
286 >>> (e1.source, e1.want, e1.lineno)
Guido van Rossumbdc36e42007-02-09 22:43:47 +0000287 ('print(12)\n', '12\n', 1)
Tim Peters8485b562004-08-04 18:46:34 +0000288 >>> (e2.source, e2.want, e2.lineno)
Guido van Rossumbdc36e42007-02-09 22:43:47 +0000289 ("print('another\\example')\n", 'another\nexample\n', 6)
Tim Peters8485b562004-08-04 18:46:34 +0000290
291Source information (name, filename, and line number) is available as
292attributes on the doctest object:
293
294 >>> (test.name, test.filename, test.lineno)
295 ('some_test', 'some_file', 20)
296
297The line number of an example within its containing file is found by
298adding the line number of the example and the line number of its
299containing test:
300
301 >>> test.lineno + e1.lineno
302 21
303 >>> test.lineno + e2.lineno
304 26
305
306If the docstring contains inconsistant leading whitespace in the
307expected output of an example, then `DocTest` will raise a ValueError:
308
309 >>> docstring = r'''
Guido van Rossumbdc36e42007-02-09 22:43:47 +0000310 ... >>> print('bad\nindentation')
Tim Peters8485b562004-08-04 18:46:34 +0000311 ... bad
312 ... indentation
313 ... '''
Edward Lopera1ef6112004-08-09 16:14:41 +0000314 >>> parser.get_doctest(docstring, globs, 'some_test', 'filename', 0)
Tim Peters8485b562004-08-04 18:46:34 +0000315 Traceback (most recent call last):
Edward Loper00f8da72004-08-26 18:05:07 +0000316 ValueError: line 4 of the docstring for some_test has inconsistent leading whitespace: 'indentation'
Tim Peters8485b562004-08-04 18:46:34 +0000317
318If the docstring contains inconsistent leading whitespace on
319continuation lines, then `DocTest` will raise a ValueError:
320
321 >>> docstring = r'''
Guido van Rossumbdc36e42007-02-09 22:43:47 +0000322 ... >>> print(('bad indentation',
323 ... ... 2))
Tim Peters8485b562004-08-04 18:46:34 +0000324 ... ('bad', 'indentation')
325 ... '''
Edward Lopera1ef6112004-08-09 16:14:41 +0000326 >>> parser.get_doctest(docstring, globs, 'some_test', 'filename', 0)
Tim Peters8485b562004-08-04 18:46:34 +0000327 Traceback (most recent call last):
Guido van Rossume0192e52007-02-09 23:39:59 +0000328 ValueError: line 2 of the docstring for some_test has inconsistent leading whitespace: '... 2))'
Tim Peters8485b562004-08-04 18:46:34 +0000329
330If there's no blank space after a PS1 prompt ('>>>'), then `DocTest`
331will raise a ValueError:
332
Guido van Rossumbdc36e42007-02-09 22:43:47 +0000333 >>> docstring = '>>>print(1)\n1'
Edward Lopera1ef6112004-08-09 16:14:41 +0000334 >>> parser.get_doctest(docstring, globs, 'some_test', 'filename', 0)
Tim Peters8485b562004-08-04 18:46:34 +0000335 Traceback (most recent call last):
Guido van Rossumbdc36e42007-02-09 22:43:47 +0000336 ValueError: line 1 of the docstring for some_test lacks blank after >>>: '>>>print(1)'
Edward Loper7c748462004-08-09 02:06:06 +0000337
338If there's no blank space after a PS2 prompt ('...'), then `DocTest`
339will raise a ValueError:
340
Guido van Rossumbdc36e42007-02-09 22:43:47 +0000341 >>> docstring = '>>> if 1:\n...print(1)\n1'
Edward Lopera1ef6112004-08-09 16:14:41 +0000342 >>> parser.get_doctest(docstring, globs, 'some_test', 'filename', 0)
Edward Loper7c748462004-08-09 02:06:06 +0000343 Traceback (most recent call last):
Guido van Rossumbdc36e42007-02-09 22:43:47 +0000344 ValueError: line 2 of the docstring for some_test lacks blank after ...: '...print(1)'
Edward Loper7c748462004-08-09 02:06:06 +0000345
Tim Peters8485b562004-08-04 18:46:34 +0000346"""
347
Tim Peters8485b562004-08-04 18:46:34 +0000348def test_DocTestFinder(): r"""
349Unit tests for the `DocTestFinder` class.
350
351DocTestFinder is used to extract DocTests from an object's docstring
352and the docstrings of its contained objects. It can be used with
353modules, functions, classes, methods, staticmethods, classmethods, and
354properties.
355
356Finding Tests in Functions
357~~~~~~~~~~~~~~~~~~~~~~~~~~
358For a function whose docstring contains examples, DocTestFinder.find()
359will return a single test (for that function's docstring):
360
Tim Peters8485b562004-08-04 18:46:34 +0000361 >>> finder = doctest.DocTestFinder()
Jim Fulton07a349c2004-08-22 14:10:00 +0000362
363We'll simulate a __file__ attr that ends in pyc:
364
365 >>> import test.test_doctest
366 >>> old = test.test_doctest.__file__
367 >>> test.test_doctest.__file__ = 'test_doctest.pyc'
368
Tim Peters8485b562004-08-04 18:46:34 +0000369 >>> tests = finder.find(sample_func)
Edward Loper8e4a34b2004-08-12 02:34:27 +0000370
Guido van Rossum7131f842007-02-09 20:13:25 +0000371 >>> print(tests) # doctest: +ELLIPSIS
Tim Petersa7def722004-08-23 22:13:22 +0000372 [<DocTest sample_func from ...:13 (1 example)>]
Edward Loper8e4a34b2004-08-12 02:34:27 +0000373
Tim Peters4de7c5c2004-08-23 22:38:05 +0000374The exact name depends on how test_doctest was invoked, so allow for
375leading path components.
376
377 >>> tests[0].filename # doctest: +ELLIPSIS
378 '...test_doctest.py'
Jim Fulton07a349c2004-08-22 14:10:00 +0000379
380 >>> test.test_doctest.__file__ = old
Tim Petersc6cbab02004-08-22 19:43:28 +0000381
Jim Fulton07a349c2004-08-22 14:10:00 +0000382
Tim Peters8485b562004-08-04 18:46:34 +0000383 >>> e = tests[0].examples[0]
Tim Petersbb431472004-08-09 03:51:46 +0000384 >>> (e.source, e.want, e.lineno)
Guido van Rossumbdc36e42007-02-09 22:43:47 +0000385 ('print(sample_func(22))\n', '44\n', 3)
Tim Peters8485b562004-08-04 18:46:34 +0000386
Edward Loper32ddbf72004-09-13 05:47:24 +0000387By default, tests are created for objects with no docstring:
Tim Peters8485b562004-08-04 18:46:34 +0000388
389 >>> def no_docstring(v):
390 ... pass
Tim Peters958cc892004-09-13 14:53:28 +0000391 >>> finder.find(no_docstring)
392 []
Edward Loper32ddbf72004-09-13 05:47:24 +0000393
394However, the optional argument `exclude_empty` to the DocTestFinder
395constructor can be used to exclude tests for objects with empty
396docstrings:
397
398 >>> def no_docstring(v):
399 ... pass
400 >>> excl_empty_finder = doctest.DocTestFinder(exclude_empty=True)
401 >>> excl_empty_finder.find(no_docstring)
Tim Peters8485b562004-08-04 18:46:34 +0000402 []
403
404If the function has a docstring with no examples, then a test with no
405examples is returned. (This lets `DocTestRunner` collect statistics
406about which functions have no tests -- but is that useful? And should
407an empty test also be created when there's no docstring?)
408
409 >>> def no_examples(v):
410 ... ''' no doctest examples '''
Tim Peters17b56372004-09-11 17:33:27 +0000411 >>> finder.find(no_examples) # doctest: +ELLIPSIS
412 [<DocTest no_examples from ...:1 (no examples)>]
Tim Peters8485b562004-08-04 18:46:34 +0000413
414Finding Tests in Classes
415~~~~~~~~~~~~~~~~~~~~~~~~
416For a class, DocTestFinder will create a test for the class's
417docstring, and will recursively explore its contents, including
418methods, classmethods, staticmethods, properties, and nested classes.
419
420 >>> finder = doctest.DocTestFinder()
421 >>> tests = finder.find(SampleClass)
Tim Peters8485b562004-08-04 18:46:34 +0000422 >>> for t in tests:
Guido van Rossum7131f842007-02-09 20:13:25 +0000423 ... print('%2s %s' % (len(t.examples), t.name))
Edward Loper4ae900f2004-09-21 03:20:34 +0000424 3 SampleClass
Tim Peters8485b562004-08-04 18:46:34 +0000425 3 SampleClass.NestedClass
426 1 SampleClass.NestedClass.__init__
427 1 SampleClass.__init__
428 2 SampleClass.a_classmethod
429 1 SampleClass.a_property
430 1 SampleClass.a_staticmethod
431 1 SampleClass.double
432 1 SampleClass.get
433
434New-style classes are also supported:
435
436 >>> tests = finder.find(SampleNewStyleClass)
Tim Peters8485b562004-08-04 18:46:34 +0000437 >>> for t in tests:
Guido van Rossum7131f842007-02-09 20:13:25 +0000438 ... print('%2s %s' % (len(t.examples), t.name))
Tim Peters8485b562004-08-04 18:46:34 +0000439 1 SampleNewStyleClass
440 1 SampleNewStyleClass.__init__
441 1 SampleNewStyleClass.double
442 1 SampleNewStyleClass.get
443
444Finding Tests in Modules
445~~~~~~~~~~~~~~~~~~~~~~~~
446For a module, DocTestFinder will create a test for the class's
447docstring, and will recursively explore its contents, including
448functions, classes, and the `__test__` dictionary, if it exists:
449
450 >>> # A module
Christian Heimes45f9af32007-11-27 21:50:00 +0000451 >>> import types
452 >>> m = types.ModuleType('some_module')
Tim Peters8485b562004-08-04 18:46:34 +0000453 >>> def triple(val):
454 ... '''
Guido van Rossumbdc36e42007-02-09 22:43:47 +0000455 ... >>> print(triple(11))
Tim Peters8485b562004-08-04 18:46:34 +0000456 ... 33
457 ... '''
458 ... return val*3
459 >>> m.__dict__.update({
460 ... 'sample_func': sample_func,
461 ... 'SampleClass': SampleClass,
462 ... '__doc__': '''
463 ... Module docstring.
Guido van Rossumbdc36e42007-02-09 22:43:47 +0000464 ... >>> print('module')
Tim Peters8485b562004-08-04 18:46:34 +0000465 ... module
466 ... ''',
467 ... '__test__': {
Guido van Rossumbdc36e42007-02-09 22:43:47 +0000468 ... 'd': '>>> print(6)\n6\n>>> print(7)\n7\n',
Tim Peters8485b562004-08-04 18:46:34 +0000469 ... 'c': triple}})
470
471 >>> finder = doctest.DocTestFinder()
472 >>> # Use module=test.test_doctest, to prevent doctest from
473 >>> # ignoring the objects since they weren't defined in m.
474 >>> import test.test_doctest
475 >>> tests = finder.find(m, module=test.test_doctest)
Tim Peters8485b562004-08-04 18:46:34 +0000476 >>> for t in tests:
Guido van Rossum7131f842007-02-09 20:13:25 +0000477 ... print('%2s %s' % (len(t.examples), t.name))
Tim Peters8485b562004-08-04 18:46:34 +0000478 1 some_module
Edward Loper4ae900f2004-09-21 03:20:34 +0000479 3 some_module.SampleClass
Tim Peters8485b562004-08-04 18:46:34 +0000480 3 some_module.SampleClass.NestedClass
481 1 some_module.SampleClass.NestedClass.__init__
482 1 some_module.SampleClass.__init__
483 2 some_module.SampleClass.a_classmethod
484 1 some_module.SampleClass.a_property
485 1 some_module.SampleClass.a_staticmethod
486 1 some_module.SampleClass.double
487 1 some_module.SampleClass.get
Tim Petersc5684782004-09-13 01:07:12 +0000488 1 some_module.__test__.c
489 2 some_module.__test__.d
Tim Peters8485b562004-08-04 18:46:34 +0000490 1 some_module.sample_func
491
492Duplicate Removal
493~~~~~~~~~~~~~~~~~
494If a single object is listed twice (under different names), then tests
495will only be generated for it once:
496
Tim Petersf3f57472004-08-08 06:11:48 +0000497 >>> from test import doctest_aliases
Edward Loper32ddbf72004-09-13 05:47:24 +0000498 >>> tests = excl_empty_finder.find(doctest_aliases)
Guido van Rossum7131f842007-02-09 20:13:25 +0000499 >>> print(len(tests))
Tim Peters8485b562004-08-04 18:46:34 +0000500 2
Guido van Rossum7131f842007-02-09 20:13:25 +0000501 >>> print(tests[0].name)
Tim Petersf3f57472004-08-08 06:11:48 +0000502 test.doctest_aliases.TwoNames
503
504 TwoNames.f and TwoNames.g are bound to the same object.
505 We can't guess which will be found in doctest's traversal of
506 TwoNames.__dict__ first, so we have to allow for either.
507
508 >>> tests[1].name.split('.')[-1] in ['f', 'g']
Tim Peters8485b562004-08-04 18:46:34 +0000509 True
510
Thomas Wouters73e5a5b2006-06-08 15:35:45 +0000511Empty Tests
512~~~~~~~~~~~
513By default, an object with no doctests doesn't create any tests:
Tim Peters8485b562004-08-04 18:46:34 +0000514
Thomas Wouters73e5a5b2006-06-08 15:35:45 +0000515 >>> tests = doctest.DocTestFinder().find(SampleClass)
Tim Peters8485b562004-08-04 18:46:34 +0000516 >>> for t in tests:
Guido van Rossum7131f842007-02-09 20:13:25 +0000517 ... print('%2s %s' % (len(t.examples), t.name))
Edward Loper4ae900f2004-09-21 03:20:34 +0000518 3 SampleClass
Tim Peters8485b562004-08-04 18:46:34 +0000519 3 SampleClass.NestedClass
520 1 SampleClass.NestedClass.__init__
Tim Peters958cc892004-09-13 14:53:28 +0000521 1 SampleClass.__init__
Thomas Wouters73e5a5b2006-06-08 15:35:45 +0000522 2 SampleClass.a_classmethod
523 1 SampleClass.a_property
524 1 SampleClass.a_staticmethod
Tim Peters958cc892004-09-13 14:53:28 +0000525 1 SampleClass.double
526 1 SampleClass.get
527
528By default, that excluded objects with no doctests. exclude_empty=False
529tells it to include (empty) tests for objects with no doctests. This feature
530is really to support backward compatibility in what doctest.master.summarize()
531displays.
532
Thomas Wouters73e5a5b2006-06-08 15:35:45 +0000533 >>> tests = doctest.DocTestFinder(exclude_empty=False).find(SampleClass)
Tim Peters958cc892004-09-13 14:53:28 +0000534 >>> for t in tests:
Guido van Rossum7131f842007-02-09 20:13:25 +0000535 ... print('%2s %s' % (len(t.examples), t.name))
Edward Loper4ae900f2004-09-21 03:20:34 +0000536 3 SampleClass
Tim Peters958cc892004-09-13 14:53:28 +0000537 3 SampleClass.NestedClass
538 1 SampleClass.NestedClass.__init__
Edward Loper32ddbf72004-09-13 05:47:24 +0000539 0 SampleClass.NestedClass.get
540 0 SampleClass.NestedClass.square
Tim Peters8485b562004-08-04 18:46:34 +0000541 1 SampleClass.__init__
Tim Peters8485b562004-08-04 18:46:34 +0000542 2 SampleClass.a_classmethod
543 1 SampleClass.a_property
544 1 SampleClass.a_staticmethod
545 1 SampleClass.double
546 1 SampleClass.get
547
Tim Peters8485b562004-08-04 18:46:34 +0000548Turning off Recursion
549~~~~~~~~~~~~~~~~~~~~~
550DocTestFinder can be told not to look for tests in contained objects
551using the `recurse` flag:
552
553 >>> tests = doctest.DocTestFinder(recurse=False).find(SampleClass)
Tim Peters8485b562004-08-04 18:46:34 +0000554 >>> for t in tests:
Guido van Rossum7131f842007-02-09 20:13:25 +0000555 ... print('%2s %s' % (len(t.examples), t.name))
Edward Loper4ae900f2004-09-21 03:20:34 +0000556 3 SampleClass
Edward Loperb51b2342004-08-17 16:37:12 +0000557
558Line numbers
559~~~~~~~~~~~~
560DocTestFinder finds the line number of each example:
561
562 >>> def f(x):
563 ... '''
564 ... >>> x = 12
565 ...
566 ... some text
567 ...
568 ... >>> # examples are not created for comments & bare prompts.
569 ... >>>
570 ... ...
571 ...
572 ... >>> for x in range(10):
Guido van Rossumbdc36e42007-02-09 22:43:47 +0000573 ... ... print(x, end=' ')
Guido van Rossumd8faa362007-04-27 19:54:29 +0000574 ... 0 1 2 3 4 5 6 7 8 9
Thomas Wouters49fd7fa2006-04-21 10:40:58 +0000575 ... >>> x//2
576 ... 6
Edward Loperb51b2342004-08-17 16:37:12 +0000577 ... '''
578 >>> test = doctest.DocTestFinder().find(f)[0]
579 >>> [e.lineno for e in test.examples]
580 [1, 9, 12]
Tim Peters8485b562004-08-04 18:46:34 +0000581"""
582
Edward Loper00f8da72004-08-26 18:05:07 +0000583def test_DocTestParser(): r"""
584Unit tests for the `DocTestParser` class.
585
586DocTestParser is used to parse docstrings containing doctest examples.
587
588The `parse` method divides a docstring into examples and intervening
589text:
590
591 >>> s = '''
592 ... >>> x, y = 2, 3 # no output expected
593 ... >>> if 1:
Guido van Rossumbdc36e42007-02-09 22:43:47 +0000594 ... ... print(x)
595 ... ... print(y)
Edward Loper00f8da72004-08-26 18:05:07 +0000596 ... 2
597 ... 3
598 ...
599 ... Some text.
600 ... >>> x+y
601 ... 5
602 ... '''
603 >>> parser = doctest.DocTestParser()
604 >>> for piece in parser.parse(s):
605 ... if isinstance(piece, doctest.Example):
Guido van Rossum7131f842007-02-09 20:13:25 +0000606 ... print('Example:', (piece.source, piece.want, piece.lineno))
Edward Loper00f8da72004-08-26 18:05:07 +0000607 ... else:
Guido van Rossum7131f842007-02-09 20:13:25 +0000608 ... print(' Text:', repr(piece))
Edward Loper00f8da72004-08-26 18:05:07 +0000609 Text: '\n'
610 Example: ('x, y = 2, 3 # no output expected\n', '', 1)
611 Text: ''
Guido van Rossumbdc36e42007-02-09 22:43:47 +0000612 Example: ('if 1:\n print(x)\n print(y)\n', '2\n3\n', 2)
Edward Loper00f8da72004-08-26 18:05:07 +0000613 Text: '\nSome text.\n'
614 Example: ('x+y\n', '5\n', 9)
615 Text: ''
616
617The `get_examples` method returns just the examples:
618
619 >>> for piece in parser.get_examples(s):
Guido van Rossum7131f842007-02-09 20:13:25 +0000620 ... print((piece.source, piece.want, piece.lineno))
Edward Loper00f8da72004-08-26 18:05:07 +0000621 ('x, y = 2, 3 # no output expected\n', '', 1)
Guido van Rossumbdc36e42007-02-09 22:43:47 +0000622 ('if 1:\n print(x)\n print(y)\n', '2\n3\n', 2)
Edward Loper00f8da72004-08-26 18:05:07 +0000623 ('x+y\n', '5\n', 9)
624
625The `get_doctest` method creates a Test from the examples, along with the
626given arguments:
627
628 >>> test = parser.get_doctest(s, {}, 'name', 'filename', lineno=5)
629 >>> (test.name, test.filename, test.lineno)
630 ('name', 'filename', 5)
631 >>> for piece in test.examples:
Guido van Rossum7131f842007-02-09 20:13:25 +0000632 ... print((piece.source, piece.want, piece.lineno))
Edward Loper00f8da72004-08-26 18:05:07 +0000633 ('x, y = 2, 3 # no output expected\n', '', 1)
Guido van Rossumbdc36e42007-02-09 22:43:47 +0000634 ('if 1:\n print(x)\n print(y)\n', '2\n3\n', 2)
Edward Loper00f8da72004-08-26 18:05:07 +0000635 ('x+y\n', '5\n', 9)
636"""
637
Tim Peters8485b562004-08-04 18:46:34 +0000638class test_DocTestRunner:
639 def basics(): r"""
640Unit tests for the `DocTestRunner` class.
641
642DocTestRunner is used to run DocTest test cases, and to accumulate
643statistics. Here's a simple DocTest case we can use:
644
645 >>> def f(x):
646 ... '''
647 ... >>> x = 12
Guido van Rossumbdc36e42007-02-09 22:43:47 +0000648 ... >>> print(x)
Tim Peters8485b562004-08-04 18:46:34 +0000649 ... 12
Thomas Wouters49fd7fa2006-04-21 10:40:58 +0000650 ... >>> x//2
651 ... 6
Tim Peters8485b562004-08-04 18:46:34 +0000652 ... '''
653 >>> test = doctest.DocTestFinder().find(f)[0]
654
655The main DocTestRunner interface is the `run` method, which runs a
656given DocTest case in a given namespace (globs). It returns a tuple
657`(f,t)`, where `f` is the number of failed tests and `t` is the number
658of tried tests.
659
660 >>> doctest.DocTestRunner(verbose=False).run(test)
Christian Heimes25bb7832008-01-11 16:17:00 +0000661 TestResults(failed=0, attempted=3)
Tim Peters8485b562004-08-04 18:46:34 +0000662
663If any example produces incorrect output, then the test runner reports
664the failure and proceeds to the next example:
665
666 >>> def f(x):
667 ... '''
668 ... >>> x = 12
Guido van Rossumbdc36e42007-02-09 22:43:47 +0000669 ... >>> print(x)
Tim Peters8485b562004-08-04 18:46:34 +0000670 ... 14
Thomas Wouters49fd7fa2006-04-21 10:40:58 +0000671 ... >>> x//2
672 ... 6
Tim Peters8485b562004-08-04 18:46:34 +0000673 ... '''
674 >>> test = doctest.DocTestFinder().find(f)[0]
675 >>> doctest.DocTestRunner(verbose=True).run(test)
Tim Peters17b56372004-09-11 17:33:27 +0000676 ... # doctest: +ELLIPSIS
Edward Loperaacf0832004-08-26 01:19:50 +0000677 Trying:
678 x = 12
679 Expecting nothing
Tim Peters8485b562004-08-04 18:46:34 +0000680 ok
Edward Loperaacf0832004-08-26 01:19:50 +0000681 Trying:
Guido van Rossumbdc36e42007-02-09 22:43:47 +0000682 print(x)
Edward Loperaacf0832004-08-26 01:19:50 +0000683 Expecting:
684 14
Tim Peters8485b562004-08-04 18:46:34 +0000685 **********************************************************************
Tim Peters17b56372004-09-11 17:33:27 +0000686 File ..., line 4, in f
Jim Fulton07a349c2004-08-22 14:10:00 +0000687 Failed example:
Guido van Rossumbdc36e42007-02-09 22:43:47 +0000688 print(x)
Jim Fulton07a349c2004-08-22 14:10:00 +0000689 Expected:
690 14
691 Got:
692 12
Edward Loperaacf0832004-08-26 01:19:50 +0000693 Trying:
Thomas Wouters49fd7fa2006-04-21 10:40:58 +0000694 x//2
Edward Loperaacf0832004-08-26 01:19:50 +0000695 Expecting:
Thomas Wouters49fd7fa2006-04-21 10:40:58 +0000696 6
Tim Peters8485b562004-08-04 18:46:34 +0000697 ok
Christian Heimes25bb7832008-01-11 16:17:00 +0000698 TestResults(failed=1, attempted=3)
Tim Peters8485b562004-08-04 18:46:34 +0000699"""
700 def verbose_flag(): r"""
701The `verbose` flag makes the test runner generate more detailed
702output:
703
704 >>> def f(x):
705 ... '''
706 ... >>> x = 12
Guido van Rossumbdc36e42007-02-09 22:43:47 +0000707 ... >>> print(x)
Tim Peters8485b562004-08-04 18:46:34 +0000708 ... 12
Thomas Wouters49fd7fa2006-04-21 10:40:58 +0000709 ... >>> x//2
710 ... 6
Tim Peters8485b562004-08-04 18:46:34 +0000711 ... '''
712 >>> test = doctest.DocTestFinder().find(f)[0]
713
714 >>> doctest.DocTestRunner(verbose=True).run(test)
Edward Loperaacf0832004-08-26 01:19:50 +0000715 Trying:
716 x = 12
717 Expecting nothing
Tim Peters8485b562004-08-04 18:46:34 +0000718 ok
Edward Loperaacf0832004-08-26 01:19:50 +0000719 Trying:
Guido van Rossumbdc36e42007-02-09 22:43:47 +0000720 print(x)
Edward Loperaacf0832004-08-26 01:19:50 +0000721 Expecting:
722 12
Tim Peters8485b562004-08-04 18:46:34 +0000723 ok
Edward Loperaacf0832004-08-26 01:19:50 +0000724 Trying:
Thomas Wouters49fd7fa2006-04-21 10:40:58 +0000725 x//2
Edward Loperaacf0832004-08-26 01:19:50 +0000726 Expecting:
Thomas Wouters49fd7fa2006-04-21 10:40:58 +0000727 6
Tim Peters8485b562004-08-04 18:46:34 +0000728 ok
Christian Heimes25bb7832008-01-11 16:17:00 +0000729 TestResults(failed=0, attempted=3)
Tim Peters8485b562004-08-04 18:46:34 +0000730
731If the `verbose` flag is unspecified, then the output will be verbose
732iff `-v` appears in sys.argv:
733
734 >>> # Save the real sys.argv list.
735 >>> old_argv = sys.argv
736
737 >>> # If -v does not appear in sys.argv, then output isn't verbose.
738 >>> sys.argv = ['test']
739 >>> doctest.DocTestRunner().run(test)
Christian Heimes25bb7832008-01-11 16:17:00 +0000740 TestResults(failed=0, attempted=3)
Tim Peters8485b562004-08-04 18:46:34 +0000741
742 >>> # If -v does appear in sys.argv, then output is verbose.
743 >>> sys.argv = ['test', '-v']
744 >>> doctest.DocTestRunner().run(test)
Edward Loperaacf0832004-08-26 01:19:50 +0000745 Trying:
746 x = 12
747 Expecting nothing
Tim Peters8485b562004-08-04 18:46:34 +0000748 ok
Edward Loperaacf0832004-08-26 01:19:50 +0000749 Trying:
Guido van Rossumbdc36e42007-02-09 22:43:47 +0000750 print(x)
Edward Loperaacf0832004-08-26 01:19:50 +0000751 Expecting:
752 12
Tim Peters8485b562004-08-04 18:46:34 +0000753 ok
Edward Loperaacf0832004-08-26 01:19:50 +0000754 Trying:
Thomas Wouters49fd7fa2006-04-21 10:40:58 +0000755 x//2
Edward Loperaacf0832004-08-26 01:19:50 +0000756 Expecting:
Thomas Wouters49fd7fa2006-04-21 10:40:58 +0000757 6
Tim Peters8485b562004-08-04 18:46:34 +0000758 ok
Christian Heimes25bb7832008-01-11 16:17:00 +0000759 TestResults(failed=0, attempted=3)
Tim Peters8485b562004-08-04 18:46:34 +0000760
761 >>> # Restore sys.argv
762 >>> sys.argv = old_argv
763
764In the remaining examples, the test runner's verbosity will be
765explicitly set, to ensure that the test behavior is consistent.
766 """
767 def exceptions(): r"""
768Tests of `DocTestRunner`'s exception handling.
769
770An expected exception is specified with a traceback message. The
771lines between the first line and the type/value may be omitted or
772replaced with any other string:
773
774 >>> def f(x):
775 ... '''
776 ... >>> x = 12
Guido van Rossumbdc36e42007-02-09 22:43:47 +0000777 ... >>> print(x//0)
Tim Peters8485b562004-08-04 18:46:34 +0000778 ... Traceback (most recent call last):
Thomas Wouters49fd7fa2006-04-21 10:40:58 +0000779 ... ZeroDivisionError: integer division or modulo by zero
Tim Peters8485b562004-08-04 18:46:34 +0000780 ... '''
781 >>> test = doctest.DocTestFinder().find(f)[0]
782 >>> doctest.DocTestRunner(verbose=False).run(test)
Christian Heimes25bb7832008-01-11 16:17:00 +0000783 TestResults(failed=0, attempted=2)
Tim Peters8485b562004-08-04 18:46:34 +0000784
Edward Loper19b19582004-08-25 23:07:03 +0000785An example may not generate output before it raises an exception; if
786it does, then the traceback message will not be recognized as
787signaling an expected exception, so the example will be reported as an
788unexpected exception:
Tim Peters8485b562004-08-04 18:46:34 +0000789
790 >>> def f(x):
791 ... '''
792 ... >>> x = 12
Guido van Rossumbdc36e42007-02-09 22:43:47 +0000793 ... >>> print('pre-exception output', x//0)
Tim Peters8485b562004-08-04 18:46:34 +0000794 ... pre-exception output
795 ... Traceback (most recent call last):
Thomas Wouters49fd7fa2006-04-21 10:40:58 +0000796 ... ZeroDivisionError: integer division or modulo by zero
Tim Peters8485b562004-08-04 18:46:34 +0000797 ... '''
798 >>> test = doctest.DocTestFinder().find(f)[0]
799 >>> doctest.DocTestRunner(verbose=False).run(test)
Edward Loper19b19582004-08-25 23:07:03 +0000800 ... # doctest: +ELLIPSIS
801 **********************************************************************
Tim Peters17b56372004-09-11 17:33:27 +0000802 File ..., line 4, in f
Edward Loper19b19582004-08-25 23:07:03 +0000803 Failed example:
Guido van Rossumbdc36e42007-02-09 22:43:47 +0000804 print('pre-exception output', x//0)
Edward Loper19b19582004-08-25 23:07:03 +0000805 Exception raised:
806 ...
Thomas Wouters49fd7fa2006-04-21 10:40:58 +0000807 ZeroDivisionError: integer division or modulo by zero
Christian Heimes25bb7832008-01-11 16:17:00 +0000808 TestResults(failed=1, attempted=2)
Tim Peters8485b562004-08-04 18:46:34 +0000809
810Exception messages may contain newlines:
811
812 >>> def f(x):
813 ... r'''
Collin Winter3add4d72007-08-29 23:37:32 +0000814 ... >>> raise ValueError('multi\nline\nmessage')
Tim Peters8485b562004-08-04 18:46:34 +0000815 ... Traceback (most recent call last):
816 ... ValueError: multi
817 ... line
818 ... message
819 ... '''
820 >>> test = doctest.DocTestFinder().find(f)[0]
821 >>> doctest.DocTestRunner(verbose=False).run(test)
Christian Heimes25bb7832008-01-11 16:17:00 +0000822 TestResults(failed=0, attempted=1)
Tim Peters8485b562004-08-04 18:46:34 +0000823
824If an exception is expected, but an exception with the wrong type or
825message is raised, then it is reported as a failure:
826
827 >>> def f(x):
828 ... r'''
Collin Winter3add4d72007-08-29 23:37:32 +0000829 ... >>> raise ValueError('message')
Tim Peters8485b562004-08-04 18:46:34 +0000830 ... Traceback (most recent call last):
831 ... ValueError: wrong message
832 ... '''
833 >>> test = doctest.DocTestFinder().find(f)[0]
834 >>> doctest.DocTestRunner(verbose=False).run(test)
Edward Loper8e4a34b2004-08-12 02:34:27 +0000835 ... # doctest: +ELLIPSIS
Tim Peters8485b562004-08-04 18:46:34 +0000836 **********************************************************************
Tim Peters17b56372004-09-11 17:33:27 +0000837 File ..., line 3, in f
Jim Fulton07a349c2004-08-22 14:10:00 +0000838 Failed example:
Collin Winter3add4d72007-08-29 23:37:32 +0000839 raise ValueError('message')
Tim Peters8485b562004-08-04 18:46:34 +0000840 Expected:
841 Traceback (most recent call last):
842 ValueError: wrong message
843 Got:
844 Traceback (most recent call last):
Edward Loper8e4a34b2004-08-12 02:34:27 +0000845 ...
Tim Peters8485b562004-08-04 18:46:34 +0000846 ValueError: message
Christian Heimes25bb7832008-01-11 16:17:00 +0000847 TestResults(failed=1, attempted=1)
Tim Peters8485b562004-08-04 18:46:34 +0000848
Tim Peters1fbf9c52004-09-04 17:21:02 +0000849However, IGNORE_EXCEPTION_DETAIL can be used to allow a mismatch in the
850detail:
851
852 >>> def f(x):
853 ... r'''
Collin Winter3add4d72007-08-29 23:37:32 +0000854 ... >>> raise ValueError('message') #doctest: +IGNORE_EXCEPTION_DETAIL
Tim Peters1fbf9c52004-09-04 17:21:02 +0000855 ... Traceback (most recent call last):
856 ... ValueError: wrong message
857 ... '''
858 >>> test = doctest.DocTestFinder().find(f)[0]
859 >>> doctest.DocTestRunner(verbose=False).run(test)
Christian Heimes25bb7832008-01-11 16:17:00 +0000860 TestResults(failed=0, attempted=1)
Tim Peters1fbf9c52004-09-04 17:21:02 +0000861
862But IGNORE_EXCEPTION_DETAIL does not allow a mismatch in the exception type:
863
864 >>> def f(x):
865 ... r'''
Collin Winter3add4d72007-08-29 23:37:32 +0000866 ... >>> raise ValueError('message') #doctest: +IGNORE_EXCEPTION_DETAIL
Tim Peters1fbf9c52004-09-04 17:21:02 +0000867 ... Traceback (most recent call last):
868 ... TypeError: wrong type
869 ... '''
870 >>> test = doctest.DocTestFinder().find(f)[0]
871 >>> doctest.DocTestRunner(verbose=False).run(test)
872 ... # doctest: +ELLIPSIS
873 **********************************************************************
Tim Peters17b56372004-09-11 17:33:27 +0000874 File ..., line 3, in f
Tim Peters1fbf9c52004-09-04 17:21:02 +0000875 Failed example:
Collin Winter3add4d72007-08-29 23:37:32 +0000876 raise ValueError('message') #doctest: +IGNORE_EXCEPTION_DETAIL
Tim Peters1fbf9c52004-09-04 17:21:02 +0000877 Expected:
878 Traceback (most recent call last):
879 TypeError: wrong type
880 Got:
881 Traceback (most recent call last):
882 ...
883 ValueError: message
Christian Heimes25bb7832008-01-11 16:17:00 +0000884 TestResults(failed=1, attempted=1)
Tim Peters1fbf9c52004-09-04 17:21:02 +0000885
Tim Peters8485b562004-08-04 18:46:34 +0000886If an exception is raised but not expected, then it is reported as an
887unexpected exception:
888
Tim Peters8485b562004-08-04 18:46:34 +0000889 >>> def f(x):
890 ... r'''
Thomas Wouters49fd7fa2006-04-21 10:40:58 +0000891 ... >>> 1//0
Tim Peters8485b562004-08-04 18:46:34 +0000892 ... 0
893 ... '''
894 >>> test = doctest.DocTestFinder().find(f)[0]
895 >>> doctest.DocTestRunner(verbose=False).run(test)
Edward Loper74bca7a2004-08-12 02:27:44 +0000896 ... # doctest: +ELLIPSIS
Tim Peters8485b562004-08-04 18:46:34 +0000897 **********************************************************************
Tim Peters17b56372004-09-11 17:33:27 +0000898 File ..., line 3, in f
Jim Fulton07a349c2004-08-22 14:10:00 +0000899 Failed example:
Thomas Wouters49fd7fa2006-04-21 10:40:58 +0000900 1//0
Tim Peters8485b562004-08-04 18:46:34 +0000901 Exception raised:
902 Traceback (most recent call last):
Jim Fulton07a349c2004-08-22 14:10:00 +0000903 ...
Thomas Wouters49fd7fa2006-04-21 10:40:58 +0000904 ZeroDivisionError: integer division or modulo by zero
Christian Heimes25bb7832008-01-11 16:17:00 +0000905 TestResults(failed=1, attempted=1)
Tim Peters8485b562004-08-04 18:46:34 +0000906"""
907 def optionflags(): r"""
908Tests of `DocTestRunner`'s option flag handling.
909
910Several option flags can be used to customize the behavior of the test
911runner. These are defined as module constants in doctest, and passed
Christian Heimesfaf2f632008-01-06 16:59:19 +0000912to the DocTestRunner constructor (multiple constants should be ORed
Tim Peters8485b562004-08-04 18:46:34 +0000913together).
914
915The DONT_ACCEPT_TRUE_FOR_1 flag disables matches between True/False
916and 1/0:
917
918 >>> def f(x):
919 ... '>>> True\n1\n'
920
921 >>> # Without the flag:
922 >>> test = doctest.DocTestFinder().find(f)[0]
923 >>> doctest.DocTestRunner(verbose=False).run(test)
Christian Heimes25bb7832008-01-11 16:17:00 +0000924 TestResults(failed=0, attempted=1)
Tim Peters8485b562004-08-04 18:46:34 +0000925
926 >>> # With the flag:
927 >>> test = doctest.DocTestFinder().find(f)[0]
928 >>> flags = doctest.DONT_ACCEPT_TRUE_FOR_1
929 >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
Tim Peters17b56372004-09-11 17:33:27 +0000930 ... # doctest: +ELLIPSIS
Tim Peters8485b562004-08-04 18:46:34 +0000931 **********************************************************************
Tim Peters17b56372004-09-11 17:33:27 +0000932 File ..., line 2, in f
Jim Fulton07a349c2004-08-22 14:10:00 +0000933 Failed example:
934 True
935 Expected:
936 1
937 Got:
938 True
Christian Heimes25bb7832008-01-11 16:17:00 +0000939 TestResults(failed=1, attempted=1)
Tim Peters8485b562004-08-04 18:46:34 +0000940
941The DONT_ACCEPT_BLANKLINE flag disables the match between blank lines
942and the '<BLANKLINE>' marker:
943
944 >>> def f(x):
Guido van Rossumbdc36e42007-02-09 22:43:47 +0000945 ... '>>> print("a\\n\\nb")\na\n<BLANKLINE>\nb\n'
Tim Peters8485b562004-08-04 18:46:34 +0000946
947 >>> # Without the flag:
948 >>> test = doctest.DocTestFinder().find(f)[0]
949 >>> doctest.DocTestRunner(verbose=False).run(test)
Christian Heimes25bb7832008-01-11 16:17:00 +0000950 TestResults(failed=0, attempted=1)
Tim Peters8485b562004-08-04 18:46:34 +0000951
952 >>> # With the flag:
953 >>> test = doctest.DocTestFinder().find(f)[0]
954 >>> flags = doctest.DONT_ACCEPT_BLANKLINE
955 >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
Tim Peters17b56372004-09-11 17:33:27 +0000956 ... # doctest: +ELLIPSIS
Tim Peters8485b562004-08-04 18:46:34 +0000957 **********************************************************************
Tim Peters17b56372004-09-11 17:33:27 +0000958 File ..., line 2, in f
Jim Fulton07a349c2004-08-22 14:10:00 +0000959 Failed example:
Guido van Rossumbdc36e42007-02-09 22:43:47 +0000960 print("a\n\nb")
Tim Peters8485b562004-08-04 18:46:34 +0000961 Expected:
962 a
963 <BLANKLINE>
964 b
965 Got:
966 a
967 <BLANKLINE>
968 b
Christian Heimes25bb7832008-01-11 16:17:00 +0000969 TestResults(failed=1, attempted=1)
Tim Peters8485b562004-08-04 18:46:34 +0000970
971The NORMALIZE_WHITESPACE flag causes all sequences of whitespace to be
972treated as equal:
973
974 >>> def f(x):
Guido van Rossumbdc36e42007-02-09 22:43:47 +0000975 ... '>>> print(1, 2, 3)\n 1 2\n 3'
Tim Peters8485b562004-08-04 18:46:34 +0000976
977 >>> # Without the flag:
978 >>> test = doctest.DocTestFinder().find(f)[0]
979 >>> doctest.DocTestRunner(verbose=False).run(test)
Tim Peters17b56372004-09-11 17:33:27 +0000980 ... # doctest: +ELLIPSIS
Tim Peters8485b562004-08-04 18:46:34 +0000981 **********************************************************************
Tim Peters17b56372004-09-11 17:33:27 +0000982 File ..., line 2, in f
Jim Fulton07a349c2004-08-22 14:10:00 +0000983 Failed example:
Guido van Rossumbdc36e42007-02-09 22:43:47 +0000984 print(1, 2, 3)
Tim Peters8485b562004-08-04 18:46:34 +0000985 Expected:
986 1 2
987 3
Jim Fulton07a349c2004-08-22 14:10:00 +0000988 Got:
989 1 2 3
Christian Heimes25bb7832008-01-11 16:17:00 +0000990 TestResults(failed=1, attempted=1)
Tim Peters8485b562004-08-04 18:46:34 +0000991
992 >>> # With the flag:
993 >>> test = doctest.DocTestFinder().find(f)[0]
994 >>> flags = doctest.NORMALIZE_WHITESPACE
995 >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
Christian Heimes25bb7832008-01-11 16:17:00 +0000996 TestResults(failed=0, attempted=1)
Tim Peters8485b562004-08-04 18:46:34 +0000997
Tim Peters026f8dc2004-08-19 16:38:58 +0000998 An example from the docs:
Guido van Rossum805365e2007-05-07 22:24:25 +0000999 >>> print(list(range(20))) #doctest: +NORMALIZE_WHITESPACE
Tim Peters026f8dc2004-08-19 16:38:58 +00001000 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9,
1001 10, 11, 12, 13, 14, 15, 16, 17, 18, 19]
1002
Tim Peters8485b562004-08-04 18:46:34 +00001003The ELLIPSIS flag causes ellipsis marker ("...") in the expected
1004output to match any substring in the actual output:
1005
1006 >>> def f(x):
Guido van Rossum805365e2007-05-07 22:24:25 +00001007 ... '>>> print(list(range(15)))\n[0, 1, 2, ..., 14]\n'
Tim Peters8485b562004-08-04 18:46:34 +00001008
1009 >>> # Without the flag:
1010 >>> test = doctest.DocTestFinder().find(f)[0]
1011 >>> doctest.DocTestRunner(verbose=False).run(test)
Tim Peters17b56372004-09-11 17:33:27 +00001012 ... # doctest: +ELLIPSIS
Tim Peters8485b562004-08-04 18:46:34 +00001013 **********************************************************************
Tim Peters17b56372004-09-11 17:33:27 +00001014 File ..., line 2, in f
Jim Fulton07a349c2004-08-22 14:10:00 +00001015 Failed example:
Guido van Rossum805365e2007-05-07 22:24:25 +00001016 print(list(range(15)))
Jim Fulton07a349c2004-08-22 14:10:00 +00001017 Expected:
1018 [0, 1, 2, ..., 14]
1019 Got:
1020 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14]
Christian Heimes25bb7832008-01-11 16:17:00 +00001021 TestResults(failed=1, attempted=1)
Tim Peters8485b562004-08-04 18:46:34 +00001022
1023 >>> # With the flag:
1024 >>> test = doctest.DocTestFinder().find(f)[0]
1025 >>> flags = doctest.ELLIPSIS
1026 >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
Christian Heimes25bb7832008-01-11 16:17:00 +00001027 TestResults(failed=0, attempted=1)
Tim Peters8485b562004-08-04 18:46:34 +00001028
Tim Peterse594bee2004-08-22 01:47:51 +00001029 ... also matches nothing:
Tim Peters1cf3aa62004-08-19 06:49:33 +00001030
Guido van Rossume0192e52007-02-09 23:39:59 +00001031 >>> if 1:
1032 ... for i in range(100):
1033 ... print(i**2, end=' ') #doctest: +ELLIPSIS
1034 ... print('!')
1035 0 1...4...9 16 ... 36 49 64 ... 9801 !
Tim Peters1cf3aa62004-08-19 06:49:33 +00001036
Tim Peters026f8dc2004-08-19 16:38:58 +00001037 ... can be surprising; e.g., this test passes:
Tim Peters26b3ebb2004-08-19 08:10:08 +00001038
Guido van Rossume0192e52007-02-09 23:39:59 +00001039 >>> if 1: #doctest: +ELLIPSIS
1040 ... for i in range(20):
1041 ... print(i, end=' ')
1042 ... print(20)
Tim Peterse594bee2004-08-22 01:47:51 +00001043 0 1 2 ...1...2...0
Tim Peters26b3ebb2004-08-19 08:10:08 +00001044
Tim Peters026f8dc2004-08-19 16:38:58 +00001045 Examples from the docs:
1046
Guido van Rossum805365e2007-05-07 22:24:25 +00001047 >>> print(list(range(20))) # doctest:+ELLIPSIS
Tim Peters026f8dc2004-08-19 16:38:58 +00001048 [0, 1, ..., 18, 19]
1049
Guido van Rossum805365e2007-05-07 22:24:25 +00001050 >>> print(list(range(20))) # doctest: +ELLIPSIS
Tim Peters026f8dc2004-08-19 16:38:58 +00001051 ... # doctest: +NORMALIZE_WHITESPACE
1052 [0, 1, ..., 18, 19]
1053
Thomas Wouters477c8d52006-05-27 19:21:47 +00001054The SKIP flag causes an example to be skipped entirely. I.e., the
1055example is not run. It can be useful in contexts where doctest
1056examples serve as both documentation and test cases, and an example
1057should be included for documentation purposes, but should not be
1058checked (e.g., because its output is random, or depends on resources
1059which would be unavailable.) The SKIP flag can also be used for
1060'commenting out' broken examples.
1061
1062 >>> import unavailable_resource # doctest: +SKIP
1063 >>> unavailable_resource.do_something() # doctest: +SKIP
1064 >>> unavailable_resource.blow_up() # doctest: +SKIP
1065 Traceback (most recent call last):
1066 ...
1067 UncheckedBlowUpError: Nobody checks me.
1068
1069 >>> import random
Guido van Rossum7131f842007-02-09 20:13:25 +00001070 >>> print(random.random()) # doctest: +SKIP
Thomas Wouters477c8d52006-05-27 19:21:47 +00001071 0.721216923889
1072
Edward Loper71f55af2004-08-26 01:41:51 +00001073The REPORT_UDIFF flag causes failures that involve multi-line expected
Tim Peters8485b562004-08-04 18:46:34 +00001074and actual outputs to be displayed using a unified diff:
1075
1076 >>> def f(x):
1077 ... r'''
Guido van Rossumbdc36e42007-02-09 22:43:47 +00001078 ... >>> print('\n'.join('abcdefg'))
Tim Peters8485b562004-08-04 18:46:34 +00001079 ... a
1080 ... B
1081 ... c
1082 ... d
1083 ... f
1084 ... g
1085 ... h
1086 ... '''
1087
1088 >>> # Without the flag:
1089 >>> test = doctest.DocTestFinder().find(f)[0]
1090 >>> doctest.DocTestRunner(verbose=False).run(test)
Tim Peters17b56372004-09-11 17:33:27 +00001091 ... # doctest: +ELLIPSIS
Tim Peters8485b562004-08-04 18:46:34 +00001092 **********************************************************************
Tim Peters17b56372004-09-11 17:33:27 +00001093 File ..., line 3, in f
Jim Fulton07a349c2004-08-22 14:10:00 +00001094 Failed example:
Guido van Rossumbdc36e42007-02-09 22:43:47 +00001095 print('\n'.join('abcdefg'))
Tim Peters8485b562004-08-04 18:46:34 +00001096 Expected:
1097 a
1098 B
1099 c
1100 d
1101 f
1102 g
1103 h
1104 Got:
1105 a
1106 b
1107 c
1108 d
1109 e
1110 f
1111 g
Christian Heimes25bb7832008-01-11 16:17:00 +00001112 TestResults(failed=1, attempted=1)
Tim Peters8485b562004-08-04 18:46:34 +00001113
1114 >>> # With the flag:
1115 >>> test = doctest.DocTestFinder().find(f)[0]
Edward Loper71f55af2004-08-26 01:41:51 +00001116 >>> flags = doctest.REPORT_UDIFF
Tim Peters8485b562004-08-04 18:46:34 +00001117 >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
Tim Peters17b56372004-09-11 17:33:27 +00001118 ... # doctest: +ELLIPSIS
Tim Peters8485b562004-08-04 18:46:34 +00001119 **********************************************************************
Tim Peters17b56372004-09-11 17:33:27 +00001120 File ..., line 3, in f
Jim Fulton07a349c2004-08-22 14:10:00 +00001121 Failed example:
Guido van Rossumbdc36e42007-02-09 22:43:47 +00001122 print('\n'.join('abcdefg'))
Edward Loper56629292004-08-26 01:31:56 +00001123 Differences (unified diff with -expected +actual):
Tim Peterse7edcb82004-08-26 05:44:27 +00001124 @@ -1,7 +1,7 @@
Tim Peters8485b562004-08-04 18:46:34 +00001125 a
1126 -B
1127 +b
1128 c
1129 d
1130 +e
1131 f
1132 g
1133 -h
Christian Heimes25bb7832008-01-11 16:17:00 +00001134 TestResults(failed=1, attempted=1)
Tim Peters8485b562004-08-04 18:46:34 +00001135
Edward Loper71f55af2004-08-26 01:41:51 +00001136The REPORT_CDIFF flag causes failures that involve multi-line expected
Tim Peters8485b562004-08-04 18:46:34 +00001137and actual outputs to be displayed using a context diff:
1138
Edward Loper71f55af2004-08-26 01:41:51 +00001139 >>> # Reuse f() from the REPORT_UDIFF example, above.
Tim Peters8485b562004-08-04 18:46:34 +00001140 >>> test = doctest.DocTestFinder().find(f)[0]
Edward Loper71f55af2004-08-26 01:41:51 +00001141 >>> flags = doctest.REPORT_CDIFF
Tim Peters8485b562004-08-04 18:46:34 +00001142 >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
Tim Peters17b56372004-09-11 17:33:27 +00001143 ... # doctest: +ELLIPSIS
Tim Peters8485b562004-08-04 18:46:34 +00001144 **********************************************************************
Tim Peters17b56372004-09-11 17:33:27 +00001145 File ..., line 3, in f
Jim Fulton07a349c2004-08-22 14:10:00 +00001146 Failed example:
Guido van Rossumbdc36e42007-02-09 22:43:47 +00001147 print('\n'.join('abcdefg'))
Edward Loper56629292004-08-26 01:31:56 +00001148 Differences (context diff with expected followed by actual):
Tim Peters8485b562004-08-04 18:46:34 +00001149 ***************
Tim Peterse7edcb82004-08-26 05:44:27 +00001150 *** 1,7 ****
Tim Peters8485b562004-08-04 18:46:34 +00001151 a
1152 ! B
1153 c
1154 d
1155 f
1156 g
1157 - h
Tim Peterse7edcb82004-08-26 05:44:27 +00001158 --- 1,7 ----
Tim Peters8485b562004-08-04 18:46:34 +00001159 a
1160 ! b
1161 c
1162 d
1163 + e
1164 f
1165 g
Christian Heimes25bb7832008-01-11 16:17:00 +00001166 TestResults(failed=1, attempted=1)
Tim Petersc6cbab02004-08-22 19:43:28 +00001167
1168
Edward Loper71f55af2004-08-26 01:41:51 +00001169The REPORT_NDIFF flag causes failures to use the difflib.Differ algorithm
Tim Petersc6cbab02004-08-22 19:43:28 +00001170used by the popular ndiff.py utility. This does intraline difference
1171marking, as well as interline differences.
1172
1173 >>> def f(x):
1174 ... r'''
Guido van Rossumbdc36e42007-02-09 22:43:47 +00001175 ... >>> print("a b c d e f g h i j k l m")
Tim Petersc6cbab02004-08-22 19:43:28 +00001176 ... a b c d e f g h i j k 1 m
1177 ... '''
1178 >>> test = doctest.DocTestFinder().find(f)[0]
Edward Loper71f55af2004-08-26 01:41:51 +00001179 >>> flags = doctest.REPORT_NDIFF
Tim Petersc6cbab02004-08-22 19:43:28 +00001180 >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
Tim Peters17b56372004-09-11 17:33:27 +00001181 ... # doctest: +ELLIPSIS
Tim Petersc6cbab02004-08-22 19:43:28 +00001182 **********************************************************************
Tim Peters17b56372004-09-11 17:33:27 +00001183 File ..., line 3, in f
Tim Petersc6cbab02004-08-22 19:43:28 +00001184 Failed example:
Guido van Rossumbdc36e42007-02-09 22:43:47 +00001185 print("a b c d e f g h i j k l m")
Tim Petersc6cbab02004-08-22 19:43:28 +00001186 Differences (ndiff with -expected +actual):
1187 - a b c d e f g h i j k 1 m
1188 ? ^
1189 + a b c d e f g h i j k l m
1190 ? + ++ ^
Christian Heimes25bb7832008-01-11 16:17:00 +00001191 TestResults(failed=1, attempted=1)
Edward Lopera89f88d2004-08-26 02:45:51 +00001192
1193The REPORT_ONLY_FIRST_FAILURE supresses result output after the first
1194failing example:
1195
1196 >>> def f(x):
1197 ... r'''
Guido van Rossumbdc36e42007-02-09 22:43:47 +00001198 ... >>> print(1) # first success
Edward Lopera89f88d2004-08-26 02:45:51 +00001199 ... 1
Guido van Rossumbdc36e42007-02-09 22:43:47 +00001200 ... >>> print(2) # first failure
Edward Lopera89f88d2004-08-26 02:45:51 +00001201 ... 200
Guido van Rossumbdc36e42007-02-09 22:43:47 +00001202 ... >>> print(3) # second failure
Edward Lopera89f88d2004-08-26 02:45:51 +00001203 ... 300
Guido van Rossumbdc36e42007-02-09 22:43:47 +00001204 ... >>> print(4) # second success
Edward Lopera89f88d2004-08-26 02:45:51 +00001205 ... 4
Guido van Rossumbdc36e42007-02-09 22:43:47 +00001206 ... >>> print(5) # third failure
Edward Lopera89f88d2004-08-26 02:45:51 +00001207 ... 500
1208 ... '''
1209 >>> test = doctest.DocTestFinder().find(f)[0]
1210 >>> flags = doctest.REPORT_ONLY_FIRST_FAILURE
1211 >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
Tim Peters17b56372004-09-11 17:33:27 +00001212 ... # doctest: +ELLIPSIS
Edward Lopera89f88d2004-08-26 02:45:51 +00001213 **********************************************************************
Tim Peters17b56372004-09-11 17:33:27 +00001214 File ..., line 5, in f
Edward Lopera89f88d2004-08-26 02:45:51 +00001215 Failed example:
Guido van Rossumbdc36e42007-02-09 22:43:47 +00001216 print(2) # first failure
Edward Lopera89f88d2004-08-26 02:45:51 +00001217 Expected:
1218 200
1219 Got:
1220 2
Christian Heimes25bb7832008-01-11 16:17:00 +00001221 TestResults(failed=3, attempted=5)
Edward Lopera89f88d2004-08-26 02:45:51 +00001222
1223However, output from `report_start` is not supressed:
1224
1225 >>> doctest.DocTestRunner(verbose=True, optionflags=flags).run(test)
Tim Peters17b56372004-09-11 17:33:27 +00001226 ... # doctest: +ELLIPSIS
Edward Lopera89f88d2004-08-26 02:45:51 +00001227 Trying:
Guido van Rossumbdc36e42007-02-09 22:43:47 +00001228 print(1) # first success
Edward Lopera89f88d2004-08-26 02:45:51 +00001229 Expecting:
1230 1
1231 ok
1232 Trying:
Guido van Rossumbdc36e42007-02-09 22:43:47 +00001233 print(2) # first failure
Edward Lopera89f88d2004-08-26 02:45:51 +00001234 Expecting:
1235 200
1236 **********************************************************************
Tim Peters17b56372004-09-11 17:33:27 +00001237 File ..., line 5, in f
Edward Lopera89f88d2004-08-26 02:45:51 +00001238 Failed example:
Guido van Rossumbdc36e42007-02-09 22:43:47 +00001239 print(2) # first failure
Edward Lopera89f88d2004-08-26 02:45:51 +00001240 Expected:
1241 200
1242 Got:
1243 2
Christian Heimes25bb7832008-01-11 16:17:00 +00001244 TestResults(failed=3, attempted=5)
Edward Lopera89f88d2004-08-26 02:45:51 +00001245
1246For the purposes of REPORT_ONLY_FIRST_FAILURE, unexpected exceptions
1247count as failures:
1248
1249 >>> def f(x):
1250 ... r'''
Guido van Rossumbdc36e42007-02-09 22:43:47 +00001251 ... >>> print(1) # first success
Edward Lopera89f88d2004-08-26 02:45:51 +00001252 ... 1
1253 ... >>> raise ValueError(2) # first failure
1254 ... 200
Guido van Rossumbdc36e42007-02-09 22:43:47 +00001255 ... >>> print(3) # second failure
Edward Lopera89f88d2004-08-26 02:45:51 +00001256 ... 300
Guido van Rossumbdc36e42007-02-09 22:43:47 +00001257 ... >>> print(4) # second success
Edward Lopera89f88d2004-08-26 02:45:51 +00001258 ... 4
Guido van Rossumbdc36e42007-02-09 22:43:47 +00001259 ... >>> print(5) # third failure
Edward Lopera89f88d2004-08-26 02:45:51 +00001260 ... 500
1261 ... '''
1262 >>> test = doctest.DocTestFinder().find(f)[0]
1263 >>> flags = doctest.REPORT_ONLY_FIRST_FAILURE
1264 >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
1265 ... # doctest: +ELLIPSIS
1266 **********************************************************************
Tim Peters17b56372004-09-11 17:33:27 +00001267 File ..., line 5, in f
Edward Lopera89f88d2004-08-26 02:45:51 +00001268 Failed example:
1269 raise ValueError(2) # first failure
1270 Exception raised:
1271 ...
1272 ValueError: 2
Christian Heimes25bb7832008-01-11 16:17:00 +00001273 TestResults(failed=3, attempted=5)
Edward Lopera89f88d2004-08-26 02:45:51 +00001274
Thomas Wouters477c8d52006-05-27 19:21:47 +00001275New option flags can also be registered, via register_optionflag(). Here
1276we reach into doctest's internals a bit.
1277
1278 >>> unlikely = "UNLIKELY_OPTION_NAME"
1279 >>> unlikely in doctest.OPTIONFLAGS_BY_NAME
1280 False
1281 >>> new_flag_value = doctest.register_optionflag(unlikely)
1282 >>> unlikely in doctest.OPTIONFLAGS_BY_NAME
1283 True
1284
1285Before 2.4.4/2.5, registering a name more than once erroneously created
1286more than one flag value. Here we verify that's fixed:
1287
1288 >>> redundant_flag_value = doctest.register_optionflag(unlikely)
1289 >>> redundant_flag_value == new_flag_value
1290 True
1291
1292Clean up.
1293 >>> del doctest.OPTIONFLAGS_BY_NAME[unlikely]
1294
Tim Petersc6cbab02004-08-22 19:43:28 +00001295 """
1296
Tim Peters8485b562004-08-04 18:46:34 +00001297 def option_directives(): r"""
1298Tests of `DocTestRunner`'s option directive mechanism.
1299
Edward Loper74bca7a2004-08-12 02:27:44 +00001300Option directives can be used to turn option flags on or off for a
1301single example. To turn an option on for an example, follow that
1302example with a comment of the form ``# doctest: +OPTION``:
Tim Peters8485b562004-08-04 18:46:34 +00001303
1304 >>> def f(x): r'''
Guido van Rossum805365e2007-05-07 22:24:25 +00001305 ... >>> print(list(range(10))) # should fail: no ellipsis
Edward Loper74bca7a2004-08-12 02:27:44 +00001306 ... [0, 1, ..., 9]
1307 ...
Guido van Rossum805365e2007-05-07 22:24:25 +00001308 ... >>> print(list(range(10))) # doctest: +ELLIPSIS
Edward Loper74bca7a2004-08-12 02:27:44 +00001309 ... [0, 1, ..., 9]
1310 ... '''
1311 >>> test = doctest.DocTestFinder().find(f)[0]
1312 >>> doctest.DocTestRunner(verbose=False).run(test)
Tim Peters17b56372004-09-11 17:33:27 +00001313 ... # doctest: +ELLIPSIS
Edward Loper74bca7a2004-08-12 02:27:44 +00001314 **********************************************************************
Tim Peters17b56372004-09-11 17:33:27 +00001315 File ..., line 2, in f
Jim Fulton07a349c2004-08-22 14:10:00 +00001316 Failed example:
Guido van Rossum805365e2007-05-07 22:24:25 +00001317 print(list(range(10))) # should fail: no ellipsis
Jim Fulton07a349c2004-08-22 14:10:00 +00001318 Expected:
1319 [0, 1, ..., 9]
1320 Got:
1321 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
Christian Heimes25bb7832008-01-11 16:17:00 +00001322 TestResults(failed=1, attempted=2)
Edward Loper74bca7a2004-08-12 02:27:44 +00001323
1324To turn an option off for an example, follow that example with a
1325comment of the form ``# doctest: -OPTION``:
1326
1327 >>> def f(x): r'''
Guido van Rossum805365e2007-05-07 22:24:25 +00001328 ... >>> print(list(range(10)))
Edward Loper74bca7a2004-08-12 02:27:44 +00001329 ... [0, 1, ..., 9]
1330 ...
1331 ... >>> # should fail: no ellipsis
Guido van Rossum805365e2007-05-07 22:24:25 +00001332 ... >>> print(list(range(10))) # doctest: -ELLIPSIS
Edward Loper74bca7a2004-08-12 02:27:44 +00001333 ... [0, 1, ..., 9]
1334 ... '''
1335 >>> test = doctest.DocTestFinder().find(f)[0]
1336 >>> doctest.DocTestRunner(verbose=False,
1337 ... optionflags=doctest.ELLIPSIS).run(test)
Tim Peters17b56372004-09-11 17:33:27 +00001338 ... # doctest: +ELLIPSIS
Edward Loper74bca7a2004-08-12 02:27:44 +00001339 **********************************************************************
Tim Peters17b56372004-09-11 17:33:27 +00001340 File ..., line 6, in f
Jim Fulton07a349c2004-08-22 14:10:00 +00001341 Failed example:
Guido van Rossum805365e2007-05-07 22:24:25 +00001342 print(list(range(10))) # doctest: -ELLIPSIS
Jim Fulton07a349c2004-08-22 14:10:00 +00001343 Expected:
1344 [0, 1, ..., 9]
1345 Got:
1346 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
Christian Heimes25bb7832008-01-11 16:17:00 +00001347 TestResults(failed=1, attempted=2)
Edward Loper74bca7a2004-08-12 02:27:44 +00001348
1349Option directives affect only the example that they appear with; they
1350do not change the options for surrounding examples:
Edward Loper8e4a34b2004-08-12 02:34:27 +00001351
Edward Loper74bca7a2004-08-12 02:27:44 +00001352 >>> def f(x): r'''
Guido van Rossum805365e2007-05-07 22:24:25 +00001353 ... >>> print(list(range(10))) # Should fail: no ellipsis
Tim Peters8485b562004-08-04 18:46:34 +00001354 ... [0, 1, ..., 9]
1355 ...
Guido van Rossum805365e2007-05-07 22:24:25 +00001356 ... >>> print(list(range(10))) # doctest: +ELLIPSIS
Tim Peters8485b562004-08-04 18:46:34 +00001357 ... [0, 1, ..., 9]
1358 ...
Guido van Rossum805365e2007-05-07 22:24:25 +00001359 ... >>> print(list(range(10))) # Should fail: no ellipsis
Tim Peters8485b562004-08-04 18:46:34 +00001360 ... [0, 1, ..., 9]
1361 ... '''
1362 >>> test = doctest.DocTestFinder().find(f)[0]
1363 >>> doctest.DocTestRunner(verbose=False).run(test)
Tim Peters17b56372004-09-11 17:33:27 +00001364 ... # doctest: +ELLIPSIS
Tim Peters8485b562004-08-04 18:46:34 +00001365 **********************************************************************
Tim Peters17b56372004-09-11 17:33:27 +00001366 File ..., line 2, in f
Jim Fulton07a349c2004-08-22 14:10:00 +00001367 Failed example:
Guido van Rossum805365e2007-05-07 22:24:25 +00001368 print(list(range(10))) # Should fail: no ellipsis
Jim Fulton07a349c2004-08-22 14:10:00 +00001369 Expected:
1370 [0, 1, ..., 9]
1371 Got:
1372 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
Tim Peters8485b562004-08-04 18:46:34 +00001373 **********************************************************************
Tim Peters17b56372004-09-11 17:33:27 +00001374 File ..., line 8, in f
Jim Fulton07a349c2004-08-22 14:10:00 +00001375 Failed example:
Guido van Rossum805365e2007-05-07 22:24:25 +00001376 print(list(range(10))) # Should fail: no ellipsis
Jim Fulton07a349c2004-08-22 14:10:00 +00001377 Expected:
1378 [0, 1, ..., 9]
1379 Got:
1380 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
Christian Heimes25bb7832008-01-11 16:17:00 +00001381 TestResults(failed=2, attempted=3)
Tim Peters8485b562004-08-04 18:46:34 +00001382
Edward Loper74bca7a2004-08-12 02:27:44 +00001383Multiple options may be modified by a single option directive. They
1384may be separated by whitespace, commas, or both:
Tim Peters8485b562004-08-04 18:46:34 +00001385
1386 >>> def f(x): r'''
Guido van Rossum805365e2007-05-07 22:24:25 +00001387 ... >>> print(list(range(10))) # Should fail
Tim Peters8485b562004-08-04 18:46:34 +00001388 ... [0, 1, ..., 9]
Guido van Rossum805365e2007-05-07 22:24:25 +00001389 ... >>> print(list(range(10))) # Should succeed
Edward Loper74bca7a2004-08-12 02:27:44 +00001390 ... ... # doctest: +ELLIPSIS +NORMALIZE_WHITESPACE
Tim Peters8485b562004-08-04 18:46:34 +00001391 ... [0, 1, ..., 9]
1392 ... '''
1393 >>> test = doctest.DocTestFinder().find(f)[0]
1394 >>> doctest.DocTestRunner(verbose=False).run(test)
Tim Peters17b56372004-09-11 17:33:27 +00001395 ... # doctest: +ELLIPSIS
Tim Peters8485b562004-08-04 18:46:34 +00001396 **********************************************************************
Tim Peters17b56372004-09-11 17:33:27 +00001397 File ..., line 2, in f
Jim Fulton07a349c2004-08-22 14:10:00 +00001398 Failed example:
Guido van Rossum805365e2007-05-07 22:24:25 +00001399 print(list(range(10))) # Should fail
Jim Fulton07a349c2004-08-22 14:10:00 +00001400 Expected:
1401 [0, 1, ..., 9]
1402 Got:
1403 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
Christian Heimes25bb7832008-01-11 16:17:00 +00001404 TestResults(failed=1, attempted=2)
Edward Loper74bca7a2004-08-12 02:27:44 +00001405
1406 >>> def f(x): r'''
Guido van Rossum805365e2007-05-07 22:24:25 +00001407 ... >>> print(list(range(10))) # Should fail
Edward Loper74bca7a2004-08-12 02:27:44 +00001408 ... [0, 1, ..., 9]
Guido van Rossum805365e2007-05-07 22:24:25 +00001409 ... >>> print(list(range(10))) # Should succeed
Edward Loper74bca7a2004-08-12 02:27:44 +00001410 ... ... # doctest: +ELLIPSIS,+NORMALIZE_WHITESPACE
1411 ... [0, 1, ..., 9]
1412 ... '''
1413 >>> test = doctest.DocTestFinder().find(f)[0]
1414 >>> doctest.DocTestRunner(verbose=False).run(test)
Tim Peters17b56372004-09-11 17:33:27 +00001415 ... # doctest: +ELLIPSIS
Edward Loper74bca7a2004-08-12 02:27:44 +00001416 **********************************************************************
Tim Peters17b56372004-09-11 17:33:27 +00001417 File ..., line 2, in f
Jim Fulton07a349c2004-08-22 14:10:00 +00001418 Failed example:
Guido van Rossum805365e2007-05-07 22:24:25 +00001419 print(list(range(10))) # Should fail
Jim Fulton07a349c2004-08-22 14:10:00 +00001420 Expected:
1421 [0, 1, ..., 9]
1422 Got:
1423 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
Christian Heimes25bb7832008-01-11 16:17:00 +00001424 TestResults(failed=1, attempted=2)
Edward Loper74bca7a2004-08-12 02:27:44 +00001425
1426 >>> def f(x): r'''
Guido van Rossum805365e2007-05-07 22:24:25 +00001427 ... >>> print(list(range(10))) # Should fail
Edward Loper74bca7a2004-08-12 02:27:44 +00001428 ... [0, 1, ..., 9]
Guido van Rossum805365e2007-05-07 22:24:25 +00001429 ... >>> print(list(range(10))) # Should succeed
Edward Loper74bca7a2004-08-12 02:27:44 +00001430 ... ... # doctest: +ELLIPSIS, +NORMALIZE_WHITESPACE
1431 ... [0, 1, ..., 9]
1432 ... '''
1433 >>> test = doctest.DocTestFinder().find(f)[0]
1434 >>> doctest.DocTestRunner(verbose=False).run(test)
Tim Peters17b56372004-09-11 17:33:27 +00001435 ... # doctest: +ELLIPSIS
Edward Loper74bca7a2004-08-12 02:27:44 +00001436 **********************************************************************
Tim Peters17b56372004-09-11 17:33:27 +00001437 File ..., line 2, in f
Jim Fulton07a349c2004-08-22 14:10:00 +00001438 Failed example:
Guido van Rossum805365e2007-05-07 22:24:25 +00001439 print(list(range(10))) # Should fail
Jim Fulton07a349c2004-08-22 14:10:00 +00001440 Expected:
1441 [0, 1, ..., 9]
1442 Got:
1443 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
Christian Heimes25bb7832008-01-11 16:17:00 +00001444 TestResults(failed=1, attempted=2)
Edward Loper74bca7a2004-08-12 02:27:44 +00001445
1446The option directive may be put on the line following the source, as
1447long as a continuation prompt is used:
1448
1449 >>> def f(x): r'''
Guido van Rossum805365e2007-05-07 22:24:25 +00001450 ... >>> print(list(range(10)))
Edward Loper74bca7a2004-08-12 02:27:44 +00001451 ... ... # doctest: +ELLIPSIS
1452 ... [0, 1, ..., 9]
1453 ... '''
1454 >>> test = doctest.DocTestFinder().find(f)[0]
1455 >>> doctest.DocTestRunner(verbose=False).run(test)
Christian Heimes25bb7832008-01-11 16:17:00 +00001456 TestResults(failed=0, attempted=1)
Edward Loper8e4a34b2004-08-12 02:34:27 +00001457
Edward Loper74bca7a2004-08-12 02:27:44 +00001458For examples with multi-line source, the option directive may appear
1459at the end of any line:
1460
1461 >>> def f(x): r'''
1462 ... >>> for x in range(10): # doctest: +ELLIPSIS
Guido van Rossum805365e2007-05-07 22:24:25 +00001463 ... ... print(' ', x, end='', sep='')
1464 ... 0 1 2 ... 9
Edward Loper74bca7a2004-08-12 02:27:44 +00001465 ...
1466 ... >>> for x in range(10):
Guido van Rossum805365e2007-05-07 22:24:25 +00001467 ... ... print(' ', x, end='', sep='') # doctest: +ELLIPSIS
1468 ... 0 1 2 ... 9
Edward Loper74bca7a2004-08-12 02:27:44 +00001469 ... '''
1470 >>> test = doctest.DocTestFinder().find(f)[0]
1471 >>> doctest.DocTestRunner(verbose=False).run(test)
Christian Heimes25bb7832008-01-11 16:17:00 +00001472 TestResults(failed=0, attempted=2)
Edward Loper74bca7a2004-08-12 02:27:44 +00001473
1474If more than one line of an example with multi-line source has an
1475option directive, then they are combined:
1476
1477 >>> def f(x): r'''
1478 ... Should fail (option directive not on the last line):
1479 ... >>> for x in range(10): # doctest: +ELLIPSIS
Guido van Rossumbdc36e42007-02-09 22:43:47 +00001480 ... ... print(x, end=' ') # doctest: +NORMALIZE_WHITESPACE
Guido van Rossumd8faa362007-04-27 19:54:29 +00001481 ... 0 1 2...9
Edward Loper74bca7a2004-08-12 02:27:44 +00001482 ... '''
1483 >>> test = doctest.DocTestFinder().find(f)[0]
1484 >>> doctest.DocTestRunner(verbose=False).run(test)
Christian Heimes25bb7832008-01-11 16:17:00 +00001485 TestResults(failed=0, attempted=1)
Edward Loper74bca7a2004-08-12 02:27:44 +00001486
1487It is an error to have a comment of the form ``# doctest:`` that is
1488*not* followed by words of the form ``+OPTION`` or ``-OPTION``, where
1489``OPTION`` is an option that has been registered with
1490`register_option`:
1491
1492 >>> # Error: Option not registered
Guido van Rossumbdc36e42007-02-09 22:43:47 +00001493 >>> s = '>>> print(12) #doctest: +BADOPTION'
Edward Loper74bca7a2004-08-12 02:27:44 +00001494 >>> test = doctest.DocTestParser().get_doctest(s, {}, 's', 's.py', 0)
1495 Traceback (most recent call last):
1496 ValueError: line 1 of the doctest for s has an invalid option: '+BADOPTION'
1497
1498 >>> # Error: No + or - prefix
Guido van Rossumbdc36e42007-02-09 22:43:47 +00001499 >>> s = '>>> print(12) #doctest: ELLIPSIS'
Edward Loper74bca7a2004-08-12 02:27:44 +00001500 >>> test = doctest.DocTestParser().get_doctest(s, {}, 's', 's.py', 0)
1501 Traceback (most recent call last):
1502 ValueError: line 1 of the doctest for s has an invalid option: 'ELLIPSIS'
1503
1504It is an error to use an option directive on a line that contains no
1505source:
1506
1507 >>> s = '>>> # doctest: +ELLIPSIS'
1508 >>> test = doctest.DocTestParser().get_doctest(s, {}, 's', 's.py', 0)
1509 Traceback (most recent call last):
1510 ValueError: line 0 of the doctest for s has an option directive on a line with no example: '# doctest: +ELLIPSIS'
Tim Peters8485b562004-08-04 18:46:34 +00001511"""
1512
1513def test_testsource(): r"""
1514Unit tests for `testsource()`.
1515
1516The testsource() function takes a module and a name, finds the (first)
Tim Peters19397e52004-08-06 22:02:59 +00001517test with that name in that module, and converts it to a script. The
1518example code is converted to regular Python code. The surrounding
1519words and expected output are converted to comments:
Tim Peters8485b562004-08-04 18:46:34 +00001520
1521 >>> import test.test_doctest
1522 >>> name = 'test.test_doctest.sample_func'
Guido van Rossum7131f842007-02-09 20:13:25 +00001523 >>> print(doctest.testsource(test.test_doctest, name))
Edward Lopera5db6002004-08-12 02:41:30 +00001524 # Blah blah
Tim Peters19397e52004-08-06 22:02:59 +00001525 #
Guido van Rossumbdc36e42007-02-09 22:43:47 +00001526 print(sample_func(22))
Tim Peters8485b562004-08-04 18:46:34 +00001527 # Expected:
Edward Lopera5db6002004-08-12 02:41:30 +00001528 ## 44
Tim Peters19397e52004-08-06 22:02:59 +00001529 #
Edward Lopera5db6002004-08-12 02:41:30 +00001530 # Yee ha!
Georg Brandlecf93c72005-06-26 23:09:51 +00001531 <BLANKLINE>
Tim Peters8485b562004-08-04 18:46:34 +00001532
1533 >>> name = 'test.test_doctest.SampleNewStyleClass'
Guido van Rossum7131f842007-02-09 20:13:25 +00001534 >>> print(doctest.testsource(test.test_doctest, name))
Guido van Rossumbdc36e42007-02-09 22:43:47 +00001535 print('1\n2\n3')
Tim Peters8485b562004-08-04 18:46:34 +00001536 # Expected:
Edward Lopera5db6002004-08-12 02:41:30 +00001537 ## 1
1538 ## 2
1539 ## 3
Georg Brandlecf93c72005-06-26 23:09:51 +00001540 <BLANKLINE>
Tim Peters8485b562004-08-04 18:46:34 +00001541
1542 >>> name = 'test.test_doctest.SampleClass.a_classmethod'
Guido van Rossum7131f842007-02-09 20:13:25 +00001543 >>> print(doctest.testsource(test.test_doctest, name))
Guido van Rossumbdc36e42007-02-09 22:43:47 +00001544 print(SampleClass.a_classmethod(10))
Tim Peters8485b562004-08-04 18:46:34 +00001545 # Expected:
Edward Lopera5db6002004-08-12 02:41:30 +00001546 ## 12
Guido van Rossumbdc36e42007-02-09 22:43:47 +00001547 print(SampleClass(0).a_classmethod(10))
Tim Peters8485b562004-08-04 18:46:34 +00001548 # Expected:
Edward Lopera5db6002004-08-12 02:41:30 +00001549 ## 12
Georg Brandlecf93c72005-06-26 23:09:51 +00001550 <BLANKLINE>
Tim Peters8485b562004-08-04 18:46:34 +00001551"""
1552
1553def test_debug(): r"""
1554
1555Create a docstring that we want to debug:
1556
1557 >>> s = '''
1558 ... >>> x = 12
Guido van Rossumbdc36e42007-02-09 22:43:47 +00001559 ... >>> print(x)
Tim Peters8485b562004-08-04 18:46:34 +00001560 ... 12
1561 ... '''
1562
1563Create some fake stdin input, to feed to the debugger:
1564
Tim Peters8485b562004-08-04 18:46:34 +00001565 >>> real_stdin = sys.stdin
Guido van Rossumbdc36e42007-02-09 22:43:47 +00001566 >>> sys.stdin = _FakeInput(['next', 'print(x)', 'continue'])
Tim Peters8485b562004-08-04 18:46:34 +00001567
1568Run the debugger on the docstring, and then restore sys.stdin.
1569
Edward Loper2de91ba2004-08-27 02:07:46 +00001570 >>> try: doctest.debug_src(s)
1571 ... finally: sys.stdin = real_stdin
Jeremy Hylton3e0055f2005-10-20 19:59:25 +00001572 > <string>(1)<module>()
Edward Loper2de91ba2004-08-27 02:07:46 +00001573 (Pdb) next
1574 12
Tim Peters8485b562004-08-04 18:46:34 +00001575 --Return--
Jeremy Hylton3e0055f2005-10-20 19:59:25 +00001576 > <string>(1)<module>()->None
Guido van Rossumbdc36e42007-02-09 22:43:47 +00001577 (Pdb) print(x)
Edward Loper2de91ba2004-08-27 02:07:46 +00001578 12
1579 (Pdb) continue
Tim Peters8485b562004-08-04 18:46:34 +00001580
1581"""
1582
Jim Fulton356fd192004-08-09 11:34:47 +00001583def test_pdb_set_trace():
Tim Peters50c6bdb2004-11-08 22:07:37 +00001584 """Using pdb.set_trace from a doctest.
Jim Fulton356fd192004-08-09 11:34:47 +00001585
Tim Peters413ced62004-08-09 15:43:47 +00001586 You can use pdb.set_trace from a doctest. To do so, you must
Jim Fulton356fd192004-08-09 11:34:47 +00001587 retrieve the set_trace function from the pdb module at the time
Tim Peters413ced62004-08-09 15:43:47 +00001588 you use it. The doctest module changes sys.stdout so that it can
1589 capture program output. It also temporarily replaces pdb.set_trace
1590 with a version that restores stdout. This is necessary for you to
Jim Fulton356fd192004-08-09 11:34:47 +00001591 see debugger output.
1592
1593 >>> doc = '''
1594 ... >>> x = 42
1595 ... >>> import pdb; pdb.set_trace()
1596 ... '''
Edward Lopera1ef6112004-08-09 16:14:41 +00001597 >>> parser = doctest.DocTestParser()
1598 >>> test = parser.get_doctest(doc, {}, "foo", "foo.py", 0)
Jim Fulton356fd192004-08-09 11:34:47 +00001599 >>> runner = doctest.DocTestRunner(verbose=False)
1600
1601 To demonstrate this, we'll create a fake standard input that
1602 captures our debugger input:
1603
1604 >>> import tempfile
Edward Loper2de91ba2004-08-27 02:07:46 +00001605 >>> real_stdin = sys.stdin
1606 >>> sys.stdin = _FakeInput([
Guido van Rossumbdc36e42007-02-09 22:43:47 +00001607 ... 'print(x)', # print data defined by the example
Jim Fulton356fd192004-08-09 11:34:47 +00001608 ... 'continue', # stop debugging
Edward Loper2de91ba2004-08-27 02:07:46 +00001609 ... ''])
Jim Fulton356fd192004-08-09 11:34:47 +00001610
Edward Loper2de91ba2004-08-27 02:07:46 +00001611 >>> try: runner.run(test)
1612 ... finally: sys.stdin = real_stdin
Jim Fulton356fd192004-08-09 11:34:47 +00001613 --Return--
Jeremy Hylton3e0055f2005-10-20 19:59:25 +00001614 > <doctest foo[1]>(1)<module>()->None
Edward Loper2de91ba2004-08-27 02:07:46 +00001615 -> import pdb; pdb.set_trace()
Guido van Rossumbdc36e42007-02-09 22:43:47 +00001616 (Pdb) print(x)
Edward Loper2de91ba2004-08-27 02:07:46 +00001617 42
1618 (Pdb) continue
Christian Heimes25bb7832008-01-11 16:17:00 +00001619 TestResults(failed=0, attempted=2)
Jim Fulton356fd192004-08-09 11:34:47 +00001620
1621 You can also put pdb.set_trace in a function called from a test:
1622
1623 >>> def calls_set_trace():
1624 ... y=2
1625 ... import pdb; pdb.set_trace()
1626
1627 >>> doc = '''
1628 ... >>> x=1
1629 ... >>> calls_set_trace()
1630 ... '''
Edward Lopera1ef6112004-08-09 16:14:41 +00001631 >>> test = parser.get_doctest(doc, globals(), "foo", "foo.py", 0)
Edward Loper2de91ba2004-08-27 02:07:46 +00001632 >>> real_stdin = sys.stdin
1633 >>> sys.stdin = _FakeInput([
Guido van Rossumbdc36e42007-02-09 22:43:47 +00001634 ... 'print(y)', # print data defined in the function
Jim Fulton356fd192004-08-09 11:34:47 +00001635 ... 'up', # out of function
Guido van Rossumbdc36e42007-02-09 22:43:47 +00001636 ... 'print(x)', # print data defined by the example
Jim Fulton356fd192004-08-09 11:34:47 +00001637 ... 'continue', # stop debugging
Edward Loper2de91ba2004-08-27 02:07:46 +00001638 ... ''])
Jim Fulton356fd192004-08-09 11:34:47 +00001639
Tim Peters50c6bdb2004-11-08 22:07:37 +00001640 >>> try:
1641 ... runner.run(test)
1642 ... finally:
1643 ... sys.stdin = real_stdin
Jim Fulton356fd192004-08-09 11:34:47 +00001644 --Return--
Edward Loper2de91ba2004-08-27 02:07:46 +00001645 > <doctest test.test_doctest.test_pdb_set_trace[8]>(3)calls_set_trace()->None
1646 -> import pdb; pdb.set_trace()
Guido van Rossumbdc36e42007-02-09 22:43:47 +00001647 (Pdb) print(y)
Edward Loper2de91ba2004-08-27 02:07:46 +00001648 2
1649 (Pdb) up
Jeremy Hylton3e0055f2005-10-20 19:59:25 +00001650 > <doctest foo[1]>(1)<module>()
Edward Loper2de91ba2004-08-27 02:07:46 +00001651 -> calls_set_trace()
Guido van Rossumbdc36e42007-02-09 22:43:47 +00001652 (Pdb) print(x)
Edward Loper2de91ba2004-08-27 02:07:46 +00001653 1
1654 (Pdb) continue
Christian Heimes25bb7832008-01-11 16:17:00 +00001655 TestResults(failed=0, attempted=2)
Edward Loper2de91ba2004-08-27 02:07:46 +00001656
1657 During interactive debugging, source code is shown, even for
1658 doctest examples:
1659
1660 >>> doc = '''
1661 ... >>> def f(x):
1662 ... ... g(x*2)
1663 ... >>> def g(x):
Guido van Rossumbdc36e42007-02-09 22:43:47 +00001664 ... ... print(x+3)
Edward Loper2de91ba2004-08-27 02:07:46 +00001665 ... ... import pdb; pdb.set_trace()
1666 ... >>> f(3)
1667 ... '''
1668 >>> test = parser.get_doctest(doc, globals(), "foo", "foo.py", 0)
1669 >>> real_stdin = sys.stdin
1670 >>> sys.stdin = _FakeInput([
1671 ... 'list', # list source from example 2
1672 ... 'next', # return from g()
1673 ... 'list', # list source from example 1
1674 ... 'next', # return from f()
1675 ... 'list', # list source from example 3
1676 ... 'continue', # stop debugging
1677 ... ''])
1678 >>> try: runner.run(test)
1679 ... finally: sys.stdin = real_stdin
1680 ... # doctest: +NORMALIZE_WHITESPACE
1681 --Return--
1682 > <doctest foo[1]>(3)g()->None
1683 -> import pdb; pdb.set_trace()
1684 (Pdb) list
1685 1 def g(x):
Guido van Rossumbdc36e42007-02-09 22:43:47 +00001686 2 print(x+3)
Edward Loper2de91ba2004-08-27 02:07:46 +00001687 3 -> import pdb; pdb.set_trace()
1688 [EOF]
1689 (Pdb) next
1690 --Return--
1691 > <doctest foo[0]>(2)f()->None
1692 -> g(x*2)
1693 (Pdb) list
1694 1 def f(x):
1695 2 -> g(x*2)
1696 [EOF]
1697 (Pdb) next
1698 --Return--
Jeremy Hylton3e0055f2005-10-20 19:59:25 +00001699 > <doctest foo[2]>(1)<module>()->None
Edward Loper2de91ba2004-08-27 02:07:46 +00001700 -> f(3)
1701 (Pdb) list
1702 1 -> f(3)
1703 [EOF]
1704 (Pdb) continue
1705 **********************************************************************
1706 File "foo.py", line 7, in foo
1707 Failed example:
1708 f(3)
1709 Expected nothing
1710 Got:
1711 9
Christian Heimes25bb7832008-01-11 16:17:00 +00001712 TestResults(failed=1, attempted=3)
Jim Fulton356fd192004-08-09 11:34:47 +00001713 """
1714
Tim Peters50c6bdb2004-11-08 22:07:37 +00001715def test_pdb_set_trace_nested():
1716 """This illustrates more-demanding use of set_trace with nested functions.
1717
1718 >>> class C(object):
1719 ... def calls_set_trace(self):
1720 ... y = 1
1721 ... import pdb; pdb.set_trace()
1722 ... self.f1()
1723 ... y = 2
1724 ... def f1(self):
1725 ... x = 1
1726 ... self.f2()
1727 ... x = 2
1728 ... def f2(self):
1729 ... z = 1
1730 ... z = 2
1731
1732 >>> calls_set_trace = C().calls_set_trace
1733
1734 >>> doc = '''
1735 ... >>> a = 1
1736 ... >>> calls_set_trace()
1737 ... '''
1738 >>> parser = doctest.DocTestParser()
1739 >>> runner = doctest.DocTestRunner(verbose=False)
1740 >>> test = parser.get_doctest(doc, globals(), "foo", "foo.py", 0)
1741 >>> real_stdin = sys.stdin
1742 >>> sys.stdin = _FakeInput([
Guido van Rossumbdc36e42007-02-09 22:43:47 +00001743 ... 'print(y)', # print data defined in the function
1744 ... 'step', 'step', 'step', 'step', 'step', 'step', 'print(z)',
1745 ... 'up', 'print(x)',
1746 ... 'up', 'print(y)',
1747 ... 'up', 'print(foo)',
Tim Peters50c6bdb2004-11-08 22:07:37 +00001748 ... 'continue', # stop debugging
1749 ... ''])
1750
1751 >>> try:
1752 ... runner.run(test)
1753 ... finally:
1754 ... sys.stdin = real_stdin
Guido van Rossum4a625c32007-09-08 16:05:25 +00001755 ... # doctest: +REPORT_NDIFF
Tim Peters50c6bdb2004-11-08 22:07:37 +00001756 > <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(5)calls_set_trace()
1757 -> self.f1()
Guido van Rossumbdc36e42007-02-09 22:43:47 +00001758 (Pdb) print(y)
Tim Peters50c6bdb2004-11-08 22:07:37 +00001759 1
1760 (Pdb) step
1761 --Call--
1762 > <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(7)f1()
1763 -> def f1(self):
1764 (Pdb) step
1765 > <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(8)f1()
1766 -> x = 1
1767 (Pdb) step
1768 > <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(9)f1()
1769 -> self.f2()
1770 (Pdb) step
1771 --Call--
1772 > <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(11)f2()
1773 -> def f2(self):
1774 (Pdb) step
1775 > <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(12)f2()
1776 -> z = 1
1777 (Pdb) step
1778 > <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(13)f2()
1779 -> z = 2
Guido van Rossumbdc36e42007-02-09 22:43:47 +00001780 (Pdb) print(z)
Tim Peters50c6bdb2004-11-08 22:07:37 +00001781 1
1782 (Pdb) up
1783 > <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(9)f1()
1784 -> self.f2()
Guido van Rossumbdc36e42007-02-09 22:43:47 +00001785 (Pdb) print(x)
Tim Peters50c6bdb2004-11-08 22:07:37 +00001786 1
1787 (Pdb) up
1788 > <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(5)calls_set_trace()
1789 -> self.f1()
Guido van Rossumbdc36e42007-02-09 22:43:47 +00001790 (Pdb) print(y)
Tim Peters50c6bdb2004-11-08 22:07:37 +00001791 1
1792 (Pdb) up
Jeremy Hylton3e0055f2005-10-20 19:59:25 +00001793 > <doctest foo[1]>(1)<module>()
Tim Peters50c6bdb2004-11-08 22:07:37 +00001794 -> calls_set_trace()
Guido van Rossumbdc36e42007-02-09 22:43:47 +00001795 (Pdb) print(foo)
Guido van Rossumfd4a7de2007-09-05 03:26:38 +00001796 *** NameError: NameError("name 'foo' is not defined",)
Tim Peters50c6bdb2004-11-08 22:07:37 +00001797 (Pdb) continue
Christian Heimes25bb7832008-01-11 16:17:00 +00001798 TestResults(failed=0, attempted=2)
Tim Peters50c6bdb2004-11-08 22:07:37 +00001799"""
1800
Tim Peters19397e52004-08-06 22:02:59 +00001801def test_DocTestSuite():
Tim Peters1e277ee2004-08-07 05:37:52 +00001802 """DocTestSuite creates a unittest test suite from a doctest.
Tim Peters19397e52004-08-06 22:02:59 +00001803
1804 We create a Suite by providing a module. A module can be provided
1805 by passing a module object:
1806
1807 >>> import unittest
1808 >>> import test.sample_doctest
1809 >>> suite = doctest.DocTestSuite(test.sample_doctest)
1810 >>> suite.run(unittest.TestResult())
Tim Peters1e277ee2004-08-07 05:37:52 +00001811 <unittest.TestResult run=9 errors=0 failures=4>
Tim Peters19397e52004-08-06 22:02:59 +00001812
1813 We can also supply the module by name:
1814
1815 >>> suite = doctest.DocTestSuite('test.sample_doctest')
1816 >>> suite.run(unittest.TestResult())
Tim Peters1e277ee2004-08-07 05:37:52 +00001817 <unittest.TestResult run=9 errors=0 failures=4>
Tim Peters19397e52004-08-06 22:02:59 +00001818
1819 We can use the current module:
1820
1821 >>> suite = test.sample_doctest.test_suite()
1822 >>> suite.run(unittest.TestResult())
Tim Peters1e277ee2004-08-07 05:37:52 +00001823 <unittest.TestResult run=9 errors=0 failures=4>
Tim Peters19397e52004-08-06 22:02:59 +00001824
1825 We can supply global variables. If we pass globs, they will be
1826 used instead of the module globals. Here we'll pass an empty
1827 globals, triggering an extra error:
1828
1829 >>> suite = doctest.DocTestSuite('test.sample_doctest', globs={})
1830 >>> suite.run(unittest.TestResult())
Tim Peters1e277ee2004-08-07 05:37:52 +00001831 <unittest.TestResult run=9 errors=0 failures=5>
Tim Peters19397e52004-08-06 22:02:59 +00001832
1833 Alternatively, we can provide extra globals. Here we'll make an
1834 error go away by providing an extra global variable:
1835
1836 >>> suite = doctest.DocTestSuite('test.sample_doctest',
1837 ... extraglobs={'y': 1})
1838 >>> suite.run(unittest.TestResult())
Tim Peters1e277ee2004-08-07 05:37:52 +00001839 <unittest.TestResult run=9 errors=0 failures=3>
Tim Peters19397e52004-08-06 22:02:59 +00001840
1841 You can pass option flags. Here we'll cause an extra error
1842 by disabling the blank-line feature:
1843
1844 >>> suite = doctest.DocTestSuite('test.sample_doctest',
Tim Peters1e277ee2004-08-07 05:37:52 +00001845 ... optionflags=doctest.DONT_ACCEPT_BLANKLINE)
Tim Peters19397e52004-08-06 22:02:59 +00001846 >>> suite.run(unittest.TestResult())
Tim Peters1e277ee2004-08-07 05:37:52 +00001847 <unittest.TestResult run=9 errors=0 failures=5>
Tim Peters19397e52004-08-06 22:02:59 +00001848
Tim Peters1e277ee2004-08-07 05:37:52 +00001849 You can supply setUp and tearDown functions:
Tim Peters19397e52004-08-06 22:02:59 +00001850
Jim Fultonf54bad42004-08-28 14:57:56 +00001851 >>> def setUp(t):
Tim Peters19397e52004-08-06 22:02:59 +00001852 ... import test.test_doctest
1853 ... test.test_doctest.sillySetup = True
1854
Jim Fultonf54bad42004-08-28 14:57:56 +00001855 >>> def tearDown(t):
Tim Peters19397e52004-08-06 22:02:59 +00001856 ... import test.test_doctest
1857 ... del test.test_doctest.sillySetup
1858
1859 Here, we installed a silly variable that the test expects:
1860
1861 >>> suite = doctest.DocTestSuite('test.sample_doctest',
1862 ... setUp=setUp, tearDown=tearDown)
1863 >>> suite.run(unittest.TestResult())
Tim Peters1e277ee2004-08-07 05:37:52 +00001864 <unittest.TestResult run=9 errors=0 failures=3>
Tim Peters19397e52004-08-06 22:02:59 +00001865
1866 But the tearDown restores sanity:
1867
1868 >>> import test.test_doctest
1869 >>> test.test_doctest.sillySetup
1870 Traceback (most recent call last):
1871 ...
1872 AttributeError: 'module' object has no attribute 'sillySetup'
1873
Jim Fultonf54bad42004-08-28 14:57:56 +00001874 The setUp and tearDown funtions are passed test objects. Here
1875 we'll use the setUp function to supply the missing variable y:
1876
1877 >>> def setUp(test):
1878 ... test.globs['y'] = 1
1879
1880 >>> suite = doctest.DocTestSuite('test.sample_doctest', setUp=setUp)
1881 >>> suite.run(unittest.TestResult())
1882 <unittest.TestResult run=9 errors=0 failures=3>
1883
1884 Here, we didn't need to use a tearDown function because we
1885 modified the test globals, which are a copy of the
1886 sample_doctest module dictionary. The test globals are
1887 automatically cleared for us after a test.
Tim Peters19397e52004-08-06 22:02:59 +00001888 """
1889
1890def test_DocFileSuite():
1891 """We can test tests found in text files using a DocFileSuite.
1892
1893 We create a suite by providing the names of one or more text
1894 files that include examples:
1895
1896 >>> import unittest
1897 >>> suite = doctest.DocFileSuite('test_doctest.txt',
Thomas Wouters4d70c3d2006-06-08 14:42:34 +00001898 ... 'test_doctest2.txt',
1899 ... 'test_doctest4.txt')
Tim Peters19397e52004-08-06 22:02:59 +00001900 >>> suite.run(unittest.TestResult())
Martin v. Löwisb1a9f272007-07-20 07:13:39 +00001901 <unittest.TestResult run=3 errors=0 failures=2>
Tim Peters19397e52004-08-06 22:02:59 +00001902
1903 The test files are looked for in the directory containing the
1904 calling module. A package keyword argument can be provided to
1905 specify a different relative location.
1906
1907 >>> import unittest
1908 >>> suite = doctest.DocFileSuite('test_doctest.txt',
1909 ... 'test_doctest2.txt',
Thomas Wouters4d70c3d2006-06-08 14:42:34 +00001910 ... 'test_doctest4.txt',
Tim Peters19397e52004-08-06 22:02:59 +00001911 ... package='test')
1912 >>> suite.run(unittest.TestResult())
Martin v. Löwisb1a9f272007-07-20 07:13:39 +00001913 <unittest.TestResult run=3 errors=0 failures=2>
Tim Peters19397e52004-08-06 22:02:59 +00001914
Guido van Rossumcd4d4522007-11-22 00:30:02 +00001915 Support for using a package's __loader__.get_data() is also
1916 provided.
1917
1918 >>> import unittest, pkgutil, test
Guido van Rossum0d3fb8a2007-11-26 23:23:18 +00001919 >>> added_loader = False
Guido van Rossumcd4d4522007-11-22 00:30:02 +00001920 >>> if not hasattr(test, '__loader__'):
1921 ... test.__loader__ = pkgutil.get_loader(test)
1922 ... added_loader = True
1923 >>> try:
1924 ... suite = doctest.DocFileSuite('test_doctest.txt',
1925 ... 'test_doctest2.txt',
1926 ... 'test_doctest4.txt',
1927 ... package='test')
1928 ... suite.run(unittest.TestResult())
1929 ... finally:
1930 ... if added_loader:
1931 ... del test.__loader__
1932 <unittest.TestResult run=3 errors=0 failures=2>
1933
Edward Loper0273f5b2004-09-18 20:27:04 +00001934 '/' should be used as a path separator. It will be converted
1935 to a native separator at run time:
Tim Peters19397e52004-08-06 22:02:59 +00001936
1937 >>> suite = doctest.DocFileSuite('../test/test_doctest.txt')
1938 >>> suite.run(unittest.TestResult())
1939 <unittest.TestResult run=1 errors=0 failures=1>
1940
Edward Loper0273f5b2004-09-18 20:27:04 +00001941 If DocFileSuite is used from an interactive session, then files
1942 are resolved relative to the directory of sys.argv[0]:
1943
Christian Heimes45f9af32007-11-27 21:50:00 +00001944 >>> import types, os.path, test.test_doctest
Edward Loper0273f5b2004-09-18 20:27:04 +00001945 >>> save_argv = sys.argv
1946 >>> sys.argv = [test.test_doctest.__file__]
1947 >>> suite = doctest.DocFileSuite('test_doctest.txt',
Christian Heimes45f9af32007-11-27 21:50:00 +00001948 ... package=types.ModuleType('__main__'))
Edward Loper0273f5b2004-09-18 20:27:04 +00001949 >>> sys.argv = save_argv
1950
Edward Loper052d0cd2004-09-19 17:19:33 +00001951 By setting `module_relative=False`, os-specific paths may be
1952 used (including absolute paths and paths relative to the
1953 working directory):
Edward Loper0273f5b2004-09-18 20:27:04 +00001954
1955 >>> # Get the absolute path of the test package.
1956 >>> test_doctest_path = os.path.abspath(test.test_doctest.__file__)
1957 >>> test_pkg_path = os.path.split(test_doctest_path)[0]
1958
1959 >>> # Use it to find the absolute path of test_doctest.txt.
1960 >>> test_file = os.path.join(test_pkg_path, 'test_doctest.txt')
1961
Edward Loper052d0cd2004-09-19 17:19:33 +00001962 >>> suite = doctest.DocFileSuite(test_file, module_relative=False)
Edward Loper0273f5b2004-09-18 20:27:04 +00001963 >>> suite.run(unittest.TestResult())
1964 <unittest.TestResult run=1 errors=0 failures=1>
1965
Edward Loper052d0cd2004-09-19 17:19:33 +00001966 It is an error to specify `package` when `module_relative=False`:
1967
1968 >>> suite = doctest.DocFileSuite(test_file, module_relative=False,
1969 ... package='test')
1970 Traceback (most recent call last):
1971 ValueError: Package may only be specified for module-relative paths.
1972
Tim Peters19397e52004-08-06 22:02:59 +00001973 You can specify initial global variables:
1974
1975 >>> suite = doctest.DocFileSuite('test_doctest.txt',
1976 ... 'test_doctest2.txt',
Thomas Wouters4d70c3d2006-06-08 14:42:34 +00001977 ... 'test_doctest4.txt',
Tim Peters19397e52004-08-06 22:02:59 +00001978 ... globs={'favorite_color': 'blue'})
1979 >>> suite.run(unittest.TestResult())
Martin v. Löwisb1a9f272007-07-20 07:13:39 +00001980 <unittest.TestResult run=3 errors=0 failures=1>
Tim Peters19397e52004-08-06 22:02:59 +00001981
1982 In this case, we supplied a missing favorite color. You can
1983 provide doctest options:
1984
1985 >>> suite = doctest.DocFileSuite('test_doctest.txt',
1986 ... 'test_doctest2.txt',
Thomas Wouters4d70c3d2006-06-08 14:42:34 +00001987 ... 'test_doctest4.txt',
Tim Peters19397e52004-08-06 22:02:59 +00001988 ... optionflags=doctest.DONT_ACCEPT_BLANKLINE,
1989 ... globs={'favorite_color': 'blue'})
1990 >>> suite.run(unittest.TestResult())
Martin v. Löwisb1a9f272007-07-20 07:13:39 +00001991 <unittest.TestResult run=3 errors=0 failures=2>
Tim Peters19397e52004-08-06 22:02:59 +00001992
1993 And, you can provide setUp and tearDown functions:
1994
Jim Fultonf54bad42004-08-28 14:57:56 +00001995 >>> def setUp(t):
Tim Peters19397e52004-08-06 22:02:59 +00001996 ... import test.test_doctest
1997 ... test.test_doctest.sillySetup = True
1998
Jim Fultonf54bad42004-08-28 14:57:56 +00001999 >>> def tearDown(t):
Tim Peters19397e52004-08-06 22:02:59 +00002000 ... import test.test_doctest
2001 ... del test.test_doctest.sillySetup
2002
2003 Here, we installed a silly variable that the test expects:
2004
2005 >>> suite = doctest.DocFileSuite('test_doctest.txt',
2006 ... 'test_doctest2.txt',
Thomas Wouters4d70c3d2006-06-08 14:42:34 +00002007 ... 'test_doctest4.txt',
Tim Peters19397e52004-08-06 22:02:59 +00002008 ... setUp=setUp, tearDown=tearDown)
2009 >>> suite.run(unittest.TestResult())
Martin v. Löwisb1a9f272007-07-20 07:13:39 +00002010 <unittest.TestResult run=3 errors=0 failures=1>
Tim Peters19397e52004-08-06 22:02:59 +00002011
2012 But the tearDown restores sanity:
2013
2014 >>> import test.test_doctest
2015 >>> test.test_doctest.sillySetup
2016 Traceback (most recent call last):
2017 ...
2018 AttributeError: 'module' object has no attribute 'sillySetup'
2019
Jim Fultonf54bad42004-08-28 14:57:56 +00002020 The setUp and tearDown funtions are passed test objects.
2021 Here, we'll use a setUp function to set the favorite color in
2022 test_doctest.txt:
2023
2024 >>> def setUp(test):
2025 ... test.globs['favorite_color'] = 'blue'
2026
2027 >>> suite = doctest.DocFileSuite('test_doctest.txt', setUp=setUp)
2028 >>> suite.run(unittest.TestResult())
2029 <unittest.TestResult run=1 errors=0 failures=0>
2030
2031 Here, we didn't need to use a tearDown function because we
2032 modified the test globals. The test globals are
2033 automatically cleared for us after a test.
Tim Petersdf7a2082004-08-29 00:38:17 +00002034
Fred Drake7c404a42004-12-21 23:46:34 +00002035 Tests in a file run using `DocFileSuite` can also access the
2036 `__file__` global, which is set to the name of the file
2037 containing the tests:
2038
2039 >>> suite = doctest.DocFileSuite('test_doctest3.txt')
2040 >>> suite.run(unittest.TestResult())
2041 <unittest.TestResult run=1 errors=0 failures=0>
2042
Thomas Wouters4d70c3d2006-06-08 14:42:34 +00002043 If the tests contain non-ASCII characters, we have to specify which
2044 encoding the file is encoded with. We do so by using the `encoding`
2045 parameter:
2046
2047 >>> suite = doctest.DocFileSuite('test_doctest.txt',
2048 ... 'test_doctest2.txt',
2049 ... 'test_doctest4.txt',
2050 ... encoding='utf-8')
2051 >>> suite.run(unittest.TestResult())
2052 <unittest.TestResult run=3 errors=0 failures=2>
2053
Jim Fultonf54bad42004-08-28 14:57:56 +00002054 """
Tim Peters19397e52004-08-06 22:02:59 +00002055
Jim Fulton07a349c2004-08-22 14:10:00 +00002056def test_trailing_space_in_test():
2057 """
Tim Petersa7def722004-08-23 22:13:22 +00002058 Trailing spaces in expected output are significant:
Tim Petersc6cbab02004-08-22 19:43:28 +00002059
Jim Fulton07a349c2004-08-22 14:10:00 +00002060 >>> x, y = 'foo', ''
Guido van Rossum7131f842007-02-09 20:13:25 +00002061 >>> print(x, y)
Jim Fulton07a349c2004-08-22 14:10:00 +00002062 foo \n
2063 """
Tim Peters19397e52004-08-06 22:02:59 +00002064
Jim Fultonf54bad42004-08-28 14:57:56 +00002065
2066def test_unittest_reportflags():
2067 """Default unittest reporting flags can be set to control reporting
2068
2069 Here, we'll set the REPORT_ONLY_FIRST_FAILURE option so we see
2070 only the first failure of each test. First, we'll look at the
2071 output without the flag. The file test_doctest.txt file has two
2072 tests. They both fail if blank lines are disabled:
2073
2074 >>> suite = doctest.DocFileSuite('test_doctest.txt',
2075 ... optionflags=doctest.DONT_ACCEPT_BLANKLINE)
2076 >>> import unittest
2077 >>> result = suite.run(unittest.TestResult())
Guido van Rossum7131f842007-02-09 20:13:25 +00002078 >>> print(result.failures[0][1]) # doctest: +ELLIPSIS
Jim Fultonf54bad42004-08-28 14:57:56 +00002079 Traceback ...
2080 Failed example:
2081 favorite_color
2082 ...
2083 Failed example:
2084 if 1:
2085 ...
2086
2087 Note that we see both failures displayed.
2088
2089 >>> old = doctest.set_unittest_reportflags(
2090 ... doctest.REPORT_ONLY_FIRST_FAILURE)
2091
2092 Now, when we run the test:
2093
2094 >>> result = suite.run(unittest.TestResult())
Guido van Rossum7131f842007-02-09 20:13:25 +00002095 >>> print(result.failures[0][1]) # doctest: +ELLIPSIS
Jim Fultonf54bad42004-08-28 14:57:56 +00002096 Traceback ...
2097 Failed example:
2098 favorite_color
2099 Exception raised:
2100 ...
2101 NameError: name 'favorite_color' is not defined
2102 <BLANKLINE>
2103 <BLANKLINE>
Tim Petersdf7a2082004-08-29 00:38:17 +00002104
Jim Fultonf54bad42004-08-28 14:57:56 +00002105 We get only the first failure.
2106
2107 If we give any reporting options when we set up the tests,
2108 however:
2109
2110 >>> suite = doctest.DocFileSuite('test_doctest.txt',
2111 ... optionflags=doctest.DONT_ACCEPT_BLANKLINE | doctest.REPORT_NDIFF)
2112
2113 Then the default eporting options are ignored:
2114
2115 >>> result = suite.run(unittest.TestResult())
Guido van Rossum7131f842007-02-09 20:13:25 +00002116 >>> print(result.failures[0][1]) # doctest: +ELLIPSIS
Jim Fultonf54bad42004-08-28 14:57:56 +00002117 Traceback ...
2118 Failed example:
2119 favorite_color
2120 ...
2121 Failed example:
2122 if 1:
Guido van Rossumbdc36e42007-02-09 22:43:47 +00002123 print('a')
2124 print()
2125 print('b')
Jim Fultonf54bad42004-08-28 14:57:56 +00002126 Differences (ndiff with -expected +actual):
2127 a
2128 - <BLANKLINE>
2129 +
2130 b
2131 <BLANKLINE>
2132 <BLANKLINE>
2133
2134
2135 Test runners can restore the formatting flags after they run:
2136
2137 >>> ignored = doctest.set_unittest_reportflags(old)
2138
2139 """
2140
Edward Loper052d0cd2004-09-19 17:19:33 +00002141def test_testfile(): r"""
2142Tests for the `testfile()` function. This function runs all the
2143doctest examples in a given file. In its simple invokation, it is
2144called with the name of a file, which is taken to be relative to the
2145calling module. The return value is (#failures, #tests).
2146
2147 >>> doctest.testfile('test_doctest.txt') # doctest: +ELLIPSIS
2148 **********************************************************************
2149 File "...", line 6, in test_doctest.txt
2150 Failed example:
2151 favorite_color
2152 Exception raised:
2153 ...
2154 NameError: name 'favorite_color' is not defined
2155 **********************************************************************
2156 1 items had failures:
2157 1 of 2 in test_doctest.txt
2158 ***Test Failed*** 1 failures.
Christian Heimes25bb7832008-01-11 16:17:00 +00002159 TestResults(failed=1, attempted=2)
Edward Loper052d0cd2004-09-19 17:19:33 +00002160 >>> doctest.master = None # Reset master.
2161
2162(Note: we'll be clearing doctest.master after each call to
2163`doctest.testfile`, to supress warnings about multiple tests with the
2164same name.)
2165
2166Globals may be specified with the `globs` and `extraglobs` parameters:
2167
2168 >>> globs = {'favorite_color': 'blue'}
2169 >>> doctest.testfile('test_doctest.txt', globs=globs)
Christian Heimes25bb7832008-01-11 16:17:00 +00002170 TestResults(failed=0, attempted=2)
Edward Loper052d0cd2004-09-19 17:19:33 +00002171 >>> doctest.master = None # Reset master.
2172
2173 >>> extraglobs = {'favorite_color': 'red'}
2174 >>> doctest.testfile('test_doctest.txt', globs=globs,
2175 ... extraglobs=extraglobs) # doctest: +ELLIPSIS
2176 **********************************************************************
2177 File "...", line 6, in test_doctest.txt
2178 Failed example:
2179 favorite_color
2180 Expected:
2181 'blue'
2182 Got:
2183 'red'
2184 **********************************************************************
2185 1 items had failures:
2186 1 of 2 in test_doctest.txt
2187 ***Test Failed*** 1 failures.
Christian Heimes25bb7832008-01-11 16:17:00 +00002188 TestResults(failed=1, attempted=2)
Edward Loper052d0cd2004-09-19 17:19:33 +00002189 >>> doctest.master = None # Reset master.
2190
2191The file may be made relative to a given module or package, using the
2192optional `module_relative` parameter:
2193
2194 >>> doctest.testfile('test_doctest.txt', globs=globs,
2195 ... module_relative='test')
Christian Heimes25bb7832008-01-11 16:17:00 +00002196 TestResults(failed=0, attempted=2)
Edward Loper052d0cd2004-09-19 17:19:33 +00002197 >>> doctest.master = None # Reset master.
2198
2199Verbosity can be increased with the optional `verbose` paremter:
2200
2201 >>> doctest.testfile('test_doctest.txt', globs=globs, verbose=True)
2202 Trying:
2203 favorite_color
2204 Expecting:
2205 'blue'
2206 ok
2207 Trying:
2208 if 1:
Guido van Rossumbdc36e42007-02-09 22:43:47 +00002209 print('a')
2210 print()
2211 print('b')
Edward Loper052d0cd2004-09-19 17:19:33 +00002212 Expecting:
2213 a
2214 <BLANKLINE>
2215 b
2216 ok
2217 1 items passed all tests:
2218 2 tests in test_doctest.txt
2219 2 tests in 1 items.
2220 2 passed and 0 failed.
2221 Test passed.
Christian Heimes25bb7832008-01-11 16:17:00 +00002222 TestResults(failed=0, attempted=2)
Edward Loper052d0cd2004-09-19 17:19:33 +00002223 >>> doctest.master = None # Reset master.
2224
2225The name of the test may be specified with the optional `name`
2226parameter:
2227
2228 >>> doctest.testfile('test_doctest.txt', name='newname')
2229 ... # doctest: +ELLIPSIS
2230 **********************************************************************
2231 File "...", line 6, in newname
2232 ...
Christian Heimes25bb7832008-01-11 16:17:00 +00002233 TestResults(failed=1, attempted=2)
Edward Loper052d0cd2004-09-19 17:19:33 +00002234 >>> doctest.master = None # Reset master.
2235
2236The summary report may be supressed with the optional `report`
2237parameter:
2238
2239 >>> doctest.testfile('test_doctest.txt', report=False)
2240 ... # doctest: +ELLIPSIS
2241 **********************************************************************
2242 File "...", line 6, in test_doctest.txt
2243 Failed example:
2244 favorite_color
2245 Exception raised:
2246 ...
2247 NameError: name 'favorite_color' is not defined
Christian Heimes25bb7832008-01-11 16:17:00 +00002248 TestResults(failed=1, attempted=2)
Edward Loper052d0cd2004-09-19 17:19:33 +00002249 >>> doctest.master = None # Reset master.
2250
2251The optional keyword argument `raise_on_error` can be used to raise an
2252exception on the first error (which may be useful for postmortem
2253debugging):
2254
2255 >>> doctest.testfile('test_doctest.txt', raise_on_error=True)
2256 ... # doctest: +ELLIPSIS
2257 Traceback (most recent call last):
Guido van Rossum6a2a2a02006-08-26 20:37:44 +00002258 doctest.UnexpectedException: ...
Edward Loper052d0cd2004-09-19 17:19:33 +00002259 >>> doctest.master = None # Reset master.
Thomas Wouters4d70c3d2006-06-08 14:42:34 +00002260
2261If the tests contain non-ASCII characters, the tests might fail, since
2262it's unknown which encoding is used. The encoding can be specified
2263using the optional keyword argument `encoding`:
2264
Martin v. Löwisb1a9f272007-07-20 07:13:39 +00002265 >>> doctest.testfile('test_doctest4.txt', encoding='latin-1') # doctest: +ELLIPSIS
Thomas Wouters4d70c3d2006-06-08 14:42:34 +00002266 **********************************************************************
2267 File "...", line 7, in test_doctest4.txt
2268 Failed example:
Martin v. Löwisb1a9f272007-07-20 07:13:39 +00002269 '...'
Thomas Wouters4d70c3d2006-06-08 14:42:34 +00002270 Expected:
Martin v. Löwisb1a9f272007-07-20 07:13:39 +00002271 'f\xf6\xf6'
Thomas Wouters4d70c3d2006-06-08 14:42:34 +00002272 Got:
Martin v. Löwisb1a9f272007-07-20 07:13:39 +00002273 'f\xc3\xb6\xc3\xb6'
Thomas Wouters4d70c3d2006-06-08 14:42:34 +00002274 **********************************************************************
2275 ...
2276 **********************************************************************
2277 1 items had failures:
Martin v. Löwisb1a9f272007-07-20 07:13:39 +00002278 2 of 2 in test_doctest4.txt
Thomas Wouters4d70c3d2006-06-08 14:42:34 +00002279 ***Test Failed*** 2 failures.
Christian Heimes25bb7832008-01-11 16:17:00 +00002280 TestResults(failed=2, attempted=2)
Thomas Wouters4d70c3d2006-06-08 14:42:34 +00002281 >>> doctest.master = None # Reset master.
2282
2283 >>> doctest.testfile('test_doctest4.txt', encoding='utf-8')
Christian Heimes25bb7832008-01-11 16:17:00 +00002284 TestResults(failed=0, attempted=2)
Thomas Wouters4d70c3d2006-06-08 14:42:34 +00002285 >>> doctest.master = None # Reset master.
Edward Loper052d0cd2004-09-19 17:19:33 +00002286"""
2287
Tim Peters8485b562004-08-04 18:46:34 +00002288######################################################################
2289## Main
2290######################################################################
2291
2292def test_main():
2293 # Check the doctest cases in doctest itself:
Benjamin Petersonee8712c2008-05-20 21:35:26 +00002294 support.run_doctest(doctest, verbosity=True)
Tim Peters8485b562004-08-04 18:46:34 +00002295 # Check the doctest cases defined here:
2296 from test import test_doctest
Benjamin Petersonee8712c2008-05-20 21:35:26 +00002297 support.run_doctest(test_doctest, verbosity=True)
Tim Peters8485b562004-08-04 18:46:34 +00002298
Guido van Rossum34d19282007-08-09 01:03:29 +00002299import trace, sys, re, io
Tim Peters8485b562004-08-04 18:46:34 +00002300def test_coverage(coverdir):
2301 tracer = trace.Trace(ignoredirs=[sys.prefix, sys.exec_prefix,],
2302 trace=0, count=1)
Guido van Rossume7ba4952007-06-06 23:52:48 +00002303 tracer.run('test_main()')
Tim Peters8485b562004-08-04 18:46:34 +00002304 r = tracer.results()
Guido van Rossumbe19ed72007-02-09 05:37:30 +00002305 print('Writing coverage results...')
Tim Peters8485b562004-08-04 18:46:34 +00002306 r.write_results(show_missing=True, summary=True,
2307 coverdir=coverdir)
2308
2309if __name__ == '__main__':
2310 if '-c' in sys.argv:
2311 test_coverage('/tmp/doctest.cover')
2312 else:
2313 test_main()