How to use the doctest module for document testing in Python 3.x

How to use the doctest module for document testing in Python 3.x

Introduction:
In the process of writing code, it is often necessary to write documents to explain the usage and expected output of functions or classes. However, documentation can easily become outdated or inaccurate, which can lead to unexpected or erroneous results. To solve this problem, Python provides a built-in module doctest, which allows you to write example code in a docstring and check whether it meets the expected results when executed.

1. Introduction to the doctest module
The doctest module is a built-in module of Python that provides a simple and reliable way to test code examples. It does this by executing the sample code given in the docstring and verifying that its output matches the expected output. doctest combines writing documentation and writing tests into one, making tests easier to maintain.

2. How to write a doctest
When writing a doctest, we need to write sample code in the documentation string of the module, function or method, and use >>&gt after the expected result ; tags to indicate sample code and expected output. For example, the following example:

def add(a, b):
    """
    计算两个数的和
    
    示例：
    >>> add(2, 3)
    5
    
    >>> add(10, 5)
    15
    """
    return a + b

3. How to execute doctest
We can use the testmod() function provided by the doctest module to execute doctest. This function will automatically find the docstring in the module and execute the sample code there, then compare it with the expected output.

import doctest

doctest.testmod()

4. Running results
After executing doctest, if the output of all sample codes matches the expected output, the output will be empty; if the output of any sample code does not match the expected output, an error will be printed. information.

The following is the result of running the sample code:

**********************************************************************
File "example.py", line 5, in __main__.add
Failed example:
    add(2, 3)
Expected:
    5
Got:
    6
**********************************************************************
File "example.py", line 9, in __main__.add
Failed example:
    add(10, 5)
Expected:
    15
Got:
    16
**********************************************************************
1 items had failures:
   2 of   2 in __main__.add
***Test Failed*** 2 failures.

In this example, we can see that there are two test cases (add(2, 3) and# The result of ##add(10, 5)) does not match the expected output, so doctest reports two failures.

5. How to extend doctest

In addition to simple sample code and expected output, doctest also supports more advanced testing methods. For example, we can use
... to represent multi-line output, and # to represent comments, etc. Here is a more complex example:

def average(numbers):
    """
    计算列表中数字的平均值
    
    示例：
    >>> average([1, 2, 3, 4, 5])
    3
    
    >>> average([10, 20, 30])
    20
    
    >>> average([])
    0
    
    >>> average([1, 2, 3, 4, 5, ...])
    3
    """
    if len(numbers) == 0:
        return 0
    return sum(numbers) / len(numbers)

This example uses

... to represent multi-line output, in the last example we use ... to indicate that there are more elements following the list, but it doesn't care what they are.

6. Conclusion

This article introduces how to use the doctest module for document testing in Python 3.x. It can help us write clear and accurate documents and verify the correctness of the documents through automated testing. By writing test cases, we can better understand how a function or class is used and ensure that they work as expected.

Through reasonable use of the doctest module, code quality and maintainability can be greatly improved. It is recommended that when writing code, you write docstrings for functions and classes and write test cases within them. This will help keep your code sound and provide useful example code for others to read when reading the documentation.

The above is the detailed content of How to use the doctest module for document testing in Python 3.x. For more information, please follow other related articles on the PHP Chinese website!