No problem, provided that the traceback is the only output produced by the example: just paste in the traceback. Since tracebacks contain details that are likely to change rapidly (for example, exact file paths and line numbers), this is one case where doctest works hard to be flexible in what it accepts.
>>> [1, 2, 3].remove(42) Traceback (most recent call last): File "<stdin>", line 1, in ? ValueError: list.remove(x): x not in list
That doctest succeeds if ValueError is raised, with the "list.remove(x): x not in list" detail as shown.
The expected output for an exception must start with a traceback header, which may be either of the following two lines, indented the same as the first line of the example:
Traceback (most recent call last): Traceback (innermost last):
The traceback header is followed by an optional traceback stack, whose contents are ignored by doctest. The traceback stack is typically omitted, or copied verbatim from an interactive session.
The traceback stack is followed by the most interesting part: the line(s) containing the exception type and detail. This is usually the last line of a traceback, but can extend across multiple lines if the exception has a multi-line detail:
>>> raise ValueError('multi\n line\ndetail') Traceback (most recent call last): File "<stdin>", line 1, in ? ValueError: multi line detail
The last three lines (starting with ValueError) are compared against the exception's type and detail, and the rest are ignored.
Best practice is to omit the traceback stack, unless it adds significant documentation value to the example. So the last example is probably better as:
>>> raise ValueError('multi\n line\ndetail') Traceback (most recent call last): ... ValueError: multi line detail
Note that tracebacks are treated very specially. In particular, in the rewritten example, the use of "..." is independent of doctest's ELLIPSIS option. The ellipsis in that example could be left out, or could just as well be three (or three hundred) commas or digits, or an indented transcript of a Monty Python skit.
Some details you should read once, but won't need to remember:
>>> 1 1 File "<stdin>", line 1 1 1 ^ SyntaxError: invalid syntax
Since the lines showing the position of the error come before the
exception type and detail, they are not checked by doctest. For
example, the following test would pass, even though it puts the
^ marker in the wrong location:
>>> 1 1 Traceback (most recent call last): File "<stdin>", line 1 1 1 ^ SyntaxError: invalid syntax
Changed in version 2.4: The ability to handle a multi-line exception detail, and the IGNORE_EXCEPTION_DETAIL doctest option, were added.
See About this document... for information on suggesting changes.