Cómo ejecutar pruebas API de Apidog CLI en Drone CI

Ejecuta pruebas de API con Apidog CLI en Drone CI añadiendo un paso Docker en tu pipeline: usa una imagen de Node, instala apidog-cli y ejecuta apidog run contra un entorno de Apidog. Guarda el token de acceso como secreto de Drone e inyéctalo con from_secret. En esta guía verás un .drone.yml listo para copiar, cómo manejar secretos, cómo limitar ejecuciones por rama y cómo exponer informes cuando Drone no tiene almacenamiento de artefactos integrado.

Prueba Apidog hoy

Qué es Drone CI y cómo funciona

Drone es una plataforma CI/CD de código abierto y nativa de contenedores, ahora parte de Harness. CI/CD significa integración continua y entrega continua: compilar, probar y entregar cambios de forma automática. Si necesitas repasar el concepto, consulta qué es CI/CD.

La idea central de Drone es simple: cada paso del pipeline se ejecuta dentro de su propio contenedor Docker. No dependes de un agente compartido lleno de herramientas preinstaladas. Tú eliges la imagen de cada paso y Drone ejecuta los comandos dentro de ella.

Define el pipeline en un archivo .drone.yml en la raíz del repositorio. Un pipeline Docker usa estas claves principales:

• kind
• type
• name
• steps

Ejemplo mínimo:

kind: pipeline
type: docker
name: api-tests

steps:
  - name: greeting
    image: alpine
    commands:
      - echo hello
      - echo world

Drone ejecuta commands como un script de shell con set -e y set -x. Eso significa que:

• el paso falla en el primer comando con código de salida distinto de cero;
• cada comando se imprime antes de ejecutarse;
• el directorio de trabajo es la raíz del repositorio;
• los comandos reemplazan el entrypoint del contenedor.

Por qué ejecutar pruebas de API en Drone

Las pruebas de API evitan regresiones de contrato. Por ejemplo, un cambio en el backend puede modificar un código de estado, eliminar un campo de respuesta o cambiar el formato de un payload. Si ejecutas estas pruebas en cada push o pull_request, detectas el problema antes del despliegue.

Apidog encaja bien en este flujo:

1. Diseñas y mantienes los escenarios en la interfaz de Apidog.
2. Guardas variables y entornos en Apidog.
3. Ejecutas los mismos escenarios desde CI con Apidog CLI.
4. Drone falla el pipeline si las pruebas fallan.

No necesitas duplicar los tests en scripts separados. Para una guía más amplia, revisa las mejores prácticas de CI/CD para pruebas de API.

Apidog es una plataforma API todo en uno para diseño, depuración, pruebas, simulación y documentación. La CLI convierte tus escenarios guardados en un comando repetible, ideal para ejecutarse dentro de un paso de Drone.

Comando base de Apidog CLI

En CI, instala la CLI con npm y ejecuta un escenario guardado:

npm install -g apidog-cli
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 1234567 -e 89012 -r cli

Parámetros principales:

• --access-token: token de acceso de Apidog. No tiene forma abreviada.
• -t: ID del escenario de prueba.
• -e: ID del entorno. Es obligatorio y define URL base y variables.
• -r: reporteros de salida. Valores válidos: cli, html, json, junit.

Parámetros útiles para CI:

• -n o --iteration-count: repite la ejecución un número determinado de veces.
• -d o --iteration-data: usa un archivo CSV/JSON o un ID de dataset almacenado.
• --out-dir: define el directorio de salida de reportes.
• --upload-report: sube un resumen del informe a la nube de Apidog.
• --on-error: controla el comportamiento en caso de error: continue, end o ignore.
• --project <id> y --branch <name>: apuntan a una rama específica del proyecto.

Para ver todas las opciones, consulta la guía completa de Apidog CLI y el tutorial sobre cómo probar una API REST desde la línea de comandos.

.drone.yml completo para ejecutar pruebas de Apidog

Crea este archivo en la raíz de tu repositorio:

kind: pipeline
type: docker
name: apidog-api-tests

steps:
  - name: run-api-tests
    image: node:20-alpine
    environment:
      APIDOG_ACCESS_TOKEN:
        from_secret: apidog_access_token
    commands:
      - npm install -g apidog-cli
      - apidog run --access-token $APIDOG_ACCESS_TOKEN -t 1234567 -e 89012 -r cli

trigger:
  branch:
    - main
  event:
    - push
    - pull_request

Sustituye:

• 1234567 por el ID de tu escenario de prueba.
• 89012 por el ID de tu entorno.

Con -r cli, los resultados se imprimen directamente en el log del build de Drone. Esto suele ser suficiente para revisar qué aserciones pasaron y cuáles fallaron.

Almacenar el token de Apidog como secreto de Drone

No guardes el token en el repositorio. Usa secretos de Drone.

En el YAML, referencia el secreto así:

environment:
  APIDOG_ACCESS_TOKEN:
    from_secret: apidog_access_token

apidog_access_token es el nombre del secreto en Drone, no el valor real del token.

Opción 1: crear el secreto desde la UI

1. Abre tu repositorio en Drone.
2. Ve a Settings.
3. Abre Secrets.
4. Crea un secreto llamado apidog_access_token.
5. Pega tu token de Apidog como valor.

Opción 2: crear el secreto con Drone CLI

drone secret add \
  --repository your-org/your-repo \
  --name apidog_access_token \
  --data your-apidog-token

Verifica los nombres exactos de los flags con la documentación de tu versión de Drone CLI, ya que pueden variar.

Drone también admite secretos cifrados en el repositorio mediante drone encrypt, que genera un bloque YAML kind: secret. Para la mayoría de los equipos, los secretos de repositorio creados desde la UI o con drone secret add son más simples.

Para más detalles sobre credenciales en la CLI, revisa la guía de autenticación de Apidog CLI.

Limitar ejecuciones por rama y evento

Drone permite controlar cuándo se ejecuta el pipeline con dos mecanismos:

• trigger: aplica a todo el pipeline.
• when: aplica a un paso específico.

Usar trigger para todo el pipeline

Este ejemplo ejecuta el pipeline solo en push y pull_request sobre main:

trigger:
  branch:
    - main
  event:
    - push
    - pull_request

Úsalo cuando no quieras que ningún paso del pipeline se ejecute fuera de esas condiciones.

Usar when para un paso concreto

Este ejemplo limita solo el paso de pruebas de API:

steps:
  - name: run-api-tests
    image: node:20-alpine
    environment:
      APIDOG_ACCESS_TOKEN:
        from_secret: apidog_access_token
    commands:
      - npm install -g apidog-cli
      - apidog run --access-token $APIDOG_ACCESS_TOKEN -t 1234567 -e 89012 -r cli
    when:
      branch:
        - main
      event:
        - push

Esto es útil si quieres ejecutar otros pasos en todas las ramas, pero reservar las pruebas de API para main.

Drone admite patrones glob y subclaves de inclusión/exclusión. Los eventos soportados incluyen:

• push
• pull_request
• tag
• promote
• rollback
• cron
• custom

Exponer informes de pruebas en Drone

Drone no incluye hosting nativo de artefactos. Para los informes de Apidog tienes dos opciones prácticas.

Opción 1: imprimir resultados en el log

La forma más simple es usar el reportero cli:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 1234567 -e 89012 -r cli

El resultado queda disponible en el log del build. Para muchos equipos esto es suficiente.

Opción 2: generar HTML y subirlo a S3

Si necesitas un informe persistente, genera HTML con -r html y súbelo a S3 o a un almacenamiento compatible con S3 usando el plugin plugins/s3.

kind: pipeline
type: docker
name: apidog-api-tests

steps:
  - name: run-api-tests
    image: node:20-alpine
    environment:
      APIDOG_ACCESS_TOKEN:
        from_secret: apidog_access_token
    commands:
      - npm install -g apidog-cli
      - apidog run --access-token $APIDOG_ACCESS_TOKEN -t 1234567 -e 89012 -r cli,html --out-dir reports

  - name: upload-report
    image: plugins/s3
    settings:
      bucket: my-bucket
      region: us-east-1
      source: reports/**/*
      target: /apidog-reports
      access_key:
        from_secret: aws_access_key
      secret_key:
        from_secret: aws_secret_key

Puntos clave:

• --out-dir reports guarda los informes en reports.
• source: reports/**/* indica qué archivos subir.
• target: /apidog-reports define el prefijo dentro del bucket.
• aws_access_key y aws_secret_key también deben existir como secretos de Drone.

Para entender mejor el contenido del informe, consulta el desglose de informes de pruebas de Apidog CLI.

Ejecutar pruebas basadas en datos

Si un escenario debe ejecutarse con múltiples entradas, usa -d. La CLI acepta:

• archivo CSV;
• archivo JSON;
• ID de dataset almacenado.

Ejemplo con CSV:

commands:
  - npm install -g apidog-cli
  - apidog run --access-token $APIDOG_ACCESS_TOKEN -t 1234567 -e 89012 -d ./data.csv -r cli

Cada fila de data.csv se convierte en una iteración. Los valores de las columnas se vinculan a las variables usadas por tu escenario de Apidog.

El flujo completo está explicado en pruebas basadas en datos con Apidog CLI.

Comparación con otras herramientas de CI

El patrón es el mismo en casi cualquier sistema de CI:

1. Levantar un entorno limpio.
2. Instalar apidog-cli.
3. Inyectar el token como secreto.
4. Ejecutar apidog run.
5. Fallar el build si las pruebas fallan.

La sintaxis del pipeline cambia, pero el comando de Apidog se mantiene.

Si también usas otros sistemas, revisa los tutoriales para GitHub Actions y Azure Pipelines.

Una aclaración importante: Apidog CLI ejecuta pruebas funcionales y de contrato. No sustituye una herramienta de pruebas de carga a gran escala. Si necesitas miles de usuarios virtuales concurrentes, usa una herramienta dedicada de load testing. Para validar comportamiento de API en cada commit, Apidog CLI dentro de Drone cubre bien el caso.

Flujo recomendado

Un flujo práctico sería:

1. Diseña endpoints y escenarios en Apidog.
2. Crea un entorno con la URL base y variables necesarias.
3. Obtén el ID del escenario y el ID del entorno.
4. Crea el secreto apidog_access_token en Drone.
5. Añade el .drone.yml al repositorio.
6. Haz push a main o abre un pull_request.
7. Revisa el resultado en los logs de Drone o en el informe HTML.

La ventaja es que las pruebas se mantienen en un solo lugar: Apidog. Cuando alguien actualiza un escenario en la aplicación, el siguiente build de Drone ejecuta esa versión. No hay una copia adicional de scripts que mantener sincronizada.

Descarga Apidog gratis para crear tu primer escenario de prueba y luego copia el .drone.yml anterior en tu repositorio.

Preguntas frecuentes

¿Qué es Drone CI?

Drone es una plataforma CI/CD de código abierto y nativa de contenedores, ahora parte de Harness. Ejecuta cada paso del pipeline dentro de su propio contenedor Docker y define pipelines mediante un archivo .drone.yml.

¿Es Drone CI gratis?

El proyecto central de Drone es de código abierto y puede autoalojarse gratis. Después de la adquisición por Harness, Drone pasó a formar parte de Harness CI Community Edition, con planes empresariales de pago disponibles.

¿Es Drone CI de código abierto?

Sí. Drone sigue siendo una herramienta CI nativa de contenedores de código abierto y puede autoalojarse.

¿Cómo se usa Drone CI?

Añades un archivo .drone.yml a tu repositorio. Drone lo lee en cada evento configurado, como push o pull_request, y ejecuta los pasos definidos dentro de contenedores. Los pasos habituales incluyen compilar código, ejecutar pruebas unitarias, correr pruebas de API y subir artefactos a almacenamiento externo.

¿Cómo se almacenan secretos en Drone CI?

Puedes añadir secretos desde la UI de Drone en Settings > Secrets o con drone secret add desde la CLI. Luego los referencias en environment o settings usando from_secret. El valor real del secreto no aparece en el YAML.

¿Puedo ejecutar pruebas de Apidog en CI sin escribir scripts?

Sí. Construyes los escenarios visualmente en Apidog y los ejecutas en CI con un único comando apidog run. En Drone solo necesitas una imagen de Node, instalar apidog-cli y pasar el token, el ID del escenario y el ID del entorno.