Ha creado un escenario de prueba sólido para su endpoint de pago. Encadena tres solicitudes, verifica cada respuesta y pasa cada vez que hace clic en Ejecutar. Pero su pipeline necesita que cubra cuarenta combinaciones de entrada, extraiga los datos de un archivo que mantiene su jefe de QA y ejecute el mismo escenario contra entornos de staging y producción con diferentes credenciales. La ejecución de apuntar y hacer clic que funcionaba en su computadora portátil no se traduce en eso, y no quiere clonar el escenario cuarenta veces.
Esa última milla es lo que maneja la línea de comandos. Con Apidog, usted crea un escenario de prueba una vez en el constructor visual, luego lo ejecuta desde una terminal con el paquete apidog-cli. El flag que convierte un escenario en una ejecución basada en datos es -d, abreviatura de --iteration-data. Toma un archivo CSV, un archivo JSON o un conjunto de datos que haya almacenado en su proyecto Apidog, y ejecuta el escenario una vez por fila, vinculando los valores de cada fila a las variables que referencian sus solicitudes.
Cómo el flag -d lee un archivo
Toda la funcionalidad reside en una sola opción. Aquí está la forma larga y corta, directamente de apidog run --help:
-d, --iteration-data <path|testDataId> Define the data which use for iterations (either JSON or CSV)
Ese <path|testDataId> es el detalle que la mayoría de la gente pasa por alto. El argumento está sobrecargado. Pásale una ruta y el CLI lee un archivo local del disco. Pásale un ID de datos de prueba y el CLI extrae un conjunto de datos que has guardado dentro de tu proyecto Apidog. El mismo flag, dos orígenes, y el ejecutor determina cuál le has pasado.
La forma de archivo local es el punto de partida común. Apúntalo a un archivo relativo a donde ejecutas el comando:
apidog run --access-token $APIDOG_ACCESS_TOKEN \
-t 605067 -e 1629989 \
-d ./test-data/checkout-cases.csv -r cli
El CLI abre checkout-cases.csv, cuenta las filas bajo el encabezado y ejecuta el escenario 605067 una vez por fila. En cada pasada, vincula las columnas a las variables coincidentes en tus solicitudes, ejecuta el escenario y registra el resultado de esa iteración. Cuarenta filas, cuarenta pasadas, un escenario.El formato sigue al archivo. El mismo flag acepta JSON sin ninguna opción adicional:
apidog run --access-token $APIDOG_ACCESS_TOKEN \
-t 605067 -e 1629989 \
-d ./test-data/checkout-cases.json -r cli
No le dices al CLI qué formato estás usando. Lee la extensión y la forma del archivo. Eso significa que puedes intercambiar un CSV por un array JSON a mitad del proyecto sin tocar el comando, siempre y cuando los nombres de las columnas y las claves JSON coincidan con las variables que tu escenario espera.
Qué espera el CLI dentro de cada archivo
CSV es el formato para casos planos y tabulares. La fila de encabezado nombra tus variables. Cada fila debajo de ella es una iteración. Aquí tienes un checkout-cases.csv real para un endpoint de descuentos:
sku,quantity,coupon,expected_status,expected_total
DESK-01,1,SAVE10,200,89.10
DESK-01,0,SAVE10,422,0
CHAIR-09,3,,200,447.00
DESK-01,1,EXPIRED,410,0
GHOST-99,1,SAVE10,404,0
Cinco columnas se convierten en cinco variables. Dentro del cuerpo de la solicitud escribes {{sku}} y {{quantity}}; en las aserciones comparas la respuesta con {{expected_status}} y {{expected_total}}. El ejecutor las vincula por fila. La celda vacía de coupon en la fila tres se convierte en una cadena vacía, que es exactamente el caso sin cupón que quieres cubrir.
JSON es el formato cuando tus casos tienen una estructura anidada que se aplana mal en columnas. El archivo es un array de objetos, un objeto por iteración:
[
{
"label": "valid order, two items",
"order": {
"items": [
{ "sku": "DESK-01", "qty": 1 },
{ "sku": "CHAIR-09", "qty": 2 }
],
"shipping": { "country": "US", "method": "ground" }
},
"expected_status": 200
},
{
"label": "unshippable country",
"order": {
"items": [{ "sku": "DESK-01", "qty": 1 }],
"shipping": { "country": "ZZ", "method": "ground" }
},
"expected_status": 422
}
]
Dentro del escenario, referencias {{order}} y {{expected_status}} de la misma manera, y el ejecutor entrega los campos de cada objeto a la iteración. El campo label es para ti. Aparece en el informe para que una pasada fallida diga "país no enviable" en lugar de "iteración 2", lo que marca la diferencia entre un diagnóstico de cinco segundos y uno de cinco minutos.
Algunas reglas evitan que estos archivos te den problemas en CI:
- Mantén los nombres de las cabeceras idénticos a los nombres de las variables en tu escenario. Una columna llamada
qtyno se vinculará a una solicitud que lea{{quantity}}. Esta falta de coincidencia es la razón más común por la que una ejecución basada en datos pasa localmente y produce valores vacíos en el pipeline. - Cita cualquier campo CSV que contenga una coma, o mueve ese archivo a JSON. Un campo de texto libre con una coma se divide en dos columnas y desplaza todos los valores posteriores.
- Coloca el resultado esperado en los datos, no en el escenario. La fila uno espera 200, la fila cuatro espera 410. Si codificas la expectativa en la aserción, vuelves a tener un escenario por caso.
- Confirma estos archivos junto a tu configuración de prueba para que versionen con el código que ejercitan. El archivo de datos es parte de la prueba, no un artefacto suelto.
Para la parte de JSONPath al escribir aserciones que leen estos valores vinculados, establecer aserciones y extraer variables de una respuesta JSON explica la sintaxis en detalle.
Ejecutar desde un conjunto de datos almacenado en lugar de un archivo
La segunda forma de -d es la que no aparece en la mayoría de los tutoriales. En lugar de una ruta, pasas un ID de datos de prueba:
apidog run --access-token $APIDOG_ACCESS_TOKEN \
-t 605067 -e 1629989 \
-d 38291 -r cli
Ahora el CLI obtiene el conjunto de datos con ese ID de tu proyecto Apidog en lugar de leer un archivo del disco del ejecutor. Esto es útil cuando los datos residen con el equipo, no con el repositorio. Tu líder de QA mantiene la tabla de casos dentro de Apidog, la edita en la aplicación, y cada ejecución de CI recoge la versión actual sin que nadie tenga que confirmar un CSV. El escenario, el entorno y los datos están todos en el lado del servidor; el comando simplemente los nombra por ID.
La compensación radica en dónde reside tu fuente de verdad. Un CSV confirmado te proporciona un conjunto de datos que es comparable en las solicitudes de extracción y está anclado al commit que se está probando. Un ID de datos de prueba almacenado te da una única tabla compartida que todos editan en un solo lugar. Ninguna opción es incorrecta. Elige el archivo confirmado cuando los datos deban moverse al unísono con el código, y el ID almacenado cuando los datos sean propiedad de personas que no tocan el repositorio.
Ejecutar sin conexión desde un archivo exportado
Hay una tercera forma de alimentar el CLI, y cambia la forma de todo el comando. Puedes exportar un caso de prueba desde Apidog como un archivo autocontenido y ejecutar ese archivo directamente, sin ID de escenario y sin viaje de ida y vuelta a la red para obtener el escenario:
apidog run ./checkout.apidog-cli.json -r cli,html
Aquí, el primer argumento es una file-source, el propio caso de prueba exportado, no un flag. El CLI ejecuta lo que está en el archivo. Todavía superpones datos de iteración con -d:
apidog run ./checkout.apidog-cli.json -d ./checkout-cases.csv -r cli,junit
Esto importa en dos situaciones. La primera es un ejecutor de CI aislado o restringido que no puede acceder a la nube de Apidog para resolver un ID de escenario; el archivo exportado contiene todo lo que la ejecución necesita. La segunda es la reproducibilidad: el archivo exportado es una instantánea congelada del escenario en el momento de la exportación, por lo que una ejecución a partir de él no se ve afectada si alguien edita el escenario en la aplicación más tarde. Para la mecánica de instalación y primera ejecución detrás de esto, la guía de instalación de Apidog CLI cubre cómo colocar el binario, y la referencia completa de Apidog CLI documenta cada flag en una tabla.
Emparejar -d con -n y anulaciones de variables
Las ejecuciones basadas en datos rara vez van solas. Tres flags se emparejan con -d constantemente.
-n, --iteration-count establece cuántas veces se ejecuta el escenario. Cuando proporcionas un archivo de datos, el recuento de filas ya impulsa las iteraciones, por lo que normalmente dejas -n desactivado y dejas que el archivo decida. Utilizas -n principalmente cuando quieres ejecutar la tabla más de una vez, o cuando ejecutas sin un archivo de datos en absoluto, como una prueba de resistencia que repite un escenario fijo:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -n 50 -r cli
--env-var y --global-var inyectan pares clave=valor en tiempo de ejecución sin tocar el entorno en tu proyecto. Así es como mantienes secretos y configuraciones por pipeline fuera del escenario y del archivo de datos. El archivo de datos contiene los casos de prueba; las anulaciones contienen las cosas que cambian por ejecución:
apidog run --access-token $APIDOG_ACCESS_TOKEN \
-t 605067 -e 1629989 \
-d ./test-data/checkout-cases.csv \
--env-var "base_url=https://staging.internal" \
--global-var "api_key=$RUNTIME_API_KEY" \
-r cli,junit
La división es deliberada. Los datos de iteración son la parte de la ejecución que es la misma en todas partes: los casos que tu endpoint debe manejar. Las anulaciones de variables son la parte que cambia por entorno: el host, la clave, el inquilino. Mantén las credenciales en tu almacén de secretos de CI y pásalas a través de --global-var desde una variable de entorno, como lo hace $RUNTIME_API_KEY arriba. Nunca las incorpores al CSV, donde cualquiera con acceso al repositorio podría leerlas.
Lectura de resultados por iteración
Una ejecución basada en datos solo es útil si puedes saber qué fila falló. Los flags del reportero deciden lo que obtienes.
apidog run --access-token $APIDOG_ACCESS_TOKEN \
-t 605067 -e 1629989 \
-d ./test-data/checkout-cases.csv \
-r cli,junit --out-dir ./test-reports
-r cli imprime un desglose legible por iteración en la terminal, que es lo que escaneas en un log de compilación. -r junit escribe JUnit XML, el formato que casi todos los paneles de CI analizan en un árbol de pass/fail, de modo que una fila fallida aparece como una prueba fallida nombrada en lugar de texto de log oculto. También puedes pasar html y json; html ofrece un informe navegable para archivar como artefacto de compilación, y json proporciona una salida estructurada sin procesar si post-procesas los resultados. --out-dir controla dónde se guardan los archivos para que puedas conservarlos como artefactos.
Por defecto, la ejecución se detiene en la primera aserción rota. Para una tabla de datos amplia, eso suele ser incorrecto, porque quieres ver todas las filas fallidas en una sola pasada, no arreglar una y volver a ejecutar para encontrar la siguiente. Cambia el comportamiento con --on-error:
apidog run --access-token $APIDOG_ACCESS_TOKEN \
-t 605067 -e 1629989 \
-d ./test-data/checkout-cases.csv \
--on-error continue \
-r cli,junit --out-dir ./test-reports
--on-error continue ejecuta cada iteración incluso cuando las anteriores fallan, por lo que un solo informe te muestra que las filas dos, siete y diecinueve están rotas de una sola vez. La ejecución sigue terminando con un código de salida distinto de cero si algo falla, por lo que sigue siendo una puerta de verdad. --on-error end es el valor predeterminado de fallo rápido para una comprobación rápida; ignore es para el raro paso conocido como inestable que no quieres que descarrile la ejecución.
Depurar una vinculación que silenciosamente no hace nada
El modo de fallo que más tiempo hace perder en las ejecuciones basadas en datos no es una aserción en rojo. Es una ejecución en verde que no probó nada, porque los datos nunca se vincularon a la solicitud. La solicitud se disparó con valores vacíos, el endpoint devolvió un 200 para una carga útil vacía, y la aserción pasó. La cobertura parece correcta; pero no lo es.
Cuando una ejecución basada en datos se comporta de manera extraña, añade --verbose:
apidog run --access-token $APIDOG_ACCESS_TOKEN \
-t 605067 -e 1629989 \
-d ./test-data/checkout-cases.csv \
--verbose -r cli
--verbose imprime la solicitud y la respuesta completas para cada iteración. Observa el cuerpo de la solicitud que el ejecutor realmente envió. Si ves {{sku}} sin sustituir, o un valor en blanco cuando la celda CSV no lo estaba, la vinculación falló. Tres causas habituales, en orden de frecuencia con la que ocurren:
- El nombre de la columna y el nombre de la variable no coinciden. El encabezado CSV es
product_skuy la solicitud lee{{sku}}. Renombra uno para que sean idénticos. - Una coma extraviada dividió una fila CSV. Un campo de texto libre sin comillas desplazó cada columna después de él, por lo que
expected_statusahora contiene lo que debería estar en la siguiente columna. Cita el campo o cambia el archivo a JSON. - La ruta al archivo de datos es incorrecta en relación con el directorio de trabajo en CI. Se resuelve bien en tu portátil y no lee nada silenciosamente en el pipeline. Utiliza una ruta relativa a la raíz del repositorio que produce el paso de checkout, y confirma que el archivo existe en un paso antes de la ejecución.
La regla general: cuando las iteraciones pasan pero sospechas que no deberían, lee una solicitud detallada antes de confiar en el verde. Una prueba que se ejecuta contra una entrada vacía es peor que ninguna prueba, porque te dice que todo está bien mientras el endpoint no se prueba.
Conectarlo a CI
La ventaja es que toda la tabla se ejecuta con cada cambio sin que nadie haga clic en Ejecutar. Aquí tienes un trabajo de GitHub Actions que instala el CLI y ejecuta un escenario basado en CSV en cada pull request:
name: Data-driven API tests
on: [pull_request]
jobs:
api-tests:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: '20'
- name: Install Apidog CLI
run: npm install -g apidog-cli
- name: Run data-driven scenario
env:
APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}
run: |
apidog run --access-token $APIDOG_ACCESS_TOKEN \
-t 605067 -e 1629989 \
-d ./test-data/checkout-cases.csv \
--on-error continue \
-r cli,junit --out-dir ./test-reports
- name: Upload report
if: always()
uses: actions/upload-artifact@v4
with:
name: api-test-report
path: ./test-reports
El token proviene de secrets.APIDOG_ACCESS_TOKEN, configurado una vez en la configuración del repositorio. --on-error continue recopila todas las filas fallidas en un solo informe en lugar de detenerse en la primera. El if: always() en la carga mantiene el informe incluso cuando la ejecución falla, que es cuando más quieres leerlo. Intercambia la ruta del CSV por un archivo JSON, o por un ID de datos de prueba almacenado, y nada más cambia.
Los mismos tres pasos se trasladan a cualquier sistema de CI: instala Node.js y el CLI, expón el token como una variable de entorno, llama a apidog run con -d. GitLab CI, Jenkins, CircleCI y el resto no necesitan una reescritura de tus pruebas por plataforma. Para una explicación más detallada del lado de Actions, consulta la automatización de pruebas API en GitHub Actions, y para la superficie completa de flags del CLI a través de reporteros, manejo de errores y TLS, la guía completa de Apidog CLI expone cada opción.
Un flujo de trabajo que escala sin aumentar la prueba
Comienza con un escenario y tres filas. Construye el escenario en la aplicación con referencias a variables en las solicitudes y el resultado esperado en las aserciones. Escribe un CSV con un camino feliz, un fallo conocido y un caso límite. Ejecútalo localmente con -d hasta que las tres iteraciones se comporten correctamente.
Luego haz crecer los datos, no el escenario. Cada informe de error se convierte en una nueva fila con su salida esperada correcta. El error se convierte en un caso de regresión permanente, y nunca escribiste una prueba nueva; agregaste una línea a un archivo. En unos pocos meses, ese archivo recopila la verdadera complejidad que tu endpoint enfrenta en producción.
Finalmente, introduce el comando apidog run -d en CI con --on-error continue y el reportero junit. Ahora, un cambio que rompa la fila del cupón caducado hará que la compilación falle en el momento en que se envíe, con una iteración nombrada que apunta directamente al caso defectuoso. El escenario sigue siendo algo pequeño y legible, sin importar cuán amplia sea la tabla. Esa es la ganancia acumulada: la cobertura crece por la entrada de datos y el mantenimiento se mantiene plano.
Si aún estás decidiendo si un ejecutor CLI como este se adapta a tu stack frente a un framework code-first, el análisis en qué herramienta elegir para pruebas de API basadas en datos con CSV o JSON compara los enfoques, y Apidog CLI vs Newman cubre el análogo de línea de comandos más cercano del mundo de Postman.
Preguntas frecuentes
¿Puede -d tomar tanto una ruta de archivo como un conjunto de datos almacenado? El flag -d acepta uno de los dos por ejecución: una ruta de archivo CSV o JSON local, o un ID de datos de prueba que apunta a un conjunto de datos guardado en tu proyecto Apidog. Pasas un solo valor. Usa la ruta del archivo cuando los datos deban versionarse con tu repositorio, y el ID almacenado cuando una tabla compartida reside en la aplicación y no quieres confirmar una copia.
¿Tengo que decirle al CLI si mi archivo es CSV o JSON? No. El ejecutor lee el formato del propio archivo, por lo que el mismo flag -d maneja ambos. Mantén los nombres de tus columnas (CSV) o claves de objeto (JSON) coincidentes con los nombres de las variables que referencia tu escenario, y podrás cambiar de formato sin modificar el comando.
¿Qué sucede si uso -d y -n juntos? El recuento de filas del archivo de datos impulsa el número de iteraciones, por lo que -n suele ser innecesario con -d. Recurre a -n cuando quieras repetir una ejecución sin un archivo de datos, como una prueba de resistencia, o cuando específicamente quieras ejecutar toda la tabla más de una vez.
¿Por qué mi ejecución basada en datos pasó sin probar nada? La causa más común es una vinculación que nunca ocurrió: un nombre de columna que no coincide con el nombre de la variable, o una ruta de archivo incorrecta en CI que no leyó nada. Ejecuta una vez con --verbose e inspecciona el cuerpo de la solicitud que envió el CLI. Si ves {{variables}} sin sustituir o valores en blanco, corrige la falta de coincidencia de nombres o la ruta antes de confiar en el resultado verde.
¿Cómo mantengo las credenciales fuera de mi archivo de datos? Mantén los tokens y las claves completamente fuera del CSV o JSON. Pásalos en tiempo de ejecución con --global-var o --env-var desde tu almacén de secretos de CI, de la misma manera que pasarías --global-var "api_key=$RUNTIME_API_KEY". El archivo de datos debe contener las entradas de prueba y los resultados esperados, nada que autentifique la ejecución.
¿Puedo ejecutar los mismos datos contra staging y producción? Sí. Mantén el escenario y el archivo de datos fijos y cambia el objetivo con -e. Apunta una comprobación de solicitud de extracción a un ID de entorno de staging y una prueba de humo post-despliegue a producción utilizando el mismo escenario y los mismos datos, solo un valor -e diferente. Separar el entorno de los datos es la razón principal por la que esto funciona.
Conclusión
El flag -d es la historia completa de las pruebas basadas en datos para el CLI de Apidog, y es más flexible de lo que parece a primera vista. Lee un archivo CSV o JSON local, o un conjunto de datos almacenado en tu proyecto por ID. Se empareja con -n para repeticiones, con --env-var y --global-var para la configuración por ejecución, y con --on-error continue para que una ejecución muestre cada fila fallida. Ejecútalo desde un ID de escenario en línea o desde un archivo exportado sin conexión, y lee los resultados por iteración a través de los reporteros junit y cli.
Crea el escenario una vez, describe cada caso como una fila y deja que el ejecutor amplíe tu cobertura cada vez que alguien añade una línea al archivo. Descarga Apidog, apunta apidog run a tu primer archivo de datos y convierte un único escenario en una tabla de casos que se ejecuta en cada push.