Insomnia é um cliente de API construído pela Kong para enviar requisições e inspecionar respostas. Ele é conhecido por uma interface limpa e sem distrações e suporte para HTTP, REST, GraphQL, gRPC, SOAP e WebSocket em um só lugar. Desenvolvedores o utilizam quando desejam algo mais leve do que uma ferramenta pesada estilo IDE, mas ainda capaz de um trabalho de teste real.
Este guia mostra como testar uma API no Insomnia do começo ao fim. Você criará uma coleção de requisições, enviará e inspecionará uma resposta, configurará ambientes para poder alternar URLs base e tokens, e usará o recurso de suítes de teste para escrever asserções que são executadas automaticamente. Os exemplos usam uma API pública para que você possa acompanhar imediatamente.
Instalar o Insomnia e criar uma requisição
Baixe o Insomnia do site oficial da Kong e instale-o para sua plataforma. No primeiro lançamento, o Insomnia pergunta se você deseja fazer login. Você pode optar por trabalhar localmente sem uma conta, se preferir, e o Insomnia armazena seus dados em sua própria máquina. A sincronização em nuvem é opcional e foi o que mudou na versão 8, que abordaremos a seguir.
O Insomnia organiza o trabalho em coleções e documentos. Clique em Criar no painel e escolha Coleção de Requisições. Dê a ela um nome claro como “Testes de API de Usuário”. Dentro da coleção, clique no botão + e escolha Requisição HTTP.
Uma requisição precisa de um método e uma URL. Escolha GET e insira um endpoint real. O serviço JSONPlaceholder funciona bem para a prática:
GET https://jsonplaceholder.typicode.com/users/1
Clique em Enviar. O painel direito mostra o corpo da resposta, o código de status, o tempo de resposta e o tamanho. O Insomnia formata JSON automaticamente e permite filtrar o corpo com uma consulta JSONPath ou XPath, o que é útil quando uma resposta é grande.
Configurar métodos, parâmetros e autenticação
Para qualquer coisa além de uma leitura simples, você configurará mais na requisição. O Insomnia agrupa esses itens em abas abaixo da barra de URL.
A aba Corpo lida com os payloads das requisições. Para um POST, escolha JSON e insira os dados:
{
"name": "Daniel Okafor",
"email": "daniel.okafor@example.com"
}
O Insomnia define o cabeçalho Content-Type para você quando você escolhe um tipo de corpo. A aba Consulta permite adicionar parâmetros de string de consulta sem editar a URL manualmente, o que mantém uma URL longa legível e permite alternar parâmetros individuais. A aba Cabeçalhos é para qualquer outra coisa que a API espere, como um X-Request-Id personalizado ou um cabeçalho Accept para negociar o formato da resposta.
A aba Autenticação lida com credenciais. O Insomnia suporta uma longa lista de esquemas: Token Portador, Autenticação Básica, Chave de API, OAuth 1.0 e 2.0, AWS IAM, entre outros. Escolha o esquema que sua API usa e preencha os campos. Para uma API protegida por token, escolha Token Portador e cole o token, ou melhor, referencie uma variável de ambiente para que o token não seja codificado. Se você não tem certeza de quais códigos de status esperar de volta, a referência sobre códigos de status HTTP que as APIs REST devem usar é um bom complemento.
Configurar ambientes e variáveis
Ambientes permitem evitar a repetição de valores e facilitam a troca de alvos. No Insomnia, um ambiente é um objeto JSON de variáveis anexado a uma coleção.
Clique no menu suspenso de ambiente próximo ao topo da barra lateral e abra Gerenciar Ambientes. O Ambiente Base contém valores compartilhados. Adicione sub-ambientes para cada alvo:
{
"base_url": "https://jsonplaceholder.typicode.com",
"auth_token": "your-token-here"
}
Crie um segundo sub-ambiente para produção com valores diferentes. Referencie uma variável em qualquer requisição com a sintaxe de template {{ _.base_url }}, de modo que uma URL se torna:
GET {{ _.base_url }}/users/1
Alterne o ambiente ativo no menu suspenso e toda requisição que usar a variável será atualizada. O Insomnia também suporta tags de template, pequenas funções que você pode inserir em um campo para gerar um timestamp, um UUID ou para extrair um valor de uma resposta anterior. Este último permite encadear requisições, por exemplo, capturando um token de uma resposta de login e alimentando-o em requisições posteriores.
A tag de template de resposta merece um olhar mais atento porque é assim que o Insomnia lida com dependências de requisições sem scripts. Você adiciona uma tag que diz “use o corpo da requisição de login, no JSONPath $.token”, e a insere no cabeçalho Authorization de toda requisição protegida. Quando você executa uma requisição protegida, o Insomnia executa a requisição de login primeiro, se necessário, extrai o token e o substitui. A cadeia permanece declarativa, então não há código de acoplamento para manter. Para a ideia mais ampla de agrupar verificações relacionadas, consulte o passo a passo do exemplo de caso de teste de API.
Escrever suítes de teste com asserções
Enviar uma requisição mostra a resposta. Para verificar se a resposta está correta, automaticamente, você usa o recurso de suítes de teste do Insomnia, às vezes exibido como a aba Testes de Unidade em uma coleção.
Abra sua coleção e mude para a visualização Testes. Crie uma suíte de testes e, em seguida, adicione testes individuais dentro dela. Cada teste é um pequeno trecho de JavaScript. O Insomnia usa a biblioteca de asserções Chai e oferece um helper para enviar uma requisição e obter sua resposta. Um teste se parece com isto:
const response = await insomnia.send();
expect(response.status).to.equal(200);
Você pode ser mais específico analisando o corpo e verificando os campos:
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");
Cada teste na suíte mira uma requisição da sua coleção, escolhida em um menu suspenso, para que o teste saiba o que enviar. Clique em Executar Testes e o Insomnia executa cada teste na suíte, mostrando cada um como aprovado ou falhou com o tempo que levou. Esta é a sua verificação de regressão: execute a suíte após uma alteração e você verá imediatamente se a API ainda se comporta.
A forma como você organiza as suítes é importante à medida que o número cresce. Um padrão comum é uma suíte por recurso, então todos os testes de artigo ficam juntos e todos os testes de usuário ficam juntos. Dentro de uma suíte, mantenha cada teste focado em um único comportamento: um teste para o caminho feliz, testes separados para o caso de não encontrado e o caso de erro de validação. Quando um teste falha, seu nome e seu escopo restrito devem dizer o que quebrou sem que você precise ler o código da asserção. Para uma análise mais aprofundada sobre como escrever boas verificações, o guia sobre asserções de API explica o que afirmar e o que pular, e o artigo suítes de teste para automação de testes de API aborda a estruturação de suítes à medida que crescem.
Executar da linha de comando com Inso
Uma GUI é boa para desenvolvimento, mas a automação precisa de algo sem interface gráfica. O Insomnia vem com um companheiro de linha de comando chamado Inso. Após exportar ou sincronizar sua coleção, você executa sua suíte de testes de um terminal:
inso run test "User API tests"
O Inso sai com um código de status diferente de zero se algum teste falhar, que é exatamente o que um pipeline de CI precisa para marcar uma build como quebrada. Você pode integrar isso ao GitHub Actions ou a qualquer outro executor para que seus testes do Insomnia sejam executados a cada push, pegando um endpoint quebrado antes que ele chegue a um colega de equipe ou à produção. O Inso também pode lintar sua especificação de API e gerar relatórios de teste em formatos padrão, o que o torna útil além de apenas executar suítes. O artigo sobre automação de testes de API em CI/CD mostra o padrão geral, que se aplica de forma limpa ao Inso.
A mudança para a nuvem na versão 8 e uma alternativa
O Insomnia 8 migrou para um modelo "cloud-first". Por padrão, ele incentivava os usuários a criar uma conta Kong e armazenar projetos na nuvem. Essa decisão frustrou parte da comunidade, já que as versões anteriores eram totalmente locais e amigáveis para uso offline. Versões posteriores restauraram uma opção mais clara de "somente local" ou "Bloco de rascunhos", mas o episódio levou algumas equipes a procurar alternativas, especialmente em ambientes onde os dados não podem sair do prédio.
Se isso o descreve, Apidog vale a pena ser considerado. É uma plataforma de API completa que abrange design, depuração, mocking, testes e documentação, e importa exportações do Insomnia para que você não precise começar do zero. O Apidog permite que você construa asserções visualmente sem escrever JavaScript, enquanto ainda suporta scripts quando você os deseja. Como a especificação da API, os dados de teste e o servidor mock compartilham um único projeto, seus testes permanecem alinhados com o contrato real em vez de se desviarem. Você pode baixar o Apidog e importar uma coleção do Insomnia para comparar lado a lado. Para uma pesquisa mais ampla, a lista de ferramentas de teste de API online gratuitas abrange várias opções.
O Insomnia ainda é um cliente forte e focado, particularmente para desenvolvedores individuais e pequenas equipes que valorizam sua interface minimalista e sem distrações e o rápido início. A escolha certa depende de como sua equipe trabalha e de quanto do ciclo de vida da API você deseja gerenciar em um só lugar, em vez de espalhar por ferramentas separadas.
Perguntas frequentes
O Insomnia é gratuito para usar?
O Insomnia possui um nível gratuito que cobre o uso individual, incluindo o envio de requisições e a execução de suítes de teste localmente. Planos pagos adicionam colaboração em equipe e limites maiores de sincronização em nuvem. Você pode usar o cliente principal sem pagar, e as versões recentes permitem que você trabalhe totalmente localmente se preferir não usar a sincronização em nuvem.
Quais protocolos o Insomnia suporta?
O Insomnia lida com HTTP, REST, GraphQL, gRPC, SOAP e WebSocket. A configuração da requisição difere por protocolo, mas a inspeção da resposta e, para requisições baseadas em HTTP, as asserções da suíte de testes funcionam consistentemente em todos eles.
Como faço para escrever asserções no Insomnia?
Use o recurso de suítes de teste. Abra a visualização Testes em uma coleção, crie uma suíte e adicione testes. Cada teste é um código JavaScript que chama insomnia.send() para executar uma requisição, e então usa asserções estilo Chai expect no status, cabeçalhos ou corpo analisado. Execute a suíte completa com o botão Executar Testes.
O que mudou no Insomnia 8?
O Insomnia 8 mudou para um padrão de prioridade à nuvem, solicitando aos usuários que fizessem login em uma conta Kong e sincronizassem projetos para a nuvem. Alguns usuários não gostaram do fluxo de conta obrigatório e do afastamento de um aplicativo puramente local. Atualizações posteriores adicionaram opções mais claras de uso local, mas a mudança levou algumas equipes a avaliar alternativas.
Posso executar testes do Insomnia em um pipeline de CI?
Sim. Use o Inso, o companheiro de linha de comando. Exporte ou sincronize sua coleção e, em seguida, execute inso run test "<nome da suíte>" em seu pipeline. O Inso retorna um código de saída diferente de zero em caso de falha, para que o CI possa falhar a build automaticamente quando um teste de API quebrar.