doctestเป็นโมดูลที่รวมอยู่ใน ไลบรารีมาตรฐานของภาษาโปรแกรม Pythonซึ่งช่วยให้สร้างการทดสอบได้ง่ายโดยอิงจากเอาต์พุตจากเชลล์ตัวแปลภาษา Python มาตรฐาน โดยการคัดลอกและวางลงใน docstrings

Doctest ใช้ประโยชน์จากความสามารถของ Python ต่อไปนี้ อย่างสร้างสรรค์ ^{[ 1 ] [ 2 ]}

• ด็อกสตริง
• เชลล์แบบโต้ตอบของ Python (ทั้งแบบบรรทัดคำสั่งและแอปพลิเคชันที่ไม่ได้ใช้งานซึ่งรวมอยู่ในชุด)
• การตรวจสอบภายในของ Python

เมื่อใช้เชลล์ Python ข้อความแจ้งเตือนหลัก: >>>ตามด้วยคำสั่งใหม่ ข้อความแจ้งเตือนรอง: ...จะใช้เมื่อต้องการต่อคำสั่งในหลายบรรทัด และผลลัพธ์ของการเรียกใช้คำสั่งจะปรากฏในบรรทัดถัดไป บรรทัดว่าง หรือบรรทัดใหม่ที่ขึ้นต้นด้วยข้อความแจ้งเตือนหลัก จะถือเป็นจุดสิ้นสุดของผลลัพธ์จากคำสั่ง

โมดูล doctest จะค้นหาลำดับของข้อความแจ้งเตือนดังกล่าวใน docstring จากนั้นจะเรียกใช้คำสั่งที่แยกออกมาอีกครั้ง และตรวจสอบผลลัพธ์กับผลลัพธ์ของคำสั่งที่ให้ไว้ในตัวอย่างการทดสอบ docstrings

โดยค่าเริ่มต้น เมื่อรัน doctests จะไม่มีการแสดงผลลัพธ์ใดๆ แต่สามารถปรับเปลี่ยนได้โดยใช้ตัวเลือกในตัวรัน doctest นอกจากนี้ doctest ยังได้ถูกรวมเข้ากับโมดูล unit test ของ Python ทำให้สามารถรัน doctests เป็นกรณีทดสอบ unittest มาตรฐานได้ ตัวรันกรณีทดสอบ unittest มีตัวเลือกเพิ่มเติมเมื่อรันการทดสอบ เช่น การรายงานสถิติการทดสอบ เช่น การทดสอบผ่าน และการทดสอบล้มเหลว

แม้ว่า doctest จะไม่อนุญาตให้ฝังโปรแกรม Python ลงในข้อความบรรยาย แต่ก็อนุญาตให้ฝังตัวอย่างที่ตรวจสอบได้ลงใน docstring ซึ่ง docstring สามารถมีข้อความอื่นๆ ได้ จากนั้นสามารถดึง docstring ออกจากไฟล์โปรแกรมเพื่อสร้างเอกสารในรูปแบบอื่นๆ เช่นHTMLหรือ PDF ไฟล์โปรแกรมสามารถประกอบด้วยเอกสาร การทดสอบ และโค้ด รวมถึงการทดสอบที่ตรวจสอบได้ง่ายกับโค้ด สิ่งนี้ช่วยให้โค้ด การทดสอบ และเอกสารพัฒนาไปพร้อมกันได้

Doctest เหมาะอย่างยิ่งสำหรับการแนะนำไลบรารีโดยการสาธิตวิธีการใช้งาน API

จากผลลัพธ์ของตัวแปลภาษาแบบโต้ตอบของ Python ข้อความสามารถผสมผสานกับการทดสอบที่ใช้ไลบรารีเพื่อแสดงผลลัพธ์ที่คาดหวังได้

ตัวอย่างแรกแสดงให้เห็นว่าสามารถแทรกข้อความบรรยายเข้ากับตัวอย่างที่ทดสอบได้ใน docstring ได้อย่างไร ตัวอย่างที่สองแสดงคุณสมบัติเพิ่มเติมของ doctest พร้อมคำอธิบาย ตัวอย่างที่สามตั้งค่าให้รัน doctest ทั้งหมดในไฟล์เมื่อรันไฟล์ แต่เมื่อนำเข้าเป็นโมดูล การทดสอบจะไม่ถูกรัน

def list_to_0_index ( lst ): """วิธีแก้ปัญหาที่ระบุไว้ใน:  https://rgrig.blogspot.com/2005/11/writing-readable-code.html 'กำหนดให้ลิสต์ lst มาให้ สมมติว่าสำหรับแต่ละองค์ประกอบ เราจะหาค่าดัชนี 0 ที่องค์ประกอบนั้นปรากฏเป็น ครั้งแรก ดังนั้นลิสต์ x = [0, 1, 4, 2, 4, 1, 0, 2] จะถูก แปลงเป็น y = [0, 1, 2, 3, 2, 1, 0, 3] สังเกตว่าสำหรับทุกค่า i เราจะได้ x[y[i]] = x[i] สามารถใช้ภาษาโปรแกรมใดก็ได้และรูปแบบ การแสดงข้อมูลใดก็ได้ตามต้องการ' >>> x = [0, 1, 4, 2, 4, 1, 0, 2]  >>> list_to_0_index(x)  [0, 1, 2, 3, 2, 1, 0, 3]  >>>  """คืนค่า[ lst . index ( i ) สำหรับi ในlst ]

====================== เอกสารสาธิต======================นี่เป็นเพียงตัวอย่างข้อความ README ที่สามารถใช้กับฟังก์ชัน doctest.DocFileSuite() จากโมดูล doctest ของ Python ได้โดยปกติแล้ว ไฟล์ README จะอธิบาย API ของโมดูล ดังนี้:>>> a = 1 >>> b = 2 >>> a + b 3โปรดสังเกตว่า เราเพิ่งสาธิตวิธีการบวกเลขสองจำนวนใน Python และผลลัพธ์จะมีลักษณะอย่างไรตัวเลือกพิเศษนี้ช่วยให้คุณสามารถระบุตัวอย่างได้อย่างไม่ชัดเจนนัก:>>> o = object () >>> o # doctest: +ELLIPSIS <object object at 0x...>การทดสอบข้อยกเว้นก็ทำได้ดีมากเช่นกัน:>>> x Traceback (most recent call last): ... NameError : name 'x' is not defined

ตัวอย่างนี้ยังจำลองการป้อนข้อมูลเข้าฟังก์ชันจากไฟล์โดยใช้โมดูล StringIO ของ Python ด้วย

def unique_words ( page ): """คืนค่าชุดคำที่ไม่ซ้ำกันในรายการบรรทัดของข้อความ" ตัวอย่าง: >>> from StringIO import StringIO  >>> fileText = '''แมวนั่งบนพรม ... พรมอยู่บนตัวแมว ... ปลาหนึ่งตัว ปลาสองตัว ปลาสีแดง ... ปลาสีฟ้า ... ปลาตัวนี้มีรถสีเหลือง ... ปลาตัวนี้มีดาวสีเหลือง'''  >>> file = StringIO(fileText)  >>> page = file.readlines()  >>> words = unique_words(page)  >>> print sorted(list(words))  ["This", "a", "blue", "car", "cat", "fish", "has", "mat",  "on", "ondur", "one", "red", "sat", "star", "the", "two",  "was", "yellow"]  >>>  """ return set ( word for line in page for word in line . split ())def _test (): import doctest doctest . testmod ()ถ้า__name__ == "__main__" : _test ()

ทั้งรูปแบบ EpyText ของ Epydoc และ รูปแบบ reStructuredText ของ Docutils รองรับการทำเครื่องหมายส่วน doctest ภายใน docstring

ใน C++ เฟรมเวิร์ก doctest เป็นการนำแนวคิดนี้ไปใช้ที่ใกล้เคียงที่สุด – สามารถเขียนการทดสอบลงในโค้ดการผลิตได้โดยตรงด้วยโอเวอร์เฮดน้อยที่สุด และมีตัวเลือกในการลบการทดสอบออกจากไบนารี^{[ 3 ]}

ไลบรารี ExUnit.DocTest Elixirใช้งานฟังก์ชันที่คล้ายกับ Doctest ^{[ 4 ]}

การนำ Doctest มาใช้กับHaskell ^{[ 5 ]}

^{การ เขียน}การทดสอบเอกสารในElm ^{[ 6} ]

^{การเขียนการ ทดสอบ}เอกสารในRust [ ^{7 ]}

^{การเขียนการ ทดสอบ}เอกสารในElixir ^{[ 8} ]

byexample^{[ 9 ]}รองรับการเขียน doctest สำหรับภาษาโปรแกรมยอดนิยมหลายภาษา (เช่น Python, Ruby, Shell,JavaScript, C/C++, Java, Go, Rust) ภายในMarkdown,reStructuredTextและเอกสารข้อความอื่นๆ

• doctest - ทดสอบตัวอย่าง Python แบบโต้ตอบ