Pytest en Python: guía completa para principiantes

Probar un programa manualmente puede ser suficiente cuando el proyecto es pequeño. Ejecutas el archivo, introduces algunos valores y compruebas el resultado. Sin embargo, cuando el código crece, repetir las mismas verificaciones después de cada cambio consume tiempo y aumenta el riesgo de olvidar un caso importante. En ese momento, Pytest en Python se convierte en una herramienta muy útil.

Pytest permite escribir pruebas automatizadas que confirman si las funciones de una aplicación siguen produciendo los resultados esperados. Cuando algo falla, muestra qué prueba se rompió, en qué línea ocurrió el problema y qué valores fueron comparados.

En esta guía aprenderás a instalar Pytest, crear tu primera prueba, utilizar assert, comprobar excepciones, organizar archivos y ejecutar los comandos más importantes. El contenido está adaptado para personas que están comenzando y no requiere experiencia previa con testing automatizado.

Qué es Pytest

Pytest es un framework de pruebas para Python. Su función principal es descubrir y ejecutar pruebas, para luego presentar un informe claro con los resultados correctos y los fallos encontrados.

Una prueba automatizada es código que ejecuta otra parte del programa y compara el resultado real con el resultado esperado. Imagina una función que suma dos números. Esperas que sumar(2, 3) devuelva 5. En lugar de comprobarlo manualmente después de cada modificación, puedes escribir una prueba que haga la verificación en milisegundos.

Pytest se utiliza con frecuencia para pruebas unitarias, que normalmente revisan una unidad pequeña del programa, como una función o un método. También puede formar parte de pruebas más amplias para APIs, bases de datos, herramientas de terminal y aplicaciones web.

Una de sus principales ventajas es la sintaxis sencilla. En muchos casos basta con crear una función cuyo nombre comience por test_ y utilizar una expresión assert. Esta simplicidad permite aprender lo esencial antes de avanzar hacia fixtures, parametrización y mocks.

Por qué aprender Pytest

Las pruebas automatizadas no son exclusivas de empresas grandes. También aportan valor en ejercicios, proyectos personales, scripts de automatización y aplicaciones pequeñas. Ayudan a modificar el código con más seguridad porque puedes ejecutar todas las pruebas después de cada cambio.

• Detectan errores poco después de introducirlos.
• Evitan que un problema corregido vuelva a aparecer.
• Documentan cómo debe comportarse una función.
• Facilitan la refactorización y el mantenimiento.
• Reducen las comprobaciones manuales repetitivas.
• Aumentan la confianza antes de publicar una nueva versión.

Una suite de pruebas aprobada no demuestra que el programa esté completamente libre de errores. Solo confirma los comportamientos que fueron cubiertos. Por eso conviene elegir casos relevantes: entradas normales, valores límite y datos inválidos.

Requisitos para seguir el tutorial

Necesitas tener Python instalado y saber ejecutar comandos básicos en una terminal. También es recomendable comprender cómo se crean y utilizan las funciones. Puedes repasar ese tema en la guía sobre funciones en Python.

Los ejemplos funcionan en cualquier editor. Visual Studio Code y PyCharm son opciones populares, aunque también puedes trabajar con IDLE u otro entorno. Para conocer alternativas gratuitas, consulta la selección de herramientas para programadores principiantes.

Crea una carpeta llamada proyecto_pytest. También es recomendable utilizar un entorno virtual para separar las dependencias del proyecto. La guía de entornos virtuales con Python explica por qué esta práctica evita conflictos entre bibliotecas.

Cómo instalar Pytest

Abre una terminal dentro de la carpeta del proyecto y crea el entorno virtual:

python -m venv .venv

En Windows PowerShell, actívalo con:

.venv\Scripts\Activate.ps1

En Linux o macOS, utiliza:

source .venv/bin/activate

Después instala Pytest:

python -m pip install -U pytest

El comando python -m pip ayuda a instalar el paquete en el mismo intérprete que utiliza el proyecto. Si todavía estás aprendiendo cómo funcionan paquetes y dependencias, consulta la guía sobre bibliotecas y módulos de Python.

Comprueba que la instalación terminó correctamente:

pytest --version

La terminal mostrará la versión instalada. La documentación oficial de Pytest utiliza el mismo procedimiento inicial. El Python Packaging User Guide ofrece información adicional sobre entornos virtuales e instalación de paquetes.

Crear el código que vamos a probar

Dentro de la carpeta, crea un archivo llamado calculadora.py y añade una función sencilla:

def sumar(a, b):
    return a + b

La función recibe dos valores y devuelve su suma. Podrías abrir el intérprete y probar diferentes números manualmente, pero una prueba automatizada realizará esas comprobaciones siempre de la misma manera.

Crear la primera prueba con Pytest

Crea otro archivo en la misma carpeta llamado test_calculadora.py. El prefijo test_ es importante porque Pytest utiliza convenciones de nombres para encontrar las pruebas automáticamente.

from calculadora import sumar


def test_sumar_dos_numeros():
    resultado = sumar(2, 3)
    assert resultado == 5

Cada parte tiene una función concreta:

• from calculadora import sumar importa el código que será probado.
• test_sumar_dos_numeros() define una función de prueba.
• sumar(2, 3) ejecuta la función real.
• assert resultado == 5 comprueba la expectativa.

El nombre de la función también comienza por test_. Utiliza nombres descriptivos para que el informe indique claramente qué comportamiento falló.

Ejecutar la primera prueba

Con el entorno virtual activo y la terminal ubicada en la carpeta principal, ejecuta:

pytest

Cuando todo funciona, verás una salida parecida a esta:

collected 1 item
test_calculadora.py .                         [100%]
1 passed

El punto representa una prueba aprobada. Para mostrar el nombre completo de cada prueba, utiliza:

pytest -v

La opción -v activa una salida más detallada. Para obtener un informe más corto, ejecuta:

pytest -q

Qué ocurre cuando una prueba falla

Cambia temporalmente el valor esperado por uno incorrecto:

def test_sumar_dos_numeros():
    resultado = sumar(2, 3)
    assert resultado == 6

Al ejecutar Pytest, la prueba fallará porque el resultado real es 5. El informe mostrará información similar a:

E       assert 5 == 6
FAILED test_calculadora.py::test_sumar_dos_numeros

La herramienta indica el valor obtenido, el esperado, la función de prueba y la línea responsable. Este informe ayuda a distinguir entre tres posibilidades:

• el código de la aplicación tiene un error;
• el valor esperado en la prueba es incorrecto;
• la prueba no representa bien la regla deseada.

Después de observar el fallo, vuelve a cambiar el resultado esperado a 5.

Añadir varios casos de prueba

Una sola prueba rara vez cubre todos los escenarios importantes. Añade casos con números negativos y cero:

from calculadora import sumar


def test_sumar_dos_numeros():
    assert sumar(2, 3) == 5


def test_sumar_numero_negativo():
    assert sumar(-2, 5) == 3


def test_sumar_con_cero():
    assert sumar(10, 0) == 10

Al ejecutar pytest -v, los tres casos aparecerán de forma independiente. Esta separación facilita identificar exactamente qué regla dejó de funcionar.

Mantén las pruebas enfocadas. Una prueba pequeña que verifica un comportamiento suele ser más fácil de entender y mantener que una función extensa con muchas comprobaciones no relacionadas.

Probar excepciones con pytest.raises()

No todas las funciones deben devolver siempre un valor. En algunos casos, el comportamiento correcto es generar una excepción. Añade esta función a calculadora.py:

def dividir(a, b):
    if b == 0:
        raise ValueError("El divisor no puede ser cero")

    return a / b

Actualiza el archivo de pruebas:

import pytest

from calculadora import dividir, sumar


def test_dividir_por_cero():
    with pytest.raises(ValueError):
        dividir(10, 0)

El bloque pytest.raises(ValueError) indica que se espera esa excepción. La prueba se aprueba cuando ocurre y falla cuando la función no la genera.

Este patrón es útil para validaciones, conversiones, lectura de archivos y reglas de negocio. La guía sobre try y except en Python explica los fundamentos del manejo de excepciones.

También puedes comprobar el mensaje:

def test_mensaje_al_dividir_por_cero():
    with pytest.raises(ValueError, match="El divisor no puede ser cero"):
        dividir(10, 0)

Organizar los archivos de prueba

En un ejercicio pequeño, el código y las pruebas pueden permanecer en la misma carpeta. En proyectos mayores, una carpeta independiente mejora la organización:

proyecto_pytest/
├── calculadora.py
└── tests/
    └── test_calculadora.py

Ejecuta Pytest desde la raíz del proyecto. Por defecto, busca archivos con nombres como test_*.py y *_test.py en la carpeta actual y sus subcarpetas.

• Centraliza las pruebas dentro de tests.
• Comienza los archivos y funciones con test_.
• Elige nombres que describan el escenario.
• Separa el código de producción del código de prueba.
• Evita que una prueba dependa del resultado de otra.

Comandos útiles de Pytest

Ejecutar todas las pruebas

pytest

Mostrar los nombres de las pruebas

pytest -v

Ejecutar un archivo específico

pytest tests/test_calculadora.py

Filtrar pruebas por nombre

pytest -k sumar

Este comando ejecuta las pruebas cuyo nombre contiene la palabra sumar.

Detenerse después del primer fallo

pytest --maxfail=1

Ejecutar solamente las pruebas que fallaron antes

pytest --lf

--lf significa “last failed”. Resulta práctico mientras estás corrigiendo un problema específico.

Errores frecuentes al comenzar

El comando pytest no se reconoce

Comprueba que el entorno virtual esté activo y que la instalación se haya completado. También puedes ejecutar:

python -m pytest

No se encuentra ninguna prueba

Confirma que el archivo comience por test_ o termine en _test.py. Las funciones también deben comenzar por test_.

El módulo principal no se puede importar

Ejecuta el comando desde la raíz del proyecto. Revisa el nombre del módulo y evita espacios o guiones en los archivos Python.

El archivo se llama pytest.py

No utilices pytest.py como nombre de un archivo propio. Puede ocultar la biblioteca real y provocar errores de importación difíciles de interpretar.

La prueba se aprueba sin comprobar nada

Pytest puede ejecutar una función que comienza por test_ aunque no contenga ninguna expectativa. Asegúrate de incluir un assert o una excepción esperada.

El informe de fallo parece confuso

Ejecuta pytest -v y analiza primero el fallo inicial. La guía sobre errores comunes de Python ayuda a desarrollar un método para leer mensajes y encontrar la causa del problema.

Buenas prácticas para las primeras pruebas

• Usa nombres descriptivos.
• Comprueba un comportamiento principal por función.
• Incluye casos normales, límites y entradas inválidas.
• No dependas del orden de ejecución.
• No compartas estado accidentalmente entre pruebas.
• Ejecuta la suite después de modificar el programa.
• Mantén las pruebas tan legibles como el código que verifican.

Una estructura sencilla para pensar cada prueba es:

1. Preparar: definir datos y condiciones iniciales.
2. Ejecutar: llamar a la función que se está probando.
3. Verificar: comparar el resultado con la expectativa.

En el ejemplo inicial, preparamos los valores 2 y 3, ejecutamos sumar y verificamos que el resultado fuera 5.

Qué aprender después

Cuando domines las bases, puedes explorar herramientas que reducen la repetición y permiten probar proyectos mayores:

• Fixtures: preparan datos y recursos reutilizables.
• Parametrización: ejecuta una prueba con diferentes entradas.
• Mocks: sustituyen temporalmente servicios externos.
• Cobertura: indica qué partes del código fueron ejecutadas.
• Integración continua: ejecuta pruebas automáticamente en el repositorio.

No necesitas aprender todo al mismo tiempo. Un conjunto pequeño de pruebas claras ya mejora la seguridad del proyecto y crea el hábito de comprobar el código con frecuencia.

Conclusión

Pytest en Python ofrece una forma accesible de comenzar con las pruebas automatizadas. Instalas el paquete, creas archivos y funciones cuyos nombres comienzan por test_, utilizas assert para comparar resultados y ejecutas la suite con el comando pytest.

En este tutorial probamos una función de suma, observamos un fallo intencional, añadimos varios escenarios y utilizamos pytest.raises() para confirmar una excepción. También revisamos la organización de carpetas, los comandos esenciales y los problemas más comunes.

Como práctica, añade funciones de resta, multiplicación y división a calculadora.py. Escribe al menos dos pruebas para cada una. Este ejercicio te ayudará a comprender el flujo completo antes de avanzar hacia fixtures, parametrización y mocks.