[ ![Python logo](../_static/py.svg) ](https://www.python.org/)

Theme  Auto  Light  Dark

###  [ Table of Contents ](../contents.html)

  * ` doctest  ` â Test interactive Python examples 
    * Simple Usage: Checking Examples in Docstrings 
    * Simple Usage: Checking Examples in a Text File 
    * How It Works 
      * Which Docstrings Are Examined? 
      * How are Docstring Examples Recognized? 
      * Whatâs the Execution Context? 
      * What About Exceptions? 
      * Option Flags 
      * Directives 
      * Warnings 
    * Basic API 
    * Unittest API 
    * Advanced API 
      * DocTest Objects 
      * Example Objects 
      * DocTestFinder objects 
      * DocTestParser objects 
      * DocTestRunner objects 
      * OutputChecker objects 
    * Debugging 
    * Soapbox 

####  Previous topic

[ Python Development Mode ](devmode.html "previous chapter")

####  Next topic

[ ` unittest  ` â Unit testing framework ](unittest.html "next chapter")

###  This Page

  * [ Report a Bug ](../bugs.html)
  * [ Show Source ](https://github.com/python/cpython/blob/main/Doc/library/doctest.rst)

###  Navigation

  * [ index ](../genindex.html "General Index")
  * [ modules ](../py-modindex.html "Python Module Index") | 
  * [ next ](unittest.html "unittest â Unit testing framework") | 
  * [ previous ](devmode.html "Python Development Mode") | 
  * ![Python logo](../_static/py.svg)
  * [ Python ](https://www.python.org/) » 
  *   *   * [ 3.12.3 Documentation ](../index.html) » 
  * [ The Python Standard Library ](index.html) » 
  * [ Development Tools ](development.html) » 
  * [ ` doctest  ` â Test interactive Python examples ]()
  * | 
  * Theme  Auto  Light  Dark  | 

#  ` doctest  ` â Test interactive Python examples  Â¶

**Source code:** [ Lib/doctest.py
](https://github.com/python/cpython/tree/3.12/Lib/doctest.py)

* * *

The  ` doctest  ` module searches for pieces of text that look like
interactive Python sessions, and then executes those sessions to verify that
they work exactly as shown. There are several common ways to use doctest:

  * To check that a moduleâs docstrings are up-to-date by verifying that all interactive examples still work as documented. 

  * To perform regression testing by verifying that interactive examples from a test file or a test object work as expected. 

  * To write tutorial documentation for a package, liberally illustrated with input-output examples. Depending on whether the examples or the expository text are emphasized, this has the flavor of âliterate testingâ or âexecutable documentationâ. 

Hereâs a complete but small example module:

    
    
    """
    This is the "example" module.
    
    The example module supplies one function, factorial().  For example,
    
    >>> factorial(5)
    120
    """
    
    def factorial(n):
        """Return the factorial of n, an exact integer >= 0.
    
        >>> [factorial(n) for n in range(6)]
        [1, 1, 2, 6, 24, 120]
        >>> factorial(30)
        265252859812191058636308480000000
        >>> factorial(-1)
        Traceback (most recent call last):
            ...
        ValueError: n must be >= 0
    
        Factorials of floats are OK, but the float must be an exact integer:
        >>> factorial(30.1)
        Traceback (most recent call last):
            ...
        ValueError: n must be exact integer
        >>> factorial(30.0)
        265252859812191058636308480000000
    
        It must also not be ridiculously large:
        >>> factorial(1e100)
        Traceback (most recent call last):
            ...
        OverflowError: n too large
        """
    
        import math
        if not n >= 0:
            raise ValueError("n must be >= 0")
        if math.floor(n) != n:
            raise ValueError("n must be exact integer")
        if n+1 == n:  # catch a value like 1e300
            raise OverflowError("n too large")
        result = 1
        factor = 2
        while factor <= n: