Fusionaste la PR. La CI estaba en verde. El despliegue finalizó sin un solo error en los registros. Veinte minutos después, empiezan a llegar tickets de soporte: un endpoint de pago está devolviendo errores 500 para una parte de los clientes, y no tienes idea de por qué, ya que nada falló en el pipeline.
Esta es la brecha que cierra el canary testing (pruebas canary). Las pruebas unitarias y las pruebas de integración verifican tu código contra lo que esperabas. No pueden verificar tu código contra el mundo real: tráfico de producción, la base de datos real, la API de terceros que silenciosamente cambió su límite de tasa el martes pasado. El canary testing despliega una nueva versión a una pequeña fracción del tráfico real primero, observa cómo se comporta y solo amplía el lanzamiento una vez que las señales parecen saludables. Si algo se rompe, se rompe para el 2% de los usuarios durante dos minutos en lugar del 100% de los usuarios durante una hora.
Específicamente para las API, puedes hacer algo mejor que solo observar paneles y esperar. Puedes ejecutar un conjunto de pruebas real contra el canary en el momento en que se activa, verificar los códigos de estado, los esquemas de respuesta y la latencia, y luego autorizar el lanzamiento basándote en el resultado. Ese es el flujo de trabajo que esta guía detalla, y lo conectaremos de principio a fin con Apidog y su ejecutor de línea de comandos para que todo resida dentro de tu pipeline de CI/CD existente.
Qué es realmente el canary testing
El nombre proviene del canario en una mina de carbón. Los mineros llevaban un pájaro enjaulado bajo tierra porque reaccionaba al gas tóxico mucho antes que los humanos. Si el pájaro dejaba de cantar, salías. Un lanzamiento canary funciona de la misma manera: una muestra pequeña y prescindible asume el riesgo primero para que el resto de tus usuarios nunca tengan que hacerlo.
En la práctica, un despliegue canary significa ejecutar dos versiones de tu servicio al mismo tiempo:
- Estable: la versión de producción actual, que atiende la mayor parte del tráfico.
- Canary: la nueva versión, que atiende un pequeño porcentaje (a menudo del 1% al 5% para empezar).
Un balanceador de carga, una malla de servicios o un controlador de entrada divide el tráfico entre ellos. Observas la tasa de errores, la latencia y las métricas comerciales del canary en comparación con la línea base estable. Si el canary se mantiene, le transfieres más tráfico en pasos hasta que atiende el 100% y se convierte en el nuevo estable. Si se degrada, rediriges todo de vuelta a la versión estable y el lanzamiento defectuoso nunca llega a la mayor parte de tu audiencia.
El canary testing es la mitad activa de ese ciclo. En lugar de esperar a que el tráfico orgánico revele un error, lanzas un conjunto deliberado de solicitudes de API al canary y verificas las respuestas. El monitoreo pasivo te dice que algo salió mal después de que los usuarios lo experimentaron. El canary testing activo te dice que algo está mal antes de que amplíes el radio de impacto.
Canary testing vs. las pruebas que ya haces
El canary testing no reemplaza tus otras pruebas. Se sitúa al final de la cadena y detecta una clase diferente de fallos.
| Tipo de prueba | Se ejecuta contra | Detecta | Pasa por alto |
|---|---|---|---|
| Pruebas unitarias | Funciones aisladas | Errores de lógica | Cualquier cosa que involucre E/S real |
| Pruebas de integración | Componentes interconectados | Contratos rotos entre servicios | Configuración de producción, forma de datos real |
| Pruebas de humo | Una compilación desplegada | Fallos básicos de "¿Está funcionando?" | Regresiones de comportamiento sutiles |
| Canary testing | Un lanzamiento en vivo en infraestructura real | Mala configuración, deriva del entorno, regresiones de rendimiento, interrupciones parciales | Errores que solo se muestran a gran escala |
La razón por la que el canary testing se gana su lugar: una gran parte de los incidentes de producción provienen de cosas que ningún entorno de preproducción puede reproducir completamente. Una variable de entorno faltante. Una configuración de pool de conexiones obsoleta. Un índice de base de datos que existe en staging pero no en producción. Una dependencia de nivel inferior que se comporta de manera diferente bajo una autenticación real. Tu código es correcto; el entorno que lo rodea no lo es. El canary testing es la primera vez que tu nuevo lanzamiento se encuentra con ese entorno, y quieres que se encuentre con el dos por ciento del tráfico, no con todo.
Si quieres el contexto más amplio de dónde encaja esto, nuestra guía sobre cómo automatizar pruebas de API en CI/CD cubre las etapas anteriores, y pruebas de humo vs. pruebas de regresión explica los dos tipos de pruebas en los que los canaries se apoyan más.
Qué medir en un canary
Un canary solo es útil si sabes cómo se ve "saludable". Elige un pequeño conjunto de señales y compara el canary con la línea base estable, no con un número absoluto. Una tasa de error del 1.2% podría ser normal para tu servicio; lo que importa es si el canary es significativamente peor que la versión estable en este momento.
Cuatro señales cubren la mayoría de los casos:
- Tasa de error: la proporción de respuestas 5xx, y a menudo 4xx que no deberían ocurrir, como un aumento repentino de 401s después de un cambio de autenticación. Esta es la métrica más importante.
- Latencia: p95 y p99, no el promedio. Un promedio oculta la cola lenta donde los usuarios reales sienten el impacto. Un canary que es 40ms más lento en p99 es una advertencia incluso si la media parece estar bien.
- Corrección de la respuesta: ¿el cuerpo sigue coincidiendo con el esquema? Un 200 OK que devuelve una forma incorrecta es peor que un 500, porque el monitoreo no lo detectará.
- Señales de negocio: éxito en la compra, éxito en el inicio de sesión, artículos añadidos al carrito. Estas detectan regresiones lógicas que son técnicamente respuestas HTTP "exitosas".
Los primeros tres puedes afirmarlos directamente en una prueba de API. Esa es la parte que automatizaremos.
El flujo de trabajo del canary testing, paso a paso
Esta es la forma de un lanzamiento canary controlado por pruebas de API automatizadas. Cada paso es algo que puedes ejecutar desde un pipeline.
- Desplegar la nueva versión como canary junto a la estable.
- Dirigir una pequeña porción de tráfico (por ejemplo, el 5%) al canary.
- Ejecutar un conjunto de pruebas de API automatizadas contra el endpoint del canary.
- Observar la tasa de errores y la latencia durante un breve período de "cocción" (bake period).
- Controlar: si las pruebas pasan y las métricas se mantienen dentro del presupuesto, cambiar más tráfico. Si no, revertir.
- Repetir el aumento (del 5% al 25%, al 50% y al 100%), volviendo a probar en cada paso.
- Promover el canary a estable, retirar la versión antigua.
Las dos partes que merecen tu atención son el paso 3 (el conjunto de pruebas) y el paso 5 (el control/gate). Si los haces bien, el resto es la infraestructura que tu plataforma ya proporciona.
Construyendo el conjunto de pruebas en Apidog
El conjunto de pruebas es el corazón del canary testing, y es donde la mayoría de los equipos suelen recortar. Una "prueba" canary que solo hace ping a /health y verifica un 200 te dice que el proceso comenzó. No te dice nada sobre si tus endpoints reales funcionan.
Un conjunto de pruebas canary real ejercita las rutas importantes: autenticar, leer, escribir y verificar la forma de la respuesta en cada una. Los escenarios de prueba de Apidog te permiten encadenar esas solicitudes, pasar datos entre ellas y afirmar los resultados sin escribir código "pegamento".
Un escenario canary sólido para una API de comercio electrónico se ve así:
- **Paso 1, autenticación.**
POST /auth/logincon una cuenta de prueba. Afirmar200, extraer el token de la respuesta a una variable. - **Paso 2, lectura.**
GET /products?limit=10con el token. Afirmar200, afirmar que la respuesta es un array, afirmar que cada elemento tieneid,nameyprice. - **Paso 3, escritura.**
POST /cartcon un producto conocido. Afirmar201, afirmar que el total del carrito devuelto coincide con el valor esperado. - **Paso 4, verificar estado.**
GET /cart. Afirmar que el artículo que acabas de añadir está presente.
En Apidog construyes cada solicitud una vez y luego añades afirmaciones visualmente. Para las comprobaciones de esquema, puedes validar la respuesta contra el esquema OpenAPI que ya diseñaste, de modo que un cuerpo de respuesta desviado falla la prueba automáticamente. Para la transferencia del token de autenticación, lo extraes de la respuesta del paso 1 y lo referencias como una variable en los pasos posteriores. No se requiere scripting para los casos comunes, y puedes recurrir a los post-procesadores de JavaScript cuando necesites lógica personalizada.
La ventaja es que este mismo escenario se ejecuta de tres maneras a partir de una única definición: manualmente mientras lo construyes, programado como monitoreo sintético una vez que está en vivo, y desde la línea de comandos dentro de tu pipeline canary. Escribes las afirmaciones una sola vez.
Ejecutando el conjunto de pruebas desde la línea de comandos
Para controlar un despliegue, el conjunto de pruebas debe ejecutarse de forma desatendida en CI. Apidog incluye una CLI para esto. Instálala en tu agente de compilación:
npm install -g apidog-cli
Exporta los datos de tu escenario de prueba desde Apidog como un archivo formateado para CLI, o apunta el ejecutor a un escenario por ID usando un token de acceso, luego ejecútalo:
apidog run \
--access-token "$APIDOG_ACCESS_TOKEN" \
-t "$CANARY_SCENARIO_ID" \
-e "$CANARY_ENV_ID" \
-r cli,html,junit
Algunas banderas que vale la pena conocer para el trabajo con canaries:
-t, --test-scenarioejecuta un escenario específico por ID. Usa-f, --test-scenario-folderpara ejecutar una carpeta completa de escenarios.-e, --environmentselecciona el entorno de ejecución. Apunta esto a un entorno cuya URL base sea tu endpoint canary, para que las mismas pruebas puedan dirigirse al canary, staging o producción intercambiando un valor.-r, --reporterscontrola la salida.cliimprime en la consola,htmlproduce un informe compartible yjunitemite XML que GitHub Actions, GitLab, Jenkins y la mayoría de los paneles de CI analizan de forma nativa para mostrar el estado de aprobado/fallido por prueba.-d, --iteration-dataejecuta el conjunto de pruebas una vez por cada fila de un archivo CSV o JSON. Útil para atacar el canary con varios perfiles de usuario o IDs de producto en una sola pasada.--upload-reportenvía el resumen de la ejecución de vuelta a Apidog para que el equipo pueda ver el historial del canary en la aplicación.
La CLI sale con un código distinto de cero cuando una afirmación falla. Ese código de salida es todo el mecanismo de control: tu pipeline ya sabe cómo detenerse en un paso fallido, por lo que una prueba canary fallida detiene el lanzamiento de forma gratuita.
Para una explicación más profunda sobre cómo ejecutar Apidog en pipelines, cómo automatizar pruebas de API en GitHub Actions y la guía de integración de Jenkins cubren esas plataformas en detalle.
Conectándolo a CI/CD
Aquí tienes un trabajo simplificado de GitHub Actions que despliega un canary, lo prueba y solo lo promueve si tiene éxito. La estructura se traslada a GitLab CI, CircleCI o Jenkins con cambios de sintaxis menores.
name: canary-release
on:
push:
branches: [main]
jobs:
canary:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Deploy canary (5% traffic)
run: ./deploy.sh --canary --weight 5
- name: Install Apidog CLI
run: npm install -g apidog-cli
- name: Test the canary
run: |
apidog run \
--access-token "$APIDOG_ACCESS_TOKEN" \
-t "$CANARY_SCENARIO_ID" \
-e "$CANARY_ENV_ID" \
-r cli,junit
env:
APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}
CANARY_SCENARIO_ID: ${{ vars.CANARY_SCENARIO_ID }}
CANARY_ENV_ID: ${{ vars.CANARY_ENV_ID }}
- name: Bake and watch (2 min)
run: sleep 120 && ./check-metrics.sh --service canary --max-error-rate 1.0
- name: Promote canary to 100%
run: ./deploy.sh --promote
- name: Roll back on any failure
if: failure()
run: ./deploy.sh --rollback
La lógica que lo convierte en un canary en lugar de un despliegue simple es el orden. El canary toma una porción de tráfico antes de que se ejecute la prueba, por lo que la prueba ejercita una versión que ya está atendiendo solicitudes reales. El paso if: failure() es la red de seguridad: si el conjunto de pruebas sale con un código distinto de cero, o si la verificación de métricas se dispara, el trabajo falla y la reversión se ejecuta antes de que el tráfico supere el 5%.
Mantén CANARY_ENV_ID apuntando a un entorno de Apidog cuya URL base apunte al canary. Cuando más tarde quieras ejecutar el mismo conjunto de pruebas como una prueba de humo de producción post-despliegue, simplemente intercambias el ID del entorno de producción y no cambias nada más. Esa reutilización es el objetivo: un conjunto de pruebas, muchas etapas.
Errores comunes que hacen inútil el canary testing
**Probar el endpoint equivocado.** Si tu prueba golpea la URL pública balanceada por carga, la solicitud podría caer en una instancia estable en lugar del canary. Dirige la prueba explícitamente al canary, ya sea a través de una cabecera que la malla rutea, un hostname canary dedicado, o un entorno cuya URL base sea la dirección del canary.
**Un período de "cocción" (bake period) de cero.** Algunos fallos solo aparecen bajo carga sostenida: fugas de memoria, agotamiento del pool de conexiones, una caché que se llena. Ejecuta la prueba y luego observa durante unos minutos antes de promover. Un canary que pasa instantáneamente y se promueve en diez segundos apenas es un canary.
**Sin reversión automática.** Si un humano tiene que notar el fallo y hacer clic en revertir, has mantenido la parte más lenta de la respuesta a incidentes en el ciclo. Todo el valor reside en que el pipeline se revierte por sí solo. Conecta la reversión a la condición de fallo y prueba que la reversión funciona.
**Umbrales absolutos en lugar de comparaciones.** "Falla si la tasa de error supera el 1%" se rompe el día en que tu tasa de error de línea base es legítimamente del 1.5%. Compara el canary con la versión estable actual y activa el control cuando el canary sea significativamente peor, no cuando cruce un número que elegiste hace meses.
**Afirmaciones superficiales.** Una respuesta 200 con un cuerpo mal formado pasa una verificación solo por código de estado y falla a tus usuarios. Afirma sobre el esquema de la respuesta, no solo el código. Aquí es donde diseñar tu contrato de API primero y validar las respuestas contra el esquema da sus frutos directamente: tu prueba canary hereda el contrato de forma gratuita.
¿Qué tan amplio debe ser el canary y por cuánto tiempo?
No hay una respuesta universal, pero un valor predeterminado funcional para la mayoría de los equipos es:
- **Comienza con el 5% del tráfico.** Lo suficientemente pequeño como para limitar el daño, lo suficientemente grande como para obtener una señal real en minutos en un servicio con mucho tráfico. Las API de bajo tráfico pueden necesitar una ventana más larga para recopilar suficientes solicitudes.
- **Aumenta en pasos:** del 5% al 25%, al 50% y al 100%. Vuelve a ejecutar el conjunto de pruebas en cada paso. Una regresión que se oculta en el 5% a veces aparece en el 50% cuando un pool de conexiones se satura.
- **Mantén un período de "cocción" (bake period) de al menos unos minutos por paso.** Lo suficientemente largo para que aparezcan los fallos de combustión lenta, lo suficientemente corto como para no estancar cada lanzamiento durante una hora.
Los servicios de alto tráfico pueden avanzar más rápido porque acumulan señales rápidamente. Una API de pagos que maneja miles de solicitudes por segundo tiene suficientes datos para juzgar un canary en un minuto. Una API de administración interna que ve unas pocas solicitudes por hora necesita un período de "cocción" más largo o una carga de prueba sintética más pesada para llegar a un veredicto.
Dónde encaja el canary testing en tu estrategia de lanzamiento
El canary testing se combina naturalmente con las feature flags y los despliegues blue-green, y vale la pena tener clara la diferencia. Blue-green cambia todo el tráfico de un entorno completo a otro de una sola vez; la reversión es rápida, pero no hay exposición gradual. Las feature flags alternan el comportamiento para usuarios elegidos sin un nuevo despliegue. Los lanzamientos canary cambian gradualmente el tráfico real y se basan en señales en vivo.
La mayoría de los equipos maduros utilizan los tres: blue-green para el intercambio de infraestructura, canary para el aumento gradual del tráfico con controles automatizados, y feature flags para un control granular una vez que el código está en vivo. El hilo común es que ninguno de ellos elimina la necesidad de probar el lanzamiento contra producción. Controlan cuánto de tu audiencia está expuesta mientras lo haces.
Esa es la verdadera conclusión. El canary testing no es una herramienta que compras; es una disciplina: desplegar poco, probar el lanzamiento en vivo con afirmaciones reales, observar las señales y controlar el despliegue según el resultado. Las herramientas existen para automatizar cada uno de esos pasos. Con Apidog construyes el conjunto de pruebas una vez, lo ejecutas desde la CLI dentro de cualquier pipeline y dejas que el código de salida decida si el lanzamiento avanza. Los lanzamientos defectuosos se detienen en el 5% del tráfico, y tus usuarios nunca ven los errores 500.
Descarga Apidog para construir tu primer escenario de prueba canary, apunta un entorno a tu endpoint canary y añade un paso de CLI a tu pipeline. La próxima fusión defectuosa se detendrá para un puñado de solicitudes en lugar de para todas ellas.
Preguntas Frecuentes
¿Es el canary testing lo mismo que un despliegue canary? Un despliegue canary es el mecanismo de lanzamiento: servir una nueva versión a una pequeña porción de tráfico. El canary testing es lo que haces durante esa ventana, ejecutando activamente pruebas y afirmando las respuestas en lugar de solo observar paneles. Necesitas el despliegue para realizar las pruebas, pero las pruebas son lo que convierte un lanzamiento arriesgado en uno controlado.
¿Necesito una malla de servicios para hacer canary testing? No. Una malla de servicios como Istio o Linkerd facilita la división del tráfico, pero puedes ejecutar canaries con un peso simple de balanceador de carga, las anotaciones canary de un controlador de entrada, o incluso ponderación DNS. La parte de prueba y control del flujo de trabajo, en la que se centra esta guía, funciona igual independientemente de cómo dividas el tráfico.
¿En qué se diferencia esto de las pruebas de humo después del despliegue? Una prueba de humo generalmente se ejecuta una vez contra un lanzamiento completamente desplegado para confirmar que está en funcionamiento. El canary testing se ejecuta contra un lanzamiento que está sirviendo solo una fracción del tráfico real, y controla el aumento gradual. Las afirmaciones pueden ser idénticas; la diferencia es el momento y la consecuencia. Una prueba de humo fallida significa revertir algo que ya está en vivo para todos; una prueba canary fallida significa detener un lanzamiento en el 5%. Para la distinción entre suites de humo y regresión, consulta nuestra guía comparativa.
¿Puedo reutilizar mis pruebas de API existentes como pruebas canary? A menudo, sí. Si ya tienes escenarios de prueba de Apidog con afirmaciones reales, los apuntas a un entorno cuya URL base es el canary y los ejecutas con la CLI. El trabajo consiste en asegurarte de que tus pruebas afirmen sobre los cuerpos de respuesta y no solo los códigos de estado, y en dirigirlas al canary en lugar de a la URL pública con balanceo de carga.
¿Qué sucede cuando una prueba canary falla en CI? La CLI de Apidog sale con un código distinto de cero ante cualquier afirmación fallida. Tu pipeline trata eso como cualquier paso fallido: el trabajo se detiene, el paso de promoción se omite y se ejecuta tu paso de reversión if: failure(). Ningún humano tiene que estar atento para que ocurra la reversión.