DEV Community

Cover image for O que é inso? A CLI do Insomnia
Lucas
Lucas

Posted on • Originally published at apidog.com

O que é inso? A CLI do Insomnia

Se você já usa o Insomnia para enviar requisições, criar especificações OpenAPI e escrever testes, o próximo passo é levar esse fluxo para o terminal. O inso é a CLI do Insomnia: ele permite executar testes, coleções e lint de especificações em pipelines de CI/CD sem abrir a interface gráfica.

Experimente o Apidog hoje

Neste guia, você verá como instalar o inso, quais comandos usar no dia a dia, como ele encontra projetos do Insomnia e quais limitações considerar antes de colocá-lo no seu fluxo de CI.

O que é o inso?

inso é a ferramenta de linha de comando do Insomnia, cliente API open source mantido pela Kong. Ele expõe no terminal três capacidades principais da interface gráfica:

  • executar suítes de testes;
  • executar coleções de requisições;
  • lintar especificações OpenAPI.

Isso torna o inso útil quando você quer transformar verificações manuais feitas no Insomnia em etapas automatizadas de CI/CD.

Imagem do inso

Em termos práticos: o inso executa, no terminal, recursos que você já configurou dentro de um projeto do Insomnia.

Instalando o inso CLI

Escolha o método de instalação de acordo com o ambiente onde a CLI será usada.

macOS ou Linux com Homebrew 

brew install inso
Enter fullscreen mode Exit fullscreen mode

Docker

Para runners de CI, Docker costuma ser a opção mais limpa:

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

Download direto

A Kong também publica builds para Windows, Linux e macOS na documentação oficial do inso CLI. Essa opção é útil quando você precisa fixar uma versão específica no pipeline.

Historicamente, o pacote também existia no npm como insomnia-inso, mas, para novas configurações, prefira Homebrew, Docker ou download direto.

Depois da instalação, valide se o binário está disponível:

inso --version
Enter fullscreen mode Exit fullscreen mode

Comandos principais do inso

A CLI tem uma superfície pequena. Na prática, estes são os comandos que você mais usará.

Executar testes com inso run test

Use inso run test para executar uma suíte criada no Insomnia.

inso run test "Payments API tests" --env "Staging"
Enter fullscreen mode Exit fullscreen mode

Onde:

  • "Payments API tests" é o nome da suíte no Insomnia;
  • --env "Staging" define o ambiente usado na execução.

Se alguma asserção falhar, o comando retorna código diferente de zero. Isso permite usá-lo como etapa bloqueante em CI.

Exemplo em script:

#!/usr/bin/env bash
set -e

inso run test "Payments API tests" --env "Staging"
Enter fullscreen mode Exit fullscreen mode

Executar coleções com inso run collection

Para executar todas as requisições de uma coleção em sequência:

inso run collection "Checkout flow" --env "Staging"
Enter fullscreen mode Exit fullscreen mode

Esse comando é útil para smoke tests, por exemplo:

  • verificar se endpoints críticos respondem;
  • validar um fluxo básico de checkout;
  • testar dependências externas em staging.

Lintar especificações com inso lint spec

Para validar uma especificação OpenAPI:

inso lint spec "Orders API"
Enter fullscreen mode Exit fullscreen mode

O inso lint spec usa o Spectral, linter open source para OpenAPI e JSON.

Isso significa que o comando não faz apenas uma verificação superficial de sintaxe. Ele aplica regras de linting, o que ajuda a manter consistência em especificações versionadas.

Use este comando em pull requests quando sua equipe quiser bloquear alterações que quebrem padrões de API.

Exportar especificações com inso export spec

Para exportar uma especificação do Insomnia para um arquivo local:

inso export spec "Orders API" --output orders.yaml
Enter fullscreen mode Exit fullscreen mode

Esse fluxo é útil quando você precisa:

  • gerar um snapshot da especificação;
  • passar o arquivo para outro gerador;
  • publicar o YAML em outro processo;
  • versionar uma saída específica da spec.

Executar scripts com inso script

Para executar um script definido nos dados do Insomnia:

inso script deploy-smoke --env env_9f2a
Enter fullscreen mode Exit fullscreen mode

Esse comando serve como ponto de extensão para fluxos personalizados.

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

O inso não mantém uma base própria de dados. Ele lê informações de uma destas fontes:

  1. Um diretório .insomnia no diretório atual.
  2. O diretório de dados do aplicativo Insomnia instalado na máquina.

Para CI, o caminho recomendado é usar Git Sync no Insomnia e commitar o diretório .insomnia no repositório.

Exemplo de estrutura:

repo/
├── .insomnia/
├── src/
└── package.json
Enter fullscreen mode Exit fullscreen mode

Depois, execute os comandos apontando para o diretório do projeto:

inso lint spec "Orders API" --workingDir .
Enter fullscreen mode Exit fullscreen mode

Ou informe a origem explicitamente:

inso run test "Payments API tests" --src ./.insomnia
Enter fullscreen mode Exit fullscreen mode

O ponto importante: o inso resolve suítes, coleções, ambientes e specs por nome ou ID dentro dos dados do Insomnia.

Se o nome não existir no .insomnia ou nos dados locais do app, o comando não terá o que executar.

Exemplo mínimo com GitHub Actions

Abaixo está um workflow que:

  1. faz checkout do repositório;
  2. instala o inso;
  3. linta a especificação;
  4. executa uma suíte de testes. 
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 .
Enter fullscreen mode Exit fullscreen mode

Como inso lint spec e inso run test retornam erro quando falham, o job também falha automaticamente. Esse é o principal benefício de mover validações do Insomnia para CI.

Limitações do inso

O inso funciona bem quando o Insomnia já é a fonte da verdade da sua equipe. Mas há limitações importantes.

Ele depende dos dados do Insomnia

Suas especificações, coleções e suítes precisam estar em um projeto do Insomnia.

Na prática, isso significa que você precisa de uma destas opções:

  • diretório .insomnia versionado no repositório;
  • aplicativo Insomnia instalado e configurado na máquina.

Em runners limpos de CI, a segunda opção geralmente não é viável.

Os recursos são referenciados por nome

Comandos como este dependem do nome exato da suíte:

inso run test "Payments API tests" --env "CI"
Enter fullscreen mode Exit fullscreen mode

Se alguém renomear a suíte no Insomnia, o pipeline pode quebrar na próxima execução.

Para reduzir risco:

  • padronize nomes;
  • evite duplicidade;
  • documente quais suítes são usadas em CI;
  • prefira IDs quando fizer sentido no seu fluxo.

O escopo é restrito

O inso executa testes, coleções, lint de especificações, exportações e scripts. Ele não tenta ser uma plataforma completa de design, mock, documentação e testes.

Para recursos além desses comandos, você provavelmente continuará usando a GUI do Insomnia ou outras ferramentas.

inso vs uma alternativa integrada

O inso é uma boa escolha quando sua equipe já usa Insomnia e precisa automatizar testes ou lint em CI.

A desvantagem é que o fluxo pode ficar fragmentado:

  • Insomnia para design e depuração;
  • inso para CI;
  • Spectral para regras de lint;
  • outras ferramentas para mocks;
  • outras ferramentas para documentação.

Imagem comparativa

O Apidog segue outra abordagem: reúne design, mock, documentação e testes em uma única plataforma. O Apidog CLI executa cenários de teste e coleções a partir da mesma fonte da verdade, com suporte a testes orientados a dados, múltiplos formatos de relatório e uso de recurso e branch como código.

A comparação justa é esta:

  • se você precisa de lint autônomo de especificação no estilo Spectral, o inso tem vantagem;
  • se você quer reduzir a quantidade de ferramentas no fluxo de API, o Apidog oferece uma experiência mais integrada.

Para comparar com mais detalhes, veja:

Você também pode baixar o Apidog gratuitamente para testar a abordagem integrada lado a lado com seu fluxo atual com inso.

Top comments (0)