Insomnia est un client API créé par Kong pour envoyer des requêtes et inspecter les réponses. Il est réputé pour son interface épurée et sans distraction, et prend en charge HTTP, REST, GraphQL, gRPC, SOAP et WebSocket au même endroit. Les développeurs l'utilisent lorsqu'ils souhaitent un outil plus léger qu'un IDE lourd, mais toujours capable de réaliser un travail de test sérieux.
Ce guide vous montre comment tester une API dans Insomnia du début à la fin. Vous allez créer une collection de requêtes, envoyer et inspecter une réponse, configurer des environnements pour pouvoir changer les URL de base et les jetons, et utiliser la fonctionnalité de suites de tests pour écrire des assertions qui s'exécutent automatiquement. Les exemples utilisent une API publique afin que vous puissiez suivre immédiatement.
Installer Insomnia et créer une requête
Téléchargez Insomnia depuis le site officiel de Kong et installez-le pour votre plateforme. Au premier lancement, Insomnia vous demande si vous souhaitez vous connecter. Vous pouvez choisir de travailler localement sans compte si vous préférez, et Insomnia stocke vos données sur votre propre machine. La synchronisation cloud est facultative et est ce qui a changé dans la version 8, que nous abordons ci-dessous.
Insomnia organise le travail en collections et documents. Cliquez sur **Créer** dans le tableau de bord et choisissez **Collection de requêtes**. Donnez-lui un nom clair comme « Tests API utilisateur ». Dans la collection, cliquez sur le bouton **+** et choisissez **Requête HTTP**.
Une requête nécessite une méthode et une URL. Choisissez GET et entrez un point de terminaison réel. Le service JSONPlaceholder fonctionne bien pour la pratique :
GET https://jsonplaceholder.typicode.com/users/1
Cliquez sur **Envoyer**. Le panneau de droite affiche le corps de la réponse, le code de statut, le temps de réponse et la taille. Insomnia formate automatiquement le JSON et vous permet de filtrer le corps avec une requête JSONPath ou XPath, ce qui est pratique lorsqu'une réponse est volumineuse.
Configurer les méthodes, les paramètres et l'authentification
Pour toute action au-delà d'une simple lecture, vous définirez plus d'éléments sur la requête. Insomnia les regroupe sous des onglets situés sous la barre d'URL.
L'onglet **Corps** gère les charges utiles des requêtes. Pour un POST, choisissez **JSON** et entrez les données :
{
"name": "Daniel Okafor",
"email": "daniel.okafor@example.com"
}
Insomnia définit l'en-tête Content-Type pour vous lorsque vous choisissez un type de corps. L'onglet **Requête** vous permet d'ajouter des paramètres de chaîne de requête sans modifier l'URL manuellement, ce qui maintient une longue URL lisible et vous permet d'activer ou de désactiver des paramètres individuels. L'onglet **En-têtes** est destiné à tout autre élément que l'API attend, comme un X-Request-Id personnalisé ou un en-tête Accept pour négocier le format de réponse.
L'onglet **Auth** gère les identifiants. Insomnia prend en charge une longue liste de schémas : Jeton Bearer, Authentification de base, Clé API, OAuth 1.0 et 2.0, AWS IAM, et d'autres. Choisissez le schéma utilisé par votre API et remplissez les champs. Pour une API protégée par un jeton, choisissez **Jeton Bearer** et collez le jeton, ou mieux, référencez une variable d'environnement pour que le jeton ne soit pas codé en dur. Si vous n'êtes pas sûr des codes de statut à attendre, la référence sur les codes de statut HTTP que les API REST devraient utiliser est un bon complément.
Configurer les environnements et les variables
Les environnements vous permettent d'éviter de répéter des valeurs et facilitent le changement de cibles. Dans Insomnia, un environnement est un objet JSON de variables attaché à une collection.
Cliquez sur le menu déroulant d'environnement près du haut de la barre latérale et ouvrez **Gérer les environnements**. L'**Environnement de base** contient les valeurs partagées. Ajoutez des sous-environnements pour chaque cible :
{
"base_url": "https://jsonplaceholder.typicode.com",
"auth_token": "your-token-here"
}
Créez un second sous-environnement pour la production avec des valeurs différentes. Référencez une variable dans n'importe quelle requête avec la syntaxe de modèle {{ _.base_url }}, de sorte qu'une URL devienne :
GET {{ _.base_url }}/users/1
Changez l'environnement actif depuis le menu déroulant et chaque requête utilisant la variable sera mise à jour. Insomnia prend également en charge les **balises de modèle**, de petites fonctions que vous pouvez insérer dans un champ pour générer un horodatage, un UUID, ou pour extraire une valeur d'une réponse précédente. Cette dernière option vous permet d'enchaîner les requêtes, par exemple en capturant un jeton d'une réponse de connexion et en l'injectant dans les requêtes ultérieures.
La balise de modèle de réponse mérite un examen plus approfondi, car c'est ainsi qu'Insomnia gère les dépendances de requêtes sans script. Vous ajoutez une balise qui dit « utiliser le corps de la requête de connexion, au JSONPath $.token », et vous la placez dans l'en-tête Authorization de chaque requête protégée. Lorsque vous exécutez une requête protégée, Insomnia exécute d'abord la requête de connexion si nécessaire, extrait le jeton et le substitue. La chaîne reste déclarative, il n'y a donc pas de code de liaison à maintenir. Pour une idée plus large du regroupement des vérifications connexes, consultez la présentation de l'exemple de cas de test API.
Écrire des suites de tests avec des assertions
L'envoi d'une requête vous montre la réponse. Pour vérifier automatiquement que la réponse est correcte, vous utilisez la fonctionnalité de **suites de tests** d'Insomnia, parfois affichée comme l'onglet **Tests unitaires** sur une collection.
Ouvrez votre collection et passez à la vue **Tests**. Créez une **suite de tests**, puis ajoutez-y des tests individuels. Chaque test est un petit morceau de JavaScript. Insomnia utilise la bibliothèque d'assertions Chai et vous fournit une aide pour envoyer une requête et récupérer sa réponse. Un test ressemble à ceci :
const response = await insomnia.send();
expect(response.status).to.equal(200);
Vous pouvez être plus précis en analysant le corps et en vérifiant les champs :
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");
Chaque test de la suite cible une requête de votre collection, sélectionnée dans un menu déroulant, afin que le test sache quoi envoyer. Cliquez sur **Exécuter les tests** et Insomnia exécute chaque test de la suite, affichant chacun comme réussi ou échoué avec le temps qu'il a fallu. C'est votre contrôle de régression : exécutez la suite après un changement et vous voyez immédiatement si l'API se comporte toujours comme prévu.
La façon dont vous organisez les suites est importante à mesure que leur nombre augmente. Un modèle courant est une suite par ressource, de sorte que tous les tests d'articles sont regroupés et tous les tests d'utilisateurs sont regroupés. À l'intérieur d'une suite, chaque test doit se concentrer sur un seul comportement : un test pour le scénario nominal, des tests distincts pour le cas « non trouvé » et le cas « erreur de validation ». Lorsqu'un test échoue, son nom et sa portée limitée devraient vous indiquer ce qui ne va pas sans que vous ayez à lire le code d'assertion. Pour une analyse plus approfondie de la rédaction de bonnes vérifications, le guide sur les assertions API explique quoi affirmer et quoi ignorer, et l'article sur les suites de tests pour l'automatisation des tests API couvre la structuration des suites à mesure qu'elles se développent.
Exécuter depuis la ligne de commande avec Inso
Une interface graphique est bien pour le développement, mais l'automatisation a besoin de quelque chose sans interface graphique. Insomnia propose un compagnon en ligne de commande appelé **Inso**. Après avoir exporté ou synchronisé votre collection, vous exécutez votre suite de tests depuis un terminal :
inso run test "User API tests"
Inso se termine avec un code de statut non nul si un test échoue, ce qui est exactement ce dont une pipeline CI a besoin pour marquer une construction comme défectueuse. Vous pouvez intégrer cela dans GitHub Actions ou tout autre exécuteur afin que vos tests Insomnia s'exécutent à chaque push, détectant un point d'accès défectueux avant qu'il n'atteigne un coéquipier ou la production. Inso peut également lint votre spécification API et générer des rapports de test dans des formats standard, ce qui le rend utile au-delà de la simple exécution de suites. L'article sur l'automatisation des tests API en CI/CD montre le modèle général, qui s'applique parfaitement à Inso.
Le changement cloud de la version 8, et une alternative
Insomnia 8 s'est orienté vers un modèle « cloud-first ». Par défaut, il incitait les utilisateurs à créer un compte Kong et à stocker les projets dans le cloud. Cette décision a frustré une partie de la communauté, car les versions précédentes étaient entièrement locales et conviviales hors ligne. Les versions ultérieures ont restauré une option plus claire, locale uniquement ou « Bloc-notes », mais cet épisode a poussé certaines équipes à chercher des alternatives, en particulier dans les environnements où les données ne peuvent pas quitter les locaux.
Si cela vous décrit, Apidog mérite d'être examiné. C'est une plateforme API tout-en-un couvrant la conception, le débogage, la simulation, les tests et la documentation, et elle importe les exportations d'Insomnia afin que vous n'ayez pas à recommencer. Apidog vous permet de construire des assertions visuellement sans écrire de JavaScript, tout en prenant en charge les scripts lorsque vous le souhaitez. Parce que la spécification API, les données de test et le serveur de simulation partagent un seul projet, vos tests restent alignés avec le contrat réel au lieu de dériver. Vous pouvez télécharger Apidog et importer une collection Insomnia pour comparer côte à côte. Pour un aperçu plus large, la liste des outils de test API en ligne gratuits couvre plusieurs options.
Insomnia reste un client solide et ciblé, particulièrement pour les développeurs solo et les petites équipes qui apprécient son interface minimale, sans distraction et son démarrage rapide. Le bon choix dépend de la façon dont votre équipe travaille et de la part du cycle de vie de l'API que vous souhaitez gérer en un seul endroit plutôt que de la répartir sur plusieurs outils distincts.
Questions fréquemment posées
Insomnia est-il gratuit ?
Insomnia propose un forfait gratuit qui couvre l'utilisation individuelle, y compris l'envoi de requêtes et l'exécution de suites de tests en local. Les forfaits payants ajoutent la collaboration d'équipe et des limites de synchronisation cloud plus importantes. Vous pouvez utiliser le client de base sans payer, et les versions récentes vous permettent de travailler entièrement en local si vous préférez ne pas utiliser la synchronisation cloud.
Quels protocoles Insomnia prend-il en charge ?
Insomnia gère HTTP, REST, GraphQL, gRPC, SOAP et WebSocket. La configuration des requêtes diffère selon le protocole, mais l'inspection des réponses et, pour les requêtes basées sur HTTP, les assertions des suites de tests fonctionnent de manière cohérente pour tous.
Comment écrire des assertions dans Insomnia ?
Utilisez la fonctionnalité des suites de tests. Ouvrez la vue Tests sur une collection, créez une suite et ajoutez des tests. Chaque test est un script JavaScript qui appelle insomnia.send() pour exécuter une requête, puis utilise des assertions de type Chai expect sur le statut, les en-têtes ou le corps analysé. Exécutez toute la suite avec le bouton Exécuter les tests.
Qu'est-ce qui a changé dans Insomnia 8 ?
Insomnia 8 est passé par défaut à un modèle « cloud-first », incitant les utilisateurs à se connecter à un compte Kong et à synchroniser leurs projets dans le cloud. Certains utilisateurs n'ont pas apprécié le flux de compte obligatoire et le passage d'une application purement locale. Les mises à jour ultérieures ont ajouté des options plus claires pour une utilisation locale uniquement, mais ce changement a poussé certaines équipes à évaluer des alternatives.
Puis-je exécuter des tests Insomnia dans un pipeline CI ?
Oui. Utilisez Inso, le compagnon en ligne de commande. Exportez ou synchronisez votre collection, puis exécutez inso run test "<suite name>" dans votre pipeline. Inso renvoie un code de sortie non nul en cas d'échec, ce qui permet à la CI d'échouer automatiquement la build lorsqu'un test API est rompu.