Ejecutas pruebas de API automatizadas en Buildkite definiendo un paso de comando en .buildkite/pipeline.yml que instala la CLI de Apidog, ejecuta apidog run contra un entorno y carga el informe HTML como un artefacto de compilación. Esta guía recorre el pipeline completo, incluyendo cómo Buildkite maneja los secretos para que tu token de acceso de Apidog nunca se filtre en los registros. Asumimos que tus pruebas de Apidog ya existen; las construyes visualmente una vez y luego las ejecutas desde un solo comando en CI.
Una aclaración rápida antes de empezar. Buildkite es una plataforma de CI/CD. No es lo mismo que Docker BuildKit, el backend de creación de imágenes dentro de Docker. Los nombres se parecen, pero son productos no relacionados. Este artículo trata enteramente sobre Buildkite, la plataforma de CI/CD.
Qué es Buildkite
Buildkite es una plataforma de CI/CD construida alrededor de un modelo híbrido. Tiene un plano de control alojado, el tablero y la orquestación de compilaciones que ves en tu navegador, y agentes que realmente ejecutan tus trabajos.
La división importa. El plano de control programa el trabajo, pero el trabajo se ejecuta en agentes. Puedes autoalojar agentes en tu propia infraestructura o en la nube, o puedes usar agentes alojados por Buildkite, que son recursos de computación gestionados que Buildkite ejecuta por ti.
Esto es lo principal que diferencia a Buildkite de los sistemas de CI totalmente alojados. Tu código y tus secretos pueden permanecer en tus propias máquinas mientras Buildkite coordina las compilaciones. Para las pruebas de API, eso significa que tus pruebas se ejecutan donde ya residen tus servicios y el acceso a la red.
El agente de Buildkite en sí es de código abierto. Está escrito en Go y se publica bajo la Licencia MIT, con el código fuente en GitHub. La plataforma y el plano de control que lo rodea son un producto SaaS comercial.
Para qué se utiliza Buildkite
Los equipos usan Buildkite para ejecutar cualquier tipo de trabajo automatizado activado por cambios en el código: construir artefactos, ejecutar pruebas unitarias y de integración, desplegar servicios y realizar comprobaciones de extremo a extremo. Debido a que los agentes pueden ejecutarse en tu propio hardware, es común en equipos que necesitan control sobre la computación, los límites de la red o hardware como las GPU.
Las pruebas de API encajan bien con esto. Quieres que tus pruebas lleguen a un entorno de staging o de prueba, afirmen sobre respuestas reales y bloqueen un despliegue cuando se rompa un contrato. Buildkite te proporciona los tipos de pasos para modelar exactamente ese flujo, que utilizaremos a continuación.
Si estás comparando Buildkite con otras opciones, nuestro resumen de las mejores herramientas de integración continua para equipos de API cubre cómo varias plataformas se comparan para este caso de uso.
Cómo se definen los pipelines de Buildkite
Un pipeline de Buildkite es una lista de pasos. El lugar predeterminado para definirlos es un archivo en .buildkite/pipeline.yml en tu repositorio. Cuando comienza una compilación, Buildkite busca un directorio llamado .buildkite que contenga un archivo llamado pipeline.yml. Un directorio buildkite/ no oculto en la raíz del repositorio también funciona.
La clave de nivel superior es steps:, y contiene una lista. Los tipos de pasos que más utilizarás para las pruebas de API son estos:
- Pasos de comando ejecutan comandos de shell en un agente. Aquí es donde se ejecutan tus pruebas.
- Pasos de espera pausan el pipeline hasta que cada paso anterior finaliza. Se escriben como un elemento de lista simple
- wait. - Pasos de bloqueo crean una puerta de aprobación manual, escrita como
- block: "Etiqueta". Un humano hace clic para continuar, lo cual es útil antes de un despliegue de producción.
Los pasos de comando admiten un conjunto de claves que usarás a menudo: label y key para nombrar y referenciar, command o commands para el script, env para variables de entorno, agents para segmentación, secrets para inyectar valores secretos, artifact_paths para archivos a mantener, parallelism para la dispersión (fan-out), y matrix para ejecutar el mismo paso a través de un conjunto de valores.
La clave agents es un hash de pares de etiquetas. La usas para enrutar un paso al agente correcto, por ejemplo queue: "tests". Las etiquetas te permiten mantener los trabajos de prueba en agentes que tienen el acceso a la red o las herramientas adecuadas.
Un pipeline de copiar y pegar que ejecuta pruebas de API
Aquí tienes un .buildkite/pipeline.yml mínimo que instala la CLI de Apidog, ejecuta un escenario de prueba contra un entorno y carga el informe HTML. La CLI de Apidog es una herramienta de Node.js que ejecuta tus escenarios de prueba de Apidog desde la línea de comandos.
steps:
- label: ":test_tube: Pruebas de API (Apidog)"
key: "api-tests"
command: |
npm install -g apidog-cli
apidog run \
--access-token "$APIDOG_ACCESS_TOKEN" \
-t 637132 \
-e 358171 \
-r html,cli
buildkite-agent artifact upload "apidog-reports/**/*"
agents:
queue: "default"
secrets:
- APIDOG_ACCESS_TOKEN
Algunas notas sobre las banderas. -t es el ID del escenario de prueba o directorio de escenarios que deseas ejecutar. -e es el ID del entorno de ejecución, que selecciona la URL base y las variables que usan tus pruebas. -r html,cli solicita tanto un resumen de terminal legible por humanos como un archivo de informe HTML. --access-token pasa tu token de Apidog para que la CLI pueda acceder a tu proyecto.
El host del agente de Buildkite ya tiene el binario buildkite-agent disponible, ya que es lo que ejecuta el trabajo. Solo tú instalas apidog-cli. Para un recorrido más profundo por cada bandera, consulta la guía completa de la CLI de Apidog.
Si primero quieres un tutorial paso a paso sobre cómo ejecutar una sola API desde la terminal, el tutorial de pruebas de línea de comandos de la CLI de Apidog es un buen calentamiento antes de conectarlo a CI.
Pasando el token de acceso de Apidog con secretos de Buildkite
Tu token de acceso de Apidog es una credencial. Nunca debe estar en tu pipeline.yml ni imprimirse en el registro de compilación. Buildkite te ofrece una función nativa para esto llamada secretos de Buildkite.
Los secretos de Buildkite son un almacén de clave-valor cifrado. Los valores se cifran en reposo y en tránsito a través de TLS, se descifran en los servidores de Buildkite y se limitan por clúster, donde cada clúster tiene su propia clave de cifrado. Funciona tanto con agentes alojados por Buildkite como con agentes autoalojados. Cualquier valor secreto que aparezca en tus registros se oculta automáticamente.
Hay dos formas de usar un secreto almacenado. La primera es la clave secrets: en un paso de comando. En su forma de lista más simple, el nombre de la variable de entorno coincide con la clave secreta:
steps:
- command: |
apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t 637132 -e 358171 -r html,cli
secrets:
- APIDOG_ACCESS_TOKEN
Si tu secreto almacenado tiene un nombre diferente al de la variable de entorno que deseas, usa la forma de hash. La clave es el nombre de la variable de entorno y el valor es la clave del secreto:
steps:
- command: |
apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t 637132 -e 358171 -r html,cli
secrets:
APIDOG_ACCESS_TOKEN: apidog_token # nombre de la variable de entorno : clave secreta de Buildkite
La segunda forma es obtener el secreto imperativamente dentro de tu script con la CLI del agente. Esto es útil cuando quieres controlar exactamente cuándo se lee el valor:
APIDOG_ACCESS_TOKEN="$(buildkite-agent secret get apidog_token)"
apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t 637132 -e 358171 -r html,cli
Los secretos de Buildkite no son tu única opción. En agentes autoalojados puedes usar un hook de agente de environment, un script que se ejecuta al inicio de cada trabajo y exporta valores al entorno. Puedes restringirlo a variables como $BUILDKITE_PIPELINE_SLUG o $BUILDKITE_STEP_KEY para que un secreto solo se cargue para los trabajos correctos. También puedes extraer de almacenes externos como AWS Secrets Manager, HashiCorp Vault o GCP a través de plugins de Buildkite, en cuyo caso el secreto nunca se almacena ni se envía a Buildkite.
Los valores simples de env: están bien para configuraciones no sensibles, pero no pongas tokens allí. Para más detalles sobre cómo el token fluye desde tu almacén de secretos a la CLI, consulta la guía sobre autenticación de la CLI de Apidog.
Subiendo el informe HTML como un artefacto
El reportero -r html escribe un informe HTML en una ruta local en el espacio de trabajo del agente. Ese archivo desaparece cuando termina el trabajo a menos que lo guardes. El comando buildkite-agent artifact upload lo conserva.
buildkite-agent artifact upload "apidog-reports/**/*"
Las comillas alrededor del patrón glob son importantes. Evitan que tu shell expanda el patrón antes de que el agente lo vea, por lo que el agente realiza la coincidencia por sí mismo. Los artefactos cargados van al almacenamiento gestionado por Buildkite por defecto, con una ventana de retención de 6 meses y un límite de 5GB por artefacto. Puedes pasar un destino como segundo argumento si quieres enviarlos a otro lugar.
Después de que se ejecuta una compilación, el informe aparece en la pestaña Artefactos de la compilación. Cualquiera que revise la compilación puede descargarlo y ver qué aserciones pasaron o fallaron. Si primero quieres entender los formatos de informe, la guía de informes de prueba de la CLI de Apidog cubre la salida de CLI, HTML y JSON.
Ejecutando pruebas en paralelo en diferentes entornos
Cuando quieres que el mismo conjunto de pruebas se ejecute contra varios entornos a la vez, usa una matrix. Buildkite expande una definición de paso en un trabajo por cada valor de la matriz, y se ejecutan en paralelo.
steps:
- label: ":test_tube: Pruebas de API {{matrix.env}}"
command: |
npm install -g apidog-cli
apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t 637132 -e "{{matrix.env}}" -r html,cli
buildkite-agent artifact upload "apidog-reports/**/*"
secrets:
- APIDOG_ACCESS_TOKEN
matrix:
setup:
env:
- "358171" # ID del entorno de staging
- "358172" # ID del entorno de producción
Aquí {{matrix.env}} se sustituye tanto en la etiqueta como en la bandera -e, de modo que cada trabajo apunta a un entorno diferente de Apidog. Si solo quieres dispersar copias idénticas de un solo trabajo, establece parallelism: 5 en el paso en lugar de una matriz.
Para ejecuciones basadas en datos, donde un escenario itera sobre filas de un archivo CSV o JSON, la CLI de Apidog lo maneja con su propia bandera -d en lugar de la matriz de Buildkite. La guía de pruebas basadas en datos de la CLI de Apidog muestra cómo alimentar un archivo de datos a un escenario.
Protegiendo un despliegue con pruebas
Una forma común es: ejecutar pruebas, esperar a que terminen, pedir a un humano que apruebe y luego desplegar. Buildkite modela esto con los pasos wait y block.
steps:
- label: ":test_tube: Pruebas de API"
command: "npm install -g apidog-cli && apidog run --access-token \"$APIDOG_ACCESS_TOKEN\" -t 637132 -e 358171 -r html,cli"
secrets:
- APIDOG_ACCESS_TOKEN
- wait
- block: ":rocket: ¿Desplegar?"
branches: "main"
- label: ":rocket: Desplegar"
command: "scripts/deploy.sh"
El paso wait detiene el pipeline hasta que las pruebas se completan. El paso block se detiene para un clic manual y está restringido a la rama main con branches:. Solo después de que alguien aprueba se ejecuta el paso de despliegue. Esto evita que un conjunto de pruebas fallidas llegue a producción. Para patrones más amplios relacionados con esto, consulta nuestras mejores prácticas de CI/CD para pruebas de API.
Añadiendo una anotación de resumen
Los registros de compilación son largos. Una anotación coloca un resumen corto y formateado en la parte superior de la página de compilación. Creas uno pasando markdown a buildkite-agent annotate.
cat << 'EOF' | buildkite-agent annotate --style "success" --context "apidog"
### Resultados de las pruebas de API
Todos los escenarios de Apidog pasaron. [Descargar el informe HTML completo](artifact://apidog-reports/index.html)
EOF
La bandera --style controla el color y el icono, con valores info, warning, error y success. La bandera --context le da a la anotación un ID único, de modo que un paso posterior con el mismo contexto actualiza la misma anotación en lugar de añadir una nueva. El enlace artifact:// dirige a los revisores directamente al informe HTML cargado.
Dónde encaja Apidog
El pipeline anterior es corto a propósito. El trabajo pesado de escribir y mantener pruebas ocurre en Apidog, no en YAML.
Apidog es una plataforma API todo en uno para diseñar, depurar, probar, simular y documentar APIs. Construyes escenarios de prueba en un editor visual: encadenas solicitudes, pasas datos entre pasos y añades aserciones sin escribir scripts. Debido a que los escenarios viven en tu proyecto de Apidog, tu equipo los edita en un solo lugar y los controla mediante versiones con soporte para ramas.
La CLI es el puente hacia CI. Construyes un escenario una vez, tomas sus IDs de escenario y entorno, y toda la integración de CI es un solo comando apidog run. Cuando actualizas una prueba en Apidog, la siguiente compilación de Buildkite detecta el cambio sin necesidad de editar YAML. Esa propiedad de comando único es lo que hace que Apidog se integre limpiamente en Buildkite, GitHub Actions o cualquier otro sistema. Cubrimos el mismo comando en otras plataformas en la guía de pipeline CI/CD de la CLI de Apidog y el tutorial Apidog CLI con GitHub Actions.
Para probarlo primero desde tu propia máquina, antes de conectar cualquier cosa a CI, ejecuta el mismo comando localmente con tu token:
apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t 637132 -e 358171 -r cli,html
Descarga Apidog gratis, construye un escenario de prueba e inserta el comando de una sola línea apidog run en tu pipeline de Buildkite.
Preguntas Frecuentes
¿Qué es Buildkite?
Buildkite es una plataforma de CI/CD con un diseño híbrido. Un plano de control alojado ejecuta el tablero y orquesta las compilaciones, mientras que los agentes ejecutan los trabajos reales. Los agentes pueden ejecutarse en tu propia infraestructura o en la computación alojada por Buildkite. No está relacionado con Docker BuildKit, que es una herramienta independiente de creación de imágenes que casualmente tiene un nombre similar.
¿Para qué se utiliza Buildkite?
Los equipos usan Buildkite para automatizar trabajos activados por cambios en el código: construir artefactos, ejecutar pruebas y desplegar. Es común en equipos que quieren que sus compilaciones se ejecuten en su propio hardware o dentro de su propia red. Para los equipos de API, ejecuta pruebas automatizadas contra entornos de staging y producción y puede bloquear un despliegue cuando las pruebas fallan.
¿Es Buildkite de código abierto?
El agente de Buildkite es de código abierto. Está escrito en Go y se publica bajo la Licencia MIT, con su código fuente en GitHub. La plataforma y el plano de control alrededor del agente son un producto SaaS comercial, por lo que solo el agente en sí es de código abierto.
¿Es Buildkite gratuito?
Sí, Buildkite tiene un plan gratuito llamado Personal. Cuesta $0 sin tarjeta de crédito y sin caducidad. Incluye 3 trabajos concurrentes, 1 usuario, retención de 90 días, 500 minutos de agente alojado en Linux al mes y 50,000 ejecuciones de pruebas al mes. También hay una prueba de 30 días de Acceso Total para evaluar las funciones de pago.
¿Cómo se suben artefactos en Buildkite?
Ejecutas buildkite-agent artifact upload "<pattern>" dentro de un paso de comando. Cita el patrón glob para que el agente lo haga coincidir en lugar de la shell. Los archivos van al almacenamiento gestionado por Buildkite por defecto, con una retención de 6 meses y un límite de 5 GB por artefacto. Para las pruebas de API, cargas el informe HTML para que los revisores puedan abrirlo desde la pestaña Artefactos de la compilación.
¿Cómo se ejecutan pruebas de API en un pipeline de Buildkite?
Añade un paso de comando a .buildkite/pipeline.yml que instala la CLI de Apidog con npm install -g apidog-cli, luego ejecuta apidog run con un ID de escenario de prueba, un ID de entorno a través de -e, y -r html,cli para los informes. Pasa tu token de acceso a través de un secreto de Buildkite y carga el informe HTML con buildkite-agent artifact upload para que los resultados persistan después de la compilación.