DEV Community

Cover image for Cómo ejecutar pruebas de API de Apidog CLI en CircleCI
Roobia
Roobia

Posted on • Originally published at apidog.com

Cómo ejecutar pruebas de API de Apidog CLI en CircleCI

Para ejecutar pruebas de API de Apidog CLI en CircleCI, cree .circleci/config.yml, use un ejecutor Docker cimg/node, instale apidog-cli con npm y ejecute apidog run con su token de acceso, el ID del escenario de prueba y el ID del entorno. Guarde esos valores como variables de entorno de CircleCI y publique los reportes JUnit/HTML con store_test_results y store_artifacts.

Prueba Apidog hoy

Este artículo se centra en la ejecución de pruebas de API, no en elegir una plataforma de CI. Si todavía está comparando opciones, consulte la comparación CircleCI vs Jenkins. Aquí asumimos que ya usa CircleCI y quiere ejecutar su suite de API en cada push.

Qué es CircleCI y cómo funciona

CircleCI es una plataforma de integración y entrega continua. Se conecta a su repositorio Git y ejecuta los pasos definidos en .circleci/config.yml cuando detecta cambios.

En una configuración típica de CircleCI intervienen tres conceptos:

  • Jobs: unidades de trabajo. Por ejemplo, instalar dependencias y ejecutar pruebas.
  • Executors: entorno donde corre el job. En esta guía usaremos Docker con cimg/node.
  • Workflows: orquestan uno o varios jobs y definen cuándo se ejecutan.

Para pruebas de API, el patrón es simple:

  1. CircleCI hace checkout del repositorio.
  2. Instala Apidog CLI.
  3. Ejecuta un escenario de prueba de Apidog.
  4. Guarda los resultados como reportes JUnit y artefactos HTML.

Por qué ejecutar pruebas de API en CircleCI

Ejecutar pruebas de API en CI ayuda a detectar cambios incompatibles antes de llegar a producción: respuestas con esquema distinto, campos renombrados, códigos de estado incorrectos o flujos de autenticación rotos.

El Apidog CLI permite ejecutar en CI los mismos escenarios que diseña en Apidog. No necesita duplicar aserciones en otro framework ni mantener un arnés de pruebas separado.

Si quiere profundizar en la estrategia general, consulte estas 12 mejores prácticas de CI/CD para pruebas de API.

Prerrequisitos

Antes de crear el archivo de CircleCI, prepare estos datos en Apidog:

  • Token de acceso: autentica Apidog CLI en CI. Puede generarlo desde la configuración de su cuenta. La guía de autenticación de Apidog CLI explica cómo manejar tokens y secretos.
  • ID del escenario de prueba: identifica el escenario que quiere ejecutar.
  • ID del entorno: define qué URL base y variables usará la ejecución, por ejemplo staging o producción.

También necesita:

  • Una cuenta de CircleCI.
  • El repositorio conectado a CircleCI.
  • El proyecto habilitado en el dashboard de CircleCI.

Configurar variables de entorno en CircleCI

No escriba tokens directamente en .circleci/config.yml. Ese archivo vive en Git, por lo que cualquier secreto quedaría expuesto.

Cree estas variables en CircleCI:

APIDOG_ACCESS_TOKEN
APIDOG_TEST_SCENARIO_ID
APIDOG_ENVIRONMENT_ID
Enter fullscreen mode Exit fullscreen mode

Puede definirlas de dos formas:

Opción 1: variables del proyecto

En CircleCI:

  1. Abra el proyecto.
  2. Vaya a Project Settings.
  3. Abra Environment Variables.
  4. Añada las tres variables.

CircleCI las expondrá al job como variables de entorno:

$APIDOG_ACCESS_TOKEN
$APIDOG_TEST_SCENARIO_ID
$APIDOG_ENVIRONMENT_ID
Enter fullscreen mode Exit fullscreen mode

Opción 2: Contextos

Use un Context si varios repositorios comparten los mismos secretos.

  1. Vaya a Organization Settings.
  2. Abra Contexts.
  3. Cree un contexto, por ejemplo apidog-secrets.
  4. Añada las variables.
  5. Referencie el contexto desde el workflow.

Más adelante verá el ejemplo YAML.

Crear .circleci/config.yml

Cree este archivo en la raíz del repositorio:

.circleci/config.yml
Enter fullscreen mode Exit fullscreen mode

Pegue esta configuración:

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
Enter fullscreen mode Exit fullscreen mode

Después haga commit y push:

git add .circleci/config.yml
git commit -m "Run Apidog API tests in CircleCI"
git push
Enter fullscreen mode Exit fullscreen mode

CircleCI detectará el cambio y ejecutará el workflow.

Entender cada parte del config.yml

Executor Docker 

docker:
  - image: cimg/node:20.11
Enter fullscreen mode Exit fullscreen mode

cimg/node es una imagen oficial de conveniencia de CircleCI para proyectos Node.js. Incluye Node.js, npm y herramientas comunes.

La etiqueta 20.11 fija la versión de Node. En equipos, conviene usar una versión explícita para evitar cambios inesperados en CI.

Checkout del repositorio 

- checkout
Enter fullscreen mode Exit fullscreen mode

Este paso clona el repositorio dentro del entorno del job.

Instalación de Apidog CLI 

- run:
    name: Install Apidog CLI
    command: npm install -g apidog-cli
Enter fullscreen mode Exit fullscreen mode

Instala apidog-cli globalmente dentro del contenedor.

Ejecución de pruebas 

apidog run \
  --access-token $APIDOG_ACCESS_TOKEN \
  -t $APIDOG_TEST_SCENARIO_ID \
  -e $APIDOG_ENVIRONMENT_ID \
  -r cli,junit,html \
  --out-dir ./reports
Enter fullscreen mode Exit fullscreen mode

Qué hace cada opción:

  • --access-token: autentica la CLI con Apidog.
  • -t: indica el ID del escenario de prueba.
  • -e: indica el ID del entorno.
  • -r cli,junit,html: genera salida en consola, reporte JUnit y reporte HTML.
  • --out-dir ./reports: guarda los reportes en el directorio reports.

Publicar reportes en CircleCI

La configuración incluye dos pasos para guardar resultados:

- store_test_results:
    path: ./reports
- store_artifacts:
    path: ./reports
Enter fullscreen mode Exit fullscreen mode

store_test_results permite que CircleCI lea los archivos JUnit y muestre los resultados en la pestaña de pruebas.

store_artifacts sube los archivos del directorio ./reports como artefactos descargables. Ahí podrá abrir el reporte HTML generado por Apidog CLI.

Para más detalle sobre formatos de salida, consulte la guía de reportes de prueba de Apidog CLI.

Ejecutar pruebas solo en ramas específicas

Si no quiere ejecutar la suite de API en cada rama, añada filtros al workflow:

workflows:
  test-api:
    jobs:
      - api-tests:
          filters:
            branches:
              only:
                - main
                - develop
Enter fullscreen mode Exit fullscreen mode

Con esta configuración, CircleCI ejecutará api-tests solo en pushes a main y develop.

Usar un Context de CircleCI

Si configuró las variables en un contexto llamado apidog-secrets, referéncielo así:

workflows:
  test-api:
    jobs:
      - api-tests:
          context:
            - apidog-secrets
Enter fullscreen mode Exit fullscreen mode

El job podrá leer:

$APIDOG_ACCESS_TOKEN
$APIDOG_TEST_SCENARIO_ID
$APIDOG_ENVIRONMENT_ID
Enter fullscreen mode Exit fullscreen mode

Esto evita duplicar secretos en múltiples proyectos. Si rota el token, solo tiene que actualizarlo en el contexto.

Ejecutar pruebas basadas en datos

Apidog CLI también permite ejecutar un escenario usando datos externos con -d.

Ejemplo con CSV:

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
Enter fullscreen mode Exit fullscreen mode

-d puede recibir:

  • Una ruta a un archivo CSV.
  • Una ruta a un archivo JSON.
  • Un ID numérico de conjunto de datos almacenado.

La guía de pruebas basadas en datos muestra cómo estructurar esos archivos.

Controlar el comportamiento ante errores

Puede ajustar qué hace la CLI cuando encuentra errores con --on-error.

Valores disponibles:

--on-error continue
--on-error end
--on-error ignore
Enter fullscreen mode Exit fullscreen mode

Ejemplo:

apidog run \
  --access-token $APIDOG_ACCESS_TOKEN \
  -t $APIDOG_TEST_SCENARIO_ID \
  -e $APIDOG_ENVIRONMENT_ID \
  --on-error end \
  -r cli,junit,html \
  --out-dir ./reports
Enter fullscreen mode Exit fullscreen mode

Use esta opción según cómo quiera que CI responda ante fallos parciales.

Ejecutar pruebas desde una rama de Apidog

Si su proyecto usa ramas en Apidog, puede apuntar a una rama específica con:

--project <id> --branch <name>
Enter fullscreen mode Exit fullscreen mode

Ejemplo:

apidog run \
  --access-token $APIDOG_ACCESS_TOKEN \
  --project 123456 \
  --branch develop \
  -t $APIDOG_TEST_SCENARIO_ID \
  -e $APIDOG_ENVIRONMENT_ID \
  -r cli,junit,html \
  --out-dir ./reports
Enter fullscreen mode Exit fullscreen mode

Subir resumen del reporte a Apidog

Para enviar un resumen del reporte a la nube de Apidog, añada:

--upload-report
Enter fullscreen mode Exit fullscreen mode

Ejemplo:

apidog run \
  --access-token $APIDOG_ACCESS_TOKEN \
  -t $APIDOG_TEST_SCENARIO_ID \
  -e $APIDOG_ENVIRONMENT_ID \
  -r cli,junit,html \
  --out-dir ./reports \
  --upload-report
Enter fullscreen mode Exit fullscreen mode

Cómo encaja esto en el flujo de trabajo de Apidog

El flujo recomendado es:

  1. Diseñe el escenario de prueba en Apidog.
  2. Añada aserciones sobre códigos de estado, headers y cuerpos de respuesta.
  3. Guarde el escenario.
  4. Ejecútelo desde CircleCI con apidog run.

Puede crear y ejecutar escenarios con la CLI o desde el constructor visual. La guía sobre cómo probar una API REST desde la línea de comandos cubre ese flujo.

La ventaja es que CircleCI no necesita conocer la lógica interna de las pruebas. Solo ejecuta el escenario definido en Apidog. Si alguien del equipo añade una aserción en Apidog, la siguiente ejecución de CircleCI la usará sin modificar el YAML.

La separación queda clara:

  • Apidog define qué se prueba.
  • CircleCI define cuándo y dónde se ejecuta.

Si quiere comparar CircleCI con otros ejecutores de CI para equipos de API, revise esta lista de herramientas de integración continua para equipos de API.

Checklist de implementación

Antes de hacer merge, valide lo siguiente:

  • [ ] Existe .circleci/config.yml.
  • [ ] El proyecto está habilitado en CircleCI.
  • [ ] APIDOG_ACCESS_TOKEN está configurado como variable segura.
  • [ ] APIDOG_TEST_SCENARIO_ID contiene el ID correcto.
  • [ ] APIDOG_ENVIRONMENT_ID apunta al entorno adecuado.
  • [ ] El comando apidog run genera reportes en ./reports.
  • [ ] store_test_results y store_artifacts apuntan al mismo directorio.
  • [ ] El workflow se ejecuta en las ramas esperadas.

Para empezar, descargue Apidog, cree un escenario de prueba y añada la configuración anterior a su repositorio.

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 .circleci/config.yml y ejecuta automáticamente pasos de construcción, prueba y despliegue cuando sube código.

Para qué se usa CircleCI

Los equipos usan CircleCI para automatizar tareas como:

  • Compilar código.
  • Ejecutar pruebas unitarias.
  • Ejecutar pruebas de integración.
  • Verificar contratos de API.
  • Construir imágenes Docker.
  • Desplegar a staging o producción.

En esta guía, CircleCI ejecuta pruebas de API de Apidog CLI en cada push.

¿Es CircleCI gratuito?

CircleCI ofrece un plan gratuito con una asignación mensual de créditos de compilación, útil para proyectos pequeños y repositorios personales. Los equipos que necesitan más concurrencia, más minutos o máquinas más potentes suelen usar planes de pago. Consulte la página de precios de CircleCI para ver límites actualizados.

¿Es CircleCI de código abierto?

No. CircleCI es un producto comercial alojado. Se configura con YAML y puede ejecutarse en infraestructura de CircleCI o mediante runners autoalojados.

Si necesita un servidor CI de código abierto, Jenkins es una alternativa común. Puede revisar la comparación CircleCI vs Jenkins mencionada al inicio.

¿Cómo funciona CircleCI?

Cuando hace un commit, CircleCI detecta el cambio, lee .circleci/config.yml y crea un pipeline. Luego inicia el executor definido, por ejemplo un contenedor Docker cimg/node, y ejecuta los steps de cada job en orden.

Los workflows permiten encadenar jobs, ejecutarlos en paralelo y aplicar filtros por rama. Para una visión más amplia del concepto, consulte la guía Qué es CI/CD.

Top comments (0)