Testowanie kontraktów API

Testowanie kontraktów API to sprawdzanie wspólnej umowy między systemem, który wysyła dane, a systemem, który je odbiera. Tą umową nie jest luźny opis w Notion, lecz konkret: adres endpointu, metoda HTTP, wymagane pola, ich typy, format odpowiedzi i zachowanie przy błędzie. Gdy formularz wysyła lead do CRM, kontrakt może mówić, że e-mail jest tekstem wymaganym, źródło jest jednym z ustalonych wariantów, a poprawny zapis zwraca identyfikator rekordu. Test wykrywa niezgodność zanim automatyzacja zacznie zapisywać niepełne dane albo przestanie działać bez wyraźnego alarmu.

To nie jest to samo co test kliknięty ręcznie raz po wdrożeniu. Ręczny test odpowiada na pytanie, czy integracja działa w tej chwili. Test kontraktowy jest powtarzalnym zabezpieczeniem uruchamianym po zmianie po stronie klienta API lub dostawcy. Pact opisuje tę technikę jako sprawdzanie punktu integracji w izolacji, aby komunikaty wysyłane lub odbierane przez aplikacje odpowiadały wspólnemu kontraktowi. Dzięki temu nie trzeba uruchamiać całego stosu usług tylko po to, aby odkryć, że nazwa pola została zmieniona z email na emailAddress.

Dla solopreneurki budującej system AI kontrakt jest szczególnie ważny na granicach workflowu. Model może poprawnie przygotować ustrukturyzowany obiekt, ale kolejny krok może oczekiwać innego pola, daty w innym formacie albo tylko jednej wartości zamiast listy. Przykład: agent kwalifikuje lead i zwraca status, uzasadnienie oraz następny krok. Kontrakt między agentem a CRM wymaga statusu z zamkniętej listy, tekstowego uzasadnienia i identyfikatora leada. Gdy prompt lub model zwróci nieobsługiwaną wartość, walidator zatrzymuje zapis i kieruje sprawę do kolejki błędów, zamiast tworzyć rekord, którego nikt później nie znajdzie.

Punktem wyjścia może być OpenAPI, czyli standardowy opis HTTP API. Specyfikacja OpenAPI pozwala ludziom i programom zrozumieć możliwości usługi bez czytania jej kodu. W opisie można określić ścieżki, parametry, statusy i schematy requestów oraz response’ów. Sam opis nie gwarantuje jednak, że działająca integracja go przestrzega. Test kontraktowy uruchamia konkretne przykłady przeciwko klientowi, dostawcy albo obu stronom. JSON Schema pomaga doprecyzować strukturę danych, ale warto testować również znaczenie biznesowe: które pole jest obowiązkowe, jakie stany są dozwolone i co ma się wydarzyć po błędzie.

Zacznij od jednego przepływu, którego awaria kosztuje Cię leady, czas lub zaufanie klienta. Zapisz trzy poprawne przykłady i trzy przypadki graniczne: brak wymaganego pola, nieobsługiwaną wartość oraz odpowiedź 429 lub 500. Następnie ustal, co ma zrobić workflow. Nie każdy błąd oznacza retry. Brak e-maila wymaga odrzucenia lub ręcznej poprawy, a limit szybkości może wymagać wykładniczego opóźnienia. Kontrakt powinien więc weryfikować zarówno dane wejściowe i wyjściowe, jak i bezpieczne zachowanie procesu przy znanych klasach błędów.

Nie zamieniaj kontraktu w kopię całej implementacji dostawcy. Zbyt szczegółowy test blokuje pożyteczne zmiany, na przykład dodanie opcjonalnego pola do odpowiedzi, i szybko staje się ignorowanym obowiązkiem. Testuj to, od czego realnie zależy Twój proces: pola używane dalej, typy, dozwolone wartości, kody odpowiedzi oraz semantykę błędów. Pozostaw tolerancję na dane, których nie wykorzystujesz. Jeśli integracja ma webhook, kontrakt nie zastępuje weryfikacji podpisu. Najpierw potwierdzasz, że wiadomość pochodzi od właściwego nadawcy, potem sprawdzasz, czy jej struktura pasuje do oczekiwanego zdarzenia.

Testowanie kontraktów nie jest zamiennikiem dla testów end-to-end ani monitoringu produkcji. Nie sprawdzi, czy zewnętrzny CRM ma dziś awarię, czy uprawnienia tokenu wygasły albo czy model przygotował sensowną wiadomość dla klienta. Jego zadanie jest węższe: szybko wykryć, że strony integracji przestały mówić tym samym językiem. Najlepszy układ to kontrakt przed wdrożeniem, obsługa błędów i alert po wdrożeniu oraz kilka testów pełnego przepływu dla najważniejszych scenariuszy. Wtedy system AI ma mniej efektownych, ale kosztownych awarii ukrytych między narzędziami.