Hoppscotch es un ecosistema API de código abierto; aplicación web, aplicación de escritorio, CLI y un backend autoalojable, a menudo descrito como una alternativa abierta a Postman e Insomnia. La CLI de Hoppscotch es la pieza que toma las colecciones que construyes en ese ecosistema y las ejecuta desde una terminal, que es exactamente lo que necesitas para CI/CD.
Esta guía explica qué es la CLI de Hoppscotch, cómo instalarla y cómo funciona realmente el comando hopp test, con las banderas reales y un ejemplo de CI funcional. Si lo estás comparando con otros ejecutores, la publicación sobre las mejores alternativas a la CLI de Hoppscotch compara las opciones, y Apidog CLI vs Hoppscotch CLI es el enfrentamiento directo.
Qué es la CLI de Hoppscotch
La CLI de Hoppscotch se distribuye como el paquete npm @hoppscotch/cli. Su trabajo es específico y útil: tomar una colección de Hoppscotch, ejecutar cada solicitud en ella, ejecutar los scripts de prueba adjuntos a esas solicitudes y salir con un código de aprobación/fallo que tu pipeline pueda leer.
Eso lo convierte en un ejecutor de colecciones, en la misma categoría que Newman para Postman o inso para Insomnia. No diseña APIs, no simula endpoints ni genera documentación. Ejecuta solicitudes y verifica aserciones. Para una herramienta gratuita de código abierto que también puedes autoalojar, ese enfoque es el punto clave.
Dado que Hoppscotch es de código abierto, puedes ejecutar toda la pila tú mismo y apuntar la CLI a tu propia instancia. Los equipos que no quieren que sus datos de solicitud residan en la nube de un proveedor suelen apreciar eso. La contrapartida es que tú te encargas del alojamiento.
Instalación de la CLI de Hoppscotch
Instálalo globalmente desde npm:
npm i -g @hoppscotch/cli
Un requisito a tener en cuenta: la CLI actual necesita Node.js v22 o superior. Si todavía usas Node 20, puedes mantenerte en la CLI v0.26.0, pero las últimas versiones asumen v22+. Verifica tu versión antes de conectarla a un agente de compilación:
node --version
hopp --version
Si tu imagen de CI incluye una versión anterior de Node, fija el entorno de ejecución a v22 en el pipeline, o encontrarás un error de instalación o de tiempo de ejecución que parecerá no relacionado con tus pruebas.
El comando hopp test
Todo se ejecuta a través de hopp test. La forma básica lo apunta a un archivo de colección:
hopp test ./my-collection.json
Puedes pasar un archivo de entorno y un retraso entre solicitudes:
hopp test ./my-collection.json -e ./staging.env.json -d 500
Aquí -e (o --env) proporciona el entorno, y -d (o --delay) espera el número de milisegundos indicado entre solicitudes, lo que ayuda cuando estás realizando solicitudes a una API con límite de velocidad.
Si tus colecciones residen en una instancia de Hoppscotch (en la nube o autoalojada) en lugar de un archivo local, las referencias por ID y te autenticas con un token de acceso personal:
hopp test <collection-id> --token <access_token> --server https://hoppscotch.your-company.com
--token lleva tu token de acceso personal, y --server apunta a tu URL autoalojada. Omite --server si estás en la nube alojada de Hoppscotch.
Ejecuciones impulsadas por datos e informes
Dos banderas convierten hopp test de una sola pasada en algo compatible con CI.
Para pruebas basadas en datos, introduce un CSV y establece cuántas iteraciones ejecutar:
hopp test ./my-collection.json --iteration-data ./users.csv --iteration-count 3
--iteration-data toma un CSV cuyas columnas se convierten en variables en cada ejecución, y --iteration-count controla cuántas veces se repite la colección. Esa es la misma idea que -d de Newman, y cubre el caso común de "ejecutar este flujo de inicio de sesión en 50 cuentas".
Para los informes, la CLI escribe XML de JUnit, que la mayoría de los sistemas de CI pueden ingerir para mostrar los resultados de las pruebas de forma nativa:
hopp test ./my-collection.json --reporter-junit ./report.xml
JUnit es el único formato de informe estructurado que produce la CLI. Si necesitas artefactos HTML o informes alojados y enlazables, esa es una brecha que vale la pena conocer antes de comprometerte. Herramientas como la CLI de Apidog emiten informes CLI, HTML y JSON para comparación.
Qué se ejecuta realmente durante una corrida
Cuando ejecutas hopp test, la CLI recorre la colección en orden y, para cada solicitud:
- ejecuta el script de pre-solicitud,
- envía la solicitud,
- ejecuta el script de prueba y evalúa cada aserción.
Los scripts de prueba utilizan la API de scripting de Hoppscotch: pw.test() define un bloque de prueba y pw.expect() realiza aserciones dentro de él. Un pequeño ejemplo adjunto a una solicitud se ve así:
pw.test("Status is 200", () => {
pw.expect(pw.response.status).toBe(200);
});
Si alguna aserción falla, el comando sale con un código distinto de cero. Si todo pasa, sale con 0. Ese comportamiento del código de salida es todo el contrato con CI: una salida distinta de cero falla la compilación, que es exactamente lo que quieres.
Un ejemplo de GitHub Actions
Integrar hopp test en CI es sencillo. Este flujo de trabajo instala la CLI en un ejecutor de Node 22 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
El paso setup-node que fija la versión v22 es la parte que la gente olvida. Sin él, el Node del ejecutor predeterminado puede ser demasiado antiguo para la CLI actual.
Limitaciones a tener en cuenta
La CLI de Hoppscotch es buena en lo que hace y honesta con su alcance:
- Es un ejecutor de colecciones, no una plataforma. No hay diseño, simulación ni documentación. Esas cosas las traes de otro lugar.
- Exportas o alojas las colecciones tú mismo. La CLI ejecuta un archivo de colección o extrae uno de una instancia a la que lo apuntas.
- JUnit es el único informe estructurado. No hay informes HTML integrados ni informes alojados.
- Node v22+. Un requisito estricto en las versiones actuales.
Nada de eso es una crítica; es el costo de una herramienta pequeña, gratuita y de código abierto. Si tus necesidades van más allá de "ejecutar una colección en CI" hacia el diseño, la simulación, ejecuciones basadas en datos con informes más completos y la gestión de recursos API como código, ahí es donde entra una plataforma integrada. Apidog cubre todo el ciclo de vida de la API, y la guía completa de la CLI de Apidog muestra el lado del terminal. Puedes descargar Apidog e importar una colección de Hoppscotch para comparar directamente, o leer la guía de migración.
Preguntas Frecuentes
¿Es gratuita la CLI de Hoppscotch? Sí. Es de código abierto bajo el proyecto Hoppscotch, y puedes autoalojar todo 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 iteraciones basadas en datos. Newman ejecuta colecciones de Postman; hopp test ejecuta colecciones de Hoppscotch. Los conceptos se corresponden estrechamente, incluyendo los datos de iteración CSV y el éxito/fallo basado en el código de salida.
¿Puede la CLI de Hoppscotch ejecutar colecciones desde un servidor autoalojado? Sí. Usa hopp test <collection-id> --token <access_token> --server <your-url> para extraer y ejecutar una colección desde tu propia instancia.
¿Produce informes HTML? No directamente. Escribe XML de JUnit a través de --reporter-junit. Para informes CLI, HTML y JSON juntos, compara con los informes de prueba de la CLI de Apidog.
La CLI de Hoppscotch es una forma limpia y gratuita de ejecutar colecciones de API en CI, especialmente si ya usas Hoppscotch o lo autoalojas. Conoce su alcance, fija Node v22 y apóyate en la salida de JUnit, y hará su único trabajo bien.