Si ha evitado escribir pruebas porque le parecen una tarea ardua, este tutorial de pytest debería hacerle cambiar de opinión. Pytest elimina la mayor parte de la ceremonia: no hay clases de las que heredar ni métodos de aserción especiales que recordar. Una prueba puede constar de solo dos líneas.

Construiremos un pequeño carrito de compras y lo probaremos paso a paso. Ejecutamos todo en Python 3.13 con pytest 9.2 y el resultado que se muestra es real, aunque recortamos las rutas de los archivos y los detalles de tiempo que diferirán en su máquina.

¿Por qué pytest?

Python viene con unittest, que funciona bien, pero pytest suele ser la opción más conveniente. Aquí está el mismo cheque en cada uno:

Pytest también puede ejecutar sus pruebas unittest existentes, para que pueda cambiar gradualmente. También tiene un gran ecosistema de complementos, que incluye pytest-cov para cobertura y pytest-xdist para ejecuciones paralelas.

Instalar pytest

Primero cree un entorno virtual, como se explica en nuestro tutorial del entorno virtual de Python, y luego instálelo:

pip install pytest
pytest --version

# pytest 9.2.0

Cree una carpeta de proyecto que contenga dos archivos, cart.py y test_cart.py. Pytest encuentra pruebas automáticamente siguiendo reglas de nomenclatura: archivos llamados test_*.py o *_test.py, funciones que comienzan con test y clases que comienzan con Test. Si una prueba no se selecciona, lo primero que se debe verificar es que el nombre no coincida.

El código a probar

# cart.py
class Cart:
    def __init__(self):
        self.items = []

    def add(self, name, price, qty=1):
        if qty < 1:
            raise ValueError("qty must be at least 1")
        self.items.append((name, price, qty))

    def total(self, discount=0):
        subtotal = sum(price * qty for _, price, qty in self.items)
        return round(subtotal * (1 - discount / 100), 2)

Tus primeras pruebas

# test_cart.py
from cart import Cart

def test_empty_cart_is_free():
    assert Cart().total() == 0

Esa es una prueba completa. Ejecute pytest desde la carpeta del proyecto e informará una prueba aprobada. Si recibe un error de importación, ejecútelo como python -m pytest, lo que agrega la carpeta actual a la ruta de importación.

Fallos de lectura

Aquí es donde realmente brilla pytest. Aquí hay una prueba con un valor esperado deliberadamente incorrecto:

def test_wrong_total():
    c = Cart()
    c.add("Keyboard", 1500)
    assert c.total() == 1400

Y esto es lo que imprimió cuando lo ejecutamos:

    def test_wrong_total():
        c = Cart()
        c.add("Keyboard", 1500)
>       assert c.total() == 1400
E       assert 1500.0 == 1400
E        +  where 1500.0 = total()

FAILED fail_example.py::test_wrong_total - assert 1500.0 == 1400
============================== 1 failed in 0.12s ==============================

El > marca la línea fallida y las líneas E muestran los valores reales. No fue necesario agregar un mensaje personalizado, porque pytest reescribe las declaraciones assert para que puedan informar lo que compararon. Hace lo mismo con listas y diccionarios, señalando exactamente qué elementos difieren.

Excepciones de prueba

El manejo de errores también es un comportamiento y merece pruebas. pytest.raises pasa solo si el bloque genera la excepción esperada:

import pytest

def test_rejects_zero_qty():
    with pytest.raises(ValueError, match="at least 1"):
        Cart().add("Pen", 10, qty=0)

El argumento opcional match verifica el mensaje usando una expresión regular, por lo que un ValueError diferente no pasará por accidente. Para aprender cómo generar y manejar errores como este, lea nuestra guía para el manejo de excepciones de Python.

Accesorios: configuración reutilizable

La mayoría de las pruebas necesitan algo preparado primero. Un accesorio es una función que lo proporciona. Decórelo con @pytest.fixture y cualquier prueba que lo nombre como argumento recibirá el resultado:

@pytest.fixture
def cart():
    c = Cart()
    c.add("Keyboard", 1500)
    c.add("Mouse", 500, qty=2)
    return c

def test_total(cart):
    assert cart.total() == 2500

Cada prueba recibe un carro nuevo de forma predeterminada, por lo que las pruebas no pueden afectarse entre sí. Pytest hace coincidir el nombre del argumento con el nombre del dispositivo y usted nunca llama al dispositivo usted mismo. @pytest.fixture es un decorador, que explicamos en Explicación de los decoradores de Python.

Limpieza con rendimiento

Utilice yield en lugar de return cuando necesite limpiar después. El código después de yield se ejecuta cuando finaliza la prueba, incluso si falló:

@pytest.fixture
def temp_db():
    print("\nopen db")
    yield {"users": []}
    print("close db")

def test_db(temp_db):
    assert temp_db["users"] == []

Ejecutar con -s para mostrar la salida impresa confirmó que el pedido estaba abierto, probado y luego cerrado.

Alcance del accesorio y conftest.py

De forma predeterminada, un dispositivo se ejecuta una vez por prueba. Para configuraciones costosas, como una base de datos o un navegador, cambie su vida útil con scope:

Coloque los aparatos utilizados por varios archivos en un archivo llamado conftest.py. Pytest lo carga automáticamente, por lo que las pruebas pueden usar sus dispositivos sin importarlos. Sin embargo, tenga cuidado con los ámbitos compartidos, porque un cambio realizado en una prueba puede filtrarse a la siguiente.

Parametrizar: una prueba, muchas entradas

En lugar de copiar una prueba para cada valor, enumere los casos:

@pytest.mark.parametrize("discount, expected", [
    (0, 2500),
    (10, 2250),
    (100, 0),
])
def test_discount(cart, discount, expected):
    assert cart.total(discount) == expected

Cada fila se convierte en su propia prueba, y puede ver esto en el resultado detallado de nuestra ejecución del archivo completo:

test_cart.py::test_total PASSED                        [ 16%]
test_cart.py::test_discount[0-2500] PASSED             [ 33%]
test_cart.py::test_discount[10-2250] PASSED            [ 50%]
test_cart.py::test_discount[100-0] PASSED              [ 66%]
test_cart.py::test_rejects_zero_qty PASSED             [ 83%]
test_cart.py::test_empty_cart_is_free PASSED           [100%]

============================== 6 passed in 0.05s ==============================

Si una fila falla, las demás aún se ejecutan y el nombre le indica exactamente qué valores causaron el problema. Observe que combinamos la parametrización con el dispositivo cart. Para elegir valores que probablemente encuentren errores, utilice el análisis de valores límite.

Accesorios incorporados útiles

Pytest incluye varios accesorios ya preparados. Estos dos son especialmente útiles y ambos aprobaron nuestra carrera:

def test_write_report(tmp_path):
    report = tmp_path / "report.txt"
    report.write_text("passed")
    assert report.read_text() == "passed"

def read_mode():
    return os.environ.get("APP_MODE", "dev")

def test_mode(monkeypatch):
    monkeypatch.setenv("APP_MODE", "staging")
    assert read_mode() == "staging"

tmp_path proporciona a cada prueba una carpeta temporal única, por lo que las pruebas nunca tocan archivos reales. monkeypatch cambia las variables o atributos de entorno y deshace el cambio cuando finaliza la prueba. Otro útil es capsys, que captura la salida impresa para que puedas comprobarla.

Marcadores: saltar y xfail

Los marcadores agregan etiquetas y comportamiento a las pruebas:

@pytest.mark.skip(reason="payment sandbox is down")
def test_payment():
    assert False

@pytest.mark.xfail(reason="floating point")
def test_rounding():
    assert 0.1 + 0.2 == 0.3

skip no ejecuta la prueba en absoluto. xfail lo ejecuta pero espera un error, por lo que un problema conocido no interrumpe la compilación. Con las otras pruebas adicionales en el mismo archivo, nuestra ejecución se resumió como 3 passed, 1 skipped, 1 xfailed. Por cierto, esa prueba de redondeo realmente falla: en aritmética de coma flotante, 0,1 + 0,2 no es exactamente 0,3. Utilice pytest.approx(0.3) al comparar decimales.

También puede crear sus propios marcadores, como @pytest.mark.slow, y ejecutar solo aquellos con pytest -m slow, o omitirlos con -m "not slow". Registre marcadores personalizados en su archivo de configuración para evitar advertencias.

Banderas de línea de comando útiles

Ejecutando pytest en CI

Las pruebas son más valiosas cuando se ejecutan automáticamente en cada cambio. Un trabajo mínimo de GitHub Actions se ve así:

steps:
  - uses: actions/checkout@v4
  - uses: actions/setup-python@v5
    with:
      python-version: "3.13"
  - run: pip install -r requirements.txt
  - run: python -m pytest

Pytest sale con un código distinto de cero cuando las pruebas fallan, que es lo que hace que la canalización se detenga. No ejecutamos este archivo de flujo de trabajo, así que adáptelo a su proyecto. Nuestra guía de CI/CD de GitHub Actions explica los detalles. Pytest también funciona bien para pruebas de navegador, como muestran nuestro tutorial de Selenium Python y el tutorial del modelo de objetos de página.

Conclusión

Ahora tiene lo que necesita para la mayoría de los conjuntos de pruebas de Python: afirmaciones simples, accesorios para configuración, parametrización para variaciones y algunas banderas para velocidad. Empiece poco a poco. Elija una función en la que haya corregido un error recientemente y escriba primero una prueba para ese error. Si no está seguro de qué probar en cada nivel, lea acerca de pruebas unitarias frente a pruebas de integración.

Preguntas frecuentes

sigue aprendiendo