¿Qué es import doctest y qué puedes hacer con él?

¿Recuerdas ese momento en el que explicabas algo paso a paso, y alguien te interrumpía diciendo: ¿Pero eso funciona de verdad? Algo similar sucede al escribir ejemplos en la documentación de tu código. Por fortuna, Python tiene una herramienta que no solo responde a esa pregunta, sino que la convierte en un sistema automático de validación: import doctest. Este es un módulo que te permite, no solo incluir ejemplos interactivos en tu documentación, sino también comprobar que esos ejemplos sean correctos. el día de hoy te quiero enseñar cómo funciona import doctest en Python y qué puedes hacer con él.

¿Qué hace doctest y cómo funciona?

El módulo de import doctest funcionan buscando ejemplos en los docstrings de tus funciones, clases y módulos que parezcan sesiones de consola interactiva. Luego, ejecuta dichos ejemplos y verifica que el resultado real coincida con el que se ha documentado. Si todo está en orden, no verás ningún error; de lo contrario, tendrás detalles precisos sobre lo que falló.

Por ejemplo, un docstring podría contener:

def suma(a, b):
    """
    Devuelve la suma de dos números.

    >>> suma(2, 3)
    5
    >>> suma(-1, 1)
    0
    """
    return a + b

Si ejecutas el módulo con import doctest, validará que las salidas de las llamadas a suma sean correctas. Esto garantiza que tu documentación siempre esté sincronizada con el comportamiento de tu código.

¿Cómo usar import doctest?

Integrar doctest en tus proyectos es tan sencillo como incluir unas pocas líneas al final de tu módulo:

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

Gracias a esta configuración, al ejecutar tu archivo con python_nombre_archivo.py, se ejecutará de forma automática las pruebas contenidas en los docstrings. Si requires un reporte más minucioso, añade el modificador -v al ejecutar el script:

python nombre_del_archivo.py -v

Esto no solo ejecutará las pruebas, sino que también mostrará cuáles pasaron, cuáles fallaron y los detalles de las diferencias.

Veamos un ejemplo:

Digamos que tienes que crear una función para calcular el área de un círculo. Así es como podrías documentarla:

import math

def area_circulo(radio):
    """
    Calcula el área de un círculo dado su radio.

    >>> area_circulo(2)
    12.566370614359172
    >>> area_circulo(0)
    0.0
    >>> area_circulo(-3)
    Traceback (most recent call last):
        ...
    ValueError: El radio debe ser un número positivo
    """
    if radio < 0:
        raise ValueError("El radio debe ser un número positivo")
    return math.pi * radio ** 2

Luego, simplemente ejecutas el archivo para asegurarte de que todo funcione como esperas. Si alguien modifica la función más adelante y rompe el cálculo, doctest lo detectará de forma inmediata.

¿Cuándo no es recomendable?: Alternativas y extensiones de doctest

Si bien import doctest es una opción ideal para ejemplos fáciles y pruebas rápidas, puede llegar a quedarse corto en proyectos de mayor complejidad. En estos casos unittest o pytest nos ofrecen funcionalidades más avanzadas, como aserciones y ejecución de pruebas en paralelo.

No obstante, no tienes que elegir una u otra. Puedes combinar import doctest con estas herramientas para aprovechar lo mejor de ambos mundos. Por ejemplo, puedes generar un conjunto de pruebas a partir de los docstrings de tus módulos e integrarlos en un flujo de trabajo más amplio con unittest. Así puedes hacerlo.

import unittest
import doctest

def load_tests(loader, tests, ignore):
    tests.addTests(doctest.DocTestSuite())
    return tests

Esto te permite reutilizar tus ejemplos documentados como parte de un sistema de pruebas más robusto.

Veamos un análisis comparativo de cada uno de estos términos para entender mejor el import doctest:

Características	doctest	unittest	pytest
Propósito principal	Verificar que los ejemplos de docstrings sean correctos.	Estructurar y ejecutar pruebas unitarias detalladas en módulos o clases.	Simplificar la creación y ejecución de pruebas con una sintaxis más legible y funcionalidades avanzadas.
Facilidad de uso	Muy simple; ideal para casos básicos y ejemplos documentados.	Más complejo; requiere mayor configuración y conocimiento.	Fácil de usar; permite pruebas simples y complejas con menor código repetitivo.
Configuración inicial	Solo requiere incluir ejemplos en los docstrings y ejecutar doctest.testmod().	Necesita definir clases que hereden de unittest.TestCase y usar métodos como assertEqual.	Instalación con pip (pip install pytest), y las pruebas se escriben como funciones normales.
Legibilidad	Muy legible, ya que los ejemplos imitan sesiones interactivas de Python.	Menos legible debido a la estructura basada en clases y métodos.	Muy legible y concisa, con soporte para fixtures y decoradores para personalizar pruebas.
Adecuado para	Pruebas sencillas y verificar documentación ejecutable.	Aplicaciones más complejas y entornos con múltiples niveles de pruebas unitarias.	Pruebas desde simples hasta muy avanzadas, incluyendo flujos de integración y parametrización.
Ventajas	– Ideal para combinar documentación y pruebas. – Muy fácil de usar.	– Integrado en la biblioteca estándar de Python. – Amplio control sobre las pruebas.	– Soporte avanzado para fixtures. – Parametrización simple. – Comunidad activa y extensiones.
Desventajas	– No apto para flujos de trabajo complejos. – Limitado a la validación de ejemplos simples.	– Verboso y menos intuitivo. – Necesidad de código boilerplate.	– Requiere instalación adicional. – Puede ser excesivo para pruebas extremadamente simples.
Soporte para fixtures	No disponible.	Limitado y más complejo de implementar.	Soporte avanzado y flexible mediante decoradores como @pytest.fixture.
Parámetros de prueba	No soportado.	Limitado a iteraciones manuales o código adicional.	Soportado directamente con @pytest.mark.parametrize.
Manejo de errores	Detecta fallos simples y muestra diferencias con los resultados esperados.	Proporciona detalles específicos de las fallas, pero con salidas más técnicas.	Ofrece rastreos detallados y legibles; resalta exactamente qué falló y por qué.
Integración con otras herramientas	Limitada; no apto para integración continua ni herramientas externas.	Moderada; se integra con flujos de CI/CD estándar.	Alta; funciona bien con CI/CD, plugins avanzados y herramientas de análisis de cobertura.
Popularidad	Moderada; útil para casos específicos.	Amplia, ya que es parte de la biblioteca estándar de Python.	Muy alta, debido a su flexibilidad, simplicidad y extensibilidad.

Si estás buscando cambiar tu vida e ingresar en el mundo de la tecnología, no dudes en unirte a nuestro bootcamp en programación desde cero, que te permite convertirte en un profesional del sector tech en tiempo record. Aprovecha esta oportunidad, que se encuentra a un click de distancia, y conviértete en el mejor profesional. Aprende d elos mejores e instrúyete en diversas áreas. ¡Solicita más información ahora!