TL;DR
Ejecutar pruebas de ReadyAPI en Jenkins es posible a través de la herramienta de línea de comandos testrunner y el plugin de SmartBear para Jenkins, pero requiere que ReadyAPI esté instalado en los agentes de construcción e implica frecuentes dolores de cabeza de configuración. La integración de CI/CD de Apidog funciona a través de una sencilla CLI instalada con npm sin requisitos de software de agente y sin licencias por ejecución.
Introducción
Integrar las pruebas de API en un pipeline de CI/CD es una de las cosas más valiosas que un equipo de pruebas puede hacer. Detectar regresiones en cada pull request, antes de que el código llegue a staging o producción, justifica el esfuerzo de configuración.
ReadyAPI soporta la integración con Jenkins a través de dos mecanismos: la herramienta de línea de comandos testrunner y el plugin oficial de SmartBear para Jenkins. Ambos funcionan, pero cada uno conlleva su complejidad. Esta guía cubre cómo configurar ReadyAPI con Jenkins, los problemas comunes que encontrará y cómo Apidog proporciona la misma integración de pipeline con menos sobrecarga de infraestructura.
Configuración de ReadyAPI en Jenkins: el enfoque de testrunner
El testrunner es el motor de ejecución de línea de comandos de ReadyAPI. Cuando Jenkins necesita ejecutar pruebas de ReadyAPI sin interfaz gráfica, llama a testrunner con argumentos que apuntan a un archivo de proyecto.
Requisitos previos:
ReadyAPI debe estar instalado en cada agente de Jenkins que ejecute pruebas de API. Este es el mayor requisito operativo. Si tiene cinco agentes de construcción y las pruebas de ReadyAPI se ejecutan en cualquiera de ellos, los cinco necesitan tener ReadyAPI instalado. Esto crea:
- Una carga de mantenimiento de la instalación cuando ReadyAPI se actualiza.
- Una pregunta sobre licencias: ¿cada instalación de agente requiere su propia licencia? La política de licencias de CI/CD de SmartBear varía según el contrato. Confirme con su equipo de cuentas.
- Mayor tamaño de imagen del agente y tiempo de inicio para agentes basados en la nube.
Comando básico de testrunner:
En Linux/macOS:
/path/to/ReadyAPI/testrunner.sh \
-r \
-f /path/to/results \
-s "TestSuiteName" \
-c "TestCaseName" \
/path/to/project.xml
En Windows:
C:\ReadyAPI\testrunner.bat ^
-r ^
-f C:\results ^
-s "TestSuiteName" ^
-c "TestCaseName" ^
C:\projects\project.xml
Banderas clave de testrunner:
-r: generar informe XML compatible con JUnit-f <directory>: directorio de salida para los resultados-s <name>: ejecutar un conjunto de pruebas específico (omitir para ejecutar todos)-c <name>: ejecutar un caso de prueba específico (omitir para ejecutar todos)-e <environment>: especificar el entorno a utilizar-P <name>=<value>: anular propiedades del proyecto
Paso de pipeline de Jenkins:
En un Jenkinsfile:
stage('API Tests') {
steps {
sh '''
/opt/readyapi/testrunner.sh \
-r \
-f ${WORKSPACE}/test-results \
-e ${ENVIRONMENT} \
${WORKSPACE}/project.xml
'''
junit 'test-results/*.xml' // Publica los resultados JUnit en Jenkins
}
}
El paso junit publica los resultados en Jenkins para que los fallos aparezcan en el informe de la construcción.
Uso del plugin de SmartBear para Jenkins
SmartBear mantiene un plugin para Jenkins para ReadyAPI disponible en el directorio de plugins de Jenkins. El plugin proporciona un paso de construcción en la interfaz de usuario de Jenkins en lugar de requerir que escriba comandos de shell manualmente.
Para instalarlo:
- Vaya a Jenkins > Administrar Jenkins > Administrador de Plugins.
- Busque "SmartBear ReadyAPI Functional Testing".
- Instale y reinicie Jenkins.
Después de la instalación, configure la ruta de instalación de ReadyAPI en la configuración global de Jenkins, luego agregue un paso de prueba de ReadyAPI a su trabajo de construcción seleccionando del menú desplegable de pasos de construcción.
El plugin gestiona la construcción de argumentos por usted e integra los resultados en los informes de prueba de Jenkins. Para los equipos que prefieren la configuración GUI a los scripts de pipeline en Groovy, el plugin reduce el tiempo de configuración.
Limitaciones del plugin: El plugin está ligado a versiones específicas de Jenkins y ReadyAPI. Las actualizaciones del plugin se retrasan con respecto a las versiones de ReadyAPI y las de Jenkins. Los equipos que ejecutan la última versión de ReadyAPI pueden encontrar problemas de compatibilidad que requieren esperar una actualización del plugin.
Problemas comunes de Jenkins + ReadyAPI
Testrunner se cuelga al iniciar. ReadyAPI es una aplicación Java/Swing. Cuando se lanza sin interfaz gráfica en CI, a veces intenta inicializar componentes GUI. Configure la variable de entorno DISPLAY o use argumentos JVM -Djava.awt.headless=true si encuentra esto.
Fallos de validación de licencia. ReadyAPI valida su licencia al iniciar. Si el agente de CI no puede alcanzar el servidor de licencias de SmartBear (común en redes corporativas restringidas), las pruebas fallan con un error de licencia en lugar de un fallo de prueba. Necesita configurar la configuración del servidor de licencias flotantes o la licencia sin conexión.
Errores de memoria insuficiente. La configuración predeterminada de la pila JVM en testrunner es conservadora. Las suites de pruebas grandes o los proyectos con muchos archivos de datos pueden necesitar ajustar la configuración -Xmx. Edite el archivo testrunner.sh o testrunner.bat para aumentar la pila:
-Xms128m -Xmx1024m
Problemas de ruta con los archivos de proyecto. Los proyectos de ReadyAPI referencian archivos externos (fuentes de datos, esquemas, scripts) usando rutas. Cuando se ejecuta en CI, las rutas relativas funcionan solo si el directorio de trabajo está configurado correctamente. Las rutas absolutas en los archivos de proyecto causan problemas cuando el proyecto se mueve entre máquinas. Use propiedades de proyecto para las rutas y configúrelas a través de banderas -P en tiempo de ejecución.
Las pruebas pasan localmente pero fallan en CI. A menudo causado por diferencias de entorno: diferentes datos en archivos externos, diferentes valores de variables de entorno o rutas codificadas. Use la función de Entorno de ReadyAPI con selección explícita de entorno en el argumento -e de testrunner.
Integración de Apidog con Jenkins: un enfoque más simple
El runner CLI de Apidog se instala a través de npm y no requiere una aplicación de escritorio en el agente de construcción.
Instalación en el agente de Jenkins:
npm install -g apidog-cli
O en un paso de pipeline:
npm ci
# apidog-cli está en devDependencies
Ejecución de pruebas en un Jenkinsfile:
stage('API Tests') {
steps {
sh '''
apidog run \
--collection ${WORKSPACE}/apidog-collection.json \
--environment staging \
--reporter junit \
--reporter-junit-export ${WORKSPACE}/results/report.xml
'''
junit 'results/report.xml' // Publica los resultados JUnit en Jenkins
}
}
Diferencias clave con ReadyAPI:
No hay aplicación de escritorio en los agentes. La CLI de Apidog es un paquete Node.js ligero. Instálelo en segundos, no minutos. Sin problemas de inicialización de GUI, sin requisitos de conectividad con el servidor de licencias.
Sin preocupaciones por licencias por ejecución. Apidog no cobra por cada ejecución de CI. Ejecute tantos ciclos de prueba al día como lo demande su pipeline.
Configuración de entorno a través de variables de entorno o banderas. Pase credenciales y URLs base como variables de entorno directamente desde el almacén de credenciales de Jenkins:
withCredentials([string(credentialsId: 'api-key', variable: 'API_KEY')]) {
sh 'apidog run collection.json -e production --env-var "apiKey=${API_KEY}"'
}
Comparación con GitHub Actions:
Para equipos que también usan GitHub Actions, el enfoque de Apidog es igualmente limpio:
- name: Run API tests
run: |
npm install -g apidog-cli
apidog run collection.json --environment staging
env:
API_BASE_URL: ${{ vars.STAGING_URL }}
API_KEY: ${{ secrets.API_KEY }}
El equivalente en ReadyAPI requiere un runner autoalojado con ReadyAPI instalado o una compleja construcción de imagen Docker. Ninguno de los dos es tan sencillo.
Migración de CI/CD de ReadyAPI a Apidog
Si está migrando su suite de pruebas y necesita actualizar su configuración de CI/CD simultáneamente:
- Exporte sus definiciones de API de ReadyAPI e impórtelas a Apidog.
- Instale la CLI de Apidog en sus agentes de Jenkins.
- Agregue un paso de prueba de Apidog a su pipeline junto con el paso existente de ReadyAPI.
- Ejecute ambos en paralelo. Compare las tasas de fallo y la cobertura de las pruebas.
- Elimine el paso de ReadyAPI una vez que tenga confianza en la cobertura de Apidog.
- Elimine ReadyAPI de los agentes de construcción durante la próxima actualización de la imagen del agente.
Preguntas Frecuentes
¿El testrunner de ReadyAPI requiere una licencia de CI separada? La política de licencias de SmartBear para el uso de CI/CD varía según el contrato. Algunos acuerdos incluyen derechos de ejecución de CI/CD en la licencia estándar; otros requieren un acuerdo separado. Revise su contrato o póngase en contacto con su gerente de cuenta de SmartBear antes de asumir que las ejecuciones de CI están cubiertas.
¿Se pueden ejecutar las pruebas de ReadyAPI en contenedores Docker? Sí, con esfuerzo. Puede construir una imagen Docker con ReadyAPI instalado y usarla como un contenedor de agente de Jenkins. La imagen es grande (ReadyAPI es una aplicación de escritorio) y requiere una configuración sin interfaz gráfica. Funciona, pero añade complejidad en comparación con las herramientas construidas para entornos de CI contenerizados.
¿Apidog soporta la ejecución paralela de pruebas en Jenkins? Sí. Puede ejecutar múltiples instancias de la CLI de Apidog en etapas paralelas de Jenkins, cada una ejecutando una colección o entorno diferente. La ejecución paralela se controla a través de su Jenkinsfile, no de la CLI de Apidog.
¿Qué formato de informe de prueba produce Apidog para Jenkins? La CLI de Apidog puede producir informes JUnit XML, que Jenkins analiza y muestra de forma nativa en la sección de resultados de las pruebas. El formato es el mismo que produce el testrunner de ReadyAPI.
¿Los scripts de prueba de Apidog se ejecutan en el mismo proceso que el runner CLI? Sí. Los scripts de prueba de JavaScript se ejecutan dentro del proceso Node.js de la CLI de Apidog. No hay un entorno de ejecución de scripts separado que configurar.
¿Existe un plugin oficial de Apidog para Jenkins? La CLI de Apidog se ejecuta como un paso de shell en Jenkins, lo que no requiere un plugin dedicado. Este enfoque es más sencillo de mantener que las integraciones basadas en plugins que necesitan actualizarse cuando Jenkins o Apidog lanzan nuevas versiones.
La integración de ReadyAPI con Jenkins funciona, pero requiere una gestión de infraestructura significativa. Para los equipos que desean simplificar su configuración de CI/CD mientras mantienen una cobertura integral de pruebas de API, el enfoque CLI de Apidog elimina los puntos débiles más comunes: requisitos de software del agente, dependencias del servidor de licencias y configuración compleja del entorno.