doctest trong Python: viết test ngay trong docstring
Bài 5/10 · Chương 16
Code sạch, kiểm thử và gỡ lỗi
- 8 phút
- Trung cấp
- Python 3.14
- Cập nhật
Trong bài này · 11
doctest trong Python là module có sẵn chạy các ví dụ viết trong docstring của hàm, rồi so kết quả thật với kết quả ghi bên dưới mỗi ví dụ. Bạn cần nó khi muốn ví dụ trong tài liệu của hàm không bao giờ sai lệch với code, và muốn kiểm một hàm nhỏ mà không phải viết cả một class test.
Cần biết trước: REPL, docstring và unittest.
Viết ví dụ trong docstring
Một ví dụ của doctest trông như một đoạn gõ trong REPL: dòng mở bằng >>> (ba dấu lớn hơn và một dấu cách) là lệnh, dòng ngay bên dưới là kết quả mong đợi. Trên trang này, doctest.run_docstring_examples() chạy các ví dụ của một hàm, verbose=True in từng bước:
import doctest
def phi_giao(tong_don):
"""Tính phí giao hàng theo tổng đơn.
>>> phi_giao(300000)
0
>>> phi_giao(299000)
30000
"""
return 0 if tong_don >= 300000 else 30000
doctest.run_docstring_examples(phi_giao, globals(), verbose=True,
name="phi_giao")KẾT QUẢ
Finding tests in phi_giao
Trying:
phi_giao(300000)
Expecting:
0
ok
Trying:
phi_giao(299000)
Expecting:
30000
okMỗi ví dụ là một lần thử (Trying): doctest chạy lệnh, lấy cái REPL sẽ hiện, so với dòng mong đợi (Expecting), rồi in ok khi khớp. Tham số globals() cho doctest biết các tên đang có, để ví dụ gọi được phi_giao. Đổi >= 300000 thành > 300000 rồi chạy lại: doctest in Failed example: cùng hai dòng Expected: và Got:.
Trên trang này doctest.testmod() không tìm thấy hàm của khối code, nên các ví dụ dùng run_docstring_examples(). Trên máy, testmod() chạy được, như ở mục cuối.
Kết quả mong đợi ghi đúng như REPL hiện
doctest so từng ký tự, nên kết quả phải ghi đúng như REPL hiện: chuỗi có dấu nháy đơn, số thực có .0. Một ví dụ có thể có vài dòng >>>: dòng gán không hiện gì nên không cần kết quả bên dưới.
import doctest
def mon_re_nhat(bang_gia):
"""Trả về tên món có giá thấp nhất.
>>> gia = {"bạc xỉu": 32000, "cà phê sữa": 29000}
>>> mon_re_nhat(gia)
'cà phê sữa'
"""
return min(bang_gia, key=bang_gia.get)
doctest.run_docstring_examples(mon_re_nhat, globals(),
verbose=True, name="mon_re_nhat")KẾT QUẢ
Finding tests in mon_re_nhat
Trying:
gia = {"bạc xỉu": 32000, "cà phê sữa": 29000}
Expecting nothing
ok
Trying:
mon_re_nhat(gia)
Expecting:
'cà phê sữa'
okĐổi 'cà phê sữa' thành cà phê sữa rồi chạy lại: doctest in Got:, vì REPL hiện chuỗi kèm dấu nháy mà dòng mong đợi thì không.
Một hàm báo lỗi cũng kiểm được. Dòng mong đợi mở bằng Traceback (most recent call last):, rồi tới dòng cuối của traceback. doctest bỏ qua các dòng ở giữa:
import doctest
def phi_giao(tong_don):
"""
>>> phi_giao(-1)
Traceback (most recent call last):
ValueError: tổng đơn không được âm
"""
if tong_don < 0:
raise ValueError("tổng đơn không được âm")
return 0 if tong_don >= 300000 else 30000
doctest.run_docstring_examples(phi_giao, globals(), verbose=True,
name="phi_giao")KẾT QUẢ
Finding tests in phi_giao
Trying:
phi_giao(-1)
Expecting:
Traceback (most recent call last):
ValueError: tổng đơn không được âm
okDocstring đã đứng đúng chỗ thì chỉ còn lời gọi run_docstring_examples(). Hàm này không tự biết các tên mà ví dụ dùng tới, nên bạn phải đưa chúng vào.
Chạy doctest trên máy
Trên máy, lưu hàm vào file phi_giao.py. Hai dòng cuối cho python3 phi_giao.py chạy các ví dụ trong file bằng doctest.testmod():
def phi_giao(tong_don):
"""Tính phí giao hàng theo tổng đơn.
>>> phi_giao(300000)
0
>>> phi_giao(299000)
30000
"""
if tong_don >= 300000:
return 0
return 30000
if __name__ == "__main__":
import doctest
doctest.testmod()
Khi các ví dụ đều đúng, python3 phi_giao.py không in gì. Muốn xem từng bước, dùng lệnh python -m doctest -v (Windows gõ python, macOS/Linux gõ python3); lệnh này không cần hai dòng cuối. Một lần chạy thật bằng Python 3.14, ngày 15/11/2026:
python3 -m doctest -v phi_giao.pyKẾT QUẢ
Trying:
phi_giao(300000)
Expecting:
0
ok
Trying:
phi_giao(299000)
Expecting:
30000
ok
1 item had no tests:
phi_giao
1 item passed all tests:
2 tests in phi_giao.phi_giao
2 tests in 2 items.
2 passed.
Test passed.Mục phi_giao "no tests" là chính module, vì đầu file không có docstring. Python 3.12 viết 1 items và 2 passed and 0 failed., còn lại giống hệt. Đổi >= thành > rồi chạy lại không có -v: doctest chỉ in ví dụ sai, kèm file và số dòng (đường dẫn trên máy bạn khác):
python3 -m doctest phi_giao.pyKẾT QUẢ
**********************************************************************
File "/home/hocvien/hoc-python/phi_giao.py", line 4, in phi_giao.phi_giao
Failed example:
phi_giao(300000)
Expected:
0
Got:
30000
**********************************************************************
1 item had failures:
1 of 2 in phi_giao.phi_giao
***Test Failed*** 1 failure.Python 3.12 viết 1 items had failures: và ***Test Failed*** 1 failures., còn lại giống hệt.
Kiểm tra nhanh
Sau dòng
ten = "bạc xỉu", lệnhprint(repr(ten))in ra gì?bạc xỉu'bạc xỉu'"bạc xỉu"
Trong khung bẫy đặt chuỗi sau dòng
tong_don = int(tong_don), doctest chạy mấy ví dụ?- Không ví dụ nào, vì hàm không có docstring
- Một ví dụ, và báo sai vì mong đợi
30000 - Một ví dụ, và báo
ok
Những cách ghi nào doctest đọc đúng là một ví dụ kèm kết quả mong đợi?
- Dòng
>>> phi_giao(0), ngay dưới là dòng30000 - Dòng
>>>phi_giao(0), ngay dưới là dòng30000 - Dòng
>>> phi_giao(-1), rồiTraceback (most recent call last):và dòng lỗi cuối - Dòng
>>> gia = 29000không có dòng kết quả nào bên dưới
- Dòng
Trong khung bẫy thứ hai, lệnh
doctest.run_docstring_examples(phi_giao)cho kết quả gì?- Chạy các ví dụ trong docstring và báo
ok - Không chạy ví dụ nào và không in gì
- Báo lỗi
TypeErrorvì thiếu tham sốglobs
- Chạy các ví dụ trong docstring và báo
Bài tập
Viết ví dụ doctest cho hàm giá sau giảm
Viết thân hàm gia_sau_giam(gia, phan_tram): trả về giá sau khi giảm phan_tram phần trăm, phần giảm làm tròn xuống tới đồng (gia * phan_tram // 100). Trong docstring, viết ít nhất ba ví dụ >>> kèm kết quả đúng, trong đó có một đơn giảm 10% và một đơn có phần giảm lẻ đồng như gia_sau_giam(29999, 15). Cuối code, chạy các ví dụ bằng doctest.run_docstring_examples(gia_sau_giam, globals()): không dòng nào in ra là mọi ví dụ đúng. Phần chấm còn chạy các ví dụ của bạn với vài bản viết sai của hàm (chia bằng /, làm tròn bằng round(), quên giảm): mỗi bản sai phải làm ít nhất một ví dụ sai.
Ví dụ: gia_sau_giam(100000, 10) trả về 90000.
Trả về: giá sau giảm, một int.
import doctest
def gia_sau_giam(gia, phan_tram):
"""Giá sau khi giảm phan_tram %, làm tròn xuống tới đồng.
"""
pass
# Chạy các ví dụ của gia_sau_giam ở đâyTóm tắt
doctest chạy các dòng
>>>trong docstring và so kết quả với dòng ngay bên dưới.Kết quả mong đợi ghi đúng như REPL hiện: chuỗi có nháy đơn, dòng gán không có kết quả.
Hàm báo lỗi: ghi
Traceback (most recent call last):rồi dòng lỗi cuối.Docstring phải là dòng đầu thân hàm; nếu không, doctest không có ví dụ nào để chạy.
Trên trang này dùng
doctest.run_docstring_examples(ham, globals(), verbose=True).Trên máy:
python -m doctest -v file.py, hoặcdoctest.testmod()trong khốiif __name__ == "__main__":.
Câu hỏi thường gặp
Khi nào nên viết test bằng doctest?
doctest hợp cho vài ví dụ ngắn vừa là tài liệu vừa là test: người đọc docstring thấy ngay cách gọi hàm. unittest hợp cho bộ test dài, cần chuẩn bị dữ liệu bằng setUp hay kiểm nhiều trường hợp biên. Nhiều dự án dùng cả hai: doctest cho ví dụ trong tài liệu, unittest cho phần kiểm kỹ.
Kết quả là dict hay số thực dài thì viết doctest thế nào?
Ghi đúng như REPL hiện. Dict giữ thứ tự thêm khóa, nên kết quả ổn định. Số thực như 0.1 + 0.2 hiện 0.30000000000000004, nên ví dụ gọn hơn khi làm tròn trước, như >>> round(0.1 + 0.2, 2) với kết quả 0.3.
Doctest có chạy được ví dụ trong file Markdown hay file văn bản không?
Có: python -m doctest -v huong_dan.txt chạy các dòng >>> trong một file văn bản như với docstring. Cách này giúp các ví dụ trong tài liệu hướng dẫn của dự án chạy đúng sau mỗi lần sửa code.
Vì sao doctest báo sai dù kết quả trông giống hệt?
Thường do dấu cách thừa ở cuối dòng kết quả, hay kiểu nháy khác nhau ("a" so với 'a'). doctest so từng ký tự, nên đọc kỹ hai dòng Expected: và Got: để thấy chỗ lệch.
Chủ đề
Bài này có hữu ích?
Hỏi đáp
Tham vấn chuyên môn
Nhà sáng lập AIDev và VietPlatform · Thạc sĩ AI MSE
- Tốt nghiệp thủ khoa xuất sắc Thạc sĩ AI MSE.
- Đồng sáng lập, CTO E-University, SVOnline: số hóa 10+ đại học, 40.000+ sinh viên.
- Xây hệ thống AI cho doanh nghiệp tại VietPlatform.