DEV Community

Cover image for Como Usar Insomnia para Testar APIs: Guia Completo
Lucas
Lucas

Posted on • Originally published at apidog.com

Como Usar Insomnia para Testar APIs: Guia Completo

Insomnia é um cliente de API da Kong para enviar requisições e inspecionar respostas. Ele oferece uma interface limpa e suporta HTTP, REST, GraphQL, gRPC, SOAP e WebSocket em um só lugar. É uma boa opção quando você quer testar APIs sem usar uma ferramenta pesada no estilo IDE.

Experimente o Apidog hoje

Neste guia, você vai testar uma API no Insomnia do começo ao fim: criar uma coleção, enviar uma requisição, inspecionar a resposta, configurar ambientes, reutilizar variáveis e escrever suítes de teste com asserções automatizadas. Os exemplos usam uma API pública para que você possa reproduzir os passos imediatamente.

Instalar o Insomnia e criar uma requisição

Baixe o Insomnia pelo site oficial da Kong e instale-o na sua plataforma.

Ao abrir o app pela primeira vez, o Insomnia pode pedir login. Você pode trabalhar localmente sem conta, se preferir. Nesse modo, os dados ficam na sua máquina. A sincronização em nuvem é opcional e ficou mais relevante a partir da versão 8.

O Insomnia organiza o trabalho em coleções e documentos.

Para criar sua primeira requisição:

  1. Clique em Criar.
  2. Escolha Coleção de Requisições.
  3. Nomeie a coleção, por exemplo: Testes de API de Usuário.
  4. Dentro da coleção, clique em +.
  5. Escolha Requisição HTTP.
  6. Selecione o método GET.
  7. Informe a URL: 
GET https://jsonplaceholder.typicode.com/users/1
Enter fullscreen mode Exit fullscreen mode

Clique em Enviar.

No painel de resposta, verifique:

  • código de status;
  • tempo de resposta;
  • tamanho da resposta;
  • corpo retornado;
  • cabeçalhos;
  • formatação automática do JSON.

Para respostas grandes, use filtros com JSONPath ou XPath para encontrar campos específicos.

Configurar métodos, parâmetros e autenticação

Para testar cenários reais, você normalmente precisa configurar corpo, query params, headers e autenticação. O Insomnia organiza esses itens em abas abaixo da barra de URL.

Enviar um corpo JSON

Crie uma requisição POST e selecione Corpo > JSON.

Exemplo:

{
  "name": "Daniel Okafor",
  "email": "daniel.okafor@example.com"
}
Enter fullscreen mode Exit fullscreen mode

Quando você escolhe o tipo de corpo, o Insomnia configura automaticamente o cabeçalho:

Content-Type: application/json
Enter fullscreen mode Exit fullscreen mode

Adicionar query params

Use a aba Consulta para adicionar parâmetros sem editar a URL manualmente.

Exemplo:

page=1
limit=10
sort=name
Enter fullscreen mode Exit fullscreen mode

Isso ajuda a manter URLs longas legíveis e permite ativar ou desativar parâmetros individualmente.

Configurar headers

Use a aba Cabeçalhos para valores esperados pela API, como:

Accept: application/json
X-Request-Id: test-123
Enter fullscreen mode Exit fullscreen mode

Configurar autenticação

Na aba Autenticação, escolha o esquema usado pela API. O Insomnia suporta, entre outros:

  • Token Portador;
  • Autenticação Básica;
  • Chave de API;
  • OAuth 1.0;
  • OAuth 2.0;
  • AWS IAM.

Para uma API protegida por bearer token:

  1. Abra Autenticação.
  2. Escolha Token Portador.
  3. Informe o token ou referencie uma variável de ambiente.

Evite colar tokens diretamente em várias requisições. Prefira variáveis, por exemplo:

{{ _.auth_token }}
Enter fullscreen mode Exit fullscreen mode

Se você está definindo quais respostas sua API deve retornar, a referência sobre códigos de status HTTP que as APIs REST devem usar pode ajudar.

Configurar ambientes e variáveis

Ambientes evitam repetição e facilitam alternar entre local, staging e produção.

No Insomnia, um ambiente é um objeto JSON de variáveis anexado a uma coleção.

Para configurar:

  1. Abra o menu de ambiente no topo da barra lateral.
  2. Clique em Gerenciar Ambientes.
  3. Edite o Ambiente Base para valores compartilhados.
  4. Crie sub-ambientes para cada destino.

Exemplo de ambiente:

{
  "base_url": "https://jsonplaceholder.typicode.com",
  "auth_token": "your-token-here"
}
Enter fullscreen mode Exit fullscreen mode

Agora altere a URL da requisição para usar a variável:

GET {{ _.base_url }}/users/1
Enter fullscreen mode Exit fullscreen mode

Para usar o token em uma requisição protegida:

Authorization: Bearer {{ _.auth_token }}
Enter fullscreen mode Exit fullscreen mode

Ao trocar o ambiente ativo, todas as requisições que usam essas variáveis são atualizadas automaticamente.

Encadear requisições com tags de template

O Insomnia também oferece tags de template, que funcionam como pequenas funções dentro dos campos.

Você pode usá-las para:

  • gerar timestamps;
  • gerar UUIDs;
  • extrair valores de respostas anteriores;
  • reutilizar tokens retornados por uma requisição de login.

Um caso comum é autenticação:

  1. Crie uma requisição de login.
  2. Execute o login e receba uma resposta com token.
  3. Use uma tag de resposta para extrair o valor em $.token.
  4. Injete esse valor no header Authorization de outras requisições.

Conceitualmente, o fluxo fica assim:

POST /login
Enter fullscreen mode Exit fullscreen mode

Resposta:

{
  "token": "abc123"
}
Enter fullscreen mode Exit fullscreen mode

Depois, nas requisições protegidas:

Authorization: Bearer <token extraído da resposta de login>
Enter fullscreen mode Exit fullscreen mode

Com isso, o Insomnia executa a requisição dependente quando necessário, extrai o valor e o reutiliza. A cadeia continua declarativa, sem scripts de acoplamento para manter.

Para estruturar verificações relacionadas, veja também este exemplo de caso de teste de API.

Escrever suítes de teste com asserções

Enviar uma requisição mostra a resposta. Para validar automaticamente se ela está correta, use o recurso de suítes de teste do Insomnia, também exibido como Testes de Unidade em algumas versões.

Para criar uma suíte:

  1. Abra sua coleção.
  2. Vá para a visualização Testes.
  3. Crie uma suíte de testes.
  4. Adicione testes individuais.
  5. Associe cada teste a uma requisição da coleção.

Cada teste é um trecho de JavaScript. O Insomnia usa a biblioteca Chai para asserções e fornece o helper insomnia.send() para executar a requisição.

Exemplo mínimo:

const response = await insomnia.send();

expect(response.status).to.equal(200);
Enter fullscreen mode Exit fullscreen mode

Exemplo validando o corpo da resposta:

const response = await insomnia.send();
const body = JSON.parse(response.data);

expect(response.status).to.equal(200);
expect(body.email).to.equal("daniel.okafor@example.com");
expect(body).to.have.property("id");
Enter fullscreen mode Exit fullscreen mode

Você também pode validar headers:

const response = await insomnia.send();

expect(response.headers["content-type"]).to.include("application/json");
Enter fullscreen mode Exit fullscreen mode

E validar campos aninhados:

const response = await insomnia.send();
const body = JSON.parse(response.data);

expect(body.address).to.have.property("city");
expect(body.company.name).to.be.a("string");
Enter fullscreen mode Exit fullscreen mode

Clique em Executar Testes para rodar a suíte. O Insomnia mostra quais testes passaram, quais falharam e quanto tempo cada um levou.

Use essas suítes como verificação de regressão: depois de alterar um endpoint, execute os testes e confirme se o comportamento esperado continua válido.

Organizar suítes de teste

À medida que o número de testes cresce, a organização passa a importar.

Um padrão prático é criar uma suíte por recurso:

Usuários
Posts
Autenticação
Pagamentos
Relatórios
Enter fullscreen mode Exit fullscreen mode

Dentro de cada suíte, mantenha cada teste focado em um comportamento.

Exemplo para um recurso de usuários:

Usuários
├── deve retornar usuário existente
├── deve retornar 404 para usuário inexistente
├── deve criar usuário com payload válido
├── deve rejeitar email inválido
└── deve bloquear criação sem autenticação
Enter fullscreen mode Exit fullscreen mode

Evite testes grandes demais. Quando um teste falha, o nome deve deixar claro o que quebrou sem exigir leitura completa do código.

Para aprofundar a estratégia de validação, veja o guia sobre asserções de API e o artigo sobre suítes de teste para automação de testes de API.

Executar testes pela linha de comando com Inso

A interface gráfica é útil durante o desenvolvimento, mas automação exige execução sem UI.

O Insomnia oferece o Inso, um companheiro de linha de comando. Depois de exportar ou sincronizar sua coleção, execute uma suíte pelo terminal:

inso run test "User API tests"
Enter fullscreen mode Exit fullscreen mode

Se algum teste falhar, o Inso retorna um código de saída diferente de zero. Isso é exatamente o que um pipeline de CI precisa para falhar uma build automaticamente.

Um fluxo comum em CI fica assim:

npm install -g inso
inso run test "User API tests"
Enter fullscreen mode Exit fullscreen mode

Em um pipeline, o objetivo é:

  1. baixar ou acessar a coleção;
  2. selecionar o ambiente correto;
  3. executar a suíte;
  4. falhar a build se houver erro.

O Inso também pode lintar especificações de API e gerar relatórios de teste em formatos padrão. Para o padrão geral de integração, veja este guia sobre automação de testes de API em CI/CD.

A mudança para a nuvem na versão 8 e uma alternativa

O Insomnia 8 migrou para um modelo mais orientado à nuvem. Por padrão, ele incentivava usuários a criar uma conta Kong e armazenar projetos na nuvem.

Essa mudança frustrou parte da comunidade, principalmente quem usava versões anteriores de forma totalmente local e offline. Versões posteriores restauraram uma opção mais clara de uso somente local ou Bloco de rascunhos, mas o episódio fez algumas equipes avaliarem alternativas, especialmente em ambientes onde dados de API não podem sair da infraestrutura interna.

Se esse é o seu caso, o Apidog pode ser considerado. Ele reúne design, depuração, mocking, testes e documentação de API, além de importar exportações do Insomnia para evitar começar do zero.

No Apidog, você pode criar asserções visualmente sem escrever JavaScript, mas ainda usar scripts quando necessário. Como especificação da API, dados de teste e servidor mock ficam no mesmo projeto, os testes tendem a permanecer alinhados ao contrato da API.

Você pode baixar o Apidog e importar uma coleção do Insomnia para comparar os fluxos lado a lado. Para uma visão mais ampla, a lista de ferramentas de teste de API online gratuitas reúne outras opções.

O Insomnia continua sendo um cliente forte e focado, especialmente para desenvolvedores individuais e pequenas equipes que valorizam uma interface minimalista e rápida. A melhor escolha depende de como sua equipe trabalha e de quanto do ciclo de vida da API você quer centralizar em uma única ferramenta.

Perguntas frequentes

O Insomnia é gratuito para usar?

Sim. O Insomnia possui um nível gratuito para uso individual, incluindo envio de requisições e execução de suítes de teste localmente.

Planos pagos adicionam recursos de colaboração em equipe e limites maiores de sincronização em nuvem. Versões recentes também permitem trabalhar localmente se você preferir não usar sincronização.

Quais protocolos o Insomnia suporta?

O Insomnia suporta:

  • HTTP;
  • REST;
  • GraphQL;
  • gRPC;
  • SOAP;
  • WebSocket.

A configuração da requisição varia conforme o protocolo, mas a inspeção da resposta e, para requisições baseadas em HTTP, as asserções de testes seguem um fluxo semelhante.

Como escrever asserções no Insomnia?

Use suítes de teste.

O fluxo básico é:

  1. Abra a visualização Testes na coleção.
  2. Crie uma suíte.
  3. Adicione um teste.
  4. Associe o teste a uma requisição.
  5. Use insomnia.send() para executar a chamada.
  6. Valide status, headers ou corpo com expect.

Exemplo:

const response = await insomnia.send();
const body = JSON.parse(response.data);

expect(response.status).to.equal(200);
expect(body).to.have.property("id");
Enter fullscreen mode Exit fullscreen mode

O que mudou no Insomnia 8?

O Insomnia 8 adotou um padrão mais orientado à nuvem, solicitando login em uma conta Kong e incentivando sincronização dos projetos.

Alguns usuários não gostaram do fluxo de conta obrigatório e da mudança em relação ao uso puramente local. Atualizações posteriores adicionaram opções mais claras para uso local, mas a mudança levou algumas equipes a considerar alternativas.

Posso executar testes do Insomnia em um pipeline de CI?

Sim. Use o Inso, a ferramenta de linha de comando do Insomnia.

Depois de exportar ou sincronizar sua coleção, execute:

inso run test "<nome da suíte>"
Enter fullscreen mode Exit fullscreen mode

Se algum teste falhar, o Inso retorna um código de saída diferente de zero. Assim, o CI pode falhar a build automaticamente quando um teste de API quebrar.

Top comments (0)