DEV Community

Cover image for Teste de API Data-Driven com Apidog CLI: Iterações CSV e JSON
Lucas
Lucas

Posted on • Originally published at apidog.com

Teste de API Data-Driven com Apidog CLI: Iterações CSV e JSON

#api #automation #cli #testing

Você já tem um cenário de teste para o endpoint de checkout: três requisições encadeadas, asserções em cada resposta e execução manual funcionando. O problema aparece quando o pipeline precisa rodar o mesmo cenário com 40 combinações de entrada, dados mantidos pelo QA e ambientes diferentes, como staging e produção. Clonar o cenário 40 vezes não escala; o caminho prático é executar o mesmo cenário via CLI com dados de iteração.

Experimente o Apidog hoje

Com o Apidog, você cria o cenário uma vez no construtor visual e executa esse cenário no terminal com o pacote apidog-cli. A flag principal é -d, abreviação de --iteration-data. Ela recebe um arquivo CSV, um arquivo JSON ou um conjunto de dados salvo no projeto Apidog, e executa o cenário uma vez por linha ou objeto.

Como a flag -d funciona

A opção aparece no apidog run --help assim:

-d, --iteration-data <path|testDataId>   Define os dados a serem usados para as iterações (JSON ou CSV)
Enter fullscreen mode Exit fullscreen mode

O argumento <path|testDataId> aceita duas formas:

  1. Caminho para um arquivo local CSV ou JSON.
  2. ID de um conjunto de dados salvo no projeto Apidog.

Exemplo com CSV local:

apidog run --access-token $APIDOG_ACCESS_TOKEN \
  -t 605067 -e 1629989 \
  -d ./test-data/checkout-cases.csv \
  -r cli
Enter fullscreen mode Exit fullscreen mode

Nesse comando:

  • -t 605067 identifica o cenário de teste.
  • -e 1629989 define o ambiente.
  • -d ./test-data/checkout-cases.csv fornece os dados de iteração.
  • -r cli imprime o resultado no terminal.

Se o arquivo tiver 40 linhas abaixo do cabeçalho, o cenário será executado 40 vezes. Em cada execução, o CLI injeta os valores da linha nas variáveis usadas nas requisições e asserções.

O mesmo comando funciona com JSON:

apidog run --access-token $APIDOG_ACCESS_TOKEN \
  -t 605067 -e 1629989 \
  -d ./test-data/checkout-cases.json \
  -r cli
Enter fullscreen mode Exit fullscreen mode

Você não precisa informar manualmente se o arquivo é CSV ou JSON. O CLI interpreta o formato a partir do arquivo.

Estrutura esperada para CSV

Use CSV quando os casos forem tabulares e simples.

Exemplo de checkout-cases.csv:

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
Enter fullscreen mode Exit fullscreen mode

Cada coluna vira uma variável disponível no cenário:

{
  "sku": "{{sku}}",
  "quantity": "{{quantity}}",
  "coupon": "{{coupon}}"
}
Enter fullscreen mode Exit fullscreen mode

Nas asserções, você pode comparar com os valores esperados da mesma linha:

status == {{expected_status}}
total == {{expected_total}}
Enter fullscreen mode Exit fullscreen mode

A linha:

CHAIR-09,3,,200,447.00
Enter fullscreen mode Exit fullscreen mode

faz coupon virar uma string vazia. Isso permite testar o caso “sem cupom” sem criar outro cenário.

Boas práticas para CSV:

  • O cabeçalho deve ter exatamente o mesmo nome das variáveis usadas no cenário.
  • Se um campo tiver vírgula, coloque o valor entre aspas.
  • Coloque o resultado esperado no arquivo de dados, não fixo na asserção.
  • Versione o CSV junto com o código ou com a configuração de teste.

Para detalhes sobre asserções com JSONPath, veja definindo asserções e extraindo variáveis de uma resposta JSON.

Estrutura esperada para JSON

Use JSON quando o caso de teste tiver dados aninhados ou estruturas difíceis de representar em colunas.

Exemplo de checkout-cases.json:

[
  {
    "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
  }
]
Enter fullscreen mode Exit fullscreen mode

No cenário, você pode usar:

{
  "order": "{{order}}"
}
Enter fullscreen mode Exit fullscreen mode

E nas asserções:

status == {{expected_status}}
Enter fullscreen mode Exit fullscreen mode

O campo label ajuda a identificar a iteração no relatório. Em vez de ver apenas “iteração 2”, você verá algo como unshippable country, o que acelera o diagnóstico.

Executando a partir de um conjunto de dados salvo no Apidog

Além de arquivos locais, -d também aceita um ID de dados de teste:

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

Nesse caso, o CLI busca o conjunto de dados salvo no projeto Apidog.

Use essa opção quando:

  • A equipe de QA mantém os dados diretamente no Apidog.
  • Os dados não precisam estar versionados no repositório.
  • Várias pessoas atualizam a mesma tabela compartilhada.

Use arquivo versionado quando:

  • Os dados precisam acompanhar o código.
  • Você quer revisar mudanças nos casos de teste via pull request.
  • A execução precisa ser reproduzível a partir de um commit específico.

Nenhuma abordagem é “melhor” em todos os casos. A escolha depende de onde deve estar a fonte da verdade dos dados.

Executando offline com um arquivo exportado

Você também pode exportar um caso de teste do Apidog como arquivo e executá-lo diretamente:

apidog run ./checkout.apidog-cli.json -r cli,html
Enter fullscreen mode Exit fullscreen mode

Aqui, o primeiro argumento é o arquivo exportado do cenário. Você não precisa informar -t nem buscar o cenário online.

Também é possível combinar esse arquivo com dados de iteração:

apidog run ./checkout.apidog-cli.json \
  -d ./checkout-cases.csv \
  -r cli,junit
Enter fullscreen mode Exit fullscreen mode

Esse modo é útil quando:

  • O runner de CI não consegue acessar a nuvem do Apidog.
  • Você quer executar um snapshot fixo do cenário.
  • Você precisa garantir que alterações futuras no cenário dentro do app não afetem a execução atual.

Para instalação e primeiros passos, consulte o guia de instalação do Apidog CLI. Para todas as flags, veja a referência completa do Apidog CLI.

Combinando -d com -n, --env-var e --global-var

Execuções orientadas a dados normalmente precisam de mais flags além de -d.

Repetindo execuções com -n

A flag -n define a quantidade de iterações:

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

Quando você usa -d, a quantidade de linhas ou objetos já define o número de iterações. Por isso, -n geralmente é desnecessário com arquivos de dados.

Use -n quando quiser repetir um cenário sem arquivo de dados, por exemplo em um teste de soak.

Injetando variáveis em tempo de execução

Use --env-var e --global-var para passar valores específicos da execução:

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
Enter fullscreen mode Exit fullscreen mode

A separação recomendada é:

  • CSV/JSON: entradas de teste e resultados esperados.
  • --env-var / --global-var: URLs, chaves, tokens e valores por ambiente.

Não coloque credenciais no CSV ou JSON. Passe segredos a partir do secret store da CI.

Gerando relatórios por iteração

Para usar testes orientados a dados na CI, você precisa identificar exatamente qual linha falhou.

Exemplo com saída no terminal e relatório JUnit:

apidog run --access-token $APIDOG_ACCESS_TOKEN \
  -t 605067 -e 1629989 \
  -d ./test-data/checkout-cases.csv \
  -r cli,junit \
  --out-dir ./test-reports
Enter fullscreen mode Exit fullscreen mode

Reporters úteis:

  • cli: mostra um resumo legível no terminal.
  • junit: gera XML compatível com dashboards de CI.
  • html: gera relatório navegável.
  • json: gera saída estruturada para pós-processamento.

Use --out-dir para controlar onde os relatórios serão salvos.

Continuando após falhas com --on-error

Por padrão, uma execução pode parar ao encontrar erro. Em uma tabela grande, isso atrapalha, porque você quer saber todas as linhas quebradas de uma vez.

Use:

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
Enter fullscreen mode Exit fullscreen mode

Com --on-error continue, o CLI executa todas as iterações, mesmo que algumas falhem.

Opções comuns:

  • continue: executa tudo e reporta todas as falhas.
  • end: comportamento de falha rápida.
  • ignore: ignora erros, útil apenas em casos específicos e controlados.

Mesmo com continue, a execução ainda pode terminar com código diferente de zero se houver falhas, mantendo o pipeline como gate de qualidade.

Depurando variáveis que não foram vinculadas

Um problema comum em testes orientados a dados é a execução “verde” que não testou o que deveria. Isso acontece quando a variável não é substituída e a requisição vai com valor vazio ou com {{variavel}} literal.

Para depurar, rode com --verbose:

apidog run --access-token $APIDOG_ACCESS_TOKEN \
  -t 605067 -e 1629989 \
  -d ./test-data/checkout-cases.csv \
  --verbose \
  -r cli
Enter fullscreen mode Exit fullscreen mode

Verifique o corpo da requisição enviado em cada iteração.

Se aparecer algo como:

{
  "sku": "{{sku}}"
}
Enter fullscreen mode Exit fullscreen mode

ou:

{
  "sku": ""
}
Enter fullscreen mode Exit fullscreen mode

quando o CSV tinha valor, a vinculação falhou.

Causas comuns:

  1. Nome da coluna diferente do nome da variável.

Exemplo: o CSV tem product_sku, mas o cenário usa {{sku}}.

  1. CSV quebrado por vírgula sem aspas.

Exemplo:

   sku,description,expected_status
   DESK-01,mesa grande, branca,200
Enter fullscreen mode Exit fullscreen mode

Corrija para:

   sku,description,expected_status
   DESK-01,"mesa grande, branca",200
Enter fullscreen mode Exit fullscreen mode
  1. Caminho errado na CI.

O arquivo existe localmente, mas não no diretório de trabalho do runner.

Antes de confiar em uma execução verde, valide pelo menos uma execução com --verbose.

Exemplo com GitHub Actions

Abaixo está um workflow que instala o CLI e executa o cenário em 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
Enter fullscreen mode Exit fullscreen mode

Pontos importantes:

  • APIDOG_ACCESS_TOKEN vem de secrets.
  • --on-error continue coleta todas as falhas.
  • if: always() faz upload do relatório mesmo quando os testes falham.
  • Para trocar CSV por JSON, altere apenas o valor de -d.
  • Para usar conjunto de dados salvo, troque o caminho por um ID.

Os mesmos passos funcionam em outros CIs:

  1. Instale Node.js.
  2. Instale apidog-cli.
  3. Exponha o token como variável de ambiente.
  4. Execute apidog run com -d.

Para um guia focado em Actions, veja automação de testes de API no GitHub Actions. Para a lista completa de flags, consulte o guia completo do Apidog CLI.

Fluxo recomendado

Comece pequeno:

  1. Crie um cenário no Apidog.
  2. Use variáveis nas requisições, como {{sku}} e {{quantity}}.
  3. Use variáveis nas asserções, como {{expected_status}}.
  4. Crie um CSV com três linhas:
    • caminho feliz;
    • erro conhecido;
    • caso de limite.
  5. Rode localmente com -d.
  6. Ative --verbose se algo parecer estranho.
  7. Adicione o comando à CI com junit e --on-error continue.

Depois, cresça apenas os dados. Cada bug corrigido pode virar uma nova linha no CSV ou um novo objeto no JSON. O cenário continua pequeno; a cobertura aumenta com a tabela.

Esse é o principal ganho: você mantém um único cenário e expande a cobertura sem duplicar testes.

Se você ainda está comparando abordagens, veja qual ferramenta escolher para testes de API orientados a dados com CSV ou JSON e Apidog CLI vs Newman.

Perguntas Frequentes

A flag -d aceita arquivo e conjunto de dados salvo?

Sim, mas apenas um por execução. Você passa um caminho CSV/JSON local ou um ID de dados de teste salvo no projeto Apidog.

Use arquivo quando quiser versionar os dados com o repositório. Use ID salvo quando a tabela for mantida dentro do Apidog pela equipe.

Preciso informar se o arquivo é CSV ou JSON?

Não. O CLI interpreta o arquivo. A exigência principal é manter os nomes das colunas CSV ou chaves JSON iguais às variáveis usadas no cenário.

O que acontece se eu usar -d e -n juntos?

Com -d, o arquivo define as iterações. Portanto, -n normalmente não é necessário. Use -n principalmente para repetir cenários sem arquivo de dados ou para casos específicos em que você quer repetir a tabela.

Por que minha execução passou sem testar os dados?

Provavelmente alguma variável não foi vinculada. Verifique:

  • nomes das colunas;
  • nomes das variáveis;
  • caminho do arquivo na CI;
  • CSV quebrado por vírgulas sem aspas.

Rode com --verbose e inspecione a requisição enviada.

Como mantenho credenciais fora do arquivo de dados?

Não coloque tokens ou chaves no CSV/JSON. Use:

--global-var "api_key=$RUNTIME_API_KEY"
Enter fullscreen mode Exit fullscreen mode

ou:

--env-var "base_url=https://staging.internal"
Enter fullscreen mode Exit fullscreen mode

Passe esses valores a partir dos secrets da CI.

Posso usar os mesmos dados em staging e produção?

Sim. Mantenha o cenário e o arquivo de dados iguais e altere o ambiente com -e:

apidog run --access-token $APIDOG_ACCESS_TOKEN \
  -t 605067 \
  -e 1629989 \
  -d ./test-data/checkout-cases.csv \
  -r cli
Enter fullscreen mode Exit fullscreen mode

Para outro ambiente, troque apenas o valor de -e.

Conclusão

A flag -d é o ponto central para testes de API orientados a dados com Apidog CLI. Ela permite executar o mesmo cenário com CSV, JSON ou um conjunto de dados salvo no projeto. Combinada com --env-var, --global-var, --on-error continue e reporters como cli e junit, ela transforma um cenário manual em uma execução automatizada e adequada para CI.

Crie o cenário uma vez, coloque os casos em uma tabela e deixe o CLI executar cada linha a cada push. Baixe o Apidog, rode apidog run -d com seu primeiro arquivo de dados e transforme um único cenário em uma suíte orientada a dados.

Top comments (0)