DEV Community

Cover image for Como Migrar do Hoppscotch CLI para o Apidog CLI
Lucas
Lucas

Posted on • Originally published at apidog.com

Como Migrar do Hoppscotch CLI para o Apidog CLI

A CLI do Hoppscotch é uma forma simples e gratuita de executar coleções de API no terminal ou em pipelines de CI. O comando hopp test lê uma coleção, executa cada requisição, roda scripts de pré-requisição e de teste, e retorna código de saída diferente de zero quando uma asserção falha.

Experimente o Apidog hoje

O ponto é que um runner resolve apenas parte do ciclo de vida de APIs. Quando design, mock, documentação e testes vivem em ferramentas diferentes, manter tudo sincronizado vira trabalho manual. É nesse cenário que faz sentido migrar da CLI do Hoppscotch para a CLI do Apidog: o Apidog centraliza design, depuração, mocking, documentação e testes em uma única plataforma, enquanto a CLI executa os testes no CI.

Quando migrar — e quando não migrar

Se você só precisa executar uma coleção em CI, de graça, com opção de auto-hospedagem, a CLI do Hoppscotch continua sendo uma boa escolha. Ela é open source, rápida e distribuída como pacote npm via @hoppscotch/cli.

Considere migrar quando você precisar:

  • manter design, mocks, documentação e testes a partir de uma única fonte de verdade;
  • evitar sincronização manual entre ferramentas diferentes;
  • gerar relatórios mais úteis para humanos e máquinas;
  • usar ambientes, endpoints, schemas e cenários como parte do fluxo de projeto;
  • integrar execuções de teste com histórico compartilhado na nuvem.

A migração não deve ser motivada apenas pelo comando de execução. O ganho real está no ecossistema ao redor da execução.

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

No Hoppscotch, tudo é exportável em JSON.

No app web ou desktop:

  1. Abra a coleção usada no CI.
  2. Use o menu da coleção.
  3. Clique em Exportar.
  4. Salve o arquivo .json.
  5. Abra o painel de ambientes.
  6. Exporte o ambiente usado com -e.

Se você já roda a CLI com arquivos locais, provavelmente já tem algo assim no repositório:

npm i -g @hoppscotch/cli

hopp test ./collections/checkout-api.json \
  -e ./environments/staging.json
Enter fullscreen mode Exit fullscreen mode

Neste exemplo:

  • ./collections/checkout-api.json é a coleção;
  • ./environments/staging.json é o ambiente.

Guarde os dois arquivos. Eles são a base da migração.

Também vale revisar a versão do Node.js. A CLI atual do Hoppscotch requer Node.js v22 ou superior; equipes fixadas no Node 20 precisam permanecer na CLI v0.26.0. Ao migrar para o Apidog, você pode remover essa restrição específica do seu pipeline.

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

Crie ou abra um projeto no Apidog.

Depois:

  1. Acesse o projeto.
  2. Importe a coleção exportada do Hoppscotch.
  3. Se você tiver uma especificação OpenAPI, importe-a também.
  4. Revise os endpoints importados.
  5. Recrie o ambiente com os mesmos nomes de variáveis.

Por exemplo, se o ambiente staging.json tiver:

{
  "base_url": "https://api.example.com",
  "api_token": "token"
}
Enter fullscreen mode Exit fullscreen mode

crie as mesmas variáveis no ambiente do Apidog:

base_url
api_token
Enter fullscreen mode Exit fullscreen mode

Manter os nomes evita alterações desnecessárias em URLs, headers, scripts e asserções.

A partir daqui, os endpoints importados passam a fazer parte do projeto: você pode associar schemas, gerar mocks e publicar documentação a partir das mesmas definições usadas nos testes.

Leituras úteis:

Passo 3: Mapeie hopp test para apidog run

O modelo é parecido: você executa uma sequência de requisições, roda scripts e valida asserções.

Antes:

hopp test ./collections/checkout-api.json \
  -e ./environments/staging.json
Enter fullscreen mode Exit fullscreen mode

Depois:

apidog run \
  --access-token "$APIDOG_TOKEN" \
  -e "Staging"
Enter fullscreen mode Exit fullscreen mode

A diferença principal é a fonte de verdade:

  • no Hoppscotch, você normalmente executa um arquivo exportado;
  • no Apidog, você executa recursos do projeto, como cenários de teste ou coleções.

O contrato importante para CI permanece: se uma asserção falhar, a CLI retorna código de saída diferente de zero. Isso mantém a lógica de falha do pipeline.

Para autenticação, use login ou token de acesso. Em CI, o padrão mais seguro é usar variável de ambiente:

export APIDOG_TOKEN="seu_token"

apidog run \
  --access-token "$APIDOG_TOKEN" \
  -e "Staging"
Enter fullscreen mode Exit fullscreen mode

Veja também o guia de autenticação da CLI do Apidog.

Passo 4: Migre testes orientados por dados

Se você usa CSV ou JSON para executar o mesmo fluxo com múltiplas entradas, a migração é direta.

No Hoppscotch:

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

No Apidog:

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

Um CSV como este:

order_id,customer_id,total
1001,501,99.90
1002,502,149.50
Enter fullscreen mode Exit fullscreen mode

pode alimentar variáveis usadas nas requisições e asserções.

Exemplo de uso conceitual dentro de uma requisição:

{
  "orderId": "{{order_id}}",
  "customerId": "{{customer_id}}",
  "total": "{{total}}"
}
Enter fullscreen mode Exit fullscreen mode

A linha de cabeçalho do CSV define os nomes das variáveis. Esse padrão é semelhante ao usado no Hoppscotch, então normalmente você não precisa reescrever a lógica dos testes.

Referência: guia de testes orientados por dados no Apidog.

Passo 5: Converta os relatórios

No Hoppscotch, você pode gerar JUnit XML:

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

No Apidog, você pode gerar relatórios CLI, HTML ou JSON, além de enviar o resultado para a nuvem:

apidog run \
  --access-token "$APIDOG_TOKEN" \
  -e "Staging" \
  -r html \
  --upload-report
Enter fullscreen mode Exit fullscreen mode

Use HTML quando o relatório for lido por pessoas:

apidog run \
  --access-token "$APIDOG_TOKEN" \
  -e "Staging" \
  -r html
Enter fullscreen mode Exit fullscreen mode

Use JSON quando outro sistema for consumir o resultado:

apidog run \
  --access-token "$APIDOG_TOKEN" \
  -e "Staging" \
  -r json
Enter fullscreen mode Exit fullscreen mode

Se seu CI depende especificamente de JUnit XML, planeje essa troca com cuidado. O Apidog usa relatórios CLI/HTML/JSON e histórico em nuvem, em vez de uma flag JUnit equivalente.

Leia mais no guia de relatórios de teste da CLI do Apidog.

Antes e depois: mapeamento de comandos

Tarefa CLI do Hoppscotch CLI do Apidog
Instalar npm i -g @hoppscotch/cli Conforme o guia de instalação
Executar uma coleção hopp test collection.json apidog run
Selecionar ambiente -e env.json -e "Staging"
Token de autenticação --token <pat> login / --access-token
Alvo auto-hospedado / nuvem --server <url> projeto + token de acesso
Entradas orientadas por dados --iteration-data orders.csv -d orders.csv
Repetir execuções --iteration-count 50 conjunto de dados de iteração
Adicionar atraso entre requisições -d <ms> configurações por cenário
Relatório JUnit --reporter-junit results.xml -r json, CLI ou HTML
Histórico de execução na nuvem não integrado --upload-report

Atenção à flag -d:

  • no Hoppscotch, -d representa atraso em milissegundos;
  • no Apidog, -d representa o dataset usado em testes orientados por dados.

É uma diferença pequena, mas comum em migrações.

Passo 6: Integre com GitHub Actions

Não substitua o job antigo às cegas. Primeiro rode os dois em paralelo:

  1. mantenha o job atual do Hoppscotch;
  2. adicione um novo job com Apidog;
  3. compare os resultados;
  4. remova o job antigo apenas depois de algumas execuções verdes.

Exemplo com GitHub Actions:

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
Enter fullscreen mode Exit fullscreen mode

Boas práticas:

  • salve APIDOG_TOKEN como secret do repositório;
  • não coloque tokens diretamente no YAML;
  • mantenha o dataset versionado se ele fizer parte do contrato de teste;
  • falhe o job quando a CLI retornar código diferente de zero;
  • remova o passo antigo apenas depois de validar a equivalência.

Mais referências:

Checklist de migração

Use esta lista para evitar regressões:

[ ] Exportei a coleção do Hoppscotch
[ ] Exportei o ambiente usado no CI
[ ] Criei ou abri um projeto no Apidog
[ ] Importei a coleção
[ ] Recriei as variáveis de ambiente com os mesmos nomes
[ ] Configurei o token de acesso como secret no CI
[ ] Rodei apidog run localmente
[ ] Rodei Apidog e Hoppscotch em paralelo no CI
[ ] Validei datasets CSV/JSON
[ ] Ajustei formato de relatório
[ ] Removi o job antigo do Hoppscotch
Enter fullscreen mode Exit fullscreen mode

Uma palavra justa sobre o Hoppscotch

Nada disso invalida o Hoppscotch. A CLI é rápida, gratuita, open source e pode ser uma excelente escolha para quem precisa apenas de um runner enxuto.

A razão para migrar é escopo. Quando design, mocks, documentação e testes precisam compartilhar a mesma definição de API, uma plataforma integrada pode reduzir trabalho manual e inconsistência entre ferramentas.

Para comparar com mais detalhe:

Top comments (0)