UnitTest Framework - 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 giúp bạn có thể tìm kiếm các đoạn văn bản trông giống như các 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ư được hiển thị hay không.

Doctest có thể rất hữu ích trong các trường hợp sau:

Để kiểm tra xem các chuỗi tài liệu của mô-đun có được cập nhật hay không bằng cách xác minh rằng tất cả các ví dụ tương tác vẫn hoạt động như được lập tài liệu.
Để thực hiện kiểm tra hồi quy bằng cách xác minh rằng các ví dụ tương tác từ tệp thử nghiệm hoặc đối tượng thử nghiệm hoạt động như mong đợi.
Để viết tài liệu hướng dẫn cho một gói, được minh họa rõ ràng với các ví dụ đầu vào-đầu ra

Trong Python, 'docstring' là một chuỗi ký tự xuất hiện dưới dạng biểu thức đầu tiên trong một lớp, hàm hoặc mô-đun. Nó bị bỏ qua khi bộ được thực thi, nhưng nó được trình biên dịch nhận dạng và đưa vào__doc__thuộc tính của lớp, hàm hoặc mô-đun bao quanh. Vì nó có sẵn thông qua xem xét nội tâm, nó là nơi chuẩn tắc cho tài liệu về đối tượng.

Một cách thông thường là đặt cách sử dụng ví dụ của các phần khác nhau của mã Python bên trong chuỗi docstring. Mô-đun học thuyết cho phép xác minh rằng các chuỗi tài liệu này được cập nhật với các bản sửa đổi không liên tục trong mã.

Trong đoạn mã sau, một hàm giai thừa được xác định xen kẽ với việc sử dụng ví dụ. Để xác minh xem cách sử dụng ví dụ có đúng hay không, hãy gọi hàm testmod () trong mô-đun doctest.

"""
This is the "example" module.

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

>>> factorial(5)
120
"""

def factorial(x):
   """Return the factorial of n, an exact integer >= 0.
   >>> factorial(-1)
   Traceback (most recent call last):
      ...
   ValueError: x must be >= 0
   """
   
   if not x >= 0:
      raise ValueError("x must be >= 0")
   f = 1
   for i in range(1,x+1):
      f = f*i
   return f
   
if __name__ == "__main__":
   import doctest
   doctest.testmod()

Nhập và lưu tập lệnh trên dưới dạng FactDocTest.py và cố gắng thực thi tập lệnh này từ dòng lệnh.

Python FactDocTest.py

Không có đầu ra nào được hiển thị trừ khi ví dụ không thành công. Bây giờ, hãy thay đổi dòng lệnh thành sau:

Python FactDocTest.py –v

Bảng điều khiển bây giờ sẽ hiển thị kết quả sau:

C:\Python27>python FactDocTest.py -v
Trying:
   factorial(5)
Expecting:
   120
ok
Trying:
   factorial(-1)
Expecting:
   Traceback (most recent call last):
      ...
   ValueError: x must be >= 0
ok
2 items passed all tests:
   1 tests in __main__
   1 tests in __main__.factorial
2 tests in 2 items.
2 passed and 0 failed.
Test passed.

Mặt khác, nếu mã của hàm thừa kế () không cung cấp kết quả mong đợi trong docstring, kết quả thất bại sẽ được hiển thị. Ví dụ: thay đổi f = 2 thay cho f = 1 trong tập lệnh trên và chạy lại học thuyết. Kết quả sẽ như sau:

Trying:
   factorial(5)
Expecting:
   120
**********************************************************************
File "docfacttest.py", line 6, in __main__
Failed example:
factorial(5)
Expected:
   120
Got:
   240
Trying:
   factorial(-1)
Expecting:
   Traceback (most recent call last):
      ...
   ValueError: x must be >= 0
ok
1 items passed all tests:
   1 tests in __main__.factorial
**********************************************************************
1 items had failures:
   1 of 1 in __main__
2 tests in 2 items.
1 passed and 1 failed.
***Test Failed*** 1 failures.

Doctest: Kiểm tra các ví dụ trong tệp văn bản

Một ứng dụng đơn giản khác của học thuyết là thử nghiệm các ví dụ tương tác trong tệp văn bản. Điều này có thể được thực hiện với hàm testfile ().

Văn bản sau được lưu trữ trong một tệp văn bản có tên 'example.txt'.

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(5)
   120

Nội dung tệp được coi là docstring. Để xác minh các ví dụ trong tệp văn bản, hãy sử dụng hàm testfile () của mô-đun doctest.

def factorial(x):
   if not x >= 0:
      raise ValueError("x must be >= 0")
   f = 1
   for i in range(1,x+1):
      f = f*i
   return f
   
if __name__ == "__main__":
   import doctest
   doctest.testfile("example.txt")

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