DEV Community

Cover image for O Que É Hoppscotch CLI?
Lucas
Lucas

Posted on • Originally published at apidog.com

O Que É Hoppscotch CLI?

Hoppscotch é um ecossistema de API open-source com aplicativo web, aplicativo desktop, CLI e backend auto-hospedável. Ele costuma ser descrito como uma alternativa aberta ao Postman e ao Insomnia. O Hoppscotch CLI é a parte que executa, pelo terminal, as coleções criadas nesse ecossistema — exatamente o que você precisa para rodar testes de API em CI/CD.

Experimente o Apidog hoje

Neste guia, você verá o que é o Hoppscotch CLI, como instalá-lo, como usar o comando hopp test e como conectá-lo a um pipeline real. Se você estiver comparando executores de coleção, veja também as melhores alternativas ao Hoppscotch CLI e o comparativo Apidog CLI vs Hoppscotch CLI.

O que é o Hoppscotch CLI

O Hoppscotch CLI é distribuído como o pacote npm @hoppscotch/cli.

Na prática, ele faz três coisas:

  1. Lê uma coleção Hoppscotch.
  2. Executa as requisições dessa coleção.
  3. Avalia os scripts de teste e retorna um código de sucesso ou falha para o CI.

Hoppscotch CLI

Ele é um executor de coleções, assim como o Newman para Postman ou o inso para Insomnia.

O CLI não projeta APIs, não gera mocks e não cria documentação. O foco é executar requisições e validar asserções.

Como o Hoppscotch é open-source, você também pode auto-hospedar a pilha inteira e apontar o CLI para sua própria instância. Isso é útil para equipes que não querem manter dados de requisições em uma nuvem de fornecedor. A contrapartida é que a operação da hospedagem fica com você.

Instalando o Hoppscotch CLI

Instale o pacote globalmente via npm:

npm i -g @hoppscotch/cli
Enter fullscreen mode Exit fullscreen mode

Verifique a versão do Node.js antes de usar em CI:

node --version
hopp --version
Enter fullscreen mode Exit fullscreen mode

As versões atuais do CLI exigem Node.js v22 ou mais recente. Se o seu ambiente ainda usa Node 20, você pode permanecer no CLI v0.26.0, mas as versões mais novas assumem Node v22+.

Em pipelines, fixe explicitamente a versão do Node para evitar falhas de instalação ou execução.

Executando uma coleção com hopp test

O comando principal é hopp test.

Para executar uma coleção local:

hopp test ./my-collection.json
Enter fullscreen mode Exit fullscreen mode

Para passar um arquivo de ambiente:

hopp test ./my-collection.json -e ./staging.env.json
Enter fullscreen mode Exit fullscreen mode

Para adicionar um atraso entre requisições:

hopp test ./my-collection.json -e ./staging.env.json -d 500
Enter fullscreen mode Exit fullscreen mode

Onde:

  • -e ou --env define o arquivo de ambiente.
  • -d ou --delay define o atraso em milissegundos entre requisições.

Esse atraso é útil quando sua API tem rate limiting ou quando você quer reduzir carga durante testes automatizados.

Executando coleções de uma instância Hoppscotch

Se suas coleções estiverem em uma instância Hoppscotch, em vez de um arquivo local, use o ID da coleção e um token de acesso pessoal:

hopp test <collection-id> --token <access_token> --server https://hoppscotch.your-company.com
Enter fullscreen mode Exit fullscreen mode

Use:

  • --token para autenticar com um token de acesso pessoal.
  • --server para apontar para sua instância auto-hospedada.

Se você usa a nuvem hospedada do Hoppscotch, pode omitir --server.

Execuções orientadas a dados

Para rodar a mesma coleção com dados diferentes, passe um CSV com --iteration-data:

hopp test ./my-collection.json --iteration-data ./users.csv --iteration-count 3
Enter fullscreen mode Exit fullscreen mode

Aqui:

  • --iteration-data recebe um arquivo CSV.
  • Cada coluna do CSV vira uma variável disponível na execução.
  • --iteration-count controla quantas iterações serão executadas.

Esse padrão cobre casos como:

  • testar login com múltiplas contas;
  • validar permissões por perfil de usuário;
  • executar o mesmo fluxo com diferentes entradas;
  • rodar testes contra uma lista de IDs ou emails.

Exemplo simples de CSV:

email,password
user1@example.com,secret123
user2@example.com,secret456
user3@example.com,secret789
Enter fullscreen mode Exit fullscreen mode

Dentro da coleção, você pode usar essas variáveis conforme o modelo de variáveis do Hoppscotch.

Gerando relatórios JUnit

Para gerar um relatório compatível com sistemas de CI, use --reporter-junit:

hopp test ./my-collection.json --reporter-junit ./report.xml
Enter fullscreen mode Exit fullscreen mode

O Hoppscotch CLI gera relatório estruturado em JUnit XML. Esse formato é suportado por muitas plataformas de CI para exibir resultados de teste nativamente.

Exemplo com ambiente e relatório:

hopp test ./my-collection.json \
  -e ./ci.env.json \
  --reporter-junit ./report.xml
Enter fullscreen mode Exit fullscreen mode

JUnit XML é o único formato estruturado produzido pelo CLI. Se você precisa de relatórios HTML, JSON ou relatórios hospedados e compartilháveis, essa é uma limitação importante. Para comparação, o Apidog CLI oferece relatórios CLI, HTML e JSON.

O que acontece durante uma execução

Quando você roda:

hopp test ./my-collection.json
Enter fullscreen mode Exit fullscreen mode

O CLI percorre a coleção em ordem. Para cada requisição, ele:

  1. executa o script de pré-requisição;
  2. envia a requisição HTTP;
  3. executa o script de teste;
  4. avalia as asserções;
  5. define o resultado da execução.

Os scripts usam a API de scripting do Hoppscotch.

Exemplo de teste simples:

pw.test("Status é 200", () => {
  pw.expect(pw.response.status).toBe(200);
});
Enter fullscreen mode Exit fullscreen mode

Se a asserção falhar, o comando retorna um código de saída diferente de zero. Se tudo passar, retorna 0.

Esse comportamento é o contrato principal com o CI:

  • saída 0: build continua;
  • saída diferente de 0: build falha.

Exemplo com GitHub Actions

Este workflow instala o Hoppscotch CLI em Node 22 e executa uma coleção a cada push:

name: Testes de API

on: [push]

jobs:
  hopp:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 22

      - run: npm i -g @hoppscotch/cli

      - run: hopp test ./collection.json -e ./ci.env.json --reporter-junit ./report.xml
Enter fullscreen mode Exit fullscreen mode

A parte mais importante é fixar o Node.js:

- uses: actions/setup-node@v4
  with:
    node-version: 22
Enter fullscreen mode Exit fullscreen mode

Sem isso, o runner pode usar uma versão antiga demais para o CLI atual.

Se quiser publicar o relatório JUnit como artefato, adicione uma etapa extra:

- uses: actions/upload-artifact@v4
  with:
    name: hopp-junit-report
    path: ./report.xml
Enter fullscreen mode Exit fullscreen mode

Exemplo de pipeline completo

Um fluxo comum para CI fica assim:

name: API CI

on:
  pull_request:
  push:
    branches:
      - main

jobs:
  api-tests:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 22

      - name: Instalar Hoppscotch CLI
        run: npm i -g @hoppscotch/cli

      - name: Executar testes de API
        run: |
          hopp test ./collection.json \
            -e ./ci.env.json \
            --iteration-data ./users.csv \
            --iteration-count 3 \
            --reporter-junit ./report.xml

      - name: Salvar relatório JUnit
        uses: actions/upload-artifact@v4
        with:
          name: api-test-report
          path: ./report.xml
Enter fullscreen mode Exit fullscreen mode

Esse exemplo cobre:

  • instalação do CLI;
  • execução com ambiente;
  • execução orientada a dados;
  • geração de relatório JUnit;
  • upload do relatório como artefato.

Limitações a considerar

O Hoppscotch CLI é direto e eficiente, mas tem escopo limitado:

  • É um executor de coleções, não uma plataforma completa. Ele não cobre design de API, mocking ou documentação.
  • Você precisa exportar ou hospedar as coleções. O CLI executa um arquivo local ou busca uma coleção em uma instância Hoppscotch.
  • JUnit é o único relatório estruturado. Não há relatório HTML integrado.
  • Node v22+ é obrigatório nas versões atuais. Fixe essa versão no CI.

Essas limitações não tornam o CLI ruim. Elas apenas definem onde ele se encaixa melhor: executar coleções Hoppscotch em pipelines.

Se você precisa de design, mocking, relatórios mais ricos e gerenciamento do ciclo de vida da API em uma plataforma integrada, o Apidog cobre esse fluxo. O guia completo do Apidog CLI mostra o uso pelo terminal. Você também pode baixar o Apidog, importar uma coleção Hoppscotch e comparar diretamente, ou seguir o passo a passo de migração.

FAQ

O Hoppscotch CLI é gratuito?

Sim. Ele faz parte do projeto open-source Hoppscotch, e você pode auto-hospedar o ecossistema. Veja a documentação oficial do CLI e o repositório no GitHub.

Qual é a diferença entre hopp test e Newman?

Ambos são executores de coleções com suporte a execuções orientadas a dados.

A diferença principal é o formato da coleção:

  • Newman executa coleções Postman.
  • hopp test executa coleções Hoppscotch.

Os conceitos são parecidos: dados de iteração, scripts de teste e aprovação ou reprovação baseada em código de saída.

O Hoppscotch CLI executa coleções de um servidor auto-hospedado?

Sim. Use:

hopp test <collection-id> --token <access_token> --server <your-url>
Enter fullscreen mode Exit fullscreen mode

Isso baixa e executa a coleção a partir da sua própria instância Hoppscotch.

Ele gera relatórios HTML?

Não diretamente. O CLI gera JUnit XML com:

hopp test ./my-collection.json --reporter-junit ./report.xml
Enter fullscreen mode Exit fullscreen mode

Para relatórios CLI, HTML e JSON, compare com os relatórios de teste do Apidog CLI.

Conclusão

O Hoppscotch CLI é uma forma simples e gratuita de executar coleções de API em CI, especialmente se você já usa Hoppscotch ou mantém uma instância auto-hospedada.

Para usar bem em pipelines:

  1. fixe Node.js v22+;
  2. execute coleções com hopp test;
  3. use arquivos de ambiente para separar configurações;
  4. use CSV para testes orientados a dados;
  5. gere JUnit XML para integração com CI.

Se o seu objetivo é apenas executar coleções Hoppscotch com validações automatizadas, o CLI faz bem esse trabalho.

Top comments (0)