DEV Community

Cover image for Cómo ejecutar pruebas de API sin la configuración YAML repetitiva de Tavern
Roobia
Roobia

Posted on • Originally published at apidog.com

Cómo ejecutar pruebas de API sin la configuración YAML repetitiva de Tavern

#api #python #spanish #testing

Tavern encaja muy bien si tu equipo ya vive en pytest: instalas el plugin, escribes pruebas de API en YAML y las ejecutas con el mismo comando que usas para tus tests de Python. El problema aparece cuando esos archivos crecen: login, tokens, recursos encadenados, validaciones de respuesta y variables guardadas terminan convirtiéndose en YAML profundo, frágil y difícil de mantener.

Prueba Apidog hoy

Lo que Tavern hace bien

Tavern merece crédito: resuelve bien el caso de uso de pruebas de API declarativas dentro de un stack Python.

1. Se integra con pytest

Tavern es un plugin de pytest. Lo instalas, colocas un archivo *.tavern.yaml en tu carpeta de tests y pytest lo descubre como cualquier otra prueba.

pip install tavern
pytest
Enter fullscreen mode Exit fullscreen mode

Eso significa que puedes seguir usando:

  • pytest -k para filtrar pruebas.
  • pytest -x para detenerte en el primer fallo.
  • pytest-xdist para ejecución paralela.
  • pytest-html o reportes JUnit mediante plugins.
  • Fixtures de pytest para configuración compartida.

Para equipos backend centrados en Python, esto es una ventaja real.

2. El YAML es legible para casos simples

Una prueba básica de Tavern se entiende rápido:

test_name: Get a single order

stages:
  - name: Fetch order 1042
    request:
      url: https://api.shop.test/orders/1042
      method: GET
    response:
      status_code: 200
      json:
        id: 1042
        status: shipped
Enter fullscreen mode Exit fullscreen mode

La solicitud y la respuesta esperada están juntas. Para validar un status_code y algunos campos, esto puede ser más claro que escribir una prueba completa con requests y assert.

3. Permite guardar y reutilizar variables

Tavern también soporta flujos de varias etapas. Puedes extraer un valor de una respuesta con save y usarlo después con {variable}:

stages:
  - name: Log in
    request:
      url: https://api.shop.test/auth/login
      method: POST
      json:
        username: tester
        password: hunter2
    response:
      status_code: 200
      save:
        json:
          token: access_token

  - name: Read the profile with the saved token
    request:
      url: https://api.shop.test/me
      method: GET
      headers:
        Authorization: "Bearer {token}"
    response:
      status_code: 200
Enter fullscreen mode Exit fullscreen mode

Esto cubre flujos comunes como:

  1. Iniciar sesión.
  2. Guardar un token.
  3. Usar el token en una llamada posterior.
  4. Validar la respuesta.

4. No se limita a HTTP

Tavern también puede probar MQTT, algo útil en sistemas IoT o arquitecturas basadas en mensajes. Además, al ejecutarse dentro de pytest, puedes mezclar pruebas YAML de API con pruebas Python tradicionales en la misma ejecución.

Tavern es una buena herramienta. La pregunta práctica es si su modelo escala bien para tu equipo.

Dónde se acumula la fricción con YAML

El costo de Tavern aparece cuando pasas de pruebas pequeñas a una suite real.

1. YAML es sensible a la indentación

El ejemplo simple es limpio. Pero una prueba real suele incluir:

  • Headers.
  • Query params.
  • Body de solicitud.
  • Validaciones del body de respuesta.
  • Variables guardadas.
  • Validaciones externas con verify_response_with.
  • Fixtures o configuración compartida.

El resultado puede terminar con varios niveles de anidación:

stages:
  - name: Create order
    request:
      url: https://api.shop.test/orders
      method: POST
      headers:
        Authorization: "Bearer {token}"
        Content-Type: application/json
      json:
        product_id: 123
        quantity: 2
    response:
      status_code: 201
      json:
        status: created
      save:
        json:
          order_id: id
Enter fullscreen mode Exit fullscreen mode

Un espacio mal colocado rompe el parser. Además, el editor no siempre autocompleta las claves específicas de Tavern como un IDE autocompleta métodos de Python. Tienes que recordar si corresponde usar status_code, json, save, verify_response_with, etc.

2. La prueba y el contrato de API viven separados

En Tavern, el YAML contiene el método, la URL, los campos esperados y las validaciones. Pero el contrato real de la API suele vivir en otro lugar:

  • Un archivo OpenAPI.
  • Una especificación Swagger.
  • Decoradores del framework backend.
  • Una wiki.
  • Una colección de Postman.

Cuando cambia un campo en la API, el YAML no se actualiza automáticamente. Alguien debe mantener sincronizados ambos artefactos.

Ese mantenimiento manual suele fallar en suites grandes.

3. Depende de un stack Python

Tavern funciona muy bien para testers y developers cómodos con Python. Pero si QA, frontend o producto quieren revisar o añadir pruebas, tienen que entender al mismo tiempo:

  • pip.
  • Entornos virtuales.
  • Convenciones de pytest.
  • Estructura YAML.
  • Esquema específico de Tavern.

Para equipos mixtos, esa barrera puede limitar la colaboración.

El camino para saltarse el YAML

Una alternativa es no escribir pruebas como archivos YAML separados, sino construirlas desde la especificación de API que ya tienes.

En Apidog, la especificación, la solicitud y la prueba forman parte del mismo flujo. Puedes importar o diseñar la API una vez usando OpenAPI, Swagger o una colección de Postman, y después crear escenarios de prueba a partir de esos endpoints.

El flujo práctico es:

  1. Importa o define tu API en Apidog.
  2. Crea un escenario de prueba.
  3. Añade los endpoints en orden.
  4. Encadena valores entre pasos, como tokens o IDs.
  5. Configura aserciones desde la interfaz.
  6. Ejecuta el escenario localmente o en CI con apidog run.

La diferencia principal es que no mantienes una segunda copia del contrato en YAML. La prueba se construye alrededor de la especificación.

Cuando necesitas automatizar, puedes ejecutar esos mismos escenarios sin interfaz gráfica con Apidog CLI, de forma similar a como ejecutarías Tavern con pytest.

Instalación y ejecución de Apidog CLI

El runner es un paquete npm llamado apidog-cli.

Instálalo globalmente:

npm install -g apidog-cli
Enter fullscreen mode Exit fullscreen mode

Luego ejecuta un escenario:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli
Enter fullscreen mode Exit fullscreen mode

Qué significa cada opción:

  • --access-token: autentica la ejecución. Guárdalo como secreto de CI, no en el repositorio.
  • -t: ID del escenario de prueba.
  • -e: ID del entorno, por ejemplo dev, staging o prod.
  • -r: reportero de salida. cli imprime resultados en la terminal.

No necesitas memorizar los IDs. En Apidog:

  1. Abre el escenario de prueba.
  2. Ve a la pestaña CI/CD.
  3. Elige la opción de línea de comandos.
  4. Genera el token.
  5. Copia el comando generado.
  6. Mueve el token a un secreto de CI.

Si prefieres no instalar el paquete globalmente, usa npx:

npx apidog-cli run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli
Enter fullscreen mode Exit fullscreen mode

Para CI, suele ser útil generar reportes HTML y JUnit:

apidog run \
  --access-token $APIDOG_ACCESS_TOKEN \
  -t 605067 \
  -e 1629989 \
  -r html,junit \
  --out-dir ./apidog-reports
Enter fullscreen mode Exit fullscreen mode

Reporteros disponibles:

  • cli
  • html
  • json
  • junit

Para ver las opciones disponibles en tu versión instalada:

apidog run --help
Enter fullscreen mode Exit fullscreen mode

Comparativa

Tavern Apidog
Formato de prueba Archivos YAML (*.tavern.yaml) Escenarios visuales construidos a partir de la especificación
Tiempo de ejecución Python + pytest apidog run sin interfaz gráfica mediante paquete npm
Autoría Escribir e indentar YAML a mano Encadenar endpoints y configurar aserciones desde la interfaz
Contrato de API Artefacto separado, sincronizado manualmente La especificación es la fuente de verdad de la prueba
Encadenamiento de variables Bloques save: y sustitución de {var} Paso de valores entre pasos en la interfaz
Reporteros pytest-html, JUnit mediante plugins de pytest cli, html, json, junit integrados
Quién puede escribir pruebas Testers cómodos con Python Miembros del equipo, incluidos perfiles no centrados en Python
Protocolos HTTP y MQTT HTTP, además de SOAP, WebSocket, gRPC y más

Tavern gana si tu equipo está completamente orientado a Python y quieres mantener las pruebas de API dentro del mismo repositorio y ejecución de pytest.

Apidog gana si quieres reducir el mantenimiento de YAML, mantener contrato y prueba conectados, y facilitar que más personas del equipo contribuyan a las pruebas.

Integrándolo en CI

Este es un ejemplo completo con GitHub Actions:

name: Pruebas de API
on: [push, pull_request]

jobs:
  api-tests:
    runs-on: ubuntu-latest
    steps:
      - name: Instalar Apidog CLI
        run: npm install -g apidog-cli

      - name: Ejecutar escenario de prueba de API
        run: |
          apidog run \
            --access-token "$APIDOG_ACCESS_TOKEN" \
            -t 605067 \
            -e 1629989 \
            -r html,junit \
            --out-dir apidog-reports
        env:
          APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}

      - name: Subir informe
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: apidog-report
          path: apidog-reports
Enter fullscreen mode Exit fullscreen mode

Puntos importantes:

  • El token se guarda en secrets.APIDOG_ACCESS_TOKEN.
  • apidog run falla con código distinto de cero si falla una aserción.
  • CI marca el job como fallido.
  • La pull request queda bloqueada si tu configuración exige checks en verde.
  • if: always() permite subir el reporte incluso cuando las pruebas fallan.

Ese comportamiento es el mismo patrón que ya usas con otros runners: el código de salida actúa como puerta de calidad.

Para pipelines más completas, revisa Apidog CLI en tu pipeline de CI/CD y el recorrido de GitHub Actions, que también cubren variantes con GitLab CI y Jenkins.

Una nota sobre pytest

Dejar de escribir YAML de Tavern no significa abandonar pytest.

Muchos equipos mantienen:

  • Pruebas unitarias en pytest.
  • Pruebas de integración Python en pytest.
  • Pruebas de contrato de API en Apidog.

Ese enfoque separa responsabilidades:

  • pytest sigue siendo ideal para lógica interna de Python.
  • Apidog cubre escenarios de API basados en la especificación.
  • CI ejecuta ambos como puertas de calidad.

Si quieres profundizar en el lado Python, puedes revisar esta guía sobre pytest para pruebas automatizadas de API.

Si también estás comparando runners de línea de comandos, revisa Postman CLI vs Newman y esta guía sobre pruebas de API sin Postman.

Preguntas frecuentes

¿Apidog CLI es gratuito?

Sí. El paquete npm apidog-cli es gratuito para instalar y ejecutar:

npm install -g apidog-cli
Enter fullscreen mode Exit fullscreen mode

Ejecuta escenarios de prueba de tu proyecto Apidog. Lo que puedes ejecutar depende de tu plan de Apidog, pero el runner de línea de comandos no es un producto de pago separado.

¿Puedo seguir usando pytest junto con Apidog?

Sí. Puedes mantener tus pruebas unitarias y de integración en pytest y usar Apidog para pruebas de contrato de API. No son opciones excluyentes.

¿Cómo bloquea Apidog una fusión incorrecta en CI?

Mediante el código de salida. Si una aserción falla, apidog run sale con un código distinto de cero. CI interpreta ese resultado como fallo y bloquea la fusión o el despliegue según tus reglas.

¿Qué reportero debo usar en CI?

Usa junit si quieres que tu CI lea resultados estructurados. Añade html si quieres un reporte navegable como artefacto.

Ejemplo recomendado:

apidog run \
  --access-token $APIDOG_ACCESS_TOKEN \
  -t 605067 \
  -e 1629989 \
  -r html,junit \
  --out-dir ./apidog-reports
Enter fullscreen mode Exit fullscreen mode

¿Apidog solo prueba HTTP?

No. Apidog cubre HTTP, SOAP, WebSocket, Server-Sent Events y gRPC. Tavern añade MQTT a HTTP, así que si MQTT es central en tu stack, considéralo dentro de la evaluación.

Conclusión

Tavern es una opción sólida si ya trabajas con pytest y quieres describir pruebas de API en YAML. Su integración con pytest es su mayor fortaleza.

El costo aparece cuando la suite crece: más indentación, más bloques save, más duplicación del contrato y más mantenimiento manual.

Si quieres ejecutar pruebas de API en CI sin interfaz gráfica, pero sin mantener YAML separado de la especificación, puedes construir los escenarios desde el contrato y ejecutarlos con apidog run.

Descarga Apidog e importa una API existente para probar el flujo donde la especificación y la prueba permanecen conectadas.

Top comments (0)