Cómo Usar Insomnia para Probar una API

Insomnia es un cliente API de Kong para enviar solicitudes e inspeccionar respuestas. Soporta HTTP, REST, GraphQL, gRPC, SOAP y WebSocket desde una interfaz limpia. Es útil cuando necesita probar APIs sin usar una herramienta pesada tipo IDE, pero con suficientes funciones para depurar, parametrizar y automatizar verificaciones.

Prueba Apidog hoy

En esta guía probará una API en Insomnia de principio a fin: creará una colección, enviará una solicitud, inspeccionará la respuesta, configurará entornos para cambiar URLs base y tokens, y escribirá aserciones con suites de pruebas. Los ejemplos usan JSONPlaceholder para que pueda seguirlos sin configurar backend propio.

Instalar Insomnia y crear una solicitud

Descargue Insomnia desde el sitio oficial de Kong e instálelo en su plataforma.

Al abrirlo por primera vez, Insomnia le preguntará si desea iniciar sesión. Puede trabajar localmente sin cuenta si no necesita sincronización en la nube. Insomnia almacenará sus datos en su máquina.

Para crear su primera solicitud:

1. Abra Insomnia.
2. Haga clic en Crear.
3. Seleccione Colección de solicitudes.
4. Asigne un nombre, por ejemplo: Pruebas de la API de usuario.
5. Dentro de la colección, haga clic en +.
6. Elija Solicitud HTTP.
7. Configure el método como GET.
8. Introduzca esta URL:

GET https://jsonplaceholder.typicode.com/users/1

Haga clic en Enviar.

Insomnia mostrará:

• Código de estado HTTP.
• Tiempo de respuesta.
• Tamaño de la respuesta.
• Cuerpo de respuesta formateado.
• Encabezados recibidos.

Para respuestas JSON grandes, use el filtro JSONPath en el panel de respuesta. Por ejemplo, si desea inspeccionar solo el email:

$.email

Configurar métodos, parámetros y autenticación

Una solicitud real suele necesitar cuerpo, parámetros, encabezados o autenticación. Insomnia agrupa estas opciones en pestañas debajo de la barra de URL.

Enviar un cuerpo JSON

Para probar un endpoint POST:

1. Cambie el método a POST.
2. Abra la pestaña Cuerpo.
3. Seleccione JSON.
4. Escriba el payload:

{
  "name": "Daniel Okafor",
  "email": "[e-mail]"
}

Cuando selecciona JSON, Insomnia configura automáticamente el encabezado:

Content-Type: application/json

Añadir parámetros de consulta

Use la pestaña Consulta para añadir query params sin editar manualmente la URL.

Por ejemplo, en lugar de escribir:

GET https://jsonplaceholder.typicode.com/posts?userId=1

Configure:

Nombre	Valor
userId	1

Esto facilita activar, desactivar o modificar parámetros durante las pruebas.

Añadir encabezados

Use la pestaña Encabezados para valores como:

Accept: application/json
X-Request-Id: test-123

Esto es útil para probar negociación de contenido, trazabilidad o comportamiento condicionado por headers.

Configurar autenticación

Abra la pestaña Auth y seleccione el esquema que usa su API. Insomnia soporta, entre otros:

• Bearer Token.
• Basic Auth.
• API Key.
• OAuth 1.0.
• OAuth 2.0.
• AWS IAM.

Para una API protegida por token:

1. Abra Auth.
2. Seleccione Bearer Token.
3. Pegue el token o use una variable de entorno.

Mejor que escribir el token directamente, use una variable:

{{ _.auth_token }}

Así evita duplicar credenciales en cada solicitud.

Si necesita validar qué códigos de estado debería devolver su API, consulte esta referencia sobre códigos de estado HTTP que las API REST deberían usar.

Configurar entornos y variables

Los entornos evitan repetir valores como URLs base, tokens o IDs de prueba. En Insomnia, un entorno es un objeto JSON asociado a una colección.

Para crear uno:

1. Abra el desplegable de entorno en la parte superior de la barra lateral.
2. Seleccione Administrar entornos.
3. Edite el Entorno Base o cree subentornos.
4. Añada variables en formato JSON.

Ejemplo:

{
  "base_url": "https://jsonplaceholder.typicode.com",
  "auth_token": "your-token-here"
}

Ahora puede reemplazar una URL fija como esta:

GET https://jsonplaceholder.typicode.com/users/1

Por una URL parametrizada:

GET {{ _.base_url }}/users/1

Cuando cambie el entorno activo, todas las solicitudes que usen {{ _.base_url }} apuntarán al nuevo destino.

Un patrón común es crear entornos como:

{
  "base_url": "https://api.dev.example.com",
  "auth_token": "dev-token"
}

{
  "base_url": "https://api.staging.example.com",
  "auth_token": "staging-token"
}

{
  "base_url": "https://api.example.com",
  "auth_token": "prod-token"
}

Encadenar solicitudes con etiquetas de plantilla

Insomnia también soporta etiquetas de plantilla. Son funciones que puede insertar en campos de solicitud para generar o extraer valores dinámicos.

Puede usarlas para:

• Generar timestamps.
• Crear UUIDs.
• Reutilizar valores de entorno.
• Extraer datos desde una respuesta anterior.
• Encadenar login + solicitudes protegidas.

Ejemplo de flujo:

1. Cree una solicitud POST /login.
2. La respuesta devuelve un token:

{
  "token": "abc123"
}

1. En otra solicitud protegida, configure el encabezado:

Authorization: Bearer <token extraído de /login>

Con la etiqueta de respuesta, Insomnia puede ejecutar la solicitud de login si es necesario, leer el valor con JSONPath como:

$.token

Y reutilizarlo en las solicitudes siguientes.

Este enfoque mantiene el flujo declarativo y evita escribir scripts de unión solo para pasar datos entre requests.

Para organizar verificaciones relacionadas, revise este ejemplo de caso de prueba de API.

Escribir suites de pruebas con aserciones

Enviar una solicitud manualmente sirve para depurar. Para verificar automáticamente que una API sigue funcionando, use las suites de pruebas de Insomnia. En algunas versiones aparecen como Pruebas Unitarias dentro de una colección.

Para crear una suite:

1. Abra su colección.
2. Cambie a la vista Pruebas.
3. Cree una suite de pruebas.
4. Añada una prueba.
5. Seleccione la solicitud que debe ejecutarse.
6. Escriba las aserciones en JavaScript.

Insomnia usa Chai para las aserciones y expone insomnia.send() para ejecutar la solicitud asociada.

Ejemplo mínimo:

const response = await insomnia.send();

expect(response.status).to.equal(200);

Ejemplo con validación del cuerpo:

const response = await insomnia.send();
const body = JSON.parse(response.data);

expect(response.status).to.equal(200);
expect(body).to.have.property("id");
expect(body.email).to.equal("[e-mail]");

Para la solicitud:

GET https://jsonplaceholder.typicode.com/users/1

La respuesta incluye un email como:

{
  "id": 1,
  "name": "Leanne Graham",
  "email": "[e-mail]"
}

Por eso la aserción anterior valida tanto el estado como un campo específico del payload.

También puede validar encabezados:

const response = await insomnia.send();

expect(response.status).to.equal(200);
expect(response.headers["content-type"]).to.include("application/json");

Organizar suites de pruebas

A medida que crece la colección, no conviene tener todas las pruebas mezcladas. Use una estructura por recurso o dominio funcional.

Ejemplo:

Suites
├── Users
│   ├── GET /users/:id devuelve 200
│   ├── GET /users/:id devuelve estructura esperada
│   └── GET /users/:id inexistente devuelve 404
├── Posts
│   ├── GET /posts devuelve lista
│   └── POST /posts valida payload requerido
└── Auth
    ├── POST /login devuelve token
    └── POST /login con credenciales inválidas devuelve 401

Mantenga cada prueba enfocada en un comportamiento. Evite pruebas demasiado amplias como “la API funciona”, porque cuando fallen no sabrá qué se rompió.

Buen patrón:

const response = await insomnia.send();

expect(response.status).to.equal(404);

Mejor aún, si el endpoint devuelve un cuerpo de error estable:

const response = await insomnia.send();
const body = JSON.parse(response.data);

expect(response.status).to.equal(404);
expect(body).to.have.property("message");

Para profundizar en qué conviene validar, consulte la guía sobre aserciones de API. Para estructurar suites más grandes, revise el artículo sobre suites de pruebas para la automatización de pruebas de API.

Ejecutar pruebas desde la línea de comandos con Inso

La interfaz gráfica es útil durante el desarrollo, pero CI/CD necesita ejecución sin GUI. Insomnia incluye una herramienta de línea de comandos llamada Inso.

Después de exportar o sincronizar su colección, puede ejecutar una suite desde la terminal:

inso run test "User API tests"

Si alguna prueba falla, Inso devuelve un código de salida distinto de cero. Esto permite que una pipeline marque el build como fallido.

Ejemplo conceptual para CI:

inso run test "User API tests"
if [ $? -ne 0 ]; then
  echo "API tests failed"
  exit 1
fi

En una pipeline, el flujo típico sería:

1. Instalar Inso.
2. Obtener la colección o proyecto.
3. Seleccionar el entorno correcto.
4. Ejecutar la suite.
5. Fallar la compilación si alguna aserción falla.

Inso también puede lintar especificaciones de API y generar reportes de prueba en formatos estándar, por lo que no se limita a ejecutar suites.

Para el patrón general de automatización, consulte esta guía sobre automatización de pruebas de API en CI/CD.

El cambio a la nube en Insomnia 8 y una alternativa

Insomnia 8 se movió hacia un modelo cloud-first. Por defecto, impulsaba a los usuarios a crear una cuenta de Kong y almacenar proyectos en la nube.

Esto frustró a parte de la comunidad, porque versiones anteriores permitían un flujo completamente local y cómodo para trabajo sin conexión. Versiones posteriores restauraron una opción local más clara, como Scratch Pad, pero el cambio hizo que algunos equipos evaluaran alternativas, especialmente en entornos donde los datos no pueden salir de la organización.

Si ese es su caso, Apidog es una opción a considerar. Es una plataforma API todo en uno para diseño, depuración, mocking, pruebas y documentación. También permite importar exportaciones de Insomnia para no empezar desde cero.

Apidog permite construir aserciones visualmente sin escribir JavaScript, pero sigue admitiendo scripts cuando los necesita. Al mantener la especificación de API, los datos de prueba y el servidor mock en un mismo proyecto, las pruebas pueden mantenerse alineadas con el contrato real de la API.

Puede descargar Apidog e importar una colección de Insomnia para compararlos lado a lado. Para revisar más opciones, esta lista de herramientas de prueba de API en línea gratuitas cubre varias alternativas.

Insomnia sigue siendo un cliente potente y enfocado, especialmente para desarrolladores individuales y equipos pequeños que valoran una interfaz mínima y un inicio rápido. La mejor elección depende de cómo trabaja su equipo y de cuánto del ciclo de vida de la API quiere centralizar en una sola herramienta.

Preguntas frecuentes

¿Es Insomnia gratuito?

Insomnia tiene un nivel gratuito para uso individual, incluyendo envío de solicitudes y ejecución local de suites de pruebas. Los planes de pago añaden colaboración en equipo y mayores límites de sincronización en la nube. También puede trabajar localmente si no desea usar sincronización.

¿Qué protocolos soporta Insomnia?

Insomnia soporta HTTP, REST, GraphQL, gRPC, SOAP y WebSocket. La configuración cambia según el protocolo, pero la inspección de respuestas y las pruebas basadas en HTTP siguen un flujo similar.

¿Cómo escribo aserciones en Insomnia?

Use las suites de pruebas. Abra la vista Pruebas en una colección, cree una suite y añada pruebas. Cada prueba ejecuta una solicitud con:

const response = await insomnia.send();

Luego valide con expect al estilo Chai:

expect(response.status).to.equal(200);

También puede analizar el cuerpo:

const body = JSON.parse(response.data);
expect(body).to.have.property("id");

¿Qué cambió en Insomnia 8?

Insomnia 8 adoptó un modelo cloud-first por defecto, solicitando iniciar sesión con una cuenta de Kong y sincronizar proyectos en la nube. A algunos usuarios no les gustó el flujo obligatorio de cuenta ni el alejamiento de una aplicación puramente local. Versiones posteriores añadieron opciones locales más claras.

¿Puedo ejecutar pruebas de Insomnia en una pipeline de CI?

Sí. Use Inso, la herramienta de línea de comandos de Insomnia. Exporte o sincronice su colección y ejecute:

inso run test "<nombre de la suite>"

Si una prueba falla, Inso devuelve un código de salida distinto de cero, por lo que CI puede fallar la compilación automáticamente.