¿Qué es Inso? Insomnia CLI

Si ha utilizado el cliente API Insomnia, tiene un lugar gráfico para enviar solicitudes, diseñar especificaciones OpenAPI y escribir pruebas. Pero las herramientas gráficas se detienen en el límite de su máquina. En el momento en que desea que esas mismas pruebas se ejecuten dentro de una canalización de CI, o desea lintar una especificación en cada solicitud de extracción, necesita algo que resida en la terminal. Ese algo es inso.

Esta guía explica qué es inso, cómo instalarlo, los comandos exactos que utilizará a diario, cómo encuentra sus especificaciones y colecciones, y dónde aparecen sus límites. Al final, sabrá si la CLI de inso se adapta a su flujo de trabajo y qué buscar si no lo hace.

¿Qué es inso?

inso es el compañero de línea de comandos de Insomnia, el cliente API de código abierto ahora mantenido por Kong. Toma tres de las cosas que Insomnia hace en su interfaz de usuario y las hace programables: ejecutar pruebas, ejecutar colecciones de solicitudes y lintar especificaciones de API. Eso lo convierte en el puente entre Insomnia en su escritorio y las comprobaciones automatizadas que desea en CI/CD.

La versión corta de "¿qué es inso?": es cómo ejecutar su trabajo de Insomnia sin abrir Insomnia. Lo apunta a un documento de diseño o a una colección por su nombre, y se ejecuta con los mismos datos que su aplicación ya conoce.

Instalación de la CLI de inso

Tiene varias rutas documentadas. Elija la que coincida con su forma de distribuir.

Homebrew es el más sencillo en macOS y Linux:

brew install inso

Docker es la opción más limpia para los ejecutores de CI, donde no desea administrar una cadena de herramientas local:

docker pull kong/inso:latest

También puede obtener una descarga directa. Kong publica archivos zip para Windows, Linux y macOS en el sitio de documentación de la CLI de inso, lo cual es útil cuando desea una versión específica en un artefacto de compilación.

Históricamente, inso también se distribuía en npm como insomnia-inso. Esa ruta todavía existe, pero las rutas documentadas y recomendadas ahora son Homebrew, Docker y las descargas directas. Si está configurando algo nuevo, prefiera esas.

Confirme que la instalación se resolvió:

inso --version

Los comandos principales de inso

inso tiene una superficie pequeña y enfocada. Aquí están los comandos que realmente usará, con ejemplos reales.

inso run test

Ejecute un conjunto de pruebas unitarias que haya creado en Insomnia, contra un entorno con nombre:

inso run test "Payments API tests" --env "Staging"

La suite y el entorno se referencian por nombre, exactamente como aparecen en sus datos de Insomnia. El comando inso run test sale con un código distinto de cero si alguna aserción falla, lo que lo hace utilizable como una puerta de CI.

inso run collection

Ejecute cada solicitud de una colección en secuencia, nuevamente contra un entorno con nombre:

inso run collection "Checkout flow" --env "Staging"

Esto es lo más parecido a "reproducir toda la carpeta" en la interfaz de usuario. Es útil para pruebas de humo donde desea confirmar que una secuencia de endpoints responde como se espera.

inso lint spec

Valide un documento de diseño OpenAPI:

inso lint spec "Orders API"

Bajo el capó, inso lint spec utiliza Spectral, el linter de OpenAPI y JSON de código abierto de Stoplight. Esa es una fortaleza genuina que vale la pena destacar claramente: obtiene un linting de especificaciones real y basado en reglas con un conjunto de reglas maduro, no una verificación de sintaxis superficial. Si su equipo se preocupa por la aplicación de guías de estilo en las especificaciones, este comando es la razón por la que muchas personas usan inso.

inso export spec

Extraiga un documento de diseño a un archivo en el disco:

inso export spec "Orders API" --output orders.yaml

Útil cuando desea alimentar la especificación a otro generador, confirmar una instantánea o entregarla a una herramienta que espera un archivo YAML simple.

inso script

Ejecute un script con nombre definido en sus datos de Insomnia, pasando un entorno por ID:

inso script deploy-smoke --env env_9f2a

Esta es la puerta de escape para encadenar sus propios pasos personalizados.

Cómo inso encuentra sus especificaciones y colecciones

Esta es la parte que confunde a la gente, por lo que vale la pena ser preciso. inso no almacena nada por sí mismo. Lee de uno de dos lugares:

1. Un directorio .insomnia en su directorio de trabajo. Esto es lo que produce Git Sync de Insomnia, por lo que cuando usted confirma su proyecto API a un repositorio, inso puede leerlo directamente desde la extracción. Este es el patrón que desea para CI.
2. El directorio de datos de la aplicación Insomnia, si la aplicación está instalada en la máquina. Esto es conveniente localmente pero inútil en un ejecutor de CI limpio que nunca ha tenido la aplicación.

Puede anular la fuente explícitamente:

inso lint spec "Orders API" --workingDir ./api-project
# or point at an exact source
inso run test "Payments API tests" --src ./api-project/.insomnia

El modelo mental clave: inso referencia todo por nombre (o ID), y esos nombres se resuelven contra la fuente de datos que encontró. Si un nombre no está presente en el directorio .insomnia o en los datos de la aplicación, inso no puede ejecutarlo. No existe el concepto de apuntar inso a un archivo OpenAPI suelto y decir "prueba esto" a menos que ese archivo viva dentro de una estructura de proyecto de Insomnia.

Un ejemplo mínimo de CI

Aquí hay un trabajo de GitHub Actions que linta una especificación y ejecuta un conjunto de pruebas en cada push, utilizando el directorio .insomnia sincronizado con Git y confirmado en el repositorio:

name: API checks
on: [push]

jobs:
  inso:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install inso
        run: |
          curl -sSL https://github.com/Kong/insomnia/releases/latest/download/inso-linux-x64.zip -o inso.zip
          unzip inso.zip && sudo mv inso /usr/local/bin/
      - name: Lint the spec
        run: inso lint spec "Orders API" --workingDir .
      - name: Run the test suite
        run: inso run test "Payments API tests" --env "CI" --workingDir .

Debido a que ambos comandos salen con un código distinto de cero en caso de fallo, una especificación rota o una aserción fallida hace que el trabajo falle. Ese es el objetivo de trasladar estas comprobaciones fuera de la interfaz gráfica de usuario.

Limitaciones honestas

inso es bueno en lo que hace, pero tiene limitaciones reales.

Está ligado a las fuentes de datos de Insomnia. Sus especificaciones, colecciones y suites deben residir en un proyecto de Insomnia, expuestas ya sea a través de Git Sync o de la aplicación instalada. Si su equipo no usa Insomnia como fuente de verdad, inso no tiene nada sobre lo que operar.

Todo se referencia por nombre. Eso es legible, pero es frágil. Si renombra una suite en la interfaz de usuario, un trabajo de CI que codifica el nombre antiguo se romperá silenciosamente hasta la siguiente ejecución. Los nombres también deben ser lo suficientemente únicos para resolverse limpiamente.

El alcance es estrecho por diseño. inso ejecuta pruebas, ejecuta colecciones, linta especificaciones, exporta y ejecuta scripts. No es una plataforma de diseño, simulación, documentación y pruebas. Para cualquier cosa más allá de esos verbos, usted está de vuelta en la interfaz gráfica de usuario o buscando otras herramientas.

inso vs. la alternativa integrada

inso es un potente compañero de terminal cuando Insomnia ya es su cliente. La desventaja es que usted está uniendo piezas: Insomnia para diseño y depuración, inso para CI, reglas de Spectral para linting y herramientas separadas para simulaciones y documentación.

Apidog adopta la postura opuesta. Combina diseño, simulación, documentación y pruebas en una sola plataforma, y su CLI de Apidog ejecuta sus escenarios de prueba y colecciones desde la misma fuente de verdad, con pruebas impulsadas por datos, múltiples formatos de informe y recursos y ramas como código. Cabe señalar: la CLI de Apidog no incluye un linter de especificaciones independiente como lo hace inso con Spectral, por lo que si la aplicación de guías de estilo al estilo Spectral es su prioridad, inso tiene una ventaja real allí. Donde Apidog se adelanta es en la integración. No está uniendo cinco herramientas.

Si desea comparar los dos frente a frente, consulte Apidog CLI vs inso (CLI de Insomnia), o lea el trasfondo más profundo en qué es inso (CLI de Insomnia). Si ha decidido que inso no es el lugar adecuado, el resumen de las mejores alternativas a inso y la guía para migrar de inso a la CLI de Apidog detallan el proceso paso a paso. Para un contexto más amplio sobre los propios clientes GUI, Apidog vs Insomnia y cómo usar Insomnia para probar una API son buenos puntos de partida.

Puede descargar Apidog gratis si desea ver el enfoque integrado junto con su configuración de inso.