Cómo migrar de la CLI de Hoppscotch a la CLI de Apidog

El CLI de Hoppscotch es una forma limpia y gratuita de ejecutar colecciones de API en un terminal o en una tubería de CI. El comando hopp test lee un archivo de colección, ejecuta cada solicitud, ejecuta tus scripts de pre-solicitud y prueba, y sale con un código distinto de cero si una aserción falla. Para muchos equipos, eso es suficiente.

Pero un ejecutor es solo una parte del trabajo de API. En algún momento, estás haciendo malabares con una herramienta de diseño separada, un servidor simulado, un sitio de documentación y el ejecutor, y ninguno de ellos comparte una fuente de verdad. Es entonces cuando los equipos suelen empezar a buscar cómo migrar del CLI de Hoppscotch al CLI de Apidog. Apidog integra diseño, depuración, mocking, documentación y pruebas en una sola plataforma, y su CLI ejecuta la parte de pruebas en CI. El ejecutor mantiene la misma forma que ya conoces. Lo que cambia es todo lo que lo rodea.

Cuándo deberías (y cuándo no) migrar

Sé honesto contigo mismo primero. Si tu único requisito es "ejecutar una colección en CI de forma gratuita, auto-alojada si quiero", el CLI de Hoppscotch es una herramienta realmente buena. Es de código abierto, el ejecutor es rápido y @hoppscotch/cli se envía como un paquete npm normal. No hay vergüenza en quedarse.

Migra cuando una de estas cosas empiece a doler:

• Diseñas APIs en una herramienta, simulas en otra y escribes documentación en una tercera, y mantenerlas sincronizadas es un trabajo manual.
• Quieres que las ejecuciones de prueba, los servidores simulados y la documentación publicada compartan una única definición de proyecto.
• Necesitas informes más ricos (informes HTML para las partes interesadas, JSON para las máquinas) además de un historial de ejecuciones alojado en la nube.
• Quieres tratar los endpoints, esquemas, entornos y ramas como código que el CLI puede gestionar, no solo ejecutar.

Si esa lista se parece a tu semana, la plataforma es la razón para cambiar, no el ejecutor. Aquí te explicamos cómo hacerlo de forma limpia.

Paso 1: Exporta tu colección y entorno de Hoppscotch

Todo en Hoppscotch es JSON, lo que hace que la exportación sea indolora.

Desde la aplicación Hoppscotch (web o escritorio), abre la colección que ejecutas en CI. Usa el menú de la colección y elige Exportar, lo que te dará un archivo .json. Haz lo mismo para el entorno que pasas con -e: abre el panel de entornos y expórtalo a su propio archivo JSON.

Si ya ejecutas el CLI con archivos locales, ya los tienes en tu disco. Un paso típico de Hoppscotch CI se ve así:

npm i -g @hoppscotch/cli
hopp test ./collections/checkout-api.json -e ./environments/staging.json

Guarda ambos archivos. checkout-api.json es tu colección, staging.json es tu entorno. Esos dos son la carga útil completa que estás transfiriendo.

Una nota sobre las versiones de Node mientras estás aquí. El CLI actual de Hoppscotch necesita Node.js v22 o posterior; los equipos anclados a Node 20 se quedan en el CLI v0.26.0. El CLI de Apidog no te ata a eso, así que una migración es también una oportunidad para eliminar una restricción de versión.

Paso 2: Importa la colección a Apidog

Crea un proyecto en Apidog (o abre uno existente), luego importa tu exportación de Hoppscotch. Apidog lee formatos de colección comunes y OpenAPI, por lo que puedes importar la colección directamente. Si tu API también tiene una especificación OpenAPI, impórtala también. Apidog valida la especificación al importarla, por lo que los problemas estructurales aparecen de inmediato en lugar de fallar silenciosamente a mitad de la ejecución.

Mapea tu entorno Hoppscotch a un entorno Apidog con los mismos nombres de variables. Si staging.json definió base_url y api_token, recrea esas claves bajo el entorno Apidog correspondiente. Mantener los nombres idénticos significa que tus scripts de prueba y URLs de solicitud no necesitan ediciones.

Este es también el momento en que la parte de la plataforma comienza a rendir frutos. Los endpoints que importaste son ahora artefactos de diseño. Puedes adjuntar esquemas, generar un servidor simulado a partir de ellos y publicar documentación a partir de las mismas definiciones que usas para probar. La guía completa del CLI de Apidog cubre toda la superficie una vez que lo tengas configurado, y la guía de instalación se encarga del binario del ejecutor.

Paso 3: Mapea hopp test a apidog run

El modelo mental se traslada directamente. Donde Hoppscotch ejecuta un archivo de colección, Apidog ejecuta un escenario de prueba o una colección de tu proyecto. El mismo trabajo, diferente fuente de verdad.

# Hoppscotch
hopp test ./collections/checkout-api.json -e ./environments/staging.json

# Apidog
apidog run --access-token $APIDOG_TOKEN -e "Staging"

Ambos comandos ejecutan cada solicitud en orden, ejecutan scripts de pre-solicitud, ejecutan tus aserciones de prueba y devuelven un código de salida distinto de cero si algo falla. Ese contrato de código de salida es la parte de la que depende CI, y se mantiene, por lo que la lógica de aprobación/falla de tu pipeline no cambia.

La autenticación difiere de una manera útil. Hoppscotch pasa un token de acceso personal con --token para colecciones en la nube o auto-alojadas. Apidog se autentica con un inicio de sesión o un token de acceso, lo que luego permite que el CLI acceda a los recursos de tu proyecto en lugar de a un solo archivo exportado. Si antes has tenido problemas con el manejo de tokens, el tutorial de autenticación explica las opciones.

Paso 4: Convierte las ejecuciones basadas en datos

Ambas herramientas realizan pruebas basadas en datos, por lo que la iteración sobre un CSV de entradas sobrevive a la migración.

En Hoppscotch, pasas datos de iteración y un recuento:

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

En Apidog, el ejecutor toma un conjunto de datos con -d. Acepta CSV y JSON, por lo que el mismo orders.csv funciona después de la importación:

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

Tu fila de encabezado CSV se convierte en los nombres de las variables a las que haces referencia dentro de las solicitudes y aserciones, el mismo patrón que usa Hoppscotch, por lo que los cuerpos de las pruebas no necesitan ser reescritos. Si eres nuevo en la versión de Apidog de esto, la guía de pruebas basadas en datos muestra cómo vincular columnas a variables y ejecutar una fila por iteración.

Paso 5: Convierte tus reportes

La generación de informes es donde la plataforma toma la delantera, y la conversión es sencilla.

Hoppscotch emite un archivo JUnit XML con una bandera, que la mayoría de los sistemas CI analizan para los paneles de prueba:

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

Apidog te ofrece una selección de reportes: un resumen CLI legible, un informe HTML que puedes entregar a las partes interesadas y un informe JSON para las máquinas. También puedes subir los resultados a la nube para un historial de ejecución compartible.

# Informe HTML legible para humanos
apidog run --access-token $APIDOG_TOKEN \
  -e "Staging" \
  -r html \
  --upload-report

Si tu panel de CI espera específicamente JUnit XML, ten en cuenta esa integración durante el cambio, ya que Apidog se apoya en sus informes CLI/HTML/JSON más los informes en la nube en lugar de una bandera JUnit. Para la mayoría de los equipos, el informe HTML más el historial en la nube subido es un paso adelante de un archivo XML sin procesar que nadie abre. La guía de informes de prueba desglosa cada formato y cuándo usarlo.

Antes y después: mapeo de comandos

Observa el flag -d en esa tabla. En Hoppscotch, -d es el retraso en milisegundos; en Apidog, -d es el conjunto de datos para las ejecuciones basadas en datos. La misma letra, diferente función. Es el único detalle que confunde a la gente durante el cambio de Hoppscotch a Apidog.

Paso 6: Intégralo en GitHub Actions

Último paso, y el objetivo es una compilación exitosa en todo momento. Configura el trabajo de Apidog junto con el antiguo de Hoppscotch primero, confirma que funciona, luego elimina el paso antiguo. Nunca cambies a ciegas.

name: API tests
on: [push, pull_request]

jobs:
  apidog-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Apidog CLI
        run: npm install -g apidog-cli

      - name: Run API tests
        env:
          APIDOG_TOKEN: ${{ secrets.APIDOG_TOKEN }}
        run: |
          apidog run \
            --access-token "$APIDOG_TOKEN" \
            -e "Staging" \
            -d ./data/orders.csv \
            -r html \
            --upload-report

Almacena tu token de acceso como un secreto del repositorio, nunca en el YAML. Debido a que el CLI devuelve un código de salida distinto de cero si alguna aserción falla, el trabajo falla exactamente cuando tus pruebas lo hacen, que es el comportamiento en el que tu equipo ya confía de Hoppscotch. La guía de GitHub Actions cubre el almacenamiento en caché y las ejecuciones en matriz, y la guía de pipeline CI/CD más amplia maneja GitLab, Jenkins y el resto.

Una vez que el trabajo de Apidog esté en verde durante algunas ejecuciones, elimina el paso de Hoppscotch y su instalación de npm. Migración completada, la compilación nunca se puso en rojo.

Una palabra justa sobre Hoppscotch

Nada de esto es una crítica a Hoppscotch. Su CLI es rápido y gratuito, el proyecto es completamente de código abierto y puedes auto-alojar toda la pila. Si quieres un ejecutor ligero y nada más, se gana su lugar. La razón para cambiar es el alcance: cuando el diseño, el mock, la documentación y las pruebas necesitan compartir una única definición, un ejecutor independiente no puede darte eso, y una plataforma integrada sí. Compara directamente los dos ejecutores en Apidog CLI vs Hoppscotch CLI, y si estás sopesando las aplicaciones en lugar de los CLIs, Postman vs Hoppscotch y el resumen de alternativas a Hoppscotch añaden contexto.