Ejecutar pruebas API automatizadas en TeamCity

Su API supera todas las pruebas en su portátil. Luego, un compañero de equipo fusiona una rama que renombra un campo, y nadie se da cuenta hasta que un cliente móvil comienza a fallar en producción. Las pruebas manuales lo pasaron por alto porque nadie volvió a ejecutar el conjunto. Esta es la brecha exacta que la integración continua está diseñada para cerrar, y TeamCity es una de las herramientas más sólidas para cerrarla.

TeamCity, el servidor CI/CD de JetBrains, ejecuta su pipeline de compilación cada vez que se envía código. Puede compilar, probar, empaquetar y desplegar sin que nadie haga clic en un botón. La parte que los equipos a menudo omiten es la conexión de pruebas de API reales a ese pipeline. Prueban unidades, prueban que la compilación se compila y envían la API con fe. Un campo renombrado, un error 500 en un caso extremo, un flujo de autenticación roto; nada de eso aparece hasta que un humano accede al endpoint.

Esta guía le guiará a través de la ejecución de pruebas de API automatizadas dentro de TeamCity de principio a fin. Diseñará y validará sus pruebas en Apidog, luego las ejecutará sin interfaz de usuario a través de la CLI de Apidog como un paso de compilación de TeamCity. El resultado es un pipeline que falla la compilación en el momento en que su API deja de funcionar, antes de que una respuesta incorrecta llegue a un usuario.

Qué construirá

Al final tendrá:

• Un proyecto de TeamCity conectado a su repositorio Git
• Una configuración de compilación con un disparador VCS que se activa en cada push
• Un paso de compilación que ejecuta su conjunto de pruebas de API a través de la CLI de Apidog
• Resultados de pruebas analizados visibles en la pestaña Pruebas de TeamCity
• Una compilación que se pone en rojo y bloquea la fusión cuando un endpoint se rompe

El mismo patrón funciona para un pequeño servicio interno o una API pública con cientos de endpoints. Lo escala agregando escenarios de prueba en Apidog, no editando el código del pipeline.

Por qué las pruebas de API pertenecen a TeamCity, no solo a su máquina

Las pruebas locales tienen un defecto fatal: dependen de que alguien se acuerde de ejecutarlas. La CI elimina al humano del ciclo. Cada commit activa el mismo conjunto, en el mismo entorno, con las mismas aserciones. No hay "funciona en mi máquina" porque no hay máquina; hay un agente de compilación que ejecuta los pasos exactos que usted definió.

TeamCity es una buena opción para esto por algunas razones concretas:

• Cadenas de compilación. Puede hacer que el paso de prueba de API dependa de un paso de despliegue a staging, de modo que las pruebas siempre se ejecuten contra una compilación recién desplegada, nunca una obsoleta.
• Historial de pruebas. TeamCity rastrea qué pruebas pasaron y fallaron en cientos de compilaciones. Cuando una prueba comienza a fallar intermitentemente, usted ve exactamente qué commit la introdujo.
• Investigación y silenciamiento. Un endpoint inestable puede silenciarse y asignarse a un propietario en lugar de bloquear las fusiones de todos.
• Pools de agentes. Los conjuntos pesados se ejecutan en agentes dedicados para que no ralenticen sus compilaciones.

El inconveniente es que TeamCity no sabe cómo llamar a su API o verificar la respuesta. Ejecuta cualquier comando que le dé. Así que el verdadero trabajo es producir un único comando que ejecute todo su conjunto de API y salga con un código distinto de cero cuando algo falle. Ahí es donde el diseño de las pruebas importa.

Paso 1: Diseñe y valide sus pruebas de API en Apidog

Antes de que nada toque TeamCity, necesita pruebas que realmente se ejecuten sin supervisión. Una prueba que requiere que usted revise una respuesta JSON es inútil en CI. Cada verificación debe ser una aserción que la máquina pueda evaluar: el código de estado es 200, el campo id es un número, la respuesta llegó en menos de 800 ms.

Apidog está diseñado exactamente para esto. Usted diseña la solicitud, luego adjunta aserciones de API que validan la respuesta automáticamente; códigos de estado, conformidad con el esquema JSON, valores de campo específicos, tiempo de respuesta. Puede encadenar solicitudes en un escenario para que la salida de una llamada de inicio de sesión alimente el token en la siguiente solicitud. No se requiere scripting para los casos comunes, y hay scripting completo disponible cuando lo necesita.

Un escenario realista para una API de comercio electrónico podría verse así:

1. POST /auth/login con credenciales de prueba, aserción 200, extraiga el token de portador en una variable.
2. GET /products?category=books con ese token, aserción 200, aserción de que la respuesta es un array, aserción de que cada elemento tiene un price mayor que 0.
3. POST /cart/items con un ID de producto, aserción 201, aserción de que el total del carrito devuelto coincide con el precio del artículo.
4. GET /cart, aserción de que el recuento de artículos es 1.

Cada paso tiene aserciones que pasan o fallan por sí solas. Ejecute el escenario dentro de Apidog primero y confirme que se pone verde contra su entorno de staging. Si no puede pasar cuando lo ejecuta manualmente, nunca pasará en CI. Agrupe escenarios relacionados en un conjunto de pruebas para que pueda ejecutar todo con un solo comando en lugar de escenario por escenario.

La ventaja de construir pruebas de esta manera es que los mismos escenarios que usa para la depuración manual se convierten en su conjunto de CI. No mantiene dos conjuntos paralelos de pruebas; uno en una GUI para exploración, otro en código para automatización. Es una única fuente de verdad. Si viene de un framework "code-first" como REST Assured, esta es la parte que ahorra más tiempo: deja de escribir y reescribir código repetitivo de solicitud/aserción para cada endpoint.

Descargue Apidog si quiere construirlo. Es gratis para empezar, y la CLI es parte de la misma cadena de herramientas.

Paso 2: Haga que la CLI de Apidog se ejecute localmente primero

Nunca depure un comando nuevo por primera vez dentro de CI. El ciclo de retroalimentación en un servidor CI es brutal; usted hace un push, espera un agente, lee un log, corrige un carácter, hace push de nuevo. Pruebe que el comando funciona en su máquina, luego copie la versión que funciona en TeamCity.

La CLI de Apidog se ejecuta en Node.js, así que instálela globalmente con npm:

npm install -g apidog-cli

Confirme que está ahí:

apidog --version

Ahora ejecute su escenario de prueba. La CLI puede ejecutar un escenario o conjunto directamente desde su proyecto Apidog haciendo referencia a su ID, autenticada con un token de acceso, o desde un archivo local exportado. El enfoque en línea mantiene sus pruebas como la única fuente de verdad; lo que su equipo edite en Apidog es lo que se ejecuta en CI, sin un paso de exportación que se pueda olvidar.

Genere un token de acceso desde la configuración de su cuenta Apidog, luego ejecute:

apidog run \
 --access-token "$APIDOG_ACCESS_TOKEN" \
 -e "$APIDOG_ENV_ID" \
 -r cli,html,junit

Algunas cosas a tener en cuenta aquí:

• --access-token autentica la ejecución. Páselo en línea así, o inicie sesión una vez con apidog login --with-token.
• -e selecciona contra qué entorno ejecutar; staging, producción-solo-lectura, lo que haya definido en Apidog. Usted apunta las mismas pruebas a diferentes URLs base cambiando este ID.
• -r elige los reporteros. cli imprime una salida legible por humanos en la consola, html produce un informe que puede navegar, y un informe en formato JUnit es lo que permite a TeamCity analizar y mostrar los resultados de pruebas individuales.

Cuando la ejecución finaliza, la CLI sale con 0 si todo pasó y con un código distinto de cero si alguna aserción falló. Ese código de salida es todo el juego en CI: una salida distinta de cero es lo que le dice a TeamCity que marque la compilación como fallida.

Para pruebas que necesitan ejecutarse en muchas entradas, la CLI admite ejecuciones impulsadas por datos. Apúntela a un archivo CSV o JSON y itera el escenario una vez por fila:

apidog run \
 --access-token "$APIDOG_ACCESS_TOKEN" \
 -d test-data/checkout-cases.csv \
 -r cli,junit

Así es como se prueban cien IDs de productos o una tabla de cargas útiles inválidas sin escribir cien escenarios. Cada fila se convierte en su propia iteración con su propio resultado de aprobado/fallido.

Una vez que vea la salida verde localmente, tiene un comando en el que confía. Cópielo. Ese comando exacto es lo que va en TeamCity.

Paso 3: Conecte TeamCity a su repositorio

Ahora cambie a TeamCity. El objetivo de este paso es darle a TeamCity un proyecto, apuntarlo a su código y permitirle disparar compilaciones en cada push.

Si está ejecutando TeamCity por primera vez, el camino más simple es la imagen oficial de Docker. Le proporciona un servidor funcional en un par de minutos:

docker run -d --name teamcity-server \
 -v ~/teamcity/datadir:/data/teamcity_server/datadir \
 -v ~/teamcity/logs:/opt/teamcity/logs \
 -p 8111:8111 \
 jetbrains/teamcity-server

Abra http://localhost:8111, complete la configuración inicial (elección de base de datos, cuenta de administrador) y llegará al panel de control. Las configuraciones de producción utilizan una base de datos externa adecuada y agentes de compilación dedicados, pero para seguir esta guía, el agente incluido es suficiente.

Cree el proyecto:

1. Vaya a Administración y elija Crear proyecto.
2. Elija Desde una URL de repositorio y pegue su remoto Git (HTTPS o SSH).
3. Agregue credenciales si el repositorio es privado; una clave de despliegue o un token de acceso personal.
4. TeamCity escanea el repositorio y debe detectar automáticamente los pasos de compilación. Puede dejar que lo haga, pero para las pruebas de API es más limpio configurar el paso usted mismo en la siguiente sección.

TeamCity crea una raíz VCS (su conexión a su repositorio) y una configuración de compilación (el conjunto de pasos que se ejecutan). Con la raíz VCS en su lugar, configure el disparador para que las compilaciones se activen automáticamente:

1. Abra su configuración de compilación y vaya a Disparadores.
2. Agregue un Disparador VCS.
3. Deje la regla predeterminada para que cada cambio en la rama observada ponga en cola una compilación.

A partir de aquí, cada push a su repositorio iniciará una compilación. En este momento, esa compilación no hace nada útil; el siguiente paso le dará el comando de prueba de API.

Paso 4: Agregue la CLI de Apidog como un paso de compilación

Este es el núcleo de la configuración. Está agregando un paso de compilación que instala la CLI en el agente y ejecuta su suite.

En su configuración de compilación, abra Pasos de compilación y agregue un nuevo paso de tipo Línea de comandos. Elija script personalizado y pegue:

#!/bin/bash
set -e

# Instale la CLI de Apidog en el agente de compilación
npm install -g apidog-cli

# Ejecute el conjunto de pruebas de API y emita un informe JUnit para TeamCity
apidog run \
 --access-token "%env.APIDOG_ACCESS_TOKEN%" \
 -e "%env.APIDOG_ENV_ID%" \
 -r cli,junit \
 --out-dir reports

Ese es el mismo comando que probó localmente, con dos cambios para CI. Primero, set -e hace que el script aborte en cualquier error. Segundo, los secretos se referencian como parámetros de TeamCity (%env.APIDOG_ACCESS_TOKEN%) en lugar de estar codificados; los definirá a continuación.

Si su agente de compilación aún no tiene Node.js, instálelo antes en la cadena o use una imagen de agente que lo incluya. Las imágenes oficiales de Docker para agentes de TeamCity y la mayoría de los pools de agentes en la nube vienen con Node disponible. También puede ejecutar todo el paso dentro de un contenedor Node configurando el paso para que se ejecute en una imagen de Docker como node:20.

Un detalle que vale la pena acertar: la CLI debe ejecutarse después de que su API esté desplegada y accesible. Si TeamCity está probando un servicio que acaba de desplegar en staging, haga que la compilación de prueba dependa de la compilación de despliegue utilizando una Dependencia de Instantánea o una Cadena de Compilación. Esto garantiza que las pruebas siempre apunten a la versión de la API que produjo este commit, nunca la anterior.

Paso 5: Almacene secretos como parámetros de TeamCity

Su token de acceso es una credencial. No debe estar en el script de compilación, en su repositorio o en el registro de compilación. TeamCity tiene un lugar de primera clase para esto.

1. En su configuración de compilación (o el proyecto padre, para compartir entre configuraciones), abra Parámetros.
2. Agregue un nuevo parámetro llamado env.APIDOG_ACCESS_TOKEN.
3. Establezca su Especificación en Contraseña. Esto enmascara el valor en la UI y lo elimina de los registros de compilación.
4. Pegue su token de acceso de Apidog como valor.
5. Agregue env.APIDOG_ENV_ID de la misma manera con su ID de entorno (este no es secreto, pero mantenerlo como parámetro le permite cambiar de entorno sin editar el script).

Definirlos a nivel de proyecto en lugar de a nivel de configuración de compilación significa que cada compilación de prueba de API bajo ese proyecto los hereda. Rote el token una vez, y cada pipeline recogerá el nuevo valor.

Un parámetro de contraseña es la diferencia entre un token que vive de forma segura en TeamCity y uno que se filtra en un archivo de registro que todo el equipo puede leer. Trátelo como trataría una contraseña de base de datos.

Paso 6: Muestre los resultados de las pruebas en la pestaña Pruebas de TeamCity

Una compilación que simplemente se pone en rojo le dice que algo se rompió. Una compilación que muestra qué prueba se rompió le dice dónde buscar. Eso es lo que le proporciona el informe JUnit.

El reportero -r junit escribe un archivo XML en formato JUnit, el formato estándar de resultados de pruebas de CI que TeamCity lee de forma nativa. Usted apunta TeamCity a ese archivo con una función de compilación de Procesamiento de Informes XML.

1. Abra La compilación tiene en su configuración de compilación.
2. Agregue el procesamiento de informes XML.
3. Establezca el tipo de informe en Ant JUnit.
4. Establezca la ruta de monitoreo para que coincida con su salida, por ejemplo, reports/*.xml.

Ejecute una compilación. Ábrala y haga clic en la pestaña Pruebas. Verá cada escenario y aserción como una prueba individual con un estado de aprobado/fallido y tiempos. Cuando una prueba falla, TeamCity muestra el mensaje de falla en línea, lo vincula al commit que lo introdujo y lo rastrea en futuras compilaciones. Si la misma prueba falla dos veces seguidas, TeamCity puede marcarla como una nueva falla en lugar de una intermitente.

Esta es la recompensa por elegir la salida JUnit antes. Sin ella, un fallo es una compilación roja y una pared de texto de consola. Con ella, obtiene un historial de pruebas estructurado y buscable que convierte "la compilación de la API está rota" en "la aserción del total del carrito comenzó a fallar en el commit a3f9c2".

Paso 7: Fallar la compilación y bloquear la fusión

El objetivo de todo esto es evitar que se fusione código defectuoso. Dos cosas hacen que eso suceda.

Primero, el código de salida. Debido a que la CLI de Apidog sale con un código distinto de cero en cualquier aserción fallida y su script usa set -e, una prueba fallida falla el paso de compilación, lo que falla la compilación. No tiene que configurar nada adicional; una prueba de API en rojo es una compilación en rojo por defecto.

Segundo, la puerta de fusión. Si su equipo trabaja con solicitudes de extracción o fusión, configure su host Git (GitHub, GitLab, Bitbucket) para que requiera que la verificación de TeamCity pase antes de fusionar. TeamCity informa el estado de su compilación al commit a través de una función de compilación del Publicador de Estado de Commit:

1. Agregue la función de compilación Publicador de Estado de Commit.
2. Seleccione su proveedor de alojamiento VCS.
3. Agregue un token de acceso para que TeamCity pueda publicar estados.

Ahora, un colaborador abre una PR, TeamCity ejecuta la suite de API contra su rama, y el botón de fusión permanece deshabilitado hasta que la suite está en verde. El escenario del campo renombrado del inicio de esta guía se detecta aquí, en la rama, antes de que llegue a main.

Un pipeline completo realista

Juntando las piezas, una configuración de compilación funcional para un pipeline de pruebas de API se ve así:

• Raíz VCS apuntando a su repositorio, con un disparador VCS en la rama principal y las ramas de PR.
• Paso de compilación 1: despliegue el servicio en un entorno de staging (o levántelo en un contenedor Docker en el agente).
• Paso de compilación 2: el comando de la CLI de Apidog del Paso 4, ejecutando su suite contra ese entorno de staging.
• La compilación tiene: procesamiento de informes XML leyendo reports/*.xml.
• La compilación tiene: Publicador de estado de commit informando a su host Git.
• Parámetros: env.APIDOG_ACCESS_TOKEN (contraseña) y env.APIDOG_ENV_ID.

Para los equipos que mantienen toda su configuración de CI en control de versiones, TeamCity admite la definición de todo esto en un DSL de Kotlin (.teamcity/settings.kts) comprometido con el repositorio, en lugar de hacer clic a través de la interfaz de usuario. El paso de compilación es el mismo comando apidog run de cualquier manera; el DSL simplemente describe la configuración como código para que se revise y versiona junto con todo lo demás.

Puede ejecutar la suite no solo en cada push. Agregue un Disparador de Programación para ejecutar la suite de regresión completa cada noche contra staging, para detectar desviaciones que ocurren entre commits; una dependencia de terceros que cambió, una base de datos que entró en un estado extraño. Las ejecuciones nocturnas de API son un seguro barato y evitan que el primer commit de la mañana herede el entorno roto de ayer.

Cómo se compara esto con otras plataformas de CI

El patrón aquí es portable. El comando que ejecuta sus pruebas (apidog run con un token de acceso y un reportero JUnit) es idéntico sin importar qué servidor de CI lo invoque. Solo cambia el envoltorio:

• En GitHub Actions, pondría el mismo comando en un paso de flujo de trabajo YAML. Lo cubrimos en Cómo automatizar pruebas de API en GitHub Actions.
• En Jenkins, va en una etapa de Jenkinsfile. Consulte Cómo integrar pruebas automatizadas de Apidog con Jenkins para CI/CD.
• La estrategia más amplia en cualquier plataforma se encuentra en Cómo automatizar pruebas de API en CI/CD.

Si todavía está eligiendo un servidor CI, nuestra comparación de las mejores herramientas CI/CD desglosa dónde encaja TeamCity frente a las alternativas. Los puntos fuertes de TeamCity son sus cadenas de compilación, su historial de pruebas granular y el DSL de Kotlin; es una opción sólida para equipos que ya están en el ecosistema de JetBrains o que ejecutan pipelines complejos de múltiples etapas.

Problemas comunes y cómo solucionarlos

La compilación no encuentra el comando apidog. Node.js no está instalado en el agente, o el directorio bin global de npm no está en la PATH del agente. Agregue un paso de instalación de Node antes en la cadena, o ejecute el paso dentro de una imagen Docker node:20.

Las pruebas pasan localmente pero fallan en CI con errores de conexión. El agente de compilación no puede acceder a su API. Una URL de staging que se resuelve en la VPN de su portátil puede ser inalcanzable desde un agente en la nube. Confirme que el entorno que selecciona con -e apunta a un host al que el agente puede acceder realmente, y que cualquier acceso de red o reglas de firewall requeridas cubren al agente.

La autenticación falla solo en CI. Verifique que el parámetro de contraseña esté escrito exactamente como lo referencia el script y que el token no haya caducado. Un error común es definir APIDOG_ACCESS_TOKEN mientras el script lee %env.APIDOG_ACCESS_TOKEN%; el prefijo env. importa.

Las pruebas son inestables; pasan y fallan con el mismo código. Generalmente es un problema de temporización o de ordenación de datos. Use las aserciones de tiempo de respuesta de Apidog para detectar endpoints lentos, y haga que cada escenario configure y desmonte sus propios datos para que las ejecuciones no dependan de los restos de otras. La función de silenciar e investigar de TeamCity le permite poner en cuarentena una prueba inestable para que deje de bloquear a todos mientras usted soluciona la causa raíz.

La pestaña Pruebas está vacía aunque la compilación se ejecutó. La ruta de procesamiento del informe XML no coincide con donde la CLI escribió el informe. Confirme que --out-dir en el comando y la ruta de monitoreo en la función de compilación apuntan al mismo lugar.

Preguntas Frecuentes

¿Necesito escribir código para ejecutar pruebas de API en TeamCity? No. Usted diseña las pruebas visualmente en Apidog con aserciones, y el único "código" en TeamCity es el comando de una línea apidog run en un paso de compilación de Línea de comandos. Esa es la principal diferencia con un enfoque "code-first" como REST Assured, donde cada endpoint necesita código de solicitud y aserción escrito a mano.

¿Puedo ejecutar las pruebas en diferentes entornos? Sí. Defina cada entorno (staging, pre-prod, producción-solo-lectura) en Apidog, luego cambie cuál se ejecuta en CI cambiando el parámetro de ID de entorno -e. Las mismas pruebas se ejecutan en cualquier entorno apuntando a una URL base diferente.

¿Cómo mantengo seguro mi token de acceso en TeamCity? Almacénelo como un parámetro de TeamCity con la especificación Contraseña. Esto lo enmascara en la interfaz de usuario y lo elimina de los registros de compilación. Nunca lo codifique en el script de compilación ni lo suba a su repositorio. Defínalo a nivel de proyecto para poder rotarlo una vez para todos los pipelines.

¿Un fallo en la prueba de API realmente bloqueará una fusión? Sí, con dos elementos en su lugar. La CLI de Apidog sale con un código distinto de cero ante cualquier aserción fallida, lo que hace que la compilación de TeamCity falle. Agregue la función de compilación del Publicador de Estado de Commit y requiera la verificación en las reglas de protección de rama de su host Git, y el botón de fusión permanecerá deshabilitado hasta que la suite pase.

¿Cuál es la diferencia entre ejecutar pruebas en línea y desde un archivo exportado? Ejecutar en línea por ID de proyecto y token de acceso significa que sus pruebas en Apidog son la única fuente de verdad; lo que el equipo edita es lo que se ejecuta en CI. Ejecutar desde un archivo exportado fija las pruebas a una versión comprometida en su repositorio. En línea es más sencillo de mantener sincronizado; exportado le da pruebas que viajan con el código. La mayoría de los equipos empiezan en línea.

¿Puedo ejecutar el conjunto de regresión completo según un cronograma en lugar de en cada push? Sí. Agregue un Disparador de Programación a la configuración de compilación para que se ejecute todas las noches (o cada hora) contra el entorno de staging. Muchos equipos ejecutan un conjunto rápido de pruebas de humo en cada push y el conjunto completo de regresión en un horario nocturno, de modo que la retroalimentación rápida y la cobertura profunda no compitan por los mismos minutos.

Conclusión

Un pipeline de TeamCity que ejecuta sus pruebas de API en cada commit cambia la economía de un endpoint roto. En lugar de que un cliente encuentre el error, la compilación lo encuentra; en la rama, antes de la fusión, con la aserción fallida exacta y el commit que la causó detallados en la pestaña Pruebas.

La configuración se reduce a tres partes móviles: pruebas con aserciones reales que construyes en Apidog, un solo comando apidog run que las ejecuta sin interfaz gráfica y sale con un código distinto de cero si falla, y una configuración de compilación de TeamCity que ejecuta ese comando, analiza los resultados de JUnit e informa el estado a tu host Git. Una vez que está en su lugar, mantienes la cobertura agregando escenarios en Apidog, no tocando el código del pipeline.

Descargue Apidog para diseñar su primer conjunto de pruebas, pruebe el comando CLI localmente y luego introdúzcalo en TeamCity. A partir de ese momento, su API se probará de la misma manera en cada commit, sin importar si alguien se acuerda de ejecutarlo o no.