Georg Brandl | 83e51f4 | 2012-10-10 16:45:11 +0200 | [diff] [blame] | 1 | :keepdoctest: |
| 2 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 3 | :mod:`doctest` --- Test interactive Python examples |
| 4 | =================================================== |
| 5 | |
| 6 | .. module:: doctest |
| 7 | :synopsis: Test pieces of code within docstrings. |
| 8 | .. moduleauthor:: Tim Peters <tim@python.org> |
| 9 | .. sectionauthor:: Tim Peters <tim@python.org> |
| 10 | .. sectionauthor:: Moshe Zadka <moshez@debian.org> |
| 11 | .. sectionauthor:: Edward Loper <edloper@users.sourceforge.net> |
| 12 | |
| 13 | |
| 14 | The :mod:`doctest` module searches for pieces of text that look like interactive |
| 15 | Python sessions, and then executes those sessions to verify that they work |
| 16 | exactly as shown. There are several common ways to use doctest: |
| 17 | |
| 18 | * To check that a module's docstrings are up-to-date by verifying that all |
| 19 | interactive examples still work as documented. |
| 20 | |
| 21 | * To perform regression testing by verifying that interactive examples from a |
| 22 | test file or a test object work as expected. |
| 23 | |
| 24 | * To write tutorial documentation for a package, liberally illustrated with |
| 25 | input-output examples. Depending on whether the examples or the expository text |
| 26 | are emphasized, this has the flavor of "literate testing" or "executable |
| 27 | documentation". |
| 28 | |
| 29 | Here's a complete but small example module:: |
| 30 | |
| 31 | """ |
| 32 | This is the "example" module. |
| 33 | |
| 34 | The example module supplies one function, factorial(). For example, |
| 35 | |
| 36 | >>> factorial(5) |
| 37 | 120 |
| 38 | """ |
| 39 | |
| 40 | def factorial(n): |
| 41 | """Return the factorial of n, an exact integer >= 0. |
| 42 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 43 | >>> [factorial(n) for n in range(6)] |
| 44 | [1, 1, 2, 6, 24, 120] |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 45 | >>> factorial(30) |
Georg Brandl | 5c10664 | 2007-11-29 17:41:05 +0000 | [diff] [blame] | 46 | 265252859812191058636308480000000 |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 47 | >>> factorial(-1) |
| 48 | Traceback (most recent call last): |
| 49 | ... |
| 50 | ValueError: n must be >= 0 |
| 51 | |
| 52 | Factorials of floats are OK, but the float must be an exact integer: |
| 53 | >>> factorial(30.1) |
| 54 | Traceback (most recent call last): |
| 55 | ... |
| 56 | ValueError: n must be exact integer |
| 57 | >>> factorial(30.0) |
Georg Brandl | 5c10664 | 2007-11-29 17:41:05 +0000 | [diff] [blame] | 58 | 265252859812191058636308480000000 |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 59 | |
| 60 | It must also not be ridiculously large: |
| 61 | >>> factorial(1e100) |
| 62 | Traceback (most recent call last): |
| 63 | ... |
| 64 | OverflowError: n too large |
| 65 | """ |
| 66 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 67 | import math |
| 68 | if not n >= 0: |
| 69 | raise ValueError("n must be >= 0") |
| 70 | if math.floor(n) != n: |
| 71 | raise ValueError("n must be exact integer") |
| 72 | if n+1 == n: # catch a value like 1e300 |
| 73 | raise OverflowError("n too large") |
| 74 | result = 1 |
| 75 | factor = 2 |
| 76 | while factor <= n: |
| 77 | result *= factor |
| 78 | factor += 1 |
| 79 | return result |
| 80 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 81 | |
| 82 | if __name__ == "__main__": |
Guido van Rossum | 04110fb | 2007-08-24 16:32:05 +0000 | [diff] [blame] | 83 | import doctest |
| 84 | doctest.testmod() |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 85 | |
| 86 | If you run :file:`example.py` directly from the command line, :mod:`doctest` |
| 87 | works its magic:: |
| 88 | |
| 89 | $ python example.py |
| 90 | $ |
| 91 | |
| 92 | There's no output! That's normal, and it means all the examples worked. Pass |
Éric Araujo | 713d303 | 2010-11-18 16:38:46 +0000 | [diff] [blame] | 93 | ``-v`` to the script, and :mod:`doctest` prints a detailed log of what |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 94 | it's trying, and prints a summary at the end:: |
| 95 | |
| 96 | $ python example.py -v |
| 97 | Trying: |
| 98 | factorial(5) |
| 99 | Expecting: |
| 100 | 120 |
| 101 | ok |
| 102 | Trying: |
| 103 | [factorial(n) for n in range(6)] |
| 104 | Expecting: |
| 105 | [1, 1, 2, 6, 24, 120] |
| 106 | ok |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 107 | |
| 108 | And so on, eventually ending with:: |
| 109 | |
| 110 | Trying: |
| 111 | factorial(1e100) |
| 112 | Expecting: |
| 113 | Traceback (most recent call last): |
| 114 | ... |
| 115 | OverflowError: n too large |
| 116 | ok |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 117 | 2 items passed all tests: |
| 118 | 1 tests in __main__ |
| 119 | 8 tests in __main__.factorial |
Guido van Rossum | 04110fb | 2007-08-24 16:32:05 +0000 | [diff] [blame] | 120 | 9 tests in 2 items. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 121 | 9 passed and 0 failed. |
| 122 | Test passed. |
| 123 | $ |
| 124 | |
| 125 | That's all you need to know to start making productive use of :mod:`doctest`! |
| 126 | Jump in. The following sections provide full details. Note that there are many |
| 127 | examples of doctests in the standard Python test suite and libraries. |
| 128 | Especially useful examples can be found in the standard test file |
| 129 | :file:`Lib/test/test_doctest.py`. |
| 130 | |
| 131 | |
| 132 | .. _doctest-simple-testmod: |
| 133 | |
| 134 | Simple Usage: Checking Examples in Docstrings |
| 135 | --------------------------------------------- |
| 136 | |
| 137 | The simplest way to start using doctest (but not necessarily the way you'll |
| 138 | continue to do it) is to end each module :mod:`M` with:: |
| 139 | |
Guido van Rossum | 04110fb | 2007-08-24 16:32:05 +0000 | [diff] [blame] | 140 | if __name__ == "__main__": |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 141 | import doctest |
| 142 | doctest.testmod() |
| 143 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 144 | :mod:`doctest` then examines docstrings in module :mod:`M`. |
| 145 | |
| 146 | Running the module as a script causes the examples in the docstrings to get |
| 147 | executed and verified:: |
| 148 | |
| 149 | python M.py |
| 150 | |
| 151 | This won't display anything unless an example fails, in which case the failing |
| 152 | example(s) and the cause(s) of the failure(s) are printed to stdout, and the |
| 153 | final line of output is ``***Test Failed*** N failures.``, where *N* is the |
| 154 | number of examples that failed. |
| 155 | |
Éric Araujo | 713d303 | 2010-11-18 16:38:46 +0000 | [diff] [blame] | 156 | Run it with the ``-v`` switch instead:: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 157 | |
| 158 | python M.py -v |
| 159 | |
| 160 | and a detailed report of all examples tried is printed to standard output, along |
| 161 | with assorted summaries at the end. |
| 162 | |
| 163 | You can force verbose mode by passing ``verbose=True`` to :func:`testmod`, or |
| 164 | prohibit it by passing ``verbose=False``. In either of those cases, |
Éric Araujo | 713d303 | 2010-11-18 16:38:46 +0000 | [diff] [blame] | 165 | ``sys.argv`` is not examined by :func:`testmod` (so passing ``-v`` or not |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 166 | has no effect). |
| 167 | |
Georg Brandl | 3183585 | 2008-05-12 17:38:56 +0000 | [diff] [blame] | 168 | There is also a command line shortcut for running :func:`testmod`. You can |
| 169 | instruct the Python interpreter to run the doctest module directly from the |
| 170 | standard library and pass the module name(s) on the command line:: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 171 | |
| 172 | python -m doctest -v example.py |
| 173 | |
| 174 | This will import :file:`example.py` as a standalone module and run |
| 175 | :func:`testmod` on it. Note that this may not work correctly if the file is |
| 176 | part of a package and imports other submodules from that package. |
| 177 | |
| 178 | For more information on :func:`testmod`, see section :ref:`doctest-basic-api`. |
| 179 | |
| 180 | |
| 181 | .. _doctest-simple-testfile: |
| 182 | |
| 183 | Simple Usage: Checking Examples in a Text File |
| 184 | ---------------------------------------------- |
| 185 | |
| 186 | Another simple application of doctest is testing interactive examples in a text |
| 187 | file. This can be done with the :func:`testfile` function:: |
| 188 | |
| 189 | import doctest |
| 190 | doctest.testfile("example.txt") |
| 191 | |
| 192 | That short script executes and verifies any interactive Python examples |
| 193 | contained in the file :file:`example.txt`. The file content is treated as if it |
| 194 | were a single giant docstring; the file doesn't need to contain a Python |
| 195 | program! For example, perhaps :file:`example.txt` contains this:: |
| 196 | |
| 197 | The ``example`` module |
| 198 | ====================== |
| 199 | |
| 200 | Using ``factorial`` |
| 201 | ------------------- |
| 202 | |
| 203 | This is an example text file in reStructuredText format. First import |
| 204 | ``factorial`` from the ``example`` module: |
| 205 | |
| 206 | >>> from example import factorial |
| 207 | |
| 208 | Now use it: |
| 209 | |
| 210 | >>> factorial(6) |
| 211 | 120 |
| 212 | |
| 213 | Running ``doctest.testfile("example.txt")`` then finds the error in this |
| 214 | documentation:: |
| 215 | |
| 216 | File "./example.txt", line 14, in example.txt |
| 217 | Failed example: |
| 218 | factorial(6) |
| 219 | Expected: |
| 220 | 120 |
| 221 | Got: |
| 222 | 720 |
| 223 | |
| 224 | As with :func:`testmod`, :func:`testfile` won't display anything unless an |
| 225 | example fails. If an example does fail, then the failing example(s) and the |
| 226 | cause(s) of the failure(s) are printed to stdout, using the same format as |
| 227 | :func:`testmod`. |
| 228 | |
| 229 | By default, :func:`testfile` looks for files in the calling module's directory. |
| 230 | See section :ref:`doctest-basic-api` for a description of the optional arguments |
| 231 | that can be used to tell it to look for files in other locations. |
| 232 | |
| 233 | Like :func:`testmod`, :func:`testfile`'s verbosity can be set with the |
Éric Araujo | 713d303 | 2010-11-18 16:38:46 +0000 | [diff] [blame] | 234 | ``-v`` command-line switch or with the optional keyword argument |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 235 | *verbose*. |
| 236 | |
Georg Brandl | 3183585 | 2008-05-12 17:38:56 +0000 | [diff] [blame] | 237 | There is also a command line shortcut for running :func:`testfile`. You can |
| 238 | instruct the Python interpreter to run the doctest module directly from the |
| 239 | standard library and pass the file name(s) on the command line:: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 240 | |
| 241 | python -m doctest -v example.txt |
| 242 | |
| 243 | Because the file name does not end with :file:`.py`, :mod:`doctest` infers that |
| 244 | it must be run with :func:`testfile`, not :func:`testmod`. |
| 245 | |
| 246 | For more information on :func:`testfile`, see section :ref:`doctest-basic-api`. |
| 247 | |
| 248 | |
| 249 | .. _doctest-how-it-works: |
| 250 | |
| 251 | How It Works |
| 252 | ------------ |
| 253 | |
| 254 | This section examines in detail how doctest works: which docstrings it looks at, |
| 255 | how it finds interactive examples, what execution context it uses, how it |
| 256 | handles exceptions, and how option flags can be used to control its behavior. |
| 257 | This is the information that you need to know to write doctest examples; for |
| 258 | information about actually running doctest on these examples, see the following |
| 259 | sections. |
| 260 | |
| 261 | |
| 262 | .. _doctest-which-docstrings: |
| 263 | |
| 264 | Which Docstrings Are Examined? |
| 265 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 266 | |
| 267 | The module docstring, and all function, class and method docstrings are |
| 268 | searched. Objects imported into the module are not searched. |
| 269 | |
| 270 | In addition, if ``M.__test__`` exists and "is true", it must be a dict, and each |
| 271 | entry maps a (string) name to a function object, class object, or string. |
| 272 | Function and class object docstrings found from ``M.__test__`` are searched, and |
| 273 | strings are treated as if they were docstrings. In output, a key ``K`` in |
| 274 | ``M.__test__`` appears with name :: |
| 275 | |
| 276 | <name of M>.__test__.K |
| 277 | |
| 278 | Any classes found are recursively searched similarly, to test docstrings in |
| 279 | their contained methods and nested classes. |
| 280 | |
Zachary Ware | a4b7a75 | 2013-11-24 01:19:09 -0600 | [diff] [blame] | 281 | .. impl-detail:: |
| 282 | Prior to version 3.4, extension modules written in C were not fully |
| 283 | searched by doctest. |
| 284 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 285 | |
| 286 | .. _doctest-finding-examples: |
| 287 | |
| 288 | How are Docstring Examples Recognized? |
| 289 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 290 | |
R. David Murray | 9691e59 | 2010-06-15 23:46:40 +0000 | [diff] [blame] | 291 | In most cases a copy-and-paste of an interactive console session works fine, |
| 292 | but doctest isn't trying to do an exact emulation of any specific Python shell. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 293 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 294 | :: |
| 295 | |
| 296 | >>> # comments are ignored |
| 297 | >>> x = 12 |
| 298 | >>> x |
| 299 | 12 |
| 300 | >>> if x == 13: |
Georg Brandl | 6911e3c | 2007-09-04 07:15:32 +0000 | [diff] [blame] | 301 | ... print("yes") |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 302 | ... else: |
Georg Brandl | 6911e3c | 2007-09-04 07:15:32 +0000 | [diff] [blame] | 303 | ... print("no") |
| 304 | ... print("NO") |
| 305 | ... print("NO!!!") |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 306 | ... |
| 307 | no |
| 308 | NO |
| 309 | NO!!! |
| 310 | >>> |
| 311 | |
| 312 | Any expected output must immediately follow the final ``'>>> '`` or ``'... '`` |
| 313 | line containing the code, and the expected output (if any) extends to the next |
| 314 | ``'>>> '`` or all-whitespace line. |
| 315 | |
| 316 | The fine print: |
| 317 | |
| 318 | * Expected output cannot contain an all-whitespace line, since such a line is |
| 319 | taken to signal the end of expected output. If expected output does contain a |
| 320 | blank line, put ``<BLANKLINE>`` in your doctest example each place a blank line |
| 321 | is expected. |
| 322 | |
R. David Murray | 9691e59 | 2010-06-15 23:46:40 +0000 | [diff] [blame] | 323 | * All hard tab characters are expanded to spaces, using 8-column tab stops. |
| 324 | Tabs in output generated by the tested code are not modified. Because any |
| 325 | hard tabs in the sample output *are* expanded, this means that if the code |
| 326 | output includes hard tabs, the only way the doctest can pass is if the |
Chris Jerdonek | 3650ea2 | 2012-10-10 06:52:08 -0700 | [diff] [blame] | 327 | :const:`NORMALIZE_WHITESPACE` option or :ref:`directive <doctest-directives>` |
| 328 | is in effect. |
R. David Murray | 9691e59 | 2010-06-15 23:46:40 +0000 | [diff] [blame] | 329 | Alternatively, the test can be rewritten to capture the output and compare it |
| 330 | to an expected value as part of the test. This handling of tabs in the |
| 331 | source was arrived at through trial and error, and has proven to be the least |
| 332 | error prone way of handling them. It is possible to use a different |
| 333 | algorithm for handling tabs by writing a custom :class:`DocTestParser` class. |
| 334 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 335 | * Output to stdout is captured, but not output to stderr (exception tracebacks |
| 336 | are captured via a different means). |
| 337 | |
| 338 | * If you continue a line via backslashing in an interactive session, or for any |
| 339 | other reason use a backslash, you should use a raw docstring, which will |
| 340 | preserve your backslashes exactly as you type them:: |
| 341 | |
| 342 | >>> def f(x): |
| 343 | ... r'''Backslashes in a raw docstring: m\n''' |
Georg Brandl | 6911e3c | 2007-09-04 07:15:32 +0000 | [diff] [blame] | 344 | >>> print(f.__doc__) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 345 | Backslashes in a raw docstring: m\n |
| 346 | |
| 347 | Otherwise, the backslash will be interpreted as part of the string. For example, |
Ezio Melotti | 694f233 | 2012-09-20 09:47:03 +0300 | [diff] [blame] | 348 | the ``\n`` above would be interpreted as a newline character. Alternatively, you |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 349 | can double each backslash in the doctest version (and not use a raw string):: |
| 350 | |
| 351 | >>> def f(x): |
| 352 | ... '''Backslashes in a raw docstring: m\\n''' |
Georg Brandl | 6911e3c | 2007-09-04 07:15:32 +0000 | [diff] [blame] | 353 | >>> print(f.__doc__) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 354 | Backslashes in a raw docstring: m\n |
| 355 | |
| 356 | * The starting column doesn't matter:: |
| 357 | |
| 358 | >>> assert "Easy!" |
| 359 | >>> import math |
| 360 | >>> math.floor(1.9) |
R. David Murray | 7c5714f | 2009-11-23 03:13:23 +0000 | [diff] [blame] | 361 | 1 |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 362 | |
| 363 | and as many leading whitespace characters are stripped from the expected output |
| 364 | as appeared in the initial ``'>>> '`` line that started the example. |
| 365 | |
| 366 | |
| 367 | .. _doctest-execution-context: |
| 368 | |
| 369 | What's the Execution Context? |
| 370 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 371 | |
| 372 | By default, each time :mod:`doctest` finds a docstring to test, it uses a |
| 373 | *shallow copy* of :mod:`M`'s globals, so that running tests doesn't change the |
| 374 | module's real globals, and so that one test in :mod:`M` can't leave behind |
| 375 | crumbs that accidentally allow another test to work. This means examples can |
| 376 | freely use any names defined at top-level in :mod:`M`, and names defined earlier |
| 377 | in the docstring being run. Examples cannot see names defined in other |
| 378 | docstrings. |
| 379 | |
| 380 | You can force use of your own dict as the execution context by passing |
| 381 | ``globs=your_dict`` to :func:`testmod` or :func:`testfile` instead. |
| 382 | |
| 383 | |
| 384 | .. _doctest-exceptions: |
| 385 | |
| 386 | What About Exceptions? |
| 387 | ^^^^^^^^^^^^^^^^^^^^^^ |
| 388 | |
| 389 | No problem, provided that the traceback is the only output produced by the |
| 390 | example: just paste in the traceback. [#]_ Since tracebacks contain details |
| 391 | that are likely to change rapidly (for example, exact file paths and line |
| 392 | numbers), this is one case where doctest works hard to be flexible in what it |
| 393 | accepts. |
| 394 | |
| 395 | Simple example:: |
| 396 | |
| 397 | >>> [1, 2, 3].remove(42) |
| 398 | Traceback (most recent call last): |
| 399 | File "<stdin>", line 1, in ? |
| 400 | ValueError: list.remove(x): x not in list |
| 401 | |
| 402 | That doctest succeeds if :exc:`ValueError` is raised, with the ``list.remove(x): |
| 403 | x not in list`` detail as shown. |
| 404 | |
| 405 | The expected output for an exception must start with a traceback header, which |
| 406 | may be either of the following two lines, indented the same as the first line of |
| 407 | the example:: |
| 408 | |
| 409 | Traceback (most recent call last): |
| 410 | Traceback (innermost last): |
| 411 | |
| 412 | The traceback header is followed by an optional traceback stack, whose contents |
| 413 | are ignored by doctest. The traceback stack is typically omitted, or copied |
| 414 | verbatim from an interactive session. |
| 415 | |
| 416 | The traceback stack is followed by the most interesting part: the line(s) |
| 417 | containing the exception type and detail. This is usually the last line of a |
| 418 | traceback, but can extend across multiple lines if the exception has a |
| 419 | multi-line detail:: |
| 420 | |
| 421 | >>> raise ValueError('multi\n line\ndetail') |
| 422 | Traceback (most recent call last): |
| 423 | File "<stdin>", line 1, in ? |
| 424 | ValueError: multi |
| 425 | line |
| 426 | detail |
| 427 | |
| 428 | The last three lines (starting with :exc:`ValueError`) are compared against the |
| 429 | exception's type and detail, and the rest are ignored. |
| 430 | |
| 431 | Best practice is to omit the traceback stack, unless it adds significant |
| 432 | documentation value to the example. So the last example is probably better as:: |
| 433 | |
| 434 | >>> raise ValueError('multi\n line\ndetail') |
| 435 | Traceback (most recent call last): |
| 436 | ... |
| 437 | ValueError: multi |
| 438 | line |
| 439 | detail |
| 440 | |
| 441 | Note that tracebacks are treated very specially. In particular, in the |
| 442 | rewritten example, the use of ``...`` is independent of doctest's |
| 443 | :const:`ELLIPSIS` option. The ellipsis in that example could be left out, or |
| 444 | could just as well be three (or three hundred) commas or digits, or an indented |
| 445 | transcript of a Monty Python skit. |
| 446 | |
| 447 | Some details you should read once, but won't need to remember: |
| 448 | |
| 449 | * Doctest can't guess whether your expected output came from an exception |
| 450 | traceback or from ordinary printing. So, e.g., an example that expects |
| 451 | ``ValueError: 42 is prime`` will pass whether :exc:`ValueError` is actually |
| 452 | raised or if the example merely prints that traceback text. In practice, |
| 453 | ordinary output rarely begins with a traceback header line, so this doesn't |
| 454 | create real problems. |
| 455 | |
| 456 | * Each line of the traceback stack (if present) must be indented further than |
| 457 | the first line of the example, *or* start with a non-alphanumeric character. |
| 458 | The first line following the traceback header indented the same and starting |
| 459 | with an alphanumeric is taken to be the start of the exception detail. Of |
| 460 | course this does the right thing for genuine tracebacks. |
| 461 | |
Nick Coghlan | 5e76e94 | 2010-06-12 13:42:46 +0000 | [diff] [blame] | 462 | * When the :const:`IGNORE_EXCEPTION_DETAIL` doctest option is specified, |
| 463 | everything following the leftmost colon and any module information in the |
| 464 | exception name is ignored. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 465 | |
| 466 | * The interactive shell omits the traceback header line for some |
| 467 | :exc:`SyntaxError`\ s. But doctest uses the traceback header line to |
| 468 | distinguish exceptions from non-exceptions. So in the rare case where you need |
| 469 | to test a :exc:`SyntaxError` that omits the traceback header, you will need to |
| 470 | manually add the traceback header line to your test example. |
| 471 | |
| 472 | * For some :exc:`SyntaxError`\ s, Python displays the character position of the |
| 473 | syntax error, using a ``^`` marker:: |
| 474 | |
| 475 | >>> 1 1 |
| 476 | File "<stdin>", line 1 |
| 477 | 1 1 |
| 478 | ^ |
| 479 | SyntaxError: invalid syntax |
| 480 | |
| 481 | Since the lines showing the position of the error come before the exception type |
| 482 | and detail, they are not checked by doctest. For example, the following test |
| 483 | would pass, even though it puts the ``^`` marker in the wrong location:: |
| 484 | |
| 485 | >>> 1 1 |
| 486 | Traceback (most recent call last): |
| 487 | File "<stdin>", line 1 |
| 488 | 1 1 |
| 489 | ^ |
| 490 | SyntaxError: invalid syntax |
| 491 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 492 | |
Chris Jerdonek | 3650ea2 | 2012-10-10 06:52:08 -0700 | [diff] [blame] | 493 | .. _option-flags-and-directives: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 494 | .. _doctest-options: |
| 495 | |
Chris Jerdonek | 3650ea2 | 2012-10-10 06:52:08 -0700 | [diff] [blame] | 496 | Option Flags |
| 497 | ^^^^^^^^^^^^ |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 498 | |
| 499 | A number of option flags control various aspects of doctest's behavior. |
| 500 | Symbolic names for the flags are supplied as module constants, which can be |
| 501 | or'ed together and passed to various functions. The names can also be used in |
R David Murray | 5707d50 | 2013-06-23 14:24:13 -0400 | [diff] [blame] | 502 | :ref:`doctest directives <doctest-directives>`, and may be passed to the |
| 503 | doctest command line interface via the ``-o`` option. |
| 504 | |
Georg Brandl | df48b97 | 2014-03-24 09:06:18 +0100 | [diff] [blame] | 505 | .. versionadded:: 3.4 |
| 506 | The ``-o`` command line option. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 507 | |
| 508 | The first group of options define test semantics, controlling aspects of how |
| 509 | doctest decides whether actual output matches an example's expected output: |
| 510 | |
| 511 | |
| 512 | .. data:: DONT_ACCEPT_TRUE_FOR_1 |
| 513 | |
| 514 | By default, if an expected output block contains just ``1``, an actual output |
| 515 | block containing just ``1`` or just ``True`` is considered to be a match, and |
| 516 | similarly for ``0`` versus ``False``. When :const:`DONT_ACCEPT_TRUE_FOR_1` is |
| 517 | specified, neither substitution is allowed. The default behavior caters to that |
| 518 | Python changed the return type of many functions from integer to boolean; |
| 519 | doctests expecting "little integer" output still work in these cases. This |
| 520 | option will probably go away, but not for several years. |
| 521 | |
| 522 | |
| 523 | .. data:: DONT_ACCEPT_BLANKLINE |
| 524 | |
| 525 | By default, if an expected output block contains a line containing only the |
| 526 | string ``<BLANKLINE>``, then that line will match a blank line in the actual |
| 527 | output. Because a genuinely blank line delimits the expected output, this is |
| 528 | the only way to communicate that a blank line is expected. When |
| 529 | :const:`DONT_ACCEPT_BLANKLINE` is specified, this substitution is not allowed. |
| 530 | |
| 531 | |
| 532 | .. data:: NORMALIZE_WHITESPACE |
| 533 | |
| 534 | When specified, all sequences of whitespace (blanks and newlines) are treated as |
| 535 | equal. Any sequence of whitespace within the expected output will match any |
| 536 | sequence of whitespace within the actual output. By default, whitespace must |
| 537 | match exactly. :const:`NORMALIZE_WHITESPACE` is especially useful when a line of |
| 538 | expected output is very long, and you want to wrap it across multiple lines in |
| 539 | your source. |
| 540 | |
| 541 | |
| 542 | .. data:: ELLIPSIS |
| 543 | |
| 544 | When specified, an ellipsis marker (``...``) in the expected output can match |
| 545 | any substring in the actual output. This includes substrings that span line |
| 546 | boundaries, and empty substrings, so it's best to keep usage of this simple. |
| 547 | Complicated uses can lead to the same kinds of "oops, it matched too much!" |
| 548 | surprises that ``.*`` is prone to in regular expressions. |
| 549 | |
| 550 | |
| 551 | .. data:: IGNORE_EXCEPTION_DETAIL |
| 552 | |
| 553 | When specified, an example that expects an exception passes if an exception of |
| 554 | the expected type is raised, even if the exception detail does not match. For |
| 555 | example, an example expecting ``ValueError: 42`` will pass if the actual |
| 556 | exception raised is ``ValueError: 3*14``, but will fail, e.g., if |
| 557 | :exc:`TypeError` is raised. |
| 558 | |
Nick Coghlan | 5e76e94 | 2010-06-12 13:42:46 +0000 | [diff] [blame] | 559 | It will also ignore the module name used in Python 3 doctest reports. Hence |
Chris Jerdonek | 3650ea2 | 2012-10-10 06:52:08 -0700 | [diff] [blame] | 560 | both of these variations will work with the flag specified, regardless of |
| 561 | whether the test is run under Python 2.7 or Python 3.2 (or later versions):: |
Nick Coghlan | 5e76e94 | 2010-06-12 13:42:46 +0000 | [diff] [blame] | 562 | |
Chris Jerdonek | 3fa8c59 | 2012-10-10 08:34:38 -0700 | [diff] [blame] | 563 | >>> raise CustomError('message') |
Nick Coghlan | 5e76e94 | 2010-06-12 13:42:46 +0000 | [diff] [blame] | 564 | Traceback (most recent call last): |
| 565 | CustomError: message |
| 566 | |
Chris Jerdonek | 3fa8c59 | 2012-10-10 08:34:38 -0700 | [diff] [blame] | 567 | >>> raise CustomError('message') |
Nick Coghlan | 5e76e94 | 2010-06-12 13:42:46 +0000 | [diff] [blame] | 568 | Traceback (most recent call last): |
| 569 | my_module.CustomError: message |
| 570 | |
| 571 | Note that :const:`ELLIPSIS` can also be used to ignore the |
| 572 | details of the exception message, but such a test may still fail based |
| 573 | on whether or not the module details are printed as part of the |
| 574 | exception name. Using :const:`IGNORE_EXCEPTION_DETAIL` and the details |
| 575 | from Python 2.3 is also the only clear way to write a doctest that doesn't |
| 576 | care about the exception detail yet continues to pass under Python 2.3 or |
Chris Jerdonek | 3650ea2 | 2012-10-10 06:52:08 -0700 | [diff] [blame] | 577 | earlier (those releases do not support :ref:`doctest directives |
| 578 | <doctest-directives>` and ignore them as irrelevant comments). For example:: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 579 | |
Chris Jerdonek | 3fa8c59 | 2012-10-10 08:34:38 -0700 | [diff] [blame] | 580 | >>> (1, 2)[3] = 'moo' |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 581 | Traceback (most recent call last): |
| 582 | File "<stdin>", line 1, in ? |
| 583 | TypeError: object doesn't support item assignment |
| 584 | |
Chris Jerdonek | 3650ea2 | 2012-10-10 06:52:08 -0700 | [diff] [blame] | 585 | passes under Python 2.3 and later Python versions with the flag specified, |
| 586 | even though the detail |
Nick Coghlan | 5e76e94 | 2010-06-12 13:42:46 +0000 | [diff] [blame] | 587 | changed in Python 2.4 to say "does not" instead of "doesn't". |
| 588 | |
| 589 | .. versionchanged:: 3.2 |
Georg Brandl | 67b21b7 | 2010-08-17 15:07:14 +0000 | [diff] [blame] | 590 | :const:`IGNORE_EXCEPTION_DETAIL` now also ignores any information relating |
| 591 | to the module containing the exception under test. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 592 | |
| 593 | |
| 594 | .. data:: SKIP |
| 595 | |
| 596 | When specified, do not run the example at all. This can be useful in contexts |
| 597 | where doctest examples serve as both documentation and test cases, and an |
| 598 | example should be included for documentation purposes, but should not be |
| 599 | checked. E.g., the example's output might be random; or the example might |
| 600 | depend on resources which would be unavailable to the test driver. |
| 601 | |
| 602 | The SKIP flag can also be used for temporarily "commenting out" examples. |
| 603 | |
| 604 | |
| 605 | .. data:: COMPARISON_FLAGS |
| 606 | |
| 607 | A bitmask or'ing together all the comparison flags above. |
| 608 | |
| 609 | The second group of options controls how test failures are reported: |
| 610 | |
| 611 | |
| 612 | .. data:: REPORT_UDIFF |
| 613 | |
| 614 | When specified, failures that involve multi-line expected and actual outputs are |
| 615 | displayed using a unified diff. |
| 616 | |
| 617 | |
| 618 | .. data:: REPORT_CDIFF |
| 619 | |
| 620 | When specified, failures that involve multi-line expected and actual outputs |
| 621 | will be displayed using a context diff. |
| 622 | |
| 623 | |
| 624 | .. data:: REPORT_NDIFF |
| 625 | |
| 626 | When specified, differences are computed by ``difflib.Differ``, using the same |
| 627 | algorithm as the popular :file:`ndiff.py` utility. This is the only method that |
| 628 | marks differences within lines as well as across lines. For example, if a line |
| 629 | of expected output contains digit ``1`` where actual output contains letter |
| 630 | ``l``, a line is inserted with a caret marking the mismatching column positions. |
| 631 | |
| 632 | |
| 633 | .. data:: REPORT_ONLY_FIRST_FAILURE |
| 634 | |
| 635 | When specified, display the first failing example in each doctest, but suppress |
| 636 | output for all remaining examples. This will prevent doctest from reporting |
| 637 | correct examples that break because of earlier failures; but it might also hide |
| 638 | incorrect examples that fail independently of the first failure. When |
| 639 | :const:`REPORT_ONLY_FIRST_FAILURE` is specified, the remaining examples are |
| 640 | still run, and still count towards the total number of failures reported; only |
| 641 | the output is suppressed. |
| 642 | |
| 643 | |
R David Murray | 5a9d706 | 2012-11-21 15:09:21 -0500 | [diff] [blame] | 644 | .. data:: FAIL_FAST |
| 645 | |
| 646 | When specified, exit after the first failing example and don't attempt to run |
R David Murray | 60dd6e5 | 2012-11-22 06:22:41 -0500 | [diff] [blame] | 647 | the remaining examples. Thus, the number of failures reported will be at most |
| 648 | 1. This flag may be useful during debugging, since examples after the first |
R David Murray | 5a9d706 | 2012-11-21 15:09:21 -0500 | [diff] [blame] | 649 | failure won't even produce debugging output. |
| 650 | |
R David Murray | 5707d50 | 2013-06-23 14:24:13 -0400 | [diff] [blame] | 651 | The doctest command line accepts the option ``-f`` as a shorthand for ``-o |
| 652 | FAIL_FAST``. |
| 653 | |
R David Murray | 5a9d706 | 2012-11-21 15:09:21 -0500 | [diff] [blame] | 654 | .. versionadded:: 3.4 |
| 655 | |
| 656 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 657 | .. data:: REPORTING_FLAGS |
| 658 | |
| 659 | A bitmask or'ing together all the reporting flags above. |
| 660 | |
Chris Jerdonek | 3650ea2 | 2012-10-10 06:52:08 -0700 | [diff] [blame] | 661 | |
| 662 | There is also a way to register new option flag names, though this isn't |
| 663 | useful unless you intend to extend :mod:`doctest` internals via subclassing: |
| 664 | |
| 665 | |
| 666 | .. function:: register_optionflag(name) |
| 667 | |
| 668 | Create a new option flag with a given name, and return the new flag's integer |
| 669 | value. :func:`register_optionflag` can be used when subclassing |
| 670 | :class:`OutputChecker` or :class:`DocTestRunner` to create new options that are |
| 671 | supported by your subclasses. :func:`register_optionflag` should always be |
| 672 | called using the following idiom:: |
| 673 | |
| 674 | MY_FLAG = register_optionflag('MY_FLAG') |
| 675 | |
| 676 | |
| 677 | .. _doctest-directives: |
| 678 | |
| 679 | Directives |
| 680 | ^^^^^^^^^^ |
| 681 | |
| 682 | Doctest directives may be used to modify the :ref:`option flags |
| 683 | <doctest-options>` for an individual example. Doctest directives are |
| 684 | special Python comments following an example's source code: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 685 | |
| 686 | .. productionlist:: doctest |
| 687 | directive: "#" "doctest:" `directive_options` |
| 688 | directive_options: `directive_option` ("," `directive_option`)\* |
| 689 | directive_option: `on_or_off` `directive_option_name` |
| 690 | on_or_off: "+" \| "-" |
| 691 | directive_option_name: "DONT_ACCEPT_BLANKLINE" \| "NORMALIZE_WHITESPACE" \| ... |
| 692 | |
| 693 | Whitespace is not allowed between the ``+`` or ``-`` and the directive option |
| 694 | name. The directive option name can be any of the option flag names explained |
| 695 | above. |
| 696 | |
| 697 | An example's doctest directives modify doctest's behavior for that single |
| 698 | example. Use ``+`` to enable the named behavior, or ``-`` to disable it. |
| 699 | |
Georg Brandl | 83e51f4 | 2012-10-10 16:45:11 +0200 | [diff] [blame] | 700 | For example, this test passes:: |
Nick Coghlan | 8f80e0a | 2012-10-03 12:21:44 +0530 | [diff] [blame] | 701 | |
Georg Brandl | 83e51f4 | 2012-10-10 16:45:11 +0200 | [diff] [blame] | 702 | >>> print(list(range(20))) # doctest: +NORMALIZE_WHITESPACE |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 703 | [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, |
| 704 | 10, 11, 12, 13, 14, 15, 16, 17, 18, 19] |
| 705 | |
| 706 | Without the directive it would fail, both because the actual output doesn't have |
| 707 | two blanks before the single-digit list elements, and because the actual output |
| 708 | is on a single line. This test also passes, and also requires a directive to do |
Georg Brandl | 83e51f4 | 2012-10-10 16:45:11 +0200 | [diff] [blame] | 709 | so:: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 710 | |
Georg Brandl | 8f80a5b | 2010-03-21 09:25:54 +0000 | [diff] [blame] | 711 | >>> print(list(range(20))) # doctest: +ELLIPSIS |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 712 | [0, 1, ..., 18, 19] |
| 713 | |
Nick Coghlan | 0b26ccf | 2012-10-03 13:52:48 +0530 | [diff] [blame] | 714 | Multiple directives can be used on a single physical line, separated by |
Georg Brandl | 83e51f4 | 2012-10-10 16:45:11 +0200 | [diff] [blame] | 715 | commas:: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 716 | |
Georg Brandl | 8f80a5b | 2010-03-21 09:25:54 +0000 | [diff] [blame] | 717 | >>> print(list(range(20))) # doctest: +ELLIPSIS, +NORMALIZE_WHITESPACE |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 718 | [0, 1, ..., 18, 19] |
| 719 | |
| 720 | If multiple directive comments are used for a single example, then they are |
Georg Brandl | 83e51f4 | 2012-10-10 16:45:11 +0200 | [diff] [blame] | 721 | combined:: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 722 | |
Georg Brandl | 8f80a5b | 2010-03-21 09:25:54 +0000 | [diff] [blame] | 723 | >>> print(list(range(20))) # doctest: +ELLIPSIS |
| 724 | ... # doctest: +NORMALIZE_WHITESPACE |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 725 | [0, 1, ..., 18, 19] |
| 726 | |
| 727 | As the previous example shows, you can add ``...`` lines to your example |
| 728 | containing only directives. This can be useful when an example is too long for |
Georg Brandl | 83e51f4 | 2012-10-10 16:45:11 +0200 | [diff] [blame] | 729 | a directive to comfortably fit on the same line:: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 730 | |
Georg Brandl | 8f80a5b | 2010-03-21 09:25:54 +0000 | [diff] [blame] | 731 | >>> print(list(range(5)) + list(range(10, 20)) + list(range(30, 40))) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 732 | ... # doctest: +ELLIPSIS |
Georg Brandl | 8f80a5b | 2010-03-21 09:25:54 +0000 | [diff] [blame] | 733 | [0, ..., 4, 10, ..., 19, 30, ..., 39] |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 734 | |
| 735 | Note that since all options are disabled by default, and directives apply only |
| 736 | to the example they appear in, enabling options (via ``+`` in a directive) is |
| 737 | usually the only meaningful choice. However, option flags can also be passed to |
| 738 | functions that run doctests, establishing different defaults. In such cases, |
| 739 | disabling an option via ``-`` in a directive can be useful. |
| 740 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 741 | |
| 742 | .. _doctest-warnings: |
| 743 | |
| 744 | Warnings |
| 745 | ^^^^^^^^ |
| 746 | |
| 747 | :mod:`doctest` is serious about requiring exact matches in expected output. If |
| 748 | even a single character doesn't match, the test fails. This will probably |
| 749 | surprise you a few times, as you learn exactly what Python does and doesn't |
| 750 | guarantee about output. For example, when printing a dict, Python doesn't |
| 751 | guarantee that the key-value pairs will be printed in any particular order, so a |
Christian Heimes | 5b5e81c | 2007-12-31 16:14:33 +0000 | [diff] [blame] | 752 | test like :: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 753 | |
| 754 | >>> foo() |
| 755 | {"Hermione": "hippogryph", "Harry": "broomstick"} |
| 756 | |
| 757 | is vulnerable! One workaround is to do :: |
| 758 | |
| 759 | >>> foo() == {"Hermione": "hippogryph", "Harry": "broomstick"} |
| 760 | True |
| 761 | |
| 762 | instead. Another is to do :: |
| 763 | |
Ezio Melotti | 8f7649e | 2009-09-13 04:48:45 +0000 | [diff] [blame] | 764 | >>> d = sorted(foo().items()) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 765 | >>> d |
| 766 | [('Harry', 'broomstick'), ('Hermione', 'hippogryph')] |
| 767 | |
| 768 | There are others, but you get the idea. |
| 769 | |
| 770 | Another bad idea is to print things that embed an object address, like :: |
| 771 | |
| 772 | >>> id(1.0) # certain to fail some of the time |
| 773 | 7948648 |
| 774 | >>> class C: pass |
| 775 | >>> C() # the default repr() for instances embeds an address |
| 776 | <__main__.C instance at 0x00AC18F0> |
| 777 | |
Georg Brandl | 23a87de | 2012-10-10 16:56:15 +0200 | [diff] [blame] | 778 | The :const:`ELLIPSIS` directive gives a nice approach for the last example:: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 779 | |
| 780 | >>> C() #doctest: +ELLIPSIS |
| 781 | <__main__.C instance at 0x...> |
| 782 | |
| 783 | Floating-point numbers are also subject to small output variations across |
| 784 | platforms, because Python defers to the platform C library for float formatting, |
| 785 | and C libraries vary widely in quality here. :: |
| 786 | |
| 787 | >>> 1./7 # risky |
| 788 | 0.14285714285714285 |
Georg Brandl | 6911e3c | 2007-09-04 07:15:32 +0000 | [diff] [blame] | 789 | >>> print(1./7) # safer |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 790 | 0.142857142857 |
Georg Brandl | 6911e3c | 2007-09-04 07:15:32 +0000 | [diff] [blame] | 791 | >>> print(round(1./7, 6)) # much safer |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 792 | 0.142857 |
| 793 | |
| 794 | Numbers of the form ``I/2.**J`` are safe across all platforms, and I often |
| 795 | contrive doctest examples to produce numbers of that form:: |
| 796 | |
| 797 | >>> 3./4 # utterly safe |
| 798 | 0.75 |
| 799 | |
| 800 | Simple fractions are also easier for people to understand, and that makes for |
| 801 | better documentation. |
| 802 | |
| 803 | |
| 804 | .. _doctest-basic-api: |
| 805 | |
| 806 | Basic API |
| 807 | --------- |
| 808 | |
| 809 | The functions :func:`testmod` and :func:`testfile` provide a simple interface to |
| 810 | doctest that should be sufficient for most basic uses. For a less formal |
| 811 | introduction to these two functions, see sections :ref:`doctest-simple-testmod` |
| 812 | and :ref:`doctest-simple-testfile`. |
| 813 | |
| 814 | |
Georg Brandl | c2a4f4f | 2009-04-10 09:03:43 +0000 | [diff] [blame] | 815 | .. function:: testfile(filename, module_relative=True, name=None, package=None, globs=None, verbose=None, report=True, optionflags=0, extraglobs=None, raise_on_error=False, parser=DocTestParser(), encoding=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 816 | |
| 817 | All arguments except *filename* are optional, and should be specified in keyword |
| 818 | form. |
| 819 | |
| 820 | Test examples in the file named *filename*. Return ``(failure_count, |
| 821 | test_count)``. |
| 822 | |
| 823 | Optional argument *module_relative* specifies how the filename should be |
| 824 | interpreted: |
| 825 | |
| 826 | * If *module_relative* is ``True`` (the default), then *filename* specifies an |
| 827 | OS-independent module-relative path. By default, this path is relative to the |
| 828 | calling module's directory; but if the *package* argument is specified, then it |
| 829 | is relative to that package. To ensure OS-independence, *filename* should use |
| 830 | ``/`` characters to separate path segments, and may not be an absolute path |
| 831 | (i.e., it may not begin with ``/``). |
| 832 | |
| 833 | * If *module_relative* is ``False``, then *filename* specifies an OS-specific |
| 834 | path. The path may be absolute or relative; relative paths are resolved with |
| 835 | respect to the current working directory. |
| 836 | |
| 837 | Optional argument *name* gives the name of the test; by default, or if ``None``, |
| 838 | ``os.path.basename(filename)`` is used. |
| 839 | |
| 840 | Optional argument *package* is a Python package or the name of a Python package |
| 841 | whose directory should be used as the base directory for a module-relative |
| 842 | filename. If no package is specified, then the calling module's directory is |
| 843 | used as the base directory for module-relative filenames. It is an error to |
| 844 | specify *package* if *module_relative* is ``False``. |
| 845 | |
| 846 | Optional argument *globs* gives a dict to be used as the globals when executing |
| 847 | examples. A new shallow copy of this dict is created for the doctest, so its |
| 848 | examples start with a clean slate. By default, or if ``None``, a new empty dict |
| 849 | is used. |
| 850 | |
| 851 | Optional argument *extraglobs* gives a dict merged into the globals used to |
| 852 | execute examples. This works like :meth:`dict.update`: if *globs* and |
| 853 | *extraglobs* have a common key, the associated value in *extraglobs* appears in |
| 854 | the combined dict. By default, or if ``None``, no extra globals are used. This |
| 855 | is an advanced feature that allows parameterization of doctests. For example, a |
| 856 | doctest can be written for a base class, using a generic name for the class, |
| 857 | then reused to test any number of subclasses by passing an *extraglobs* dict |
| 858 | mapping the generic name to the subclass to be tested. |
| 859 | |
| 860 | Optional argument *verbose* prints lots of stuff if true, and prints only |
| 861 | failures if false; by default, or if ``None``, it's true if and only if ``'-v'`` |
| 862 | is in ``sys.argv``. |
| 863 | |
| 864 | Optional argument *report* prints a summary at the end when true, else prints |
| 865 | nothing at the end. In verbose mode, the summary is detailed, else the summary |
| 866 | is very brief (in fact, empty if all tests passed). |
| 867 | |
Georg Brandl | 7fa4a8f | 2014-10-06 16:56:43 +0200 | [diff] [blame] | 868 | Optional argument *optionflags* (default value 0) takes the bitwise-or of |
| 869 | option flags. See section :ref:`doctest-options`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 870 | |
| 871 | Optional argument *raise_on_error* defaults to false. If true, an exception is |
| 872 | raised upon the first failure or unexpected exception in an example. This |
| 873 | allows failures to be post-mortem debugged. Default behavior is to continue |
| 874 | running examples. |
| 875 | |
| 876 | Optional argument *parser* specifies a :class:`DocTestParser` (or subclass) that |
| 877 | should be used to extract tests from the files. It defaults to a normal parser |
| 878 | (i.e., ``DocTestParser()``). |
| 879 | |
| 880 | Optional argument *encoding* specifies an encoding that should be used to |
| 881 | convert the file to unicode. |
| 882 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 883 | |
Georg Brandl | c2a4f4f | 2009-04-10 09:03:43 +0000 | [diff] [blame] | 884 | .. function:: testmod(m=None, name=None, globs=None, verbose=None, report=True, optionflags=0, extraglobs=None, raise_on_error=False, exclude_empty=False) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 885 | |
| 886 | All arguments are optional, and all except for *m* should be specified in |
| 887 | keyword form. |
| 888 | |
| 889 | Test examples in docstrings in functions and classes reachable from module *m* |
| 890 | (or module :mod:`__main__` if *m* is not supplied or is ``None``), starting with |
| 891 | ``m.__doc__``. |
| 892 | |
| 893 | Also test examples reachable from dict ``m.__test__``, if it exists and is not |
| 894 | ``None``. ``m.__test__`` maps names (strings) to functions, classes and |
| 895 | strings; function and class docstrings are searched for examples; strings are |
| 896 | searched directly, as if they were docstrings. |
| 897 | |
| 898 | Only docstrings attached to objects belonging to module *m* are searched. |
| 899 | |
| 900 | Return ``(failure_count, test_count)``. |
| 901 | |
| 902 | Optional argument *name* gives the name of the module; by default, or if |
| 903 | ``None``, ``m.__name__`` is used. |
| 904 | |
| 905 | Optional argument *exclude_empty* defaults to false. If true, objects for which |
| 906 | no doctests are found are excluded from consideration. The default is a backward |
| 907 | compatibility hack, so that code still using :meth:`doctest.master.summarize` in |
| 908 | conjunction with :func:`testmod` continues to get output for objects with no |
| 909 | tests. The *exclude_empty* argument to the newer :class:`DocTestFinder` |
| 910 | constructor defaults to true. |
| 911 | |
| 912 | Optional arguments *extraglobs*, *verbose*, *report*, *optionflags*, |
| 913 | *raise_on_error*, and *globs* are the same as for function :func:`testfile` |
| 914 | above, except that *globs* defaults to ``m.__dict__``. |
| 915 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 916 | |
Georg Brandl | c2a4f4f | 2009-04-10 09:03:43 +0000 | [diff] [blame] | 917 | .. function:: run_docstring_examples(f, globs, verbose=False, name="NoName", compileflags=None, optionflags=0) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 918 | |
Ethan Furman | 2a5f9da | 2015-09-17 22:20:41 -0700 | [diff] [blame] | 919 | Test examples associated with object *f*; for example, *f* may be a string, |
| 920 | a module, a function, or a class object. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 921 | |
| 922 | A shallow copy of dictionary argument *globs* is used for the execution context. |
| 923 | |
| 924 | Optional argument *name* is used in failure messages, and defaults to |
| 925 | ``"NoName"``. |
| 926 | |
| 927 | If optional argument *verbose* is true, output is generated even if there are no |
| 928 | failures. By default, output is generated only in case of an example failure. |
| 929 | |
| 930 | Optional argument *compileflags* gives the set of flags that should be used by |
| 931 | the Python compiler when running the examples. By default, or if ``None``, |
| 932 | flags are deduced corresponding to the set of future features found in *globs*. |
| 933 | |
| 934 | Optional argument *optionflags* works as for function :func:`testfile` above. |
| 935 | |
| 936 | |
| 937 | .. _doctest-unittest-api: |
| 938 | |
| 939 | Unittest API |
| 940 | ------------ |
| 941 | |
| 942 | As your collection of doctest'ed modules grows, you'll want a way to run all |
Georg Brandl | 3183585 | 2008-05-12 17:38:56 +0000 | [diff] [blame] | 943 | their doctests systematically. :mod:`doctest` provides two functions that can |
| 944 | be used to create :mod:`unittest` test suites from modules and text files |
Georg Brandl | a851483 | 2010-07-10 12:20:38 +0000 | [diff] [blame] | 945 | containing doctests. To integrate with :mod:`unittest` test discovery, include |
| 946 | a :func:`load_tests` function in your test module:: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 947 | |
| 948 | import unittest |
| 949 | import doctest |
Georg Brandl | a851483 | 2010-07-10 12:20:38 +0000 | [diff] [blame] | 950 | import my_module_with_doctests |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 951 | |
Georg Brandl | a851483 | 2010-07-10 12:20:38 +0000 | [diff] [blame] | 952 | def load_tests(loader, tests, ignore): |
| 953 | tests.addTests(doctest.DocTestSuite(my_module_with_doctests)) |
R. David Murray | 796343b | 2010-12-13 22:50:30 +0000 | [diff] [blame] | 954 | return tests |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 955 | |
| 956 | There are two main functions for creating :class:`unittest.TestSuite` instances |
| 957 | from text files and modules with doctests: |
| 958 | |
| 959 | |
Georg Brandl | c2a4f4f | 2009-04-10 09:03:43 +0000 | [diff] [blame] | 960 | .. function:: DocFileSuite(*paths, module_relative=True, package=None, setUp=None, tearDown=None, globs=None, optionflags=0, parser=DocTestParser(), encoding=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 961 | |
| 962 | Convert doctest tests from one or more text files to a |
| 963 | :class:`unittest.TestSuite`. |
| 964 | |
| 965 | The returned :class:`unittest.TestSuite` is to be run by the unittest framework |
| 966 | and runs the interactive examples in each file. If an example in any file |
| 967 | fails, then the synthesized unit test fails, and a :exc:`failureException` |
| 968 | exception is raised showing the name of the file containing the test and a |
| 969 | (sometimes approximate) line number. |
| 970 | |
| 971 | Pass one or more paths (as strings) to text files to be examined. |
| 972 | |
| 973 | Options may be provided as keyword arguments: |
| 974 | |
| 975 | Optional argument *module_relative* specifies how the filenames in *paths* |
| 976 | should be interpreted: |
| 977 | |
Benjamin Peterson | d23f822 | 2009-04-05 19:13:16 +0000 | [diff] [blame] | 978 | * If *module_relative* is ``True`` (the default), then each filename in |
| 979 | *paths* specifies an OS-independent module-relative path. By default, this |
| 980 | path is relative to the calling module's directory; but if the *package* |
| 981 | argument is specified, then it is relative to that package. To ensure |
| 982 | OS-independence, each filename should use ``/`` characters to separate path |
| 983 | segments, and may not be an absolute path (i.e., it may not begin with |
| 984 | ``/``). |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 985 | |
Benjamin Peterson | d23f822 | 2009-04-05 19:13:16 +0000 | [diff] [blame] | 986 | * If *module_relative* is ``False``, then each filename in *paths* specifies |
| 987 | an OS-specific path. The path may be absolute or relative; relative paths |
| 988 | are resolved with respect to the current working directory. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 989 | |
Benjamin Peterson | d23f822 | 2009-04-05 19:13:16 +0000 | [diff] [blame] | 990 | Optional argument *package* is a Python package or the name of a Python |
| 991 | package whose directory should be used as the base directory for |
| 992 | module-relative filenames in *paths*. If no package is specified, then the |
| 993 | calling module's directory is used as the base directory for module-relative |
| 994 | filenames. It is an error to specify *package* if *module_relative* is |
| 995 | ``False``. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 996 | |
Benjamin Peterson | d23f822 | 2009-04-05 19:13:16 +0000 | [diff] [blame] | 997 | Optional argument *setUp* specifies a set-up function for the test suite. |
| 998 | This is called before running the tests in each file. The *setUp* function |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 999 | will be passed a :class:`DocTest` object. The setUp function can access the |
| 1000 | test globals as the *globs* attribute of the test passed. |
| 1001 | |
Benjamin Peterson | d23f822 | 2009-04-05 19:13:16 +0000 | [diff] [blame] | 1002 | Optional argument *tearDown* specifies a tear-down function for the test |
| 1003 | suite. This is called after running the tests in each file. The *tearDown* |
| 1004 | function will be passed a :class:`DocTest` object. The setUp function can |
| 1005 | access the test globals as the *globs* attribute of the test passed. |
| 1006 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1007 | Optional argument *globs* is a dictionary containing the initial global |
| 1008 | variables for the tests. A new copy of this dictionary is created for each |
| 1009 | test. By default, *globs* is a new empty dictionary. |
| 1010 | |
| 1011 | Optional argument *optionflags* specifies the default doctest options for the |
| 1012 | tests, created by or-ing together individual option flags. See section |
Benjamin Peterson | d23f822 | 2009-04-05 19:13:16 +0000 | [diff] [blame] | 1013 | :ref:`doctest-options`. See function :func:`set_unittest_reportflags` below |
| 1014 | for a better way to set reporting options. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1015 | |
Benjamin Peterson | d23f822 | 2009-04-05 19:13:16 +0000 | [diff] [blame] | 1016 | Optional argument *parser* specifies a :class:`DocTestParser` (or subclass) |
| 1017 | that should be used to extract tests from the files. It defaults to a normal |
| 1018 | parser (i.e., ``DocTestParser()``). |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1019 | |
| 1020 | Optional argument *encoding* specifies an encoding that should be used to |
| 1021 | convert the file to unicode. |
| 1022 | |
Georg Brandl | 55ac8f0 | 2007-09-01 13:51:09 +0000 | [diff] [blame] | 1023 | The global ``__file__`` is added to the globals provided to doctests loaded |
| 1024 | from a text file using :func:`DocFileSuite`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1025 | |
| 1026 | |
Georg Brandl | c2a4f4f | 2009-04-10 09:03:43 +0000 | [diff] [blame] | 1027 | .. function:: DocTestSuite(module=None, globs=None, extraglobs=None, test_finder=None, setUp=None, tearDown=None, checker=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1028 | |
| 1029 | Convert doctest tests for a module to a :class:`unittest.TestSuite`. |
| 1030 | |
| 1031 | The returned :class:`unittest.TestSuite` is to be run by the unittest framework |
| 1032 | and runs each doctest in the module. If any of the doctests fail, then the |
| 1033 | synthesized unit test fails, and a :exc:`failureException` exception is raised |
| 1034 | showing the name of the file containing the test and a (sometimes approximate) |
| 1035 | line number. |
| 1036 | |
| 1037 | Optional argument *module* provides the module to be tested. It can be a module |
| 1038 | object or a (possibly dotted) module name. If not specified, the module calling |
| 1039 | this function is used. |
| 1040 | |
| 1041 | Optional argument *globs* is a dictionary containing the initial global |
| 1042 | variables for the tests. A new copy of this dictionary is created for each |
| 1043 | test. By default, *globs* is a new empty dictionary. |
| 1044 | |
| 1045 | Optional argument *extraglobs* specifies an extra set of global variables, which |
| 1046 | is merged into *globs*. By default, no extra globals are used. |
| 1047 | |
| 1048 | Optional argument *test_finder* is the :class:`DocTestFinder` object (or a |
| 1049 | drop-in replacement) that is used to extract doctests from the module. |
| 1050 | |
| 1051 | Optional arguments *setUp*, *tearDown*, and *optionflags* are the same as for |
| 1052 | function :func:`DocFileSuite` above. |
| 1053 | |
Georg Brandl | 55ac8f0 | 2007-09-01 13:51:09 +0000 | [diff] [blame] | 1054 | This function uses the same search technique as :func:`testmod`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1055 | |
R David Murray | 5abd76a | 2012-09-10 10:15:58 -0400 | [diff] [blame] | 1056 | .. note:: |
| 1057 | Unlike :func:`testmod` and :class:`DocTestFinder`, this function raises |
| 1058 | a :exc:`ValueError` if *module* contains no docstrings. You can prevent |
| 1059 | this error by passing a :class:`DocTestFinder` instance as the |
| 1060 | *test_finder* argument with its *exclude_empty* keyword argument set |
| 1061 | to ``False``:: |
| 1062 | |
| 1063 | >>> finder = doctest.DocTestFinder(exclude_empty=False) |
| 1064 | >>> suite = doctest.DocTestSuite(test_finder=finder) |
| 1065 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1066 | |
| 1067 | Under the covers, :func:`DocTestSuite` creates a :class:`unittest.TestSuite` out |
| 1068 | of :class:`doctest.DocTestCase` instances, and :class:`DocTestCase` is a |
| 1069 | subclass of :class:`unittest.TestCase`. :class:`DocTestCase` isn't documented |
| 1070 | here (it's an internal detail), but studying its code can answer questions about |
| 1071 | the exact details of :mod:`unittest` integration. |
| 1072 | |
| 1073 | Similarly, :func:`DocFileSuite` creates a :class:`unittest.TestSuite` out of |
| 1074 | :class:`doctest.DocFileCase` instances, and :class:`DocFileCase` is a subclass |
| 1075 | of :class:`DocTestCase`. |
| 1076 | |
| 1077 | So both ways of creating a :class:`unittest.TestSuite` run instances of |
| 1078 | :class:`DocTestCase`. This is important for a subtle reason: when you run |
| 1079 | :mod:`doctest` functions yourself, you can control the :mod:`doctest` options in |
| 1080 | use directly, by passing option flags to :mod:`doctest` functions. However, if |
| 1081 | you're writing a :mod:`unittest` framework, :mod:`unittest` ultimately controls |
| 1082 | when and how tests get run. The framework author typically wants to control |
| 1083 | :mod:`doctest` reporting options (perhaps, e.g., specified by command line |
| 1084 | options), but there's no way to pass options through :mod:`unittest` to |
| 1085 | :mod:`doctest` test runners. |
| 1086 | |
| 1087 | For this reason, :mod:`doctest` also supports a notion of :mod:`doctest` |
| 1088 | reporting flags specific to :mod:`unittest` support, via this function: |
| 1089 | |
| 1090 | |
| 1091 | .. function:: set_unittest_reportflags(flags) |
| 1092 | |
| 1093 | Set the :mod:`doctest` reporting flags to use. |
| 1094 | |
Georg Brandl | 7fa4a8f | 2014-10-06 16:56:43 +0200 | [diff] [blame] | 1095 | Argument *flags* takes the bitwise-or of option flags. See section |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1096 | :ref:`doctest-options`. Only "reporting flags" can be used. |
| 1097 | |
| 1098 | This is a module-global setting, and affects all future doctests run by module |
| 1099 | :mod:`unittest`: the :meth:`runTest` method of :class:`DocTestCase` looks at |
| 1100 | the option flags specified for the test case when the :class:`DocTestCase` |
| 1101 | instance was constructed. If no reporting flags were specified (which is the |
| 1102 | typical and expected case), :mod:`doctest`'s :mod:`unittest` reporting flags are |
| 1103 | or'ed into the option flags, and the option flags so augmented are passed to the |
| 1104 | :class:`DocTestRunner` instance created to run the doctest. If any reporting |
| 1105 | flags were specified when the :class:`DocTestCase` instance was constructed, |
| 1106 | :mod:`doctest`'s :mod:`unittest` reporting flags are ignored. |
| 1107 | |
| 1108 | The value of the :mod:`unittest` reporting flags in effect before the function |
| 1109 | was called is returned by the function. |
| 1110 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1111 | |
| 1112 | .. _doctest-advanced-api: |
| 1113 | |
| 1114 | Advanced API |
| 1115 | ------------ |
| 1116 | |
| 1117 | The basic API is a simple wrapper that's intended to make doctest easy to use. |
| 1118 | It is fairly flexible, and should meet most users' needs; however, if you |
| 1119 | require more fine-grained control over testing, or wish to extend doctest's |
| 1120 | capabilities, then you should use the advanced API. |
| 1121 | |
| 1122 | The advanced API revolves around two container classes, which are used to store |
| 1123 | the interactive examples extracted from doctest cases: |
| 1124 | |
Ezio Melotti | 0639d5a | 2009-12-19 23:26:38 +0000 | [diff] [blame] | 1125 | * :class:`Example`: A single Python :term:`statement`, paired with its expected |
Christian Heimes | d8654cf | 2007-12-02 15:22:16 +0000 | [diff] [blame] | 1126 | output. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1127 | |
| 1128 | * :class:`DocTest`: A collection of :class:`Example`\ s, typically extracted |
| 1129 | from a single docstring or text file. |
| 1130 | |
| 1131 | Additional processing classes are defined to find, parse, and run, and check |
| 1132 | doctest examples: |
| 1133 | |
| 1134 | * :class:`DocTestFinder`: Finds all docstrings in a given module, and uses a |
| 1135 | :class:`DocTestParser` to create a :class:`DocTest` from every docstring that |
| 1136 | contains interactive examples. |
| 1137 | |
| 1138 | * :class:`DocTestParser`: Creates a :class:`DocTest` object from a string (such |
| 1139 | as an object's docstring). |
| 1140 | |
| 1141 | * :class:`DocTestRunner`: Executes the examples in a :class:`DocTest`, and uses |
| 1142 | an :class:`OutputChecker` to verify their output. |
| 1143 | |
| 1144 | * :class:`OutputChecker`: Compares the actual output from a doctest example with |
| 1145 | the expected output, and decides whether they match. |
| 1146 | |
| 1147 | The relationships among these processing classes are summarized in the following |
| 1148 | diagram:: |
| 1149 | |
| 1150 | list of: |
| 1151 | +------+ +---------+ |
| 1152 | |module| --DocTestFinder-> | DocTest | --DocTestRunner-> results |
| 1153 | +------+ | ^ +---------+ | ^ (printed) |
| 1154 | | | | Example | | | |
| 1155 | v | | ... | v | |
| 1156 | DocTestParser | Example | OutputChecker |
| 1157 | +---------+ |
| 1158 | |
| 1159 | |
| 1160 | .. _doctest-doctest: |
| 1161 | |
| 1162 | DocTest Objects |
| 1163 | ^^^^^^^^^^^^^^^ |
| 1164 | |
| 1165 | |
| 1166 | .. class:: DocTest(examples, globs, name, filename, lineno, docstring) |
| 1167 | |
| 1168 | A collection of doctest examples that should be run in a single namespace. The |
Senthil Kumaran | a6bac95 | 2011-07-04 11:28:30 -0700 | [diff] [blame] | 1169 | constructor arguments are used to initialize the attributes of the same names. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1170 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1171 | |
Senthil Kumaran | a6bac95 | 2011-07-04 11:28:30 -0700 | [diff] [blame] | 1172 | :class:`DocTest` defines the following attributes. They are initialized by |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1173 | the constructor, and should not be modified directly. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1174 | |
| 1175 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1176 | .. attribute:: examples |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1177 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1178 | A list of :class:`Example` objects encoding the individual interactive Python |
| 1179 | examples that should be run by this test. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1180 | |
| 1181 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1182 | .. attribute:: globs |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1183 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1184 | The namespace (aka globals) that the examples should be run in. This is a |
| 1185 | dictionary mapping names to values. Any changes to the namespace made by the |
| 1186 | examples (such as binding new variables) will be reflected in :attr:`globs` |
| 1187 | after the test is run. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1188 | |
| 1189 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1190 | .. attribute:: name |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1191 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1192 | A string name identifying the :class:`DocTest`. Typically, this is the name |
| 1193 | of the object or file that the test was extracted from. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1194 | |
| 1195 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1196 | .. attribute:: filename |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1197 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1198 | The name of the file that this :class:`DocTest` was extracted from; or |
| 1199 | ``None`` if the filename is unknown, or if the :class:`DocTest` was not |
| 1200 | extracted from a file. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1201 | |
| 1202 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1203 | .. attribute:: lineno |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1204 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1205 | The line number within :attr:`filename` where this :class:`DocTest` begins, or |
| 1206 | ``None`` if the line number is unavailable. This line number is zero-based |
| 1207 | with respect to the beginning of the file. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1208 | |
| 1209 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1210 | .. attribute:: docstring |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1211 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1212 | The string that the test was extracted from, or 'None' if the string is |
| 1213 | unavailable, or if the test was not extracted from a string. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1214 | |
| 1215 | |
| 1216 | .. _doctest-example: |
| 1217 | |
| 1218 | Example Objects |
| 1219 | ^^^^^^^^^^^^^^^ |
| 1220 | |
| 1221 | |
Georg Brandl | c2a4f4f | 2009-04-10 09:03:43 +0000 | [diff] [blame] | 1222 | .. class:: Example(source, want, exc_msg=None, lineno=0, indent=0, options=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1223 | |
| 1224 | A single interactive example, consisting of a Python statement and its expected |
Senthil Kumaran | a6bac95 | 2011-07-04 11:28:30 -0700 | [diff] [blame] | 1225 | output. The constructor arguments are used to initialize the attributes of |
| 1226 | the same names. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1227 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1228 | |
Senthil Kumaran | a6bac95 | 2011-07-04 11:28:30 -0700 | [diff] [blame] | 1229 | :class:`Example` defines the following attributes. They are initialized by |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1230 | the constructor, and should not be modified directly. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1231 | |
| 1232 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1233 | .. attribute:: source |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1234 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1235 | A string containing the example's source code. This source code consists of a |
| 1236 | single Python statement, and always ends with a newline; the constructor adds |
| 1237 | a newline when necessary. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1238 | |
| 1239 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1240 | .. attribute:: want |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1241 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1242 | The expected output from running the example's source code (either from |
| 1243 | stdout, or a traceback in case of exception). :attr:`want` ends with a |
| 1244 | newline unless no output is expected, in which case it's an empty string. The |
| 1245 | constructor adds a newline when necessary. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1246 | |
| 1247 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1248 | .. attribute:: exc_msg |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1249 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1250 | The exception message generated by the example, if the example is expected to |
| 1251 | generate an exception; or ``None`` if it is not expected to generate an |
| 1252 | exception. This exception message is compared against the return value of |
| 1253 | :func:`traceback.format_exception_only`. :attr:`exc_msg` ends with a newline |
| 1254 | unless it's ``None``. The constructor adds a newline if needed. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1255 | |
| 1256 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1257 | .. attribute:: lineno |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1258 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1259 | The line number within the string containing this example where the example |
| 1260 | begins. This line number is zero-based with respect to the beginning of the |
| 1261 | containing string. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1262 | |
| 1263 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1264 | .. attribute:: indent |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1265 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1266 | The example's indentation in the containing string, i.e., the number of space |
| 1267 | characters that precede the example's first prompt. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1268 | |
| 1269 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1270 | .. attribute:: options |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1271 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1272 | A dictionary mapping from option flags to ``True`` or ``False``, which is used |
| 1273 | to override default options for this example. Any option flags not contained |
| 1274 | in this dictionary are left at their default value (as specified by the |
| 1275 | :class:`DocTestRunner`'s :attr:`optionflags`). By default, no options are set. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1276 | |
| 1277 | |
| 1278 | .. _doctest-doctestfinder: |
| 1279 | |
| 1280 | DocTestFinder objects |
| 1281 | ^^^^^^^^^^^^^^^^^^^^^ |
| 1282 | |
| 1283 | |
Georg Brandl | c2a4f4f | 2009-04-10 09:03:43 +0000 | [diff] [blame] | 1284 | .. class:: DocTestFinder(verbose=False, parser=DocTestParser(), recurse=True, exclude_empty=True) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1285 | |
| 1286 | A processing class used to extract the :class:`DocTest`\ s that are relevant to |
| 1287 | a given object, from its docstring and the docstrings of its contained objects. |
Zachary Ware | a4b7a75 | 2013-11-24 01:19:09 -0600 | [diff] [blame] | 1288 | :class:`DocTest`\ s can be extracted from modules, classes, functions, |
| 1289 | methods, staticmethods, classmethods, and properties. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1290 | |
| 1291 | The optional argument *verbose* can be used to display the objects searched by |
| 1292 | the finder. It defaults to ``False`` (no output). |
| 1293 | |
| 1294 | The optional argument *parser* specifies the :class:`DocTestParser` object (or a |
| 1295 | drop-in replacement) that is used to extract doctests from docstrings. |
| 1296 | |
| 1297 | If the optional argument *recurse* is false, then :meth:`DocTestFinder.find` |
| 1298 | will only examine the given object, and not any contained objects. |
| 1299 | |
| 1300 | If the optional argument *exclude_empty* is false, then |
| 1301 | :meth:`DocTestFinder.find` will include tests for objects with empty docstrings. |
| 1302 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1303 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1304 | :class:`DocTestFinder` defines the following method: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1305 | |
| 1306 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1307 | .. method:: find(obj[, name][, module][, globs][, extraglobs]) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1308 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1309 | Return a list of the :class:`DocTest`\ s that are defined by *obj*'s |
| 1310 | docstring, or by any of its contained objects' docstrings. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1311 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1312 | The optional argument *name* specifies the object's name; this name will be |
| 1313 | used to construct names for the returned :class:`DocTest`\ s. If *name* is |
| 1314 | not specified, then ``obj.__name__`` is used. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1315 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1316 | The optional parameter *module* is the module that contains the given object. |
| 1317 | If the module is not specified or is None, then the test finder will attempt |
| 1318 | to automatically determine the correct module. The object's module is used: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1319 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1320 | * As a default namespace, if *globs* is not specified. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1321 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1322 | * To prevent the DocTestFinder from extracting DocTests from objects that are |
| 1323 | imported from other modules. (Contained objects with modules other than |
| 1324 | *module* are ignored.) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1325 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1326 | * To find the name of the file containing the object. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1327 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1328 | * To help find the line number of the object within its file. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1329 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1330 | If *module* is ``False``, no attempt to find the module will be made. This is |
| 1331 | obscure, of use mostly in testing doctest itself: if *module* is ``False``, or |
| 1332 | is ``None`` but cannot be found automatically, then all objects are considered |
| 1333 | to belong to the (non-existent) module, so all contained objects will |
| 1334 | (recursively) be searched for doctests. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1335 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1336 | The globals for each :class:`DocTest` is formed by combining *globs* and |
| 1337 | *extraglobs* (bindings in *extraglobs* override bindings in *globs*). A new |
| 1338 | shallow copy of the globals dictionary is created for each :class:`DocTest`. |
| 1339 | If *globs* is not specified, then it defaults to the module's *__dict__*, if |
| 1340 | specified, or ``{}`` otherwise. If *extraglobs* is not specified, then it |
| 1341 | defaults to ``{}``. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1342 | |
| 1343 | |
| 1344 | .. _doctest-doctestparser: |
| 1345 | |
| 1346 | DocTestParser objects |
| 1347 | ^^^^^^^^^^^^^^^^^^^^^ |
| 1348 | |
| 1349 | |
| 1350 | .. class:: DocTestParser() |
| 1351 | |
| 1352 | A processing class used to extract interactive examples from a string, and use |
| 1353 | them to create a :class:`DocTest` object. |
| 1354 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1355 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1356 | :class:`DocTestParser` defines the following methods: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1357 | |
| 1358 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1359 | .. method:: get_doctest(string, globs, name, filename, lineno) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1360 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1361 | Extract all doctest examples from the given string, and collect them into a |
| 1362 | :class:`DocTest` object. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1363 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1364 | *globs*, *name*, *filename*, and *lineno* are attributes for the new |
| 1365 | :class:`DocTest` object. See the documentation for :class:`DocTest` for more |
| 1366 | information. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1367 | |
| 1368 | |
Georg Brandl | c2a4f4f | 2009-04-10 09:03:43 +0000 | [diff] [blame] | 1369 | .. method:: get_examples(string, name='<string>') |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1370 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1371 | Extract all doctest examples from the given string, and return them as a list |
| 1372 | of :class:`Example` objects. Line numbers are 0-based. The optional argument |
| 1373 | *name* is a name identifying this string, and is only used for error messages. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1374 | |
| 1375 | |
Georg Brandl | c2a4f4f | 2009-04-10 09:03:43 +0000 | [diff] [blame] | 1376 | .. method:: parse(string, name='<string>') |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1377 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1378 | Divide the given string into examples and intervening text, and return them as |
| 1379 | a list of alternating :class:`Example`\ s and strings. Line numbers for the |
| 1380 | :class:`Example`\ s are 0-based. The optional argument *name* is a name |
| 1381 | identifying this string, and is only used for error messages. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1382 | |
| 1383 | |
| 1384 | .. _doctest-doctestrunner: |
| 1385 | |
| 1386 | DocTestRunner objects |
| 1387 | ^^^^^^^^^^^^^^^^^^^^^ |
| 1388 | |
| 1389 | |
Georg Brandl | c2a4f4f | 2009-04-10 09:03:43 +0000 | [diff] [blame] | 1390 | .. class:: DocTestRunner(checker=None, verbose=None, optionflags=0) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1391 | |
| 1392 | A processing class used to execute and verify the interactive examples in a |
| 1393 | :class:`DocTest`. |
| 1394 | |
| 1395 | The comparison between expected outputs and actual outputs is done by an |
| 1396 | :class:`OutputChecker`. This comparison may be customized with a number of |
| 1397 | option flags; see section :ref:`doctest-options` for more information. If the |
| 1398 | option flags are insufficient, then the comparison may also be customized by |
| 1399 | passing a subclass of :class:`OutputChecker` to the constructor. |
| 1400 | |
| 1401 | The test runner's display output can be controlled in two ways. First, an output |
| 1402 | function can be passed to :meth:`TestRunner.run`; this function will be called |
| 1403 | with strings that should be displayed. It defaults to ``sys.stdout.write``. If |
| 1404 | capturing the output is not sufficient, then the display output can be also |
| 1405 | customized by subclassing DocTestRunner, and overriding the methods |
| 1406 | :meth:`report_start`, :meth:`report_success`, |
| 1407 | :meth:`report_unexpected_exception`, and :meth:`report_failure`. |
| 1408 | |
| 1409 | The optional keyword argument *checker* specifies the :class:`OutputChecker` |
| 1410 | object (or drop-in replacement) that should be used to compare the expected |
| 1411 | outputs to the actual outputs of doctest examples. |
| 1412 | |
| 1413 | The optional keyword argument *verbose* controls the :class:`DocTestRunner`'s |
| 1414 | verbosity. If *verbose* is ``True``, then information is printed about each |
| 1415 | example, as it is run. If *verbose* is ``False``, then only failures are |
| 1416 | printed. If *verbose* is unspecified, or ``None``, then verbose output is used |
Éric Araujo | 713d303 | 2010-11-18 16:38:46 +0000 | [diff] [blame] | 1417 | iff the command-line switch ``-v`` is used. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1418 | |
| 1419 | The optional keyword argument *optionflags* can be used to control how the test |
| 1420 | runner compares expected output to actual output, and how it displays failures. |
| 1421 | For more information, see section :ref:`doctest-options`. |
| 1422 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1423 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1424 | :class:`DocTestParser` defines the following methods: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1425 | |
| 1426 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1427 | .. method:: report_start(out, test, example) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1428 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1429 | Report that the test runner is about to process the given example. This method |
| 1430 | is provided to allow subclasses of :class:`DocTestRunner` to customize their |
| 1431 | output; it should not be called directly. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1432 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1433 | *example* is the example about to be processed. *test* is the test |
| 1434 | *containing example*. *out* is the output function that was passed to |
| 1435 | :meth:`DocTestRunner.run`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1436 | |
| 1437 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1438 | .. method:: report_success(out, test, example, got) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1439 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1440 | Report that the given example ran successfully. This method is provided to |
| 1441 | allow subclasses of :class:`DocTestRunner` to customize their output; it |
| 1442 | should not be called directly. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1443 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1444 | *example* is the example about to be processed. *got* is the actual output |
| 1445 | from the example. *test* is the test containing *example*. *out* is the |
| 1446 | output function that was passed to :meth:`DocTestRunner.run`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1447 | |
| 1448 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1449 | .. method:: report_failure(out, test, example, got) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1450 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1451 | Report that the given example failed. This method is provided to allow |
| 1452 | subclasses of :class:`DocTestRunner` to customize their output; it should not |
| 1453 | be called directly. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1454 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1455 | *example* is the example about to be processed. *got* is the actual output |
| 1456 | from the example. *test* is the test containing *example*. *out* is the |
| 1457 | output function that was passed to :meth:`DocTestRunner.run`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1458 | |
| 1459 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1460 | .. method:: report_unexpected_exception(out, test, example, exc_info) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1461 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1462 | Report that the given example raised an unexpected exception. This method is |
| 1463 | provided to allow subclasses of :class:`DocTestRunner` to customize their |
| 1464 | output; it should not be called directly. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1465 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1466 | *example* is the example about to be processed. *exc_info* is a tuple |
| 1467 | containing information about the unexpected exception (as returned by |
| 1468 | :func:`sys.exc_info`). *test* is the test containing *example*. *out* is the |
| 1469 | output function that was passed to :meth:`DocTestRunner.run`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1470 | |
| 1471 | |
Georg Brandl | c2a4f4f | 2009-04-10 09:03:43 +0000 | [diff] [blame] | 1472 | .. method:: run(test, compileflags=None, out=None, clear_globs=True) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1473 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1474 | Run the examples in *test* (a :class:`DocTest` object), and display the |
| 1475 | results using the writer function *out*. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1476 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1477 | The examples are run in the namespace ``test.globs``. If *clear_globs* is |
| 1478 | true (the default), then this namespace will be cleared after the test runs, |
| 1479 | to help with garbage collection. If you would like to examine the namespace |
| 1480 | after the test completes, then use *clear_globs=False*. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1481 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1482 | *compileflags* gives the set of flags that should be used by the Python |
| 1483 | compiler when running the examples. If not specified, then it will default to |
| 1484 | the set of future-import flags that apply to *globs*. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1485 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1486 | The output of each example is checked using the :class:`DocTestRunner`'s |
| 1487 | output checker, and the results are formatted by the |
| 1488 | :meth:`DocTestRunner.report_\*` methods. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1489 | |
| 1490 | |
Georg Brandl | c2a4f4f | 2009-04-10 09:03:43 +0000 | [diff] [blame] | 1491 | .. method:: summarize(verbose=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1492 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1493 | Print a summary of all the test cases that have been run by this DocTestRunner, |
| 1494 | and return a :term:`named tuple` ``TestResults(failed, attempted)``. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1495 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1496 | The optional *verbose* argument controls how detailed the summary is. If the |
| 1497 | verbosity is not specified, then the :class:`DocTestRunner`'s verbosity is |
| 1498 | used. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1499 | |
| 1500 | .. _doctest-outputchecker: |
| 1501 | |
| 1502 | OutputChecker objects |
| 1503 | ^^^^^^^^^^^^^^^^^^^^^ |
| 1504 | |
| 1505 | |
| 1506 | .. class:: OutputChecker() |
| 1507 | |
| 1508 | A class used to check the whether the actual output from a doctest example |
| 1509 | matches the expected output. :class:`OutputChecker` defines two methods: |
| 1510 | :meth:`check_output`, which compares a given pair of outputs, and returns true |
| 1511 | if they match; and :meth:`output_difference`, which returns a string describing |
| 1512 | the differences between two outputs. |
| 1513 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1514 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1515 | :class:`OutputChecker` defines the following methods: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1516 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1517 | .. method:: check_output(want, got, optionflags) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1518 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1519 | Return ``True`` iff the actual output from an example (*got*) matches the |
| 1520 | expected output (*want*). These strings are always considered to match if |
| 1521 | they are identical; but depending on what option flags the test runner is |
| 1522 | using, several non-exact match types are also possible. See section |
| 1523 | :ref:`doctest-options` for more information about option flags. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1524 | |
| 1525 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1526 | .. method:: output_difference(example, got, optionflags) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1527 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1528 | Return a string describing the differences between the expected output for a |
| 1529 | given example (*example*) and the actual output (*got*). *optionflags* is the |
| 1530 | set of option flags used to compare *want* and *got*. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1531 | |
| 1532 | |
| 1533 | .. _doctest-debugging: |
| 1534 | |
| 1535 | Debugging |
| 1536 | --------- |
| 1537 | |
| 1538 | Doctest provides several mechanisms for debugging doctest examples: |
| 1539 | |
| 1540 | * Several functions convert doctests to executable Python programs, which can be |
| 1541 | run under the Python debugger, :mod:`pdb`. |
| 1542 | |
| 1543 | * The :class:`DebugRunner` class is a subclass of :class:`DocTestRunner` that |
| 1544 | raises an exception for the first failing example, containing information about |
| 1545 | that example. This information can be used to perform post-mortem debugging on |
| 1546 | the example. |
| 1547 | |
| 1548 | * The :mod:`unittest` cases generated by :func:`DocTestSuite` support the |
| 1549 | :meth:`debug` method defined by :class:`unittest.TestCase`. |
| 1550 | |
| 1551 | * You can add a call to :func:`pdb.set_trace` in a doctest example, and you'll |
| 1552 | drop into the Python debugger when that line is executed. Then you can inspect |
| 1553 | current values of variables, and so on. For example, suppose :file:`a.py` |
| 1554 | contains just this module docstring:: |
| 1555 | |
| 1556 | """ |
| 1557 | >>> def f(x): |
| 1558 | ... g(x*2) |
| 1559 | >>> def g(x): |
Georg Brandl | 6911e3c | 2007-09-04 07:15:32 +0000 | [diff] [blame] | 1560 | ... print(x+3) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1561 | ... import pdb; pdb.set_trace() |
| 1562 | >>> f(3) |
| 1563 | 9 |
| 1564 | """ |
| 1565 | |
| 1566 | Then an interactive Python session may look like this:: |
| 1567 | |
| 1568 | >>> import a, doctest |
| 1569 | >>> doctest.testmod(a) |
| 1570 | --Return-- |
| 1571 | > <doctest a[1]>(3)g()->None |
| 1572 | -> import pdb; pdb.set_trace() |
| 1573 | (Pdb) list |
| 1574 | 1 def g(x): |
Georg Brandl | 6911e3c | 2007-09-04 07:15:32 +0000 | [diff] [blame] | 1575 | 2 print(x+3) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1576 | 3 -> import pdb; pdb.set_trace() |
| 1577 | [EOF] |
Georg Brandl | 6911e3c | 2007-09-04 07:15:32 +0000 | [diff] [blame] | 1578 | (Pdb) p x |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1579 | 6 |
| 1580 | (Pdb) step |
| 1581 | --Return-- |
| 1582 | > <doctest a[0]>(2)f()->None |
| 1583 | -> g(x*2) |
| 1584 | (Pdb) list |
| 1585 | 1 def f(x): |
| 1586 | 2 -> g(x*2) |
| 1587 | [EOF] |
Georg Brandl | 6911e3c | 2007-09-04 07:15:32 +0000 | [diff] [blame] | 1588 | (Pdb) p x |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1589 | 3 |
| 1590 | (Pdb) step |
| 1591 | --Return-- |
| 1592 | > <doctest a[2]>(1)?()->None |
| 1593 | -> f(3) |
| 1594 | (Pdb) cont |
| 1595 | (0, 3) |
| 1596 | >>> |
| 1597 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1598 | |
| 1599 | Functions that convert doctests to Python code, and possibly run the synthesized |
| 1600 | code under the debugger: |
| 1601 | |
| 1602 | |
| 1603 | .. function:: script_from_examples(s) |
| 1604 | |
| 1605 | Convert text with examples to a script. |
| 1606 | |
| 1607 | Argument *s* is a string containing doctest examples. The string is converted |
| 1608 | to a Python script, where doctest examples in *s* are converted to regular code, |
| 1609 | and everything else is converted to Python comments. The generated script is |
| 1610 | returned as a string. For example, :: |
| 1611 | |
| 1612 | import doctest |
Georg Brandl | 6911e3c | 2007-09-04 07:15:32 +0000 | [diff] [blame] | 1613 | print(doctest.script_from_examples(r""" |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1614 | Set x and y to 1 and 2. |
| 1615 | >>> x, y = 1, 2 |
| 1616 | |
| 1617 | Print their sum: |
Georg Brandl | 6911e3c | 2007-09-04 07:15:32 +0000 | [diff] [blame] | 1618 | >>> print(x+y) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1619 | 3 |
Georg Brandl | 6911e3c | 2007-09-04 07:15:32 +0000 | [diff] [blame] | 1620 | """)) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1621 | |
| 1622 | displays:: |
| 1623 | |
| 1624 | # Set x and y to 1 and 2. |
| 1625 | x, y = 1, 2 |
| 1626 | # |
| 1627 | # Print their sum: |
Georg Brandl | 6911e3c | 2007-09-04 07:15:32 +0000 | [diff] [blame] | 1628 | print(x+y) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1629 | # Expected: |
| 1630 | ## 3 |
| 1631 | |
| 1632 | This function is used internally by other functions (see below), but can also be |
| 1633 | useful when you want to transform an interactive Python session into a Python |
| 1634 | script. |
| 1635 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1636 | |
| 1637 | .. function:: testsource(module, name) |
| 1638 | |
| 1639 | Convert the doctest for an object to a script. |
| 1640 | |
| 1641 | Argument *module* is a module object, or dotted name of a module, containing the |
| 1642 | object whose doctests are of interest. Argument *name* is the name (within the |
| 1643 | module) of the object with the doctests of interest. The result is a string, |
| 1644 | containing the object's docstring converted to a Python script, as described for |
| 1645 | :func:`script_from_examples` above. For example, if module :file:`a.py` |
| 1646 | contains a top-level function :func:`f`, then :: |
| 1647 | |
| 1648 | import a, doctest |
Georg Brandl | 6911e3c | 2007-09-04 07:15:32 +0000 | [diff] [blame] | 1649 | print(doctest.testsource(a, "a.f")) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1650 | |
| 1651 | prints a script version of function :func:`f`'s docstring, with doctests |
| 1652 | converted to code, and the rest placed in comments. |
| 1653 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1654 | |
Georg Brandl | c2a4f4f | 2009-04-10 09:03:43 +0000 | [diff] [blame] | 1655 | .. function:: debug(module, name, pm=False) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1656 | |
| 1657 | Debug the doctests for an object. |
| 1658 | |
| 1659 | The *module* and *name* arguments are the same as for function |
| 1660 | :func:`testsource` above. The synthesized Python script for the named object's |
| 1661 | docstring is written to a temporary file, and then that file is run under the |
| 1662 | control of the Python debugger, :mod:`pdb`. |
| 1663 | |
| 1664 | A shallow copy of ``module.__dict__`` is used for both local and global |
| 1665 | execution context. |
| 1666 | |
| 1667 | Optional argument *pm* controls whether post-mortem debugging is used. If *pm* |
| 1668 | has a true value, the script file is run directly, and the debugger gets |
| 1669 | involved only if the script terminates via raising an unhandled exception. If |
| 1670 | it does, then post-mortem debugging is invoked, via :func:`pdb.post_mortem`, |
| 1671 | passing the traceback object from the unhandled exception. If *pm* is not |
| 1672 | specified, or is false, the script is run under the debugger from the start, via |
| 1673 | passing an appropriate :func:`exec` call to :func:`pdb.run`. |
| 1674 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1675 | |
Georg Brandl | c2a4f4f | 2009-04-10 09:03:43 +0000 | [diff] [blame] | 1676 | .. function:: debug_src(src, pm=False, globs=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1677 | |
| 1678 | Debug the doctests in a string. |
| 1679 | |
| 1680 | This is like function :func:`debug` above, except that a string containing |
| 1681 | doctest examples is specified directly, via the *src* argument. |
| 1682 | |
| 1683 | Optional argument *pm* has the same meaning as in function :func:`debug` above. |
| 1684 | |
| 1685 | Optional argument *globs* gives a dictionary to use as both local and global |
| 1686 | execution context. If not specified, or ``None``, an empty dictionary is used. |
| 1687 | If specified, a shallow copy of the dictionary is used. |
| 1688 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1689 | |
| 1690 | The :class:`DebugRunner` class, and the special exceptions it may raise, are of |
| 1691 | most interest to testing framework authors, and will only be sketched here. See |
| 1692 | the source code, and especially :class:`DebugRunner`'s docstring (which is a |
| 1693 | doctest!) for more details: |
| 1694 | |
| 1695 | |
Georg Brandl | c2a4f4f | 2009-04-10 09:03:43 +0000 | [diff] [blame] | 1696 | .. class:: DebugRunner(checker=None, verbose=None, optionflags=0) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1697 | |
| 1698 | A subclass of :class:`DocTestRunner` that raises an exception as soon as a |
| 1699 | failure is encountered. If an unexpected exception occurs, an |
| 1700 | :exc:`UnexpectedException` exception is raised, containing the test, the |
| 1701 | example, and the original exception. If the output doesn't match, then a |
| 1702 | :exc:`DocTestFailure` exception is raised, containing the test, the example, and |
| 1703 | the actual output. |
| 1704 | |
| 1705 | For information about the constructor parameters and methods, see the |
| 1706 | documentation for :class:`DocTestRunner` in section :ref:`doctest-advanced-api`. |
| 1707 | |
| 1708 | There are two exceptions that may be raised by :class:`DebugRunner` instances: |
| 1709 | |
| 1710 | |
| 1711 | .. exception:: DocTestFailure(test, example, got) |
| 1712 | |
Georg Brandl | 7cb1319 | 2010-08-03 12:06:29 +0000 | [diff] [blame] | 1713 | An exception raised by :class:`DocTestRunner` to signal that a doctest example's |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1714 | actual output did not match its expected output. The constructor arguments are |
Senthil Kumaran | a6bac95 | 2011-07-04 11:28:30 -0700 | [diff] [blame] | 1715 | used to initialize the attributes of the same names. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1716 | |
Senthil Kumaran | a6bac95 | 2011-07-04 11:28:30 -0700 | [diff] [blame] | 1717 | :exc:`DocTestFailure` defines the following attributes: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1718 | |
| 1719 | |
| 1720 | .. attribute:: DocTestFailure.test |
| 1721 | |
| 1722 | The :class:`DocTest` object that was being run when the example failed. |
| 1723 | |
| 1724 | |
| 1725 | .. attribute:: DocTestFailure.example |
| 1726 | |
| 1727 | The :class:`Example` that failed. |
| 1728 | |
| 1729 | |
| 1730 | .. attribute:: DocTestFailure.got |
| 1731 | |
| 1732 | The example's actual output. |
| 1733 | |
| 1734 | |
| 1735 | .. exception:: UnexpectedException(test, example, exc_info) |
| 1736 | |
Georg Brandl | 7cb1319 | 2010-08-03 12:06:29 +0000 | [diff] [blame] | 1737 | An exception raised by :class:`DocTestRunner` to signal that a doctest |
| 1738 | example raised an unexpected exception. The constructor arguments are used |
Senthil Kumaran | a6bac95 | 2011-07-04 11:28:30 -0700 | [diff] [blame] | 1739 | to initialize the attributes of the same names. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1740 | |
Senthil Kumaran | a6bac95 | 2011-07-04 11:28:30 -0700 | [diff] [blame] | 1741 | :exc:`UnexpectedException` defines the following attributes: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1742 | |
| 1743 | |
| 1744 | .. attribute:: UnexpectedException.test |
| 1745 | |
| 1746 | The :class:`DocTest` object that was being run when the example failed. |
| 1747 | |
| 1748 | |
| 1749 | .. attribute:: UnexpectedException.example |
| 1750 | |
| 1751 | The :class:`Example` that failed. |
| 1752 | |
| 1753 | |
| 1754 | .. attribute:: UnexpectedException.exc_info |
| 1755 | |
| 1756 | A tuple containing information about the unexpected exception, as returned by |
| 1757 | :func:`sys.exc_info`. |
| 1758 | |
| 1759 | |
| 1760 | .. _doctest-soapbox: |
| 1761 | |
| 1762 | Soapbox |
| 1763 | ------- |
| 1764 | |
| 1765 | As mentioned in the introduction, :mod:`doctest` has grown to have three primary |
| 1766 | uses: |
| 1767 | |
| 1768 | #. Checking examples in docstrings. |
| 1769 | |
| 1770 | #. Regression testing. |
| 1771 | |
| 1772 | #. Executable documentation / literate testing. |
| 1773 | |
| 1774 | These uses have different requirements, and it is important to distinguish them. |
| 1775 | In particular, filling your docstrings with obscure test cases makes for bad |
| 1776 | documentation. |
| 1777 | |
| 1778 | When writing a docstring, choose docstring examples with care. There's an art to |
| 1779 | this that needs to be learned---it may not be natural at first. Examples should |
| 1780 | add genuine value to the documentation. A good example can often be worth many |
| 1781 | words. If done with care, the examples will be invaluable for your users, and |
| 1782 | will pay back the time it takes to collect them many times over as the years go |
| 1783 | by and things change. I'm still amazed at how often one of my :mod:`doctest` |
| 1784 | examples stops working after a "harmless" change. |
| 1785 | |
| 1786 | Doctest also makes an excellent tool for regression testing, especially if you |
| 1787 | don't skimp on explanatory text. By interleaving prose and examples, it becomes |
| 1788 | much easier to keep track of what's actually being tested, and why. When a test |
| 1789 | fails, good prose can make it much easier to figure out what the problem is, and |
| 1790 | how it should be fixed. It's true that you could write extensive comments in |
| 1791 | code-based testing, but few programmers do. Many have found that using doctest |
| 1792 | approaches instead leads to much clearer tests. Perhaps this is simply because |
| 1793 | doctest makes writing prose a little easier than writing code, while writing |
| 1794 | comments in code is a little harder. I think it goes deeper than just that: |
| 1795 | the natural attitude when writing a doctest-based test is that you want to |
| 1796 | explain the fine points of your software, and illustrate them with examples. |
| 1797 | This in turn naturally leads to test files that start with the simplest |
| 1798 | features, and logically progress to complications and edge cases. A coherent |
| 1799 | narrative is the result, instead of a collection of isolated functions that test |
| 1800 | isolated bits of functionality seemingly at random. It's a different attitude, |
| 1801 | and produces different results, blurring the distinction between testing and |
| 1802 | explaining. |
| 1803 | |
| 1804 | Regression testing is best confined to dedicated objects or files. There are |
| 1805 | several options for organizing tests: |
| 1806 | |
| 1807 | * Write text files containing test cases as interactive examples, and test the |
| 1808 | files using :func:`testfile` or :func:`DocFileSuite`. This is recommended, |
| 1809 | although is easiest to do for new projects, designed from the start to use |
| 1810 | doctest. |
| 1811 | |
| 1812 | * Define functions named ``_regrtest_topic`` that consist of single docstrings, |
| 1813 | containing test cases for the named topics. These functions can be included in |
| 1814 | the same file as the module, or separated out into a separate test file. |
| 1815 | |
| 1816 | * Define a ``__test__`` dictionary mapping from regression test topics to |
| 1817 | docstrings containing test cases. |
| 1818 | |
Ethan Furman | 2a5f9da | 2015-09-17 22:20:41 -0700 | [diff] [blame] | 1819 | When you have placed your tests in a module, the module can itself be the test |
| 1820 | runner. When a test fails, you can arrange for your test runner to re-run only |
| 1821 | the failing doctest while you debug the problem. Here is a minimal example of |
| 1822 | such a test runner:: |
| 1823 | |
| 1824 | if __name__ == '__main__': |
| 1825 | import doctest |
| 1826 | flags = doctest.REPORT_NDIFF|doctest.FAIL_FAST |
| 1827 | if len(sys.argv) > 1: |
| 1828 | name = sys.argv[1] |
| 1829 | if name in globals(): |
| 1830 | obj = globals()[name] |
| 1831 | else: |
| 1832 | obj = __test__[name] |
| 1833 | doctest.run_docstring_examples(obj, globals(), name=name, |
| 1834 | optionflags=flags) |
| 1835 | else: |
| 1836 | fail, total = doctest.testmod(optionflags=flags) |
| 1837 | print("{} failures out of {} tests".format(fail, total)) |
| 1838 | |
| 1839 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1840 | .. rubric:: Footnotes |
| 1841 | |
| 1842 | .. [#] Examples containing both expected output and an exception are not supported. |
| 1843 | Trying to guess where one ends and the other begins is too error-prone, and that |
| 1844 | also makes for a confusing test. |