## 使用 doctest 的背景

doctest 正是利用这个过程进行代码测试的工作。所以要体会到 doctest 的先进性，首先，必须明确你的代码设计过程是符合上述流程的。当然上述流程是绝大多数程序员喜欢的过程，也是绝大多数场景下推荐的(肯定存在特例，比如你的主要工作是接手别人的代码，ORZ)。既然我们在设计每个程序模块的时候都会规定好输入和输出，何不用这些规定来做程序测试？甚至进一步，这些测试能不能用来展示程序的用法呢？

# doctest

The doctest module searches for pieces of text that look like interactive Python sessions, and then executes those sessions to verify that they work exactly as shown. There are several common ways to use doctest:

• To check that a module’s docstrings are up-to-date by verifying that all interactive examples still work as documented.
• To perform regression testing by verifying that interactive examples from a test file or a test object work as expected.
• To write tutorial documentation for a package, liberally illustrated with input-output examples. Depending on whether the examples or the expository text are emphasized, this has the flavor of “literate testing” or “executable documentation”.

## 示例

Talk is Cheap, show me the code.

"""
This is the "example" module.

The example module supplies one function, factorial().  For example,

>>> factorial(5)
120
"""

def factorial(n):
"""Return the factorial of n, an exact integer >= 0.

>>> [factorial(n) for n in range(6)]
[1, 1, 2, 6, 24, 120]
>>> factorial(30)
265252859812191058636308480000000
>>> factorial(-1)
Traceback (most recent call last):
...
ValueError: n must be >= 0

Factorials of floats are OK, but the float must be an exact integer:
>>> factorial(30.1)
Traceback (most recent call last):
...
ValueError: n must be exact integer
>>> factorial(30.0)
265252859812191058636308480000000

It must also not be ridiculously large:
>>> factorial(1e100)
Traceback (most recent call last):
...
OverflowError: n too large
"""

import math
if not n >= 0:
raise ValueError("n must be >= 0")
if math.floor(n) != n:
raise ValueError("n must be exact integer")
if n+1 == n:  # catch a value like 1e300
raise OverflowError("n too large")
result = 1
factor = 2
while factor <= n:
result *= factor
factor += 1
return result

if __name__ == "__main__":
import doctest
doctest.testmod()


python example.py


>>>python example.py -v
Trying:
factorial(5)
Expecting:
120
ok
Trying:
[factorial(n) for n in range(6)]
Expecting:
[1, 1, 2, 6, 24, 120]
ok
Trying:
factorial(30)
Expecting:
265252859812191058636308480000000
ok
Trying:
factorial(-1)
Expecting:
Traceback (most recent call last):
...
ValueError: n must be >= 0
ok
Trying:
factorial(30.1)
Expecting:
Traceback (most recent call last):
...
ValueError: n must be exact integer
ok
Trying:
factorial(30.0)
Expecting:
265252859812191058636308480000000
ok
Trying:
factorial(1e100)
Expecting:
Traceback (most recent call last):
...
OverflowError: n too large
ok
2 items passed all tests:
1 tests in __main__
6 tests in __main__.factorial
7 tests in 2 items.
7 passed and 0 failed.
Test passed.


-v表示显示详细信息。最后的总与信息也是非常有用的，可以帮助具体判断。

## 讨论

### 测试文件

The example module
======================

Using factorial
-------------------

This is an example text file in reStructuredText format.  First import
factorial from the example module:

>>> from example import factorial

Now use it:

>>> factorial(6)
120


import doctest
doctest.testfile("example.txt")


testfile()方法可以实现从文件中测试的目的。