Tests con pytest en FastAPI: prueba tu API de la tienda sin abrir el navegador

Convierte las pruebas manuales en /docs en tests que se ejecutan solos, con la API de la tienda y el IVA calculado en el servidor

Cambias el IVA de la API de la tienda, abres /docs, pulsas "Try it out" en el POST, miras que sale el precio bien y te das por satisfecho. Tres días después añades un filtro y no vuelves a probar el POST, porque total ya lo probaste. Esa comprobación a mano funciona hasta que tienes cinco rutas, y a partir de ahí se te olvida alguna siempre.

Los tests automáticos son esas mismas comprobaciones escritas una vez en un archivo, para que un solo comando las repita todas en un segundo. Si leíste el post de tests con JUnit en Java, la idea es la misma con otra herramienta. Aquí la herramienta se llama pytest, y para hablar con tu API sin levantar el servidor usaremos una pieza que ya viene con FastAPI.

Partimos de la API que construimos en tu primera API con FastAPI: listar productos, ver uno, añadir uno nuevo y calcular el 21% de IVA en el servidor. Al final tendrás una batería de tests que se ejecuta con un comando y un fallo provocado a propósito para ver cómo avisa.

Preparar el entorno

Entra en la carpeta tienda-api del post anterior, con su entorno virtual activado y el main.py completo que quedó allí. Si no lo tienes, cópialo del post de la primera API, sección "El código completo". Los tests necesitan una librería nueva:

Terminal 📋
pip install pytest httpx

El httpx es el cliente HTTP que usa por debajo la herramienta de pruebas de FastAPI. Si al ejecutar los tests Python se queja de que falta, ya sabes qué instalar. Los tests van en un archivo nuevo que se llama test_main.py y vive al lado de main.py, en la raíz del proyecto. El nombre importa: pytest solo recoge archivos que empiecen por test_ o acaben en _test.py.

Tu primer test: llamar a la API sin servidor

Piensa en cómo pruebas ahora: arrancas fastapi dev, abres el navegador y pulsas botones. Un test hace exactamente lo mismo, pero con código. Para eso FastAPI trae el TestClient, un cliente que se comporta como un navegador pero habla directamente con tu aplicación, sin abrir ningún puerto. No necesitas tener el servidor encendido.

Python: test_main.py 📋
from fastapi.testclient import TestClient

from main import app

client = TestClient(app)


def test_inicio():
    respuesta = client.get("/")
    assert respuesta.status_code == 200
    assert respuesta.json() == {"mensaje": "La API de la tienda funciona"}

Una función cuyo nombre empieza por test_ es un test. Dentro haces la petición y compruebas con assert lo que esperas: si la condición es verdadera, no pasa nada; si es falsa, pytest marca el test como fallido y te enseña qué esperabas y qué llegó. Ejecútalo desde la raíz del proyecto:

Terminal 📋
pytest

Verás una línea con un punto por cada test que pasa y un resumen al final, algo parecido a esto:

Salida (aproximada) 📋
test_main.py .                                                  [100%]

1 passed

Un punto es un test que pasa. Si ves una F, es uno que falla, y justo debajo pytest explica por qué.

❌ Error común: ModuleNotFoundError: No module named 'main'

Aquí es donde se atascan muchos. Si guardas los tests en una carpeta tests/ y ejecutas pytest, Python no encuentra main.py porque está un nivel más arriba. Dos salidas: dejar test_main.py junto a main.py, como hacemos aquí, o crear un archivo pytest.ini en la raíz con [pytest] y debajo pythonpath = .. Y ejecuta siempre pytest desde la raíz del proyecto, no desde dentro de otra carpeta.

Probar los errores también: 404 y 422

Los tests que más valor dan no son los de "todo va bien", sino los de "qué pasa si piden algo que no existe". En la API ya definimos dos casos: un id que no está en la lista devuelve 404, y un id que ni siquiera es un número devuelve 422 porque FastAPI lo rechaza antes de que tu función llegue a ejecutarse.

Python: test_main.py 📋
def test_listar_productos():
    respuesta = client.get("/productos")
    assert respuesta.status_code == 200
    assert len(respuesta.json()) == 3


def test_ver_producto_existente():
    respuesta = client.get("/productos/1")
    assert respuesta.status_code == 200
    assert respuesta.json()["nombre"] == "Teclado mecánico"


def test_producto_inexistente_da_404():
    respuesta = client.get("/productos/99")
    assert respuesta.status_code == 404
    assert respuesta.json() == {"detail": "Producto no encontrado"}


def test_id_que_no_es_numero_da_422():
    respuesta = client.get("/productos/abc")
    assert respuesta.status_code == 422

Ejecuta pytest otra vez. Deberías ver cinco puntos. Fíjate en que en el test del 404 comprobamos también el mensaje: si mañana alguien cambia el texto del error, el test avisa de que el frontend, que quizá lo enseña tal cual, va a mostrar algo distinto.

Probar el IVA con un POST

Esta es la prueba que antes hacías a mano en /docs. Con client.post mandas un cuerpo JSON y compruebas que el servidor responde 201 y que calcula bien el precio con el 21%. Una alfombrilla de 10 euros tiene que salir a 12,10:

Python: test_main.py 📋
def test_anadir_producto_calcula_el_iva():
    respuesta = client.post(
        "/productos",
        json={"nombre": "Alfombrilla", "precio": 10},
    )
    assert respuesta.status_code == 201
    datos = respuesta.json()
    assert datos["nombre"] == "Alfombrilla"
    assert datos["precio_con_iva"] == 12.1

Ejecuta pytest. Debería pasar. Ahora viene la trampa: todo está en verde, pero por suerte. El test del listado está escrito antes que el del POST. Mueve test_listar_productos debajo de test_anadir_producto_calcula_el_iva y vuelve a ejecutar: falla, porque el listado ya ve cuatro productos en lugar de tres.

El problema de los tests que se contagian

Esto me costó pillarlo la primera vez que probé una API con una lista en memoria. La lista productos vive en main.py mientras el programa está en marcha, y el POST la modifica. Los tests comparten esa lista, así que lo que hace uno afecta a los siguientes. Un test que pasa o falla según lo que ejecutó otro antes es una trampa: el día que falle, no sabrás si es un fallo real o un contagio.

La regla es que cada test empiece con el mismo punto de partida. Pytest lo resuelve con las fixtures. Imagina que antes de cada comida tienes que poner la mesa y después recogerla: no quieres hacerlo a mano cada vez, quieres que alguien lo haga solo. Una fixture es una función que pytest ejecuta antes (y, si quieres, después) de cada test para dejar el terreno preparado.

Python: test_main.py 📋
import pytest

import main


@pytest.fixture(autouse=True)
def restaurar_productos():
    original = list(main.productos)
    yield
    main.productos[:] = original

Lo que hace: antes del test guarda una copia de la lista, el yield cede el turno al test, y cuando el test acaba la lista vuelve a quedar como estaba. El autouse=True hace que se aplique a todos los tests del archivo sin tener que pedirla uno por uno. Ojo con la línea main.productos[:] = original: con los corchetes y los dos puntos se vacía y rellena la misma lista. Si escribieras main.productos = original solo cambiarías qué lista ve este archivo, y la API seguiría usando la antigua, la contagiada.

Esta fixture funciona porque la API guarda los datos en una lista dentro del propio programa. Con una base de datos de verdad el problema es el mismo y la solución cambia (una base de datos de pruebas, no la tuya), pero el principio no: cada test empieza limpio.

Comprueba que el test sirve: rómpelo a propósito

Un test que nunca ha fallado no te ha demostrado nada. Puede estar comprobando algo que siempre es verdad, y entonces es decoración. Rómpelo tú. Abre main.py y cambia el IVA:

Python: main.py 📋
IVA = 0.10

Ejecuta pytest. El test del POST tiene que ponerse en rojo, con un mensaje donde se ve a qué se comparó cada lado: esperaba 12.1 y llegó 11.0. Además falla en la fila exacta del assert, así que sabes qué comprobación saltó sin abrir el navegador. Devuelve el IVA a 0.21 y vuelve a ejecutarlos para ver todo en verde otra vez.

Esa es la gracia: cuando en el futuro cambies algo y rompas sin querer el cálculo, te enteras en un segundo y no cuando un cliente te escribe que le salen mal los precios.

Muchos casos inválidos con un solo test: parametrize

La API rechaza nombres de menos de dos letras y precios que no sean mayores que cero. Escribir un test por cada caso sería repetir cuatro veces lo mismo. Pytest tiene parametrize: escribes el test una vez, le das una lista de entradas y se ejecuta una vez por cada una. Es el mismo bucle que harías a mano, pero cada entrada cuenta como un test propio y si falla una sabes cuál.

Python: test_main.py 📋
@pytest.mark.parametrize(
    "datos",
    [
        {"nombre": "Alfombrilla", "precio": 0},
        {"nombre": "Alfombrilla", "precio": -5},
        {"nombre": "Alfombrilla", "precio": "gratis"},
        {"nombre": "A", "precio": 10},
        {"nombre": "Alfombrilla"},
    ],
)
def test_datos_invalidos_dan_422(datos):
    respuesta = client.post("/productos", json=datos)
    assert respuesta.status_code == 422

Cinco entradas, un test, cinco resultados. Esto también es seguridad básica: todo lo que llega de fuera es sospechoso, y estos tests demuestran que tu API lo rechaza antes de guardar nada. Si algún día quitas una validación del modelo, el test se pone en rojo y te cuenta que has dejado entrar datos que antes no entraban.

Y como la fixture restaura la lista, comprobar que un dato inválido no se guarda es fácil. Añade este test para cerrar el círculo:

Python: test_main.py 📋
def test_un_dato_invalido_no_se_guarda():
    client.post("/productos", json={"nombre": "Alfombrilla", "precio": -5})
    respuesta = client.get("/productos")
    assert len(respuesta.json()) == 3

El filtro por precio máximo

Falta la ruta que filtra con ?max_precio=. En el test no escribes la parte de la URL a mano: se la pasas a params y el cliente la monta. Con un máximo de 50 euros deben salir el teclado (50) y el ratón (20), y no el monitor:

Python: test_main.py 📋
def test_filtrar_por_precio_maximo():
    respuesta = client.get("/productos", params={"max_precio": 50})
    nombres = [p["nombre"] for p in respuesta.json()]
    assert nombres == ["Teclado mecánico", "Ratón inalámbrico"]

Fíjate en el <= del filtro de main.py: el teclado cuesta justo 50, y este test es el que protege ese límite. Si alguien lo cambia por un <, el teclado desaparece del resultado y el test avisa. Los límites son donde más fallos se esconden, y por eso conviene probar siempre el valor frontera y no solo uno cómodo de por medio.

Ejecutar solo lo que necesitas

Con diez tests da igual, pero cuando crezca el proyecto no querrás esperar a todos para probar uno. Tres variantes que uso a diario:

Terminal 📋
pytest -v
pytest -k iva
pytest test_main.py::test_inicio

La primera lista cada test con su nombre y su resultado, útil para ver qué hay. La segunda ejecuta solo los tests cuyo nombre contiene "iva". La tercera, uno concreto por su ruta completa. Ponerles nombres que se lean como una frase (test_producto_inexistente_da_404) hace que el resultado se entienda sin abrir el código.

Un aviso sobre pedirle los tests a una IA

Es tentador pegar tu main.py en un chat y pedir "escríbeme los tests". Lo que sale suele pasar a la primera, y ahí está el peligro: un test que pasa no es lo mismo que un test que comprueba algo útil. Si lo haces, léelos línea por línea, pregúntate qué cambio en el código los pondría en rojo y haz la prueba de arriba: rómpelo a propósito. Si no se pone en rojo, ese test sobra. Usa la IA para que te explique un fallo de pytest que no entiendes, no para saltarte el entender qué estás comprobando.

El archivo completo

Junto todo en un test_main.py para que compares con el tuyo:

Python: test_main.py 📋
import pytest
from fastapi.testclient import TestClient

import main
from main import app

client = TestClient(app)


@pytest.fixture(autouse=True)
def restaurar_productos():
    original = list(main.productos)
    yield
    main.productos[:] = original


def test_inicio():
    respuesta = client.get("/")
    assert respuesta.status_code == 200
    assert respuesta.json() == {"mensaje": "La API de la tienda funciona"}


def test_listar_productos():
    respuesta = client.get("/productos")
    assert respuesta.status_code == 200
    assert len(respuesta.json()) == 3


def test_ver_producto_existente():
    respuesta = client.get("/productos/1")
    assert respuesta.status_code == 200
    assert respuesta.json()["nombre"] == "Teclado mecánico"


def test_producto_inexistente_da_404():
    respuesta = client.get("/productos/99")
    assert respuesta.status_code == 404
    assert respuesta.json() == {"detail": "Producto no encontrado"}


def test_id_que_no_es_numero_da_422():
    respuesta = client.get("/productos/abc")
    assert respuesta.status_code == 422


def test_anadir_producto_calcula_el_iva():
    respuesta = client.post(
        "/productos",
        json={"nombre": "Alfombrilla", "precio": 10},
    )
    assert respuesta.status_code == 201
    datos = respuesta.json()
    assert datos["nombre"] == "Alfombrilla"
    assert datos["precio_con_iva"] == 12.1


@pytest.mark.parametrize(
    "datos",
    [
        {"nombre": "Alfombrilla", "precio": 0},
        {"nombre": "Alfombrilla", "precio": -5},
        {"nombre": "Alfombrilla", "precio": "gratis"},
        {"nombre": "A", "precio": 10},
        {"nombre": "Alfombrilla"},
    ],
)
def test_datos_invalidos_dan_422(datos):
    respuesta = client.post("/productos", json=datos)
    assert respuesta.status_code == 422


def test_un_dato_invalido_no_se_guarda():
    client.post("/productos", json={"nombre": "Alfombrilla", "precio": -5})
    respuesta = client.get("/productos")
    assert len(respuesta.json()) == 3


def test_filtrar_por_precio_maximo():
    respuesta = client.get("/productos", params={"max_precio": 50})
    nombres = [p["nombre"] for p in respuesta.json()]
    assert nombres == ["Teclado mecánico", "Ratón inalámbrico"]

Son nueve funciones de test, pero el parametrizado cuenta cinco veces, así que pytest debería mostrar trece puntos. Con eso ya puedes cambiar el IVA, añadir una ruta o tocar un modelo y saber en un segundo si has roto algo, sin abrir el navegador.

Qué toca ahora

El siguiente paso concreto es añadir una ruta nueva a la API, por ejemplo DELETE /productos/{id}, y escribir el test antes que el código: primero el test que espera un 204 al borrar y un 404 si ya no existe, verlo fallar, y después escribir la ruta hasta que se ponga en verde. Es la mejor forma de comprobar que has pillado la idea, y te obliga a pensar en qué casos raros puede recibir esa ruta.

Cuando eso te salga solo, el reto siguiente es probar la versión con base de datos del post de FastAPI con SQLModel. Ahí la fixture ya no puede limpiar una lista: tendrás que hacer que los tests usen una base de datos de pruebas, y FastAPI tiene un mecanismo para cambiar esa dependencia solo durante los tests. Ese post usa SQLite para empezar; en un trabajo real sería PostgreSQL o MariaDB en un contenedor, pero la idea de aislar los datos de los tests es la misma.