Cómo automatizar pruebas de API en Azure Pipelines (Paso a paso)

Tu API funciona en tu portátil. Pasa todas las comprobaciones en tu cliente de pruebas local. Luego, un compañero de equipo fusiona una rama, se realiza el despliegue y un endpoint que antes devolvía 200 empieza a devolver 500 en producción. Nadie lo detectó, porque nadie ejecutó las pruebas en esa rama. Las ejecutaron en una máquina, una vez, manualmente.

Esa brecha, entre "las pruebas existen" y "las pruebas se ejecutan en cada cambio", es exactamente lo que cierra una pipeline de CI. Si tu código ya reside en Azure Repos o GitHub y tu equipo trabaja con Azure DevOps, Azure Pipelines es el lugar natural para colocar esa red de seguridad. Lo difícil rara vez es el YAML. Es conseguir que tu suite de pruebas API adopte una forma que la pipeline pueda ejecutar sin interfaz gráfica, con el entorno correcto, contra una build recién desplegada, y luego que la build falle ruidosamente cuando algo se rompa.

En resumen

• Azure Pipelines ejecuta tus pruebas API automáticamente en cada commit o PR, para que las regresiones se detecten antes de que se desplieguen.
• Crea tus escenarios de prueba visualmente en Apidog, luego ejecútalos en CI con la CLI de Apidog (apidog-cli) en lugar de escribir y mantener scripts de prueba manualmente.
• La pipeline necesita cuatro cosas: Node.js instalado en el agente, la CLI instalada, tu escenario de prueba accesible a través de un enlace o archivo exportado, y un token de acceso almacenado como secreto.
• Un código de salida distinto de cero de la CLI hace que la build falle automáticamente. Eso es lo que te proporciona una puerta de calidad real.
• Publica el informe HTML o JUnit como un artefacto de la pipeline (o a través de PublishTestResults) para que cualquiera pueda leer si pasa o falla sin abrir los logs.

Qué significa realmente "pruebas API automatizadas en Azure Pipelines"

Azure Pipelines es el servicio de CI/CD dentro de Azure DevOps. Describes una build en un archivo YAML (azure-pipelines.yml) que reside en tu repositorio, y Azure ejecuta ese archivo en un agente alojado o autoalojado cada vez que se dispara un disparador: un push, una pull request, una programación o una ejecución manual.

Para las pruebas API, el trabajo es sencillo en su forma:

1. Iniciar un agente (una VM limpia).
2. Instalar todo lo que necesite tu ejecutor de pruebas.
3. Ejecutar las pruebas API contra un entorno objetivo.
4. Informar los resultados y establecer el estado de la build en función de ellos.

El detalle que confunde a la gente es el paso 3. Un cliente API local es interactivo; haces clic en "Enviar", revisas la respuesta con la vista, lees una marca de verificación verde. Una pipeline no tiene a nadie que haga clic ni a nadie que revise. Necesitas una forma de ejecutar las mismas aserciones sin un humano y sin una GUI. Esa es la razón por la que existe un ejecutor de línea de comandos.

Si deseas una introducción más amplia a los conceptos de CI aquí, la diferencia entre integración continua, entrega continua y despliegue continuo merece una lectura rápida antes de configurar tu primera pipeline.

Por qué diseñar pruebas en Apidog y ejecutarlas con la CLI

Podrías escribir pruebas API en código puro. Elige un lenguaje, incorpora una librería HTTP y un framework de aserciones, crea manualmente cuerpos de solicitud, analiza respuestas, gestiona tokens de autenticación y mantén todo sincronizado con una API que cambia en cada sprint. Los equipos hacen esto. También dedican una cantidad desproporcionada de tiempo a mantenerlo.

Apidog toma un camino diferente. Construyes escenarios de prueba visualmente: encadenas solicitudes, pasas datos de una respuesta a la siguiente solicitud, añades aserciones sobre códigos de estado, encabezados y campos JSON, y ejecutas el mismo escenario con múltiples filas de datos. Debido a que Apidog ya contiene tus definiciones de API, las pruebas se mantienen cerca de la especificación. Cuando el esquema cambia, ves la desviación en lugar de descubrirla en producción.

La pieza que conecta ese trabajo visual con la CI es la CLI de Apidog, un ejecutor de línea de comandos publicado en npm. Ejecuta un escenario de prueba guardado sin interfaz gráfica y sale con un código de estado que refleja el resultado: 0 si todo pasó, distinto de cero si alguna aserción falló. Ese código de salida es el contrato que todo sistema de CI entiende. Azure Pipelines lo lee y decide si la build es verde o roja. Diseñas una vez en la GUI, y el mismo escenario se ejecuta sin cambios en la pipeline.

Este es el mismo modelo que funciona para GitHub Actions, GitLab CI y Jenkins. Azure Pipelines es solo otro host para el mismo comando CLI, lo que significa que el conocimiento se transfiere si tu equipo alguna vez cambia de plataforma.

Prerrequisitos

Antes de construir la pipeline, ten esto en su lugar:

• Un proyecto de Apidog con al menos un escenario de prueba. Abre la sección de escenarios de prueba, crea un escenario, añade algunas solicitudes y adjunta aserciones. Ejecútalo una vez localmente y confirma que pasa. Si es inestable en tu máquina, lo será en CI.
• Un token de acceso de Apidog. La CLI se autentica con un token de acceso personal de la configuración de tu cuenta de Apidog. Trátalo como una contraseña; lo almacenarás como un secreto de pipeline, nunca en el YAML.
• Un proyecto de Azure DevOps con un repositorio. Tu azure-pipelines.yml residirá en la raíz del repositorio.
• Familiaridad con Node.js (ligera). La CLI se ejecuta en Node, por lo que el agente necesita Node instalado. Los agentes alojados de Azure ya lo tienen; solo tendrás que elegir una versión.
• Un entorno objetivo accesible. Tus pruebas deben interactuar con una API en ejecución; una URL de staging, un despliegue de vista previa o un servicio que la pipeline inicie por sí misma. Decide cuál antes de escribir el disparador.

Una nota rápida sobre qué objetivo probar. Ejecutar la suite contra producción en cada commit es arriesgado y a menudo imposible (no querrás datos de prueba en producción). La mayoría de los equipos dirigen las pruebas de CI a un entorno de staging o a un despliegue de vista previa por rama. Los entornos de Apidog hacen que esto sea limpio: mantén un entorno Staging con su propia URL base y variables, y dile a la CLI cuál usar en tiempo de ejecución.

Paso 1: Poner tu escenario de prueba en una forma ejecutable

La CLI necesita saber qué escenario ejecutar. Apidog te ofrece dos formas de proporcionárselo.

Opción A, ejecutar desde un enlace compartido en línea. En Apidog, abre tu escenario de prueba, elige ejecutarlo a través de la CLI, y Apidog genera un comando que apunta al escenario a través de la red. Esta es la opción de menor mantenimiento: la pipeline siempre ejecuta la versión actual del escenario, y no tienes que commitear archivos de prueba al repositorio. La desventaja es que la pipeline depende de que ese enlace sea accesible en tiempo de ejecución.

Opción B, exportar el escenario a un archivo y hacer commit. Exporta el escenario (y su entorno) a un archivo local, commitealo junto con tu código y apunta la CLI a la ruta del archivo. Esto fija la prueba a un commit específico, que es lo que quieres si te importa la reproducibilidad; las pruebas que se ejecutaron son exactamente las pruebas de ese commit. La desventaja es que tienes que reexportar cuando el escenario cambia.

Para la mayoría de los equipos que están empezando, la Opción A es más rápida de configurar. Para trabajos regulados o con muchas auditorías, la reproducibilidad de la Opción B es una ventaja. También puedes combinar: basado en enlaces para ramas de características de rápido movimiento, basado en archivos para ramas de lanzamiento.

De cualquier manera, anota el comando de ejecución exacto que te proporciona Apidog. Se parecerá a esto:

apidog run https://api.apidog.com/api/v1/test-scenarios/<scenario-id> \
 -t <access-token> \
 -e <environment-id>

Las banderas en las que más te apoyarás:

• la referencia del escenario (un enlace en línea o una ruta de archivo local),
• -t / token de acceso para autenticación,
• -e para qué entorno ejecutar,
• una opción de reportero para controlar el formato de salida (texto CLI, HTML o un resumen legible por máquina),
• un recuento de iteraciones cuando quieras que el escenario se repita sobre un conjunto de datos.

Confirma los nombres exactos de las banderas con el comando de ejecución que Apidog genera para tu escenario; el ejecutor imprime el uso con apidog run --help. No adivines las banderas; copia las que te da Apidog y parametriza los secretos.

Paso 2: Verifica primero que la CLI funciona localmente

Nunca depures una herramienta nueva dentro de CI. Los bucles de retroalimentación de la pipeline son lentos y los logs son más ruidosos que tu terminal. Obtén primero una ejecución exitosa en tu propia máquina.

Instala la CLI:

npm install -g apidog-cli

Luego ejecuta tu escenario:

apidog run https://api.apidog.com/api/v1/test-scenarios/<scenario-id> \
 -t "$APIDOG_ACCESS_TOKEN" \
 -e "<staging-environment-id>"

Estás comprobando tres cosas:

1. El comando finaliza e imprime un resumen de éxito/fallo.
2. El código de salida coincide con el resultado. Ejecuta echo $? justo después; debe ser 0 en caso de éxito y distinto de cero en caso de fallo.
3. El entorno se resolvió correctamente; las solicitudes llegaron a tu URL de staging, no a una local que quedó.

Esa verificación del código de salida importa más de lo que parece. Si la CLI sale con 0 incluso cuando falla una aserción, tu pipeline se pondrá en verde con código roto, lo cual es peor que no tener ninguna prueba. Fuerza un fallo una vez (rompe una aserción a propósito) y confirma que obtienes un código distinto de cero. Luego, vuelve a poner la aserción.

Paso 3: Crea el archivo YAML de Azure Pipelines

Agrega un archivo llamado azure-pipelines.yml a la raíz de tu repositorio. Un punto de partida completo y funcional para un agente Ubuntu alojado:

trigger:
 branches:
 include:
 - main
 - develop

pr:
 branches:
 include:
 - main

pool:
 vmImage: ubuntu-latest

variables:
 NODE_VERSION: '20.x'

steps:
 - task: NodeTool@0
 inputs:
 versionSpec: $(NODE_VERSION)
 displayName: 'Install Node.js'

 - script: npm install -g apidog-cli
 displayName: 'Install Apidog CLI'

 - script: |
 apidog run https://api.apidog.com/api/v1/test-scenarios/$(SCENARIO_ID) \
 -t $(APIDOG_ACCESS_TOKEN) \
 -e $(STAGING_ENV_ID)
 displayName: 'Run API tests'

Explicación:

• trigger ejecuta la pipeline en cada push a main y develop. Ajusta a tus nombres de rama.
• pr la ejecuta en solicitudes de extracción (pull requests) dirigidas a main. Esta es la puerta que impide que una rama rota se fusione.
• pool / vmImage elige un agente Ubuntu alojado por Microsoft. No hay infraestructura que gestionar.
• NodeTool@0 instala una versión específica de Node, para que tus ejecuciones sean reproducibles.
• El paso de instalación descarga la CLI fresca en cada ejecución. Para builds más rápidas puedes cachear node_modules o fijar una versión, pero empieza de forma sencilla.
• El paso de ejecución es el que importa. Si alguna aserción falla, apidog run sale con un código distinto de cero, la tarea de script falla y toda la build se pone en rojo.

Las referencias $(...) son variables de pipeline. SCENARIO_ID, STAGING_ENV_ID y, especialmente, APIDOG_ACCESS_TOKEN provienen del siguiente paso, no están codificadas aquí.

Paso 4: Almacenar los secretos de la forma correcta

Tu token de acceso nunca debe estar en el archivo YAML en texto plano. Cualquiera con acceso de lectura al repositorio lo vería, y otorga acceso a tu proyecto de Apidog.

Usa una variable secreta de pipeline:

1. En Azure DevOps, abre tu pipeline y elige Editar, luego Variables (o Biblioteca para un grupo de variables compartido).
2. Agrega APIDOG_ACCESS_TOKEN y pega el token.
3. Activa el icono de candado para marcarlo como secreto. Azure lo cifra y lo enmascara en los logs.

Las variables secretas no se inyectan automáticamente en el entorno de la shell; las mapeas explícitamente en el paso. Actualiza el paso de ejecución para pasar el secreto a través de env:

 - script: |
 apidog run https://api.apidog.com/api/v1/test-scenarios/$(SCENARIO_ID) \
 -t $(APIDOG_ACCESS_TOKEN) \
 -e $(STAGING_ENV_ID)
 displayName: 'Run API tests'
 env:
 APIDOG_ACCESS_TOKEN: $(APIDOG_ACCESS_TOKEN)

SCENARIO_ID y STAGING_ENV_ID no necesitan ser secretos; trátalos como variables normales para facilitar la lectura, o muévelos a un grupo de variables que reutilices en varias pipelines. Para equipos que gestionan muchos secretos, respalda el grupo de variables con Azure Key Vault para que la rotación ocurra en un solo lugar.

Paso 5: Publicar un informe de pruebas legible

Una build en rojo te dice que algo se rompió. No te dice qué. La solución es que la CLI emita un informe y que Azure lo muestre.

La CLI de Apidog puede escribir sus resultados en un archivo de informe. Apúntalo a un formato de salida (HTML para humanos, un XML estilo JUnit si quieres la vista de prueba nativa de Azure) y un directorio de salida, luego publica ese directorio.

Para un artefacto legible por humanos:

 - script: |
 apidog run https://api.apidog.com/api/v1/test-scenarios/$(SCENARIO_ID) \
 -t $(APIDOG_ACCESS_TOKEN) \
 -e $(STAGING_ENV_ID) \
 -r html \
 --out-dir $(Build.ArtifactStagingDirectory)/api-report
 displayName: 'Run API tests'
 env:
 APIDOG_ACCESS_TOKEN: $(APIDOG_ACCESS_TOKEN)

 - task: PublishBuildArtifacts@1
 condition: always()
 inputs:
 pathToPublish: $(Build.ArtifactStagingDirectory)/api-report
 artifactName: api-test-report
 displayName: 'Publish API test report'

Hay dos cosas que notar. Primero, condition: always() hace que el paso de publicación se ejecute incluso cuando el paso de prueba falla; ese es el punto principal, ya que lo que más quieres es el informe cuando algo se rompió. Segundo, verifica la bandera de reportero exacta (-r, --reporter, o similar) y la opción de salida contra apidog run --help para tu versión de CLI, luego ajusta el ejemplo para que coincida.

Si prefieres ver los resultados en la pestaña de Pruebas integrada de Azure con gráficos de tendencias, haz que la CLI emita JUnit XML y añade una tarea PublishTestResults@2 apuntando al XML. Eso te da un historial por aserción a lo largo de las builds, no solo un archivo único.

Paso 6: Hacer que la puerta sea real

Configurar la pipeline no es lo mismo que hacerla cumplir. Por defecto, una build fallida no impide que nadie fusione a menos que le digas a Azure DevOps que lo requiera.

Configura una política de rama en main:

1. Ve a Repos, luego Ramas, busca main y abre Políticas de rama.
2. Agrega Validación de compilación y selecciona tu pipeline.
3. Establécela como obligatoria.

Ahora, una pull request no puede fusionarse en main hasta que la pipeline de pruebas API pase. Esa es la diferencia entre pruebas que se ejecutan y pruebas que protegen. Hasta que actives esto, tienes un tablero; después, tienes una puerta de calidad.

Un ejemplo realista impulsado por datos

Los escenarios de una sola ejecución detectan fallos obvios. Las API reales necesitan que el mismo endpoint sea ejercitado con muchas entradas; payloads válidos, casos extremos, la solicitud mal formada que debería devolver 400 en lugar de 500.

Apidog soporta pruebas basadas en datos: adjunta un conjunto de datos CSV o JSON a un escenario, y se ejecuta una vez por cada fila, sustituyendo los valores de la fila en las solicitudes y aserciones. Un escenario de inicio de sesión, por ejemplo, podría ejecutar filas para un usuario válido, una contraseña incorrecta, una cuenta bloqueada y un cuerpo vacío, cada una con su propio código de estado esperado.

En la pipeline, nada cambia en la forma del comando; sigues llamando a apidog run contra el mismo escenario. El conjunto de datos viaja con el escenario, por lo que una invocación de la CLI cubre cada fila. Cuando añades un nuevo caso extremo en Apidog, la siguiente ejecución de la pipeline lo detecta sin necesidad de editar el YAML. Esa es la ventaja de mantener la lógica de prueba en la herramienta en lugar de en la pipeline: la pipeline sigue siendo sencilla mientras tu cobertura crece.

Problemas comunes y cómo solucionarlos

La build pasa aunque un endpoint esté roto. Casi siempre un problema de código de salida. Confirma que la CLI devuelve un valor distinto de cero en caso de fallo (Paso 2), y asegúrate de no estarlo ocultando; un || true al final o un script de varios comandos que termina en un comando diferente enmascararán el fallo. Mantén la llamada a apidog run como el último comando significativo en su bloque de script.

apidog: command not found. El paso de instalación no se ejecutó, se ejecutó después del paso de prueba, o se instaló en una ruta que la shell del agente no puede ver. Confirma que npm install -g apidog-cli aparece antes del paso de ejecución. En algunos agentes autoalojados, el bin global de npm no está en PATH; instala localmente y llámalo a través de npx apidog run ... en su lugar.

La autenticación falla en CI pero funciona localmente. El secreto no está llegando al paso. Las variables secretas deben mapearse a través de env: (Paso 4); no se inyectan automáticamente. También verifica que el token no se haya pegado con un salto de línea o una comilla al final.

Las pruebas apuntan al entorno equivocado. El valor de -e apunta al entorno de Apidog incorrecto, o la URL base del entorno todavía hace referencia a localhost. Mantén un entorno Staging dedicado cuyas variables se resuelvan a URLs accesibles y seguras para CI, y pasa su ID explícitamente.

Paso/fallo inestable entre ejecuciones. Generalmente, un estado mutable compartido; una prueba que crea un registro y una ejecución posterior que choca con él. Haz que los escenarios sean autocontenidos: crea lo que necesites, aserción, luego limpia, o usa identificadores únicos por ejecución para que las nuevas ejecuciones no tropiecen con los datos de ayer. Si estás migrando de otra herramienta, los patrones en cómo ejecutar pruebas API en CI sin Newman cubren los mismos problemas de aislamiento.

Más allá de lo básico

Una vez que la pipeline principal es sólida, algunas extensiones valen la pena:

• Programa una ejecución nocturna. Añade un disparador de schedules para ejecutar la suite completa a las 2 a.m. contra staging, para que detectes desviaciones por cambios de datos o cambios de API de terceros incluso en días en que nadie sube código.
• Divide suites rápidas y lentas. Ejecuta un escenario de humo rápido en cada PR para una retroalimentación ágil, y la suite de regresión completa en las fusiones a main. Dos definiciones de pipeline, la misma CLI.
• Prueba múltiples entornos en una matriz. Utiliza una matriz de pipeline para ejecutar el mismo escenario contra staging y un entorno de pre-producción en paralelo, cada uno con su propio ID de entorno.
• Asegura el despliegue, no solo la fusión. Coloca la etapa de prueba API antes de tu etapa de despliegue en una pipeline de múltiples etapas, para que una prueba fallida detenga el lanzamiento, no solo la fusión.

Cada una de estas es una pequeña adición a la misma base: una CLI que sale limpiamente y una pipeline que respeta el código de salida.

Preguntas frecuentes

¿Necesito escribir algún código para ejecutar pruebas API en Azure Pipelines? No. Construyes los escenarios de prueba visualmente en Apidog y la pipeline los ejecuta con un solo comando CLI. El único "código" es el propio azure-pipelines.yml, que es configuración, no lógica de prueba. Si prefieres pruebas completamente basadas en scripts, aún puedes hacerlo, pero el objetivo de este flujo de trabajo es omitirlo.

¿Puedo ejecutar mis colecciones existentes de Postman en Azure Pipelines en su lugar? Puedes, normalmente con Newman o un ejecutor similar. Si estás sopesando las opciones, Apidog importa colecciones de Postman directamente, para que puedas traer tus pruebas existentes y ejecutarlas a través de la misma CLI sin mantener una cadena de herramientas separada. Consulta cómo ejecutar pruebas API en CI sin Newman para la comparación.

¿Adónde deben apuntar las pruebas; a staging o a producción? A staging o a un entorno de vista previa por rama, casi siempre. Ejecutar pruebas con muchas escrituras contra producción contamina los datos reales y puede desencadenar efectos secundarios reales. Mantén un entorno de Apidog dedicado para CI con URLs base seguras, y pasa su ID a la CLI con -e.

¿Cómo sabe la pipeline que una prueba falló? A través del código de salida. apidog run devuelve 0 cuando todas las aserciones pasan y un código distinto de cero cuando alguna falla. Azure Pipelines hace que la tarea de script falle con una salida distinta de cero, lo que hace que la build falle. Verifica esto una vez localmente con echo $? para que confíes en la puerta de calidad.

¿Esto funciona con Azure DevOps Classic (UI) pipelines, no solo con YAML? Sí. Se aplican los mismos pasos; añade una tarea "Use Node", una tarea de línea de comandos que ejecute npm install -g apidog-cli y otra tarea de línea de comandos que ejecute apidog run .... Se recomienda YAML porque reside en tu repositorio y está versionado, pero al ejecutor no le importa cómo se definen los pasos.

¿Puedo usar un agente autoalojado en lugar de uno alojado por Microsoft? Sí. Los agentes autoalojados funcionan de la misma manera; solo asegúrate de que Node.js esté instalado y que el bin global de npm esté en el PATH del agente, o llama a la CLI a través de npx. Los agentes autoalojados son útiles cuando tu API de staging solo es accesible desde dentro de una red privada.

Conclusión

Una build de CI en verde debería significar que tu API realmente funciona, no solo que el código compiló. Lograr esto en Azure Pipelines se reduce a cuatro acciones: diseñar escenarios de prueba reales en Apidog, ejecutarlos sin interfaz gráfica con la CLI de Apidog, dejar que el código de salida impulse el estado de la build y requerir que la build pase antes de que se fusione cualquier cosa. Una vez que ese ciclo está en marcha, cada push recibe el mismo escrutinio que tu compañero de equipo más cuidadoso le daría, automáticamente, cada vez.

La razón por la que esto se mantiene es la división. La lógica de prueba reside en Apidog, donde está cerca de tu especificación de API y es fácil de extender. La pipeline se mantiene como una capa delgada; instalar, ejecutar, informar. Cuando tu API crece, añades escenarios y filas de datos en la herramienta, y la pipeline sigue haciendo su único trabajo sin necesidad de ediciones.

¿Listo para configurarlo? Descarga Apidog, crea un escenario de prueba, toma el comando de ejecución de la CLI y colócalo en tu azure-pipelines.yml. Tu próxima regresión será detectada por una máquina en lugar de por un cliente.