La mayoría de las pruebas de API comienzan su vida en una interfaz gráfica de usuario (GUI). Haces clic por aquí y por allá, añades algunas aserciones y las ejecutas manualmente. Esto funciona hasta que necesitas que las mismas pruebas se ejecuten en cada envío, cada noche o dentro de una pipeline donde nadie está mirando. En ese momento, quieres un comando que puedas escribir, scriptar y pasar a CI.
Ese comando es la CLI de Apidog. Este tutorial te guiará a través de las pruebas de una API REST real de extremo a extremo desde tu terminal: instala la herramienta, importa una API, configura un entorno, construye un escenario de prueba, ejecútalo con aserciones, aliméntalo con datos y recopila informes. Cada comando y salida a continuación proviene de una ejecución real en Apidog CLI versión 2.2.2 contra una API pública en vivo, para que puedas seguirlo y obtener los mismos resultados.
Si deseas la parte visual de la misma plataforma, puedes descargar Apidog y diseñar las pruebas primero en la aplicación. Pero todo aquí se mantiene en la línea de comandos.
Qué construirás
Probarás restful-api.dev, una API REST pública gratuita con CRUD real sobre un recurso /objects. Al final tendrás:
- Un proyecto de Apidog inicializado desde un archivo OpenAPI
- Un escenario de prueba de tres pasos que crea un objeto, lo lee y lo elimina, con aserciones en cada paso
- Una ejecución basada en datos que repite una solicitud una vez por cada fila de datos de prueba
- Informes CLI, HTML, JSON y JUnit, además de un informe en la nube compartible
El mismo flujo se adapta a tu propia API y es la base para ejecutar pruebas de API en CI/CD.
Antes de empezar
Necesitas Node.js 16 o superior y una cuenta de Apidog. Si primero estás comparando ejecutores, la versión corta es que la CLI de Apidog ejecuta escenarios de prueba completos y gestiona los recursos de la API como código, lo que la distingue de Newman y la CLI de Postman.
Paso 1: Instalar e iniciar sesión
Instala la CLI globalmente desde npm:
npm install -g apidog-cli@latest
Confirma que está ahí:
apidog --version
# 2.2.2
Ahora autentícate. Obtén un token de la aplicación Apidog bajo tu avatar, Configuración de la cuenta, Token de acceso a la API, luego ejecuta:
apidog login --with-token <YOUR_TOKEN>
El token se guarda en ~/.apidog/config.toml, por lo que solo haces esto una vez por máquina. Comprueba quién eres:
Cada comando devuelve JSON estructurado con un indicador success y agentHints útiles, lo que facilita el scripting de la salida o su redirección a jq.
Paso 2: Crear un proyecto
Elige el equipo bajo el cual crear el proyecto, luego créalo:
apidog team list
apidog project create --team 329562 --name "CLI Field Test"
Recibirás el ID del nuevo proyecto.
Guárdalo en una variable de shell para que el resto de este tutorial sea copiar y pegar:
PID=1314366 # replace with your project id
apidog project get $PID
Paso 3: Importar tu API REST
Podrías crear endpoints manualmente, pero importar un archivo OpenAPI es más rápido y refleja cómo comienzan los proyectos reales. Aquí tienes una pequeña especificación que describe los endpoints CRUD de /objects (guárdala como objects-api.openapi.json):
{
"openapi": "3.0.3",
"info": { "title": "Objects API", "version": "1.0.0" },
"servers": [{ "url": "https://api.restful-api.dev" }],
"paths": {
"/objects": {
"get": { "summary": "List objects" },
"post": { "summary": "Create object" }
},
"/objects/{id}": {
"get": { "summary": "Get object by id" },
"put": { "summary": "Update object" },
"delete": { "summary": "Delete object" }
}
}
}
Impórtala:
apidog import --project $PID --format openapi --file ./objects-api.openapi.json
# "createCount": 5 (5 endpoints created, 0 errors)
El importador también lee openapi, postman, har, insomnia, jmeter y más. Lista lo que se importó:
apidog endpoint list --project $PID
# 37921721 get /objects
# 37921722 post /objects
# 37921723 get /objects/{id}
# 37921724 put /objects/{id}
# 37921725 delete /objects/{id}
Paso 4: Configurar un entorno
Un entorno contiene la URL base y cualquier variable que tus pruebas reutilicen. Crea uno y guarda su ID:
apidog environment create "Production" --project $PID --base-url "https://api.restful-api.dev"
apidog environment list --project $PID
# { "id": 6334917, "name": "Production", "baseUrls": { "default": "https://api.restful-api.dev" } }
ENV=6334917 # replace with your environment id
Más adelante, pasarás -e $ENV al comando de ejecución para que la prueba sepa dónde enviar las solicitudes.
Paso 5: Superar la barrera de escritura de automatización
Aquí está lo primero que confunde a la gente. Los escenarios de prueba y los datos de prueba son recursos de automatización, y escribirlos en tu rama principal desde una herramienta externa está bloqueado por defecto:
apidog test-scenario create --project $PID --name "x" --description "" --folder-id 0 --priority 1
# "error": { "code": "403075", "message": "Automation caller branch required" }
Esto es una medida de seguridad, no un error. Tienes dos maneras de superarlo:
- Activa el permiso de edición directa en la aplicación de escritorio de Apidog en Configuración del Proyecto, Configuración de Funciones, Configuración de Funciones de IA, Permisos de Edición Externa de IA.
- Trabaja en una rama de IA, que mantiene los cambios de automatización aislados hasta que decidas fusionarlos. Esta ruta se mantiene completamente en la línea de comandos, así que eso es lo que usaremos.
Crea la rama desde main:
apidog branch create --project $PID --type ai \
--name "ai/20260616-from-main-cli-field-test" --from main
BR="ai/20260616-from-main-cli-field-test"
El patrón de nombres ai/YYYYMMDD-from-<source>-<feature> es la convención que espera la CLI. Ten en cuenta que import, environment create y las ediciones de endpoints no están restringidos; solo lo están los recursos de automatización.
Paso 6: Construir un escenario de prueba
Un escenario es un flujo ordenado de solicitudes con aserciones entre ellas. Primero creas el esqueleto, luego añades los pasos. Créalo en tu rama de IA:
apidog test-scenario create --project $PID --branch "$BR" \
--name "Object CRUD lifecycle" \
--description "Create, read, then delete an object and assert each step" \
--folder-id 0 --priority 1
SID=1836498 # the returned scenario id
Los pasos se añaden a través de update con un archivo JSON. La regla de oro con cualquier escritura JSON es validar antes de enviarlo, para que nunca envíes una carga útil mal formada:
apidog cli-schema get test-scenario-update # see the exact shape
apidog cli-schema validate test-scenario-update --file ./steps-crud.json
# "data file is valid"
Cada paso es una solicitud más un pequeño script que afirma la respuesta y pasa los datos al siguiente paso. Aquí está la forma del paso de creación, que publica un nuevo objeto y guarda su id para pasos posteriores:
{
"type": "customHttp",
"name": "Create object",
"customHttpRequest": {
"path": "https://api.restful-api.dev/objects",
"method": "post",
"requestBody": { "type": "json", "data": "{\"name\":\"Apidog CLI Field Test\",\"data\":{\"price\":42}}" },
"postProcessors": [{
"type": "customScript",
"data": "pm.test('create returns 200', function () { pm.response.to.have.status(200); });\nvar body = pm.response.json();\npm.globals.set('objId', body.id);",
"enable": true
}],
"projectId": 1314366
}
}
Los siguientes pasos reutilizan {{objId}} en la URL para obtener y luego eliminar el mismo objeto. Aplica el archivo completo de tres pasos:
apidog test-scenario update $SID --project $PID --branch "$BR" --file ./steps-crud.json
# "success": true
No tienes que crear escenarios como JSON. Construirlos visualmente en Apidog y ejecutarlos desde la CLI es igual de válido. La ruta JSON importa cuando quieres que tus pruebas estén controladas por versiones y revisadas como cualquier otro código.
Paso 7: Ejecutarlo desde la línea de comandos
Esta es la recompensa. Ejecuta el escenario con el reportero de la CLI:
apidog run -t $SID --project $PID --branch "$BR" -e $ENV -r cli
❏ Ciclo de vida CRUD de objetos
↳ Crear objeto POST .../objects [200 OK]
✓ la creación devuelve 200 ✓ la respuesta tiene un ID ✓ el nombre fue devuelto
↳ Obtener el objeto creado GET .../objects/ff80...3de [200 OK]
✓ la obtención devuelve 200 ✓ el ID coincide con el objeto creado ✓ el precio persiste en los datos
↳ Eliminar el objeto DELETE .../objects/ff80...3de [200 OK]
✓ la eliminación devuelve 200
Solicitudes Http 3 / 0 fallidas
Aserciones 7 / 0 fallidas
Tres solicitudes, siete aserciones, cero fallos, y el id creado fluyó del primer paso a los dos siguientes. Eso es una prueba de API completa ejecutándose sin un solo clic.
¿Quieres archivos en lugar de la salida de la consola? Solicita varios reportadores a la vez y dirígelos a una carpeta:
apidog run -t $SID --project $PID --branch "$BR" -e $ENV \
-r cli,html,json,junit --out-dir ./reports --out-file "crud-report"
ls ./reports
# crud-report.html crud-report.json crud-report.xml
El XML de JUnit es lo que tu servidor de CI lee para mostrar el éxito/fracaso por cada compilación. El informe HTML es el que compartes con tus compañeros de equipo.
Paso 8: Ejecutar la misma prueba con múltiples entradas
Las suites de pruebas reales cubren más de un caso. Las ejecuciones impulsadas por datos repiten un escenario una vez por cada fila de datos, por lo que pruebas diez entradas sin escribir diez escenarios. Esta es la misma idea que las pruebas parametrizadas desde CSV y JSON.
Pon tus filas en un archivo:
[
{ "name": "Pixel 8 Pro", "price": 999 },
{ "name": "iPhone 15", "price": 899 },
{ "name": "Galaxy S24", "price": 799 }
]
Haz referencia a los datos con -d, y deja que el escenario lea {{name}} y {{price}} de cada fila:
apidog run -t $DID --project $PID --branch "$BR" -e $ENV -d ./objects-data.json -r cli
Iteración 1/3 … ✓ fila creada (200) ✓ el nombre coincide con la fila de datos
Iteración 2/3 … ✓ fila creada (200) ✓ el nombre coincide con la fila de datos
Iteración 3/3 … ✓ fila creada (200) ✓ el nombre coincide con la fila de datos
Iteraciones 3 / 0 fallidas Aserciones 6 / 0 fallidas
Tres filas de entrada, tres iteraciones de salida. Cambia el archivo por un CSV y nada más cambia.
Paso 9: Recopilar informes
Las ejecuciones locales escriben archivos. Para obtener un informe que todo tu equipo pueda abrir en un navegador, añade --upload-report:
apidog run -t $SID --project $PID --branch "$BR" -e $ENV -r cli --upload-report
# Apidog CLI runs data uploaded to the cloud successfully.
# https://app.apidog.com/link/project/1314366/api-test/test-report/2605398
Un detalle que vale la pena saber: un informe en la nube está etiquetado con la rama en la que se ejecutó. Dado que esta ejecución ocurrió en tu rama de IA, un simple apidog test-report list --project $PID (que apunta a main) no lo mostrará. En su lugar, obténlo por el ID del enlace de subida:
apidog test-report get 2605398 --project $PID
apidog test-report download 2605398 --project $PID --format json --output ./cloud-report.json
Paso 10: Exportar tu API como documentos o una especificación
La CLI también exporta datos. Exporta el proyecto como un archivo OpenAPI, Markdown o documentos HTML:
apidog export --project $PID --format openapi --oas-version 3.0 --output ./openapi-export.json
apidog export --project $PID --format markdown --output ./api-docs.md
apidog export --project $PID --format html --output ./api-docs.html
Esto es útil para hacer un commit de una nueva especificación en cada cambio o publicar documentos estáticos desde una pipeline.
Paso 11: Integrarlo en CI/CD
Todo lo que ejecutaste manualmente se convierte en tres líneas en una pipeline. El núcleo es instalar, luego ejecutar con el reportero JUnit para que el servidor de CI pueda leer los resultados:
- run: npm install -g apidog-cli@latest
- run: apidog login --with-token $APIDOG_TOKEN
- run: apidog run -t $SID --project $PID -e $ENV -r junit --out-dir ./reports
Guarda el token como un secreto y haz que la compilación falle cuando una prueba falle (la CLI devuelve un código de salida distinto de cero en caso de fallos). Para un flujo de trabajo completo, de copiar y pegar, consulta la guía sobre cómo ejecutar pruebas de Apidog CLI en GitHub Actions, o explora las herramientas de automatización de pruebas de API que se adaptan a una pipeline.
Conclusión
Pasaste de una terminal vacía a una prueba de API exitosa, impulsada por datos y con informes compartibles, y nunca saliste de la línea de comandos. El patrón es siempre el mismo: importa o diseña tu API, crea un entorno, construye un escenario con aserciones y luego ejecútalo con apidog run. Una vez que ese comando funciona localmente, integrarlo en CI es un cambio de tres líneas.
Dirige los mismos pasos a tu propia API, haz commit de los archivos de escenario junto con tu código, y tus pruebas se ejecutarán en cualquier lugar donde haya un shell. Descarga Apidog para empezar, y ten a mano las alternativas a curl para pruebas de API REST para esas comprobaciones rápidas y únicas para las que la CLI es excesiva.