DEV Community

Cover image for ¿Qué es el CLI de Hoppscotch?
Roobia
Roobia

Posted on • Originally published at apidog.com

¿Qué es el CLI de Hoppscotch?

Hoppscotch es un ecosistema API de código abierto: aplicación web, aplicación de escritorio, CLI y backend autoalojable. Suele describirse como una alternativa abierta a Postman e Insomnia. Su CLI ejecuta desde la terminal las colecciones que creas en Hoppscotch, por lo que encaja bien en flujos de CI/CD.

Prueba Apidog hoy

En esta guía verás qué es la CLI de Hoppscotch, cómo instalarla, cómo usar hopp test, qué banderas son útiles en CI y cómo integrarla con GitHub Actions. Si estás comparando ejecutores, revisa también las mejores alternativas a la CLI de Hoppscotch y la comparación directa Apidog CLI vs Hoppscotch CLI.

Qué es la CLI de Hoppscotch

La CLI de Hoppscotch se distribuye como el paquete npm @hoppscotch/cli.

Su función es concreta:

  1. Cargar una colección de Hoppscotch.
  2. Ejecutar cada solicitud.
  3. Ejecutar los scripts de prueba asociados.
  4. Devolver un código de salida que CI pueda interpretar como éxito o fallo.

CLI de Hoppscotch

En la práctica, funciona como un ejecutor de colecciones, similar a Newman para Postman o inso para Insomnia.

No está pensada para diseñar APIs, simular endpoints ni generar documentación. Su objetivo es ejecutar solicitudes y validar aserciones.

Como Hoppscotch es de código abierto, también puedes autoalojar el ecosistema completo y apuntar la CLI a tu propia instancia. Esto resulta útil si tu equipo no quiere que los datos de las solicitudes residan en la nube de un proveedor. La contrapartida es que tú gestionas el alojamiento.

Instalación de la CLI de Hoppscotch

Instala la CLI globalmente desde npm:

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

Verifica que el binario esté disponible:

hopp --version
Enter fullscreen mode Exit fullscreen mode

La CLI actual requiere Node.js v22 o superior. Antes de usarla en un agente de CI, comprueba la versión de Node:

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

Si todavía usas Node 20, puedes mantenerte en la CLI v0.26.0. Para versiones recientes, fija Node v22+ en tu pipeline para evitar errores de instalación o ejecución.

Ejecutar una colección con hopp test

El comando principal es hopp test.

Para ejecutar una colección local:

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

Para usar un entorno y añadir un retraso entre solicitudes:

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

Donde:

  • -e o --env carga un archivo de entorno.
  • -d o --delay espera el número indicado de milisegundos entre solicitudes.

El retraso es útil cuando pruebas APIs con límites de velocidad.

Ejecutar colecciones desde una instancia de Hoppscotch

Si tus colecciones están en Hoppscotch Cloud o en una instancia autoalojada, puedes ejecutarlas por ID.

Ejemplo con una instancia autoalojada:

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

Parámetros importantes:

  • --token: token de acceso personal.
  • --server: URL de tu instancia autoalojada.

Si usas la nube alojada de Hoppscotch, puedes omitir --server.

Ejecuciones basadas en datos

Para pruebas data-driven, usa un CSV como fuente de datos:

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

--iteration-data recibe un archivo CSV. Sus columnas se convierten en variables disponibles durante cada ejecución.

--iteration-count controla cuántas veces se repite la colección.

Este patrón sirve para casos como:

  • Ejecutar el mismo flujo con varias cuentas.
  • Probar distintos roles de usuario.
  • Validar múltiples combinaciones de entrada.
  • Reutilizar una colección contra varios escenarios.

Ejemplo conceptual de CSV:

email,password
user1@example.com,secret1
user2@example.com,secret2
user3@example.com,secret3
Enter fullscreen mode Exit fullscreen mode

Generar informes para CI

La CLI puede escribir resultados en formato JUnit XML:

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

La mayoría de sistemas de CI pueden ingerir JUnit para mostrar resultados de pruebas de forma nativa.

JUnit es el único formato de informe estructurado que genera la CLI. Si necesitas reportes HTML, JSON o artefactos alojados y enlazables, tenlo en cuenta antes de adoptarla como ejecutor principal. Para comparar, la CLI de Apidog emite informes CLI, HTML y JSON.

Qué ocurre durante una ejecución

Cuando ejecutas:

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

la CLI recorre la colección en orden. Para cada solicitud:

  1. Ejecuta el script de pre-solicitud.
  2. Envía la solicitud HTTP.
  3. Ejecuta el script de prueba.
  4. Evalúa las aserciones.
  5. Continúa con la siguiente solicitud o termina con error si falla una validación.

Los scripts de prueba usan la API de scripting de Hoppscotch.

Ejemplo:

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

Si alguna aserción falla, hopp test termina con un código de salida distinto de cero.

Si todas pasan, termina con código 0.

Ese comportamiento es lo que permite integrarlo con CI:

  • Código 0: el job pasa.
  • Código distinto de 0: el job falla.

Ejemplo con GitHub Actions

Este workflow instala Node 22, instala la CLI y ejecuta una colección en cada push:

name: API tests

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

La parte crítica es fijar Node 22:

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

Sin este paso, el runner podría usar una versión de Node incompatible con la CLI actual.

Publicar el reporte JUnit en GitHub Actions

Si quieres conservar el XML como artefacto del workflow, añade un paso de subida:

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

Workflow completo:

name: API tests

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

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

El if: always() permite subir el reporte incluso si las pruebas fallan.

Limitaciones a tener en cuenta

La CLI de Hoppscotch es útil, pero tiene un alcance específico.

Es un ejecutor de colecciones, no una plataforma completa

No cubre diseño de APIs, simulación de endpoints ni documentación. Para eso necesitas otras herramientas del ecosistema o una plataforma integrada.

Debes exportar o alojar tus colecciones

La CLI ejecuta una colección local o extrae una colección desde una instancia de Hoppscotch a la que tenga acceso.

Solo genera JUnit como informe estructurado

No incluye reportes HTML integrados ni reportes alojados.

Requiere Node v22+

Las versiones actuales tienen este requisito. En CI, fija explícitamente la versión de Node.

Cuándo usar la CLI de Hoppscotch

Tiene sentido usarla si:

  • Ya trabajas con colecciones de Hoppscotch.
  • Quieres ejecutar pruebas API en CI.
  • Necesitas una herramienta gratuita y de código abierto.
  • Puedes gestionar tus propios archivos de entorno y reportes.
  • Te basta con salida JUnit para CI.

Puede quedarse corta si necesitas:

  • Diseño de API integrado.
  • Mocking.
  • Documentación.
  • Reportes HTML o JSON.
  • Gestión de recursos API como código.
  • Una experiencia más completa de ciclo de vida API.

En ese caso, puedes evaluar una plataforma integrada. Apidog cubre el ciclo de vida de la API, y la guía completa de la CLI de Apidog muestra cómo usarla desde terminal. También puedes descargar Apidog, importar una colección de Hoppscotch y comparar el flujo directamente, o revisar la guía de migración.

Preguntas frecuentes

¿Es gratuita la CLI de Hoppscotch?

Sí. Es de código abierto como parte del proyecto Hoppscotch. También puedes autoalojar el ecosistema. Consulta la documentación oficial de la CLI y el repositorio de GitHub.

¿Cuál es la diferencia entre hopp test y Newman?

Ambos son ejecutores de colecciones con soporte para iteraciones basadas en datos.

La diferencia principal es el formato de colección:

  • Newman ejecuta colecciones de Postman.
  • hopp test ejecuta colecciones de Hoppscotch.

Los conceptos son similares: variables, datos de iteración, aserciones y éxito/fallo basado en código de salida.

¿Puede ejecutar colecciones desde un servidor autoalojado?

Sí. Usa:

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

Esto extrae y ejecuta una colección desde tu propia instancia de Hoppscotch.

¿La CLI de Hoppscotch genera informes HTML?

No directamente. Genera XML de JUnit con:

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

Si necesitas informes CLI, HTML y JSON, compara con los informes de prueba de la CLI de Apidog.

Conclusión

La CLI de Hoppscotch es una forma simple y gratuita de ejecutar colecciones API en CI, especialmente si ya usas Hoppscotch o lo tienes autoalojado.

Para usarla bien:

  1. Instala @hoppscotch/cli.
  2. Fija Node.js v22+ en CI.
  3. Ejecuta colecciones con hopp test.
  4. Usa archivos de entorno para separar configuraciones.
  5. Añade datos CSV si necesitas iteraciones.
  6. Genera JUnit XML para que tu pipeline procese los resultados.

Si tu objetivo es ejecutar colecciones y fallar el build cuando una aserción no pasa, la CLI cumple esa función de forma directa.

Top comments (0)