Para ejecutar pruebas de API de Apidog CLI en CircleCI, añada un archivo .circleci/config.yml que utilice un ejecutor de Docker cimg/node, instale apidog-cli con npm, y ejecute apidog run con su token de acceso, ID de escenario de prueba, e ID de entorno. Almacene el token y los IDs como variables de entorno de CircleCI, luego publique los informes JUnit y HTML con store_test_results y store_artifacts. Esta guía le mostrará cada parte para que pueda copiar, pegar y desplegar.
Este artículo trata sobre la ejecución de pruebas, no sobre la elección de una plataforma de CI. Si todavía está decidiendo entre herramientas, la comparación CircleCI vs Jenkins cubre ese terreno. Aquí asumimos que ya ha elegido CircleCI y desea que su suite de API se ejecute en cada 'push'.
Qué es CircleCI y cómo funciona
CircleCI es un servicio de integración y entrega continua basado en la nube. Observa su repositorio de Git y, cuando hace un 'commit', ejecuta los pasos de construcción, prueba y despliegue que usted definió. Usted describe esos pasos en un único archivo YAML, de modo que su 'pipeline' vive en el control de versiones junto con su código.
Todo comienza con .circleci/config.yml en la raíz de su repositorio. CircleCI lee este archivo en cada 'push' y lo convierte en un 'pipeline'. El formato de configuración actual es la versión 2.1, que añade bloques de construcción reutilizables como orbes, comandos y parámetros sobre el motor base 2.0.
Una configuración de CircleCI tiene tres conceptos clave:
- Trabajos (Jobs) son unidades de trabajo. Cada trabajo ejecuta una serie de pasos (steps), como extraer código, instalar dependencias o ejecutar un comando de prueba.
- Los Ejecutores (Executors) definen dónde se ejecuta un trabajo. Un ejecutor de Docker ejecuta sus pasos dentro de una imagen de contenedor que usted elija, como
cimg/nodepara proyectos Node.js. - Los Flujos de trabajo (Workflows) orquestan los trabajos. Un flujo de trabajo decide qué trabajos se ejecutan, en qué orden y si se ejecutan en paralelo o en secuencia.
Esa separación es importante para las pruebas de API. Usted define un trabajo que instala Apidog CLI y ejecuta sus escenarios, luego un flujo de trabajo que lo activa en las ramas que le interesan.
Por qué ejecutar pruebas de API en CircleCI
Ejecutar su suite de API en CI detecta rupturas de contrato antes de que lleguen a producción. Un cambio de esquema, un campo renombrado o un flujo de autenticación roto aparece como una compilación en rojo en lugar de un ticket de soporte.
El Apidog CLI está diseñado precisamente para esto. Usted diseña y depura un escenario de prueba en la aplicación Apidog, luego ejecuta ese mismo escenario sin interfaz gráfica en CI con un solo comando. Sin necesidad de reescribir aserciones en código, y sin un arnés de prueba separado que mantener.
Si desea una visión más amplia de cómo encajan las verificaciones automatizadas en un 'pipeline', la guía de 12 mejores prácticas de CI/CD para pruebas de API es una buena lectura complementaria.
Prerrequisitos
Antes de escribir la configuración, tenga esto listo en la aplicación Apidog:
- Un token de acceso. Genérelo en la configuración de su cuenta Apidog. Esto autentica la CLI en entornos sin interfaz gráfica. La guía de autenticación de Apidog CLI cubre la creación de tokens y el manejo de secretos de CI en detalle.
- Un ID de escenario de prueba. Abra el escenario de prueba que desea ejecutar y copie su ID de la URL o de la configuración del escenario.
- Un ID de entorno. Esto le dice a la CLI qué URL base y variables usar, como las de 'staging' o producción.
También necesitará una cuenta de CircleCI conectada a su proveedor de Git, con el proyecto habilitado en el panel de CircleCI.
Almacenar secretos como variables de entorno
Nunca codifique su token de acceso directamente en config.yml. El archivo se sube a Git, por lo que un token allí es un token filtrado.
CircleCI le ofrece dos opciones seguras:
- Variables de entorno del proyecto. En la interfaz de usuario de CircleCI, abra Configuración del Proyecto, luego Variables de Entorno, y añada cada valor. Se cifran y se exponen a los trabajos como
$VARS. - Contextos. Un contexto es un grupo nombrado de variables de entorno compartidas entre proyectos. Se crea en Configuración de la Organización, luego Contextos, y se referencia desde un flujo de trabajo. Los contextos son útiles cuando varios repositorios comparten el mismo token de Apidog.
Para esta guía, añada tres variables: APIDOG_ACCESS_TOKEN, APIDOG_TEST_SCENARIO_ID y APIDOG_ENVIRONMENT_ID. La CLI las lee en tiempo de ejecución, y nada sensible vive en su repositorio.
El config.yml completo
Aquí tiene una configuración completa para copiar y pegar. Colóquela en .circleci/config.yml, configure sus tres variables de entorno y haga 'push'.
version: 2.1
jobs:
api-tests:
docker:
- image: cimg/node:20.11
steps:
- checkout
- run:
name: Install Apidog CLI
command: npm install -g apidog-cli
- run:
name: Run Apidog API tests
command: |
apidog run \
--access-token $APIDOG_ACCESS_TOKEN \
-t $APIDOG_TEST_SCENARIO_ID \
-e $APIDOG_ENVIRONMENT_ID \
-r cli,junit,html \
--out-dir ./reports
- store_test_results:
path: ./reports
- store_artifacts:
path: ./reports
workflows:
test-api:
jobs:
- api-tests
Permítame desglosar lo que hace cada parte.
El ejecutor
docker:
- image: cimg/node:20.11
cimg/node es la imagen de conveniencia de CircleCI para Node.js. Viene con Node, npm y herramientas de construcción comunes preinstaladas, por lo que npm install -g apidog-cli funciona sin configuración adicional. La etiqueta :20.11 fija una versión de Node; fíjela a la que su equipo estandarice.
Los pasos
checkout extrae su repositorio al directorio de trabajo del trabajo. El primer paso run instala la CLI globalmente. El segundo paso run ejecuta sus pruebas.
Mire el comando de prueba de cerca:
apidog run \
--access-token $APIDOG_ACCESS_TOKEN \
-t $APIDOG_TEST_SCENARIO_ID \
-e $APIDOG_ENVIRONMENT_ID \
-r cli,junit,html \
--out-dir ./reports
Cada bandera hace un trabajo:
--access-tokenautentica la ejecución. No tiene forma corta.-tselecciona el escenario de prueba por ID.-eselecciona el entorno. Esta bandera es obligatoria; la CLI necesita saber qué URL base y variables usar.-restablece los reportadores. Aquí pide tres:cliimprime resultados en vivo en el registro de la compilación,junitescribe XML legible por máquina, yhtmlescribe un informe navegable.--out-dirle dice a la CLI dónde escribir los archivos de informe.
Publicando los informes
- store_test_results:
path: ./reports
- store_artifacts:
path: ./reports
store_test_results apunta a CircleCI al XML de JUnit en ./reports. CircleCI lo analiza y muestra una pestaña de Pruebas en la compilación, de modo que los fallos se enumeran por nombre con datos de tiempo. Esto es lo que convierte un muro de texto de registro en una vista estructurada de aprobado/fallido.
store_artifacts sube el mismo directorio como archivos descargables, incluyendo el informe HTML. Después de una compilación, abre la pestaña de Artefactos y ve el informe renderizado en su navegador. La guía de informes de prueba de Apidog CLI explica los formatos CLI, HTML y JSON con mayor profundidad.
El flujo de trabajo
workflows:
test-api:
jobs:
- api-tests
Este flujo de trabajo ejecuta el trabajo api-tests en cada 'push'. Puede añadir filtros para restringirlo a ciertas ramas, o añadir otros trabajos que se ejecuten antes o después. Para un único trabajo de prueba, este bloque mínimo es todo lo que necesita.
Ejecutar pruebas solo en la rama principal
Puede que no desee una ejecución completa de la API en cada rama de características. Añada un filtro de rama al flujo de trabajo:
workflows:
test-api:
jobs:
- api-tests:
filters:
branches:
only:
- main
- develop
Ahora el trabajo se ejecuta solo en los 'pushes' a main y develop. Otras ramas lo saltan, lo que mantiene sus minutos de compilación enfocados en las ramas que se despliegan.
Usar un Contexto en lugar de variables de proyecto
Si varios repositorios comparten un token de Apidog, un Contexto lo mantiene en un solo lugar. Cree el Contexto en Configuración de la Organización, añada sus variables allí, luego referéncielo:
workflows:
test-api:
jobs:
- api-tests:
context:
- apidog-secrets
El trabajo ahora lee APIDOG_ACCESS_TOKEN y el resto del Contexto apidog-secrets. Rote el token una vez, y cada proyecto recogerá el nuevo valor.
Ejecuciones basadas en datos y otras opciones
La CLI tiene más banderas de las que utiliza esta guía. Dos vale la pena conocer para CI.
Puede repetir un escenario a través de filas de datos de prueba con -d y -n:
apidog run \
--access-token $APIDOG_ACCESS_TOKEN \
-t $APIDOG_TEST_SCENARIO_ID \
-e $APIDOG_ENVIRONMENT_ID \
-d ./data/users.csv \
-r cli,junit \
--out-dir ./reports
La bandera -d toma una ruta de archivo CSV o JSON, o un ID numérico de conjunto de datos almacenado, y ejecuta el escenario una vez por fila. La guía de pruebas basadas en datos muestra cómo estructurar esos archivos.
También puede controlar cómo la ejecución maneja los fallos con --on-error, que acepta continue, end o ignore. Y para proyectos que usan ramas de Apidog, --project <id> --branch <name> apunta a una rama específica. Para enviar un resumen del informe a la nube de Apidog, añada --upload-report como una bandera simple.
Cómo encaja esto en el flujo de trabajo de Apidog
El objetivo de Apidog CLI es que usted no escribe ni mantiene código de prueba. Usted construye un escenario de prueba desde la línea de comandos o en el constructor visual de pruebas, establece aserciones sobre códigos de estado y cuerpos de respuesta, y lo guarda. CI luego ejecuta ese mismo escenario.
Debido a que el escenario vive en su proyecto Apidog, su equipo edita las pruebas en un solo lugar. La configuración de CI rara vez cambia; simplemente llama a apidog run. Cuando alguien añade una aserción en la aplicación, la siguiente compilación de CircleCI la recoge sin necesidad de editar el YAML.
Eso mantiene una clara división. Apidog posee lo que se prueba. CircleCI posee cuándo y dónde se ejecuta. Si desea comparar CircleCI con otros ejecutores para este tipo de trabajo, el resumen de herramientas de integración continua para equipos de API expone las ventajas y desventajas.
¿Listo para incluir su suite de API en cada 'push'? Descargue Apidog, construya un escenario de prueba y coloque la configuración anterior en su repositorio.
botón
Preguntas Frecuentes
Qué es CircleCI
CircleCI es una plataforma de integración y entrega continua en la nube. Se conecta a su repositorio Git, lee un archivo .circleci/config.yml y ejecuta automáticamente los pasos de construcción, prueba y despliegue cada vez que sube código. Elimina la necesidad de ejecutar esos pasos manualmente en su propia máquina.
Para qué se usa CircleCI
Los equipos usan CircleCI para automatizar las pruebas y el despliegue. Los trabajos comunes incluyen compilar código, ejecutar pruebas unitarias y de integración, verificar contratos de API, construir imágenes Docker y enviar lanzamientos a entornos de 'staging' o producción. En esta guía, el trabajo ejecuta pruebas de API de Apidog CLI en cada 'push'.
¿Es CircleCI gratuito?
CircleCI tiene un plan gratuito que incluye una asignación mensual de créditos de compilación, lo cual es suficiente para proyectos pequeños y repositorios personales. Los equipos más grandes que necesitan mayor concurrencia, más minutos de compilación o máquinas más potentes, pasan a los planes de pago Performance y Scale. Consulte la página de precios actual de CircleCI para conocer los límites exactos.
¿Es CircleCI de código abierto?
No, CircleCI es un producto comercial, alojado, no de código abierto. Lo configura a través de un archivo YAML y lo ejecuta en la infraestructura de CircleCI o en un 'runner' autoalojado. Si necesita un servidor de CI completamente de código abierto, Jenkins es la alternativa común, que se discute en la comparación CircleCI vs Jenkins.
¿Cómo funciona CircleCI?
Cuando hace un 'commit', CircleCI detecta el cambio, lee .circleci/config.yml y activa el ejecutor que usted definió, como un contenedor Docker cimg/node. Ejecuta cada paso en sus trabajos en orden, luego informa los resultados a su proveedor de Git. Los flujos de trabajo le permiten encadenar y paralelizar trabajos. Para una visión más amplia de cómo encaja esto en un 'pipeline' de entrega, consulte la guía Qué es CI/CD.