O que é inso? A CLI do Insomnia

Se você já usou o cliente Insomnia API, você tem um local gráfico para enviar requisições, projetar especificações OpenAPI e escrever testes. Mas as ferramentas gráficas param na borda da sua máquina. No momento em que você quer que esses mesmos testes rodem dentro de um pipeline de CI, ou você quer lintar uma especificação em cada pull request, você precisa de algo que viva no terminal. Esse algo é o inso.

Este guia explica o que é o inso, como instalá-lo, os comandos exatos que você usará no dia a dia, como ele encontra suas especificações e coleções, e onde seus limites aparecem. Ao final, você saberá se o inso cli se encaixa no seu fluxo de trabalho e o que procurar caso não se encaixe.

O que é o inso?

inso é o companheiro de linha de comando para o Insomnia, o cliente API de código aberto agora mantido pela Kong. Ele pega três das coisas que o Insomnia faz em sua interface de usuário e as torna programáveis: executar testes, executar coleções de requisições e lintar especificações de API. Isso o torna a ponte entre o Insomnia em sua área de trabalho e as verificações automatizadas que você deseja em CI/CD.

A versão curta de “o que é o inso”: é como você executa seu trabalho no Insomnia sem abrir o Insomnia. Você o aponta para um documento de design ou uma coleção por nome, e ele executa contra os mesmos dados que seu aplicativo já conhece.

Instalando o inso cli

Você tem alguns caminhos documentados. Escolha aquele que se alinha com a sua forma de entrega.

Homebrew é o mais simples no macOS e Linux:

brew install inso

Docker é a escolha mais limpa para runners de CI, onde você não quer gerenciar um conjunto de ferramentas local:

docker pull kong/inso:latest

Você também pode fazer um download direto. A Kong publica arquivos zip para Windows, Linux e macOS no site de documentação do inso CLI, o que é útil quando você quer uma versão fixada em um artefato de build.

Historicamente, o inso também era distribuído no npm como insomnia-inso. Essa rota ainda existe, mas os caminhos documentados e recomendados agora são Homebrew, Docker e os downloads diretos. Se você está configurando algo novo, prefira esses.

Confirme a resolução da instalação:

inso --version

Os comandos principais do inso

O inso tem uma superfície pequena e focada. Aqui estão os comandos que você realmente usará, com exemplos reais.

inso run test

Execute uma suíte de testes unitários que você criou no Insomnia, contra um ambiente nomeado:

inso run test "Payments API tests" --env "Staging"

A suíte e o ambiente são ambos referenciados por nome, exatamente como aparecem em seus dados do Insomnia. O comando inso run test sai com um código diferente de zero se alguma asserção falhar, o que o torna utilizável como um portão de CI.

inso run collection

Execute cada requisição em uma coleção em sequência, novamente contra um ambiente nomeado:

inso run collection "Checkout flow" --env "Staging"

Este é o equivalente mais próximo de “executar a pasta inteira” na UI. É útil para testes de fumaça onde você quer confirmar que uma sequência de endpoints responde conforme o esperado.

inso lint spec

Valide um documento de design OpenAPI:

inso lint spec "Orders API"

Por baixo dos panos, o inso lint spec usa o Spectral, o linter de OpenAPI e JSON de código aberto da Stoplight. Essa é uma força genuína que vale a pena destacar claramente: você obtém linting de especificação real, baseado em regras, com um conjunto de regras maduro, e não uma verificação superficial de sintaxe. Se sua equipe se preocupa com a aplicação de guias de estilo em especificações, este comando é a razão pela qual muitas pessoas mantêm o inso por perto.

inso export spec

Extraia um documento de design para um arquivo em disco:

inso export spec "Orders API" --output orders.yaml

Útil quando você quer alimentar a especificação para outro gerador, fazer um commit de um snapshot ou entregá-la a uma ferramenta que espera um arquivo YAML simples.

inso script

Execute um script nomeado definido em seus dados do Insomnia, passando um ambiente por id:

inso script deploy-smoke --env env_9f2a

Este é o mecanismo de escape para encadear seus próprios passos personalizados.

Como o inso encontra suas especificações e coleções

Esta é a parte que confunde as pessoas, então vale a pena ser preciso. O inso não armazena nada por si só. Ele lê de um de dois lugares:

1. Um diretório .insomnia em seu diretório de trabalho. É isso que o Git Sync do Insomnia produz, então quando você faz commit do seu projeto API em um repositório, o inso pode lê-lo diretamente do checkout. Este é o padrão que você deseja para CI.
2. O diretório de dados do aplicativo Insomnia, se o aplicativo estiver instalado na máquina. Isso é conveniente localmente, mas inútil em um runner de CI limpo que nunca teve o aplicativo.

Você pode sobrescrever a fonte explicitamente:

inso lint spec "Orders API" --workingDir ./api-project
# or point at an exact source
inso run test "Payments API tests" --src ./api-project/.insomnia

O modelo mental chave: o inso referencia tudo por nome (ou id), e esses nomes são resolvidos contra a fonte de dados que ele encontrou. Se um nome não estiver presente no diretório .insomnia ou nos dados do aplicativo, o inso não poderá executá-lo. Não há conceito de apontar o inso para um arquivo OpenAPI solto e dizer “teste isso”, a menos que esse arquivo viva dentro de uma estrutura de projeto do Insomnia.

Um exemplo mínimo de CI

Aqui está um trabalho do GitHub Actions que linta uma especificação e executa uma suíte de testes em cada push, usando o diretório .insomnia sincronizado com Git e commitado no repositório:

name: API checks
on: [push]

jobs:
  inso:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install inso
        run: |
          curl -sSL https://github.com/Kong/insomnia/releases/latest/download/inso-linux-x64.zip -o inso.zip
          unzip inso.zip && sudo mv inso /usr/local/bin/
      - name: Lint the spec
        run: inso lint spec "Orders API" --workingDir .
      - name: Run the test suite
        run: inso run test "Payments API tests" --env "CI" --workingDir .

Como ambos os comandos saem com um código diferente de zero em caso de falha, uma especificação quebrada ou uma asserção falha faz com que o trabalho falhe. Esse é o objetivo principal de mover essas verificações para fora da GUI.

Limitações honestas

O inso é bom no que faz, mas tem limitações reais.

Ele está vinculado às fontes de dados do Insomnia. Suas especificações, coleções e suítes precisam viver em um projeto do Insomnia, expostas via Git Sync ou o aplicativo instalado. Se sua equipe não usa o Insomnia como fonte da verdade, o inso não tem nada para operar.

Tudo é referenciado por nome. Isso é legível, mas é frágil. Renomeie uma suíte na UI e um trabalho de CI que codifica o nome antigo falhará silenciosamente até a próxima execução. Os nomes também precisam ser únicos o suficiente para serem resolvidos de forma limpa.

O escopo é restrito por design. O inso executa testes, executa coleções, linta especificações, exporta e executa scripts. Não é uma plataforma de design-mock-documento-teste. Para qualquer coisa além desses verbos, você está de volta à GUI ou usando outras ferramentas.

inso vs a alternativa integrada

O inso é um forte companheiro de terminal quando o Insomnia já é seu cliente. A desvantagem é que você está juntando pedaços: Insomnia para design e depuração, inso para CI, regras do Spectral para linting e ferramentas separadas para mocks e docs.

Apidog adota a postura oposta. Ele reúne design, mock, documentação e testes em uma única plataforma, e seu Apidog CLI executa seus cenários de teste e coleções da mesma fonte da verdade, com testes orientados a dados, múltiplos formatos de relatório e recurso-e-branch-como-código. Sendo justo aqui: o Apidog CLI não entrega um linter de especificação autônomo como o inso faz com o Spectral, então se a aplicação de guias de estilo no estilo Spectral é sua prioridade, o inso tem uma vantagem real ali. Onde o Apidog se destaca é na integração. Você não está unindo cinco ferramentas diferentes.

Se você quiser comparar os dois lado a lado, veja Apidog CLI vs inso (Insomnia CLI), ou leia o contexto mais aprofundado em o que é inso (Insomnia CLI). Se você decidiu que o inso não é a ferramenta certa, o resumo das melhores alternativas ao inso e o guia de migração do inso para o Apidog CLI detalham a mudança passo a passo. Para um contexto mais amplo sobre os próprios clientes GUI, Apidog vs Insomnia e como usar o Insomnia para testar uma API são bons pontos de partida.

Você pode baixar o Apidog gratuitamente se quiser ver a abordagem integrada lado a lado com sua configuração do inso.