2
Test script for doctest.
5
from test import test_support
9
######################################################################
10
## Sample Objects (used by test cases)
11
######################################################################
17
>>> print sample_func(22)
29
>>> # comments get ignored. so are empty PS1 and PS2 prompts:
34
>>> sc = SampleClass(3)
35
>>> for i in range(10):
38
6 12 24 48 96 192 384 768 1536 3072
40
def __init__(self, val):
42
>>> print SampleClass(12).get()
49
>>> print SampleClass(12).double().get()
52
return SampleClass(self.val + self.val)
56
>>> print SampleClass(-5).get()
61
def a_staticmethod(v):
63
>>> print SampleClass.a_staticmethod(10)
67
a_staticmethod = staticmethod(a_staticmethod)
69
def a_classmethod(cls, v):
71
>>> print SampleClass.a_classmethod(10)
73
>>> print SampleClass(0).a_classmethod(10)
77
a_classmethod = classmethod(a_classmethod)
79
a_property = property(get, doc="""
80
>>> print SampleClass(22).a_property
86
>>> x = SampleClass.NestedClass(5)
91
def __init__(self, val=0):
93
>>> print SampleClass.NestedClass().get()
98
return SampleClass.NestedClass(self.val*self.val)
102
class SampleNewStyleClass(object):
109
def __init__(self, val):
111
>>> print SampleNewStyleClass(12).get()
118
>>> print SampleNewStyleClass(12).double().get()
121
return SampleNewStyleClass(self.val + self.val)
125
>>> print SampleNewStyleClass(-5).get()
130
######################################################################
131
## Fake stdin (for testing interactive debugging)
132
######################################################################
136
A fake input stream for pdb's interactive debugger. Whenever a
137
line is read, print it (to simulate the user typing it), and then
138
return it. The set of lines to return is specified in the
139
constructor; they should not have trailing newlines.
141
def __init__(self, lines):
145
line = self.lines.pop(0)
149
######################################################################
151
######################################################################
153
def test_Example(): r"""
154
Unit tests for the `Example` class.
156
Example is a simple container class that holds:
157
- `source`: A source string.
158
- `want`: An expected output string.
159
- `exc_msg`: An expected exception message string (or None if no
160
exception is expected).
161
- `lineno`: A line number (within the docstring).
162
- `indent`: The example's indentation in the input string.
163
- `options`: An option dictionary, mapping option flags to True or
166
These attributes are set by the constructor. `source` and `want` are
167
required; the other attributes all have default values:
169
>>> example = doctest.Example('print 1', '1\n')
170
>>> (example.source, example.want, example.exc_msg,
171
... example.lineno, example.indent, example.options)
172
('print 1\n', '1\n', None, 0, 0, {})
174
The first three attributes (`source`, `want`, and `exc_msg`) may be
175
specified positionally; the remaining arguments should be specified as
178
>>> exc_msg = 'IndexError: pop from an empty list'
179
>>> example = doctest.Example('[].pop()', '', exc_msg,
180
... lineno=5, indent=4,
181
... options={doctest.ELLIPSIS: True})
182
>>> (example.source, example.want, example.exc_msg,
183
... example.lineno, example.indent, example.options)
184
('[].pop()\n', '', 'IndexError: pop from an empty list\n', 5, 4, {8: True})
186
The constructor normalizes the `source` string to end in a newline:
188
Source spans a single line: no terminating newline.
189
>>> e = doctest.Example('print 1', '1\n')
193
>>> e = doctest.Example('print 1\n', '1\n')
197
Source spans multiple lines: require terminating newline.
198
>>> e = doctest.Example('print 1;\nprint 2\n', '1\n2\n')
200
('print 1;\nprint 2\n', '1\n2\n')
202
>>> e = doctest.Example('print 1;\nprint 2', '1\n2\n')
204
('print 1;\nprint 2\n', '1\n2\n')
206
Empty source string (which should never appear in real examples)
207
>>> e = doctest.Example('', '')
211
The constructor normalizes the `want` string to end in a newline,
212
unless it's the empty string:
214
>>> e = doctest.Example('print 1', '1\n')
218
>>> e = doctest.Example('print 1', '1')
222
>>> e = doctest.Example('print', '')
226
The constructor normalizes the `exc_msg` string to end in a newline,
229
Message spans one line
230
>>> exc_msg = 'IndexError: pop from an empty list'
231
>>> e = doctest.Example('[].pop()', '', exc_msg)
233
'IndexError: pop from an empty list\n'
235
>>> exc_msg = 'IndexError: pop from an empty list\n'
236
>>> e = doctest.Example('[].pop()', '', exc_msg)
238
'IndexError: pop from an empty list\n'
240
Message spans multiple lines
241
>>> exc_msg = 'ValueError: 1\n 2'
242
>>> e = doctest.Example('raise ValueError("1\n 2")', '', exc_msg)
244
'ValueError: 1\n 2\n'
246
>>> exc_msg = 'ValueError: 1\n 2\n'
247
>>> e = doctest.Example('raise ValueError("1\n 2")', '', exc_msg)
249
'ValueError: 1\n 2\n'
251
Empty (but non-None) exception message (which should never appear
254
>>> e = doctest.Example('raise X()', '', exc_msg)
259
def test_DocTest(): r"""
260
Unit tests for the `DocTest` class.
262
DocTest is a collection of examples, extracted from a docstring, along
263
with information about where the docstring comes from (a name,
264
filename, and line number). The docstring is parsed by the `DocTest`
271
... Non-example text.
273
... >>> print 'another\example'
277
>>> globs = {} # globals to run the test in.
278
>>> parser = doctest.DocTestParser()
279
>>> test = parser.get_doctest(docstring, globs, 'some_test',
282
<DocTest some_test from some_file:20 (2 examples)>
283
>>> len(test.examples)
285
>>> e1, e2 = test.examples
286
>>> (e1.source, e1.want, e1.lineno)
287
('print 12\n', '12\n', 1)
288
>>> (e2.source, e2.want, e2.lineno)
289
("print 'another\\example'\n", 'another\nexample\n', 6)
291
Source information (name, filename, and line number) is available as
292
attributes on the doctest object:
294
>>> (test.name, test.filename, test.lineno)
295
('some_test', 'some_file', 20)
297
The line number of an example within its containing file is found by
298
adding the line number of the example and the line number of its
301
>>> test.lineno + e1.lineno
303
>>> test.lineno + e2.lineno
306
If the docstring contains inconsistant leading whitespace in the
307
expected output of an example, then `DocTest` will raise a ValueError:
310
... >>> print 'bad\nindentation'
314
>>> parser.get_doctest(docstring, globs, 'some_test', 'filename', 0)
315
Traceback (most recent call last):
316
ValueError: line 4 of the docstring for some_test has inconsistent leading whitespace: 'indentation'
318
If the docstring contains inconsistent leading whitespace on
319
continuation lines, then `DocTest` will raise a ValueError:
322
... >>> print ('bad indentation',
324
... ('bad', 'indentation')
326
>>> parser.get_doctest(docstring, globs, 'some_test', 'filename', 0)
327
Traceback (most recent call last):
328
ValueError: line 2 of the docstring for some_test has inconsistent leading whitespace: '... 2)'
330
If there's no blank space after a PS1 prompt ('>>>'), then `DocTest`
331
will raise a ValueError:
333
>>> docstring = '>>>print 1\n1'
334
>>> parser.get_doctest(docstring, globs, 'some_test', 'filename', 0)
335
Traceback (most recent call last):
336
ValueError: line 1 of the docstring for some_test lacks blank after >>>: '>>>print 1'
338
If there's no blank space after a PS2 prompt ('...'), then `DocTest`
339
will raise a ValueError:
341
>>> docstring = '>>> if 1:\n...print 1\n1'
342
>>> parser.get_doctest(docstring, globs, 'some_test', 'filename', 0)
343
Traceback (most recent call last):
344
ValueError: line 2 of the docstring for some_test lacks blank after ...: '...print 1'
348
def test_DocTestFinder(): r"""
349
Unit tests for the `DocTestFinder` class.
351
DocTestFinder is used to extract DocTests from an object's docstring
352
and the docstrings of its contained objects. It can be used with
353
modules, functions, classes, methods, staticmethods, classmethods, and
356
Finding Tests in Functions
357
~~~~~~~~~~~~~~~~~~~~~~~~~~
358
For a function whose docstring contains examples, DocTestFinder.find()
359
will return a single test (for that function's docstring):
361
>>> finder = doctest.DocTestFinder()
363
We'll simulate a __file__ attr that ends in pyc:
365
>>> import test.test_doctest
366
>>> old = test.test_doctest.__file__
367
>>> test.test_doctest.__file__ = 'test_doctest.pyc'
369
>>> tests = finder.find(sample_func)
371
>>> print tests # doctest: +ELLIPSIS
372
[<DocTest sample_func from ...:13 (1 example)>]
374
The exact name depends on how test_doctest was invoked, so allow for
375
leading path components.
377
>>> tests[0].filename # doctest: +ELLIPSIS
380
>>> test.test_doctest.__file__ = old
383
>>> e = tests[0].examples[0]
384
>>> (e.source, e.want, e.lineno)
385
('print sample_func(22)\n', '44\n', 3)
387
By default, tests are created for objects with no docstring:
389
>>> def no_docstring(v):
391
>>> finder.find(no_docstring)
394
However, the optional argument `exclude_empty` to the DocTestFinder
395
constructor can be used to exclude tests for objects with empty
398
>>> def no_docstring(v):
400
>>> excl_empty_finder = doctest.DocTestFinder(exclude_empty=True)
401
>>> excl_empty_finder.find(no_docstring)
404
If the function has a docstring with no examples, then a test with no
405
examples is returned. (This lets `DocTestRunner` collect statistics
406
about which functions have no tests -- but is that useful? And should
407
an empty test also be created when there's no docstring?)
409
>>> def no_examples(v):
410
... ''' no doctest examples '''
411
>>> finder.find(no_examples) # doctest: +ELLIPSIS
412
[<DocTest no_examples from ...:1 (no examples)>]
414
Finding Tests in Classes
415
~~~~~~~~~~~~~~~~~~~~~~~~
416
For a class, DocTestFinder will create a test for the class's
417
docstring, and will recursively explore its contents, including
418
methods, classmethods, staticmethods, properties, and nested classes.
420
>>> finder = doctest.DocTestFinder()
421
>>> tests = finder.find(SampleClass)
423
... print '%2s %s' % (len(t.examples), t.name)
425
3 SampleClass.NestedClass
426
1 SampleClass.NestedClass.__init__
427
1 SampleClass.__init__
428
2 SampleClass.a_classmethod
429
1 SampleClass.a_property
430
1 SampleClass.a_staticmethod
434
New-style classes are also supported:
436
>>> tests = finder.find(SampleNewStyleClass)
438
... print '%2s %s' % (len(t.examples), t.name)
439
1 SampleNewStyleClass
440
1 SampleNewStyleClass.__init__
441
1 SampleNewStyleClass.double
442
1 SampleNewStyleClass.get
444
Finding Tests in Modules
445
~~~~~~~~~~~~~~~~~~~~~~~~
446
For a module, DocTestFinder will create a test for the class's
447
docstring, and will recursively explore its contents, including
448
functions, classes, and the `__test__` dictionary, if it exists:
452
>>> m = types.ModuleType('some_module')
455
... >>> print triple(11)
459
>>> m.__dict__.update({
460
... 'sample_func': sample_func,
461
... 'SampleClass': SampleClass,
463
... Module docstring.
464
... >>> print 'module'
468
... 'd': '>>> print 6\n6\n>>> print 7\n7\n',
471
>>> finder = doctest.DocTestFinder()
472
>>> # Use module=test.test_doctest, to prevent doctest from
473
>>> # ignoring the objects since they weren't defined in m.
474
>>> import test.test_doctest
475
>>> tests = finder.find(m, module=test.test_doctest)
477
... print '%2s %s' % (len(t.examples), t.name)
479
3 some_module.SampleClass
480
3 some_module.SampleClass.NestedClass
481
1 some_module.SampleClass.NestedClass.__init__
482
1 some_module.SampleClass.__init__
483
2 some_module.SampleClass.a_classmethod
484
1 some_module.SampleClass.a_property
485
1 some_module.SampleClass.a_staticmethod
486
1 some_module.SampleClass.double
487
1 some_module.SampleClass.get
488
1 some_module.__test__.c
489
2 some_module.__test__.d
490
1 some_module.sample_func
494
If a single object is listed twice (under different names), then tests
495
will only be generated for it once:
497
>>> from test import doctest_aliases
498
>>> tests = excl_empty_finder.find(doctest_aliases)
501
>>> print tests[0].name
502
test.doctest_aliases.TwoNames
504
TwoNames.f and TwoNames.g are bound to the same object.
505
We can't guess which will be found in doctest's traversal of
506
TwoNames.__dict__ first, so we have to allow for either.
508
>>> tests[1].name.split('.')[-1] in ['f', 'g']
513
By default, an object with no doctests doesn't create any tests:
515
>>> tests = doctest.DocTestFinder().find(SampleClass)
517
... print '%2s %s' % (len(t.examples), t.name)
519
3 SampleClass.NestedClass
520
1 SampleClass.NestedClass.__init__
521
1 SampleClass.__init__
522
2 SampleClass.a_classmethod
523
1 SampleClass.a_property
524
1 SampleClass.a_staticmethod
528
By default, that excluded objects with no doctests. exclude_empty=False
529
tells it to include (empty) tests for objects with no doctests. This feature
530
is really to support backward compatibility in what doctest.master.summarize()
533
>>> tests = doctest.DocTestFinder(exclude_empty=False).find(SampleClass)
535
... print '%2s %s' % (len(t.examples), t.name)
537
3 SampleClass.NestedClass
538
1 SampleClass.NestedClass.__init__
539
0 SampleClass.NestedClass.get
540
0 SampleClass.NestedClass.square
541
1 SampleClass.__init__
542
2 SampleClass.a_classmethod
543
1 SampleClass.a_property
544
1 SampleClass.a_staticmethod
548
Turning off Recursion
549
~~~~~~~~~~~~~~~~~~~~~
550
DocTestFinder can be told not to look for tests in contained objects
551
using the `recurse` flag:
553
>>> tests = doctest.DocTestFinder(recurse=False).find(SampleClass)
555
... print '%2s %s' % (len(t.examples), t.name)
560
DocTestFinder finds the line number of each example:
568
... >>> # examples are not created for comments & bare prompts.
572
... >>> for x in range(10):
574
... 0 1 2 3 4 5 6 7 8 9
578
>>> test = doctest.DocTestFinder().find(f)[0]
579
>>> [e.lineno for e in test.examples]
583
def test_DocTestParser(): r"""
584
Unit tests for the `DocTestParser` class.
586
DocTestParser is used to parse docstrings containing doctest examples.
588
The `parse` method divides a docstring into examples and intervening
592
... >>> x, y = 2, 3 # no output expected
603
>>> parser = doctest.DocTestParser()
604
>>> for piece in parser.parse(s):
605
... if isinstance(piece, doctest.Example):
606
... print 'Example:', (piece.source, piece.want, piece.lineno)
608
... print ' Text:', `piece`
610
Example: ('x, y = 2, 3 # no output expected\n', '', 1)
612
Example: ('if 1:\n print x\n print y\n', '2\n3\n', 2)
613
Text: '\nSome text.\n'
614
Example: ('x+y\n', '5\n', 9)
617
The `get_examples` method returns just the examples:
619
>>> for piece in parser.get_examples(s):
620
... print (piece.source, piece.want, piece.lineno)
621
('x, y = 2, 3 # no output expected\n', '', 1)
622
('if 1:\n print x\n print y\n', '2\n3\n', 2)
625
The `get_doctest` method creates a Test from the examples, along with the
628
>>> test = parser.get_doctest(s, {}, 'name', 'filename', lineno=5)
629
>>> (test.name, test.filename, test.lineno)
630
('name', 'filename', 5)
631
>>> for piece in test.examples:
632
... print (piece.source, piece.want, piece.lineno)
633
('x, y = 2, 3 # no output expected\n', '', 1)
634
('if 1:\n print x\n print y\n', '2\n3\n', 2)
638
class test_DocTestRunner:
640
Unit tests for the `DocTestRunner` class.
642
DocTestRunner is used to run DocTest test cases, and to accumulate
643
statistics. Here's a simple DocTest case we can use:
653
>>> test = doctest.DocTestFinder().find(f)[0]
655
The main DocTestRunner interface is the `run` method, which runs a
656
given DocTest case in a given namespace (globs). It returns a tuple
657
`(f,t)`, where `f` is the number of failed tests and `t` is the number
660
>>> doctest.DocTestRunner(verbose=False).run(test)
661
TestResults(failed=0, attempted=3)
663
If any example produces incorrect output, then the test runner reports
664
the failure and proceeds to the next example:
674
>>> test = doctest.DocTestFinder().find(f)[0]
675
>>> doctest.DocTestRunner(verbose=True).run(test)
676
... # doctest: +ELLIPSIS
685
**********************************************************************
686
File ..., line 4, in f
698
TestResults(failed=1, attempted=3)
700
def verbose_flag(): r"""
701
The `verbose` flag makes the test runner generate more detailed
712
>>> test = doctest.DocTestFinder().find(f)[0]
714
>>> doctest.DocTestRunner(verbose=True).run(test)
729
TestResults(failed=0, attempted=3)
731
If the `verbose` flag is unspecified, then the output will be verbose
732
iff `-v` appears in sys.argv:
734
>>> # Save the real sys.argv list.
735
>>> old_argv = sys.argv
737
>>> # If -v does not appear in sys.argv, then output isn't verbose.
738
>>> sys.argv = ['test']
739
>>> doctest.DocTestRunner().run(test)
740
TestResults(failed=0, attempted=3)
742
>>> # If -v does appear in sys.argv, then output is verbose.
743
>>> sys.argv = ['test', '-v']
744
>>> doctest.DocTestRunner().run(test)
759
TestResults(failed=0, attempted=3)
761
>>> # Restore sys.argv
762
>>> sys.argv = old_argv
764
In the remaining examples, the test runner's verbosity will be
765
explicitly set, to ensure that the test behavior is consistent.
767
def exceptions(): r"""
768
Tests of `DocTestRunner`'s exception handling.
770
An expected exception is specified with a traceback message. The
771
lines between the first line and the type/value may be omitted or
772
replaced with any other string:
778
... Traceback (most recent call last):
779
... ZeroDivisionError: integer division or modulo by zero
781
>>> test = doctest.DocTestFinder().find(f)[0]
782
>>> doctest.DocTestRunner(verbose=False).run(test)
783
TestResults(failed=0, attempted=2)
785
An example may not generate output before it raises an exception; if
786
it does, then the traceback message will not be recognized as
787
signaling an expected exception, so the example will be reported as an
788
unexpected exception:
793
... >>> print 'pre-exception output', x//0
794
... pre-exception output
795
... Traceback (most recent call last):
796
... ZeroDivisionError: integer division or modulo by zero
798
>>> test = doctest.DocTestFinder().find(f)[0]
799
>>> doctest.DocTestRunner(verbose=False).run(test)
800
... # doctest: +ELLIPSIS
801
**********************************************************************
802
File ..., line 4, in f
804
print 'pre-exception output', x//0
807
ZeroDivisionError: integer division or modulo by zero
808
TestResults(failed=1, attempted=2)
810
Exception messages may contain newlines:
814
... >>> raise ValueError, 'multi\nline\nmessage'
815
... Traceback (most recent call last):
816
... ValueError: multi
820
>>> test = doctest.DocTestFinder().find(f)[0]
821
>>> doctest.DocTestRunner(verbose=False).run(test)
822
TestResults(failed=0, attempted=1)
824
If an exception is expected, but an exception with the wrong type or
825
message is raised, then it is reported as a failure:
829
... >>> raise ValueError, 'message'
830
... Traceback (most recent call last):
831
... ValueError: wrong message
833
>>> test = doctest.DocTestFinder().find(f)[0]
834
>>> doctest.DocTestRunner(verbose=False).run(test)
835
... # doctest: +ELLIPSIS
836
**********************************************************************
837
File ..., line 3, in f
839
raise ValueError, 'message'
841
Traceback (most recent call last):
842
ValueError: wrong message
844
Traceback (most recent call last):
847
TestResults(failed=1, attempted=1)
849
However, IGNORE_EXCEPTION_DETAIL can be used to allow a mismatch in the
854
... >>> raise ValueError, 'message' #doctest: +IGNORE_EXCEPTION_DETAIL
855
... Traceback (most recent call last):
856
... ValueError: wrong message
858
>>> test = doctest.DocTestFinder().find(f)[0]
859
>>> doctest.DocTestRunner(verbose=False).run(test)
860
TestResults(failed=0, attempted=1)
862
But IGNORE_EXCEPTION_DETAIL does not allow a mismatch in the exception type:
866
... >>> raise ValueError, 'message' #doctest: +IGNORE_EXCEPTION_DETAIL
867
... Traceback (most recent call last):
868
... TypeError: wrong type
870
>>> test = doctest.DocTestFinder().find(f)[0]
871
>>> doctest.DocTestRunner(verbose=False).run(test)
872
... # doctest: +ELLIPSIS
873
**********************************************************************
874
File ..., line 3, in f
876
raise ValueError, 'message' #doctest: +IGNORE_EXCEPTION_DETAIL
878
Traceback (most recent call last):
879
TypeError: wrong type
881
Traceback (most recent call last):
884
TestResults(failed=1, attempted=1)
886
If an exception is raised but not expected, then it is reported as an
887
unexpected exception:
894
>>> test = doctest.DocTestFinder().find(f)[0]
895
>>> doctest.DocTestRunner(verbose=False).run(test)
896
... # doctest: +ELLIPSIS
897
**********************************************************************
898
File ..., line 3, in f
902
Traceback (most recent call last):
904
ZeroDivisionError: integer division or modulo by zero
905
TestResults(failed=1, attempted=1)
907
def optionflags(): r"""
908
Tests of `DocTestRunner`'s option flag handling.
910
Several option flags can be used to customize the behavior of the test
911
runner. These are defined as module constants in doctest, and passed
912
to the DocTestRunner constructor (multiple constants should be ORed
915
The DONT_ACCEPT_TRUE_FOR_1 flag disables matches between True/False
921
>>> # Without the flag:
922
>>> test = doctest.DocTestFinder().find(f)[0]
923
>>> doctest.DocTestRunner(verbose=False).run(test)
924
TestResults(failed=0, attempted=1)
927
>>> test = doctest.DocTestFinder().find(f)[0]
928
>>> flags = doctest.DONT_ACCEPT_TRUE_FOR_1
929
>>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
930
... # doctest: +ELLIPSIS
931
**********************************************************************
932
File ..., line 2, in f
939
TestResults(failed=1, attempted=1)
941
The DONT_ACCEPT_BLANKLINE flag disables the match between blank lines
942
and the '<BLANKLINE>' marker:
945
... '>>> print "a\\n\\nb"\na\n<BLANKLINE>\nb\n'
947
>>> # Without the flag:
948
>>> test = doctest.DocTestFinder().find(f)[0]
949
>>> doctest.DocTestRunner(verbose=False).run(test)
950
TestResults(failed=0, attempted=1)
953
>>> test = doctest.DocTestFinder().find(f)[0]
954
>>> flags = doctest.DONT_ACCEPT_BLANKLINE
955
>>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
956
... # doctest: +ELLIPSIS
957
**********************************************************************
958
File ..., line 2, in f
969
TestResults(failed=1, attempted=1)
971
The NORMALIZE_WHITESPACE flag causes all sequences of whitespace to be
975
... '>>> print 1, 2, 3\n 1 2\n 3'
977
>>> # Without the flag:
978
>>> test = doctest.DocTestFinder().find(f)[0]
979
>>> doctest.DocTestRunner(verbose=False).run(test)
980
... # doctest: +ELLIPSIS
981
**********************************************************************
982
File ..., line 2, in f
990
TestResults(failed=1, attempted=1)
993
>>> test = doctest.DocTestFinder().find(f)[0]
994
>>> flags = doctest.NORMALIZE_WHITESPACE
995
>>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
996
TestResults(failed=0, attempted=1)
998
An example from the docs:
999
>>> print range(20) #doctest: +NORMALIZE_WHITESPACE
1000
[0, 1, 2, 3, 4, 5, 6, 7, 8, 9,
1001
10, 11, 12, 13, 14, 15, 16, 17, 18, 19]
1003
The ELLIPSIS flag causes ellipsis marker ("...") in the expected
1004
output to match any substring in the actual output:
1007
... '>>> print range(15)\n[0, 1, 2, ..., 14]\n'
1009
>>> # Without the flag:
1010
>>> test = doctest.DocTestFinder().find(f)[0]
1011
>>> doctest.DocTestRunner(verbose=False).run(test)
1012
... # doctest: +ELLIPSIS
1013
**********************************************************************
1014
File ..., line 2, in f
1020
[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14]
1021
TestResults(failed=1, attempted=1)
1023
>>> # With the flag:
1024
>>> test = doctest.DocTestFinder().find(f)[0]
1025
>>> flags = doctest.ELLIPSIS
1026
>>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
1027
TestResults(failed=0, attempted=1)
1029
... also matches nothing:
1031
>>> for i in range(100):
1032
... print i**2, #doctest: +ELLIPSIS
1033
0 1...4...9 16 ... 36 49 64 ... 9801
1035
... can be surprising; e.g., this test passes:
1037
>>> for i in range(21): #doctest: +ELLIPSIS
1041
Examples from the docs:
1043
>>> print range(20) # doctest:+ELLIPSIS
1046
>>> print range(20) # doctest: +ELLIPSIS
1047
... # doctest: +NORMALIZE_WHITESPACE
1050
The SKIP flag causes an example to be skipped entirely. I.e., the
1051
example is not run. It can be useful in contexts where doctest
1052
examples serve as both documentation and test cases, and an example
1053
should be included for documentation purposes, but should not be
1054
checked (e.g., because its output is random, or depends on resources
1055
which would be unavailable.) The SKIP flag can also be used for
1056
'commenting out' broken examples.
1058
>>> import unavailable_resource # doctest: +SKIP
1059
>>> unavailable_resource.do_something() # doctest: +SKIP
1060
>>> unavailable_resource.blow_up() # doctest: +SKIP
1061
Traceback (most recent call last):
1063
UncheckedBlowUpError: Nobody checks me.
1066
>>> print random.random() # doctest: +SKIP
1069
The REPORT_UDIFF flag causes failures that involve multi-line expected
1070
and actual outputs to be displayed using a unified diff:
1074
... >>> print '\n'.join('abcdefg')
1084
>>> # Without the flag:
1085
>>> test = doctest.DocTestFinder().find(f)[0]
1086
>>> doctest.DocTestRunner(verbose=False).run(test)
1087
... # doctest: +ELLIPSIS
1088
**********************************************************************
1089
File ..., line 3, in f
1091
print '\n'.join('abcdefg')
1108
TestResults(failed=1, attempted=1)
1110
>>> # With the flag:
1111
>>> test = doctest.DocTestFinder().find(f)[0]
1112
>>> flags = doctest.REPORT_UDIFF
1113
>>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
1114
... # doctest: +ELLIPSIS
1115
**********************************************************************
1116
File ..., line 3, in f
1118
print '\n'.join('abcdefg')
1119
Differences (unified diff with -expected +actual):
1130
TestResults(failed=1, attempted=1)
1132
The REPORT_CDIFF flag causes failures that involve multi-line expected
1133
and actual outputs to be displayed using a context diff:
1135
>>> # Reuse f() from the REPORT_UDIFF example, above.
1136
>>> test = doctest.DocTestFinder().find(f)[0]
1137
>>> flags = doctest.REPORT_CDIFF
1138
>>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
1139
... # doctest: +ELLIPSIS
1140
**********************************************************************
1141
File ..., line 3, in f
1143
print '\n'.join('abcdefg')
1144
Differences (context diff with expected followed by actual):
1162
TestResults(failed=1, attempted=1)
1165
The REPORT_NDIFF flag causes failures to use the difflib.Differ algorithm
1166
used by the popular ndiff.py utility. This does intraline difference
1167
marking, as well as interline differences.
1171
... >>> print "a b c d e f g h i j k l m"
1172
... a b c d e f g h i j k 1 m
1174
>>> test = doctest.DocTestFinder().find(f)[0]
1175
>>> flags = doctest.REPORT_NDIFF
1176
>>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
1177
... # doctest: +ELLIPSIS
1178
**********************************************************************
1179
File ..., line 3, in f
1181
print "a b c d e f g h i j k l m"
1182
Differences (ndiff with -expected +actual):
1183
- a b c d e f g h i j k 1 m
1185
+ a b c d e f g h i j k l m
1187
TestResults(failed=1, attempted=1)
1189
The REPORT_ONLY_FIRST_FAILURE supresses result output after the first
1194
... >>> print 1 # first success
1196
... >>> print 2 # first failure
1198
... >>> print 3 # second failure
1200
... >>> print 4 # second success
1202
... >>> print 5 # third failure
1205
>>> test = doctest.DocTestFinder().find(f)[0]
1206
>>> flags = doctest.REPORT_ONLY_FIRST_FAILURE
1207
>>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
1208
... # doctest: +ELLIPSIS
1209
**********************************************************************
1210
File ..., line 5, in f
1212
print 2 # first failure
1217
TestResults(failed=3, attempted=5)
1219
However, output from `report_start` is not supressed:
1221
>>> doctest.DocTestRunner(verbose=True, optionflags=flags).run(test)
1222
... # doctest: +ELLIPSIS
1224
print 1 # first success
1229
print 2 # first failure
1232
**********************************************************************
1233
File ..., line 5, in f
1235
print 2 # first failure
1240
TestResults(failed=3, attempted=5)
1242
For the purposes of REPORT_ONLY_FIRST_FAILURE, unexpected exceptions
1247
... >>> print 1 # first success
1249
... >>> raise ValueError(2) # first failure
1251
... >>> print 3 # second failure
1253
... >>> print 4 # second success
1255
... >>> print 5 # third failure
1258
>>> test = doctest.DocTestFinder().find(f)[0]
1259
>>> flags = doctest.REPORT_ONLY_FIRST_FAILURE
1260
>>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
1261
... # doctest: +ELLIPSIS
1262
**********************************************************************
1263
File ..., line 5, in f
1265
raise ValueError(2) # first failure
1269
TestResults(failed=3, attempted=5)
1271
New option flags can also be registered, via register_optionflag(). Here
1272
we reach into doctest's internals a bit.
1274
>>> unlikely = "UNLIKELY_OPTION_NAME"
1275
>>> unlikely in doctest.OPTIONFLAGS_BY_NAME
1277
>>> new_flag_value = doctest.register_optionflag(unlikely)
1278
>>> unlikely in doctest.OPTIONFLAGS_BY_NAME
1281
Before 2.4.4/2.5, registering a name more than once erroneously created
1282
more than one flag value. Here we verify that's fixed:
1284
>>> redundant_flag_value = doctest.register_optionflag(unlikely)
1285
>>> redundant_flag_value == new_flag_value
1289
>>> del doctest.OPTIONFLAGS_BY_NAME[unlikely]
1293
def option_directives(): r"""
1294
Tests of `DocTestRunner`'s option directive mechanism.
1296
Option directives can be used to turn option flags on or off for a
1297
single example. To turn an option on for an example, follow that
1298
example with a comment of the form ``# doctest: +OPTION``:
1301
... >>> print range(10) # should fail: no ellipsis
1304
... >>> print range(10) # doctest: +ELLIPSIS
1307
>>> test = doctest.DocTestFinder().find(f)[0]
1308
>>> doctest.DocTestRunner(verbose=False).run(test)
1309
... # doctest: +ELLIPSIS
1310
**********************************************************************
1311
File ..., line 2, in f
1313
print range(10) # should fail: no ellipsis
1317
[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
1318
TestResults(failed=1, attempted=2)
1320
To turn an option off for an example, follow that example with a
1321
comment of the form ``# doctest: -OPTION``:
1324
... >>> print range(10)
1327
... >>> # should fail: no ellipsis
1328
... >>> print range(10) # doctest: -ELLIPSIS
1331
>>> test = doctest.DocTestFinder().find(f)[0]
1332
>>> doctest.DocTestRunner(verbose=False,
1333
... optionflags=doctest.ELLIPSIS).run(test)
1334
... # doctest: +ELLIPSIS
1335
**********************************************************************
1336
File ..., line 6, in f
1338
print range(10) # doctest: -ELLIPSIS
1342
[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
1343
TestResults(failed=1, attempted=2)
1345
Option directives affect only the example that they appear with; they
1346
do not change the options for surrounding examples:
1349
... >>> print range(10) # Should fail: no ellipsis
1352
... >>> print range(10) # doctest: +ELLIPSIS
1355
... >>> print range(10) # Should fail: no ellipsis
1358
>>> test = doctest.DocTestFinder().find(f)[0]
1359
>>> doctest.DocTestRunner(verbose=False).run(test)
1360
... # doctest: +ELLIPSIS
1361
**********************************************************************
1362
File ..., line 2, in f
1364
print range(10) # Should fail: no ellipsis
1368
[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
1369
**********************************************************************
1370
File ..., line 8, in f
1372
print range(10) # Should fail: no ellipsis
1376
[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
1377
TestResults(failed=2, attempted=3)
1379
Multiple options may be modified by a single option directive. They
1380
may be separated by whitespace, commas, or both:
1383
... >>> print range(10) # Should fail
1385
... >>> print range(10) # Should succeed
1386
... ... # doctest: +ELLIPSIS +NORMALIZE_WHITESPACE
1389
>>> test = doctest.DocTestFinder().find(f)[0]
1390
>>> doctest.DocTestRunner(verbose=False).run(test)
1391
... # doctest: +ELLIPSIS
1392
**********************************************************************
1393
File ..., line 2, in f
1395
print range(10) # Should fail
1399
[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
1400
TestResults(failed=1, attempted=2)
1403
... >>> print range(10) # Should fail
1405
... >>> print range(10) # Should succeed
1406
... ... # doctest: +ELLIPSIS,+NORMALIZE_WHITESPACE
1409
>>> test = doctest.DocTestFinder().find(f)[0]
1410
>>> doctest.DocTestRunner(verbose=False).run(test)
1411
... # doctest: +ELLIPSIS
1412
**********************************************************************
1413
File ..., line 2, in f
1415
print range(10) # Should fail
1419
[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
1420
TestResults(failed=1, attempted=2)
1423
... >>> print range(10) # Should fail
1425
... >>> print range(10) # Should succeed
1426
... ... # doctest: +ELLIPSIS, +NORMALIZE_WHITESPACE
1429
>>> test = doctest.DocTestFinder().find(f)[0]
1430
>>> doctest.DocTestRunner(verbose=False).run(test)
1431
... # doctest: +ELLIPSIS
1432
**********************************************************************
1433
File ..., line 2, in f
1435
print range(10) # Should fail
1439
[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
1440
TestResults(failed=1, attempted=2)
1442
The option directive may be put on the line following the source, as
1443
long as a continuation prompt is used:
1446
... >>> print range(10)
1447
... ... # doctest: +ELLIPSIS
1450
>>> test = doctest.DocTestFinder().find(f)[0]
1451
>>> doctest.DocTestRunner(verbose=False).run(test)
1452
TestResults(failed=0, attempted=1)
1454
For examples with multi-line source, the option directive may appear
1455
at the end of any line:
1458
... >>> for x in range(10): # doctest: +ELLIPSIS
1462
... >>> for x in range(10):
1463
... ... print x, # doctest: +ELLIPSIS
1466
>>> test = doctest.DocTestFinder().find(f)[0]
1467
>>> doctest.DocTestRunner(verbose=False).run(test)
1468
TestResults(failed=0, attempted=2)
1470
If more than one line of an example with multi-line source has an
1471
option directive, then they are combined:
1474
... Should fail (option directive not on the last line):
1475
... >>> for x in range(10): # doctest: +ELLIPSIS
1476
... ... print x, # doctest: +NORMALIZE_WHITESPACE
1479
>>> test = doctest.DocTestFinder().find(f)[0]
1480
>>> doctest.DocTestRunner(verbose=False).run(test)
1481
TestResults(failed=0, attempted=1)
1483
It is an error to have a comment of the form ``# doctest:`` that is
1484
*not* followed by words of the form ``+OPTION`` or ``-OPTION``, where
1485
``OPTION`` is an option that has been registered with
1488
>>> # Error: Option not registered
1489
>>> s = '>>> print 12 #doctest: +BADOPTION'
1490
>>> test = doctest.DocTestParser().get_doctest(s, {}, 's', 's.py', 0)
1491
Traceback (most recent call last):
1492
ValueError: line 1 of the doctest for s has an invalid option: '+BADOPTION'
1494
>>> # Error: No + or - prefix
1495
>>> s = '>>> print 12 #doctest: ELLIPSIS'
1496
>>> test = doctest.DocTestParser().get_doctest(s, {}, 's', 's.py', 0)
1497
Traceback (most recent call last):
1498
ValueError: line 1 of the doctest for s has an invalid option: 'ELLIPSIS'
1500
It is an error to use an option directive on a line that contains no
1503
>>> s = '>>> # doctest: +ELLIPSIS'
1504
>>> test = doctest.DocTestParser().get_doctest(s, {}, 's', 's.py', 0)
1505
Traceback (most recent call last):
1506
ValueError: line 0 of the doctest for s has an option directive on a line with no example: '# doctest: +ELLIPSIS'
1509
def test_testsource(): r"""
1510
Unit tests for `testsource()`.
1512
The testsource() function takes a module and a name, finds the (first)
1513
test with that name in that module, and converts it to a script. The
1514
example code is converted to regular Python code. The surrounding
1515
words and expected output are converted to comments:
1517
>>> import test.test_doctest
1518
>>> name = 'test.test_doctest.sample_func'
1519
>>> print doctest.testsource(test.test_doctest, name)
1522
print sample_func(22)
1529
>>> name = 'test.test_doctest.SampleNewStyleClass'
1530
>>> print doctest.testsource(test.test_doctest, name)
1538
>>> name = 'test.test_doctest.SampleClass.a_classmethod'
1539
>>> print doctest.testsource(test.test_doctest, name)
1540
print SampleClass.a_classmethod(10)
1543
print SampleClass(0).a_classmethod(10)
1549
def test_debug(): r"""
1551
Create a docstring that we want to debug:
1559
Create some fake stdin input, to feed to the debugger:
1562
>>> real_stdin = sys.stdin
1563
>>> sys.stdin = _FakeInput(['next', 'print x', 'continue'])
1565
Run the debugger on the docstring, and then restore sys.stdin.
1567
>>> try: doctest.debug_src(s)
1568
... finally: sys.stdin = real_stdin
1569
> <string>(1)<module>()
1573
> <string>(1)<module>()->None
1580
def test_pdb_set_trace():
1581
"""Using pdb.set_trace from a doctest.
1583
You can use pdb.set_trace from a doctest. To do so, you must
1584
retrieve the set_trace function from the pdb module at the time
1585
you use it. The doctest module changes sys.stdout so that it can
1586
capture program output. It also temporarily replaces pdb.set_trace
1587
with a version that restores stdout. This is necessary for you to
1588
see debugger output.
1592
... >>> import pdb; pdb.set_trace()
1594
>>> parser = doctest.DocTestParser()
1595
>>> test = parser.get_doctest(doc, {}, "foo", "foo.py", 0)
1596
>>> runner = doctest.DocTestRunner(verbose=False)
1598
To demonstrate this, we'll create a fake standard input that
1599
captures our debugger input:
1602
>>> real_stdin = sys.stdin
1603
>>> sys.stdin = _FakeInput([
1604
... 'print x', # print data defined by the example
1605
... 'continue', # stop debugging
1608
>>> try: runner.run(test)
1609
... finally: sys.stdin = real_stdin
1611
> <doctest foo[1]>(1)<module>()->None
1612
-> import pdb; pdb.set_trace()
1616
TestResults(failed=0, attempted=2)
1618
You can also put pdb.set_trace in a function called from a test:
1620
>>> def calls_set_trace():
1622
... import pdb; pdb.set_trace()
1626
... >>> calls_set_trace()
1628
>>> test = parser.get_doctest(doc, globals(), "foo", "foo.py", 0)
1629
>>> real_stdin = sys.stdin
1630
>>> sys.stdin = _FakeInput([
1631
... 'print y', # print data defined in the function
1632
... 'up', # out of function
1633
... 'print x', # print data defined by the example
1634
... 'continue', # stop debugging
1638
... runner.run(test)
1640
... sys.stdin = real_stdin
1642
> <doctest test.test_doctest.test_pdb_set_trace[8]>(3)calls_set_trace()->None
1643
-> import pdb; pdb.set_trace()
1647
> <doctest foo[1]>(1)<module>()
1648
-> calls_set_trace()
1652
TestResults(failed=0, attempted=2)
1654
During interactive debugging, source code is shown, even for
1662
... ... import pdb; pdb.set_trace()
1665
>>> test = parser.get_doctest(doc, globals(), "foo", "foo.py", 0)
1666
>>> real_stdin = sys.stdin
1667
>>> sys.stdin = _FakeInput([
1668
... 'list', # list source from example 2
1669
... 'next', # return from g()
1670
... 'list', # list source from example 1
1671
... 'next', # return from f()
1672
... 'list', # list source from example 3
1673
... 'continue', # stop debugging
1675
>>> try: runner.run(test)
1676
... finally: sys.stdin = real_stdin
1677
... # doctest: +NORMALIZE_WHITESPACE
1679
> <doctest foo[1]>(3)g()->None
1680
-> import pdb; pdb.set_trace()
1684
3 -> import pdb; pdb.set_trace()
1688
> <doctest foo[0]>(2)f()->None
1696
> <doctest foo[2]>(1)<module>()->None
1702
**********************************************************************
1703
File "foo.py", line 7, in foo
1709
TestResults(failed=1, attempted=3)
1712
def test_pdb_set_trace_nested():
1713
"""This illustrates more-demanding use of set_trace with nested functions.
1715
>>> class C(object):
1716
... def calls_set_trace(self):
1718
... import pdb; pdb.set_trace()
1729
>>> calls_set_trace = C().calls_set_trace
1733
... >>> calls_set_trace()
1735
>>> parser = doctest.DocTestParser()
1736
>>> runner = doctest.DocTestRunner(verbose=False)
1737
>>> test = parser.get_doctest(doc, globals(), "foo", "foo.py", 0)
1738
>>> real_stdin = sys.stdin
1739
>>> sys.stdin = _FakeInput([
1740
... 'print y', # print data defined in the function
1741
... 'step', 'step', 'step', 'step', 'step', 'step', 'print z',
1742
... 'up', 'print x',
1743
... 'up', 'print y',
1744
... 'up', 'print foo',
1745
... 'continue', # stop debugging
1749
... runner.run(test)
1751
... sys.stdin = real_stdin
1752
> <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(5)calls_set_trace()
1758
> <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(7)f1()
1761
> <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(8)f1()
1764
> <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(9)f1()
1768
> <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(11)f2()
1771
> <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(12)f2()
1774
> <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(13)f2()
1779
> <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(9)f1()
1784
> <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(5)calls_set_trace()
1789
> <doctest foo[1]>(1)<module>()
1790
-> calls_set_trace()
1792
*** NameError: name 'foo' is not defined
1794
TestResults(failed=0, attempted=2)
1797
def test_DocTestSuite():
1798
"""DocTestSuite creates a unittest test suite from a doctest.
1800
We create a Suite by providing a module. A module can be provided
1801
by passing a module object:
1804
>>> import test.sample_doctest
1805
>>> suite = doctest.DocTestSuite(test.sample_doctest)
1806
>>> suite.run(unittest.TestResult())
1807
<unittest.TestResult run=9 errors=0 failures=4>
1809
We can also supply the module by name:
1811
>>> suite = doctest.DocTestSuite('test.sample_doctest')
1812
>>> suite.run(unittest.TestResult())
1813
<unittest.TestResult run=9 errors=0 failures=4>
1815
We can use the current module:
1817
>>> suite = test.sample_doctest.test_suite()
1818
>>> suite.run(unittest.TestResult())
1819
<unittest.TestResult run=9 errors=0 failures=4>
1821
We can supply global variables. If we pass globs, they will be
1822
used instead of the module globals. Here we'll pass an empty
1823
globals, triggering an extra error:
1825
>>> suite = doctest.DocTestSuite('test.sample_doctest', globs={})
1826
>>> suite.run(unittest.TestResult())
1827
<unittest.TestResult run=9 errors=0 failures=5>
1829
Alternatively, we can provide extra globals. Here we'll make an
1830
error go away by providing an extra global variable:
1832
>>> suite = doctest.DocTestSuite('test.sample_doctest',
1833
... extraglobs={'y': 1})
1834
>>> suite.run(unittest.TestResult())
1835
<unittest.TestResult run=9 errors=0 failures=3>
1837
You can pass option flags. Here we'll cause an extra error
1838
by disabling the blank-line feature:
1840
>>> suite = doctest.DocTestSuite('test.sample_doctest',
1841
... optionflags=doctest.DONT_ACCEPT_BLANKLINE)
1842
>>> suite.run(unittest.TestResult())
1843
<unittest.TestResult run=9 errors=0 failures=5>
1845
You can supply setUp and tearDown functions:
1848
... import test.test_doctest
1849
... test.test_doctest.sillySetup = True
1851
>>> def tearDown(t):
1852
... import test.test_doctest
1853
... del test.test_doctest.sillySetup
1855
Here, we installed a silly variable that the test expects:
1857
>>> suite = doctest.DocTestSuite('test.sample_doctest',
1858
... setUp=setUp, tearDown=tearDown)
1859
>>> suite.run(unittest.TestResult())
1860
<unittest.TestResult run=9 errors=0 failures=3>
1862
But the tearDown restores sanity:
1864
>>> import test.test_doctest
1865
>>> test.test_doctest.sillySetup
1866
Traceback (most recent call last):
1868
AttributeError: 'module' object has no attribute 'sillySetup'
1870
The setUp and tearDown funtions are passed test objects. Here
1871
we'll use the setUp function to supply the missing variable y:
1873
>>> def setUp(test):
1874
... test.globs['y'] = 1
1876
>>> suite = doctest.DocTestSuite('test.sample_doctest', setUp=setUp)
1877
>>> suite.run(unittest.TestResult())
1878
<unittest.TestResult run=9 errors=0 failures=3>
1880
Here, we didn't need to use a tearDown function because we
1881
modified the test globals, which are a copy of the
1882
sample_doctest module dictionary. The test globals are
1883
automatically cleared for us after a test.
1886
def test_DocFileSuite():
1887
"""We can test tests found in text files using a DocFileSuite.
1889
We create a suite by providing the names of one or more text
1890
files that include examples:
1893
>>> suite = doctest.DocFileSuite('test_doctest.txt',
1894
... 'test_doctest2.txt',
1895
... 'test_doctest4.txt')
1896
>>> suite.run(unittest.TestResult())
1897
<unittest.TestResult run=3 errors=0 failures=3>
1899
The test files are looked for in the directory containing the
1900
calling module. A package keyword argument can be provided to
1901
specify a different relative location.
1904
>>> suite = doctest.DocFileSuite('test_doctest.txt',
1905
... 'test_doctest2.txt',
1906
... 'test_doctest4.txt',
1908
>>> suite.run(unittest.TestResult())
1909
<unittest.TestResult run=3 errors=0 failures=3>
1911
Support for using a package's __loader__.get_data() is also
1914
>>> import unittest, pkgutil, test
1915
>>> added_loader = False
1916
>>> if not hasattr(test, '__loader__'):
1917
... test.__loader__ = pkgutil.get_loader(test)
1918
... added_loader = True
1920
... suite = doctest.DocFileSuite('test_doctest.txt',
1921
... 'test_doctest2.txt',
1922
... 'test_doctest4.txt',
1924
... suite.run(unittest.TestResult())
1926
... if added_loader:
1927
... del test.__loader__
1928
<unittest.TestResult run=3 errors=0 failures=3>
1930
'/' should be used as a path separator. It will be converted
1931
to a native separator at run time:
1933
>>> suite = doctest.DocFileSuite('../test/test_doctest.txt')
1934
>>> suite.run(unittest.TestResult())
1935
<unittest.TestResult run=1 errors=0 failures=1>
1937
If DocFileSuite is used from an interactive session, then files
1938
are resolved relative to the directory of sys.argv[0]:
1940
>>> import types, os.path, test.test_doctest
1941
>>> save_argv = sys.argv
1942
>>> sys.argv = [test.test_doctest.__file__]
1943
>>> suite = doctest.DocFileSuite('test_doctest.txt',
1944
... package=types.ModuleType('__main__'))
1945
>>> sys.argv = save_argv
1947
By setting `module_relative=False`, os-specific paths may be
1948
used (including absolute paths and paths relative to the
1951
>>> # Get the absolute path of the test package.
1952
>>> test_doctest_path = os.path.abspath(test.test_doctest.__file__)
1953
>>> test_pkg_path = os.path.split(test_doctest_path)[0]
1955
>>> # Use it to find the absolute path of test_doctest.txt.
1956
>>> test_file = os.path.join(test_pkg_path, 'test_doctest.txt')
1958
>>> suite = doctest.DocFileSuite(test_file, module_relative=False)
1959
>>> suite.run(unittest.TestResult())
1960
<unittest.TestResult run=1 errors=0 failures=1>
1962
It is an error to specify `package` when `module_relative=False`:
1964
>>> suite = doctest.DocFileSuite(test_file, module_relative=False,
1966
Traceback (most recent call last):
1967
ValueError: Package may only be specified for module-relative paths.
1969
You can specify initial global variables:
1971
>>> suite = doctest.DocFileSuite('test_doctest.txt',
1972
... 'test_doctest2.txt',
1973
... 'test_doctest4.txt',
1974
... globs={'favorite_color': 'blue'})
1975
>>> suite.run(unittest.TestResult())
1976
<unittest.TestResult run=3 errors=0 failures=2>
1978
In this case, we supplied a missing favorite color. You can
1979
provide doctest options:
1981
>>> suite = doctest.DocFileSuite('test_doctest.txt',
1982
... 'test_doctest2.txt',
1983
... 'test_doctest4.txt',
1984
... optionflags=doctest.DONT_ACCEPT_BLANKLINE,
1985
... globs={'favorite_color': 'blue'})
1986
>>> suite.run(unittest.TestResult())
1987
<unittest.TestResult run=3 errors=0 failures=3>
1989
And, you can provide setUp and tearDown functions:
1992
... import test.test_doctest
1993
... test.test_doctest.sillySetup = True
1995
>>> def tearDown(t):
1996
... import test.test_doctest
1997
... del test.test_doctest.sillySetup
1999
Here, we installed a silly variable that the test expects:
2001
>>> suite = doctest.DocFileSuite('test_doctest.txt',
2002
... 'test_doctest2.txt',
2003
... 'test_doctest4.txt',
2004
... setUp=setUp, tearDown=tearDown)
2005
>>> suite.run(unittest.TestResult())
2006
<unittest.TestResult run=3 errors=0 failures=2>
2008
But the tearDown restores sanity:
2010
>>> import test.test_doctest
2011
>>> test.test_doctest.sillySetup
2012
Traceback (most recent call last):
2014
AttributeError: 'module' object has no attribute 'sillySetup'
2016
The setUp and tearDown funtions are passed test objects.
2017
Here, we'll use a setUp function to set the favorite color in
2020
>>> def setUp(test):
2021
... test.globs['favorite_color'] = 'blue'
2023
>>> suite = doctest.DocFileSuite('test_doctest.txt', setUp=setUp)
2024
>>> suite.run(unittest.TestResult())
2025
<unittest.TestResult run=1 errors=0 failures=0>
2027
Here, we didn't need to use a tearDown function because we
2028
modified the test globals. The test globals are
2029
automatically cleared for us after a test.
2031
Tests in a file run using `DocFileSuite` can also access the
2032
`__file__` global, which is set to the name of the file
2033
containing the tests:
2035
>>> suite = doctest.DocFileSuite('test_doctest3.txt')
2036
>>> suite.run(unittest.TestResult())
2037
<unittest.TestResult run=1 errors=0 failures=0>
2039
If the tests contain non-ASCII characters, we have to specify which
2040
encoding the file is encoded with. We do so by using the `encoding`
2043
>>> suite = doctest.DocFileSuite('test_doctest.txt',
2044
... 'test_doctest2.txt',
2045
... 'test_doctest4.txt',
2046
... encoding='utf-8')
2047
>>> suite.run(unittest.TestResult())
2048
<unittest.TestResult run=3 errors=0 failures=2>
2052
def test_trailing_space_in_test():
2054
Trailing spaces in expected output are significant:
2056
>>> x, y = 'foo', ''
2062
def test_unittest_reportflags():
2063
"""Default unittest reporting flags can be set to control reporting
2065
Here, we'll set the REPORT_ONLY_FIRST_FAILURE option so we see
2066
only the first failure of each test. First, we'll look at the
2067
output without the flag. The file test_doctest.txt file has two
2068
tests. They both fail if blank lines are disabled:
2070
>>> suite = doctest.DocFileSuite('test_doctest.txt',
2071
... optionflags=doctest.DONT_ACCEPT_BLANKLINE)
2073
>>> result = suite.run(unittest.TestResult())
2074
>>> print result.failures[0][1] # doctest: +ELLIPSIS
2083
Note that we see both failures displayed.
2085
>>> old = doctest.set_unittest_reportflags(
2086
... doctest.REPORT_ONLY_FIRST_FAILURE)
2088
Now, when we run the test:
2090
>>> result = suite.run(unittest.TestResult())
2091
>>> print result.failures[0][1] # doctest: +ELLIPSIS
2097
NameError: name 'favorite_color' is not defined
2101
We get only the first failure.
2103
If we give any reporting options when we set up the tests,
2106
>>> suite = doctest.DocFileSuite('test_doctest.txt',
2107
... optionflags=doctest.DONT_ACCEPT_BLANKLINE | doctest.REPORT_NDIFF)
2109
Then the default eporting options are ignored:
2111
>>> result = suite.run(unittest.TestResult())
2112
>>> print result.failures[0][1] # doctest: +ELLIPSIS
2122
Differences (ndiff with -expected +actual):
2131
Test runners can restore the formatting flags after they run:
2133
>>> ignored = doctest.set_unittest_reportflags(old)
2137
def test_testfile(): r"""
2138
Tests for the `testfile()` function. This function runs all the
2139
doctest examples in a given file. In its simple invokation, it is
2140
called with the name of a file, which is taken to be relative to the
2141
calling module. The return value is (#failures, #tests).
2143
>>> doctest.testfile('test_doctest.txt') # doctest: +ELLIPSIS
2144
**********************************************************************
2145
File "...", line 6, in test_doctest.txt
2150
NameError: name 'favorite_color' is not defined
2151
**********************************************************************
2152
1 items had failures:
2153
1 of 2 in test_doctest.txt
2154
***Test Failed*** 1 failures.
2155
TestResults(failed=1, attempted=2)
2156
>>> doctest.master = None # Reset master.
2158
(Note: we'll be clearing doctest.master after each call to
2159
`doctest.testfile`, to supress warnings about multiple tests with the
2162
Globals may be specified with the `globs` and `extraglobs` parameters:
2164
>>> globs = {'favorite_color': 'blue'}
2165
>>> doctest.testfile('test_doctest.txt', globs=globs)
2166
TestResults(failed=0, attempted=2)
2167
>>> doctest.master = None # Reset master.
2169
>>> extraglobs = {'favorite_color': 'red'}
2170
>>> doctest.testfile('test_doctest.txt', globs=globs,
2171
... extraglobs=extraglobs) # doctest: +ELLIPSIS
2172
**********************************************************************
2173
File "...", line 6, in test_doctest.txt
2180
**********************************************************************
2181
1 items had failures:
2182
1 of 2 in test_doctest.txt
2183
***Test Failed*** 1 failures.
2184
TestResults(failed=1, attempted=2)
2185
>>> doctest.master = None # Reset master.
2187
The file may be made relative to a given module or package, using the
2188
optional `module_relative` parameter:
2190
>>> doctest.testfile('test_doctest.txt', globs=globs,
2191
... module_relative='test')
2192
TestResults(failed=0, attempted=2)
2193
>>> doctest.master = None # Reset master.
2195
Verbosity can be increased with the optional `verbose` paremter:
2197
>>> doctest.testfile('test_doctest.txt', globs=globs, verbose=True)
2213
1 items passed all tests:
2214
2 tests in test_doctest.txt
2216
2 passed and 0 failed.
2218
TestResults(failed=0, attempted=2)
2219
>>> doctest.master = None # Reset master.
2221
The name of the test may be specified with the optional `name`
2224
>>> doctest.testfile('test_doctest.txt', name='newname')
2225
... # doctest: +ELLIPSIS
2226
**********************************************************************
2227
File "...", line 6, in newname
2229
TestResults(failed=1, attempted=2)
2230
>>> doctest.master = None # Reset master.
2232
The summary report may be supressed with the optional `report`
2235
>>> doctest.testfile('test_doctest.txt', report=False)
2236
... # doctest: +ELLIPSIS
2237
**********************************************************************
2238
File "...", line 6, in test_doctest.txt
2243
NameError: name 'favorite_color' is not defined
2244
TestResults(failed=1, attempted=2)
2245
>>> doctest.master = None # Reset master.
2247
The optional keyword argument `raise_on_error` can be used to raise an
2248
exception on the first error (which may be useful for postmortem
2251
>>> doctest.testfile('test_doctest.txt', raise_on_error=True)
2252
... # doctest: +ELLIPSIS
2253
Traceback (most recent call last):
2254
UnexpectedException: ...
2255
>>> doctest.master = None # Reset master.
2257
If the tests contain non-ASCII characters, the tests might fail, since
2258
it's unknown which encoding is used. The encoding can be specified
2259
using the optional keyword argument `encoding`:
2261
>>> doctest.testfile('test_doctest4.txt') # doctest: +ELLIPSIS
2262
**********************************************************************
2263
File "...", line 7, in test_doctest4.txt
2269
u'f\xc3\xb6\xc3\xb6'
2270
**********************************************************************
2272
**********************************************************************
2273
1 items had failures:
2274
2 of 4 in test_doctest4.txt
2275
***Test Failed*** 2 failures.
2276
TestResults(failed=2, attempted=4)
2277
>>> doctest.master = None # Reset master.
2279
>>> doctest.testfile('test_doctest4.txt', encoding='utf-8')
2280
TestResults(failed=0, attempted=4)
2281
>>> doctest.master = None # Reset master.
2284
# old_test1, ... used to live in doctest.py, but cluttered it. Note
2285
# that these use the deprecated doctest.Tester, so should go away (or
2286
# be rewritten) someday.
2288
# Ignore all warnings about the use of class Tester in this module.
2289
# Note that the name of this module may differ depending on how it's
2290
# imported, so the use of __name__ is important.
2291
warnings.filterwarnings("ignore", "class Tester", DeprecationWarning,
2294
def old_test1(): r"""
2295
>>> from doctest import Tester
2296
>>> t = Tester(globs={'x': 42}, verbose=0)
2297
>>> t.runstring(r'''
2302
**********************************************************************
2310
TestResults(failed=1, attempted=2)
2311
>>> t.runstring(">>> x = x * 2\n>>> print x\n84\n", 'example2')
2312
TestResults(failed=0, attempted=2)
2314
**********************************************************************
2315
1 items had failures:
2317
***Test Failed*** 1 failures.
2318
TestResults(failed=1, attempted=4)
2319
>>> t.summarize(verbose=1)
2320
1 items passed all tests:
2322
**********************************************************************
2323
1 items had failures:
2326
3 passed and 1 failed.
2327
***Test Failed*** 1 failures.
2328
TestResults(failed=1, attempted=4)
2331
def old_test2(): r"""
2332
>>> from doctest import Tester
2333
>>> t = Tester(globs={}, verbose=1)
2335
... # just an example
2340
>>> t.runstring(test, "Example")
2341
Running string Example
2351
0 of 2 examples failed in string Example
2352
TestResults(failed=0, attempted=2)
2355
def old_test3(): r"""
2356
>>> from doctest import Tester
2357
>>> t = Tester(globs={}, verbose=0)
2359
... '''Trivial docstring example.
2360
... >>> assert 2 == 2
2364
>>> t.rundoc(_f) # expect 0 failures in 1 example
2365
TestResults(failed=0, attempted=1)
2368
def old_test4(): """
2370
>>> m1 = types.ModuleType('_m1')
2371
>>> m2 = types.ModuleType('_m2')
2372
>>> test_data = \"""
2374
... '''>>> assert 1 == 1
2377
... '''>>> assert 2 != 1
2380
... '''>>> assert 2 > 1
2383
... '''>>> assert 1 < 2
2386
>>> exec test_data in m1.__dict__
2387
>>> exec test_data in m2.__dict__
2388
>>> m1.__dict__.update({"f2": m2._f, "g2": m2.g, "h2": m2.H})
2390
Tests that objects outside m1 are excluded:
2392
>>> from doctest import Tester
2393
>>> t = Tester(globs={}, verbose=0)
2394
>>> t.rundict(m1.__dict__, "rundict_test", m1) # f2 and g2 and h2 skipped
2395
TestResults(failed=0, attempted=4)
2397
Once more, not excluding stuff outside m1:
2399
>>> t = Tester(globs={}, verbose=0)
2400
>>> t.rundict(m1.__dict__, "rundict_test_pvt") # None are skipped.
2401
TestResults(failed=0, attempted=8)
2403
The exclusion of objects from outside the designated module is
2404
meant to be invoked automagically by testmod.
2406
>>> doctest.testmod(m1, verbose=False)
2407
TestResults(failed=0, attempted=4)
2410
######################################################################
2412
######################################################################
2415
# Check the doctest cases in doctest itself:
2416
test_support.run_doctest(doctest, verbosity=True)
2417
# Check the doctest cases defined here:
2418
from test import test_doctest
2419
test_support.run_doctest(test_doctest, verbosity=True)
2422
def test_coverage(coverdir):
2423
tracer = trace.Trace(ignoredirs=[sys.prefix, sys.exec_prefix,],
2425
tracer.run('reload(doctest); test_main()')
2426
r = tracer.results()
2427
print 'Writing coverage results...'
2428
r.write_results(show_missing=True, summary=True,
2431
if __name__ == '__main__':
2432
if '-c' in sys.argv:
2433
test_coverage('/tmp/doctest.cover')
added
removed
Lib/test/test_doctest.py
