Insomnia es un cliente API creado por Kong para enviar solicitudes e inspeccionar respuestas. Es conocido por su interfaz limpia y sin distracciones, y por su soporte para HTTP, REST, GraphQL, gRPC, SOAP y WebSocket en un solo lugar. Los desarrolladores lo eligen cuando quieren algo más ligero que una herramienta pesada estilo IDE, pero que aún sea capaz de realizar pruebas reales.
Esta guía muestra cómo probar una API en Insomnia de principio a fin. Creará una colección de solicitudes, enviará e inspeccionará una respuesta, configurará entornos para poder cambiar URLs base y tokens, y utilizará la función de suites de pruebas para escribir aserciones que se ejecuten automáticamente. Los ejemplos utilizan una API pública para que pueda seguirla de inmediato.
Instalar Insomnia y crear una solicitud
Descargue Insomnia desde el sitio oficial de Kong e instálelo para su plataforma. En el primer lanzamiento, Insomnia le pregunta si desea iniciar sesión. Puede optar por trabajar localmente sin una cuenta si lo prefiere, e Insomnia almacenará sus datos en su propia máquina. La sincronización en la nube es opcional y es lo que cambió en la versión 8, que cubrimos a continuación.
Insomnia organiza el trabajo en colecciones y documentos. Haga clic en Crear en el panel y elija Colección de solicitudes. Dele un nombre claro como "Pruebas de la API de usuario". Dentro de la colección, haga clic en el botón + y elija Solicitud HTTP.
Una solicitud necesita un método y una URL. Elija GET e introduzca un endpoint real. El servicio JSONPlaceholder funciona bien para practicar:
GET https://jsonplaceholder.typicode.com/users/1
Haga clic en Enviar. El panel derecho muestra el cuerpo de la respuesta, el código de estado, el tiempo de respuesta y el tamaño. Insomnia imprime JSON de forma bonita automáticamente y le permite filtrar el cuerpo con una consulta JSONPath o XPath, lo cual es útil cuando una respuesta es grande.
Configurar métodos, parámetros y autenticación
Para cualquier cosa más allá de una lectura simple, configurará más en la solicitud. Insomnia agrupa estas opciones en pestañas debajo de la barra de URL.
La pestaña Cuerpo maneja las cargas de solicitud. Para un POST, elija JSON e introduzca los datos:
{
"name": "Daniel Okafor",
"email": "daniel.okafor@example.com"
}
Insomnia establece el encabezado Content-Type por usted cuando elige un tipo de cuerpo. La pestaña Consulta le permite añadir parámetros de cadena de consulta sin editar la URL a mano, lo que mantiene una URL larga legible y le permite activar y desactivar parámetros individuales. La pestaña Encabezados es para cualquier otra cosa que la API espere, como un X-Request-Id personalizado o un encabezado Accept para negociar el formato de respuesta.
La pestaña Auth maneja las credenciales. Insomnia soporta una larga lista de esquemas: Bearer Token, Basic Auth, API Key, OAuth 1.0 y 2.0, AWS IAM, y otros. Elija el esquema que utiliza su API y rellene los campos. Para una API protegida por token, elija Bearer Token y pegue el token, o mejor, haga referencia a una variable de entorno para que el token no esté codificado. Si no está seguro de qué códigos de estado esperar, la referencia sobre códigos de estado HTTP que las API REST deberían usar es una buena compañera.
Configurar entornos y variables
Los entornos le permiten evitar la repetición de valores y facilitan el cambio de objetivos. En Insomnia, un entorno es un objeto JSON de variables adjunto a una colección.
Haga clic en el desplegable de entorno cerca de la parte superior de la barra lateral y abra Administrar entornos. El Entorno Base contiene valores compartidos. Añada subentornos para cada objetivo:
{
"base_url": "https://jsonplaceholder.typicode.com",
"auth_token": "your-token-here"
}
Cree un segundo subentorno para producción con diferentes valores. Haga referencia a una variable en cualquier solicitud con la sintaxis de plantilla {{ _.base_url }}, de modo que una URL se convierte en:
GET {{ _.base_url }}/users/1
Cambie el entorno activo desde el desplegable y cada solicitud que use la variable se actualizará. Insomnia también admite etiquetas de plantilla, pequeñas funciones que puede colocar en un campo para generar una marca de tiempo, un UUID o extraer un valor de una respuesta anterior. Esto último le permite encadenar solicitudes, por ejemplo, capturando un token de una respuesta de inicio de sesión y alimentándolo en solicitudes posteriores.
La etiqueta de plantilla de respuesta merece un examen más detallado porque es la forma en que Insomnia maneja las dependencias de las solicitudes sin scripts. Añade una etiqueta que dice "usar el cuerpo de la solicitud de inicio de sesión, en el JSONPath $.token", y la coloca en el encabezado Authorization de cada solicitud protegida. Cuando ejecuta una solicitud protegida, Insomnia ejecuta la solicitud de inicio de sesión primero si es necesario, extrae el token y lo sustituye. La cadena permanece declarativa, por lo que no hay código de unión que mantener. Para la idea más amplia de agrupar verificaciones relacionadas, consulte el tutorial de ejemplo de caso de prueba de API.
Escribir suites de pruebas con aserciones
Enviar una solicitud le muestra la respuesta. Para verificar que la respuesta es correcta, automáticamente, utilice la función de suites de pruebas de Insomnia, a veces mostrada como la pestaña Pruebas Unitarias en una colección.
Abra su colección y cambie a la vista Pruebas. Cree una suite de pruebas y luego añada pruebas individuales dentro de ella. Cada prueba es un pequeño fragmento de JavaScript. Insomnia utiliza la librería de aserciones Chai y le proporciona una ayuda para enviar una solicitud y obtener su respuesta. Una prueba se ve así:
const response = await insomnia.send();
expect(response.status).to.equal(200);
Puede ser más específico analizando el cuerpo y comprobando los campos:
const response = await insomnia.send();
const body = JSON.parse(response.data);
expect(response.status).to.equal(200);
expect(body.email).to.equal("daniel.okafor@example.com");
expect(body).to.have.property("id");
Cada prueba en la suite apunta a una solicitud de su colección, elegida de un menú desplegable, para que la prueba sepa qué enviar. Haga clic en Ejecutar pruebas e Insomnia ejecutará cada prueba en la suite, mostrando cada una como aprobada o fallida con el tiempo que tardó. Esta es su verificación de regresión: ejecute la suite después de un cambio e inmediatamente verá si la API sigue funcionando correctamente.
La forma en que organiza las suites importa a medida que aumenta el número. Un patrón común es una suite por recurso, de modo que todas las pruebas de artículos y todas las pruebas de usuario se agrupan. Dentro de una suite, mantenga cada prueba centrada en un solo comportamiento: una prueba para el "camino feliz", pruebas separadas para el caso de "no encontrado" y el caso de "error de validación". Cuando una prueba falla, su nombre y su alcance limitado deberían decirle qué se rompió sin que tenga que leer el código de la aserción. Para una mirada más profunda a la escritura de buenas verificaciones, la guía sobre aserciones de API explica qué afirmar y qué omitir, y el artículo sobre suites de pruebas para la automatización de pruebas de API cubre la estructuración de suites a medida que crecen.
Ejecutar desde la línea de comandos con Inso
Una GUI está bien para el desarrollo, pero la automatización necesita algo sin interfaz gráfica. Insomnia incluye un compañero de línea de comandos llamado Inso. Después de exportar o sincronizar su colección, ejecuta su suite de pruebas desde una terminal:
inso run test "User API tests"
Inso sale con un código de estado distinto de cero si alguna prueba falla, que es exactamente lo que necesita una pipeline de CI para marcar una compilación como rota. Puede integrar esto en GitHub Actions o cualquier otro ejecutor para que sus pruebas de Insomnia se ejecuten en cada push, detectando un endpoint defectuoso antes de que llegue a un compañero de equipo o a producción. Inso también puede lintar su especificación de API y generar informes de prueba en formatos estándar, lo que lo hace útil más allá de simplemente ejecutar suites. El artículo sobre automatización de pruebas de API en CI/CD muestra el patrón general, que se aplica limpiamente a Inso.
El cambio a la nube de la versión 8 y una alternativa
Insomnia 8 se orientó hacia un modelo "cloud-first". Por defecto, impulsaba a los usuarios a crear una cuenta Kong y almacenar proyectos en la nube. Esa decisión frustró a parte de la comunidad, ya que las versiones anteriores habían sido completamente locales y amigables con el trabajo sin conexión. Las versiones posteriores restauraron una opción más clara solo local o "Scratch Pad", pero el episodio hizo que algunos equipos buscaran alternativas, especialmente en entornos donde los datos no pueden salir del edificio.
Si esa es su situación, Apidog vale la pena considerarlo. Es una plataforma API todo en uno que cubre diseño, depuración, mocking, pruebas y documentación, e importa exportaciones de Insomnia para que no tenga que empezar de nuevo. Apidog le permite construir aserciones visualmente sin escribir JavaScript, al tiempo que sigue admitiendo scripts cuando los necesita. Debido a que la especificación de la API, los datos de prueba y el servidor simulado comparten un mismo proyecto, sus pruebas se mantienen alineadas con el contrato real en lugar de desviarse. Puede descargar Apidog e importar una colección de Insomnia para comparar lado a lado. Para un análisis más amplio, la lista de herramientas de prueba de API en línea gratuitas cubre varias opciones.
Insomnia sigue siendo un cliente potente y centrado, especialmente para desarrolladores individuales y equipos pequeños que valoran su interfaz mínima y sin distracciones, y su rápido inicio. La elección correcta depende de cómo trabaja su equipo y de qué parte del ciclo de vida de la API desea manejar en un solo lugar en lugar de distribuirlo entre herramientas separadas.
Preguntas frecuentes
¿Es Insomnia gratuito?
Insomnia tiene un nivel gratuito que cubre el uso individual, incluyendo el envío de solicitudes y la ejecución de suites de pruebas localmente. Los planes de pago añaden colaboración en equipo y mayores límites de sincronización en la nube. Puede usar el cliente principal sin pagar, y las versiones recientes le permiten trabajar completamente localmente si prefiere no usar la sincronización en la nube.
¿Qué protocolos soporta Insomnia?
Insomnia maneja HTTP, REST, GraphQL, gRPC, SOAP y WebSocket. La configuración de la solicitud difiere por protocolo, pero la inspección de la respuesta y, para las solicitudes basadas en HTTP, las aserciones de la suite de pruebas funcionan de manera consistente en todos ellos.
¿Cómo escribo aserciones en Insomnia?
Utilice la función de suites de pruebas. Abra la vista Pruebas en una colección, cree una suite y añada pruebas. Cada prueba es JavaScript que llama a insomnia.send() para ejecutar una solicitud, y luego usa aserciones expect al estilo Chai sobre el estado, los encabezados o el cuerpo analizado. Ejecute toda la suite con el botón "Run Tests".
¿Qué cambió en Insomnia 8?
Insomnia 8 cambió a un modelo "cloud-first" por defecto, pidiendo a los usuarios que iniciaran sesión en una cuenta de Kong y sincronizaran proyectos en la nube. A algunos usuarios no les gustó el flujo de cuenta obligatorio y el alejamiento de una aplicación puramente local. Actualizaciones posteriores añadieron opciones más claras solo locales, pero el cambio impulsó a algunos equipos a evaluar alternativas.
¿Puedo ejecutar pruebas de Insomnia en una pipeline de CI?
Sí. Utilice Inso, el compañero de línea de comandos. Exporte o sincronice su colección, luego ejecute inso run test "<nombre de la suite>" en su pipeline. Inso devuelve un código de salida distinto de cero en caso de fallo, por lo que CI puede fallar la compilación automáticamente cuando una prueba de API se rompe.