Contoh di docstring sebagai test: doctest

Modul doctest mencari potongan teks yang tampak seperti sesi Python interaktif — baris berawalan >>> diikuti keluaran yang diharapkan — lalu menjalankan baris itu dan membandingkan keluarannya. Potongan tersebut ditulis di docstring, yaitu teks berkutip tiga di baris pertama badan fungsi. Hasilnya, contoh pemakaian di dokumentasi sekaligus menjadi test, dan dokumentasi yang sudah tidak cocok dengan kodenya ketahuan sendiri.

def kode_kelas(tingkat, rombel):
    """Kode rombongan belajar, misalnya 7A.

    >>> kode_kelas(7, "a")
    '7A'
    >>> kode_kelas(10, "c")
    '10C'
    """
    return f"{tingkat}{rombel.upper()}"


if __name__ == "__main__":
    import doctest
    doctest.testmod()

Pembandingannya berupa teks, karakter demi karakter, bukan nilai. Yang dibandingkan adalah tampilan yang akan dicetak sesi interaktif: nilai teks muncul bertanda kutip, pecahan muncul dengan semua digitnya, dan spasi di ujung baris ikut dihitung. doctest.testmod() memeriksa semua docstring di berkas yang sedang dijalankan dan diam saja bila semuanya cocok; perintah python -m doctest -v berkas.py menampilkan setiap contoh yang dicoba beserta hasilnya.

Kapan dipakai: untuk dua atau tiga pemanggilan yang memang ingin dibaca orang sebagai penjelasan cara pakai fungsi. Untuk puluhan kasus batas, unittest di modul berikutnya lebih mudah dirawat, karena hasil harapannya berupa nilai yang dibandingkan dengan ==, bukan teks tampilan. Contoh yang harus melempar galat juga bisa ditulis: baris Traceback (most recent call last): lalu baris nama galat dan pesannya.