Validar que tus endpoints cumplan con el contrato definido es tan importante como construirlos. Con pruebas unitarias en FastAPI usando PyTest y Cursor, puedes garantizar que cada respuesta respete la estructura acordada sin depender de la base de datos. Esto te sirve si trabajas con APIs en Python y quieres acelerar tu flujo de testing apoyado en IA.
¿Cómo indexar la documentación de FastAPI en Cursor?
Antes de pedirle a Cursor que escriba pruebas, necesita conocer cómo se testean los endpoints en FastAPI. La estrategia es la misma que usaste con Alembic y SQLAlchemy: indexar la documentación oficial.
- Copia la URL de la documentación de testing de FastAPI.
- Abre los settings de Cursor y agrega la fuente como
FastAPIDocs.
- Confirma y espera a que termine la indexación.
Con eso, Cursor ya puede generar código alineado con las prácticas reales del framework.
¿Por qué indexar la documentación antes de pedir pruebas? Porque sin contexto oficial, el modelo improvisa. Indexarla le da referencias actualizadas sobre TestClient, fixtures y dependency overrides.
¿Qué instrucciones darle a Cursor para generar las pruebas?
La clave está en ser explícito con tres cosas: objetivo, framework y estrategia de aislamiento. En el prompt le pides crear pruebas unitarias para los endpoints de main que cumplan con el contrato definido en contracts, usando PyTest como framework y haciendo mock del course service para no depender de la base de datos.
Aquí aparece un detalle importante. Si el course service no está inyectado como dependencia de FastAPI, mockearlo se vuelve complicado. Por eso, antes de generar las pruebas, conviene pedir un refactor para que el servicio se consuma como un Depends de FastAPI.
¿Qué cambia con la inyección de dependencias?
El endpoint get_courses deja de recibir directamente la sesión de base de datos y pasa a recibir el course_service, que se resuelve con una función get_course_service encargada de instanciar el servicio. Ese pequeño cambio habilita algo poderoso: puedes sobreescribir la dependencia en pruebas con un mock limpio.
¿Cómo se estructura el archivo test_main.py?
Cursor genera el archivo de pruebas siguiendo buenas prácticas de PyTest. Lo interesante es cómo organiza el aislamiento:
- Crea un mock de los cursos y del detalle para evitar consultar la base de datos.
- Define ese mock como fixture de PyTest, lo que permite reutilizarlo como dependencia en cada método de prueba.
- Cubre el endpoint de health, el root y el de cursos, validando que la estructura del contrato esté presente en cada respuesta.
Esto se traduce en pruebas rápidas, deterministas y enfocadas en lo que importa: que el endpoint devuelva lo prometido.
¿Qué es un fixture en PyTest? Es una función que prepara datos o dependencias antes de cada prueba. En FastAPI se usa para inyectar mocks del servicio sin tocar la base de datos real.
¿Cómo ejecutar y depurar las pruebas desde Cursor?
El plugin de Python para Cursor incluye una integración visual con PyTest que ahorra tiempo al depurar. Para activarla:
- Abre la paleta con
Command + Shift + P y escribe tests.
- Selecciona configurar pruebas unitarias y elige PyTest como framework.
- Define el root directory del servicio, en este caso
app.
Después de configurarlo, aparece un botón de play junto a cada prueba. Desde ahí puedes ejecutar tests individuales o lanzarlos en modo debug.
¿Cómo aprovechar los breakpoints en pruebas y endpoints?
Puedes poner un breakpoint dentro del test y otro dentro del endpoint en main.py. Al correr el debug, el flujo se detiene primero en la prueba, luego entra al endpoint donde el course_service ya es el mock configurado, y finalmente regresa con el response HTTP. En la debug console inspeccionas el JSON, los datos retornados y validas que todo coincida con el contrato.
Ese ciclo de inspección es oro cuando una prueba falla y necesitas entender si el problema está en el mock, en el endpoint o en la serialización de la respuesta.
¿Qué reto puedes tomar después de las pruebas unitarias?
El siguiente paso natural es subir el nivel y pasar de pruebas unitarias a pruebas de integración. En lugar de mockear el course service, dejas que se ejecute realmente y que invoque a la base de datos. Eso te obliga a configurar una base de datos de pruebas, manejar transacciones y limpiar el estado entre tests.
Es un ejercicio incómodo al principio, pero te da confianza real sobre el comportamiento del sistema completo. Cuéntame en los comentarios qué pasos seguiste, qué se rompió en el camino y cómo lo resolviste.
