DEV Community

Cover image for Ferramenta de Teste de API Headless: Execute Testes sem GUI na CI
Lucas
Lucas

Posted on • Originally published at apidog.com

Ferramenta de Teste de API Headless: Execute Testes sem GUI na CI

Uma ferramenta de teste de API headless executa testes pela linha de comando, sem interface gráfica, para que as mesmas verificações rodem localmente e em pipelines de CI a cada push. Se você já criou um teste em uma GUI e depois precisou executá-lo em um servidor de build, é esse o problema que ferramentas headless resolvem. Neste guia, você verá o que torna uma ferramenta “headless”, como executar testes com a CLI do Apidog e quando considerar alternativas como Newman e Hurl.

Experimente o Apidog hoje

O que “headless” significa em testes de API

“Headless” significa executar sem interface gráfica. Em testes de API, isso normalmente quer dizer que a ferramenta:

  • roda como um comando de terminal;
  • não depende de tela, login manual ou cliques;
  • lê testes de arquivos, coleções, suítes ou IDs de projeto;
  • retorna código de saída diferente de zero quando uma asserção falha;
  • gera relatórios para humanos e para máquinas, como CLI, HTML, JSON ou JUnit XML.

Esse comportamento é essencial em CI/CD. Uma GUI mostra a uma pessoa o que passou ou falhou. Uma ferramenta headless informa isso ao pipeline, permitindo bloquear merges, impedir deploys ruins e detectar regressões antes dos usuários.

Para contexto sobre como encaixar isso no fluxo de entrega, veja as melhores práticas de CI/CD para teste de API.

Por que tirar testes de API da GUI

Clientes visuais são úteis para explorar endpoints, ajustar headers e validar respostas manualmente. O problema aparece quando você precisa repetir o mesmo teste dezenas ou centenas de vezes.

Você não quer depender de alguém executando quarenta requisições manualmente a cada commit. Também não quer uma pessoa no caminho de um deploy automatizado às 2 da manhã.

Executores headless resolvem isso com comandos reproduzíveis:

api-test-runner run ./tests
Enter fullscreen mode Exit fullscreen mode

O mesmo comando pode rodar:

  • no notebook de um desenvolvedor;
  • na máquina de outro membro do time;
  • em um pipeline do GitHub Actions, GitLab CI, Jenkins ou similar.

Com entradas orientadas a dados, um único cenário pode cobrir vários casos usando CSV ou JSON. Isso ajuda a tratar sua API como um produto: testável, versionada e confiável.

Apidog CLI: executando testes de API sem GUI

A CLI do Apidog é o executor headless do Apidog. Você cria, depura e organiza cenários no aplicativo e depois executa esses mesmos testes no terminal com:

apidog run
Enter fullscreen mode Exit fullscreen mode

O comando pode executar cenários de teste, pastas, suítes ou arquivos exportados. Ele imprime o resultado, gera relatórios e retorna um código de saída que o pipeline pode usar para aprovar ou falhar o build.

Apidog CLI

1. Instale a CLI 

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

2. Execute um cenário ou suíte

Um exemplo mínimo de execução:

apidog run https://api.apidog.com/...
Enter fullscreen mode Exit fullscreen mode

Em CI, normalmente você também define ambiente, dados de iteração e formatos de relatório.

apidog run https://api.apidog.com/... \
  -e <environment-id> \
  -d ./data/users.csv \
  -r cli,html,junit
Enter fullscreen mode Exit fullscreen mode

3. Use dados de teste com CSV ou JSON

Para rodar o mesmo cenário várias vezes com entradas diferentes, use:

-d, --iteration-data <path>
Enter fullscreen mode Exit fullscreen mode

Exemplo:

apidog run https://api.apidog.com/... \
  -d ./data/users.csv
Enter fullscreen mode Exit fullscreen mode

Você também pode limitar a quantidade de iterações:

apidog run https://api.apidog.com/... \
  -d ./data/users.csv \
  -n 10
Enter fullscreen mode Exit fullscreen mode

Esse fluxo permite transformar um único cenário em vários casos de teste. A mecânica completa está no guia de teste de API orientado a dados com a CLI do Apidog.

4. Gere relatórios para o pipeline

A flag -r, --reporters define os formatos de saída:

apidog run https://api.apidog.com/... \
  -r cli,html,junit
Enter fullscreen mode Exit fullscreen mode

Formatos úteis:

  • cli: saída no terminal;
  • html: relatório visual para revisão;
  • json: pós-processamento personalizado;
  • junit: integração com dashboards de CI.

Por padrão, os relatórios HTML e JUnit são salvos em apidog-reports/, no diretório onde o comando foi executado. Em CI, configure esse diretório como artefato do build.

5. Controle ambientes e variáveis

Use -e para selecionar um ambiente:

apidog run https://api.apidog.com/... \
  -e <environment-id>
Enter fullscreen mode Exit fullscreen mode

Para injetar variáveis em tempo de execução:

apidog run https://api.apidog.com/... \
  --env-var token=$API_TOKEN \
  --global-var baseUrl=https://staging.example.com
Enter fullscreen mode Exit fullscreen mode

Isso evita commitar segredos no repositório.

Para um passo a passo completo, consulte o guia completo da CLI do Apidog, o tutorial de linha de comando para API REST e a referência do comando apidog run.

Exemplo de job em CI

Um job simples pode instalar a CLI, executar os testes e publicar relatórios como artefatos.

name: API tests

on:
  push:
    branches:
      - main
  pull_request:

jobs:
  api-tests:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Install Apidog CLI
        run: npm install -g apidog-cli

      - name: Run API tests
        run: |
          apidog run https://api.apidog.com/... \
            -e ${{ secrets.APIDOG_ENV_ID }} \
            -d ./data/users.csv \
            -r cli,html,junit

      - name: Upload reports
        uses: actions/upload-artifact@v4
        with:
          name: apidog-reports
          path: apidog-reports/
Enter fullscreen mode Exit fullscreen mode

O ponto importante: se uma asserção falhar, o comando deve retornar erro, e o job falha automaticamente.

Headless também pode significar contrato guiando automação

Há outra capacidade sem GUI no ecossistema do Apidog: o servidor MCP do Apidog.

Com ele, um agente de IA ou uma IDE com suporte a IA, como Cursor ou VS Code via Cline, pode ler suas especificações de API diretamente. Assim, o assistente gera código e testes com base no contrato real, em vez de inferir endpoints e payloads.

Esse fluxo é explicado em depuração visual com o cliente Apidog MCP.

Outros executores headless para testes de API

A melhor ferramenta depende de onde seus testes já vivem.

Newman

Newman é o executor de coleções do Postman pela linha de comando.

Use Newman quando:

  • sua equipe já usa Postman;
  • as coleções do Postman são a fonte de verdade;
  • você quer rodar essas coleções em CI sem abrir a GUI.

Exemplo básico:

newman run collection.json \
  -e environment.json \
  -d data.csv \
  -r cli,json,junit
Enter fullscreen mode Exit fullscreen mode

Newman inclui reporters como cli, json, junit, progress e emojitrain. Relatório HTML está disponível via pacote npm separado.

Newman terminal

Hurl

Hurl usa arquivos .hurl em texto simples. Você escreve requisições HTTP e asserções no mesmo arquivo.

Exemplo simplificado:

GET https://api.example.com/users/1
HTTP 200
[Asserts]
jsonpath "$.id" == 1
jsonpath "$.email" exists
Enter fullscreen mode Exit fullscreen mode

Depois execute:

hurl test.hurl
Enter fullscreen mode Exit fullscreen mode

Hurl é uma boa opção quando você prefere testes versionados como texto simples e quer algo pequeno, rápido e fácil de encaixar em scripts.

Hoppscotch CLI

A Hoppscotch CLI, também chamada de hopp, executa coleções e scripts de teste do Hoppscotch em CI.

Ela permite usar coleções e ambientes exportados como JSON ou referenciar IDs com token de acesso. Também suporta dados de iteração CSV e reporter JUnit via --reporter-junit.

É uma escolha natural se sua equipe já usa Hoppscotch. Se você está avaliando alternativas, veja a análise das melhores alternativas ao Hoppscotch CLI.

Comparação rápida

Ferramenta Fonte do teste Entrada orientada a dados Relatórios integrados Melhor quando
Apidog CLI Projeto Apidog, suítes ou arquivo exportado CSV / JSON com -d cli, html, json, junit Você quer design, mock, teste e documentação em um projeto
Newman Coleções do Postman CSV / JSON com -d cli, json, junit, progress; HTML via add-on Coleções do Postman são sua fonte de verdade
Hurl Arquivos .hurl CSV via opções do executor JUnit, TAP, JSON Você prefere testes em texto simples e versionados
Hoppscotch CLI Coleções Hoppscotch por arquivo ou ID CSV com --iteration-data JUnit Sua equipe já usa Hoppscotch

Todos eles são headless: rodam por comando, não dependem de GUI e sinalizam sucesso ou falha com código de saída.

A diferença do Apidog é o fluxo integrado: o mesmo projeto usado na CLI também pode conter contrato, mocks, testes e documentação.

Como escolher

Use a ferramenta que reduz atrito no seu contexto atual:

  • usa Postman? Comece com Newman;
  • prefere testes em texto puro? Avalie Hurl;
  • já usa Hoppscotch? Use Hoppscotch CLI;
  • quer consolidar design, mock, teste e documentação? Use Apidog.

A CLI do Apidog faz sentido quando você não quer manter contrato, documentação, mocks e testes espalhados em ferramentas diferentes. Os cenários executados em modo headless são os mesmos criados visualmente, apoiados pelo mesmo contrato de API.

Você pode baixar o Apidog para criar um cenário uma vez e executá-lo em qualquer lugar.

Perguntas frequentes

Uma ferramenta headless de teste de API é a mesma coisa que uma ferramenta CLI?

Na prática, quase sempre sim.

“Headless” descreve a característica: não precisar de GUI. “CLI” descreve a interface: você opera pela linha de comando.

O que importa para CI/CD é que a ferramenta rode sem supervisão e retorne um status que o pipeline consiga interpretar.

Posso executar testes sem escrever scripts?

Depende da ferramenta.

No Apidog, você pode criar asserções visualmente e executar os mesmos cenários pela CLI. Newman e Hoppscotch CLI executam coleções que podem incluir scripts criados em seus respectivos aplicativos. Hurl exige que você escreva os testes em arquivos de texto.

Se você prefere um fluxo visual primeiro e headless depois, veja o guia completo da CLI do Apidog.

Testes de API headless precisam de backend real?

Nem sempre.

Você pode apontar os testes para:

  • um serviço local;
  • um ambiente de staging;
  • uma URL pública;
  • um servidor de mock.

Executar testes contra mocks em CI ajuda a validar formatos de request e response antes de o backend estar finalizado.

Qual executor headless é melhor para CI/CD?

Não existe um vencedor universal. O melhor executor é aquele que roda os testes que você já tem com o menor esforço de configuração.

Se você está começando do zero ou consolidando ferramentas, a CLI do Apidog cobre design, mock, teste e documentação em um único projeto. Se sua equipe já está presa a um ecossistema, escolha o executor correspondente.

Para mais detalhes, veja as comparações Apidog CLI vs Newman e Apidog CLI vs Postman CLI.

Conclusão

Uma ferramenta headless de teste de API é um executor sem janela: um comando que você pode automatizar, parametrizar com dados e conectar ao CI.

Newman, Hurl e Hoppscotch CLI funcionam bem dentro de seus ecossistemas. A CLI do Apidog faz o mesmo, com a vantagem de manter testes, mocks, contrato e documentação no mesmo projeto.

Baixe o Apidog para criar um cenário uma vez e executá-lo em modo headless em qualquer ambiente.

Top comments (0)