DEV Community

Cover image for Como Executar Testes de API Sem o Boilerplate YAML do Tavern
Lucas
Lucas

Posted on • Originally published at apidog.com

Como Executar Testes de API Sem o Boilerplate YAML do Tavern

#python #api #productivity #testing

Tavern é uma escolha sólida quando sua equipe já usa pytest: você descreve testes de API em YAML, executa com o mesmo comando pytest e reaproveita fixtures, plugins, pytest-xdist, relatórios e paralelismo. Para times Python, colocar um test_*.tavern.yaml ao lado dos testes unitários parece natural.

Experimente o Apidog hoje

A fricção aparece quando o YAML cresce. Um fluxo comum — login, salvar token, criar recurso, validar resposta e excluir — vira um arquivo longo com blocos request, response, save e verify_response_with. Um espaço errado quebra o parsing, e o contrato real da API geralmente continua em outro lugar: OpenAPI, Swagger, wiki ou coleção Postman desatualizada.

O que o Tavern faz bem

Antes de trocar de ferramenta, vale reconhecer onde o Tavern funciona bem.

1. Ele roda dentro do pytest

Instale o Tavern:

pip install tavern
Enter fullscreen mode Exit fullscreen mode

Crie um arquivo YAML no diretório de testes e execute:

pytest
Enter fullscreen mode Exit fullscreen mode

Como o Tavern é um plugin do pytest, você mantém o fluxo que sua equipe Python já usa:

pytest -k orders
pytest -x
pytest -n auto
Enter fullscreen mode Exit fullscreen mode

Isso permite usar:

  • fixtures para setup compartilhado;
  • pytest-xdist para paralelismo;
  • pytest-html para relatórios;
  • filtros com -k;
  • a mesma pipeline que já roda testes Python.

2. O YAML é declarativo para casos simples

Um teste básico é fácil de ler:

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

A requisição e a resposta esperada ficam próximas. Para validar status code e alguns campos, isso é mais direto do que escrever um teste completo com requests e assert.

3. Ele permite encadear valores entre etapas

Você pode salvar valores da resposta e reutilizá-los depois:

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

Para fluxos curtos, isso resolve bem o problema de autenticação e reutilização de dados.

4. Ele também cobre MQTT

Além de HTTP, o Tavern testa MQTT. Isso é útil para equipes que trabalham com IoT ou sistemas baseados em mensagens. Como tudo roda dentro do pytest, você pode misturar testes YAML e testes Python no mesmo relatório.

Onde o YAML começa a pesar

O Tavern não é o problema. O custo aparece quando a suíte cresce.

1. O YAML fica profundo e frágil

Um teste real geralmente inclui:

  • headers;
  • query params;
  • body;
  • validações de resposta;
  • tipos;
  • variáveis salvas;
  • funções externas com verify_response_with.

Isso leva a arquivos com vários níveis de indentação. Em YAML, um espaço errado pode transformar uma falha de teste em erro de parsing.

Exemplo do tipo de estrutura que começa a ficar difícil de manter:

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

Além disso, editores nem sempre oferecem autocomplete confiável para o schema do Tavern. Você acaba consultando a documentação para lembrar se o campo correto é status_code, json, body, save ou outro.

2. O teste e o contrato ficam separados

O YAML codifica método, URL, payload e resposta esperada. Mas o contrato real da API pode estar em:

  • OpenAPI;
  • Swagger;
  • decorators do framework;
  • documentação interna;
  • coleção Postman;
  • lugar nenhum com garantia de atualização.

Quando um campo muda no contrato, o YAML não sabe disso automaticamente. Alguém precisa manter as duas versões sincronizadas.

3. Ele exige familiaridade com Python

Para devs backend Python, o fluxo é natural. Para QA, frontend ou produto, o caminho pode ser mais pesado:

pip install tavern
python -m venv .venv
pytest
Enter fullscreen mode Exit fullscreen mode

Além disso, a pessoa precisa entender convenções do pytest e o schema YAML do Tavern apenas para validar uma chamada HTTP.

Uma alternativa: criar testes a partir da especificação

Uma forma de reduzir boilerplate é criar os testes a partir da definição da API, em vez de duplicar o contrato em arquivos YAML.

No Apidog, a especificação da API, a requisição e o teste ficam conectados. Você pode importar ou projetar sua API usando OpenAPI, Swagger ou uma coleção Postman, e cada endpoint mantém seu schema associado.

O fluxo prático fica assim:

  1. Importe ou crie a API no Apidog.
  2. Crie um cenário de teste.
  3. Encadeie endpoints visualmente.
  4. Passe valores entre etapas, como tokens ou IDs.
  5. Configure asserções no painel.
  6. Execute localmente ou via CLI na CI.

Em vez de escrever manualmente:

save:
  json:
    token: access_token
Enter fullscreen mode Exit fullscreen mode

você configura a extração e reutilização do valor no cenário.

A vantagem principal é que o teste nasce ligado à especificação. Se o contrato muda, o cenário que depende daquele campo fica mais fácil de revisar do que um YAML isolado no repositório.

Quando precisar executar sem interface gráfica, o Apidog CLI roda os mesmos cenários pela linha de comando, incluindo em CI.

Instalando e executando o Apidog CLI

O executor é o pacote npm apidog-cli.

Instale globalmente:

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

Depois execute um cenário:

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

Significado dos parâmetros:

  • --access-token: autentica a execução na sua conta Apidog;
  • -t: ID do cenário de teste;
  • -e: ID do ambiente, como dev, staging ou prod;
  • -r: reporter usado na saída.

Você não precisa decorar os IDs. No Apidog:

  1. Abra o cenário de teste.
  2. Acesse a aba CI/CD.
  3. Escolha a opção de linha de comando.
  4. Gere o token.
  5. Copie o comando.
  6. Salve o token como segredo na CI.

Para runners efêmeros, use npx:

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

Gerando relatórios

O Apidog CLI suporta reporters como:

  • cli;
  • html;
  • json;
  • junit.

Para CI, uma combinação prática é:

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

Use:

  • junit para dashboards de CI;
  • html para um relatório navegável;
  • --out-dir para controlar onde os arquivos serão salvos.

Para ver as flags disponíveis na sua versão:

apidog run --help
Enter fullscreen mode Exit fullscreen mode

Comparativo

Tavern Apidog
Formato do teste Arquivos YAML (*.tavern.yaml) Cenários visuais construídos contra a especificação
Ambiente de execução Python + pytest apidog run headless (pacote npm)
Criação Escrever e identar YAML manualmente Arrastar e encadear endpoints, asserções de caixa de seleção
Contrato da API Artefato separado, mantido sincronizado manualmente A especificação é a fonte de verdade do teste
Encadeamento de variáveis Blocos save: e substituição {var} Passa valores entre as etapas na interface
Relatores pytest-html, JUnit via plugins pytest cli, html, json, junit integrados
Quem pode escrever testes Testadores confortáveis com Python Qualquer pessoa da equipe, incluindo não-codificadores
Protocolos HTTP e MQTT HTTP, mais SOAP, WebSocket, gRPC e mais

Escolha Tavern se:

  • sua equipe já vive no pytest;
  • você quer manter os testes no mesmo repositório;
  • seus testes de API são curtos;
  • MQTT é essencial para sua stack.

Escolha Apidog se:

  • você quer evitar manutenção manual de YAML;
  • o contrato da API precisa ser a fonte de verdade;
  • pessoas fora do time Python também precisam criar ou revisar testes;
  • você quer execução headless na CI sem escrever arquivos *.tavern.yaml.

Integrando na CI com GitHub Actions

Exemplo completo:

name: API tests
on: [push, pull_request]

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

      - name: Run API test scenario
        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: Upload report
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: apidog-report
          path: apidog-reports
Enter fullscreen mode Exit fullscreen mode

Pontos importantes:

  • salve APIDOG_ACCESS_TOKEN em secrets;
  • não coloque token no repositório;
  • use if: always() para publicar relatório mesmo quando os testes falharem;
  • use junit para integração com a visualização de testes da CI;
  • use html para depuração manual.

Quando uma asserção falha, apidog run retorna código diferente de zero. A CI interpreta isso como falha, marca o job em vermelho e pode bloquear merge ou deploy.

Para pipelines mais detalhados, veja Apidog CLI em seu pipeline CI/CD e o guia passo a passo do GitHub Actions.

Usando pytest e Apidog juntos

Migrar testes de API para fora do YAML do Tavern não significa abandonar pytest.

Um desenho comum é:

  • manter testes unitários e de integração Python no pytest;
  • usar Apidog para testes de contrato e cenários de API;
  • executar ambos na mesma pipeline.

Exemplo de pipeline conceitual:

steps:
  - name: Run Python tests
    run: pytest

  - name: Run API contract tests
    run: |
      apidog run \
        --access-token "$APIDOG_ACCESS_TOKEN" \
        -t 605067 \
        -e 1629989 \
        -r html,junit \
        --out-dir apidog-reports
Enter fullscreen mode Exit fullscreen mode

Assim, o pytest continua cobrindo lógica Python, e o Apidog cobre os fluxos que precisam acompanhar a especificação da API.

Se você também está comparando outros executores, veja Postman CLI vs Newman e testes de API sem Postman.

FAQ

O Apidog CLI é gratuito?

Sim. O pacote npm apidog-cli é gratuito para instalar e executar com:

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

Ele executa os cenários de teste do seu projeto Apidog. O que você pode executar depende do seu plano Apidog, mas o executor de linha de comando não é um produto pago separado.

Ainda posso usar pytest junto com Apidog?

Sim. Mantenha testes unitários e de integração Python no pytest e use Apidog para a camada de contrato da API. As duas abordagens podem rodar na mesma CI.

Como o Apidog bloqueia um merge incorreto?

Pelo código de saída. Quando uma asserção falha, apidog run retorna um código não zero. A CI marca a etapa como falha e pode bloquear o merge ou deploy.

Qual reporter devo usar na CI?

Use junit para resultado legível por máquina e html para um relatório navegável.

Exemplo:

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

O Apidog testa apenas HTTP?

Não. O Apidog cobre HTTP, SOAP, WebSocket, Server-Sent Events e gRPC. O Tavern cobre HTTP e MQTT, então considere isso se MQTT for central para sua arquitetura.

Conclusão

Tavern é uma boa opção quando sua equipe já trabalha com pytest e aceita manter testes de API em YAML. A integração com pytest é seu ponto mais forte.

O custo aparece na manutenção: arquivos YAML profundos, sensíveis à indentação e separados do contrato da API.

Se você quer testes de API executáveis em CI, com código de saída confiável, relatórios e menos duplicação de contrato, construir cenários contra a especificação e executá-los com apidog run é um caminho mais leve.

Baixe o Apidog e importe uma API existente para testar o fluxo em que a especificação vira a base dos testes.

Top comments (0)