Cómo ejecutar pruebas de API parametrizadas desde CSV y JSON

Escribiste una prueba de inicio de sesión. Pasa. Luego un compañero de equipo hace la pregunta obvia: ¿pasa para la cuenta bloqueada, el correo electrónico no verificado, la contraseña con un espacio al final, la cadena de inyección SQL que alguien eventualmente pegará en el campo? Ahora tienes una opción. Copiar esa prueba cinco veces y cambiar un valor en cada copia, o encontrar una manera de alimentar la misma prueba con muchas filas de entrada y dejar que las ejecute todas.

La ruta de copiar y pegar es como la mayoría de los conjuntos de pruebas se pudren. Cinco pruebas casi idénticas se separan a lo largo de un año. Una recibe una nueva aserción, las otras no. Un cambio de nombre de campo rompe cuatro de ellas silenciosamente. Terminas manteniendo cinco cosas que deberían haber sido una. Las pruebas parametrizadas solucionan esto de raíz: escribes la prueba una vez, luego la apuntas a una tabla de entradas y salidas esperadas. Un escenario, cientos de casos, un único lugar para editar.

Qué significan realmente las pruebas parametrizadas

Las pruebas parametrizadas, a veces llamadas pruebas dirigidas por datos, separan la lógica de una prueba de los datos contra los que se ejecuta. La lógica es la secuencia de pasos: enviar una solicitud, verificar el código de estado, validar un campo en la respuesta. Los datos son el conjunto de entradas y expectativas contra las que quieres que se ejecute esa lógica.

Imagina un único escenario de prueba para un endpoint de código de descuento. La lógica es siempre la misma. Envía POST /api/orders con un código, luego aserción sobre la respuesta. Los datos cambian por caso:

Cinco filas, cinco comportamientos distintos, una prueba. El ejecutor itera sobre las filas. En cada pasada, vincula los valores de las columnas a variables, dispara la solicitud y verifica las aserciones contra las expectativas de esa fila. Cuando la fila 3 falla porque el código caducado devolvió 200 en lugar de 410, obtienes un fallo claro que apunta a una fila. No tienes que buscar en cinco archivos de prueba separados para averiguar qué copia se rompió.

Este patrón es más importante en los límites. La cobertura de la ruta feliz es fácil de escribir y rara vez detecta el error que te despierta a las 2 a.m. Los errores residen en los casos límite: la cadena vacía, el número negativo, el nombre Unicode, el token caducado, el valor que está un centavo por encima del límite. La parametrización hace que añadir un caso límite sea tan barato como añadir una fila a una hoja de cálculo.

Por qué un archivo de datos separado es mejor que los valores codificados

Podrías codificar cada caso directamente en la prueba. La mayoría de la gente empieza ahí. El problema aparece más tarde.

Cuando los datos residen en la prueba, un no ingeniero no puede contribuir con casos. Tu líder de QA conoce quince entradas complicadas que han roto este endpoint antes, pero no puede añadirlas sin editar código y abrir una solicitud de extracción. Cuando los datos residen en un CSV, editan una hoja de cálculo y la confirman. La barrera se reduce a casi cero.

Un archivo separado también mantiene legible tu escenario de prueba. Una prueba que itera sobre un archivo externo es corta: una solicitud, un puñado de aserciones, listo. Una prueba con treinta casos en línea es un muro de repetición que nadie quiere tocar. Y cuando necesitas generar casos programáticamente, por ejemplo, mil filas extraídas de los registros de producción, un archivo es la única opción sensata. No puedes pegar mil casos en el cuerpo de una prueba.

El formato que elijas depende de la forma de tus datos. Los casos planos y tabulares se ajustan a CSV. Las cargas útiles anidadas o estructuradas se ajustan a JSON. Ambos son entradas de primera clase en el ejecutor de Apidog, por lo que la elección se trata de tus datos, no de las limitaciones de la herramienta.

Configuración de tu archivo de datos

Empieza con CSV para casos tabulares. La fila de encabezado nombra tus variables; cada fila siguiente es una iteración. Aquí tienes la tabla de códigos de descuento como un archivo real, discount-cases.csv:

code,order_total,expected_status,expected_discount
WELCOME10,100,200,10
WELCOME10,5,422,0
EXPIRED,100,410,0
,100,400,0
FAKE123,100,404,0

Cada encabezado de columna se convierte en una variable que referencias dentro de la prueba. En el cuerpo de la solicitud escribes {{code}} y {{order_total}}; en las aserciones comparas contra {{expected_status}} y {{expected_discount}}. El ejecutor realiza la vinculación fila por fila.

Cuando tus entradas están anidadas, recurre a JSON. Un array de objetos, un objeto por iteración, permite que cada caso lleve datos estructurados que serían incómodos de aplanar en columnas. Aquí tienes user-cases.json para un endpoint de creación de usuarios donde la carga útil tiene campos anidados:

[
  {
    "scenario": "perfil completo válido",
    "user": {
      "email": "ada@example.com",
      "roles": ["admin", "billing"],
      "profile": { "country": "US", "timezone": "America/New_York" }
    },
    "expected_status": 201
  },
  {
    "scenario": "correo electrónico faltante",
    "user": {
      "email": "",
      "roles": ["viewer"],
      "profile": { "country": "GB", "timezone": "Europe/London" }
    },
    "expected_status": 400
  },
  {
    "scenario": "rol desconocido",
    "user": {
      "email": "grace@example.com",
      "roles": ["wizard"],
      "profile": { "country": "CA", "timezone": "America/Toronto" }
    },
    "expected_status": 422
  }
]

Dentro de la prueba, referencias los valores estructurados con la misma sintaxis {{user}}, {{expected_status}}, y Apidog entrega los campos de cada objeto a la iteración. La columna scenario es una etiqueta para ti; aparece en el informe para que una iteración fallida diga “rol desconocido” en lugar de “iteración 3.”

Algunas reglas evitan que los archivos de datos te causen problemas:

• Mantén una preocupación por archivo. Un archivo de códigos de descuento y un archivo de creación de usuarios son dos archivos, no uno con columnas mezcladas.
• Pon el resultado esperado en los datos, no en la prueba. El punto es que la fila 2 espera un 422 mientras que la fila 1 espera un 200. Si la expectativa está codificada, vuelves a tener una prueba por caso.
• Cita cualquier cosa con una coma en CSV, o cambia ese archivo a JSON. Un campo de texto libre con comas es la trampa común clásica de CSV.
• Almacena estos archivos en tu repositorio junto al resto de tu configuración de prueba para que tengan versiones junto con el código que prueban.

Construyendo el escenario parametrizado en Apidog

En la aplicación Apidog, construye el escenario de prueba una vez como cualquier otro. Añade la solicitud a tu endpoint. En el cuerpo, intercambia los valores literales por referencias a variables: {{code}}, {{order_total}}, y así sucesivamente. Estas son las columnas de tu archivo de datos.

Luego añade las aserciones que leen del mismo archivo. Para el ejemplo del descuento, afirmarías que el estado de la respuesta es igual a {{expected_status}} y que el campo de descuento en el cuerpo JSON es igual a {{expected_discount}}. Debido a que tanto la entrada como la salida esperada provienen de la fila, la misma lógica de aserción valida cada caso correctamente. Si no has escrito aserciones en Apidog antes, Aserciones de API: una guía práctica cubre los patrones, y cómo establecer aserciones y extraer variables de una respuesta JSON muestra el lado de JSONPath en detalle.

Para integrar los datos, abre la configuración de ejecución del escenario de prueba y adjunta tu archivo CSV o JSON como fuente de datos de iteración. Apidog lee el archivo, cuenta las filas y ejecuta el escenario una vez por fila, vinculando las columnas de cada fila a las variables correspondientes. Ejecútalo dentro de la aplicación y obtendrás un desglose por iteración: qué filas pasaron, cuáles fallaron y el valor real frente al esperado para cada aserción fallida.

Aquí es también donde la parametrización se combina con el resto de tu suite. Un escenario parametrizado sigue siendo un escenario, por lo que puedes agrupar varios de ellos en una suite de pruebas y ejecutar todo el conjunto como un solo trabajo. El bucle dirigido por datos maneja la amplitud dentro de un único endpoint; la suite de pruebas maneja la cobertura a través de los endpoints.

Ejecutándolo desde la línea de comandos

La aplicación es donde construyes y depuras. CI es donde la prueba se justifica, ejecutándose en cada solicitud de extracción sin que nadie haga clic en un botón. Esa entrega es para lo que sirve la CLI de Apidog. Toma el escenario que construiste en la aplicación y lo ejecuta sin interfaz gráfica desde una terminal, con los mismos datos de iteración.

La CLI se distribuye como un paquete npm. Instálala globalmente:

npm install -g apidog-cli

El binario es apidog, por lo que cada comando comienza con apidog run. Una ejecución básica apunta a un escenario por ID y un entorno por ID:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli

Para impulsar ese escenario desde un archivo de datos, añade el flag iteration-data. Acepta una ruta a un archivo JSON o CSV:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 \
  -d ./discount-cases.csv -r cli,junit --out-dir ./test-reports

El flag -d (forma larga --iteration-data) es el núcleo de las ejecuciones parametrizadas desde la línea de comandos. Apidog lee el archivo, ejecuta el escenario una vez por fila y reporta cada iteración. Intercambia discount-cases.csv por user-cases.json y el mismo flag maneja el array JSON; el ejecutor detecta el formato del archivo. Trata el token de acceso como una contraseña y guárdalo como un secreto de CI, nunca en un archivo commiteado. Por eso cada ejemplo hace referencia a $APIDOG_ACCESS_TOKEN en lugar de un valor literal.

Algunos flags se emparejan naturalmente con las ejecuciones parametrizadas:

• -d, --iteration-data <ruta> apunta la ejecución a tu archivo CSV o JSON. Este es el que convierte una ejecución de una sola pasada en una dirigida por datos.
• -n, --iteration-count <n> ejecuta el escenario un número fijo de veces. Cuando proporcionas un archivo de datos, el recuento de filas suele impulsar las iteraciones, por lo que recurres a -n principalmente para casos de repetición sin datos, como las pruebas de soak.
• -r, --reporters <lista> elige los formatos de salida. Usa cli para una salida legible del registro de construcción y junit para emitir el XML que los paneles de CI analizan en un árbol de aprobación/falla por iteración.
• --out-dir <ruta> establece dónde se guardan los informes para que puedas archivarlos como artefactos de construcción.

Si quieres la lista autorizada y actual de flags para tu versión instalada, ejecuta apidog run --help. La CLI imprime cada opción con su forma corta y larga.

Integrando ejecuciones parametrizadas en CI

La razón para invertir en pruebas parametrizadas es que dan frutos automáticamente. Aquí tienes un trabajo de GitHub Actions que instala la CLI y ejecuta un escenario dirigido por CSV en cada pull request:

name: Pruebas de API
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: Instalar CLI de Apidog
        run: npm install -g apidog-cli
      - name: Ejecutar pruebas de API parametrizadas
        env:
          APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}
        run: |
          apidog run --access-token $APIDOG_ACCESS_TOKEN \
            -t 605067 -e 1629989 \
            -d ./tests/discount-cases.csv \
            -r cli,junit --out-dir ./test-reports
      - name: Subir informe
        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 de tu repositorio. El reportero junit escribe XML que la mayoría de los paneles de CI convierten en un árbol de resultados por iteración, por lo que una fila fallida aparece como una prueba fallida nombrada en lugar de una pared de texto de registro. El if: always() en el paso de carga significa que conservas el informe incluso cuando la ejecución falla, que es exactamente cuando lo deseas. Para una explicación más detallada del lado de Actions, consulta cómo automatizar pruebas de API en GitHub Actions.

El mismo escenario y el mismo archivo de datos se ejecutan en cualquier sistema de CI. GitLab CI, Jenkins, CircleCI y el resto se reducen a los mismos tres movimientos: instalar Node y la CLI, exponer el token como una variable de entorno, llamar a apidog run con -d. No hay necesidad de reescribir tus pruebas por plataforma.

Comparando enfoques de pruebas parametrizadas

Apidog no es la única forma de ejecutar pruebas de API dirigidas por datos. Vale la pena conocer el panorama para que elijas la opción correcta.

Postman y sus ejecutores también admiten archivos de datos. Con el Collection Runner de Postman o la herramienta de línea de comandos Newman, adjuntas un archivo CSV o JSON y referencias variables {{column}} en las solicitudes, de forma muy similar al patrón aquí. Es un enfoque capaz y bien documentado. La desventaja es que tu lógica de prueba reside en scripts JavaScript de pre-solicitud y de prueba, por lo que a medida que tus aserciones crecen, mantienes más código. Si estás evaluando específicamente los ejecutores de línea de comandos, Postman CLI vs Newman desglosa las diferencias.

Los frameworks 'code-first' como pytest con @pytest.mark.parametrize, @ParameterizedTest de JUnit o REST Assured te dan control total del lenguaje de programación. Son la elección correcta cuando tu lógica de prueba realmente necesita código: configuración compleja, generación de datos personalizada, acoplamiento estrecho a una base de código de prueba existente. El costo es que cada caso vive en código, por lo que los no ingenieros no pueden contribuir, y tú mantienes la configuración HTTP tú mismo.

El enfoque de Apidog es que el escenario es visual y los datos son externos, por lo que la lógica permanece legible y los casos están abiertos a cualquiera que pueda editar una hoja de cálculo, mientras que el mismo escenario sigue ejecutándose sin interfaz gráfica en CI. Si estás eligiendo específicamente una herramienta para ejecuciones dirigidas por datos CSV y JSON, la comparación en qué herramienta usar para pruebas de API dirigidas por datos con CSV o JSON profundiza en las compensaciones. Ninguno de estos enfoques es incorrecto. Adapta el enfoque a quién escribe los casos y cuánta lógica personalizada necesita cada caso.

Un flujo de trabajo práctico que escala

Así es como se ve esto una vez que forma parte de la rutina de tu equipo.

Empieza de forma acotada. Elige un endpoint que te haya causado problemas antes. Escribe el escenario único en Apidog con referencias a variables en la solicitud y el resultado esperado en las aserciones. Construye un CSV con tres filas: una ruta feliz, un fallo conocido, un caso límite. Ejecútalo en la aplicación hasta que las tres iteraciones se comporten como se espera.

Luego haz crecer los datos, no la prueba. Cada vez que llegue un informe de error, añade la entrada que lo causó como una nueva fila con su salida esperada correcta. El error se convierte en un caso de regresión permanente y nunca escribiste una nueva prueba, añadiste una línea a un archivo. En unos pocos meses, el archivo acumula la complejidad del mundo real a la que realmente se enfrenta tu endpoint.

Finalmente, automatízalo. Inserta el comando apidog run -d en CI para que toda la tabla se ejecute en cada pull request. Ahora, un cambio que rompa la ruta del código caducado fallará la compilación en el momento en que se envíe, con una iteración nombrada que apunta directamente a la fila rota.

La ventaja acumulada es el mantenimiento. Cuando la forma de la respuesta del endpoint cambia, arreglas la aserción una vez y cada caso recibe la corrección. Cuando necesitas cincuenta casos más, añades cincuenta filas. La lógica de prueba sigue siendo una cosa única, pequeña y legible, sin importar cuán amplia sea tu cobertura.

Preguntas frecuentes

¿Cuál es la diferencia entre pruebas parametrizadas y pruebas dirigidas por datos? Describen la misma idea y la gente usa los términos indistintamente. Ambos significan ejecutar una prueba repetidamente con diferentes entradas y salidas esperadas proporcionadas desde fuera de la prueba. "Parametrizadas" se apoya en el mecanismo de vinculación de parámetros; "dirigidas por datos" se apoya en la fuente de datos externa. En la práctica, trátalos como sinónimos.

¿Debo usar CSV o JSON para mi archivo de datos? Haz coincidir el formato con la forma de tus datos. Los casos planos y tabulares donde cada fila tiene las mismas columnas simples se ajustan a CSV, y CSV es más fácil de editar para los no ingenieros en una hoja de cálculo. Las cargas útiles anidadas o estructuradas, como un cuerpo de solicitud con arrays y subobjetos, se ajustan a JSON. Apidog lee ambos como datos de iteración, así que elige el que mejor represente tus casos sin contorsiones.

¿Cientos de iteraciones ralentizarán mi pipeline? Cada fila es una ejecución del escenario, por lo que el tiempo total escala con el número de filas multiplicado por la latencia por solicitud. Para la mayoría de las pruebas de API, eso son segundos, no minutos. Si un conjunto de datos grande alarga tu compilación, divídelo: ejecuta un subconjunto de smoke tests rápido en cada pull request y la tabla completa en un trabajo nocturno o de pre-lanzamiento. El mismo escenario y archivo impulsan ambos; solo cambia el subconjunto de datos.

¿Cómo mantengo los secretos fuera de mis archivos de datos y la configuración de pruebas? Mantén las credenciales completamente fuera del archivo de datos. Los tokens y las contraseñas pertenecen a las variables de entorno o al almacén de secretos de tu sistema de CI, referenciados como $APIDOG_ACCESS_TOKEN y similares. El archivo de datos debe contener las entradas de la prueba y los resultados esperados, no material de autenticación. Cualquiera que pueda leer el repositorio puede leer el CSV, así que trátalo de esa manera.

¿Puedo ejecutar el mismo escenario parametrizado contra staging y producción? Sí. Mantén el escenario y el archivo de datos fijos, y cambia de entornos con el flag -e. Apunta una verificación de pull request a staging y una prueba de smoke test post-despliegue a producción usando el mismo ID de escenario y los mismos datos, solo un ID de entorno diferente. Esa es la razón principal por la que el entorno y los datos son entradas separadas.

Conclusión

Las pruebas de API parametrizadas convierten la cobertura de una tarea de copiar y pegar en una tarea de entrada de datos. Escribes la prueba una vez, describes cada caso como una fila en un archivo CSV o JSON, y dejas que el ejecutor haga el resto. La lógica permanece pequeña y legible, los casos están abiertos a cualquiera del equipo, y CI ejecuta toda la tabla en cada cambio.

Apidog te ofrece el constructor visual de escenarios para la autoría, archivos externos CSV y JSON para los datos, y el comando apidog run -d para la ejecución sin interfaz gráfica en cualquier sistema de CI. Construye un escenario, apúntalo a una tabla creciente de casos, y tu cobertura de pruebas se amplía cada vez que alguien añade una fila. Descarga Apidog y convierte tu próxima prueba única y poco confiable en un escenario parametrizado que escala.