Kontraktní testování: aby změna API nerozbila jeho klienty
Tým, který vlastní API, přejmenuje pole v odpovědi. Změna je malá, testy služby projdou a nasazení proběhne bez problémů. O tři hodiny později volá jiný tým, že mu přestaly přicházet objednávky – jeho aplikace toto pole četla. Nikdo neudělal nic špatně. Jen nebylo nikde zaznamenáno, kdo se na co spoléhá.
Co je kontraktní testování
Kontraktní testování, anglicky contract testing, zaznamenává očekávání mezi poskytovatelem API a jeho klientem do strojově čitelného kontraktu. Ten popisuje například potřebná pole, jejich typy a konkrétní interakce. Pokud změna tato očekávání poruší, pipeline na to může upozornit ještě před releasem.
„Klientem“ přitom nemyslíme zákazníka, ale jinou službu nebo aplikaci, která vaše API používá – například mobilní aplikaci, integraci partnera nebo jinou mikroslužbu. Představte si to jako výkres zástrčky a zásuvky: když obě části odpovídají stejnému výkresu, zapadnou do sebe, i když je nikdo nikdy fyzicky nespojil.
Proč to běžné testy nemusí odhalit
Poskytovatel API má testy své implementace. Klient může mít testy proti simulované odpovědi neboli mocku. Obě sady mohou projít, a přesto si systémy nemusí rozumět, pokud každá strana ověřuje pouze vlastní představu o dohodě.
Společné integrační prostředí je užitečná vrstva, ale nemusí poskytnout včasnou zpětnou vazbu. Obvykle ho sdílí více týmů a nekompatibilita se v něm může projevit až ve chvíli, kdy je změna dokončena a připravena na release.
Samotná dokumentace nemusí stačit. Popisuje zamýšlené rozhraní, ale nemusí zachytit, která pole a chování jednotliví klienti skutečně používají. Kontrakt tato konkrétní očekávání zaznamenává v podobě, kterou lze automaticky ověřit.
S rostoucím počtem služeb a klientů roste také počet dohod, které je nutné udržovat. U mikroslužeb proto může být bez společného mechanismu obtížné zjistit, koho se změna dotkne.
Jak to řešíme
Kontraktní testování převádí dohodu mezi službami do kódu. Když se kontrakty ověřují při relevantních změnách API, může se nekompatibilita projevit ještě před propojením obou systémů.
Jedním z open-source nástrojů pro spotřebitelem řízené kontrakty je Pact. Konkrétní nástroj však vybíráme až podle používaných jazyků, typu integrace a způsobu, jakým týmy kontrakty publikují a ověřují.
Klient v testu popíše, co od API očekává: odešlu tento požadavek a v odpovědi potřebuji tato pole s těmito typy. Z toho vznikne kontrakt – strojově čitelný záznam skutečné potřeby klienta, nikoli dokumentace, která zastará.
Poskytovatel API poté ověří kontrakty klientů vůči své skutečné implementaci. Pokud změna poruší zaznamenané očekávání, kontrola může selhat už v pipeline služby, která změnu připravuje.
Podstatné je, co kontrakt nehlídá. Nejde o seznam všeho, co API vrací, ale o vybraná očekávání konkrétního klienta. Pole lze bezpečněji změnit pouze tehdy, když kontrakty pokrývají všechny relevantní klienty a když zohledníte také veřejné nebo neznámé uživatele API.
Kontraktní testy bývají rychlejší než test celého integrovaného systému, protože obě strany lze ověřovat samostatně. Není při nich nutné spouštět všechny služby najednou.
Co z toho máte
U klientů pokrytých kontrakty lépe vidíte, která zaznamenaná očekávání plánovaná změna ovlivní. Pipeline tak může upozornit na nekompatibilitu ještě před releasem, nikoli až po hlášení od jiného týmu nebo zákazníka.
Konkrétně to znamená:
- nekompatibilní změnu lze odhalit před nasazením, nikoli až na základě hlášení od jiného týmu nebo zákazníka;
- týmy nemusí při každé kontrole spouštět celé společné integrační prostředí;
- kontrakt lze udržovat společně s testy a sledovat jeho historii;
- vývojáři při úpravě rozhraní lépe vidí, která očekávání musí zachovat.
Kontrakty však znají pouze klienty a očekávání, které jsou v nich zaznamenány. U veřejného API nebo neznámých klientů je nutné kompatibilitu chránit také verzováním, jasnou dokumentací a dohodnutým postupem ukončování starších verzí.
Kontraktní testy přitom nenahrazují funkční API testy. Hlídají hranici mezi službami; správnost logiky za touto hranicí ověřuje funkční sada, například autorizační matice, hraniční hodnoty a chybové stavy. Obě vrstvy lze zapojit do CI/CD tak, aby podle rizika upozornily tým nebo zablokovaly nasazení.
Další krok
Nejprve si zmapujte klienty kritických API a změny, které jim v minulosti způsobily problémy. Vhodné hranice kontraktů můžete projít během nezávazné konzultace v rámci API testů.