Cómo migrar de inso (Insomnia CLI) a Apidog CLI

Si ejecutas pruebas de API desde inso, la CLI de Insomnia de Kong, y has estado pensando en un cambio, esta guía te acompaña de principio a fin. Verás cómo exportar tus especificaciones y conjuntos de pruebas de Insomnia, importarlos a Apidog y reescribir tus comandos inso run como comandos apidog run. Hay una tabla de comandos antes/después para que puedas mapear tus scripts CI existentes línea por línea.

Por qué los equipos migran de inso a Apidog CLI

inso es una herramienta sólida. Lleva la ejecución de solicitudes, el linting de Spectral y las pruebas unitarias a la terminal, y lee desde un directorio .insomnia creado por la Sincronización Git de Insomnia. Si ese flujo de trabajo te conviene, no hay ninguna regla que diga que tengas que marcharte.

La fricción suele empezar con la aplicación Insomnia, no con la CLI. Dos cosas impulsan la mayoría de las búsquedas de migración:

• La cuenta en la nube requerida. Insomnia 8, lanzado en 2023, introdujo una cuenta de inicio de sesión/nube obligatoria que tomó a muchos equipos por sorpresa. Muchos desarrolladores querían un cliente local-first y en su lugar encontraron una barrera de inicio de sesión.
• Pérdida de datos y dolor de migración. Algunos usuarios sufrieron incidentes de pérdida de datos y migración durante esa transición. Si has vivido uno, ya conoces el costo. Si te estás recuperando de uno ahora, estas guías te ayudarán: recuperación y exportación de datos de Insomnia y la guía más profunda de recuperación de pérdida de datos y migración de Insomnia 8.

La otra razón es la consolidación. Con inso, la CLI es una pieza de una pila: Insomnia para solicitudes, Spectral para linting, herramientas separadas para mocks y documentación. Apidog integra el diseño, la depuración, las pruebas, los mocks y la documentación en una sola plataforma, y la CLI ejecuta la parte de pruebas de esa plataforma. Menos piezas móviles, una única fuente de verdad.

Si quieres el contexto más amplio antes de comprometerte, Apidog vs Insomnia y elegir entre Insomnia y Apidog exponen las ventajas y desventajas de las aplicaciones completas, no de las CLI.

Antes de empezar: qué se migra y qué no

Establece las expectativas de antemano para que nada te sorprenda a mitad de la migración.

La nota sincera: inso lint spec ejecuta Spectral, el linter de OpenAPI de Stoplight, y eso es una verdadera fortaleza. Apidog CLI no incluye un linter de especificaciones independiente, una guía de estilo, un comando de división, unión o empaquetado. Apidog valida tu especificación cuando la importas, por lo que los problemas estructurales surgen en el momento de la importación, pero si tu pipeline depende de conjuntos de reglas personalizados de Spectral como un control, mantén Spectral en tu CI junto con Apidog. No esperes apidog lint. No existe, y pretender lo contrario solo te perjudicaría más adelante.

Paso 1: exporta tus especificaciones y pruebas desde Insomnia

inso puede escribir tu documento de diseño directamente en un archivo. La especificación se referencia por nombre, el mismo nombre que ves en la aplicación Insomnia:

# Exportar un documento de diseño OpenAPI a un archivo YAML
inso export spec "My API Design" --output my-api.yaml

Si inso no encuentra tus datos, apúntalo a la fuente correcta. Por defecto, lee desde un directorio .insomnia en el directorio de trabajo o en el directorio de datos de la aplicación Insomnia. Anula con --workingDir o --src:

inso export spec "My API Design" --workingDir ./design --output my-api.yaml

Para las colecciones de solicitudes y cualquier cosa que inso no exporte limpiamente, utiliza la propia aplicación Insomnia: abre la aplicación, selecciona tu espacio de trabajo y utiliza **Exportar** para producir un archivo OpenAPI o Insomnia v4. Guarda tanto el documento de diseño como la exportación de la colección. Los importarás por separado.

Si estás en medio de una recuperación y la aplicación no coopera, la guía de exportación y recuperación cubre cómo extraer datos cuando la Sincronización Git o la cuenta en la nube te están dando problemas.

Paso 2: importar a Apidog

Abre Apidog, crea un proyecto e importa el YAML o JSON que acabas de exportar. Apidog lee OpenAPI de forma nativa, por lo que tus endpoints, esquemas y datos de ejemplo se convierten en recursos estructurados que puedes editar, simular y probar.

También puedes importar desde la CLI como parte de una configuración automatizada, lo cual es útil cuando estás automatizando una migración de equipo en lugar de hacer clic a través de la interfaz de usuario. Apidog importa OpenAPI y gestiona endpoints, esquemas, entornos, ramas y solicitudes de fusión como código desde la terminal, autenticándose mediante inicio de sesión o un token de acceso. Si estás configurando la CLI por primera vez, la guía de instalación de Apidog CLI y la guía completa de la CLI cubren la configuración y el flujo de autenticación.

Al importar, Apidog valida la especificación. Si tu OpenAPI tiene problemas estructurales, lo descubrirás ahora en lugar de en tiempo de ejecución. Esta es la analogía más cercana a inso lint spec, con una diferencia que vale la pena repetir: es validación, no un conjunto de reglas configurable de Spectral.

Paso 3: mapea tus comandos (la parte que estabas esperando)

Esta es la esencia de la migración. Así es como los comandos inso se traducen a apidog run.

Algunas notas sobre el mapeo:

• Entornos. inso usa --env "nombre". Apidog usa -e (--env). Ambos seleccionan la URL base y las variables del entorno a aplicar. Primero recrea tus entornos de Insomnia como entornos de Apidog, luego referéncialos por nombre o ID.
• Los conjuntos de pruebas se convierten en escenarios de prueba. Donde inso run test ejecuta un conjunto de pruebas unitarias de Insomnia, Apidog ejecuta escenarios de prueba. El concepto se mapea limpiamente: solicitudes ordenadas con aserciones. Reconstruirás el conjunto una vez en Apidog, y luego se ejecutará en cada apidog run.
• inso script era una indirección. Si encapsulabas comandos detrás de scripts con nombre, simplemente llama a apidog run directamente en tu paso de CI, o encapsúlalo en tu propio script npm/make.

Para una comparación más profunda comando por comando, Apidog CLI vs inso (Insomnia CLI) detalla cada bandera. Si vienes de Newman o la CLI de Postman de una vida anterior, Apidog CLI vs Newman y Apidog CLI vs Postman CLI también los cubren.

Paso 4: mueve tus reporteros

inso se apoya en su salida de pruebas y en los informes de estilo JUnit para CI. Apidog te ofrece reporteros en formatos CLI, HTML y JSON, para que tu compilación pueda imprimir resultados legibles por humanos en la consola y emitir un artefacto legible por máquina al mismo tiempo:

# Ejecutar un escenario y emitir un resumen CLI y un informe HTML
apidog run --test-scenario "Smoke Suite" -e staging -r cli,html

Elige json cuando una herramienta posterior necesite analizar los resultados, html cuando un humano revise la compilación y cli para la alimentación en vivo de la consola. También puedes enviar los resultados a los informes de pruebas en la nube de Apidog con --upload-report para que todo el equipo vea la ejecución sin tener que buscar en los logs de CI. La guía de informes de pruebas cubre los formatos en detalle.

Paso 5: trae las pruebas basadas en datos

Si tus conjuntos de Insomnia iteraban sobre datos, Apidog admite las pruebas basadas en datos de forma nativa. Alimenta un conjunto de datos CSV o JSON con -d y el escenario se ejecutará una vez por fila:

apidog run --test-scenario "Login Matrix" -e staging -d ./users.csv -r cli,json

Este es un lugar donde Apidog tiende a sentirse menos añadido que encadenar datos externos a través de inso. La guía de pruebas basadas en datos explica los formatos de conjuntos de datos y la vinculación de variables.

Paso 6: intégralo en tu CI

El paso final es intercambiar el comando en tu pipeline. Tu antiguo paso de GitHub Actions o GitLab probablemente se veía así:

# Antes: inso en CI
inso run test "Smoke Suite" --env "CI" --reporter junit

El equivalente en Apidog:

# Después: Apidog CLI en CI
apidog run --test-scenario "Smoke Suite" -e ci -r cli,json --upload-report

Autentica el ejecutor con un token de acceso almacenado como secreto de CI, de la misma manera que manejarías cualquier paso con credenciales. La guía de pipeline CI/CD y la guía de GitHub Actions tienen archivos de flujo de trabajo para copiar y pegar. Para detalles específicos de tokens e inicio de sesión, consulta la autenticación de Apidog CLI.

Si mantuviste Spectral para el linting (recomendado si tenías reglas personalizadas), tu pipeline ahora tiene dos puertas: Spectral analiza la especificación, Apidog ejecuta las pruebas. Ese es un estado final perfectamente razonable, y es honesto sobre lo que cada herramienta hace mejor.

Manteniendo Spectral en el bucle

Para ser claros sobre lo único que no se porta: si el linting es parte de tu contrato, no lo abandones. Spectral es de código abierto y funciona bien fuera de Insomnia. Un CI híbrido típico se ve así:

# Lint con Spectral (mantenido de tu configuración de inso)
npx @stoplight/spectral-cli lint my-api.yaml

# Prueba con Apidog CLI
apidog run --test-scenario "Smoke Suite" -e ci -r cli,json

No pierdes nada en el lado del linting y ganas la plataforma integrada de diseño-simulación-pruebas-documentación de Apidog en todo lo demás. Ese es el intercambio preciso, y es bueno para la mayoría de los equipos.

inso vs Apidog CLI de un vistazo

Preguntas frecuentes

¿Se importará mi especificación OpenAPI de Insomnia a Apidog sin ediciones? Normalmente sí. Apidog lee OpenAPI de forma nativa y valida al importar. Si la validación marca algo, suele ser un problema estructural real en la especificación, y solucionarlo una vez beneficia a todas las herramientas posteriores.

¿Apidog CLI tiene un comando lint como inso lint spec? No. Apidog valida las especificaciones al importar, pero no hay un linter CLI independiente ni un comando de guía de estilo. Si dependes de conjuntos de reglas personalizados de Spectral, mantén Spectral en tu pipeline junto a apidog run. Para una comparación lado a lado, consulta Apidog CLI vs Redocly CLI, ya que Redocly CLI sí incluye un linter.

¿Puedo ejecutar Apidog CLI en CI de la misma manera que ejecutaba inso? Sí. Intercambia el comando, autentica con un token de acceso de un secreto de CI y elige tus reporteros. La guía de CI/CD tiene ejemplos completos de flujos de trabajo.

¿Qué sucede con mis conjuntos de pruebas unitarias de Insomnia? Los reconstruyes como escenarios de prueba de Apidog. La estructura se mantiene directamente: solicitudes ordenadas más aserciones. Es una reconstrucción única, después de la cual se ejecutarán en cada apidog run.

Estoy migrando de Insomnia debido a un incidente de pérdida de datos. ¿Por dónde empiezo? Primero recupera tus datos utilizando la guía de recuperación y exportación, luego sigue el Paso 2 anterior para importar la exportación limpia a Apidog.

Conclusión

Migrar de inso a Apidog CLI es principalmente un trabajo de traducción: exporta tus especificaciones y conjuntos, impórtalos a Apidog, reescribe inso run test e inso run collection como apidog run, cambia --env a -e, y apunta tus reporteros a la salida CLI/HTML/JSON de Apidog. Mantén Spectral si haces linting, porque Apidog valida al importar pero no reemplaza un conjunto de reglas personalizado.

La recompensa es una plataforma en lugar de una pila que tienes que seguir uniendo. ¿Listo para probarlo? Descarga Apidog y ejecuta tu primer apidog run contra la especificación que acabas de exportar.