Kiểm tra ví dụ Python tương tác (doctest)

Phân phối chuẩn của Python chứa mô-đun doctest. Chức năng của mô-đun này làm cho việc tìm kiếm các đoạn văn bản trông như phiên Python tương tác và thực thi các phiên này để xem chúng có hoạt động chính xác như hiển thị hay không. Các ví dụ này được trích xuất từ các biểu thức docstring trong lớp, mô-đun hoặc hàm. Doctest cũng có thể chạy từ một file văn bản đi kèm.

Trong Python, một "docstring" là một chuỗi chữ thức xuất hiện như biểu thức đầu tiên trong một lớp, hàm hoặc mô-đun. Nó bị bỏ qua khi suite được thực thi, nhưng nó được trình biên dịch nhận ra và đưa vào thuộc tính __doc__ của lớp, hàm hoặc mô-đun bao quanh.

Các docstring thường được dùng để mô tả ví dụ sử dụng của các phần khác nhau của mã Python. Mô-đun doctest cho phép xác minh rằng các docstring này được cập nhật với các sửa đổi ngắt quãng trong mã.

Trong mã sau, một hàm giai thừa được định nghĩa lồng ghép với ví dụ sử dụng. Để xác minh xem ví dụ sử dụng có đúng không, hãy gọi hàm testmod() trong mô-đun doctest.

def add(a, b):
    '''
    >>> add(10, 20)
    30
    >>> add('aaa', 'bbb')
    'aaabbb'
    >>> add('aaa', 20)
    Traceback (most recent call last):
    ...
    TypeError: must be str, not int
    '''
    return a + b

Trước tiên nhập và lưu script trên thành mytest.py và thử thực thi script này từ dòng lệnh.

python mytest.py

Không có đầu ra nào sẽ được hiển thị trừ khi ví dụ thất bại. Bây giờ thay đổi dòng lệnh thành:

python mytest.py -v

Bây giờ console sẽ hiển thị kết quả sau:

F:\Python36>python mytest.py -v
Trying: add(10,20)
Expecting: 30
ok
Trying: add('aaa','bbb')
Expecting: 'aaabbb'
ok
Trying: add('aaa',20)
Expecting: Traceback (most recent call last):
...
TypeError: must be str, not int
ok
1 items had no tests: __main__
1 items passed all tests: 3 tests in __main__.add
3 tests in 2 items. 3 passed and 0 failed.
Test passed.

Kiểm tra ví dụ trong File Văn bản

Một ứng dụng đơn giản khác của doctest là kiểm tra các ví dụ tương tác trong một file văn bản. Điều này có thể thực hiện với hàm testfile().

Văn bản sau được lưu trong file văn bản tên là example.txt:

Using ``add``
-------------------
This is an example text file. First import ``add`` from the ``mytest`` module:
>>> from mytest import add
>>> add(10,20)
30

Nội dung file được coi như docstring. Để xác minh các ví dụ trong file văn bản, dùng hàm testfile() của mô-đun doctest.

def add(a, b):
    return a + b
if __name__ == "__main__":
    import doctest
    doctest.testfile("example.txt")

Giống như testmod(), testfile() sẽ không hiển thị gì trừ khi một ví dụ thất bại. Nếu một ví dụ thất bại, thì ví dụ thất bại đó và nguyên nhân của thất bại được in ra console, dùng cùng định dạng như testmod().
Trong hầu hết các trường hợp, sao chép-dán một phiên console tương tác hoạt động tốt, nhưng doctest không cố gắng làm mô phỏng chính xác của bất kỳ shell Python cụ thể nào.
Bất kỳ đầu ra kỳ vọng nào phải ngay lập tức theo sau dòng cuối cùng >>> hoặc ... chứa mã, và đầu ra kỳ vọng (nếu có) kéo dài đến dòng >>> tiếp theo hoặc dòng toàn khoảng trắng.
Đầu ra kỳ vọng không thể chứa dòng toàn khoảng trắng, vì dòng như vậy được coi là tín hiệu kết thúc đầu ra kỳ vọng. Nếu đầu ra kỳ vọng chứa dòng trống, hãy đặt <BLANKLINE> trong ví dụ doctest ở mỗi nơi dòng trống được kỳ vọng.

Trong bài viết này, các hàm testmod() và testfile() trong mô-đun doctest đã được thảo luận.