TL;DR

Insomnia to API client łączący projektowanie, debugowanie, testowanie i mockowanie API w jedno narzędzie, wspierający HTTP, GraphQL, gRPC, WebSocket i Server-Sent Events
Nowe funkcje takie jak pre-request i after-response scripts umożliwiają automatyzację testów bez opuszczania narzędzia
Dwa modele synchronizacji – Git sync (kontrola manualna, dla zespołów DevOps) i Cloud sync (end-to-end encrypted, dla startupów)
Enterprise security obejmuje SSO/SAML 2.0, SCIM provisioning, domain verification i polityki dostępu do storage’u
Collection runner pozwala na uruchomienie setek requestów jednocześnie z automatycznym raportowaniem
Automatyzacja testów polega na przechwyceniu tokena w after-response, zapisie go jako zmiennej i tworzeniu asercji w kolejnych żądaniach
Prompt feature umożliwia dynamiczne pytanie użytkownika o parametry – przydatne zarówno dla testowania, jak i wewnętrznych narzędzi
Onboarding zespołu zmienia się drastycznie – zamiast wysyłać curl scripts, zapraszasz osobę do organizacji
Storage control policies dają adminowi pełną kontrolę nad tym, gdzie przechowywane są dane (local vault, cloud, hybrid)

Czym jest Insomnia?

Insomnia to narzędzie klasy API client, które wspomaga pracę nad interfejsami aplikacji. W praktyce umożliwia projektowanie, debugowanie, testowanie i mockowanie API w jednym miejscu. Wspiera nie tylko tradycyjne REST, ale także GraphQL, gRPC, WebSocket i Server-Sent Events.

Według Mark’a z zespołu Insomnia, narzędzie prowadzi użytkownika przez cały cykl pracy nad API – od pierwszych testów na etapie developmentu, przez współpracę zespołu, aż do automatyzacji testów w pipeline’ach CI/CD. Zamiast przełączać się między różnymi aplikacjami, developer pracuje w jednym interfejsie.

Główne funkcje Insomnia

Insomnia skupia się na czterech kluczowych obszarach:

Design – użytkownik definiuje strukturę API (metody, parametry, response’y) bezpośrednio w narzędziu
Debug – testowanie endpointów w trakcie developmentu, widoczne błędy i response’y w czasie rzeczywistym
Mock – generowanie mock’owanych odpowiedzi, umożliwiające frontendowcowi pracę bez czekania na gotowy backend
Test – automatyzacja testów poprzez pre-request i after-response scripts z możliwością asercji

Dane z definicjami API mogą być przechowywane lokalnie, w Git repozytorium lub w cloud storage, co umożliwia synchronizację i wspólną pracę zespołu. Testy mogą być również uruchamiane automatycznie w pipeline’ach CI/CD – każdy pull request może być testowany bez ręcznej interwencji.

Nowe funkcje Insomnia

W ostatnich wersjach narzędzia pojawiło się kilka nowych funkcjonalności:

Pre-request i after-response scripts – możliwość uruchamiania niestandardowej logiki JavaScript przed wysłaniem requestu lub po odebraniu response’u. W praktyce: skrypt pre-request może ustawić nagłówek autoryzacji, a skrypt after-response może wyciągnąć token z response’u i zapisać go do zmiennych do następnego requestu. Eliminuje to potrzebę ręcznego kopiowania danych między requestami.

API mocking – definiowanie mock’owanych odpowiedzi dla endpointów bezpośrednio w Insomnia. Pozwala frontendowcowi na pracę niezależnie od postępu backendu.

Global environments i folder-level settings – konfiguracja może być zdefiniowana raz na poziomie globalnym lub folderu zamiast powielania dla każdego requestu. Szczególnie przydatne dla wspólnych nagłówków autoryzacji.

Global search – wyszukiwanie requestów, zmiennych i dokumentacji bez przechodzenia między folderami. Funkcjonalność podobna do spotlight search w edytorach kodu.

Collection runner – uruchamianie całej kolekcji requestów w jednym kliknięciu z możliwością ustawienia iteracji, opóźnień między requestami oraz weryfikacji asercji. Automatyzuje pracę testową.

Obsługiwane protokoły

Insomnia wspiera zarówno tradycyjne, jak i nowoczesne protokoły API:

REST (HTTP) – ze wsparciem dla JSONPath do filtrowania i transformacji dużych odpowiedzi JSON
GraphQL – dedykowany query builder z auto-complete, introspekcją schematu i wbudowanym eksploratorem dokumentacji API
gRPC – obsługa .proto files i dynamiczna refleksja – jeśli serwer wspiera refleksję, Insomnia wyświetli dostępne metody
WebSocket – możliwość łączenia się, wysyłania wiadomości i subskrybowania eventów bez pisania kodu
Server-Sent Events – obsługa komunikacji jednokierunkowej z serwera

Każdy protokół ma dedykowany interfejs. W przypadku WebSocket’u użytkownik może przeglądać historię połączenia, headers, cookies i console – kompletne środowisko testowe bez budowania frontendu.

Praktyczne demonstracje:

REST: publiczne Rick and Morty API (filtrowanie za pomocą JSONPath)
WebSocket: połączenie z Coinbase do testowania real-time komunikacji

Prompt feature – funkcja umożliwiająca zaznaczenie parametru jako zmienną, którą Insomnia pyta podczas wysyłania requestu. Dostępna wszędzie (query params, headers, body) z możliwością ustawienia wartości domyślnej.

Modele synchronizacji: Git sync vs Cloud sync

Insomnia oferuje dwa podejścia do zarządzania definicjami API.

Git Sync

Jeśli zespół już pracuje z Git repozytorium, można eksportować kolekcję requestów w formacie OpenAPI spec, commitować i pushować do repo. W tym modelu dane przechowywane są wyłącznie w repozytorium Git – Insomnia nie przechowuje niczego na swoich serwerach. Git staje się źródłem prawdy. Zespół może robić pull requesty, mergować gałęzie i zarządzać wersjami jak zwykłym kodem.

Zaleta: pełna kontrola, historyk zmian w Git, współpraca poprzez znane narzędzia
Wada: wymaga ręcznego setup’u – konfiguracja dostępu, generowanie tokenów; nowy członek musi sklonować repozytorium

Cloud Sync

W tym modelu zamiast zarządzać repozytorium, użytkownik zapraszakogoś do organizacji w Insomnia. Osoba ma natychmiast dostęp do wszystkich requestów, zmiennych i dokumentacji. Źródłem prawdy jest baza danych Insomnia, a nie repozytorium Git.

Kluczowa różnica: dane są szyfrowane end-to-end. Insomnia może ich nie deszyfrować – szyfrowanie zachodzi na urządzeniu użytkownika przed wysłaniem do chmury. To zapewnia wyższy poziom bezpieczeństwa niż tradycyjne cloud storage.

Onboarding zespołu

Tradycyjny onboarding w kontekście API polega na wysyłaniu dokumentacji, curl scripts lub instrukcji tekstowych. Nowy członek zespołu musi czytać, kopiować i testować – process zajmuje wiele godzin.

W Insomnia proces wygląda inaczej. Zamiast wysyłać dokumenty, zespół zaprasza nowego członka do organizacji. Po zalogowaniu (ewentualnie przez SSO w wersji Enterprise) osoba ma natychmiast dostęp do wszystkich kolekcji requestów, zmiennych środowiskowych i dokumentacji. Może uruchomić pierwszy test w ciągu kilku minut bez dodatkowej konfiguracji – wszystko jest już tam, gdzie powinno być.

Funkcje Enterprise

Edycja Enterprise Insomnia dostarcza dodatkowych możliwości:

Self-hosted API mocking – możliwość hostowania mock’ów na własnej infrastrukturze zamiast w chmurze Insomnia. Ważne dla organizacji z wymogami compliance, gdzie dane nie mogą opuszczać sieci wewnętrznej.

Unlimited mock requests – brak limitów na ilość requestów do mock’ów (bezpłatna wersja ma ograniczenia).

SOC 2 Type 1 & 2 certification – infrastruktura bezpieczeństwa została poddana audytom zewnętrznym, co jest wymagane przez wiele dużych organizacji.

Enterprise support – dedykowany team supportu.

Professional services – pomoc w implementacji i migracji.

Zarządzanie dostępem i bezpieczeństwo

Dashboard organizacyjny – każdy użytkownik widzi organizacje, do których należy, oraz personal workspace. Administrator może tworzyć nowe organizacje i je zarządzać.

Domain verification – można ograniczyć, które domeny mogą być zapraszane do organizacji. Administrator dodaje domenę, weryfikuje ją poprzez DNS TXT record, i tylko osoby z tej domeny mogą być zapraszane. Zapobiega przypadkowemu dodaniu osób spoza organizacji.

Teams i grupy – w ramach organizacji można tworzyć zespoły (np. Backend team, Mobile team). Możliwe jest zapraszanie całej grupy jednocześnie zamiast poszczególnych osób.

SSO/SAML 2.0 – zamiast logowania emailem i hasłem, wszyscy z domeny logują się poprzez firmowy SSO (np. Okta, Azure AD). Wymaga wcześniejszej weryfikacji domeny, a następnie skonfigurowania połączenia z identiity provider’em.

SCIM provisioning – automatyczne tworzenie użytkowników w Insomnia na podstawie zmian w identity provider’ze. Gdy nowy użytkownik jest dodany w Okta i przypisany do aplikacji Insomnia, pojawia się automatycznie w systemie. Dotyczy to także grup – grupy utworzone w Okta synchronizują się z teamami w Insomnia. Użytkownik musi mieć zweryfikowaną domenę, w przeciwnym razie zostaje odrzucony z powodu bezpieczeństwa.

Storage control policies – administrator może mandatować, gdzie przechowywane są dane dla całej organizacji lub poszczególnych zespołów. Opcje to: local vault only (dane tylko na urządzeniu), cloud sync only (wszystko w chmurze) lub hybrid (wybór użytkownika). Każdy team może mieć inne ustawienia – np. cały team dev może mieć hybrid, ale team billing może być ograniczony do cloud sync only.

Storage control policies – przejęcie pełnej kontroli

Jeśli jesteś enterprise, administrator chce wiedzieć, gdzie przechowywane są dane. Insomnia oferuje trzy modele: local vault only (dane tylko na urządzeniu użytkownika, brak chmury), cloud sync only (wszystko w chmurze z end-to-end encryption), i hybrid (użytkownik wybiera sam).

Kluczowe: możesz konfigurować to na różnych poziomach. Definiujesz politykę domyślną dla całej enterprise account, ale możesz też override’ować dla konkretnej organizacji. Mark pokazuje przykład – w Enterprise control > Storage tab wybiera „Cloud sync only” dla billing organizacji, co oznacza, że local vault jest niedostępny dla osób w tej organizacji.

To jest zaawansowana kontrola – dokładnie to, co Enterprise szuka, gdy ma obowiązek compliance wobec klientów.

Collection runner – automatyczne testy

Collection runner uruchamia wszystkie requesty z kolekcji w określonej sekwencji. Użytkownik może ustawić liczbę iteracji, opóźnienia między requestami oraz sprawdzić asercje zdefiniowane w skryptach. Po kliknięciu run system wykonuje wszystkie requesty, zbiera response’y i generuje raport.

Narzędzie integruje się z pipeline’ami CI/CD – requesty mogą być uruchamiane automatycznie dla każdego pull request’a w GitHub Actions lub podobnych systemach.

Praktyczna automatyzacja testów API

Automatyzacja testów API w Insomnia polega na powiązaniu wykonywania żądań z weryfikacją odpowiedzi. Mark zademonstrował to na praktycznym scenariuszu dodawania i usuwania produktu.

Krok 1: Przechwycenie tokena autoryzacji Najpierw tworzony jest request pobierający token (np. endpoint logowania). W zakładce after-response tego żądania umieszczany jest skrypt JavaScript, który przechwytuje token z odpowiedzi.

Krok 2: Zapis tokena jako zmiennej środowiskowej Skrypt zapisuje token jako zmienną (np. insomnia.environment.set("API_key", jsonBody.token)).

Krok 3: Autoryzacja na poziomie folderu Autoryzacja (np. Bearer Token lub API Key) jest ustawiana na poziomie całego folderu „Test”, dzięki czemu wszystkie żądania w folderze automatycznie dziedziczą ten token.

Krok 4: Asercje w kolejnych żądaniach W każdym kolejnym żądaniu (np. „Pobierz listę”, „Usuń produkt”) umieszczane są skrypty after-response zawierające asercje. Mogą one sprawdzać status odpowiedzi (np. czy to 200) lub zawartość (np. czy jsonBody.groceries.length === 0 po usunięciu).

Krok 5: Uruchomienie Collection Runnera Cały scenariusz jest uruchamiany za pomocą Collection Runnera, który sekwencyjnie wykonuje wszystkie żądania i raportuje wyniki.

Checklist: Automatyzacja scenariusza testowego

Stwórz żądanie pobierające token (np. logowanie)
Dodaj skrypt after-response przechwytujący token z odpowiedzi
Zapisz token jako zmienną środowiskową (insomnia.environment.set())
Ustaw autoryzację na poziomie folderu używając zmiennej
Dodaj skrypty after-response z asercjami w kolejnych żądaniach
Uruchom cały folder za pomocą Collection Runnera

Główne atuty Insomnia

Szybkość onboardingu – nowy członek zespołu może zamiast spędzać godziny na czytaniu dokumentacji i konfiguracji, zalogować się i natychmiast pracować.

Bezpieczeństwo – w wersji Enterprise dostępne są systemy kontroli dostępu na poziomie enterprise (SSO, SCIM, domain verification, end-to-end encryption).

Elastyczność – użytkownik może wybrać Git sync dla pełnej kontroli, Cloud sync dla wygody, lub model hybrydowy w zależności od potrzeb.

Automatyzacja – skrypty pre-request i after-response eliminują ręczną pracę przy zarządzaniu tokenami i weryfikacją response’ów.

Checklist: Pierwszy krok z Insomnia

Jeśli chcesz szybko przetestować Insomnia w swoim zespole, oto co musisz zrobić (różne ścieżki dla różnych struktur):

Dla startup’u / małego zespołu:

Stwórz organizację w Insomnia
Zaproś team memberów (Cloud sync – one-click)
Wygeneruj kolekcję z OpenAPI spec
Ustaw environment variables i skrypty pre-request
Uruchom Collection Runner

Dla zespołu DevOps:

Wygeneruj kolekcję i commitnij do Git (OpenAPI format)
Skonfiguruj dostęp do repo’u
Sklonuj repo w Insomnia (Git sync)
Dodaj testy do CI/CD pipeline’u

Dla enterprise:

Zweryfikuj domenę (DNS TXT record)
Skonfiguruj SSO connection i SCIM provisioning w Okta
Zaproś całą organizację (wszyscy logują się przez SSO)
Skonfiguruj storage policies w Enterprise control

Status funkcji: SCIM provisioning w preview

Kilka funkcji prezentowanych w webinarze, szczególnie SCIM provisioning, znajduje się na etapie preview – funkcja jest nowa i ciągle się rozwija. Mark zwrócił uwagę na bug w interfejsie użytkownika, gdzie synchronizacja grupy nie wyświetlała się prawidłowo. Funkcja ma zostać wypuszczona jako pełna (GA) w ciągu tygodnia od webinaru.

Dla organizacji planujących wdrażać SCIM provisioning, rekomenduje się testowanie na środowisku staging po oficjalnym wydaniu.

Prompt feature – praktyczne zastosowania

Prompt feature pozwala na zaznaczenie parametru i ustawienie go jako zmienną, którą Insomnia będzie pytać podczas każdego sendowania requestu. Można ustawić wartość domyślną.

Zastosowania:

Testowanie z różnymi ID – zamiast zmieniać zmienną w environmentach, prompt pyta za każdym razem
Paginacja – zamiast commitować zmianę page index, prompt prosi o wartość
Dane testowe – gdy testujesz z różnymi inputami (email, phone, itp.)
Szybkie przełączanie scenariuszy – bez zmiany zmiennych środowiskowych
Kolaboracja – kilka osób testuje ten sam endpoint z różnymi parametrami

Kiedy nie używać:

Gdy parametr się nie zmienia – lepiej ustawić jako zwykłą zmienną
W Collection Runner – prompty blokują automatyczne uruchamianie
W automatyzacji – prompty wymagają ręcznej interwencji

Prompt feature najlepiej sprawdza się podczas ręcznego testowania i exploracji.

Dla kogo jest Insomnia?

Insomnia ma zastosowanie w różnych scenariuszach:

Developerzy indywidualni debugujący lokalne API – narzędzie jest dostępne w bezpłatnej wersji
Startups – Cloud sync umożliwia szybkie udostępnianie API w zespole bez zawiłej konfiguracji
Duże organizacje – wersja Enterprise oferuje SSO, SCIM, storage control i inne narzędzia do zarządzania dostępem

Niezależnie od modelu – Insomnia wspiera HTTP, GraphQL, gRPC, WebSocket i Server-Sent Events, co czyni ją uniwersalnym narzędziem do testowania nowoczesnych interfejsów.

Obserwacja: Dokumentacja jako wyzwanie w onboardingu

Tradycyjne podejście do onboardingu API polega na przygotowaniu dokumentacji (README, wiki, instrukcji tekstowych). Nowy członek zespołu czyta materiały, kopiuje curl commands i testuje – process zajmuje wiele godzin, a dokumentacja ma tendencję do szybkiego starzenia się.

Alternatywne podejście, które demonstruje Mark: zamiast wysyłać dokumenty, zespół zaprasza nowego członka do organizacji Insomnia. Osoba ma natychmiast dostęp do żywych definicji API z predefiniowanymi zmiennymi, skryptami i testami. Może uruchomić pierwszy test w ciągu kilku minut. Jeśli endpoint się zmieni, zmiana odzwierciedla się natychmiast – nie ma zagrożenia nieaktualnej dokumentacji.

Implikacja: onboarding time spada z dni na godziny. Błędy związane z nieaktualnymi danymi testowymi znikają. Cała wiedza o interfejsach API jest scentralizowana w jednym miejscu.

Praktyczne zastosowanie: następnym razem gdy nowy członek zespołu dołączy do projektu API, zamiast wysyłać dokumentację, zaproś go do organizacji Insomnia i zaobserwuj różnicę w time-to-productive.

Obserwacja: Paradoks interfejsu użytkownika

Tradycyjnie zakładamy, że aby nietechniczne zespoły (np. wsparcie klienta) mogły pracować z API, musimy zbudować dla nich dedykowany interfejs użytkownika – panel administracyjny lub narzędzie.

W praktyce okazuje się, że dla prostych zadań sam API client, zamiast dedykowanego UI, jest wystarczającym interfejsem. Korzystając z funkcji Prompt w Insomnia, można stworzyć kolekcję, która pyta użytkownika o potrzebne dane (np. ID klienta), delegując zadanie bez pisania linijki kodu front-endowego.

Dlaczego to ma znaczenie: To zmienia postrzeganie Insomnia z narzędzia czysto deweloperskiego w platformę do błyskawicznego tworzenia wewnętrznych narzędzi. Oszczędza to tygodnie pracy, które pochłonęłoby budowanie i utrzymywanie prostych paneli admina.

Praktyczne zastosowanie: Następnym razem gdy zespół wsparcia poprosi o proste narzędzie do „sprawdzenia czegoś” (wymagające jednego lub kilku API calls), zamiast planować nowy projekt UI, stwórz kolekcję w Insomnia. Użyj funkcji Prompt dla zmiennych (np. ID użytkownika) i przekaż ją zespołowi. Wymaga to minut zamiast tygodni.

Artykuł stanowi notatki z webinaru „API Design and Testing for AI-driven Endpoints with Insomnia”, w którym Mark z zespołu Insomnia przedstawił możliwości i funkcje narzędzia. Wszystkie opisane funkcjonalności, podejścia i rekomendacje pochodzą bezpośrednio z prezentacji.

Źródło: Webinar „API Design and Testing for AI-driven Endpoints with Insomnia„

Tag: Git Sync

Insomnia: Kompletna platforma do projektowania, testowania i mockowania API #EN331