Like program source code, doctest tests are written in plain text. The doctest module extracts the tests and ignores the rest of the text, which means that the tests can be embedded in human-readable explanations or discussions. This is the feature that makes doctest suitable for uses such as program specifications.
We are going to create a simple doctest file, to show the fundamentals of using the tool. Perform the following steps:
- Open a new text file in your editor, and name it
test.txt. - Insert the following text into the file:
This is a simple doctest that checks some of Python's arithmetic operations. >>> 2 + 2 4 >>> 3 * 3 10
- We can now run the
doctest. At the command prompt, change to the directory where you savedtest.txt. Type the following command:$ python3 ‑m doctest test.txt - When the test is run, you should see output like this:
You just wrote a doctest file that describes a couple of arithmetic operations, and ran it to check whether Python behaved as the tests said it should. You ran the tests by telling Python to execute doctest on the file containing the tests.
In this case, Python's behavior differed from the tests because, according to the tests, three times three equals ten. However, Python disagrees on that. As doctest expected one thing and Python did something different, doctest presented you with a nice little error report showing where to find the failed test, and how the actual result differed from the expected result. At the bottom of the report is a summary showing how many tests failed in each file tested, which is helpful when you have more than one file containing tests.
You might have already figured it out from looking at the previous example: doctest recognizes tests by looking for sections of text that look like they've been copied and pasted from a Python interactive session. Anything that can be expressed in Python is valid within a doctest.
Lines that start with a >>> prompt are sent to a Python interpreter. Lines that start with a ... prompt are sent as continuations of the code from the previous line, allowing you to embed complex block statements into your doctests. Finally, any lines that don't start with >>> or ..., up to the next blank line or >>> prompt, represent the output expected from the statement. The output appears as it would in an interactive Python session, including both the return value and anything printed to the console. If you don't have any output lines, doctest assumes it to mean that the statement is expected to have no visible result on the console, which usually means that it returns None.
The doctest module ignores anything in the file that isn't part of a test, which means that you can put explanatory text, HTML, line-art diagrams, or whatever else strikes your fancy in between your tests. We took advantage of this in the previous doctest to add an explanatory sentence before the test itself.
Add the following code to your test.txt file, separated from the existing code by at least one blank line:
Now we're going to take some more of doctest's syntax for a spin.
>>> import sys
>>> def test_write():
... sys.stdout.write("Hello
")
... return True
>>> test_write()
Hello
TrueNow take a moment to consider before running the test. Will it pass or fail? Should it pass or fail?
Just as we discussed before, run the test using the following command:
python3 -m doctest test.txtYou should see a result like this:
Because we added the new tests to the same file containing the tests from before, we still see the notification that three times three does not equal 10. Now, though, we also see that five tests were run, which means our new tests ran and were successful.
Why five tests? As far as doctest is concerned, we added the following three tests to the file:
- The first one says that, when we
import sys, nothing visible should happen - The second test says that, when we define the
test_writefunction, nothing visible should happen - The third test says that, when we call the
test_writefunction,HelloandTrueshould appear on the console, in that order, on separate lines
Since all three of these tests pass, doctest doesn't bother to say much about them. All it did was increase the number of tests reported at the bottom from two to five.