Lección 47 de 47 · Proyecto final: CRUD de tareas con SQLite✦ WebMCP implementado
Fase 6: tests y despliegue
10 min de lectura4 retos
La app funciona, pero ¿lo sabes o lo crees? En esta última fase le pones tests con pytest a cada capa y la preparas para vivir fuera de tu portátil: configuración por variables de entorno, un Dockerfile, uvicorn con varios procesos y nginx por delante. Es el paso de «funciona en mi máquina» a «funciona».
¿De dónde vienen los nombres?
pytest = py (Python) + inglés test
La herramienta de tests más usada de Python. Busca las funciones que empiezan por test_ y las ejecuta. Es el PHPUnit de Python, sin clases obligatorias.
fixture = inglés fixture (pieza fija; lo que ya está montado antes de empezar)
Una función que prepara algo que los tests necesitan (un cliente, una base de datos limpia) y se lo entrega pidiéndolo por el nombre. Es el setUp() de PHPUnit, pero reutilizable.
tmp_path = inglés temporary path (ruta temporal)
Una fixture de pytest que da una carpeta nueva y vacía para cada test, y la borra después.
monkeypatch = inglés monkey patch (parche «a lo mono»: cambiar algo a la fuerza mientras se ejecuta)
Una fixture que cambia una variable de entorno o un atributo solo durante ese test y lo deja como estaba.
Dockerfile = inglés dock (muelle, donde se carga la mercancía) + file (fichero)
La receta para construir la imagen de un contenedor: qué base usar, qué copiar y qué comando ejecutar.
En 4 ideas
1/4
Un test de pytest es una funcióntest_... con un assert normal, sin clases ni assertSame. Se prueba cada capa por separado: el dominio sin base de datos, el repositorio con ":memory:" y la API con TestClient. En PHP, PHPUnit.
Las fixtures (@pytest.fixture) preparan lo que necesita un test y se piden por nombre. tmp_path y monkeypatch hacen que cada test use su propia base de datos y no toque la real.
La configuración sale del entorno (os.environ.get("TAREAS_DB", "tareas.db")), no del código: la misma imagen sirve en desarrollo y en producción. Es el getenv() de PHP.
En el contenedor, uvicorn arranca con --host 0.0.0.0 (si no, nadie de fuera llega) y la base de datos vive en un volumen. En producción, nginx hace proxy_pass a uvicorn, como antes hacía fastcgi_pass a php-fpm.
1 · Probar cada capa por separado
Gracias a las capas, no hace falta levantar nada para probar casi todo. Un test es más rápido y más útil cuanto menos tiene que montar: el dominio se prueba sin base de datos, el repositorio con una base en memoria y solo la API necesita el cliente de pruebas. La regla: probar cada cosa en la capa más baja posible.
#
Capa
Qué se prueba
Con qué
Velocidad
1
app/domain
Reglas: título limpio, etiquetas, errores
Nada: solo assert
Instantánea
2
app/infrastructure/sqlite
Que guarda, busca, borra y falla bien
sqlite3.connect(":memory:")
Muy rápida
3
app/application
Buscar → cambiar → guardar
Un repositorio falso
Instantánea
4
app/infrastructure/api
Códigos HTTP, JSON, validación
TestClient y un fichero temporal
Rápida
Un test de pytest es una función cuyo nombre empieza por test_ y que usa assert. Para entender qué hace pytest por dentro, aquí tienes uno de juguete que busca esas funciones y las ejecuta. Pulsa Ejecutar:
Pythonmain.py
from dataclasses import dataclass, field
classTituloVacio(Exception):
pass@dataclassclassTarea:
titulo: str
etiquetas: list[str] = field(default_factory=list)
def__post_init__(self):
self.titulo = self.titulo.strip()
ifnotself.titulo:
raiseTituloVacio("el título no puede estar vacío")
deftest_el_titulo_se_limpia():
assertTarea(" Comprar pan ").titulo == "Comprar pan"deftest_titulo_vacio_no_puede_existir():
try:
Tarea(" ")
exceptTituloVacio:
returnraiseAssertionError("debería haber lanzado TituloVacio")
deftest_las_etiquetas_no_se_comparten():
a, b = Tarea("a"), Tarea("b")
a.etiquetas.append("casa")
assert b.etiquetas == []
# Un pytest de juguete: busca las funciones test_* de este fichero y las ejecuta.
pruebas = [(n, f) for n, f inlist(globals().items()) if n.startswith("test_") andcallable(f)]
for nombre, prueba in pruebas:
try:
prueba()
print("PASSED", nombre)
exceptAssertionErroras error:
print("FAILED", nombre, error)
print(len(pruebas), "pruebas")
from dataclasses import dataclass
import pytest
classTituloVacio(Exception):
pass@dataclassclassTarea:
titulo: strdef__post_init__(self):
self.titulo = self.titulo.strip()
ifnotself.titulo:
raiseTituloVacio("el título no puede estar vacío")
deftest_el_titulo_se_limpia():
assertTarea(" Comprar pan ").titulo == "Comprar pan"deftest_titulo_vacio_no_puede_existir():
with pytest.raises(TituloVacio):
Tarea(" ")
¿Por qué? · En PHP no existe
¿Por qué un assert a secas y no assertSame, assertEquals…? En PHPUnit hay decenas
PHPUnit necesita un método por cada tipo de comparación porque assert de PHP no cuenta qué falló. pytest reescribe tus assert antes de ejecutarlos: guarda el valor de cada parte, y si falla, te dice exactamente qué había a cada lado. Un solo assert vale para todo: igualdad, in, is None, comparaciones.
Mira lo que cuenta pytest cuando un test falla (el test espera "Comprar pan ", con un espacio sobrante):
$ pytest
============================= test session starts ==============================
collected 1 item
tests/test_fallo.py F [100%]
=================================== FAILURES ===================================
___________________________ test_el_titulo_se_limpia ___________________________
def test_el_titulo_se_limpia():
titulo = " Comprar pan ".strip()
> assert titulo == "Comprar pan "
E AssertionError: assert 'Comprar pan' == 'Comprar pan '
E
E - Comprar pan
E ? -
E + Comprar pan
tests/test_fallo.py:3: AssertionError
=========================== short test summary info ============================
FAILED tests/test_fallo.py::test_el_titulo_se_limpia - AssertionError: assert...
============================== 1 failed in 0.03s ===============================
El ? y el - señalan el carácter que sobra. Sin escribir un mensaje. Esto, en PHPUnit, son assertSame con un mensaje de tu cosecha.
2 · pytest y las fixtures: preparar sin repetir
Las fixtures son funciones que preparan lo que un test necesita. El test las pide escribiendo su nombre como parámetro, y pytest las ejecuta antes y le pasa el resultado. Con una sola fixture parametrizada, los mismos tests se ejecutan contra la memoria y contra SQLite, la prueba de que las dos cumplen el mismo contrato:
params=[RepositorioMemoria, sqlite_en_memoria] hace que pytest ejecute cada test dos veces, una con cada repositorio (los nombres [memoria] y [sqlite] salen de ids). Si algún día añades un repositorio nuevo, lo metes en la lista y pasa los mismos tests. Esa misma idea, escrita sin pytest y ejecutable aquí:
Pythonmain.py
import sqlite3
from dataclasses import dataclass, replace
classTareaNoEncontrada(Exception):
pass@dataclassclassTarea:
titulo: str
hecha: bool = False
id: int | None = NoneclassRepositorioMemoria:
def__init__(self):
self._tareas = {}
self._siguiente = 1defguardar(self, tarea):
if tarea.id isNone:
tarea = replace(tarea, id=self._siguiente)
self._siguiente += 1self._tareas[tarea.id] = replace(tarea)
return tarea
defbuscar_por_id(self, id):
if id notinself._tareas:
raiseTareaNoEncontrada(id)
returnreplace(self._tareas[id])
defborrar(self, id):
if id notinself._tareas:
raiseTareaNoEncontrada(id)
delself._tareas[id]
classRepositorioSqlite:
def__init__(self):
self._conexion = sqlite3.connect(":memory:")
self._conexion.execute(
"CREATE TABLE tareas (id INTEGER PRIMARY KEY AUTOINCREMENT, titulo TEXT NOT NULL, hecha INTEGER NOT NULL DEFAULT 0)"
)
defguardar(self, tarea):
cursor = self._conexion.execute(
"INSERT INTO tareas (titulo, hecha) VALUES (?, ?)", (tarea.titulo, int(tarea.hecha))
)
self._conexion.commit()
returnreplace(tarea, id=cursor.lastrowid)
defbuscar_por_id(self, id):
fila = self._conexion.execute("SELECT id, titulo, hecha FROM tareas WHERE id = ?", (id,)).fetchone()
if fila isNone:
raiseTareaNoEncontrada(id)
returnTarea(fila[1], bool(fila[2]), fila[0])
defborrar(self, id):
cursor = self._conexion.execute("DELETE FROM tareas WHERE id = ?", (id,))
if cursor.rowcount == 0:
raiseTareaNoEncontrada(id)
self._conexion.commit()
defcontrato_repositorio(repositorio):
"""Lo que TODO repositorio tiene que cumplir. Falla con assert si no."""
guardada = repositorio.guardar(Tarea("Comprar pan"))
assert guardada.id isnotNone, "guardar tiene que dar un id"assert repositorio.buscar_por_id(guardada.id).titulo == "Comprar pan"
repositorio.borrar(guardada.id)
try:
repositorio.buscar_por_id(guardada.id)
exceptTareaNoEncontrada:
returnraiseAssertionError("buscar tras borrar tendría que lanzar TareaNoEncontrada")
for nombre, fabrica in [("memoria", RepositorioMemoria), ("sqlite", RepositorioSqlite)]:
contrato_repositorio(fabrica())
print("cumple el contrato:", nombre)
¿Por qué? · En PHP no existe
¿Por qué una fixture y no un setUp() como en PHPUnit?
setUp() se ejecuta antes de todos los tests de la clase, los necesiten o no, y vive atado a esa clase. Una fixture se ejecuta solo para los tests que la piden, vale para cualquier fichero (en conftest.py) y se puede combinar con otras (la fixture cliente usa tmp_path y monkeypatch).
Además, una fixture puede usar yield: lo que hay antes prepara y lo de después limpia (igual que el tearDown()), todo en una sola función. Es el gestor de contexto del módulo 07 aplicado a los tests.
3 · Probar la API con TestClient
Para la capa de arriba usamos el TestClient que ya viste: llama a la app sin abrir ningún puerto. Lo envolvemos en una fixture en tests/conftest.py, que además le da a cada test su propia base de datos en una carpeta temporal:
Pythonmain.py
import pytest
from fastapi.testclient importTestClientfrom app.main import app
@pytest.fixturedefcliente(tmp_path, monkeypatch):
monkeypatch.setenv("TAREAS_DB", str(tmp_path / "tareas.db"))
withTestClient(app) as cliente:
yield cliente
tmp_path es una carpeta nueva y vacía por test. La base de datos de cada test nace ahí y nunca toca tu tareas.db.
monkeypatch.setenv("TAREAS_DB", ...) cambia la variable de entorno que lee ruta_bd(), y al acabar el test la deja como estaba. Así la app usa el fichero de prueba sin cambiar una línea de código.
with TestClient(app) as cliente hace que se ejecute el lifespan: se migra la base de datos al empezar, como en producción. Sin el with, la tabla no existiría.
yield cliente entrega el cliente al test y, al terminar, el with se cierra solo.
Y con esa fixture, los tests de la API se leen casi como una conversación. Esto es tests/test_api.py:
¿Por qué comprobar 404 y 422, no solo el camino feliz?
Porque los errores son parte de la API. Un cliente depende de que «no existe» sea un 404 y no un 500, y de que un título vacío sea un 422. Un fallo en esos códigos no rompe nada a la vista, pero rompe a quien consume la API.
Los tests de errores son los que más valor dan: son justo el trabajo que cuesta recordar. Cada vez que arregles un bug de la API, empieza por escribir el test que lo reproduce: falla, lo arreglas, pasa, y no vuelve.
4 · Configuración: variables de entorno, no código
En tu portátil la base de datos es tareas.db; en el servidor, un fichero en otra carpeta. Si escribes la ruta en el código, hay que cambiar el código para cambiar el entorno. En su lugar, el programa pregunta al entorno, y quien lo ejecuta decide. En PHP lo haces con getenv() o $_ENV; en Python, con os.environ:
import os
os.environ["PUERTO"] = "9000"
ruta = os.environ.get("TAREAS_DB", "tareas.db")
puerto = int(os.environ.get("PUERTO", "8000"))
print(ruta, puerto)
os.environ se comporta como un diccionario: .get(clave, por_defecto) es el getenv(...) ?: por_defecto de PHP.
Una variable de entorno es siempre texto: "9000", no 9000. Hay que convertirla (int(...)), igual que el (int) de PHP. Un bool con "False" sería True, porque cualquier texto no vacío lo es.
Las dos primeras líneas de asignación solo están para la demostración: en la vida real quien pone PUERTO es el sistema, no tu programa.
¿Por qué? · En PHP no existe
¿Por qué configurar con el entorno y no con un fichero config.py por cada servidor?
Porque así la misma imagen de Docker sirve en tu portátil, en pruebas y en producción: lo único que cambia es el entorno que le das al arrancar. Sin reconstruir nada, sin editar ficheros dentro del contenedor.
Y porque los secretos no se escriben en el código: ni claves de APIs ni contraseñas de bases de datos van en el repositorio. Se inyectan al arrancar. Es el principio de la «aplicación de doce factores»: config in the environment.
5 · El Dockerfile: la app en una caja
Un contenedor es una caja con tu app y todo lo que necesita (Python, las librerías), igual en cualquier máquina. En PHP ya conoces el patrón: una imagen php:8.5-fpm con tu código copiado y nginx delante. En Python es más corto, porque uvicorn hace de servidor y no hace falta FPM. Este es el Dockerfile del proyecto (lo hemos construido y arrancado de verdad):
Parte de una imagen con Python (la slim pesa poco)
FROM php:8.5-fpm
2
COPY requirements.txt . + pip install
Instala las librerías antes de copiar el código, para que Docker reutilice esa capa
composer install
3
COPY app ./app
Copia el código
COPY src/ /var/www/
4
USER tareas
Ejecuta con un usuario normal, no root
USER www-data
5
ENV TAREAS_DB=/data/tareas.db
Pone la base de datos en /data, que será un volumen
Las variables del .env
6
CMD ["uvicorn", ...]
El comando que arranca el servidor
php-fpm (y un nginx aparte)
Se construye y se arranca así. Fíjate en el volumen (-v tareas-datos:/data): sin él, la base de datos viviría dentro del contenedor y se perdería al borrarlo:
$ docker build -t tareas .
$ docker run -d --name tareas -p 8000:8000 -v tareas-datos:/data tareas
$ docker logs tareas
INFO: Started server process [1]
INFO: Waiting for application startup.
INFO: Application startup complete.
INFO: Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
¿Por qué? · En PHP no existe
¿Por qué --host 0.0.0.0? En PHP no tocabas esto
Por defecto, uvicorn escucha en 127.0.0.1: solo acepta conexiones de su propia máquina. Dentro de un contenedor, «su propia máquina» es solo el contenedor, así que ni tu navegador ni nginx podrían llegar, aunque publiques el puerto con -p.
0.0.0.0 significa «escucha en todas las direcciones del contenedor». Por eso no hace falta en tu portátil sin Docker, y es obligatorio dentro. En PHP no lo veías porque nginx y php-fpm hablaban por un socket interno.
6 · Detrás de nginx y con varios procesos
En producción no se expone uvicorn directamente. Lo normal es nginx por delante: gestiona el HTTPS, los ficheros estáticos y las peticiones lentas, y reenvía el resto a uvicorn. Es la misma foto que con PHP; solo cambia una directiva:
Las tres líneas proxy_set_header le cuentan a uvicorn quién llamó de verdad (X-Forwarded-For) y por qué protocolo (X-Forwarded-Proto), porque desde su punto de vista todas las peticiones llegan desde nginx. Uvicorn las usa si le dices en qué IPs confiar (--forwarded-allow-ips) y trae --proxy-headers activado por defecto.
Un proceso de uvicorn usa un núcleo de la CPU. Para aprovechar más, hay dos caminos:
uvicorn app.main:app --workers 4: uvicorn arranca y supervisa 4 procesos. Es lo más sencillo y suficiente para empezar.
gunicorn con workers de uvicorn: gunicorn app.main:app -k uvicorn_worker.UvicornWorker -w 4 -b 0.0.0.0:8000. Gunicorn es un gestor de procesos veterano (reinicia los que caen, recarga sin cortar). Hay que instalar gunicorn y uvicorn-worker. El módulo uvicorn.workers está obsoleto: usa el paquete uvicorn-worker.
¿Cuántos? Para empezar, la regla de gunicorn: (2 × núcleos) + 1. Con un servidor async como uvicorn suele bastar con menos (a veces uno por núcleo). Mide antes de subirlo: más workers consumen más memoria y no ayudan si el cuello de botella es la base de datos.
¿Por qué? · En PHP no existe
¿Por qué con varios workers hay que mirar SQLite con cuidado? En PHP-FPM tampoco era un problema
Cada worker es un proceso con sus propias conexiones al mismo fichero. SQLite deja un solo escritor a la vez: si dos workers escriben a la vez, uno espera (sqlite3.connect espera 5 segundos por defecto antes de dar database is locked). Para una app de tareas con poco tráfico es de sobra, pero es un límite real.
Para aliviarlo, SQLite tiene el modo WAL (PRAGMA journal_mode=WAL), que deja leer mientras otro escribe. Y si el límite aprieta de verdad, el siguiente paso no es más workers, sino otra base de datos. Con la arquitectura de capas de este proyecto, ese cambio vive entero dentro de app/infrastructure/sqlite.
La pregunta que te vas a hacer
Vale, pero… ¿cómo lo despliego en un servidor de verdad, con HTTPS y todo?
Lo habitual es un servidor con Docker, nginx (o Caddy) por delante y un certificado de Let's Encrypt. Estos son los recursos más usados:
Escribe leer_ajustes(entorno): recibe un diccionario (tu os.environ) y devuelve otro con db (variable TAREAS_DB, por defecto "tareas.db"), puerto (variable PUERTO como int, por defecto 8000) y debug (variable DEBUG: True solo si vale 1, true o si, en cualquier mayúscula; por defecto False). Es el getenv() de PHP con conversiones.
Al pulsar Comprobar, unos tests ocultos prueban tu código en tu navegador, con Python 3.14.
Pythonmain.py · editable
Pista.entorno.get("CLAVE", "por_defecto") da el texto; conviértelo con int(...). Para debug, pasa el texto a minúsculas con .lower() y comprueba si está en {"1", "true", "si"}: un bool("False") sería True.
Reto 2 de 4 · ✓ Resuelto
Cuántos workers
Escribe workers_recomendados(nucleos, maximo=9): la regla de gunicorn (2 × núcleos) + 1, sin pasar de maximo. Si nucleos es None o menor que 1, devuelve 1. Es el pm.max_children de php-fpm, calculado.
Al pulsar Comprobar, unos tests ocultos prueban tu código en tu navegador, con Python 3.14.
Pythonmain.py · editable
Pista. Primero el caso raro (nucleos is None or nucleos < 1 → 1) y luego min(2 * nucleos + 1, maximo).
Reto 3 de 4 · ✓ Resuelto
El comando de arranque
Escribe comando_arranque(ajustes): devuelve la lista de argumentos para ejecutar uvicorn: ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "<puerto>"]. Si workers es mayor que 1, añade "--workers", "<n>"; si debug es True, añade "--reload" (y en modo debug nunca--workers, porque --reload no se lleva bien con varios procesos). Los números van como texto. Es el CMD del Dockerfile construido a mano.
Al pulsar Comprobar, unos tests ocultos prueban tu código en tu navegador, con Python 3.14.
Pythonmain.py · editable
Pista. Parte de la lista base con str(ajustes["puerto"]). Después, un if ajustes["debug"]: que añade --reload y, solo si no es debug, un elif para los workers (comando += [...]).
Reto 4 de 4 · ✓ Resuelto
Un test de contrato para repositorios
Escribe contrato_repositorio(repositorio), la función que prueba que cualquier repositorio cumple lo básico, usando assert. Tiene que comprobar que: (1) guardar devuelve una tarea con id; (2) buscar_por_id devuelve una tarea con el mismo título; (3) tras borrar, buscar_por_idlanza TareaNoEncontrada. Si algo falla, se lanza AssertionError; si todo va bien, no devuelve nada. Es un test de PHPUnit reutilizable.
Al pulsar Comprobar, unos tests ocultos prueban tu código en tu navegador, con Python 3.14.
Pythonmain.py · editable
Pista. Tres assert seguidos, y para el último un try / except TareaNoEncontrada: return seguido de raise AssertionError(...): si no se lanza el error, es que el repositorio falla.
Resumen
Lo que te llevas de esta lección
Cada capa se prueba en la más baja posible: el dominio con un assert, el repositorio con ":memory:" y la API con TestClient (en PHP, PHPUnit con mocks).
Las fixtures preparan lo que el test pide por su nombre; tmp_path y monkeypatch dan a cada test su propia base de datos (en PHP, setUp()).
La configuración va en el entorno: os.environ.get("TAREAS_DB", "tareas.db") (en PHP, getenv()), y siempre llega como texto.
En el contenedor uvicorn escucha en --host 0.0.0.0, y la base de datos SQLite vive en un volumen (/data).
En producción, nginx hace proxy_pass a uvicorn (con --workers N o gunicorn + uvicorn-worker), igual que antes hacía fastcgi_pass a php-fpm.
Para recordarlo: «Capas, Entorno, Caja»
CCapas cada una con su test
EEntorno os.environ.get(...)
CCaja Dockerfile + --host 0.0.0.0
Para pasar de tu portátil al servidor: Capas probadas una a una, configuración en el Entorno y todo en una Caja (Docker) con nginx delante.