»Core Development>Code coverage>Lib/test/test_doctest.py

Python code coverage for Lib/test/test_doctest.py

#countcontent
1n/a"""
2n/aTest script for doctest.
3n/a"""
4n/a
5n/afrom test import support
6n/aimport doctest
7n/aimport functools
8n/aimport os
9n/aimport sys
10n/a
11n/a
12n/a# NOTE: There are some additional tests relating to interaction with
13n/a# zipimport in the test_zipimport_support test module.
14n/a
15n/a######################################################################
16n/a## Sample Objects (used by test cases)
17n/a######################################################################
18n/a
19n/adef sample_func(v):
20n/a """
21n/a Blah blah
22n/a
23n/a >>> print(sample_func(22))
24n/a 44
25n/a
26n/a Yee ha!
27n/a """
28n/a return v+v
29n/a
30n/aclass SampleClass:
31n/a """
32n/a >>> print(1)
33n/a 1
34n/a
35n/a >>> # comments get ignored. so are empty PS1 and PS2 prompts:
36n/a >>>
37n/a ...
38n/a
39n/a Multiline example:
40n/a >>> sc = SampleClass(3)
41n/a >>> for i in range(10):
42n/a ... sc = sc.double()
43n/a ... print(' ', sc.get(), sep='', end='')
44n/a 6 12 24 48 96 192 384 768 1536 3072
45n/a """
46n/a def __init__(self, val):
47n/a """
48n/a >>> print(SampleClass(12).get())
49n/a 12
50n/a """
51n/a self.val = val
52n/a
53n/a def double(self):
54n/a """
55n/a >>> print(SampleClass(12).double().get())
56n/a 24
57n/a """
58n/a return SampleClass(self.val + self.val)
59n/a
60n/a def get(self):
61n/a """
62n/a >>> print(SampleClass(-5).get())
63n/a -5
64n/a """
65n/a return self.val
66n/a
67n/a def a_staticmethod(v):
68n/a """
69n/a >>> print(SampleClass.a_staticmethod(10))
70n/a 11
71n/a """
72n/a return v+1
73n/a a_staticmethod = staticmethod(a_staticmethod)
74n/a
75n/a def a_classmethod(cls, v):
76n/a """
77n/a >>> print(SampleClass.a_classmethod(10))
78n/a 12
79n/a >>> print(SampleClass(0).a_classmethod(10))
80n/a 12
81n/a """
82n/a return v+2
83n/a a_classmethod = classmethod(a_classmethod)
84n/a
85n/a a_property = property(get, doc="""
86n/a >>> print(SampleClass(22).a_property)
87n/a 22
88n/a """)
89n/a
90n/a class NestedClass:
91n/a """
92n/a >>> x = SampleClass.NestedClass(5)
93n/a >>> y = x.square()
94n/a >>> print(y.get())
95n/a 25
96n/a """
97n/a def __init__(self, val=0):
98n/a """
99n/a >>> print(SampleClass.NestedClass().get())
100n/a 0
101n/a """
102n/a self.val = val
103n/a def square(self):
104n/a return SampleClass.NestedClass(self.val*self.val)
105n/a def get(self):
106n/a return self.val
107n/a
108n/aclass SampleNewStyleClass(object):
109n/a r"""
110n/a >>> print('1\n2\n3')
111n/a 1
112n/a 2
113n/a 3
114n/a """
115n/a def __init__(self, val):
116n/a """
117n/a >>> print(SampleNewStyleClass(12).get())
118n/a 12
119n/a """
120n/a self.val = val
121n/a
122n/a def double(self):
123n/a """
124n/a >>> print(SampleNewStyleClass(12).double().get())
125n/a 24
126n/a """
127n/a return SampleNewStyleClass(self.val + self.val)
128n/a
129n/a def get(self):
130n/a """
131n/a >>> print(SampleNewStyleClass(-5).get())
132n/a -5
133n/a """
134n/a return self.val
135n/a
136n/a######################################################################
137n/a## Fake stdin (for testing interactive debugging)
138n/a######################################################################
139n/a
140n/aclass _FakeInput:
141n/a """
142n/a A fake input stream for pdb's interactive debugger. Whenever a
143n/a line is read, print it (to simulate the user typing it), and then
144n/a return it. The set of lines to return is specified in the
145n/a constructor; they should not have trailing newlines.
146n/a """
147n/a def __init__(self, lines):
148n/a self.lines = lines
149n/a
150n/a def readline(self):
151n/a line = self.lines.pop(0)
152n/a print(line)
153n/a return line+'\n'
154n/a
155n/a######################################################################
156n/a## Test Cases
157n/a######################################################################
158n/a
159n/adef test_Example(): r"""
160n/aUnit tests for the `Example` class.
161n/a
162n/aExample is a simple container class that holds:
163n/a - `source`: A source string.
164n/a - `want`: An expected output string.
165n/a - `exc_msg`: An expected exception message string (or None if no
166n/a exception is expected).
167n/a - `lineno`: A line number (within the docstring).
168n/a - `indent`: The example's indentation in the input string.
169n/a - `options`: An option dictionary, mapping option flags to True or
170n/a False.
171n/a
172n/aThese attributes are set by the constructor. `source` and `want` are
173n/arequired; the other attributes all have default values:
174n/a
175n/a >>> example = doctest.Example('print(1)', '1\n')
176n/a >>> (example.source, example.want, example.exc_msg,
177n/a ... example.lineno, example.indent, example.options)
178n/a ('print(1)\n', '1\n', None, 0, 0, {})
179n/a
180n/aThe first three attributes (`source`, `want`, and `exc_msg`) may be
181n/aspecified positionally; the remaining arguments should be specified as
182n/akeyword arguments:
183n/a
184n/a >>> exc_msg = 'IndexError: pop from an empty list'
185n/a >>> example = doctest.Example('[].pop()', '', exc_msg,
186n/a ... lineno=5, indent=4,
187n/a ... options={doctest.ELLIPSIS: True})
188n/a >>> (example.source, example.want, example.exc_msg,
189n/a ... example.lineno, example.indent, example.options)
190n/a ('[].pop()\n', '', 'IndexError: pop from an empty list\n', 5, 4, {8: True})
191n/a
192n/aThe constructor normalizes the `source` string to end in a newline:
193n/a
194n/a Source spans a single line: no terminating newline.
195n/a >>> e = doctest.Example('print(1)', '1\n')
196n/a >>> e.source, e.want
197n/a ('print(1)\n', '1\n')
198n/a
199n/a >>> e = doctest.Example('print(1)\n', '1\n')
200n/a >>> e.source, e.want
201n/a ('print(1)\n', '1\n')
202n/a
203n/a Source spans multiple lines: require terminating newline.
204n/a >>> e = doctest.Example('print(1);\nprint(2)\n', '1\n2\n')
205n/a >>> e.source, e.want
206n/a ('print(1);\nprint(2)\n', '1\n2\n')
207n/a
208n/a >>> e = doctest.Example('print(1);\nprint(2)', '1\n2\n')
209n/a >>> e.source, e.want
210n/a ('print(1);\nprint(2)\n', '1\n2\n')
211n/a
212n/a Empty source string (which should never appear in real examples)
213n/a >>> e = doctest.Example('', '')
214n/a >>> e.source, e.want
215n/a ('\n', '')
216n/a
217n/aThe constructor normalizes the `want` string to end in a newline,
218n/aunless it's the empty string:
219n/a
220n/a >>> e = doctest.Example('print(1)', '1\n')
221n/a >>> e.source, e.want
222n/a ('print(1)\n', '1\n')
223n/a
224n/a >>> e = doctest.Example('print(1)', '1')
225n/a >>> e.source, e.want
226n/a ('print(1)\n', '1\n')
227n/a
228n/a >>> e = doctest.Example('print', '')
229n/a >>> e.source, e.want
230n/a ('print\n', '')
231n/a
232n/aThe constructor normalizes the `exc_msg` string to end in a newline,
233n/aunless it's `None`:
234n/a
235n/a Message spans one line
236n/a >>> exc_msg = 'IndexError: pop from an empty list'
237n/a >>> e = doctest.Example('[].pop()', '', exc_msg)
238n/a >>> e.exc_msg
239n/a 'IndexError: pop from an empty list\n'
240n/a
241n/a >>> exc_msg = 'IndexError: pop from an empty list\n'
242n/a >>> e = doctest.Example('[].pop()', '', exc_msg)
243n/a >>> e.exc_msg
244n/a 'IndexError: pop from an empty list\n'
245n/a
246n/a Message spans multiple lines
247n/a >>> exc_msg = 'ValueError: 1\n 2'
248n/a >>> e = doctest.Example('raise ValueError("1\n 2")', '', exc_msg)
249n/a >>> e.exc_msg
250n/a 'ValueError: 1\n 2\n'
251n/a
252n/a >>> exc_msg = 'ValueError: 1\n 2\n'
253n/a >>> e = doctest.Example('raise ValueError("1\n 2")', '', exc_msg)
254n/a >>> e.exc_msg
255n/a 'ValueError: 1\n 2\n'
256n/a
257n/a Empty (but non-None) exception message (which should never appear
258n/a in real examples)
259n/a >>> exc_msg = ''
260n/a >>> e = doctest.Example('raise X()', '', exc_msg)
261n/a >>> e.exc_msg
262n/a '\n'
263n/a
264n/aCompare `Example`:
265n/a >>> example = doctest.Example('print 1', '1\n')
266n/a >>> same_example = doctest.Example('print 1', '1\n')
267n/a >>> other_example = doctest.Example('print 42', '42\n')
268n/a >>> example == same_example
269n/a True
270n/a >>> example != same_example
271n/a False
272n/a >>> hash(example) == hash(same_example)
273n/a True
274n/a >>> example == other_example
275n/a False
276n/a >>> example != other_example
277n/a True
278n/a"""
279n/a
280n/adef test_DocTest(): r"""
281n/aUnit tests for the `DocTest` class.
282n/a
283n/aDocTest is a collection of examples, extracted from a docstring, along
284n/awith information about where the docstring comes from (a name,
285n/afilename, and line number). The docstring is parsed by the `DocTest`
286n/aconstructor:
287n/a
288n/a >>> docstring = '''
289n/a ... >>> print(12)
290n/a ... 12
291n/a ...
292n/a ... Non-example text.
293n/a ...
294n/a ... >>> print('another\\example')
295n/a ... another
296n/a ... example
297n/a ... '''
298n/a >>> globs = {} # globals to run the test in.
299n/a >>> parser = doctest.DocTestParser()
300n/a >>> test = parser.get_doctest(docstring, globs, 'some_test',
301n/a ... 'some_file', 20)
302n/a >>> print(test)
303n/a <DocTest some_test from some_file:20 (2 examples)>
304n/a >>> len(test.examples)
305n/a 2
306n/a >>> e1, e2 = test.examples
307n/a >>> (e1.source, e1.want, e1.lineno)
308n/a ('print(12)\n', '12\n', 1)
309n/a >>> (e2.source, e2.want, e2.lineno)
310n/a ("print('another\\example')\n", 'another\nexample\n', 6)
311n/a
312n/aSource information (name, filename, and line number) is available as
313n/aattributes on the doctest object:
314n/a
315n/a >>> (test.name, test.filename, test.lineno)
316n/a ('some_test', 'some_file', 20)
317n/a
318n/aThe line number of an example within its containing file is found by
319n/aadding the line number of the example and the line number of its
320n/acontaining test:
321n/a
322n/a >>> test.lineno + e1.lineno
323n/a 21
324n/a >>> test.lineno + e2.lineno
325n/a 26
326n/a
327n/aIf the docstring contains inconsistent leading whitespace in the
328n/aexpected output of an example, then `DocTest` will raise a ValueError:
329n/a
330n/a >>> docstring = r'''
331n/a ... >>> print('bad\nindentation')
332n/a ... bad
333n/a ... indentation
334n/a ... '''
335n/a >>> parser.get_doctest(docstring, globs, 'some_test', 'filename', 0)
336n/a Traceback (most recent call last):
337n/a ValueError: line 4 of the docstring for some_test has inconsistent leading whitespace: 'indentation'
338n/a
339n/aIf the docstring contains inconsistent leading whitespace on
340n/acontinuation lines, then `DocTest` will raise a ValueError:
341n/a
342n/a >>> docstring = r'''
343n/a ... >>> print(('bad indentation',
344n/a ... ... 2))
345n/a ... ('bad', 'indentation')
346n/a ... '''
347n/a >>> parser.get_doctest(docstring, globs, 'some_test', 'filename', 0)
348n/a Traceback (most recent call last):
349n/a ValueError: line 2 of the docstring for some_test has inconsistent leading whitespace: '... 2))'
350n/a
351n/aIf there's no blank space after a PS1 prompt ('>>>'), then `DocTest`
352n/awill raise a ValueError:
353n/a
354n/a >>> docstring = '>>>print(1)\n1'
355n/a >>> parser.get_doctest(docstring, globs, 'some_test', 'filename', 0)
356n/a Traceback (most recent call last):
357n/a ValueError: line 1 of the docstring for some_test lacks blank after >>>: '>>>print(1)'
358n/a
359n/aIf there's no blank space after a PS2 prompt ('...'), then `DocTest`
360n/awill raise a ValueError:
361n/a
362n/a >>> docstring = '>>> if 1:\n...print(1)\n1'
363n/a >>> parser.get_doctest(docstring, globs, 'some_test', 'filename', 0)
364n/a Traceback (most recent call last):
365n/a ValueError: line 2 of the docstring for some_test lacks blank after ...: '...print(1)'
366n/a
367n/aCompare `DocTest`:
368n/a
369n/a >>> docstring = '''
370n/a ... >>> print 12
371n/a ... 12
372n/a ... '''
373n/a >>> test = parser.get_doctest(docstring, globs, 'some_test',
374n/a ... 'some_test', 20)
375n/a >>> same_test = parser.get_doctest(docstring, globs, 'some_test',
376n/a ... 'some_test', 20)
377n/a >>> test == same_test
378n/a True
379n/a >>> test != same_test
380n/a False
381n/a >>> hash(test) == hash(same_test)
382n/a True
383n/a >>> docstring = '''
384n/a ... >>> print 42
385n/a ... 42
386n/a ... '''
387n/a >>> other_test = parser.get_doctest(docstring, globs, 'other_test',
388n/a ... 'other_file', 10)
389n/a >>> test == other_test
390n/a False
391n/a >>> test != other_test
392n/a True
393n/a
394n/aCompare `DocTestCase`:
395n/a
396n/a >>> DocTestCase = doctest.DocTestCase
397n/a >>> test_case = DocTestCase(test)
398n/a >>> same_test_case = DocTestCase(same_test)
399n/a >>> other_test_case = DocTestCase(other_test)
400n/a >>> test_case == same_test_case
401n/a True
402n/a >>> test_case != same_test_case
403n/a False
404n/a >>> hash(test_case) == hash(same_test_case)
405n/a True
406n/a >>> test == other_test_case
407n/a False
408n/a >>> test != other_test_case
409n/a True
410n/a
411n/a"""
412n/a
413n/aclass test_DocTestFinder:
414n/a def basics(): r"""
415n/aUnit tests for the `DocTestFinder` class.
416n/a
417n/aDocTestFinder is used to extract DocTests from an object's docstring
418n/aand the docstrings of its contained objects. It can be used with
419n/amodules, functions, classes, methods, staticmethods, classmethods, and
420n/aproperties.
421n/a
422n/aFinding Tests in Functions
423n/a~~~~~~~~~~~~~~~~~~~~~~~~~~
424n/aFor a function whose docstring contains examples, DocTestFinder.find()
425n/awill return a single test (for that function's docstring):
426n/a
427n/a >>> finder = doctest.DocTestFinder()
428n/a
429n/aWe'll simulate a __file__ attr that ends in pyc:
430n/a
431n/a >>> import test.test_doctest
432n/a >>> old = test.test_doctest.__file__
433n/a >>> test.test_doctest.__file__ = 'test_doctest.pyc'
434n/a
435n/a >>> tests = finder.find(sample_func)
436n/a
437n/a >>> print(tests) # doctest: +ELLIPSIS
438n/a [<DocTest sample_func from ...:19 (1 example)>]
439n/a
440n/aThe exact name depends on how test_doctest was invoked, so allow for
441n/aleading path components.
442n/a
443n/a >>> tests[0].filename # doctest: +ELLIPSIS
444n/a '...test_doctest.py'
445n/a
446n/a >>> test.test_doctest.__file__ = old
447n/a
448n/a
449n/a >>> e = tests[0].examples[0]
450n/a >>> (e.source, e.want, e.lineno)
451n/a ('print(sample_func(22))\n', '44\n', 3)
452n/a
453n/aBy default, tests are created for objects with no docstring:
454n/a
455n/a >>> def no_docstring(v):
456n/a ... pass
457n/a >>> finder.find(no_docstring)
458n/a []
459n/a
460n/aHowever, the optional argument `exclude_empty` to the DocTestFinder
461n/aconstructor can be used to exclude tests for objects with empty
462n/adocstrings:
463n/a
464n/a >>> def no_docstring(v):
465n/a ... pass
466n/a >>> excl_empty_finder = doctest.DocTestFinder(exclude_empty=True)
467n/a >>> excl_empty_finder.find(no_docstring)
468n/a []
469n/a
470n/aIf the function has a docstring with no examples, then a test with no
471n/aexamples is returned. (This lets `DocTestRunner` collect statistics
472n/aabout which functions have no tests -- but is that useful? And should
473n/aan empty test also be created when there's no docstring?)
474n/a
475n/a >>> def no_examples(v):
476n/a ... ''' no doctest examples '''
477n/a >>> finder.find(no_examples) # doctest: +ELLIPSIS
478n/a [<DocTest no_examples from ...:1 (no examples)>]
479n/a
480n/aFinding Tests in Classes
481n/a~~~~~~~~~~~~~~~~~~~~~~~~
482n/aFor a class, DocTestFinder will create a test for the class's
483n/adocstring, and will recursively explore its contents, including
484n/amethods, classmethods, staticmethods, properties, and nested classes.
485n/a
486n/a >>> finder = doctest.DocTestFinder()
487n/a >>> tests = finder.find(SampleClass)
488n/a >>> for t in tests:
489n/a ... print('%2s %s' % (len(t.examples), t.name))
490n/a 3 SampleClass
491n/a 3 SampleClass.NestedClass
492n/a 1 SampleClass.NestedClass.__init__
493n/a 1 SampleClass.__init__
494n/a 2 SampleClass.a_classmethod
495n/a 1 SampleClass.a_property
496n/a 1 SampleClass.a_staticmethod
497n/a 1 SampleClass.double
498n/a 1 SampleClass.get
499n/a
500n/aNew-style classes are also supported:
501n/a
502n/a >>> tests = finder.find(SampleNewStyleClass)
503n/a >>> for t in tests:
504n/a ... print('%2s %s' % (len(t.examples), t.name))
505n/a 1 SampleNewStyleClass
506n/a 1 SampleNewStyleClass.__init__
507n/a 1 SampleNewStyleClass.double
508n/a 1 SampleNewStyleClass.get
509n/a
510n/aFinding Tests in Modules
511n/a~~~~~~~~~~~~~~~~~~~~~~~~
512n/aFor a module, DocTestFinder will create a test for the class's
513n/adocstring, and will recursively explore its contents, including
514n/afunctions, classes, and the `__test__` dictionary, if it exists:
515n/a
516n/a >>> # A module
517n/a >>> import types
518n/a >>> m = types.ModuleType('some_module')
519n/a >>> def triple(val):
520n/a ... '''
521n/a ... >>> print(triple(11))
522n/a ... 33
523n/a ... '''
524n/a ... return val*3
525n/a >>> m.__dict__.update({
526n/a ... 'sample_func': sample_func,
527n/a ... 'SampleClass': SampleClass,
528n/a ... '__doc__': '''
529n/a ... Module docstring.
530n/a ... >>> print('module')
531n/a ... module
532n/a ... ''',
533n/a ... '__test__': {
534n/a ... 'd': '>>> print(6)\n6\n>>> print(7)\n7\n',
535n/a ... 'c': triple}})
536n/a
537n/a >>> finder = doctest.DocTestFinder()
538n/a >>> # Use module=test.test_doctest, to prevent doctest from
539n/a >>> # ignoring the objects since they weren't defined in m.
540n/a >>> import test.test_doctest
541n/a >>> tests = finder.find(m, module=test.test_doctest)
542n/a >>> for t in tests:
543n/a ... print('%2s %s' % (len(t.examples), t.name))
544n/a 1 some_module
545n/a 3 some_module.SampleClass
546n/a 3 some_module.SampleClass.NestedClass
547n/a 1 some_module.SampleClass.NestedClass.__init__
548n/a 1 some_module.SampleClass.__init__
549n/a 2 some_module.SampleClass.a_classmethod
550n/a 1 some_module.SampleClass.a_property
551n/a 1 some_module.SampleClass.a_staticmethod
552n/a 1 some_module.SampleClass.double
553n/a 1 some_module.SampleClass.get
554n/a 1 some_module.__test__.c
555n/a 2 some_module.__test__.d
556n/a 1 some_module.sample_func
557n/a
558n/aDuplicate Removal
559n/a~~~~~~~~~~~~~~~~~
560n/aIf a single object is listed twice (under different names), then tests
561n/awill only be generated for it once:
562n/a
563n/a >>> from test import doctest_aliases
564n/a >>> assert doctest_aliases.TwoNames.f
565n/a >>> assert doctest_aliases.TwoNames.g
566n/a >>> tests = excl_empty_finder.find(doctest_aliases)
567n/a >>> print(len(tests))
568n/a 2
569n/a >>> print(tests[0].name)
570n/a test.doctest_aliases.TwoNames
571n/a
572n/a TwoNames.f and TwoNames.g are bound to the same object.
573n/a We can't guess which will be found in doctest's traversal of
574n/a TwoNames.__dict__ first, so we have to allow for either.
575n/a
576n/a >>> tests[1].name.split('.')[-1] in ['f', 'g']
577n/a True
578n/a
579n/aEmpty Tests
580n/a~~~~~~~~~~~
581n/aBy default, an object with no doctests doesn't create any tests:
582n/a
583n/a >>> tests = doctest.DocTestFinder().find(SampleClass)
584n/a >>> for t in tests:
585n/a ... print('%2s %s' % (len(t.examples), t.name))
586n/a 3 SampleClass
587n/a 3 SampleClass.NestedClass
588n/a 1 SampleClass.NestedClass.__init__
589n/a 1 SampleClass.__init__
590n/a 2 SampleClass.a_classmethod
591n/a 1 SampleClass.a_property
592n/a 1 SampleClass.a_staticmethod
593n/a 1 SampleClass.double
594n/a 1 SampleClass.get
595n/a
596n/aBy default, that excluded objects with no doctests. exclude_empty=False
597n/atells it to include (empty) tests for objects with no doctests. This feature
598n/ais really to support backward compatibility in what doctest.master.summarize()
599n/adisplays.
600n/a
601n/a >>> tests = doctest.DocTestFinder(exclude_empty=False).find(SampleClass)
602n/a >>> for t in tests:
603n/a ... print('%2s %s' % (len(t.examples), t.name))
604n/a 3 SampleClass
605n/a 3 SampleClass.NestedClass
606n/a 1 SampleClass.NestedClass.__init__
607n/a 0 SampleClass.NestedClass.get
608n/a 0 SampleClass.NestedClass.square
609n/a 1 SampleClass.__init__
610n/a 2 SampleClass.a_classmethod
611n/a 1 SampleClass.a_property
612n/a 1 SampleClass.a_staticmethod
613n/a 1 SampleClass.double
614n/a 1 SampleClass.get
615n/a
616n/aTurning off Recursion
617n/a~~~~~~~~~~~~~~~~~~~~~
618n/aDocTestFinder can be told not to look for tests in contained objects
619n/ausing the `recurse` flag:
620n/a
621n/a >>> tests = doctest.DocTestFinder(recurse=False).find(SampleClass)
622n/a >>> for t in tests:
623n/a ... print('%2s %s' % (len(t.examples), t.name))
624n/a 3 SampleClass
625n/a
626n/aLine numbers
627n/a~~~~~~~~~~~~
628n/aDocTestFinder finds the line number of each example:
629n/a
630n/a >>> def f(x):
631n/a ... '''
632n/a ... >>> x = 12
633n/a ...
634n/a ... some text
635n/a ...
636n/a ... >>> # examples are not created for comments & bare prompts.
637n/a ... >>>
638n/a ... ...
639n/a ...
640n/a ... >>> for x in range(10):
641n/a ... ... print(x, end=' ')
642n/a ... 0 1 2 3 4 5 6 7 8 9
643n/a ... >>> x//2
644n/a ... 6
645n/a ... '''
646n/a >>> test = doctest.DocTestFinder().find(f)[0]
647n/a >>> [e.lineno for e in test.examples]
648n/a [1, 9, 12]
649n/a"""
650n/a
651n/a if int.__doc__: # simple check for --without-doc-strings, skip if lacking
652n/a def non_Python_modules(): r"""
653n/a
654n/aFinding Doctests in Modules Not Written in Python
655n/a~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
656n/aDocTestFinder can also find doctests in most modules not written in Python.
657n/aWe'll use builtins as an example, since it almost certainly isn't written in
658n/aplain ol' Python and is guaranteed to be available.
659n/a
660n/a >>> import builtins
661n/a >>> tests = doctest.DocTestFinder().find(builtins)
662n/a >>> 790 < len(tests) < 810 # approximate number of objects with docstrings
663n/a True
664n/a >>> real_tests = [t for t in tests if len(t.examples) > 0]
665n/a >>> len(real_tests) # objects that actually have doctests
666n/a 8
667n/a >>> for t in real_tests:
668n/a ... print('{} {}'.format(len(t.examples), t.name))
669n/a ...
670n/a 1 builtins.bin
671n/a 3 builtins.float.as_integer_ratio
672n/a 2 builtins.float.fromhex
673n/a 2 builtins.float.hex
674n/a 1 builtins.hex
675n/a 1 builtins.int
676n/a 2 builtins.int.bit_length
677n/a 1 builtins.oct
678n/a
679n/aNote here that 'bin', 'oct', and 'hex' are functions; 'float.as_integer_ratio',
680n/a'float.hex', and 'int.bit_length' are methods; 'float.fromhex' is a classmethod,
681n/aand 'int' is a type.
682n/a"""
683n/a
684n/adef test_DocTestParser(): r"""
685n/aUnit tests for the `DocTestParser` class.
686n/a
687n/aDocTestParser is used to parse docstrings containing doctest examples.
688n/a
689n/aThe `parse` method divides a docstring into examples and intervening
690n/atext:
691n/a
692n/a >>> s = '''
693n/a ... >>> x, y = 2, 3 # no output expected
694n/a ... >>> if 1:
695n/a ... ... print(x)
696n/a ... ... print(y)
697n/a ... 2
698n/a ... 3
699n/a ...
700n/a ... Some text.
701n/a ... >>> x+y
702n/a ... 5
703n/a ... '''
704n/a >>> parser = doctest.DocTestParser()
705n/a >>> for piece in parser.parse(s):
706n/a ... if isinstance(piece, doctest.Example):
707n/a ... print('Example:', (piece.source, piece.want, piece.lineno))
708n/a ... else:
709n/a ... print(' Text:', repr(piece))
710n/a Text: '\n'
711n/a Example: ('x, y = 2, 3 # no output expected\n', '', 1)
712n/a Text: ''
713n/a Example: ('if 1:\n print(x)\n print(y)\n', '2\n3\n', 2)
714n/a Text: '\nSome text.\n'
715n/a Example: ('x+y\n', '5\n', 9)
716n/a Text: ''
717n/a
718n/aThe `get_examples` method returns just the examples:
719n/a
720n/a >>> for piece in parser.get_examples(s):
721n/a ... print((piece.source, piece.want, piece.lineno))
722n/a ('x, y = 2, 3 # no output expected\n', '', 1)
723n/a ('if 1:\n print(x)\n print(y)\n', '2\n3\n', 2)
724n/a ('x+y\n', '5\n', 9)
725n/a
726n/aThe `get_doctest` method creates a Test from the examples, along with the
727n/agiven arguments:
728n/a
729n/a >>> test = parser.get_doctest(s, {}, 'name', 'filename', lineno=5)
730n/a >>> (test.name, test.filename, test.lineno)
731n/a ('name', 'filename', 5)
732n/a >>> for piece in test.examples:
733n/a ... print((piece.source, piece.want, piece.lineno))
734n/a ('x, y = 2, 3 # no output expected\n', '', 1)
735n/a ('if 1:\n print(x)\n print(y)\n', '2\n3\n', 2)
736n/a ('x+y\n', '5\n', 9)
737n/a"""
738n/a
739n/aclass test_DocTestRunner:
740n/a def basics(): r"""
741n/aUnit tests for the `DocTestRunner` class.
742n/a
743n/aDocTestRunner is used to run DocTest test cases, and to accumulate
744n/astatistics. Here's a simple DocTest case we can use:
745n/a
746n/a >>> def f(x):
747n/a ... '''
748n/a ... >>> x = 12
749n/a ... >>> print(x)
750n/a ... 12
751n/a ... >>> x//2
752n/a ... 6
753n/a ... '''
754n/a >>> test = doctest.DocTestFinder().find(f)[0]
755n/a
756n/aThe main DocTestRunner interface is the `run` method, which runs a
757n/agiven DocTest case in a given namespace (globs). It returns a tuple
758n/a`(f,t)`, where `f` is the number of failed tests and `t` is the number
759n/aof tried tests.
760n/a
761n/a >>> doctest.DocTestRunner(verbose=False).run(test)
762n/a TestResults(failed=0, attempted=3)
763n/a
764n/aIf any example produces incorrect output, then the test runner reports
765n/athe failure and proceeds to the next example:
766n/a
767n/a >>> def f(x):
768n/a ... '''
769n/a ... >>> x = 12
770n/a ... >>> print(x)
771n/a ... 14
772n/a ... >>> x//2
773n/a ... 6
774n/a ... '''
775n/a >>> test = doctest.DocTestFinder().find(f)[0]
776n/a >>> doctest.DocTestRunner(verbose=True).run(test)
777n/a ... # doctest: +ELLIPSIS
778n/a Trying:
779n/a x = 12
780n/a Expecting nothing
781n/a ok
782n/a Trying:
783n/a print(x)
784n/a Expecting:
785n/a 14
786n/a **********************************************************************
787n/a File ..., line 4, in f
788n/a Failed example:
789n/a print(x)
790n/a Expected:
791n/a 14
792n/a Got:
793n/a 12
794n/a Trying:
795n/a x//2
796n/a Expecting:
797n/a 6
798n/a ok
799n/a TestResults(failed=1, attempted=3)
800n/a"""
801n/a def verbose_flag(): r"""
802n/aThe `verbose` flag makes the test runner generate more detailed
803n/aoutput:
804n/a
805n/a >>> def f(x):
806n/a ... '''
807n/a ... >>> x = 12
808n/a ... >>> print(x)
809n/a ... 12
810n/a ... >>> x//2
811n/a ... 6
812n/a ... '''
813n/a >>> test = doctest.DocTestFinder().find(f)[0]
814n/a
815n/a >>> doctest.DocTestRunner(verbose=True).run(test)
816n/a Trying:
817n/a x = 12
818n/a Expecting nothing
819n/a ok
820n/a Trying:
821n/a print(x)
822n/a Expecting:
823n/a 12
824n/a ok
825n/a Trying:
826n/a x//2
827n/a Expecting:
828n/a 6
829n/a ok
830n/a TestResults(failed=0, attempted=3)
831n/a
832n/aIf the `verbose` flag is unspecified, then the output will be verbose
833n/aiff `-v` appears in sys.argv:
834n/a
835n/a >>> # Save the real sys.argv list.
836n/a >>> old_argv = sys.argv
837n/a
838n/a >>> # If -v does not appear in sys.argv, then output isn't verbose.
839n/a >>> sys.argv = ['test']
840n/a >>> doctest.DocTestRunner().run(test)
841n/a TestResults(failed=0, attempted=3)
842n/a
843n/a >>> # If -v does appear in sys.argv, then output is verbose.
844n/a >>> sys.argv = ['test', '-v']
845n/a >>> doctest.DocTestRunner().run(test)
846n/a Trying:
847n/a x = 12
848n/a Expecting nothing
849n/a ok
850n/a Trying:
851n/a print(x)
852n/a Expecting:
853n/a 12
854n/a ok
855n/a Trying:
856n/a x//2
857n/a Expecting:
858n/a 6
859n/a ok
860n/a TestResults(failed=0, attempted=3)
861n/a
862n/a >>> # Restore sys.argv
863n/a >>> sys.argv = old_argv
864n/a
865n/aIn the remaining examples, the test runner's verbosity will be
866n/aexplicitly set, to ensure that the test behavior is consistent.
867n/a """
868n/a def exceptions(): r"""
869n/aTests of `DocTestRunner`'s exception handling.
870n/a
871n/aAn expected exception is specified with a traceback message. The
872n/alines between the first line and the type/value may be omitted or
873n/areplaced with any other string:
874n/a
875n/a >>> def f(x):
876n/a ... '''
877n/a ... >>> x = 12
878n/a ... >>> print(x//0)
879n/a ... Traceback (most recent call last):
880n/a ... ZeroDivisionError: integer division or modulo by zero
881n/a ... '''
882n/a >>> test = doctest.DocTestFinder().find(f)[0]
883n/a >>> doctest.DocTestRunner(verbose=False).run(test)
884n/a TestResults(failed=0, attempted=2)
885n/a
886n/aAn example may not generate output before it raises an exception; if
887n/ait does, then the traceback message will not be recognized as
888n/asignaling an expected exception, so the example will be reported as an
889n/aunexpected exception:
890n/a
891n/a >>> def f(x):
892n/a ... '''
893n/a ... >>> x = 12
894n/a ... >>> print('pre-exception output', x//0)
895n/a ... pre-exception output
896n/a ... Traceback (most recent call last):
897n/a ... ZeroDivisionError: integer division or modulo by zero
898n/a ... '''
899n/a >>> test = doctest.DocTestFinder().find(f)[0]
900n/a >>> doctest.DocTestRunner(verbose=False).run(test)
901n/a ... # doctest: +ELLIPSIS
902n/a **********************************************************************
903n/a File ..., line 4, in f
904n/a Failed example:
905n/a print('pre-exception output', x//0)
906n/a Exception raised:
907n/a ...
908n/a ZeroDivisionError: integer division or modulo by zero
909n/a TestResults(failed=1, attempted=2)
910n/a
911n/aException messages may contain newlines:
912n/a
913n/a >>> def f(x):
914n/a ... r'''
915n/a ... >>> raise ValueError('multi\nline\nmessage')
916n/a ... Traceback (most recent call last):
917n/a ... ValueError: multi
918n/a ... line
919n/a ... message
920n/a ... '''
921n/a >>> test = doctest.DocTestFinder().find(f)[0]
922n/a >>> doctest.DocTestRunner(verbose=False).run(test)
923n/a TestResults(failed=0, attempted=1)
924n/a
925n/aIf an exception is expected, but an exception with the wrong type or
926n/amessage is raised, then it is reported as a failure:
927n/a
928n/a >>> def f(x):
929n/a ... r'''
930n/a ... >>> raise ValueError('message')
931n/a ... Traceback (most recent call last):
932n/a ... ValueError: wrong message
933n/a ... '''
934n/a >>> test = doctest.DocTestFinder().find(f)[0]
935n/a >>> doctest.DocTestRunner(verbose=False).run(test)
936n/a ... # doctest: +ELLIPSIS
937n/a **********************************************************************
938n/a File ..., line 3, in f
939n/a Failed example:
940n/a raise ValueError('message')
941n/a Expected:
942n/a Traceback (most recent call last):
943n/a ValueError: wrong message
944n/a Got:
945n/a Traceback (most recent call last):
946n/a ...
947n/a ValueError: message
948n/a TestResults(failed=1, attempted=1)
949n/a
950n/aHowever, IGNORE_EXCEPTION_DETAIL can be used to allow a mismatch in the
951n/adetail:
952n/a
953n/a >>> def f(x):
954n/a ... r'''
955n/a ... >>> raise ValueError('message') #doctest: +IGNORE_EXCEPTION_DETAIL
956n/a ... Traceback (most recent call last):
957n/a ... ValueError: wrong message
958n/a ... '''
959n/a >>> test = doctest.DocTestFinder().find(f)[0]
960n/a >>> doctest.DocTestRunner(verbose=False).run(test)
961n/a TestResults(failed=0, attempted=1)
962n/a
963n/aIGNORE_EXCEPTION_DETAIL also ignores difference in exception formatting
964n/abetween Python versions. For example, in Python 2.x, the module path of
965n/athe exception is not in the output, but this will fail under Python 3:
966n/a
967n/a >>> def f(x):
968n/a ... r'''
969n/a ... >>> from http.client import HTTPException
970n/a ... >>> raise HTTPException('message')
971n/a ... Traceback (most recent call last):
972n/a ... HTTPException: message
973n/a ... '''
974n/a >>> test = doctest.DocTestFinder().find(f)[0]
975n/a >>> doctest.DocTestRunner(verbose=False).run(test)
976n/a ... # doctest: +ELLIPSIS
977n/a **********************************************************************
978n/a File ..., line 4, in f
979n/a Failed example:
980n/a raise HTTPException('message')
981n/a Expected:
982n/a Traceback (most recent call last):
983n/a HTTPException: message
984n/a Got:
985n/a Traceback (most recent call last):
986n/a ...
987n/a http.client.HTTPException: message
988n/a TestResults(failed=1, attempted=2)
989n/a
990n/aBut in Python 3 the module path is included, and therefore a test must look
991n/alike the following test to succeed in Python 3. But that test will fail under
992n/aPython 2.
993n/a
994n/a >>> def f(x):
995n/a ... r'''
996n/a ... >>> from http.client import HTTPException
997n/a ... >>> raise HTTPException('message')
998n/a ... Traceback (most recent call last):
999n/a ... http.client.HTTPException: message
1000n/a ... '''
1001n/a >>> test = doctest.DocTestFinder().find(f)[0]
1002n/a >>> doctest.DocTestRunner(verbose=False).run(test)
1003n/a TestResults(failed=0, attempted=2)
1004n/a
1005n/aHowever, with IGNORE_EXCEPTION_DETAIL, the module name of the exception
1006n/a(or its unexpected absence) will be ignored:
1007n/a
1008n/a >>> def f(x):
1009n/a ... r'''
1010n/a ... >>> from http.client import HTTPException
1011n/a ... >>> raise HTTPException('message') #doctest: +IGNORE_EXCEPTION_DETAIL
1012n/a ... Traceback (most recent call last):
1013n/a ... HTTPException: message
1014n/a ... '''
1015n/a >>> test = doctest.DocTestFinder().find(f)[0]
1016n/a >>> doctest.DocTestRunner(verbose=False).run(test)
1017n/a TestResults(failed=0, attempted=2)
1018n/a
1019n/aThe module path will be completely ignored, so two different module paths will
1020n/astill pass if IGNORE_EXCEPTION_DETAIL is given. This is intentional, so it can
1021n/abe used when exceptions have changed module.
1022n/a
1023n/a >>> def f(x):
1024n/a ... r'''
1025n/a ... >>> from http.client import HTTPException
1026n/a ... >>> raise HTTPException('message') #doctest: +IGNORE_EXCEPTION_DETAIL
1027n/a ... Traceback (most recent call last):
1028n/a ... foo.bar.HTTPException: message
1029n/a ... '''
1030n/a >>> test = doctest.DocTestFinder().find(f)[0]
1031n/a >>> doctest.DocTestRunner(verbose=False).run(test)
1032n/a TestResults(failed=0, attempted=2)
1033n/a
1034n/aBut IGNORE_EXCEPTION_DETAIL does not allow a mismatch in the exception type:
1035n/a
1036n/a >>> def f(x):
1037n/a ... r'''
1038n/a ... >>> raise ValueError('message') #doctest: +IGNORE_EXCEPTION_DETAIL
1039n/a ... Traceback (most recent call last):
1040n/a ... TypeError: wrong type
1041n/a ... '''
1042n/a >>> test = doctest.DocTestFinder().find(f)[0]
1043n/a >>> doctest.DocTestRunner(verbose=False).run(test)
1044n/a ... # doctest: +ELLIPSIS
1045n/a **********************************************************************
1046n/a File ..., line 3, in f
1047n/a Failed example:
1048n/a raise ValueError('message') #doctest: +IGNORE_EXCEPTION_DETAIL
1049n/a Expected:
1050n/a Traceback (most recent call last):
1051n/a TypeError: wrong type
1052n/a Got:
1053n/a Traceback (most recent call last):
1054n/a ...
1055n/a ValueError: message
1056n/a TestResults(failed=1, attempted=1)
1057n/a
1058n/aIf the exception does not have a message, you can still use
1059n/aIGNORE_EXCEPTION_DETAIL to normalize the modules between Python 2 and 3:
1060n/a
1061n/a >>> def f(x):
1062n/a ... r'''
1063n/a ... >>> from http.client import HTTPException
1064n/a ... >>> raise HTTPException() #doctest: +IGNORE_EXCEPTION_DETAIL
1065n/a ... Traceback (most recent call last):
1066n/a ... foo.bar.HTTPException
1067n/a ... '''
1068n/a >>> test = doctest.DocTestFinder().find(f)[0]
1069n/a >>> doctest.DocTestRunner(verbose=False).run(test)
1070n/a TestResults(failed=0, attempted=2)
1071n/a
1072n/aNote that a trailing colon doesn't matter either:
1073n/a
1074n/a >>> def f(x):
1075n/a ... r'''
1076n/a ... >>> from http.client import HTTPException
1077n/a ... >>> raise HTTPException() #doctest: +IGNORE_EXCEPTION_DETAIL
1078n/a ... Traceback (most recent call last):
1079n/a ... foo.bar.HTTPException:
1080n/a ... '''
1081n/a >>> test = doctest.DocTestFinder().find(f)[0]
1082n/a >>> doctest.DocTestRunner(verbose=False).run(test)
1083n/a TestResults(failed=0, attempted=2)
1084n/a
1085n/aIf an exception is raised but not expected, then it is reported as an
1086n/aunexpected exception:
1087n/a
1088n/a >>> def f(x):
1089n/a ... r'''
1090n/a ... >>> 1//0
1091n/a ... 0
1092n/a ... '''
1093n/a >>> test = doctest.DocTestFinder().find(f)[0]
1094n/a >>> doctest.DocTestRunner(verbose=False).run(test)
1095n/a ... # doctest: +ELLIPSIS
1096n/a **********************************************************************
1097n/a File ..., line 3, in f
1098n/a Failed example:
1099n/a 1//0
1100n/a Exception raised:
1101n/a Traceback (most recent call last):
1102n/a ...
1103n/a ZeroDivisionError: integer division or modulo by zero
1104n/a TestResults(failed=1, attempted=1)
1105n/a"""
1106n/a def displayhook(): r"""
1107n/aTest that changing sys.displayhook doesn't matter for doctest.
1108n/a
1109n/a >>> import sys
1110n/a >>> orig_displayhook = sys.displayhook
1111n/a >>> def my_displayhook(x):
1112n/a ... print('hi!')
1113n/a >>> sys.displayhook = my_displayhook
1114n/a >>> def f():
1115n/a ... '''
1116n/a ... >>> 3
1117n/a ... 3
1118n/a ... '''
1119n/a >>> test = doctest.DocTestFinder().find(f)[0]
1120n/a >>> r = doctest.DocTestRunner(verbose=False).run(test)
1121n/a >>> post_displayhook = sys.displayhook
1122n/a
1123n/a We need to restore sys.displayhook now, so that we'll be able to test
1124n/a results.
1125n/a
1126n/a >>> sys.displayhook = orig_displayhook
1127n/a
1128n/a Ok, now we can check that everything is ok.
1129n/a
1130n/a >>> r
1131n/a TestResults(failed=0, attempted=1)
1132n/a >>> post_displayhook is my_displayhook
1133n/a True
1134n/a"""
1135n/a def optionflags(): r"""
1136n/aTests of `DocTestRunner`'s option flag handling.
1137n/a
1138n/aSeveral option flags can be used to customize the behavior of the test
1139n/arunner. These are defined as module constants in doctest, and passed
1140n/ato the DocTestRunner constructor (multiple constants should be ORed
1141n/atogether).
1142n/a
1143n/aThe DONT_ACCEPT_TRUE_FOR_1 flag disables matches between True/False
1144n/aand 1/0:
1145n/a
1146n/a >>> def f(x):
1147n/a ... '>>> True\n1\n'
1148n/a
1149n/a >>> # Without the flag:
1150n/a >>> test = doctest.DocTestFinder().find(f)[0]
1151n/a >>> doctest.DocTestRunner(verbose=False).run(test)
1152n/a TestResults(failed=0, attempted=1)
1153n/a
1154n/a >>> # With the flag:
1155n/a >>> test = doctest.DocTestFinder().find(f)[0]
1156n/a >>> flags = doctest.DONT_ACCEPT_TRUE_FOR_1
1157n/a >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
1158n/a ... # doctest: +ELLIPSIS
1159n/a **********************************************************************
1160n/a File ..., line 2, in f
1161n/a Failed example:
1162n/a True
1163n/a Expected:
1164n/a 1
1165n/a Got:
1166n/a True
1167n/a TestResults(failed=1, attempted=1)
1168n/a
1169n/aThe DONT_ACCEPT_BLANKLINE flag disables the match between blank lines
1170n/aand the '<BLANKLINE>' marker:
1171n/a
1172n/a >>> def f(x):
1173n/a ... '>>> print("a\\n\\nb")\na\n<BLANKLINE>\nb\n'
1174n/a
1175n/a >>> # Without the flag:
1176n/a >>> test = doctest.DocTestFinder().find(f)[0]
1177n/a >>> doctest.DocTestRunner(verbose=False).run(test)
1178n/a TestResults(failed=0, attempted=1)
1179n/a
1180n/a >>> # With the flag:
1181n/a >>> test = doctest.DocTestFinder().find(f)[0]
1182n/a >>> flags = doctest.DONT_ACCEPT_BLANKLINE
1183n/a >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
1184n/a ... # doctest: +ELLIPSIS
1185n/a **********************************************************************
1186n/a File ..., line 2, in f
1187n/a Failed example:
1188n/a print("a\n\nb")
1189n/a Expected:
1190n/a a
1191n/a <BLANKLINE>
1192n/a b
1193n/a Got:
1194n/a a
1195n/a <BLANKLINE>
1196n/a b
1197n/a TestResults(failed=1, attempted=1)
1198n/a
1199n/aThe NORMALIZE_WHITESPACE flag causes all sequences of whitespace to be
1200n/atreated as equal:
1201n/a
1202n/a >>> def f(x):
1203n/a ... '>>> print(1, 2, 3)\n 1 2\n 3'
1204n/a
1205n/a >>> # Without the flag:
1206n/a >>> test = doctest.DocTestFinder().find(f)[0]
1207n/a >>> doctest.DocTestRunner(verbose=False).run(test)
1208n/a ... # doctest: +ELLIPSIS
1209n/a **********************************************************************
1210n/a File ..., line 2, in f
1211n/a Failed example:
1212n/a print(1, 2, 3)
1213n/a Expected:
1214n/a 1 2
1215n/a 3
1216n/a Got:
1217n/a 1 2 3
1218n/a TestResults(failed=1, attempted=1)
1219n/a
1220n/a >>> # With the flag:
1221n/a >>> test = doctest.DocTestFinder().find(f)[0]
1222n/a >>> flags = doctest.NORMALIZE_WHITESPACE
1223n/a >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
1224n/a TestResults(failed=0, attempted=1)
1225n/a
1226n/a An example from the docs:
1227n/a >>> print(list(range(20))) #doctest: +NORMALIZE_WHITESPACE
1228n/a [0, 1, 2, 3, 4, 5, 6, 7, 8, 9,
1229n/a 10, 11, 12, 13, 14, 15, 16, 17, 18, 19]
1230n/a
1231n/aThe ELLIPSIS flag causes ellipsis marker ("...") in the expected
1232n/aoutput to match any substring in the actual output:
1233n/a
1234n/a >>> def f(x):
1235n/a ... '>>> print(list(range(15)))\n[0, 1, 2, ..., 14]\n'
1236n/a
1237n/a >>> # Without the flag:
1238n/a >>> test = doctest.DocTestFinder().find(f)[0]
1239n/a >>> doctest.DocTestRunner(verbose=False).run(test)
1240n/a ... # doctest: +ELLIPSIS
1241n/a **********************************************************************
1242n/a File ..., line 2, in f
1243n/a Failed example:
1244n/a print(list(range(15)))
1245n/a Expected:
1246n/a [0, 1, 2, ..., 14]
1247n/a Got:
1248n/a [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14]
1249n/a TestResults(failed=1, attempted=1)
1250n/a
1251n/a >>> # With the flag:
1252n/a >>> test = doctest.DocTestFinder().find(f)[0]
1253n/a >>> flags = doctest.ELLIPSIS
1254n/a >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
1255n/a TestResults(failed=0, attempted=1)
1256n/a
1257n/a ... also matches nothing:
1258n/a
1259n/a >>> if 1:
1260n/a ... for i in range(100):
1261n/a ... print(i**2, end=' ') #doctest: +ELLIPSIS
1262n/a ... print('!')
1263n/a 0 1...4...9 16 ... 36 49 64 ... 9801 !
1264n/a
1265n/a ... can be surprising; e.g., this test passes:
1266n/a
1267n/a >>> if 1: #doctest: +ELLIPSIS
1268n/a ... for i in range(20):
1269n/a ... print(i, end=' ')
1270n/a ... print(20)
1271n/a 0 1 2 ...1...2...0
1272n/a
1273n/a Examples from the docs:
1274n/a
1275n/a >>> print(list(range(20))) # doctest:+ELLIPSIS
1276n/a [0, 1, ..., 18, 19]
1277n/a
1278n/a >>> print(list(range(20))) # doctest: +ELLIPSIS
1279n/a ... # doctest: +NORMALIZE_WHITESPACE
1280n/a [0, 1, ..., 18, 19]
1281n/a
1282n/aThe SKIP flag causes an example to be skipped entirely. I.e., the
1283n/aexample is not run. It can be useful in contexts where doctest
1284n/aexamples serve as both documentation and test cases, and an example
1285n/ashould be included for documentation purposes, but should not be
1286n/achecked (e.g., because its output is random, or depends on resources
1287n/awhich would be unavailable.) The SKIP flag can also be used for
1288n/a'commenting out' broken examples.
1289n/a
1290n/a >>> import unavailable_resource # doctest: +SKIP
1291n/a >>> unavailable_resource.do_something() # doctest: +SKIP
1292n/a >>> unavailable_resource.blow_up() # doctest: +SKIP
1293n/a Traceback (most recent call last):
1294n/a ...
1295n/a UncheckedBlowUpError: Nobody checks me.
1296n/a
1297n/a >>> import random
1298n/a >>> print(random.random()) # doctest: +SKIP
1299n/a 0.721216923889
1300n/a
1301n/aThe REPORT_UDIFF flag causes failures that involve multi-line expected
1302n/aand actual outputs to be displayed using a unified diff:
1303n/a
1304n/a >>> def f(x):
1305n/a ... r'''
1306n/a ... >>> print('\n'.join('abcdefg'))
1307n/a ... a
1308n/a ... B
1309n/a ... c
1310n/a ... d
1311n/a ... f
1312n/a ... g
1313n/a ... h
1314n/a ... '''
1315n/a
1316n/a >>> # Without the flag:
1317n/a >>> test = doctest.DocTestFinder().find(f)[0]
1318n/a >>> doctest.DocTestRunner(verbose=False).run(test)
1319n/a ... # doctest: +ELLIPSIS
1320n/a **********************************************************************
1321n/a File ..., line 3, in f
1322n/a Failed example:
1323n/a print('\n'.join('abcdefg'))
1324n/a Expected:
1325n/a a
1326n/a B
1327n/a c
1328n/a d
1329n/a f
1330n/a g
1331n/a h
1332n/a Got:
1333n/a a
1334n/a b
1335n/a c
1336n/a d
1337n/a e
1338n/a f
1339n/a g
1340n/a TestResults(failed=1, attempted=1)
1341n/a
1342n/a >>> # With the flag:
1343n/a >>> test = doctest.DocTestFinder().find(f)[0]
1344n/a >>> flags = doctest.REPORT_UDIFF
1345n/a >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
1346n/a ... # doctest: +ELLIPSIS
1347n/a **********************************************************************
1348n/a File ..., line 3, in f
1349n/a Failed example:
1350n/a print('\n'.join('abcdefg'))
1351n/a Differences (unified diff with -expected +actual):
1352n/a @@ -1,7 +1,7 @@
1353n/a a
1354n/a -B
1355n/a +b
1356n/a c
1357n/a d
1358n/a +e
1359n/a f
1360n/a g
1361n/a -h
1362n/a TestResults(failed=1, attempted=1)
1363n/a
1364n/aThe REPORT_CDIFF flag causes failures that involve multi-line expected
1365n/aand actual outputs to be displayed using a context diff:
1366n/a
1367n/a >>> # Reuse f() from the REPORT_UDIFF example, above.
1368n/a >>> test = doctest.DocTestFinder().find(f)[0]
1369n/a >>> flags = doctest.REPORT_CDIFF
1370n/a >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
1371n/a ... # doctest: +ELLIPSIS
1372n/a **********************************************************************
1373n/a File ..., line 3, in f
1374n/a Failed example:
1375n/a print('\n'.join('abcdefg'))
1376n/a Differences (context diff with expected followed by actual):
1377n/a ***************
1378n/a *** 1,7 ****
1379n/a a
1380n/a ! B
1381n/a c
1382n/a d
1383n/a f
1384n/a g
1385n/a - h
1386n/a --- 1,7 ----
1387n/a a
1388n/a ! b
1389n/a c
1390n/a d
1391n/a + e
1392n/a f
1393n/a g
1394n/a TestResults(failed=1, attempted=1)
1395n/a
1396n/a
1397n/aThe REPORT_NDIFF flag causes failures to use the difflib.Differ algorithm
1398n/aused by the popular ndiff.py utility. This does intraline difference
1399n/amarking, as well as interline differences.
1400n/a
1401n/a >>> def f(x):
1402n/a ... r'''
1403n/a ... >>> print("a b c d e f g h i j k l m")
1404n/a ... a b c d e f g h i j k 1 m
1405n/a ... '''
1406n/a >>> test = doctest.DocTestFinder().find(f)[0]
1407n/a >>> flags = doctest.REPORT_NDIFF
1408n/a >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
1409n/a ... # doctest: +ELLIPSIS
1410n/a **********************************************************************
1411n/a File ..., line 3, in f
1412n/a Failed example:
1413n/a print("a b c d e f g h i j k l m")
1414n/a Differences (ndiff with -expected +actual):
1415n/a - a b c d e f g h i j k 1 m
1416n/a ? ^
1417n/a + a b c d e f g h i j k l m
1418n/a ? + ++ ^
1419n/a TestResults(failed=1, attempted=1)
1420n/a
1421n/aThe REPORT_ONLY_FIRST_FAILURE suppresses result output after the first
1422n/afailing example:
1423n/a
1424n/a >>> def f(x):
1425n/a ... r'''
1426n/a ... >>> print(1) # first success
1427n/a ... 1
1428n/a ... >>> print(2) # first failure
1429n/a ... 200
1430n/a ... >>> print(3) # second failure
1431n/a ... 300
1432n/a ... >>> print(4) # second success
1433n/a ... 4
1434n/a ... >>> print(5) # third failure
1435n/a ... 500
1436n/a ... '''
1437n/a >>> test = doctest.DocTestFinder().find(f)[0]
1438n/a >>> flags = doctest.REPORT_ONLY_FIRST_FAILURE
1439n/a >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
1440n/a ... # doctest: +ELLIPSIS
1441n/a **********************************************************************
1442n/a File ..., line 5, in f
1443n/a Failed example:
1444n/a print(2) # first failure
1445n/a Expected:
1446n/a 200
1447n/a Got:
1448n/a 2
1449n/a TestResults(failed=3, attempted=5)
1450n/a
1451n/aHowever, output from `report_start` is not suppressed:
1452n/a
1453n/a >>> doctest.DocTestRunner(verbose=True, optionflags=flags).run(test)
1454n/a ... # doctest: +ELLIPSIS
1455n/a Trying:
1456n/a print(1) # first success
1457n/a Expecting:
1458n/a 1
1459n/a ok
1460n/a Trying:
1461n/a print(2) # first failure
1462n/a Expecting:
1463n/a 200
1464n/a **********************************************************************
1465n/a File ..., line 5, in f
1466n/a Failed example:
1467n/a print(2) # first failure
1468n/a Expected:
1469n/a 200
1470n/a Got:
1471n/a 2
1472n/a TestResults(failed=3, attempted=5)
1473n/a
1474n/aThe FAIL_FAST flag causes the runner to exit after the first failing example,
1475n/aso subsequent examples are not even attempted:
1476n/a
1477n/a >>> flags = doctest.FAIL_FAST
1478n/a >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
1479n/a ... # doctest: +ELLIPSIS
1480n/a **********************************************************************
1481n/a File ..., line 5, in f
1482n/a Failed example:
1483n/a print(2) # first failure
1484n/a Expected:
1485n/a 200
1486n/a Got:
1487n/a 2
1488n/a TestResults(failed=1, attempted=2)
1489n/a
1490n/aSpecifying both FAIL_FAST and REPORT_ONLY_FIRST_FAILURE is equivalent to
1491n/aFAIL_FAST only:
1492n/a
1493n/a >>> flags = doctest.FAIL_FAST | doctest.REPORT_ONLY_FIRST_FAILURE
1494n/a >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
1495n/a ... # doctest: +ELLIPSIS
1496n/a **********************************************************************
1497n/a File ..., line 5, in f
1498n/a Failed example:
1499n/a print(2) # first failure
1500n/a Expected:
1501n/a 200
1502n/a Got:
1503n/a 2
1504n/a TestResults(failed=1, attempted=2)
1505n/a
1506n/aFor the purposes of both REPORT_ONLY_FIRST_FAILURE and FAIL_FAST, unexpected
1507n/aexceptions count as failures:
1508n/a
1509n/a >>> def f(x):
1510n/a ... r'''
1511n/a ... >>> print(1) # first success
1512n/a ... 1
1513n/a ... >>> raise ValueError(2) # first failure
1514n/a ... 200
1515n/a ... >>> print(3) # second failure
1516n/a ... 300
1517n/a ... >>> print(4) # second success
1518n/a ... 4
1519n/a ... >>> print(5) # third failure
1520n/a ... 500
1521n/a ... '''
1522n/a >>> test = doctest.DocTestFinder().find(f)[0]
1523n/a >>> flags = doctest.REPORT_ONLY_FIRST_FAILURE
1524n/a >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
1525n/a ... # doctest: +ELLIPSIS
1526n/a **********************************************************************
1527n/a File ..., line 5, in f
1528n/a Failed example:
1529n/a raise ValueError(2) # first failure
1530n/a Exception raised:
1531n/a ...
1532n/a ValueError: 2
1533n/a TestResults(failed=3, attempted=5)
1534n/a >>> flags = doctest.FAIL_FAST
1535n/a >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
1536n/a ... # doctest: +ELLIPSIS
1537n/a **********************************************************************
1538n/a File ..., line 5, in f
1539n/a Failed example:
1540n/a raise ValueError(2) # first failure
1541n/a Exception raised:
1542n/a ...
1543n/a ValueError: 2
1544n/a TestResults(failed=1, attempted=2)
1545n/a
1546n/aNew option flags can also be registered, via register_optionflag(). Here
1547n/awe reach into doctest's internals a bit.
1548n/a
1549n/a >>> unlikely = "UNLIKELY_OPTION_NAME"
1550n/a >>> unlikely in doctest.OPTIONFLAGS_BY_NAME
1551n/a False
1552n/a >>> new_flag_value = doctest.register_optionflag(unlikely)
1553n/a >>> unlikely in doctest.OPTIONFLAGS_BY_NAME
1554n/a True
1555n/a
1556n/aBefore 2.4.4/2.5, registering a name more than once erroneously created
1557n/amore than one flag value. Here we verify that's fixed:
1558n/a
1559n/a >>> redundant_flag_value = doctest.register_optionflag(unlikely)
1560n/a >>> redundant_flag_value == new_flag_value
1561n/a True
1562n/a
1563n/aClean up.
1564n/a >>> del doctest.OPTIONFLAGS_BY_NAME[unlikely]
1565n/a
1566n/a """
1567n/a
1568n/a def option_directives(): r"""
1569n/aTests of `DocTestRunner`'s option directive mechanism.
1570n/a
1571n/aOption directives can be used to turn option flags on or off for a
1572n/asingle example. To turn an option on for an example, follow that
1573n/aexample with a comment of the form ``# doctest: +OPTION``:
1574n/a
1575n/a >>> def f(x): r'''
1576n/a ... >>> print(list(range(10))) # should fail: no ellipsis
1577n/a ... [0, 1, ..., 9]
1578n/a ...
1579n/a ... >>> print(list(range(10))) # doctest: +ELLIPSIS
1580n/a ... [0, 1, ..., 9]
1581n/a ... '''
1582n/a >>> test = doctest.DocTestFinder().find(f)[0]
1583n/a >>> doctest.DocTestRunner(verbose=False).run(test)
1584n/a ... # doctest: +ELLIPSIS
1585n/a **********************************************************************
1586n/a File ..., line 2, in f
1587n/a Failed example:
1588n/a print(list(range(10))) # should fail: no ellipsis
1589n/a Expected:
1590n/a [0, 1, ..., 9]
1591n/a Got:
1592n/a [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
1593n/a TestResults(failed=1, attempted=2)
1594n/a
1595n/aTo turn an option off for an example, follow that example with a
1596n/acomment of the form ``# doctest: -OPTION``:
1597n/a
1598n/a >>> def f(x): r'''
1599n/a ... >>> print(list(range(10)))
1600n/a ... [0, 1, ..., 9]
1601n/a ...
1602n/a ... >>> # should fail: no ellipsis
1603n/a ... >>> print(list(range(10))) # doctest: -ELLIPSIS
1604n/a ... [0, 1, ..., 9]
1605n/a ... '''
1606n/a >>> test = doctest.DocTestFinder().find(f)[0]
1607n/a >>> doctest.DocTestRunner(verbose=False,
1608n/a ... optionflags=doctest.ELLIPSIS).run(test)
1609n/a ... # doctest: +ELLIPSIS
1610n/a **********************************************************************
1611n/a File ..., line 6, in f
1612n/a Failed example:
1613n/a print(list(range(10))) # doctest: -ELLIPSIS
1614n/a Expected:
1615n/a [0, 1, ..., 9]
1616n/a Got:
1617n/a [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
1618n/a TestResults(failed=1, attempted=2)
1619n/a
1620n/aOption directives affect only the example that they appear with; they
1621n/ado not change the options for surrounding examples:
1622n/a
1623n/a >>> def f(x): r'''
1624n/a ... >>> print(list(range(10))) # Should fail: no ellipsis
1625n/a ... [0, 1, ..., 9]
1626n/a ...
1627n/a ... >>> print(list(range(10))) # doctest: +ELLIPSIS
1628n/a ... [0, 1, ..., 9]
1629n/a ...
1630n/a ... >>> print(list(range(10))) # Should fail: no ellipsis
1631n/a ... [0, 1, ..., 9]
1632n/a ... '''
1633n/a >>> test = doctest.DocTestFinder().find(f)[0]
1634n/a >>> doctest.DocTestRunner(verbose=False).run(test)
1635n/a ... # doctest: +ELLIPSIS
1636n/a **********************************************************************
1637n/a File ..., line 2, in f
1638n/a Failed example:
1639n/a print(list(range(10))) # Should fail: no ellipsis
1640n/a Expected:
1641n/a [0, 1, ..., 9]
1642n/a Got:
1643n/a [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
1644n/a **********************************************************************
1645n/a File ..., line 8, in f
1646n/a Failed example:
1647n/a print(list(range(10))) # Should fail: no ellipsis
1648n/a Expected:
1649n/a [0, 1, ..., 9]
1650n/a Got:
1651n/a [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
1652n/a TestResults(failed=2, attempted=3)
1653n/a
1654n/aMultiple options may be modified by a single option directive. They
1655n/amay be separated by whitespace, commas, or both:
1656n/a
1657n/a >>> def f(x): r'''
1658n/a ... >>> print(list(range(10))) # Should fail
1659n/a ... [0, 1, ..., 9]
1660n/a ... >>> print(list(range(10))) # Should succeed
1661n/a ... ... # doctest: +ELLIPSIS +NORMALIZE_WHITESPACE
1662n/a ... [0, 1, ..., 9]
1663n/a ... '''
1664n/a >>> test = doctest.DocTestFinder().find(f)[0]
1665n/a >>> doctest.DocTestRunner(verbose=False).run(test)
1666n/a ... # doctest: +ELLIPSIS
1667n/a **********************************************************************
1668n/a File ..., line 2, in f
1669n/a Failed example:
1670n/a print(list(range(10))) # Should fail
1671n/a Expected:
1672n/a [0, 1, ..., 9]
1673n/a Got:
1674n/a [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
1675n/a TestResults(failed=1, attempted=2)
1676n/a
1677n/a >>> def f(x): r'''
1678n/a ... >>> print(list(range(10))) # Should fail
1679n/a ... [0, 1, ..., 9]
1680n/a ... >>> print(list(range(10))) # Should succeed
1681n/a ... ... # doctest: +ELLIPSIS,+NORMALIZE_WHITESPACE
1682n/a ... [0, 1, ..., 9]
1683n/a ... '''
1684n/a >>> test = doctest.DocTestFinder().find(f)[0]
1685n/a >>> doctest.DocTestRunner(verbose=False).run(test)
1686n/a ... # doctest: +ELLIPSIS
1687n/a **********************************************************************
1688n/a File ..., line 2, in f
1689n/a Failed example:
1690n/a print(list(range(10))) # Should fail
1691n/a Expected:
1692n/a [0, 1, ..., 9]
1693n/a Got:
1694n/a [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
1695n/a TestResults(failed=1, attempted=2)
1696n/a
1697n/a >>> def f(x): r'''
1698n/a ... >>> print(list(range(10))) # Should fail
1699n/a ... [0, 1, ..., 9]
1700n/a ... >>> print(list(range(10))) # Should succeed
1701n/a ... ... # doctest: +ELLIPSIS, +NORMALIZE_WHITESPACE
1702n/a ... [0, 1, ..., 9]
1703n/a ... '''
1704n/a >>> test = doctest.DocTestFinder().find(f)[0]
1705n/a >>> doctest.DocTestRunner(verbose=False).run(test)
1706n/a ... # doctest: +ELLIPSIS
1707n/a **********************************************************************
1708n/a File ..., line 2, in f
1709n/a Failed example:
1710n/a print(list(range(10))) # Should fail
1711n/a Expected:
1712n/a [0, 1, ..., 9]
1713n/a Got:
1714n/a [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
1715n/a TestResults(failed=1, attempted=2)
1716n/a
1717n/aThe option directive may be put on the line following the source, as
1718n/along as a continuation prompt is used:
1719n/a
1720n/a >>> def f(x): r'''
1721n/a ... >>> print(list(range(10)))
1722n/a ... ... # doctest: +ELLIPSIS
1723n/a ... [0, 1, ..., 9]
1724n/a ... '''
1725n/a >>> test = doctest.DocTestFinder().find(f)[0]
1726n/a >>> doctest.DocTestRunner(verbose=False).run(test)
1727n/a TestResults(failed=0, attempted=1)
1728n/a
1729n/aFor examples with multi-line source, the option directive may appear
1730n/aat the end of any line:
1731n/a
1732n/a >>> def f(x): r'''
1733n/a ... >>> for x in range(10): # doctest: +ELLIPSIS
1734n/a ... ... print(' ', x, end='', sep='')
1735n/a ... 0 1 2 ... 9
1736n/a ...
1737n/a ... >>> for x in range(10):
1738n/a ... ... print(' ', x, end='', sep='') # doctest: +ELLIPSIS
1739n/a ... 0 1 2 ... 9
1740n/a ... '''
1741n/a >>> test = doctest.DocTestFinder().find(f)[0]
1742n/a >>> doctest.DocTestRunner(verbose=False).run(test)
1743n/a TestResults(failed=0, attempted=2)
1744n/a
1745n/aIf more than one line of an example with multi-line source has an
1746n/aoption directive, then they are combined:
1747n/a
1748n/a >>> def f(x): r'''
1749n/a ... Should fail (option directive not on the last line):
1750n/a ... >>> for x in range(10): # doctest: +ELLIPSIS
1751n/a ... ... print(x, end=' ') # doctest: +NORMALIZE_WHITESPACE
1752n/a ... 0 1 2...9
1753n/a ... '''
1754n/a >>> test = doctest.DocTestFinder().find(f)[0]
1755n/a >>> doctest.DocTestRunner(verbose=False).run(test)
1756n/a TestResults(failed=0, attempted=1)
1757n/a
1758n/aIt is an error to have a comment of the form ``# doctest:`` that is
1759n/a*not* followed by words of the form ``+OPTION`` or ``-OPTION``, where
1760n/a``OPTION`` is an option that has been registered with
1761n/a`register_option`:
1762n/a
1763n/a >>> # Error: Option not registered
1764n/a >>> s = '>>> print(12) #doctest: +BADOPTION'
1765n/a >>> test = doctest.DocTestParser().get_doctest(s, {}, 's', 's.py', 0)
1766n/a Traceback (most recent call last):
1767n/a ValueError: line 1 of the doctest for s has an invalid option: '+BADOPTION'
1768n/a
1769n/a >>> # Error: No + or - prefix
1770n/a >>> s = '>>> print(12) #doctest: ELLIPSIS'
1771n/a >>> test = doctest.DocTestParser().get_doctest(s, {}, 's', 's.py', 0)
1772n/a Traceback (most recent call last):
1773n/a ValueError: line 1 of the doctest for s has an invalid option: 'ELLIPSIS'
1774n/a
1775n/aIt is an error to use an option directive on a line that contains no
1776n/asource:
1777n/a
1778n/a >>> s = '>>> # doctest: +ELLIPSIS'
1779n/a >>> test = doctest.DocTestParser().get_doctest(s, {}, 's', 's.py', 0)
1780n/a Traceback (most recent call last):
1781n/a ValueError: line 0 of the doctest for s has an option directive on a line with no example: '# doctest: +ELLIPSIS'
1782n/a"""
1783n/a
1784n/adef test_testsource(): r"""
1785n/aUnit tests for `testsource()`.
1786n/a
1787n/aThe testsource() function takes a module and a name, finds the (first)
1788n/atest with that name in that module, and converts it to a script. The
1789n/aexample code is converted to regular Python code. The surrounding
1790n/awords and expected output are converted to comments:
1791n/a
1792n/a >>> import test.test_doctest
1793n/a >>> name = 'test.test_doctest.sample_func'
1794n/a >>> print(doctest.testsource(test.test_doctest, name))
1795n/a # Blah blah
1796n/a #
1797n/a print(sample_func(22))
1798n/a # Expected:
1799n/a ## 44
1800n/a #
1801n/a # Yee ha!
1802n/a <BLANKLINE>
1803n/a
1804n/a >>> name = 'test.test_doctest.SampleNewStyleClass'
1805n/a >>> print(doctest.testsource(test.test_doctest, name))
1806n/a print('1\n2\n3')
1807n/a # Expected:
1808n/a ## 1
1809n/a ## 2
1810n/a ## 3
1811n/a <BLANKLINE>
1812n/a
1813n/a >>> name = 'test.test_doctest.SampleClass.a_classmethod'
1814n/a >>> print(doctest.testsource(test.test_doctest, name))
1815n/a print(SampleClass.a_classmethod(10))
1816n/a # Expected:
1817n/a ## 12
1818n/a print(SampleClass(0).a_classmethod(10))
1819n/a # Expected:
1820n/a ## 12
1821n/a <BLANKLINE>
1822n/a"""
1823n/a
1824n/adef test_debug(): r"""
1825n/a
1826n/aCreate a docstring that we want to debug:
1827n/a
1828n/a >>> s = '''
1829n/a ... >>> x = 12
1830n/a ... >>> print(x)
1831n/a ... 12
1832n/a ... '''
1833n/a
1834n/aCreate some fake stdin input, to feed to the debugger:
1835n/a
1836n/a >>> real_stdin = sys.stdin
1837n/a >>> sys.stdin = _FakeInput(['next', 'print(x)', 'continue'])
1838n/a
1839n/aRun the debugger on the docstring, and then restore sys.stdin.
1840n/a
1841n/a >>> try: doctest.debug_src(s)
1842n/a ... finally: sys.stdin = real_stdin
1843n/a > <string>(1)<module>()
1844n/a (Pdb) next
1845n/a 12
1846n/a --Return--
1847n/a > <string>(1)<module>()->None
1848n/a (Pdb) print(x)
1849n/a 12
1850n/a (Pdb) continue
1851n/a
1852n/a"""
1853n/a
1854n/aif not hasattr(sys, 'gettrace') or not sys.gettrace():
1855n/a def test_pdb_set_trace():
1856n/a """Using pdb.set_trace from a doctest.
1857n/a
1858n/a You can use pdb.set_trace from a doctest. To do so, you must
1859n/a retrieve the set_trace function from the pdb module at the time
1860n/a you use it. The doctest module changes sys.stdout so that it can
1861n/a capture program output. It also temporarily replaces pdb.set_trace
1862n/a with a version that restores stdout. This is necessary for you to
1863n/a see debugger output.
1864n/a
1865n/a >>> doc = '''
1866n/a ... >>> x = 42
1867n/a ... >>> raise Exception('clé')
1868n/a ... Traceback (most recent call last):
1869n/a ... Exception: clé
1870n/a ... >>> import pdb; pdb.set_trace()
1871n/a ... '''
1872n/a >>> parser = doctest.DocTestParser()
1873n/a >>> test = parser.get_doctest(doc, {}, "foo-bar@baz", "foo-bar@baz.py", 0)
1874n/a >>> runner = doctest.DocTestRunner(verbose=False)
1875n/a
1876n/a To demonstrate this, we'll create a fake standard input that
1877n/a captures our debugger input:
1878n/a
1879n/a >>> real_stdin = sys.stdin
1880n/a >>> sys.stdin = _FakeInput([
1881n/a ... 'print(x)', # print data defined by the example
1882n/a ... 'continue', # stop debugging
1883n/a ... ''])
1884n/a
1885n/a >>> try: runner.run(test)
1886n/a ... finally: sys.stdin = real_stdin
1887n/a --Return--
1888n/a > <doctest foo-bar@baz[2]>(1)<module>()->None
1889n/a -> import pdb; pdb.set_trace()
1890n/a (Pdb) print(x)
1891n/a 42
1892n/a (Pdb) continue
1893n/a TestResults(failed=0, attempted=3)
1894n/a
1895n/a You can also put pdb.set_trace in a function called from a test:
1896n/a
1897n/a >>> def calls_set_trace():
1898n/a ... y=2
1899n/a ... import pdb; pdb.set_trace()
1900n/a
1901n/a >>> doc = '''
1902n/a ... >>> x=1
1903n/a ... >>> calls_set_trace()
1904n/a ... '''
1905n/a >>> test = parser.get_doctest(doc, globals(), "foo-bar@baz", "foo-bar@baz.py", 0)
1906n/a >>> real_stdin = sys.stdin
1907n/a >>> sys.stdin = _FakeInput([
1908n/a ... 'print(y)', # print data defined in the function
1909n/a ... 'up', # out of function
1910n/a ... 'print(x)', # print data defined by the example
1911n/a ... 'continue', # stop debugging
1912n/a ... ''])
1913n/a
1914n/a >>> try:
1915n/a ... runner.run(test)
1916n/a ... finally:
1917n/a ... sys.stdin = real_stdin
1918n/a --Return--
1919n/a > <doctest test.test_doctest.test_pdb_set_trace[7]>(3)calls_set_trace()->None
1920n/a -> import pdb; pdb.set_trace()
1921n/a (Pdb) print(y)
1922n/a 2
1923n/a (Pdb) up
1924n/a > <doctest foo-bar@baz[1]>(1)<module>()
1925n/a -> calls_set_trace()
1926n/a (Pdb) print(x)
1927n/a 1
1928n/a (Pdb) continue
1929n/a TestResults(failed=0, attempted=2)
1930n/a
1931n/a During interactive debugging, source code is shown, even for
1932n/a doctest examples:
1933n/a
1934n/a >>> doc = '''
1935n/a ... >>> def f(x):
1936n/a ... ... g(x*2)
1937n/a ... >>> def g(x):
1938n/a ... ... print(x+3)
1939n/a ... ... import pdb; pdb.set_trace()
1940n/a ... >>> f(3)
1941n/a ... '''
1942n/a >>> test = parser.get_doctest(doc, globals(), "foo-bar@baz", "foo-bar@baz.py", 0)
1943n/a >>> real_stdin = sys.stdin
1944n/a >>> sys.stdin = _FakeInput([
1945n/a ... 'list', # list source from example 2
1946n/a ... 'next', # return from g()
1947n/a ... 'list', # list source from example 1
1948n/a ... 'next', # return from f()
1949n/a ... 'list', # list source from example 3
1950n/a ... 'continue', # stop debugging
1951n/a ... ''])
1952n/a >>> try: runner.run(test)
1953n/a ... finally: sys.stdin = real_stdin
1954n/a ... # doctest: +NORMALIZE_WHITESPACE
1955n/a --Return--
1956n/a > <doctest foo-bar@baz[1]>(3)g()->None
1957n/a -> import pdb; pdb.set_trace()
1958n/a (Pdb) list
1959n/a 1 def g(x):
1960n/a 2 print(x+3)
1961n/a 3 -> import pdb; pdb.set_trace()
1962n/a [EOF]
1963n/a (Pdb) next
1964n/a --Return--
1965n/a > <doctest foo-bar@baz[0]>(2)f()->None
1966n/a -> g(x*2)
1967n/a (Pdb) list
1968n/a 1 def f(x):
1969n/a 2 -> g(x*2)
1970n/a [EOF]
1971n/a (Pdb) next
1972n/a --Return--
1973n/a > <doctest foo-bar@baz[2]>(1)<module>()->None
1974n/a -> f(3)
1975n/a (Pdb) list
1976n/a 1 -> f(3)
1977n/a [EOF]
1978n/a (Pdb) continue
1979n/a **********************************************************************
1980n/a File "foo-bar@baz.py", line 7, in foo-bar@baz
1981n/a Failed example:
1982n/a f(3)
1983n/a Expected nothing
1984n/a Got:
1985n/a 9
1986n/a TestResults(failed=1, attempted=3)
1987n/a """
1988n/a
1989n/a def test_pdb_set_trace_nested():
1990n/a """This illustrates more-demanding use of set_trace with nested functions.
1991n/a
1992n/a >>> class C(object):
1993n/a ... def calls_set_trace(self):
1994n/a ... y = 1
1995n/a ... import pdb; pdb.set_trace()
1996n/a ... self.f1()
1997n/a ... y = 2
1998n/a ... def f1(self):
1999n/a ... x = 1
2000n/a ... self.f2()
2001n/a ... x = 2
2002n/a ... def f2(self):
2003n/a ... z = 1
2004n/a ... z = 2
2005n/a
2006n/a >>> calls_set_trace = C().calls_set_trace
2007n/a
2008n/a >>> doc = '''
2009n/a ... >>> a = 1
2010n/a ... >>> calls_set_trace()
2011n/a ... '''
2012n/a >>> parser = doctest.DocTestParser()
2013n/a >>> runner = doctest.DocTestRunner(verbose=False)
2014n/a >>> test = parser.get_doctest(doc, globals(), "foo-bar@baz", "foo-bar@baz.py", 0)
2015n/a >>> real_stdin = sys.stdin
2016n/a >>> sys.stdin = _FakeInput([
2017n/a ... 'print(y)', # print data defined in the function
2018n/a ... 'step', 'step', 'step', 'step', 'step', 'step', 'print(z)',
2019n/a ... 'up', 'print(x)',
2020n/a ... 'up', 'print(y)',
2021n/a ... 'up', 'print(foo)',
2022n/a ... 'continue', # stop debugging
2023n/a ... ''])
2024n/a
2025n/a >>> try:
2026n/a ... runner.run(test)
2027n/a ... finally:
2028n/a ... sys.stdin = real_stdin
2029n/a ... # doctest: +REPORT_NDIFF
2030n/a > <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(5)calls_set_trace()
2031n/a -> self.f1()
2032n/a (Pdb) print(y)
2033n/a 1
2034n/a (Pdb) step
2035n/a --Call--
2036n/a > <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(7)f1()
2037n/a -> def f1(self):
2038n/a (Pdb) step
2039n/a > <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(8)f1()
2040n/a -> x = 1
2041n/a (Pdb) step
2042n/a > <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(9)f1()
2043n/a -> self.f2()
2044n/a (Pdb) step
2045n/a --Call--
2046n/a > <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(11)f2()
2047n/a -> def f2(self):
2048n/a (Pdb) step
2049n/a > <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(12)f2()
2050n/a -> z = 1
2051n/a (Pdb) step
2052n/a > <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(13)f2()
2053n/a -> z = 2
2054n/a (Pdb) print(z)
2055n/a 1
2056n/a (Pdb) up
2057n/a > <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(9)f1()
2058n/a -> self.f2()
2059n/a (Pdb) print(x)
2060n/a 1
2061n/a (Pdb) up
2062n/a > <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(5)calls_set_trace()
2063n/a -> self.f1()
2064n/a (Pdb) print(y)
2065n/a 1
2066n/a (Pdb) up
2067n/a > <doctest foo-bar@baz[1]>(1)<module>()
2068n/a -> calls_set_trace()
2069n/a (Pdb) print(foo)
2070n/a *** NameError: name 'foo' is not defined
2071n/a (Pdb) continue
2072n/a TestResults(failed=0, attempted=2)
2073n/a """
2074n/a
2075n/adef test_DocTestSuite():
2076n/a """DocTestSuite creates a unittest test suite from a doctest.
2077n/a
2078n/a We create a Suite by providing a module. A module can be provided
2079n/a by passing a module object:
2080n/a
2081n/a >>> import unittest
2082n/a >>> import test.sample_doctest
2083n/a >>> suite = doctest.DocTestSuite(test.sample_doctest)
2084n/a >>> suite.run(unittest.TestResult())
2085n/a <unittest.result.TestResult run=9 errors=0 failures=4>
2086n/a
2087n/a We can also supply the module by name:
2088n/a
2089n/a >>> suite = doctest.DocTestSuite('test.sample_doctest')
2090n/a >>> suite.run(unittest.TestResult())
2091n/a <unittest.result.TestResult run=9 errors=0 failures=4>
2092n/a
2093n/a The module need not contain any doctest examples:
2094n/a
2095n/a >>> suite = doctest.DocTestSuite('test.sample_doctest_no_doctests')
2096n/a >>> suite.run(unittest.TestResult())
2097n/a <unittest.result.TestResult run=0 errors=0 failures=0>
2098n/a
2099n/a The module need not contain any docstrings either:
2100n/a
2101n/a >>> suite = doctest.DocTestSuite('test.sample_doctest_no_docstrings')
2102n/a >>> suite.run(unittest.TestResult())
2103n/a <unittest.result.TestResult run=0 errors=0 failures=0>
2104n/a
2105n/a We can use the current module:
2106n/a
2107n/a >>> suite = test.sample_doctest.test_suite()
2108n/a >>> suite.run(unittest.TestResult())
2109n/a <unittest.result.TestResult run=9 errors=0 failures=4>
2110n/a
2111n/a We can also provide a DocTestFinder:
2112n/a
2113n/a >>> finder = doctest.DocTestFinder()
2114n/a >>> suite = doctest.DocTestSuite('test.sample_doctest',
2115n/a ... test_finder=finder)
2116n/a >>> suite.run(unittest.TestResult())
2117n/a <unittest.result.TestResult run=9 errors=0 failures=4>
2118n/a
2119n/a The DocTestFinder need not return any tests:
2120n/a
2121n/a >>> finder = doctest.DocTestFinder()
2122n/a >>> suite = doctest.DocTestSuite('test.sample_doctest_no_docstrings',
2123n/a ... test_finder=finder)
2124n/a >>> suite.run(unittest.TestResult())
2125n/a <unittest.result.TestResult run=0 errors=0 failures=0>
2126n/a
2127n/a We can supply global variables. If we pass globs, they will be
2128n/a used instead of the module globals. Here we'll pass an empty
2129n/a globals, triggering an extra error:
2130n/a
2131n/a >>> suite = doctest.DocTestSuite('test.sample_doctest', globs={})
2132n/a >>> suite.run(unittest.TestResult())
2133n/a <unittest.result.TestResult run=9 errors=0 failures=5>
2134n/a
2135n/a Alternatively, we can provide extra globals. Here we'll make an
2136n/a error go away by providing an extra global variable:
2137n/a
2138n/a >>> suite = doctest.DocTestSuite('test.sample_doctest',
2139n/a ... extraglobs={'y': 1})
2140n/a >>> suite.run(unittest.TestResult())
2141n/a <unittest.result.TestResult run=9 errors=0 failures=3>
2142n/a
2143n/a You can pass option flags. Here we'll cause an extra error
2144n/a by disabling the blank-line feature:
2145n/a
2146n/a >>> suite = doctest.DocTestSuite('test.sample_doctest',
2147n/a ... optionflags=doctest.DONT_ACCEPT_BLANKLINE)
2148n/a >>> suite.run(unittest.TestResult())
2149n/a <unittest.result.TestResult run=9 errors=0 failures=5>
2150n/a
2151n/a You can supply setUp and tearDown functions:
2152n/a
2153n/a >>> def setUp(t):
2154n/a ... import test.test_doctest
2155n/a ... test.test_doctest.sillySetup = True
2156n/a
2157n/a >>> def tearDown(t):
2158n/a ... import test.test_doctest
2159n/a ... del test.test_doctest.sillySetup
2160n/a
2161n/a Here, we installed a silly variable that the test expects:
2162n/a
2163n/a >>> suite = doctest.DocTestSuite('test.sample_doctest',
2164n/a ... setUp=setUp, tearDown=tearDown)
2165n/a >>> suite.run(unittest.TestResult())
2166n/a <unittest.result.TestResult run=9 errors=0 failures=3>
2167n/a
2168n/a But the tearDown restores sanity:
2169n/a
2170n/a >>> import test.test_doctest
2171n/a >>> test.test_doctest.sillySetup
2172n/a Traceback (most recent call last):
2173n/a ...
2174n/a AttributeError: module 'test.test_doctest' has no attribute 'sillySetup'
2175n/a
2176n/a The setUp and tearDown functions are passed test objects. Here
2177n/a we'll use the setUp function to supply the missing variable y:
2178n/a
2179n/a >>> def setUp(test):
2180n/a ... test.globs['y'] = 1
2181n/a
2182n/a >>> suite = doctest.DocTestSuite('test.sample_doctest', setUp=setUp)
2183n/a >>> suite.run(unittest.TestResult())
2184n/a <unittest.result.TestResult run=9 errors=0 failures=3>
2185n/a
2186n/a Here, we didn't need to use a tearDown function because we
2187n/a modified the test globals, which are a copy of the
2188n/a sample_doctest module dictionary. The test globals are
2189n/a automatically cleared for us after a test.
2190n/a """
2191n/a
2192n/adef test_DocFileSuite():
2193n/a """We can test tests found in text files using a DocFileSuite.
2194n/a
2195n/a We create a suite by providing the names of one or more text
2196n/a files that include examples:
2197n/a
2198n/a >>> import unittest
2199n/a >>> suite = doctest.DocFileSuite('test_doctest.txt',
2200n/a ... 'test_doctest2.txt',
2201n/a ... 'test_doctest4.txt')
2202n/a >>> suite.run(unittest.TestResult())
2203n/a <unittest.result.TestResult run=3 errors=0 failures=2>
2204n/a
2205n/a The test files are looked for in the directory containing the
2206n/a calling module. A package keyword argument can be provided to
2207n/a specify a different relative location.
2208n/a
2209n/a >>> import unittest
2210n/a >>> suite = doctest.DocFileSuite('test_doctest.txt',
2211n/a ... 'test_doctest2.txt',
2212n/a ... 'test_doctest4.txt',
2213n/a ... package='test')
2214n/a >>> suite.run(unittest.TestResult())
2215n/a <unittest.result.TestResult run=3 errors=0 failures=2>
2216n/a
2217n/a Support for using a package's __loader__.get_data() is also
2218n/a provided.
2219n/a
2220n/a >>> import unittest, pkgutil, test
2221n/a >>> added_loader = False
2222n/a >>> if not hasattr(test, '__loader__'):
2223n/a ... test.__loader__ = pkgutil.get_loader(test)
2224n/a ... added_loader = True
2225n/a >>> try:
2226n/a ... suite = doctest.DocFileSuite('test_doctest.txt',
2227n/a ... 'test_doctest2.txt',
2228n/a ... 'test_doctest4.txt',
2229n/a ... package='test')
2230n/a ... suite.run(unittest.TestResult())
2231n/a ... finally:
2232n/a ... if added_loader:
2233n/a ... del test.__loader__
2234n/a <unittest.result.TestResult run=3 errors=0 failures=2>
2235n/a
2236n/a '/' should be used as a path separator. It will be converted
2237n/a to a native separator at run time:
2238n/a
2239n/a >>> suite = doctest.DocFileSuite('../test/test_doctest.txt')
2240n/a >>> suite.run(unittest.TestResult())
2241n/a <unittest.result.TestResult run=1 errors=0 failures=1>
2242n/a
2243n/a If DocFileSuite is used from an interactive session, then files
2244n/a are resolved relative to the directory of sys.argv[0]:
2245n/a
2246n/a >>> import types, os.path, test.test_doctest
2247n/a >>> save_argv = sys.argv
2248n/a >>> sys.argv = [test.test_doctest.__file__]
2249n/a >>> suite = doctest.DocFileSuite('test_doctest.txt',
2250n/a ... package=types.ModuleType('__main__'))
2251n/a >>> sys.argv = save_argv
2252n/a
2253n/a By setting `module_relative=False`, os-specific paths may be
2254n/a used (including absolute paths and paths relative to the
2255n/a working directory):
2256n/a
2257n/a >>> # Get the absolute path of the test package.
2258n/a >>> test_doctest_path = os.path.abspath(test.test_doctest.__file__)
2259n/a >>> test_pkg_path = os.path.split(test_doctest_path)[0]
2260n/a
2261n/a >>> # Use it to find the absolute path of test_doctest.txt.
2262n/a >>> test_file = os.path.join(test_pkg_path, 'test_doctest.txt')
2263n/a
2264n/a >>> suite = doctest.DocFileSuite(test_file, module_relative=False)
2265n/a >>> suite.run(unittest.TestResult())
2266n/a <unittest.result.TestResult run=1 errors=0 failures=1>
2267n/a
2268n/a It is an error to specify `package` when `module_relative=False`:
2269n/a
2270n/a >>> suite = doctest.DocFileSuite(test_file, module_relative=False,
2271n/a ... package='test')
2272n/a Traceback (most recent call last):
2273n/a ValueError: Package may only be specified for module-relative paths.
2274n/a
2275n/a You can specify initial global variables:
2276n/a
2277n/a >>> suite = doctest.DocFileSuite('test_doctest.txt',
2278n/a ... 'test_doctest2.txt',
2279n/a ... 'test_doctest4.txt',
2280n/a ... globs={'favorite_color': 'blue'})
2281n/a >>> suite.run(unittest.TestResult())
2282n/a <unittest.result.TestResult run=3 errors=0 failures=1>
2283n/a
2284n/a In this case, we supplied a missing favorite color. You can
2285n/a provide doctest options:
2286n/a
2287n/a >>> suite = doctest.DocFileSuite('test_doctest.txt',
2288n/a ... 'test_doctest2.txt',
2289n/a ... 'test_doctest4.txt',
2290n/a ... optionflags=doctest.DONT_ACCEPT_BLANKLINE,
2291n/a ... globs={'favorite_color': 'blue'})
2292n/a >>> suite.run(unittest.TestResult())
2293n/a <unittest.result.TestResult run=3 errors=0 failures=2>
2294n/a
2295n/a And, you can provide setUp and tearDown functions:
2296n/a
2297n/a >>> def setUp(t):
2298n/a ... import test.test_doctest
2299n/a ... test.test_doctest.sillySetup = True
2300n/a
2301n/a >>> def tearDown(t):
2302n/a ... import test.test_doctest
2303n/a ... del test.test_doctest.sillySetup
2304n/a
2305n/a Here, we installed a silly variable that the test expects:
2306n/a
2307n/a >>> suite = doctest.DocFileSuite('test_doctest.txt',
2308n/a ... 'test_doctest2.txt',
2309n/a ... 'test_doctest4.txt',
2310n/a ... setUp=setUp, tearDown=tearDown)
2311n/a >>> suite.run(unittest.TestResult())
2312n/a <unittest.result.TestResult run=3 errors=0 failures=1>
2313n/a
2314n/a But the tearDown restores sanity:
2315n/a
2316n/a >>> import test.test_doctest
2317n/a >>> test.test_doctest.sillySetup
2318n/a Traceback (most recent call last):
2319n/a ...
2320n/a AttributeError: module 'test.test_doctest' has no attribute 'sillySetup'
2321n/a
2322n/a The setUp and tearDown functions are passed test objects.
2323n/a Here, we'll use a setUp function to set the favorite color in
2324n/a test_doctest.txt:
2325n/a
2326n/a >>> def setUp(test):
2327n/a ... test.globs['favorite_color'] = 'blue'
2328n/a
2329n/a >>> suite = doctest.DocFileSuite('test_doctest.txt', setUp=setUp)
2330n/a >>> suite.run(unittest.TestResult())
2331n/a <unittest.result.TestResult run=1 errors=0 failures=0>
2332n/a
2333n/a Here, we didn't need to use a tearDown function because we
2334n/a modified the test globals. The test globals are
2335n/a automatically cleared for us after a test.
2336n/a
2337n/a Tests in a file run using `DocFileSuite` can also access the
2338n/a `__file__` global, which is set to the name of the file
2339n/a containing the tests:
2340n/a
2341n/a >>> suite = doctest.DocFileSuite('test_doctest3.txt')
2342n/a >>> suite.run(unittest.TestResult())
2343n/a <unittest.result.TestResult run=1 errors=0 failures=0>
2344n/a
2345n/a If the tests contain non-ASCII characters, we have to specify which
2346n/a encoding the file is encoded with. We do so by using the `encoding`
2347n/a parameter:
2348n/a
2349n/a >>> suite = doctest.DocFileSuite('test_doctest.txt',
2350n/a ... 'test_doctest2.txt',
2351n/a ... 'test_doctest4.txt',
2352n/a ... encoding='utf-8')
2353n/a >>> suite.run(unittest.TestResult())
2354n/a <unittest.result.TestResult run=3 errors=0 failures=2>
2355n/a
2356n/a """
2357n/a
2358n/adef test_trailing_space_in_test():
2359n/a """
2360n/a Trailing spaces in expected output are significant:
2361n/a
2362n/a >>> x, y = 'foo', ''
2363n/a >>> print(x, y)
2364n/a foo \n
2365n/a """
2366n/a
2367n/aclass Wrapper:
2368n/a def __init__(self, func):
2369n/a self.func = func
2370n/a functools.update_wrapper(self, func)
2371n/a
2372n/a def __call__(self, *args, **kwargs):
2373n/a self.func(*args, **kwargs)
2374n/a
2375n/a@Wrapper
2376n/adef test_look_in_unwrapped():
2377n/a """
2378n/a Docstrings in wrapped functions must be detected as well.
2379n/a
2380n/a >>> 'one other test'
2381n/a 'one other test'
2382n/a """
2383n/a
2384n/adef test_unittest_reportflags():
2385n/a """Default unittest reporting flags can be set to control reporting
2386n/a
2387n/a Here, we'll set the REPORT_ONLY_FIRST_FAILURE option so we see
2388n/a only the first failure of each test. First, we'll look at the
2389n/a output without the flag. The file test_doctest.txt file has two
2390n/a tests. They both fail if blank lines are disabled:
2391n/a
2392n/a >>> suite = doctest.DocFileSuite('test_doctest.txt',
2393n/a ... optionflags=doctest.DONT_ACCEPT_BLANKLINE)
2394n/a >>> import unittest
2395n/a >>> result = suite.run(unittest.TestResult())
2396n/a >>> print(result.failures[0][1]) # doctest: +ELLIPSIS
2397n/a Traceback ...
2398n/a Failed example:
2399n/a favorite_color
2400n/a ...
2401n/a Failed example:
2402n/a if 1:
2403n/a ...
2404n/a
2405n/a Note that we see both failures displayed.
2406n/a
2407n/a >>> old = doctest.set_unittest_reportflags(
2408n/a ... doctest.REPORT_ONLY_FIRST_FAILURE)
2409n/a
2410n/a Now, when we run the test:
2411n/a
2412n/a >>> result = suite.run(unittest.TestResult())
2413n/a >>> print(result.failures[0][1]) # doctest: +ELLIPSIS
2414n/a Traceback ...
2415n/a Failed example:
2416n/a favorite_color
2417n/a Exception raised:
2418n/a ...
2419n/a NameError: name 'favorite_color' is not defined
2420n/a <BLANKLINE>
2421n/a <BLANKLINE>
2422n/a
2423n/a We get only the first failure.
2424n/a
2425n/a If we give any reporting options when we set up the tests,
2426n/a however:
2427n/a
2428n/a >>> suite = doctest.DocFileSuite('test_doctest.txt',
2429n/a ... optionflags=doctest.DONT_ACCEPT_BLANKLINE | doctest.REPORT_NDIFF)
2430n/a
2431n/a Then the default eporting options are ignored:
2432n/a
2433n/a >>> result = suite.run(unittest.TestResult())
2434n/a >>> print(result.failures[0][1]) # doctest: +ELLIPSIS
2435n/a Traceback ...
2436n/a Failed example:
2437n/a favorite_color
2438n/a ...
2439n/a Failed example:
2440n/a if 1:
2441n/a print('a')
2442n/a print()
2443n/a print('b')
2444n/a Differences (ndiff with -expected +actual):
2445n/a a
2446n/a - <BLANKLINE>
2447n/a +
2448n/a b
2449n/a <BLANKLINE>
2450n/a <BLANKLINE>
2451n/a
2452n/a
2453n/a Test runners can restore the formatting flags after they run:
2454n/a
2455n/a >>> ignored = doctest.set_unittest_reportflags(old)
2456n/a
2457n/a """
2458n/a
2459n/adef test_testfile(): r"""
2460n/aTests for the `testfile()` function. This function runs all the
2461n/adoctest examples in a given file. In its simple invokation, it is
2462n/acalled with the name of a file, which is taken to be relative to the
2463n/acalling module. The return value is (#failures, #tests).
2464n/a
2465n/aWe don't want `-v` in sys.argv for these tests.
2466n/a
2467n/a >>> save_argv = sys.argv
2468n/a >>> if '-v' in sys.argv:
2469n/a ... sys.argv = [arg for arg in save_argv if arg != '-v']
2470n/a
2471n/a
2472n/a >>> doctest.testfile('test_doctest.txt') # doctest: +ELLIPSIS
2473n/a **********************************************************************
2474n/a File "...", line 6, in test_doctest.txt
2475n/a Failed example:
2476n/a favorite_color
2477n/a Exception raised:
2478n/a ...
2479n/a NameError: name 'favorite_color' is not defined
2480n/a **********************************************************************
2481n/a 1 items had failures:
2482n/a 1 of 2 in test_doctest.txt
2483n/a ***Test Failed*** 1 failures.
2484n/a TestResults(failed=1, attempted=2)
2485n/a >>> doctest.master = None # Reset master.
2486n/a
2487n/a(Note: we'll be clearing doctest.master after each call to
2488n/a`doctest.testfile`, to suppress warnings about multiple tests with the
2489n/asame name.)
2490n/a
2491n/aGlobals may be specified with the `globs` and `extraglobs` parameters:
2492n/a
2493n/a >>> globs = {'favorite_color': 'blue'}
2494n/a >>> doctest.testfile('test_doctest.txt', globs=globs)
2495n/a TestResults(failed=0, attempted=2)
2496n/a >>> doctest.master = None # Reset master.
2497n/a
2498n/a >>> extraglobs = {'favorite_color': 'red'}
2499n/a >>> doctest.testfile('test_doctest.txt', globs=globs,
2500n/a ... extraglobs=extraglobs) # doctest: +ELLIPSIS
2501n/a **********************************************************************
2502n/a File "...", line 6, in test_doctest.txt
2503n/a Failed example:
2504n/a favorite_color
2505n/a Expected:
2506n/a 'blue'
2507n/a Got:
2508n/a 'red'
2509n/a **********************************************************************
2510n/a 1 items had failures:
2511n/a 1 of 2 in test_doctest.txt
2512n/a ***Test Failed*** 1 failures.
2513n/a TestResults(failed=1, attempted=2)
2514n/a >>> doctest.master = None # Reset master.
2515n/a
2516n/aThe file may be made relative to a given module or package, using the
2517n/aoptional `module_relative` parameter:
2518n/a
2519n/a >>> doctest.testfile('test_doctest.txt', globs=globs,
2520n/a ... module_relative='test')
2521n/a TestResults(failed=0, attempted=2)
2522n/a >>> doctest.master = None # Reset master.
2523n/a
2524n/aVerbosity can be increased with the optional `verbose` parameter:
2525n/a
2526n/a >>> doctest.testfile('test_doctest.txt', globs=globs, verbose=True)
2527n/a Trying:
2528n/a favorite_color
2529n/a Expecting:
2530n/a 'blue'
2531n/a ok
2532n/a Trying:
2533n/a if 1:
2534n/a print('a')
2535n/a print()
2536n/a print('b')
2537n/a Expecting:
2538n/a a
2539n/a <BLANKLINE>
2540n/a b
2541n/a ok
2542n/a 1 items passed all tests:
2543n/a 2 tests in test_doctest.txt
2544n/a 2 tests in 1 items.
2545n/a 2 passed and 0 failed.
2546n/a Test passed.
2547n/a TestResults(failed=0, attempted=2)
2548n/a >>> doctest.master = None # Reset master.
2549n/a
2550n/aThe name of the test may be specified with the optional `name`
2551n/aparameter:
2552n/a
2553n/a >>> doctest.testfile('test_doctest.txt', name='newname')
2554n/a ... # doctest: +ELLIPSIS
2555n/a **********************************************************************
2556n/a File "...", line 6, in newname
2557n/a ...
2558n/a TestResults(failed=1, attempted=2)
2559n/a >>> doctest.master = None # Reset master.
2560n/a
2561n/aThe summary report may be suppressed with the optional `report`
2562n/aparameter:
2563n/a
2564n/a >>> doctest.testfile('test_doctest.txt', report=False)
2565n/a ... # doctest: +ELLIPSIS
2566n/a **********************************************************************
2567n/a File "...", line 6, in test_doctest.txt
2568n/a Failed example:
2569n/a favorite_color
2570n/a Exception raised:
2571n/a ...
2572n/a NameError: name 'favorite_color' is not defined
2573n/a TestResults(failed=1, attempted=2)
2574n/a >>> doctest.master = None # Reset master.
2575n/a
2576n/aThe optional keyword argument `raise_on_error` can be used to raise an
2577n/aexception on the first error (which may be useful for postmortem
2578n/adebugging):
2579n/a
2580n/a >>> doctest.testfile('test_doctest.txt', raise_on_error=True)
2581n/a ... # doctest: +ELLIPSIS
2582n/a Traceback (most recent call last):
2583n/a doctest.UnexpectedException: ...
2584n/a >>> doctest.master = None # Reset master.
2585n/a
2586n/aIf the tests contain non-ASCII characters, the tests might fail, since
2587n/ait's unknown which encoding is used. The encoding can be specified
2588n/ausing the optional keyword argument `encoding`:
2589n/a
2590n/a >>> doctest.testfile('test_doctest4.txt', encoding='latin-1') # doctest: +ELLIPSIS
2591n/a **********************************************************************
2592n/a File "...", line 7, in test_doctest4.txt
2593n/a Failed example:
2594n/a '...'
2595n/a Expected:
2596n/a 'f\xf6\xf6'
2597n/a Got:
2598n/a 'f\xc3\xb6\xc3\xb6'
2599n/a **********************************************************************
2600n/a ...
2601n/a **********************************************************************
2602n/a 1 items had failures:
2603n/a 2 of 2 in test_doctest4.txt
2604n/a ***Test Failed*** 2 failures.
2605n/a TestResults(failed=2, attempted=2)
2606n/a >>> doctest.master = None # Reset master.
2607n/a
2608n/a >>> doctest.testfile('test_doctest4.txt', encoding='utf-8')
2609n/a TestResults(failed=0, attempted=2)
2610n/a >>> doctest.master = None # Reset master.
2611n/a
2612n/aTest the verbose output:
2613n/a
2614n/a >>> doctest.testfile('test_doctest4.txt', encoding='utf-8', verbose=True)
2615n/a Trying:
2616n/a 'föö'
2617n/a Expecting:
2618n/a 'f\xf6\xf6'
2619n/a ok
2620n/a Trying:
2621n/a 'bąr'
2622n/a Expecting:
2623n/a 'b\u0105r'
2624n/a ok
2625n/a 1 items passed all tests:
2626n/a 2 tests in test_doctest4.txt
2627n/a 2 tests in 1 items.
2628n/a 2 passed and 0 failed.
2629n/a Test passed.
2630n/a TestResults(failed=0, attempted=2)
2631n/a >>> doctest.master = None # Reset master.
2632n/a >>> sys.argv = save_argv
2633n/a"""
2634n/a
2635n/adef test_lineendings(): r"""
2636n/a*nix systems use \n line endings, while Windows systems use \r\n. Python
2637n/ahandles this using universal newline mode for reading files. Let's make
2638n/asure doctest does so (issue 8473) by creating temporary test files using each
2639n/aof the two line disciplines. One of the two will be the "wrong" one for the
2640n/aplatform the test is run on.
2641n/a
2642n/aWindows line endings first:
2643n/a
2644n/a >>> import tempfile, os
2645n/a >>> fn = tempfile.mktemp()
2646n/a >>> with open(fn, 'wb') as f:
2647n/a ... f.write(b'Test:\r\n\r\n >>> x = 1 + 1\r\n\r\nDone.\r\n')
2648n/a 35
2649n/a >>> doctest.testfile(fn, module_relative=False, verbose=False)
2650n/a TestResults(failed=0, attempted=1)
2651n/a >>> os.remove(fn)
2652n/a
2653n/aAnd now *nix line endings:
2654n/a
2655n/a >>> fn = tempfile.mktemp()
2656n/a >>> with open(fn, 'wb') as f:
2657n/a ... f.write(b'Test:\n\n >>> x = 1 + 1\n\nDone.\n')
2658n/a 30
2659n/a >>> doctest.testfile(fn, module_relative=False, verbose=False)
2660n/a TestResults(failed=0, attempted=1)
2661n/a >>> os.remove(fn)
2662n/a
2663n/a"""
2664n/a
2665n/adef test_testmod(): r"""
2666n/aTests for the testmod function. More might be useful, but for now we're just
2667n/atesting the case raised by Issue 6195, where trying to doctest a C module would
2668n/afail with a UnicodeDecodeError because doctest tried to read the "source" lines
2669n/aout of the binary module.
2670n/a
2671n/a >>> import unicodedata
2672n/a >>> doctest.testmod(unicodedata, verbose=False)
2673n/a TestResults(failed=0, attempted=0)
2674n/a"""
2675n/a
2676n/atry:
2677n/a os.fsencode("foo-bär@baz.py")
2678n/aexcept UnicodeEncodeError:
2679n/a # Skip the test: the filesystem encoding is unable to encode the filename
2680n/a pass
2681n/aelse:
2682n/a def test_unicode(): """
2683n/aCheck doctest with a non-ascii filename:
2684n/a
2685n/a >>> doc = '''
2686n/a ... >>> raise Exception('clé')
2687n/a ... '''
2688n/a ...
2689n/a >>> parser = doctest.DocTestParser()
2690n/a >>> test = parser.get_doctest(doc, {}, "foo-bär@baz", "foo-bär@baz.py", 0)
2691n/a >>> test
2692n/a <DocTest foo-bär@baz from foo-bär@baz.py:0 (1 example)>
2693n/a >>> runner = doctest.DocTestRunner(verbose=False)
2694n/a >>> runner.run(test) # doctest: +ELLIPSIS
2695n/a **********************************************************************
2696n/a File "foo-bär@baz.py", line 2, in foo-bär@baz
2697n/a Failed example:
2698n/a raise Exception('clé')
2699n/a Exception raised:
2700n/a Traceback (most recent call last):
2701n/a File ...
2702n/a compileflags, 1), test.globs)
2703n/a File "<doctest foo-bär@baz[0]>", line 1, in <module>
2704n/a raise Exception('clé')
2705n/a Exception: clé
2706n/a TestResults(failed=1, attempted=1)
2707n/a """
2708n/a
2709n/adef test_CLI(): r"""
2710n/aThe doctest module can be used to run doctests against an arbitrary file.
2711n/aThese tests test this CLI functionality.
2712n/a
2713n/aWe'll use the support module's script_helpers for this, and write a test files
2714n/ato a temp dir to run the command against. Due to a current limitation in
2715n/ascript_helpers, though, we need a little utility function to turn the returned
2716n/aoutput into something we can doctest against:
2717n/a
2718n/a >>> def normalize(s):
2719n/a ... return '\n'.join(s.decode().splitlines())
2720n/a
2721n/aWith those preliminaries out of the way, we'll start with a file with two
2722n/asimple tests and no errors. We'll run both the unadorned doctest command, and
2723n/athe verbose version, and then check the output:
2724n/a
2725n/a >>> from test.support import script_helper, temp_dir
2726n/a >>> with temp_dir() as tmpdir:
2727n/a ... fn = os.path.join(tmpdir, 'myfile.doc')
2728n/a ... with open(fn, 'w') as f:
2729n/a ... _ = f.write('This is a very simple test file.\n')
2730n/a ... _ = f.write(' >>> 1 + 1\n')
2731n/a ... _ = f.write(' 2\n')
2732n/a ... _ = f.write(' >>> "a"\n')
2733n/a ... _ = f.write(" 'a'\n")
2734n/a ... _ = f.write('\n')
2735n/a ... _ = f.write('And that is it.\n')
2736n/a ... rc1, out1, err1 = script_helper.assert_python_ok(
2737n/a ... '-m', 'doctest', fn)
2738n/a ... rc2, out2, err2 = script_helper.assert_python_ok(
2739n/a ... '-m', 'doctest', '-v', fn)
2740n/a
2741n/aWith no arguments and passing tests, we should get no output:
2742n/a
2743n/a >>> rc1, out1, err1
2744n/a (0, b'', b'')
2745n/a
2746n/aWith the verbose flag, we should see the test output, but no error output:
2747n/a
2748n/a >>> rc2, err2
2749n/a (0, b'')
2750n/a >>> print(normalize(out2))
2751n/a Trying:
2752n/a 1 + 1
2753n/a Expecting:
2754n/a 2
2755n/a ok
2756n/a Trying:
2757n/a "a"
2758n/a Expecting:
2759n/a 'a'
2760n/a ok
2761n/a 1 items passed all tests:
2762n/a 2 tests in myfile.doc
2763n/a 2 tests in 1 items.
2764n/a 2 passed and 0 failed.
2765n/a Test passed.
2766n/a
2767n/aNow we'll write a couple files, one with three tests, the other a python module
2768n/awith two tests, both of the files having "errors" in the tests that can be made
2769n/anon-errors by applying the appropriate doctest options to the run (ELLIPSIS in
2770n/athe first file, NORMALIZE_WHITESPACE in the second). This combination will
2771n/aallow thoroughly testing the -f and -o flags, as well as the doctest command's
2772n/aability to process more than one file on the command line and, since the second
2773n/afile ends in '.py', its handling of python module files (as opposed to straight
2774n/atext files).
2775n/a
2776n/a >>> from test.support import script_helper, temp_dir
2777n/a >>> with temp_dir() as tmpdir:
2778n/a ... fn = os.path.join(tmpdir, 'myfile.doc')
2779n/a ... with open(fn, 'w') as f:
2780n/a ... _ = f.write('This is another simple test file.\n')
2781n/a ... _ = f.write(' >>> 1 + 1\n')
2782n/a ... _ = f.write(' 2\n')
2783n/a ... _ = f.write(' >>> "abcdef"\n')
2784n/a ... _ = f.write(" 'a...f'\n")
2785n/a ... _ = f.write(' >>> "ajkml"\n')
2786n/a ... _ = f.write(" 'a...l'\n")
2787n/a ... _ = f.write('\n')
2788n/a ... _ = f.write('And that is it.\n')
2789n/a ... fn2 = os.path.join(tmpdir, 'myfile2.py')
2790n/a ... with open(fn2, 'w') as f:
2791n/a ... _ = f.write('def test_func():\n')
2792n/a ... _ = f.write(' \"\"\"\n')
2793n/a ... _ = f.write(' This is simple python test function.\n')
2794n/a ... _ = f.write(' >>> 1 + 1\n')
2795n/a ... _ = f.write(' 2\n')
2796n/a ... _ = f.write(' >>> "abc def"\n')
2797n/a ... _ = f.write(" 'abc def'\n")
2798n/a ... _ = f.write("\n")
2799n/a ... _ = f.write(' \"\"\"\n')
2800n/a ... rc1, out1, err1 = script_helper.assert_python_failure(
2801n/a ... '-m', 'doctest', fn, fn2)
2802n/a ... rc2, out2, err2 = script_helper.assert_python_ok(
2803n/a ... '-m', 'doctest', '-o', 'ELLIPSIS', fn)
2804n/a ... rc3, out3, err3 = script_helper.assert_python_ok(
2805n/a ... '-m', 'doctest', '-o', 'ELLIPSIS',
2806n/a ... '-o', 'NORMALIZE_WHITESPACE', fn, fn2)
2807n/a ... rc4, out4, err4 = script_helper.assert_python_failure(
2808n/a ... '-m', 'doctest', '-f', fn, fn2)
2809n/a ... rc5, out5, err5 = script_helper.assert_python_ok(
2810n/a ... '-m', 'doctest', '-v', '-o', 'ELLIPSIS',
2811n/a ... '-o', 'NORMALIZE_WHITESPACE', fn, fn2)
2812n/a
2813n/aOur first test run will show the errors from the first file (doctest stops if a
2814n/afile has errors). Note that doctest test-run error output appears on stdout,
2815n/anot stderr:
2816n/a
2817n/a >>> rc1, err1
2818n/a (1, b'')
2819n/a >>> print(normalize(out1)) # doctest: +ELLIPSIS
2820n/a **********************************************************************
2821n/a File "...myfile.doc", line 4, in myfile.doc
2822n/a Failed example:
2823n/a "abcdef"
2824n/a Expected:
2825n/a 'a...f'
2826n/a Got:
2827n/a 'abcdef'
2828n/a **********************************************************************
2829n/a File "...myfile.doc", line 6, in myfile.doc
2830n/a Failed example:
2831n/a "ajkml"
2832n/a Expected:
2833n/a 'a...l'
2834n/a Got:
2835n/a 'ajkml'
2836n/a **********************************************************************
2837n/a 1 items had failures:
2838n/a 2 of 3 in myfile.doc
2839n/a ***Test Failed*** 2 failures.
2840n/a
2841n/aWith -o ELLIPSIS specified, the second run, against just the first file, should
2842n/aproduce no errors, and with -o NORMALIZE_WHITESPACE also specified, neither
2843n/ashould the third, which ran against both files:
2844n/a
2845n/a >>> rc2, out2, err2
2846n/a (0, b'', b'')
2847n/a >>> rc3, out3, err3
2848n/a (0, b'', b'')
2849n/a
2850n/aThe fourth run uses FAIL_FAST, so we should see only one error:
2851n/a
2852n/a >>> rc4, err4
2853n/a (1, b'')
2854n/a >>> print(normalize(out4)) # doctest: +ELLIPSIS
2855n/a **********************************************************************
2856n/a File "...myfile.doc", line 4, in myfile.doc
2857n/a Failed example:
2858n/a "abcdef"
2859n/a Expected:
2860n/a 'a...f'
2861n/a Got:
2862n/a 'abcdef'
2863n/a **********************************************************************
2864n/a 1 items had failures:
2865n/a 1 of 2 in myfile.doc
2866n/a ***Test Failed*** 1 failures.
2867n/a
2868n/aThe fifth test uses verbose with the two options, so we should get verbose
2869n/asuccess output for the tests in both files:
2870n/a
2871n/a >>> rc5, err5
2872n/a (0, b'')
2873n/a >>> print(normalize(out5))
2874n/a Trying:
2875n/a 1 + 1
2876n/a Expecting:
2877n/a 2
2878n/a ok
2879n/a Trying:
2880n/a "abcdef"
2881n/a Expecting:
2882n/a 'a...f'
2883n/a ok
2884n/a Trying:
2885n/a "ajkml"
2886n/a Expecting:
2887n/a 'a...l'
2888n/a ok
2889n/a 1 items passed all tests:
2890n/a 3 tests in myfile.doc
2891n/a 3 tests in 1 items.
2892n/a 3 passed and 0 failed.
2893n/a Test passed.
2894n/a Trying:
2895n/a 1 + 1
2896n/a Expecting:
2897n/a 2
2898n/a ok
2899n/a Trying:
2900n/a "abc def"
2901n/a Expecting:
2902n/a 'abc def'
2903n/a ok
2904n/a 1 items had no tests:
2905n/a myfile2
2906n/a 1 items passed all tests:
2907n/a 2 tests in myfile2.test_func
2908n/a 2 tests in 2 items.
2909n/a 2 passed and 0 failed.
2910n/a Test passed.
2911n/a
2912n/aWe should also check some typical error cases.
2913n/a
2914n/aInvalid file name:
2915n/a
2916n/a >>> rc, out, err = script_helper.assert_python_failure(
2917n/a ... '-m', 'doctest', 'nosuchfile')
2918n/a >>> rc, out
2919n/a (1, b'')
2920n/a >>> print(normalize(err)) # doctest: +ELLIPSIS
2921n/a Traceback (most recent call last):
2922n/a ...
2923n/a FileNotFoundError: [Errno ...] No such file or directory: 'nosuchfile'
2924n/a
2925n/aInvalid doctest option:
2926n/a
2927n/a >>> rc, out, err = script_helper.assert_python_failure(
2928n/a ... '-m', 'doctest', '-o', 'nosuchoption')
2929n/a >>> rc, out
2930n/a (2, b'')
2931n/a >>> print(normalize(err)) # doctest: +ELLIPSIS
2932n/a usage...invalid...nosuchoption...
2933n/a
2934n/a"""
2935n/a
2936n/a######################################################################
2937n/a## Main
2938n/a######################################################################
2939n/a
2940n/adef test_main():
2941n/a # Check the doctest cases in doctest itself:
2942n/a ret = support.run_doctest(doctest, verbosity=True)
2943n/a
2944n/a # Check the doctest cases defined here:
2945n/a from test import test_doctest
2946n/a support.run_doctest(test_doctest, verbosity=True)
2947n/a
2948n/adef test_coverage(coverdir):
2949n/a trace = support.import_module('trace')
2950n/a tracer = trace.Trace(ignoredirs=[sys.base_prefix, sys.base_exec_prefix,],
2951n/a trace=0, count=1)
2952n/a tracer.run('test_main()')
2953n/a r = tracer.results()
2954n/a print('Writing coverage results...')
2955n/a r.write_results(show_missing=True, summary=True,
2956n/a coverdir=coverdir)
2957n/a
2958n/aif __name__ == '__main__':
2959n/a if '-c' in sys.argv:
2960n/a test_coverage('/tmp/doctest.cover')
2961n/a else:
2962n/a test_main()