doctest busca sesiones interactivas en las docstrings y compara la salida real con la salida escrita. Así evita que los ejemplos breves queden desactualizados cuando cambia la implementación.
Ejemplo práctico
def total_with_tax(value: float, rate: float) -> float:
"""Return the total after tax.
>>> total_with_tax(100, 0.2)
120.0
>>> total_with_tax(50, 0)
50.0
"""
return value * (1 + rate)
if __name__ == "__main__":
import doctest
doctest.testmod(verbose=True)Cómo ejecutar el ejemplo
El bloque llama a testmod() solo al ejecutar el archivo directamente. También puedes usar python -m doctest -v archivo.py. La comparación es textual, por lo que importan la representación, los espacios y los decimales.
Cuándo resulta útil
Úsalo para contratos pequeños, tutoriales y ejemplos de API. No ocultes una preparación extensa en la docstring. Las fixtures, muchos escenarios y los informes de error detallados encajan mejor en una suite convencional.
Cuidados prácticos
No registres salidas inestables, como direcciones de memoria u orden de conjuntos. Opciones como ELLIPSIS ayudan, pero demasiada tolerancia puede aceptar un ejemplo incorrecto.
Sigue aprendiendo
Refuerza la base con pruebas unitarias con unittest. A documentación oficial de Python, consultada el 22 de julio de 2026, detalla la API, las limitaciones y las diferencias entre versiones.