Bỏ qua đến nội dung chính
Mục lục

doctest trong Python: viết test ngay trong docstring

AIDev Team · duyệt: Nguyễn Việt Chung

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

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:

python
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
ok

Mỗ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.

python
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:

python
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
ok

Docstring đã đứ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():

python
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:

bash
python3 -m doctest -v phi_giao.py

KẾ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):

bash
python3 -m doctest phi_giao.py

KẾ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

  1. Sau dòng ten = "bạc xỉu", lệnh print(repr(ten)) in ra gì?

    • bạc xỉu
    • 'bạc xỉu'
    • "bạc xỉu"
  2. 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
  3. 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òng 30000
    • Dòng >>>phi_giao(0), ngay dưới là dòng 30000
    • Dòng >>> phi_giao(-1), rồi Traceback (most recent call last): và dòng lỗi cuối
    • Dòng >>> gia = 29000 không có dòng kết quả nào bên dưới
  4. 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 TypeError vì thiếu tham số globs
Đúng hết lần đầu +15 XP

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.

python
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 ở đây

Tó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ặc doctest.testmod() trong khối if __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ủ đề

doctest python

Bài này có hữu ích?

Hỏi đáp

Đang tải câu hỏi…

Tham vấn chuyên môn

Nguyễn Việt Chung

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.
Biên soạn: AIDev Team · Rà soát · Quy trình biên tập