Itse1359-1720-doctest  (Page 2/4)

There are at least two different ways to use doctest :

1. You can write the test code in a separate text file and use that file to perform the testing.
2. You can embed the test code in one or more docstrings in a module and cause the test code to be executed each time you execute the module as ascript.

A simple example of each approach will be provided and explained in this module.

Discussion and sample code

An interactive session

Figure 1 shows a simple interactive session run on the Python interactive command line interface.

If you have forgotten what the text in Figure 1 means, see the earlier module titled Itse1359-1010-Getting Started .

An automated interactive session

This first example is provided solely to show how doctest works. It is not intended to be useful otherwise.

The test file named Py1359_1720_01

Listing 1 shows the contents of a test file named Py1359_1720_01.txt .

Note that the contents of the test file mirror the input and the output of the interactive session shown in Figure 1 except that the result of performing the computation was purposely specified incorrectly as 6 instead of 5. (When you create a doctest test file, you must specify the required output as shown in Listing 1 .)

Note that the doctest process is very picky regarding file names. Some file names that are valid for the operating system may not work when using doctest . However, if you restrict your file names to names that would be valid for variables, you should be okay.

Listing 2 shows the contents of a Windows batch file named Py1359_1720_01.bat that I used to perform the test. Although not a requirement, the use of such a batch file makes it convenient to performthe test more than once with a minimal typing effort.

The batch the named Py1359_1720_01

(Some of the text in Listing 2 is peculiar to my machine. You can ignore the text shown in Listing 2 down to the command that begins with the word python .)

The third command that begins with the word python in Listing 2 executes the Python doctest module as a script and passes the name of the test file as a command-lineargument to the module.

According to Python v3.1.5 documentation -- Python Setup and Usage , "When called with -m module-name, the given module is located on the Python module path and executed as a script."

The syntax shown for the python command in Listing 2 is a command line shortcut for calling the testmod() function in the doctest module. (You will see more on this later.)

The output

The execution of the python command in Listing 2 produced the command line output shown in Figure 2 .