Como Migrar de inso (Insomnia CLI) para Apidog CLI

Se você executa testes de API a partir do inso, o CLI do Insomnia da Kong, e tem pensado em uma mudança, este guia o acompanhará do início ao fim. Você verá como exportar suas especificações e suítes de teste do Insomnia, trazê-las para o Apidog e reescrever seus comandos inso run como comandos apidog run. Há uma tabela de comandos antes/depois para que você possa mapear seus scripts de CI existentes linha por linha.

Por que as equipes migram do inso para o Apidog CLI

inso é uma ferramenta sólida. Ela traz a execução de requisições, linting Spectral e testes de unidade para o terminal, e lê de um diretório .insomnia criado pelo Git Sync do Insomnia. Se esse fluxo de trabalho se encaixa em você, não há regra que diga que você precisa sair.

O atrito geralmente começa com o aplicativo Insomnia, não com o CLI. Duas coisas impulsionam a maioria das buscas por migração:

• A conta na nuvem obrigatória. O Insomnia 8, lançado em 2023, introduziu uma conta de login/nuvem obrigatória que pegou muitas equipes desprevenidas. Muitos desenvolvedores queriam um cliente local-first e, em vez disso, encontraram um muro de login.
• Perda de dados e dor na migração. Alguns usuários sofreram incidentes de perda de dados e migração durante essa transição. Se você já passou por um, já sabe o custo. Se você está se recuperando de um agora, estes tutoriais ajudarão: recuperando e exportando dados do Insomnia e o guia mais aprofundado recuperação e migração de perda de dados do Insomnia 8.

A outra razão é a consolidação. Com o inso, o CLI é uma peça de uma pilha: Insomnia para requisições, Spectral para linting, ferramentas separadas para mocks e docs. O Apidog integra design, depuração, teste, mock e documentação em uma única plataforma, e o CLI executa a parte de teste dessa plataforma. Menos partes móveis, uma única fonte de verdade.

Se você quiser o contexto mais amplo antes de se comprometer, Apidog vs Insomnia e escolhendo entre Insomnia e Apidog apresentam as vantagens e desvantagens para os aplicativos completos, não para os CLIs.

Antes de começar: o que migra e o que não migra

Defina as expectativas desde o início para que nada o surpreenda durante a migração.

A nota sincera: inso lint spec executa o Spectral, o linter OpenAPI da Stoplight, e isso é um verdadeiro ponto forte. O Apidog CLI não oferece um linter de especificação autônomo, guia de estilo, comando de split, join ou bundle. O Apidog valida sua especificação ao importá-la, então problemas estruturais surgem no momento da importação, mas se seu pipeline depende de conjuntos de regras Spectral personalizados como um portão, mantenha o Spectral em seu CI junto com o Apidog. Não espere por apidog lint. Ele não está lá, e fingir o contrário só o prejudicaria mais tarde.

Passo 1: exporte suas especificações e testes do Insomnia

inso pode escrever seu documento de design diretamente em um arquivo. A especificação é referenciada pelo nome, o mesmo nome que você vê no aplicativo Insomnia:

# Export an OpenAPI design document to a YAML file
inso export spec "My API Design" --output my-api.yaml

Se o inso não conseguir encontrar seus dados, aponte-o para a fonte correta. Por padrão, ele lê de um diretório .insomnia no diretório de trabalho ou no diretório de dados do aplicativo Insomnia. Sobrescreva com --workingDir ou --src:

inso export spec "My API Design" --workingDir ./design --output my-api.yaml

Para coleções de requisições e qualquer coisa que o inso não exportar de forma limpa, use o próprio aplicativo Insomnia: abra o aplicativo, selecione seu workspace e use Exportar para produzir um arquivo OpenAPI ou Insomnia v4. Mantenha tanto o documento de design quanto a exportação da coleção. Você os importará separadamente.

Se você estiver em meio a uma recuperação e o aplicativo não cooperar, o passo a passo de exportação e recuperação aborda como obter dados quando o Git Sync ou a conta na nuvem estiverem causando problemas.

Passo 2: importar para o Apidog

Abra o Apidog, crie um projeto e importe o YAML ou JSON que você acabou de exportar. O Apidog lê OpenAPI nativamente, então seus endpoints, esquemas e dados de exemplo chegam como recursos estruturados que você pode editar, simular e testar.

Você também pode importar via CLI como parte de uma configuração automatizada, o que é útil ao scriptar uma mudança para toda a equipe em vez de clicar na interface do usuário. O Apidog importa OpenAPI e gerencia endpoints, esquemas, ambientes, branches e merge requests como código a partir do terminal, autenticando via login ou um token de acesso. Se você está configurando o CLI pela primeira vez, o guia de instalação do Apidog CLI e o guia completo do CLI cobrem a configuração e o fluxo de autenticação.

Na importação, o Apidog valida a especificação. Se seu OpenAPI tiver problemas estruturais, você descobrirá agora, e não em tempo de execução. Este é o análogo mais próximo de inso lint spec, com uma diferença que vale a pena repetir: é validação, não um conjunto de regras Spectral configurável.

Passo 3: mapeie seus comandos (a parte pela qual você veio)

Esta é a parte central da migração. Veja como os comandos inso se traduzem para apidog run.

Algumas notas sobre o mapeamento:

• Ambientes. inso usa --env "name". O Apidog usa -e (--env). Ambos selecionam qual URL base e variáveis de ambiente aplicar. Recrie seus ambientes Insomnia como ambientes Apidog primeiro, depois referencie-os por nome ou ID.
• Suítes de teste se tornam cenários de teste. Onde inso run test executa uma suíte de teste de unidade do Insomnia, o Apidog executa cenários de teste. O conceito se mapeia de forma limpa: requisições ordenadas com asserções. Você reconstruirá a suíte uma vez no Apidog, e então ela será executada a cada apidog run.
• inso script era uma indireção. Se você envolvia comandos por trás de scripts nomeados, basta chamar apidog run diretamente em sua etapa de CI, ou envolvê-lo em seu próprio script npm/make.

Para uma comparação mais aprofundada comando por comando, Apidog CLI vs inso (Insomnia CLI) detalha flag por flag. Se você veio do Newman ou do Postman CLI em uma vida passada, Apidog CLI vs Newman e Apidog CLI vs Postman CLI também cobrem esses casos.

Passo 4: mova seus geradores de relatórios

O inso depende de sua saída de teste e relatórios estilo JUnit para CI. O Apidog oferece geradores de relatórios nos formatos CLI, HTML e JSON, para que sua build possa imprimir resultados legíveis por humanos no console e emitir um artefato legível por máquina ao mesmo tempo:

# Run a scenario and emit both a CLI summary and an HTML report
apidog run --test-scenario "Smoke Suite" -e staging -r cli,html

Escolha json quando uma ferramenta downstream precisar analisar os resultados, html quando um humano revisar a build, e cli para o feed ao vivo do console. Você também pode enviar os resultados para os relatórios de teste na nuvem do Apidog com --upload-report para que toda a equipe veja a execução sem precisar vasculhar os logs de CI. O guia de relatórios de teste cobre os formatos em detalhes.

Passo 5: traga seus testes orientados a dados

Se suas suítes do Insomnia faziam loop sobre dados, o Apidog oferece suporte nativo a testes orientados a dados. Forneça um conjunto de dados CSV ou JSON com -d e o cenário será executado uma vez por linha:

apidog run --test-scenario "Login Matrix" -e staging -d ./users.csv -r cli,json

Este é um ponto em que o Apidog tende a parecer menos "remendado" do que encadear dados externos através do inso. O guia de testes orientados a dados aborda os formatos de conjunto de dados e a vinculação de variáveis.

Passo 6: integre-o ao CI

O passo final é trocar o comando em seu pipeline. Sua etapa antiga do GitHub Actions ou GitLab provavelmente se parecia com isto:

# Before: inso in CI
inso run test "Smoke Suite" --env "CI" --reporter junit

O equivalente no Apidog:

# After: Apidog CLI in CI
apidog run --test-scenario "Smoke Suite" -e ci -r cli,json --upload-report

Autentique o executor com um token de acesso armazenado como um segredo de CI, da mesma forma que você lidaria com qualquer etapa credenciada. O guia de pipeline CI/CD e o guia do GitHub Actions contêm arquivos de workflow prontos para copiar e colar. Para detalhes específicos de token e login, consulte autenticação do Apidog CLI.

Se você manteve o Spectral para linting (recomendado se você tinha regras personalizadas), seu pipeline agora tem dois portões: o Spectral faz o lint da especificação, o Apidog executa os testes. Esse é um estado final perfeitamente razoável, e é honesto sobre o que cada ferramenta faz de melhor.

Mantendo o Spectral no ciclo

Para ser claro sobre a única coisa que não é portada: se o linting faz parte do seu contrato, não o abandone. O Spectral é de código aberto e funciona bem fora do Insomnia. Um CI híbrido típico se parece com isto:

# Lint with Spectral (kept from your inso setup)
npx @stoplight/spectral-cli lint my-api.yaml

# Test with Apidog CLI
apidog run --test-scenario "Smoke Suite" -e ci -r cli,json

Você não perde nada no lado do linting e ganha a plataforma integrada de design-mock-teste-documentação do Apidog em todo o resto. Essa é a troca precisa, e é uma boa para a maioria das equipes.

inso vs Apidog CLI: um panorama

FAQ

Minha especificação Insomnia OpenAPI será importada para o Apidog sem edições? Geralmente sim. O Apidog lê OpenAPI nativamente e valida na importação. Se a validação sinalizar algo, é tipicamente um problema estrutural real na especificação, e corrigi-lo uma vez beneficia todas as ferramentas downstream.

O Apidog CLI possui um comando lint como o inso lint spec? Não. O Apidog valida as especificações na importação, mas não há um linter CLI autônomo ou comando de guia de estilo. Se você depende de conjuntos de regras Spectral personalizados, mantenha o Spectral em seu pipeline ao lado de apidog run. Para uma comparação lado a lado, veja Apidog CLI vs Redocly CLI, já que o Redocly CLI inclui um linter.

Posso executar o Apidog CLI em CI da mesma forma que executava o inso? Sim. Troque o comando, autentique com um token de acesso de um segredo de CI e escolha seus geradores de relatórios. O guia de pipeline CI/CD tem exemplos completos de workflow.

O que acontece com minhas suítes de teste de unidade do Insomnia? Você as reconstrói como cenários de teste do Apidog. A estrutura é transferida diretamente: requisições ordenadas mais asserções. É uma reconstrução única, após a qual elas são executadas a cada apidog run.

Estou migrando do Insomnia devido a um incidente de perda de dados. Por onde começo? Recupere seus dados primeiro usando o guia de recuperação e exportação, depois siga o Passo 2 acima para importar a exportação limpa para o Apidog.

Concluindo

Migrar do inso para o Apidog CLI é principalmente um trabalho de tradução: exporte suas especificações e suítes, importe-as para o Apidog, reescreva inso run test e inso run collection como apidog run, troque --env por -e, e aponte seus geradores de relatórios para a saída CLI/HTML/JSON do Apidog. Mantenha o Spectral se você fizer lint, porque o Apidog valida na importação, mas não substitui um conjunto de regras personalizadas.

A recompensa é uma plataforma única em vez de uma pilha que você precisa continuar juntando. Pronto para experimentar? Baixe o Apidog e execute seu primeiro apidog run contra a especificação que você acabou de exportar.