Como Migrar do Hoppscotch CLI para o Apidog CLI

A CLI do Hoppscotch é uma maneira limpa e gratuita de executar coleções de API em um terminal ou pipeline de CI. O comando hopp test lê um arquivo de coleção, executa cada requisição, roda seus scripts de pré-requisição e de teste, e retorna um valor diferente de zero quando uma asserção falha. Para muitas equipes, isso é o suficiente.

Mas um executor (runner) é apenas uma parte do trabalho com APIs. Em algum momento, você estará gerenciando uma ferramenta de design separada, um servidor de mock, um site de documentação e o executor, e nenhum deles compartilha uma fonte única de verdade. É geralmente quando as equipes começam a procurar como migrar da CLI do Hoppscotch para a CLI do Apidog. O Apidog integra design, depuração, mocking, documentação e testes em uma única plataforma, e sua CLI executa a parte de testes em CI. O executor mantém o mesmo formato que você já conhece. O que muda é tudo ao redor dele.

botão

Quando você deve (e não deve) migrar

Seja honesto consigo mesmo primeiro. Se seu único requisito é "executar uma coleção em CI gratuitamente, auto-hospedado se eu quiser", a CLI do Hoppscotch é uma ferramenta genuinamente boa. É de código aberto, o executor é rápido, e @hoppscotch/cli é entregue como um pacote npm normal. Não há vergonha em permanecer.

Migre quando um destes começar a causar problemas:

• Você projeta APIs em uma ferramenta, faz mock em outra e escreve documentação em uma terceira, e mantê-los sincronizados é um trabalho manual.
• Você deseja que execuções de teste, servidores de mock e documentação publicada compartilhem uma única definição de projeto.
• Você precisa de relatórios mais ricos (relatórios HTML para stakeholders, JSON para máquinas) além de histórico de execução hospedado na nuvem.
• Você quer tratar endpoints, schemas, ambientes e branches como código que a CLI pode gerenciar, não apenas executar.

Se essa lista descreve sua semana, a plataforma é a razão para mudar, não o executor. Veja como fazer isso de forma limpa.

Passo 1: Exporte sua coleção e ambiente Hoppscotch

Tudo no Hoppscotch é JSON, o que torna a exportação indolor.

No aplicativo Hoppscotch (web ou desktop), abra a coleção que você executa em CI. Use o menu da coleção e escolha Exportar, o que lhe dará um arquivo .json. Faça o mesmo para o ambiente que você passa com -e: abra o painel de ambientes e exporte-o para seu próprio arquivo JSON.

Se você já executa a CLI contra arquivos locais, você já os tem em disco. Um passo típico de CI do Hoppscotch se parece com isto:

npm i -g @hoppscotch/cli
hopp test ./collections/checkout-api.json -e ./environments/staging.json

Mantenha ambos os arquivos. checkout-api.json é sua coleção, staging.json é seu ambiente. Esses dois são o payload completo que você está transferindo.

Uma observação sobre as versões do Node enquanto estamos aqui. A CLI atual do Hoppscotch requer Node.js v22 ou mais recente; equipes fixadas no Node 20 permanecem na CLI v0.26.0. A CLI do Apidog não o vincula a isso, então uma migração é também uma chance de remover uma restrição de versão.

Passo 2: Importe a coleção para o Apidog

Crie um projeto no Apidog (ou abra um existente), e então importe sua exportação do Hoppscotch. O Apidog lê formatos de coleção comuns e OpenAPI, então você pode trazer a coleção diretamente. Se sua API também tiver uma especificação OpenAPI, importe-a também. O Apidog valida a especificação na importação, então problemas estruturais surgem imediatamente em vez de falharem silenciosamente no meio da execução.

Mapeie seu ambiente Hoppscotch para um ambiente Apidog com os mesmos nomes de variáveis. Se staging.json definiu base_url e api_token, recrie essas chaves no ambiente Apidog correspondente. Manter os nomes idênticos significa que seus scripts de teste e URLs de requisição não precisarão de edições.

Este é também o momento em que o lado da plataforma começa a valer a pena. Os endpoints que você importou agora são artefatos de design. Você pode anexar schemas, gerar um servidor de mock a partir deles e publicar documentação das mesmas definições que você usa para testar. O guia completo da CLI do Apidog cobre toda a superfície assim que você estiver configurado, e o guia de instalação lida com o binário do executor.

Passo 3: Mapeie hopp test para apidog run

O modelo mental se transfere diretamente. Onde o Hoppscotch executa um arquivo de coleção, o Apidog executa um cenário de teste ou coleção do seu projeto. Mesmo trabalho, diferente fonte de verdade.

# Hoppscotch
hopp test ./collections/checkout-api.json -e ./environments/staging.json

# Apidog
apidog run --access-token $APIDOG_TOKEN -e "Staging"

Ambos os comandos executam cada requisição em ordem, rodam scripts de pré-requisição, executam suas asserções de teste e retornam um código de saída diferente de zero se algo falhar. Esse contrato de código de saída é a parte da qual o CI depende, e ele é preservado, então a lógica de aprovação/falha do seu pipeline não muda.

A autenticação difere de uma maneira útil. O Hoppscotch passa um token de acesso pessoal com --token para coleções na nuvem ou auto-hospedadas. O Apidog autentica com um login ou um token de acesso, o que permite à CLI alcançar os recursos do seu projeto em vez de um único arquivo exportado. Se você já teve problemas com o manuseio de tokens antes, o guia de autenticação apresenta as opções.

Passo 4: Converter execuções orientadas por dados

Ambas as ferramentas fazem testes orientados por dados, então a iteração sobre um CSV de entradas sobrevive à mudança.

No Hoppscotch, você passa dados de iteração e uma contagem:

hopp test ./collections/checkout-api.json \
  -e ./environments/staging.json \
  --iteration-count 50 \
  --iteration-data ./data/orders.csv

No Apidog, o executor recebe um conjunto de dados com -d. Ele aceita CSV e JSON, então o mesmo orders.csv funciona após a importação:

apidog run --access-token $APIDOG_TOKEN \
  -e "Staging" \
  -d ./data/orders.csv

Sua linha de cabeçalho CSV se torna os nomes das variáveis que você referencia dentro das requisições e asserções, o mesmo padrão que o Hoppscotch usa, então os corpos dos testes não precisam ser reescritos. Se você é novo no estilo Apidog disso, o guia de testes orientados por dados mostra como vincular colunas a variáveis e executar uma linha por iteração.

Passo 5: Converta seus relatórios

A geração de relatórios é onde a plataforma se destaca, e a conversão é direta.

O Hoppscotch emite um arquivo XML JUnit com uma flag, que a maioria dos sistemas de CI analisa para painéis de teste:

hopp test ./collections/checkout-api.json \
  -e ./environments/staging.json \
  --reporter-junit ./reports/results.xml

O Apidog oferece uma escolha de geradores de relatórios: um resumo legível da CLI, um relatório HTML que você pode entregar aos stakeholders, e um relatório JSON para máquinas. Você também pode enviar os resultados para a nuvem para um histórico de execução compartilhável.

# Relatório HTML legível por humanos
apidog run --access-token $APIDOG_TOKEN \
  -e "Staging" \
  -r html \
  --upload-report

Se o seu painel de CI espera especificamente JUnit XML, mantenha essa integração em mente durante a troca, já que o Apidog se baseia em seus relatórios CLI/HTML/JSON mais relatórios em nuvem em vez de uma flag JUnit. Para a maioria das equipes, o relatório HTML mais o histórico em nuvem carregado é um avanço em relação a um arquivo XML bruto que ninguém abre. O guia de relatórios de teste detalha cada formato e quando usá-lo.

Antes e depois: mapeamento de comandos

Observe a flag -d naquela tabela. No Hoppscotch, -d é o atraso em milissegundos; no Apidog, -d é o conjunto de dados para execuções orientadas por dados. Mesma letra, trabalho diferente. É a única pegadinha que atrapalha as pessoas durante a transição de Hopp para Apidog.

Passo 6: Integrar com GitHub Actions

Último passo, e o objetivo é uma construção (build) verde do começo ao fim. Configure o job do Apidog junto com o antigo do Hoppscotch primeiro, confirme que ele passa, e então exclua o passo antigo. Nunca faça uma transição às cegas.

name: Testes de API
on: [push, pull_request]

jobs:
  apidog-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Instalar Apidog CLI
        run: npm install -g apidog-cli

      - name: Executar testes de API
        env:
          APIDOG_TOKEN: ${{ secrets.APIDOG_TOKEN }}
        run: |
          apidog run \
            --access-token "$APIDOG_TOKEN" \
            -e "Staging" \
            -d ./data/orders.csv \
            -r html \
            --upload-report

Armazene seu token de acesso como um segredo do repositório, nunca no YAML. Como a CLI retorna um código de saída diferente de zero em qualquer asserção falha, o job falha exatamente quando seus testes falham, que é o comportamento que sua equipe já confia do Hoppscotch. O guia de GitHub Actions cobre o cache e as execuções matriciais, e o guia de pipeline de CI/CD mais amplo lida com GitLab, Jenkins e o restante.

Assim que o job do Apidog estiver verde por algumas execuções, remova o passo do Hoppscotch e sua instalação npm. Migração concluída, a construção nunca ficou vermelha.

Uma palavra justa sobre o Hoppscotch

Nada disso é uma crítica ao Hoppscotch. Seu executor CLI é rápido e gratuito, o projeto é totalmente de código aberto, e você pode auto-hospedar toda a stack. Se você quer um executor enxuto e nada mais, ele merece seu lugar. A razão para mudar é o escopo: quando design, mock, docs e teste precisam compartilhar uma única definição, um executor autônomo não pode oferecer isso, e uma plataforma integrada pode. Compare os dois executores diretamente em Apidog CLI vs Hoppscotch CLI, e se você está avaliando os aplicativos em vez das CLIs, Postman vs Hoppscotch e o resumo de alternativas ao Hoppscotch adicionam contexto.