DEV Community

Cover image for Melhores Alternativas ao Insomnia CLI (inso) para Testes de API em CI
Lucas
Lucas

Posted on • Originally published at apidog.com

Melhores Alternativas ao Insomnia CLI (inso) para Testes de API em CI

Se você executa testes do Insomnia em CI, provavelmente usa o inso: o CLI do Insomnia para rodar suítes de teste, executar coleções e lintar especificações OpenAPI com Spectral. Ele funciona bem para muitos times, mas começa a gerar atrito quando testes, ambientes e specs ficam acoplados ao diretório .insomnia ou ao banco de dados do aplicativo.

Experimente o Apidog hoje

Este guia mostra o que o inso faz, onde ele costuma limitar fluxos de CI/CD e quais alternativas usar dependendo do seu caso: execução de coleções, testes como código, OpenAPI linting, relatórios ou automação orientada a dados.

O que o inso faz

O inso lê dados de um diretório .insomnia no repositório, geralmente criado pelo Git Sync do Insomnia, ou do diretório local do app Insomnia. Em vez de apontar diretamente para arquivos, você referencia specs, coleções e suítes por nome:

inso run test "My API Test Suite" --env "Staging"
inso run collection "Smoke Tests" --env "Staging"
inso lint spec "Petstore Design Doc"
inso export spec "Petstore Design Doc" --output openapi.yaml
Enter fullscreen mode Exit fullscreen mode

A instalação é simples:

brew install inso
docker pull kong/inso:latest
Enter fullscreen mode Exit fullscreen mode

O ponto forte real do inso é o comando de linting:

inso lint spec "Petstore Design Doc"
Enter fullscreen mode Exit fullscreen mode

Ele usa o Spectral, da Stoplight, para validar estilo e qualidade de especificações OpenAPI. Se seu uso principal é inso lint spec, talvez você não precise substituir o inso; talvez precise apenas separar linting de execução de testes.

Onde o inso costuma gerar atrito

Antes de migrar, identifique qual problema você quer resolver:

  • Fonte de verdade dentro do Insomnia: testes e specs vivem em .insomnia ou no banco de dados do app.
  • Referências por nome: renomear uma suíte na GUI pode quebrar comandos de CI.
  • Dependência do ecossistema Insomnia: algumas equipes preferem arquivos versionáveis ou ferramentas sem conta de fornecedor.
  • Linting e execução juntos: se você só precisa rodar testes, talvez o Spectral seja irrelevante; se só precisa lintar OpenAPI, um executor de coleções não resolve.

A escolha da alternativa depende do comando do inso que você usa hoje.

Alternativas em resumo

Ferramenta Tipo Fonte Dados externos Relatórios Código aberto Melhor para
Apidog CLI Executor de plataforma completa Projeto Apidog / importação OpenAPI Sim, CSV/JSON com -d CLI, HTML, JSON Não, com camada gratuita Design, mock, docs e testes em uma plataforma
Newman Executor Postman Collection JSON do Postman Sim, CSV/JSON com -d CLI, HTML, JSON Sim Times com coleções Postman existentes
Hoppscotch CLI Executor OSS JSON Hoppscotch / ID da nuvem Sim CLI, JUnit XML Sim Pipelines OSS e auto-hospedáveis
Step CI Testes declarativos YAML/JSON Limitado CLI, JUnit Sim Testes versionados como código
Hurl Executor HTTP em texto simples Arquivos .hurl Via variáveis CLI, JUnit, HTML Sim Smoke tests e asserções HTTP leves

1. Apidog CLI: quando você quer uma plataforma única

Apidog é uma plataforma para design, depuração, testes, mocking e documentação de APIs. O Apidog CLI leva a execução de testes para o terminal e para o CI/CD.

Use quando você quer substituir o fluxo de testes do inso por uma ferramenta que também se integra ao ciclo de vida da API.

Exemplos básicos:

apidog run --access-token <token> -t <scenario-id> -e <env-id>
apidog run -t <scenario-id> -d ./users.csv -r html,cli
apidog run -t <scenario-id> --upload-report
Enter fullscreen mode Exit fullscreen mode

Casos comuns:

# Rodar um cenário em um ambiente específico
apidog run \
  --access-token "$APIDOG_TOKEN" \
  -t "$SCENARIO_ID" \
  -e "$ENV_ID"

# Rodar testes orientados a dados
apidog run \
  -t "$SCENARIO_ID" \
  -d ./test-data/users.csv \
  -r cli,html,json

# Gerar relatório e enviar para a nuvem
apidog run \
  -t "$SCENARIO_ID" \
  --upload-report
Enter fullscreen mode Exit fullscreen mode

O Apidog CLI também permite trabalhar com recursos de API a partir do terminal, como importação de OpenAPI, endpoints, esquemas, ambientes, branches e solicitações de merge. Isso ajuda quando você quer aproximar o fluxo de API de um processo versionado e revisável.

Limitação importante: o Apidog CLI não substitui o inso lint spec. Ele valida specs na importação, mas não oferece um linter OpenAPI autônomo como o Spectral. Se o seu pipeline depende de regras Spectral, mantenha o Spectral diretamente ou use outro CLI dedicado para linting.

Use Apidog CLI se você precisa de:

  • execução de cenários no CI;
  • testes orientados a dados com CSV/JSON;
  • relatórios CLI, HTML e JSON;
  • upload de relatórios;
  • uma plataforma única para design, mock, docs e testes.

Evite se seu objetivo principal é:

  • substituir apenas o inso lint spec;
  • manter uma stack 100% open source.

Links úteis:

2. Newman: quando você já usa Postman

Newman é o executor CLI open source do Postman. Se sua equipe já mantém coleções no Postman, ele é a migração mais direta para rodar testes no CI.

Exemplo:

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

Exemplo em pipeline:

npm install -g newman newman-reporter-htmlextra

newman run ./collections/api.postman_collection.json \
  -e ./envs/staging.postman_environment.json \
  -d ./data/users.csv \
  -r cli,htmlextra,json
Enter fullscreen mode Exit fullscreen mode

Use Newman se você precisa de:

  • executar coleções Postman existentes;
  • manter compatibilidade com scripts e environments do Postman;
  • usar um ecossistema maduro de reporters;
  • uma opção open source para CI.

Limitações:

  • não faz linting OpenAPI;
  • depende do formato de coleção do Postman;
  • a modelagem continua centrada no Postman, não em arquivos OpenAPI simples.

Para comparar com uma opção de plataforma completa, veja Apidog CLI vs Newman.

3. Hoppscotch CLI: quando você quer OSS e auto-hospedável

Hoppscotch é um ecossistema open source para APIs, com web, desktop, CLI e opção auto-hospedável. O CLI @hoppscotch/cli executa coleções em pipelines.

Instalação:

npm i -g @hoppscotch/cli
Enter fullscreen mode Exit fullscreen mode

A CLI atual requer Node.js v22 ou superior. Usuários de Node 20 devem permanecer na versão v0.26.0 da CLI.

Exemplos:

hopp test ./collection.json -e ./env.json -d 100
hopp test <collection-id> --token <pat> --server https://hoppscotch.example.com
hopp test ./collection.json --reporter-junit ./report.xml
Enter fullscreen mode Exit fullscreen mode

O comando hopp test executa as requisições da coleção, roda scripts de pré-requisição e testes, valida respostas e retorna código diferente de zero quando alguma asserção falha.

Flags úteis:

# Ambiente
-e ./env.json

# Servidor auto-hospedado
--server https://hoppscotch.example.com

# Token de acesso pessoal
--token <pat>

# Relatório JUnit
--reporter-junit ./report.xml

# Dados de iteração
--iteration-data ./data.csv
Enter fullscreen mode Exit fullscreen mode

Use Hoppscotch CLI se você precisa de:

  • ferramenta open source;
  • opção auto-hospedável;
  • execução de coleções em CI;
  • saída JUnit para integração com pipelines.

Limitações:

  • ecossistema menor que o Newman;
  • requisito de Node v22+ pode exigir ajuste na imagem de CI;
  • não substitui linting OpenAPI com Spectral.

Leituras relacionadas:

4. Step CI: quando você quer testes como código

Step CI usa arquivos YAML ou JSON declarativos. Em vez de criar coleções em uma GUI, você escreve os testes diretamente no repositório.

Exemplo:

version: "1.1"
name: Status check
tests:
  health:
    steps:
      - name: GET health
        http:
          url: https://api.example.com/health
          method: GET
          check:
            status: 200
Enter fullscreen mode Exit fullscreen mode

Esse modelo resolve um problema comum do inso: referências frágeis por nome. No Step CI, o arquivo versionado é a definição do teste.

Exemplo de organização:

tests/
  api/
    health.yml
    users.yml
    billing.yml
Enter fullscreen mode Exit fullscreen mode

Você pode revisar alterações em pull requests, assim como qualquer outro código.

Use Step CI se você precisa de:

  • testes declarativos em YAML/JSON;
  • versionamento direto no repositório;
  • revisão por pull request;
  • saída JUnit para CI.

Limitações:

  • menos interativo para depuração ad-hoc;
  • suporte a dados é mais limitado que Newman ou Apidog;
  • você escreve mais configuração manualmente.

Step CI é uma boa opção quando a prioridade é remover dependência de GUI e manter testes próximos ao código da aplicação.

5. Hurl: quando você quer HTTP em texto simples

Hurl é a alternativa mais minimalista. Você escreve requisições HTTP e asserções em arquivos .hurl.

Exemplo:

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

Execute:

hurl --test users.hurl
Enter fullscreen mode Exit fullscreen mode

Exemplo com variáveis:

hurl --test users.hurl \
  --variable base_url=https://api.example.com \
  --variable token="$API_TOKEN"
Enter fullscreen mode Exit fullscreen mode

Exemplo de arquivo:

GET {{base_url}}/users/1
Authorization: Bearer {{token}}

HTTP 200
[Asserts]
jsonpath "$.id" exists
jsonpath "$.email" matches /^[^@]+@[^@]+$/
Enter fullscreen mode Exit fullscreen mode

Hurl também suporta encadeamento de requisições, captura de variáveis e relatórios JUnit/HTML.

Use Hurl se você precisa de:

  • smoke tests rápidos;
  • testes versionáveis em texto puro;
  • baixa dependência em CI;
  • validações HTTP simples.

Limitações:

  • cenários complexos podem ficar verbosos;
  • não há GUI de coleção;
  • não faz linting OpenAPI.

Como escolher na prática

Escolha pela tarefa que você precisa automatizar.

Se você usa inso run test

Considere:

  • Apidog CLI, se quer cenários, ambientes, relatórios e dados externos em uma plataforma completa.
  • Newman, se seus testes já estão no Postman.
  • Hoppscotch CLI, se você quer um fluxo open source e auto-hospedável.
  • Step CI, se quer testes declarativos no repositório.
  • Hurl, se os testes são simples e baseados em HTTP puro.

Se você usa inso run collection

Considere:

  • Newman, para coleções Postman;
  • Hoppscotch CLI, para coleções Hoppscotch;
  • Apidog CLI, se você quer conectar execução de coleções a design, mock, docs e relatórios.

Se você usa inso lint spec

Não substitua por um executor de coleções esperando o mesmo resultado.

O inso lint spec é forte porque usa Spectral. Para manter esse comportamento, use o Spectral diretamente ou outro CLI dedicado de linting OpenAPI.

Exemplo com Spectral:

npm install -g @stoplight/spectral-cli

spectral lint openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Você também pode combinar ferramentas:

# Lint da especificação
spectral lint openapi.yaml

# Execução de testes
apidog run -t "$SCENARIO_ID" -e "$ENV_ID"
Enter fullscreen mode Exit fullscreen mode

ou:

spectral lint openapi.yaml
newman run collection.json -e staging.json
Enter fullscreen mode Exit fullscreen mode

Exemplo de estratégia de migração

Uma migração segura do inso pode seguir este fluxo:

  1. Liste os comandos usados hoje no CI: 
grep -R "inso " .github workflows Jenkinsfile .gitlab-ci.yml
Enter fullscreen mode Exit fullscreen mode
  1. Classifique cada uso: 
inso lint spec       -> manter Spectral ou CLI de linting
inso run test        -> migrar para executor de testes
inso run collection  -> migrar para executor de coleções
inso export spec     -> substituir por fluxo OpenAPI adequado
Enter fullscreen mode Exit fullscreen mode

  1. Migre primeiro comandos que não alteram dados.

  2. Rode a ferramenta nova em paralelo por alguns pipelines.

  3. Só depois remova o inso.

Recomendação final

Se você precisa de uma substituição ampla para automação de testes e ciclo de vida de API, comece pelo Apidog CLI. Ele cobre execução, ambientes, dados externos e relatórios em uma plataforma integrada.

Se você só quer executar coleções Postman, use Newman.

Se a prioridade é open source e auto-hospedagem, avalie Hoppscotch CLI.

Se você quer testes versionados como arquivos declarativos, use Step CI.

Se quer algo mínimo para smoke tests HTTP, use Hurl.

E se seu pipeline depende principalmente de inso lint spec, não trate executores de API como substitutos diretos. Mantenha o Spectral ou um CLI dedicado de linting OpenAPI.

Para migrações relacionadas ao ecossistema Insomnia, veja também:

Top comments (0)