Pruebas y Documentación (Doctest)

 

¿Qué es Doctest?

doctest permite escribir pruebas dentro de los docstrings de tus funciones. Es decir, los ejemplos que pones en la documentación se ejecutan automáticamente para comprobar que el código funciona como dices.

Esto ayuda a:

• Documentar funciones con ejemplos reales

• Detectar errores rápidamente

• Enseñar buenas prácticas

• Crear tests sin frameworks complicados

1. Ejemplo básico de doctest

def sumar(a, b):
    """
    Suma dos números.

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

Para ejecutar los tests:

python -m doctest archivo.py

Si todo está bien, no muestra nada. Si falla, muestra el error.

2. Doctest con cadenas

def mayusculas(texto):
    """
    Convierte un texto a mayúsculas.

    >>> mayusculas("hola")
    'HOLA'
    """
    return texto.upper()

3. Doctest con listas

def pares(lista):
    """
    Devuelve los números pares de una lista.

    >>> pares([1,2,3,4,5])
    [2, 4]
    """
    return [n for n in lista if n % 2 == 0]

4. Ignorar espacios o formatos (ELLIPSIS)

A veces no importa el resultado exacto:

def info():
    """
    >>> info()  # doctest: +ELLIPSIS
    'Versión...'
    """
    return "Versión 1.2.3"

5. Ejecutar doctest desde el propio archivo

Al final del archivo:

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

Así, al ejecutar:

python archivo.py

se ejecutan los tests automáticamente.

6. Ventajas de Doctest para tus alumnos

• Aprenden a documentar funciones

• Aprenden a escribir pruebas sin frameworks

• Ven ejemplos reales funcionando

• Es perfecto para ejercicios pequeños

• Se integra muy bien con FP y proyectos educativos

ACTIVIDAD PRÁCTICA: “Biblioteca de utilidades con Doctest”

Objetivo: crear un módulo con varias funciones documentadas y probadas.

Enunciado

Crea un archivo utilidades.py con las siguientes funciones:

1. es_primo(n)

   • Devuelve True si n es primo

   • Incluye 3 doctests

2. invertir(texto)

   • Devuelve el texto al revés

   • Incluye 2 doctests

3. media(lista)

   • Devuelve la media de una lista

   • Incluye 2 doctests

Al final del archivo, añade:

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

Solución propuesta

def es_primo(n):
    """
    Determina si un número es primo.

    >>> es_primo(2)
    True
    >>> es_primo(15)
    False
    >>> es_primo(17)
    True
    """
    if n < 2:
        return False
    for i in range(2, int(n**0.5) + 1):
        if n % i == 0:
            return False
    return True


def invertir(texto):
    """
    Invierte un texto.

    >>> invertir("hola")
    'aloh'
    >>> invertir("Python")
    'nohtyP'
    """
    return texto[::-1]


def media(lista):
    """
    Calcula la media de una lista de números.

    >>> media([1,2,3])
    2.0
    >>> media([10, 20])
    15.0
    """
    return sum(lista) / len(lista)


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

Resultado esperado

• Los alumnos ejecutan el archivo

• Doctest valida automáticamente todos los ejemplos

• Si algo falla, doctest lo muestra