Ejecutas pruebas de API con Apidog CLI en Drone CI añadiendo un paso de pipeline de Docker que utiliza una imagen de Node, instala apidog-cli y ejecuta apidog run contra un entorno. Tu token de acceso de Apidog se guarda en un secreto de Drone y se inyecta a través de from_secret. Esta guía te muestra un .drone.yml para copiar y pegar, el manejo de secretos, la restricción por rama y cómo exponer el informe de pruebas, ya que Drone no tiene un almacén de artefactos incorporado.
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, la práctica de construir y probar código automáticamente con cada cambio. Si deseas un repaso del concepto en sí, consulta qué es CI/CD.
La característica que define a Drone es simple: cada paso del pipeline se ejecuta dentro de su propio contenedor Docker. No hay un agente de compilación compartido con una proliferación de herramientas preinstaladas. Tú eliges una imagen para cada paso, y Drone ejecuta tus comandos dentro de ella. Esto hace que las compilaciones sean reproducibles y fáciles de entender.
Defines un pipeline en un archivo .drone.yml en la raíz de tu repositorio. Un pipeline de Docker tiene tres claves de nivel superior: kind, type y name. El trabajo se realiza bajo steps, donde cada paso declara un name, una image y una lista de commands.
kind: pipeline
type: docker
name: api-tests
steps:
- name: greeting
image: alpine
commands:
- echo hello
- echo world
Drone ejecuta los commands como un script de shell con set -e y set -x, por lo que la compilación falla rápidamente al primer código de salida distinto de cero y muestra cada comando antes de ejecutarlo. Los comandos anulan el punto de entrada del contenedor, y el directorio de trabajo es la raíz de tu repositorio.
Por qué ejecutar pruebas de API en un paso de contenedor
Las pruebas de API protegen contra la desviación del contrato. Un cambio en el backend que altere silenciosamente la forma de una respuesta o un código de estado puede romper todos los clientes posteriores. Ejecutar esas pruebas en cada `push` detecta la regresión antes de que se despliegue.
Apidog encaja bien con este modelo. Construyes y mantienes tus pruebas visualmente en la aplicación de Apidog, luego ejecutas los mismos escenarios de prueba desde la línea de comandos con Apidog CLI. Sin reescritura de scripts, sin arnés de pruebas separado. Para una guía más amplia sobre cómo integrar pruebas de API en pipelines, lee 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 es la pieza que convierte tus escenarios de prueba guardados en un único comando repetible, que es exactamente lo que necesita un paso de Drone.
El comando de Apidog CLI que ejecutarás
Instala la CLI con npm, luego ejecuta un escenario de prueba. En CI, apuntas la ejecución a un escenario guardado con "flags" (parámetros), por lo que no hay un archivo de colección local que gestionar.
npm install -g apidog-cli
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 1234567 -e 89012 -r cli
Esto es lo que hace cada "flag" (parámetro):
--access-tokenpasa tu token de acceso de Apidog. No hay forma abreviada.-tes el ID del escenario de prueba que deseas ejecutar.-ees el ID del entorno, y es obligatorio. Esto selecciona qué URL base y variables utiliza la ejecución.-renumera los reporteros. Los valores válidos soncli,html,jsonyjunit.
Puedes añadir más "flags" (parámetros) según sea necesario:
-no--iteration-countrepite la ejecución un número determinado de veces.-do--iteration-datatoma una ruta de archivo CSV o JSON, o un ID de conjunto de datos numérico almacenado, para ejecuciones basadas en datos.--out-direstablece el directorio de salida del informe.--upload-reportsube un resumen del informe a la nube de Apidog, donde puedes verlo en la aplicación. Puedes usarlo como un "flag" simple.--on-errorcontrola el comportamiento en caso de fallo concontinue,endoignore.--project <id>y--branch <name>apuntan a una rama de proyecto específica.
Para una revisión completa del comando y sus 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.
Un archivo .drone.yml completo para pruebas de Apidog
Aquí tienes un pipeline en funcionamiento. Utiliza una imagen de Node, instala la CLI y ejecuta tu escenario. El token proviene de un secreto de Drone en lugar de estar codificado.
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
Reemplaza 1234567 con el ID de tu escenario de prueba y 89012 con el ID de tu entorno. Ambos son visibles en la aplicación de Apidog. Debido a que el paso utiliza el reportero cli, el desglose completo de aprobados/fallidos se imprime directamente en el registro de compilación de Drone, donde cualquiera que revise la compilación puede leerlo.
Almacenamiento de secretos en Drone CI
Nunca subas un token de API a tu repositorio. Drone mantiene los secretos fuera del YAML y los inyecta en tiempo de ejecución.
Haces referencia a un secreto dentro del bloque environment de un paso (o el bloque settings de un plugin) con from_secret. El valor que escribes es el nombre del secreto, no el token en sí.
environment:
APIDOG_ACCESS_TOKEN:
from_secret: apidog_access_token
Hay dos formas comunes de crear el secreto. La primera es la interfaz de usuario de Drone: abre tu repositorio, ve a Configuración, luego a Secretos, y añade un secreto llamado apidog_access_token con tu token como valor. La segunda es la herramienta de línea de comandos de Drone.
drone secret add \
--repository your-org/your-repo \
--name apidog_access_token \
--data your-apidog-token
Confirma los nombres exactos de los "flags" (parámetros) con la documentación de Drone CLI para tu versión, ya que los "flags" de CLI pueden cambiar entre versiones. Drone también admite una variante de secreto cifrado en el repositorio donde drone encrypt produce un blob cifrado que incrustas como un documento YAML kind: secret separado. Para la mayoría de los equipos, los secretos de repositorio añadidos a través de la interfaz de usuario o drone secret add son más sencillos y el punto de partida recomendado.
Mantener el token en un secreto es la misma disciplina que aplicarías en cualquier otro lugar. Para más información sobre cómo la CLI gestiona las credenciales, consulta la guía sobre autenticación de Apidog CLI.
Restricción de ejecuciones por rama y evento
Drone te ofrece dos palancas para controlar cuándo se ejecuta el trabajo: trigger a nivel de pipeline y when a nivel de paso.
Un bloque trigger decide si se ejecuta todo el pipeline. Todas las condiciones deben evaluarse como verdaderas, por lo que el ejemplo siguiente se ejecuta solo en `pushes` y `pull requests` dirigidos a main.
trigger:
branch:
- main
event:
- push
- pull_request
Un bloque when se encuentra dentro de un único paso y restringe solo ese paso. Esto es útil cuando quieres que la mayor parte del pipeline se ejecute en todas partes, pero reservas un pase de prueba más intensivo para una rama.
steps:
- name: run-api-tests
image: node:20-alpine
commands:
- npm install -g apidog-cli
- apidog run --access-token $APIDOG_ACCESS_TOKEN -t 1234567 -e 89012 -r cli
when:
branch:
- main
event:
- push
Ambos bloques admiten patrones "glob" y subclaves de inclusión/exclusión. Los tipos de eventos admitidos incluyen push, pull_request, tag, promote, rollback, cron y custom.
Exposición de informes de pruebas sin un almacén de artefactos
Drone no tiene alojamiento nativo de artefactos. Esto cambia la forma en que manejas los informes, pero tienes dos opciones claras.
La primera es la más sencilla: usa el reportero cli para que los resultados se impriman en el registro de la compilación. Para la mayoría de los equipos esto es suficiente, ya que el registro ya muestra qué aserciones pasaron y cuáles fallaron.
La segunda opción es generar un informe HTML y subirlo a algún lugar duradero. Drone publica un plugin oficial de S3, plugins/s3, que sube archivos a S3 o a cualquier almacenamiento compatible con S3. Genera el informe con el reportero html y --out-dir, luego añade un paso de subida.
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
El plugin lee sus credenciales de AWS desde secretos a través de from_secret, el mismo mecanismo que usaste para el token de Apidog. La clave source es un patrón "glob" de archivos a subir, y target es el prefijo de destino en el "bucket".
Si deseas una mirada más profunda a lo que contiene el informe y cómo leerlo, consulta el desglose de los informes de pruebas de Apidog CLI.
Adición de ejecuciones basadas en datos
A veces, un escenario necesita ejecutarse contra muchas filas de entrada: diez IDs de usuario, una docena de "payloads", un conjunto de casos límite. La CLI maneja esto con -d, que acepta una ruta de archivo CSV o JSON o un ID de conjunto de datos almacenado.
commands:
- npm install -g apidog-cli
- apidog run --access-token $APIDOG_ACCESS_TOKEN -t 1234567 -e 89012 -d ./data.csv -r cli
Cada fila en data.csv se convierte en una iteración, con valores de columna vinculados a las variables de tu escenario. El patrón completo se cubre en pruebas basadas en datos con Apidog CLI.
Comparación con otras herramientas de CI
El patrón de Drone, instalar la CLI en un contenedor limpio y ejecutar un comando, se traslada a casi todos los sistemas de CI. La sintaxis del "wrapper" difiere, pero el paso de Apidog es el mismo.
Si también ejecutas pipelines en otros lugares, Apidog tiene tutoriales coincidentes para GitHub Actions y Azure Pipelines. La idea compartida es que tus pruebas residen en Apidog y la herramienta de CI simplemente las activa.
Una nota honesta sobre el alcance: Apidog CLI ejecuta pruebas funcionales y de contrato, no pruebas de carga a gran escala. Si necesitas miles de usuarios virtuales concurrentes para estresar un "endpoint", recurre a una herramienta de pruebas de carga dedicada. Para verificar que tu API se comporta correctamente en cada "commit", la CLI en un paso de Drone hace bien el trabajo.
Crea las pruebas visualmente, ejecútalas con un comando
El flujo de trabajo que hace esto agradable es la división entre la autoría y la ejecución. Diseñas "endpoints" y ensamblas escenarios de prueba visualmente en Apidog, encadenando solicitudes, afirmando sobre códigos de estado y campos de respuesta, y reutilizando variables de entorno. No se requiere código para construir el conjunto.
Luego, CI ejecuta la misma suite con un comando CLI dentro de un paso de contenedor. Cuando un compañero de equipo actualiza una prueba en la aplicación de Apidog, la siguiente compilación de Drone la recoge automáticamente. No hay una segunda copia de las pruebas que mantener sincronizada.
Descarga Apidog gratis para construir tu primer escenario de prueba, luego copia el .drone.yml anterior en tu repositorio para ejecutarlo en cada `push`.
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, con pipelines definidos en un archivo .drone.yml. Esto mantiene las compilaciones reproducibles y evita la proliferación de herramientas preinstaladas de los agentes de compilación tradicionales.
¿Es Drone CI gratis?
El proyecto central de Drone es de código abierto y de alojamiento propio gratuito. Después de la adquisición por parte de Harness, Drone se convirtió en Harness CI Community Edition, con planes empresariales de pago disponibles. Para la mayoría de los equipos, la versión de código abierto autoalojada cubre la ejecución de pruebas de API como las de esta guía.
¿Es Drone CI de código abierto?
Sí. Drone es una de las herramientas de CI originales nativas de contenedores y sigue siendo de código abierto. Cuando Harness lo adquirió en 2020, la compañía se comprometió a mantener el proyecto como código abierto, y todavía puedes autoalojarlo.
¿Cómo se usa Drone CI?
Los equipos utilizan Drone para construir, probar y entregar código automáticamente en cada `push` o `pull request`. Subes un .drone.yml a tu repositorio, Drone lo lee y ejecuta cada paso en un contenedor. Los pasos comunes incluyen compilar código, ejecutar pruebas unitarias, ejecutar pruebas de API y subir artefactos a un almacenamiento externo.
¿Cómo se almacenan secretos en Drone CI?
Añades secretos a través de la pantalla de Configuración y luego Secretos del repositorio en la interfaz de usuario de Drone, o con drone secret add desde la CLI. Luego haces referencia a cada secreto dentro del bloque environment de un paso o el bloque settings de un plugin usando from_secret, donde el valor es el nombre del secreto. El token en sí nunca aparece en tu YAML.
¿Puedo ejecutar pruebas de Apidog en CI sin escribir scripts?
Sí. Construyes escenarios de prueba visualmente en la aplicación de Apidog, luego los ejecutas en CI con un solo comando apidog run. El paso de Drone solo necesita una imagen de Node, una línea npm install -g apidog-cli y el comando de ejecución apuntando a los IDs de tu escenario y entorno.