Cómo escribir pruebas en Python con doctest

Como desarrolladores, a menudo escribimos casos de prueba y comentarios para explicar nuestro código. Los comentarios mejoran la legibilidad y la calidad de la base de código. Los comentarios detallados pueden recordarnos por qué implementamos una funcionalidad específica. También pueden ayudar a otros programadores a entender, mantener, usar y ampliar las bases de código.

Una de las mejores prácticas consiste en escribir primero los comentarios y los casos de prueba de tus funciones. Esto te ayuda a escribir código de mayor calidad y a tener presentes los distintos casos límite y requisitos de la función. Sin embargo, los métodos tradicionales requieren muchísimo tiempo, ya que debemos preparar un archivo de casos aparte y escribir funciones extensas para cada prueba.

La herramienta doctest de Python resulta muy útil en estas situaciones. La comunidad de código abierto desarrolló el módulo doctest para ofrecer un marco de pruebas eficiente durante el desarrollo. Podemos usar doctest para escribir pruebas del código de nuestras funciones y definir tanto los valores de entrada como los de salida. Así ahorramos tiempo y esfuerzo mientras escribimos código de alta calidad.

Suena bien, pero ¿cómo se escribe exactamente un doctest en Python? En este artículo, te guiaremos por la configuración, la creación y las pruebas de tu primer doctest para que tengas toda la información que necesitas para empezar.

Cómo escribir tu primer doctest

Antes de empezar a escribir tu primer doctest de Python, asegúrate de tener Python 3 y un entorno de programación adecuado instalados en tu computadora, como Visual Studio Code (VS Code). En este tutorial usaremos VS Code como entorno de desarrollo integrado (IDE).

Configurar el IDE

Después de instalar Python 3, verifica que la instalación se haya completado correctamente. En Windows, escribe el siguiente fragmento de código en el símbolo del sistema:

1py -3 --version

En macOS o Unix, abre la terminal y escribe el siguiente comando:

1python3 --version.

A continuación, descarga el IDE Visual Studio Code.

Abre el asistente de configuración y sigue las instrucciones en pantalla para instalar VS Code.

Después de abrir VS Code, descarga la extensión de Python desde la pestaña Extensiones. Ya tienes todo listo para usar Python en VS Code.

Introducción a docstring

Python tiene un módulo llamado docstring. Los docstrings son literales de cadena que usamos en la declaración de una función, clase o módulo para escribir comentarios y casos de prueba dentro de nuestras funciones. Por eso, los docstrings son esenciales tanto para la documentación como para las pruebas.

Podemos escribir un docstring entre tres comillas:

1"""

Después del docstring, podemos escribir tanto los comentarios como las pruebas, también entre tres comillas.

1"""

En este tutorial aprenderemos la sintaxis de los casos de prueba y los comentarios. A primera vista, un docstring y un comentario pueden parecer similares. Sin embargo, cumplen propósitos distintos. Los comentarios explican la implementación del código, mientras que los docstrings documentan clases, métodos y funciones. Ayudan a otros programadores a entender el propósito de una función y cómo pueden usarla en su trabajo.

El módulo doctest detecta los docstrings dentro de las definiciones de funciones o clases. Para identificar y diferenciar los casos de prueba de los comentarios, colocamos el símbolo >>> antes de los casos de prueba en el docstring.

Abre la línea de comandos de tu sistema operativo y escribe python3.

El shell interactivo de Python 3 usa el símbolo >>> como indicador y devuelve el resultado sin ese símbolo. Supongamos que imprimimos un valor. La sesión interactiva se ve así:

El módulo doctest busca y detecta patrones en el docstring que se asemejan a sesiones interactivas de Python. Una vez detectados, ejecuta los doctests. Estos deben estar en el docstring inicial, justo después de la llamada a la función o del encabezado del método. Asegúrate de no agregar espacios adicionales después de escribir el doctest para evitar errores o fallas inesperados.

Escribir un doctest

Para poder usar doctests, primero escribamos un código de ejemplo. En este tutorial, crearemos un módulo básico llamado square.py, que tiene una función llamada square. La función calcula el cuadrado del valor de entrada.

1def square(x):
2    return x*x

Ahora agregamos un docstring a nuestra función. Este docstring contiene la documentación que especifica lo que hace la función. También incluye dos casos de prueba, con los valores de entrada y los resultados esperados. Estos valores sirven para probar el resultado procesado.

1def square(x):
2    """
3    This function returns the square of the input.
4    >>> square(2)
5    4
6    >>> square(5)
7    25
8    """
9    return x*x

¿Cómo se prueba el resultado procesado?

El módulo doctest analiza el docstring y genera texto. Luego, ejecuta el texto analizado como un comando del shell de Python y compara el resultado con el esperado que aparece en el docstring.

Cómo ejecutar un doctest

Para ejecutar el doctest con nuestro módulo square.py, agregamos la función testmod de doctest. La función doctest.testmod prueba el módulo m o el módulo "_main_" si no se proporciona m. Esta función es necesaria para ejecutar doctest.

1def square(x):
2    """
3    This function returns the square of the input.
4    >>> square(2)
5    4
6    >>> square(5)
7    25
8    """
9    return x*x
10
11if __name__ == "__main__":
12    import doctest
13    doctest.testmod() #test the whole module.

Luego, simplemente ejecutamos el módulo square.py en la terminal con el comando:

1python square.py

Como square.py solo tiene una función, el módulo doctest solo prueba esa función.

Como no aparece ningún resultado, todas las pruebas se aprobaron. Si una prueba falla, el error aparece en la terminal y podemos resolverlo como corresponda. Si queremos ver el registro, modificamos el script y agregamos -v:

1python square.py -v

Los registros nos muestran los resultados con más detalle, incluidas las tasas de éxito y de fallas de nuestras pruebas. También podemos usar un práctico atajo para ejecutar la función testmod sin la función main: podemos ejecutar directamente el módulo doctest mediante la biblioteca estándar. Para ello, pasamos el nombre del módulo a la interfaz de línea de comandos:

1python -m doctest -v square.py

Ahora ampliemos un poco el ejemplo anterior. ¿Qué pasa si quieres especificar los tipos de datos de entrada y salida de tu función? Para hacerlo, modificamos ligeramente nuestro docstring. A partir del ejemplo anterior, simplemente agregamos:

1:param a: int
2:return: int

Así queda nuestro docstring:

1def square(x):
2    """
3    This function returns the square of the input.
4    :param a: int
5    :return: int
6    >>> square(2)
7    4
8    >>> square(5)
9    25
10    """
11    return x*x

Si tenemos más de un parámetro de entrada, podemos modificar :param. Supongamos que tenemos dos parámetros de entrada. El docstring correspondiente sería:

1:param a: int
2:param b: int
3:return: int

Podemos seguir haciendo esto para todos los parámetros de entrada que necesitemos.

¡Felicidades! Acabas de escribir un doctest.

Conclusión

En este artículo presentamos el módulo doctest de Python para ofrecerte una introducción básica y mostrarte cómo los doctests pueden mejorar la calidad del código y ofrecer un mejor enfoque de programación.

También mostramos cómo incorporar doctests en las funciones y ejecutarlos con el archivo de código y la terminal. Además, demostramos lo fácil que es usar el módulo doctest al programar.

El enfoque clásico para probar funciones consiste en escribir un script independiente con los casos de prueba. Los doctests eliminan la necesidad de escribir esos scripts y nos permiten probar el código de manera más eficiente. En resumen, facilitan las pruebas y mejoran la calidad de nuestro código Python.