Hoppscotch é um ecossistema de API open-source; aplicativo web, aplicativo desktop, CLI e um backend auto-hospedável, frequentemente descrito como uma alternativa aberta ao Postman e Insomnia. O Hoppscotch CLI é a peça que pega as coleções que você constrói nesse ecossistema e as executa a partir de um terminal, o que é exatamente o que você precisa para CI/CD.
Este guia explica o que é o Hoppscotch CLI, como instalá-lo e como o comando hopp test realmente funciona, com os parâmetros reais e um exemplo de CI funcional. Se você estiver comparando-o com outros executores, o post melhores alternativas ao Hoppscotch CLI compara as opções, e Apidog CLI vs Hoppscotch CLI é o confronto direto.
O que é o Hoppscotch CLI
O Hoppscotch CLI é distribuído como o pacote npm @hoppscotch/cli. Seu trabalho é específico e útil: pegar uma coleção Hoppscotch, executar cada requisição nela, executar os scripts de teste anexados a essas requisições e sair com um código de aprovação/reprovação que seu pipeline pode ler.
Isso o torna um executor de coleções, na mesma categoria do Newman para Postman ou inso para Insomnia. Ele não projeta APIs, não simula endpoints nem gera documentação. Ele executa requisições e verifica asserções. Para uma ferramenta gratuita e de código aberto que você também pode auto-hospedar, esse foco é o ponto principal.
Como o Hoppscotch é de código aberto, você pode executar toda a pilha por conta própria e apontar o CLI para sua própria instância. Equipes que não querem que seus dados de requisição fiquem em uma nuvem de fornecedor tendem a gostar disso. A desvantagem é que você é o responsável pela hospedagem.
Instalando o Hoppscotch CLI
Instale-o globalmente a partir do npm:
npm i -g @hoppscotch/cli
Um requisito a observar: o CLI atual precisa do Node.js v22 ou mais recente. Se você ainda estiver no Node 20, pode permanecer no CLI v0.26.0, mas as versões mais recentes assumem v22+. Verifique sua versão antes de conectá-lo a um agente de build:
node --version
hopp --version
Se sua imagem de CI usar uma versão mais antiga do Node, fixe o tempo de execução para v22 no pipeline, ou você encontrará um erro de instalação ou de tempo de execução que parece não relacionado aos seus testes.
O comando hopp test
Tudo é executado através de hopp test. A forma básica o aponta para um arquivo de coleção:
hopp test ./my-collection.json
Você pode passar um arquivo de ambiente e um atraso entre as requisições:
hopp test ./my-collection.json -e ./staging.env.json -d 500
Aqui -e (ou --env) fornece o ambiente, e -d (ou --delay) aguarda o número dado de milissegundos entre as requisições, o que ajuda quando você está acessando uma API com limite de taxa.
Se suas coleções estiverem em uma instância Hoppscotch (nuvem ou auto-hospedada) em vez de um arquivo local, você as referencia pelo ID e se autentica com um token de acesso pessoal:
hopp test <collection-id> --token <access_token> --server https://hoppscotch.your-company.com
--token carrega seu token de acesso pessoal, e --server aponta para sua URL auto-hospedada. Omita --server se você estiver na nuvem Hoppscotch hospedada.
Execuções orientadas a dados e relatórios
Dois parâmetros transformam hopp test de uma única execução em algo amigável ao CI.
Para testes orientados a dados, forneça um CSV e defina quantas iterações executar:
hopp test ./my-collection.json --iteration-data ./users.csv --iteration-count 3
--iteration-data recebe um CSV cujas colunas se tornam variáveis em cada execução, e --iteration-count controla quantas vezes a coleção se repete. Essa é a mesma ideia do -d do Newman, e cobre o caso comum de “executar este fluxo de login contra 50 contas”.
Para relatórios, o CLI escreve JUnit XML, que a maioria dos sistemas de CI pode ingerir para mostrar os resultados dos testes nativamente:
hopp test ./my-collection.json --reporter-junit ./report.xml
JUnit é o único formato de relatório estruturado que o CLI produz. Se você precisar de artefatos HTML ou relatórios hospedados e linkáveis, essa é uma lacuna que vale a pena conhecer antes de se comprometer. Ferramentas como o Apidog CLI emitem relatórios CLI, HTML e JSON para comparação.
O que realmente é executado durante uma rodada
Quando você executa hopp test, o CLI percorre a coleção em ordem e, para cada requisição:
- executa o script de pré-requisição,
- envia a requisição,
- executa o script de teste e avalia cada asserção.
Scripts de teste usam a API de scripting do Hoppscotch: pw.test() define um bloco de teste e pw.expect() faz asserções dentro dele. Um pequeno exemplo anexado a uma requisição se parece com isto:
pw.test("Status é 200", () => {
pw.expect(pw.response.status).toBe(200);
});
Se alguma asserção falhar, o comando sai com um código diferente de zero. Se tudo passar, ele sai com 0. Esse comportamento de código de saída é todo o contrato com o CI: uma saída diferente de zero falha o build, o que é exatamente o que você deseja.
Um exemplo com GitHub Actions
Integrar hopp test ao CI é simples. Este workflow instala o CLI em um executor 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
A etapa setup-node fixando a v22 é a parte que as pessoas esquecem. Sem ela, o Node padrão do executor pode ser muito antigo para o CLI atual.
Limitações a ter em mente
O Hoppscotch CLI é bom no que faz e honesto sobre seu escopo:
- É um executor de coleções, não uma plataforma. Sem design, mocking ou documentação. Você traz esses recursos de outro lugar.
- Você exporta ou hospeda as coleções por conta própria. O CLI executa um arquivo de coleção ou puxa um de uma instância para a qual você o aponta.
- JUnit é o único relatório estruturado. Sem HTML integrado ou relatório hospedado.
- Node v22+. Um requisito rigoroso nas versões atuais.
Nada disso é uma crítica; é o custo de uma ferramenta pequena, gratuita e de código aberto. Se suas necessidades forem além de “executar uma coleção em CI” em direção a design, mocking, execuções orientadas a dados com relatórios mais ricos e gerenciamento de recursos de API como código, é aí que entra uma plataforma integrada. O Apidog cobre todo o ciclo de vida da API, e o guia completo do Apidog CLI mostra o lado do terminal. Você pode baixar o Apidog e importar uma coleção Hoppscotch para comparar diretamente, ou ler o passo a passo da migração.
FAQ
O Hoppscotch CLI é gratuito? Sim. É de código aberto sob o projeto Hoppscotch, e você pode auto-hospedar todo 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 iterações orientadas a dados. Newman executa coleções Postman; hopp test executa coleções Hoppscotch. Os conceitos se alinham de perto, incluindo dados de iteração CSV e aprovação/reprovação baseada em código de saída.
O Hoppscotch CLI pode executar coleções de um servidor auto-hospedado? Sim. Use hopp test <collection-id> --token <access_token> --server <your-url> para puxar e executar uma coleção de sua própria instância.
Ele produz relatórios HTML? Não diretamente. Ele escreve JUnit XML via --reporter-junit. Para relatórios CLI, HTML e JSON juntos, compare com os relatórios de teste do Apidog CLI.
O Hoppscotch CLI é uma maneira limpa e gratuita de executar coleções de API em CI, especialmente se você já usa Hoppscotch ou o auto-hospeda. Conheça seu escopo, fixe o Node v22 e use a saída JUnit, e ele fará bem o seu trabalho.