Následující návrh rozvíjí můj pohled na testování rozhraní. Nejde o popis incidentu z vlastní praxe: doložená změna veřejného API slouží jako výchozí případ a další postup je moje analytické doporučení. Zaměřuji se na hranici mezi dvěma týmy, kde se technická shoda musí potkat se skutečnou potřebou uživatele.
Doložený případ: změna autentizace GitHub.com
GitHub dne 13. listopadu 2020 oznámil, že GitHub.com již nepřijímá hesla účtů pro autentizaci REST API a pro autentizované operace vyžaduje tokeny. Předchozí oznámení popisovalo harmonogram a přechodové kroky. Jde o doložený případ změny podmínek rozhraní provozovaného americkou společností, nikoli o tvrzení, že GitHub způsobil konkrétní veřejně doložený výpadek. Pro testování je podstatné, že kompatibilitu neurčuje pouze tvar JSON odpovědi. Spotřebitel může správně zpracovávat pole a přesto přestat fungovat, pokud jeho způsob autentizace přestane být podporován.
Proč je téma důležité
V integračním prostředí může každá služba samostatně projít svými testy, a přesto společný proces selže. Stačí změnit název pole, typ hodnoty, povinnost atributu nebo chování chybové odpovědi. Kontraktní testování ověřuje, že poskytovatel a spotřebitel rozumějí rozhraní stejným způsobem.
Nejde o náhradu integračních nebo end-to-end testů. Jde o rychlou ochrannou vrstvu, která zachytí nekompatibilní změnu dříve, než se dostane do sdíleného prostředí.
Jak postupovat správně
Zmapujte poskytovatele a spotřebitele
U každého endpointu určete, kdo jej vlastní, kdo jej používá a jaký obchodní proces na něm závisí.
Popište očekávání konkrétními příklady
Zahrňte povinná pole, datové typy, význam stavových kódů a klíčové chybové scénáře. Příklady musí vycházet z reálného použití.
Testujte kontrakt u spotřebitele
Spotřebitel ověří, že dokáže pracovat s odpovědí odpovídající dohodnutému kontraktu bez potřeby živé služby.
Ověřujte kontrakty u poskytovatele
Poskytovatel v CI spustí všechny relevantní spotřebitelské kontrakty a zjistí, zda změna někoho nepoškodí.
Řiďte kompatibilitu a verze
Změny rozlišujte na kompatibilní a nekompatibilní. U breaking change připravte přechodné období, novou verzi nebo koordinovaný release.
Udržujte jasné vlastnictví
Kontrakt má vlastníka, pravidla aktualizace a viditelný stav. Neaktuální kontrakt je pouze falešná jistota.
Čemu se naopak vyhnout
- Příliš detailnímu kontraktu, který kopíruje interní strukturu a brání běžným změnám.
- Ověřování pouze úspěšné odpovědi bez chybových stavů a prázdných dat.
- Spoléhání na jedno sdílené integrační prostředí jako jediný důkaz kompatibility.
- Breaking changes bez identifikace všech spotřebitelů a přechodového plánu.
- Kontraktům bez vlastníka, které se při změně aplikace neaktualizují.
Modelový příklad (hypotetický)
Marketingová platforma odesílá seznam kontaktů externímu poskytovateli. Spotřebitel očekává identifikátor, stav validace a seznam důvodů odmítnutí. Poskytovatel změní důvody z pole řetězců na objekty. Jednotkové testy obou služeb mohou projít, ale kontraktní test u poskytovatele změnu okamžitě označí jako nekompatibilní.
Tým má čas buď zachovat původní tvar, nebo vydat novou verzi endpointu a spotřebitele převést. Incident se tak řeší ještě před nasazením.
Ponaučení pro praxi
Kontraktní testování chrání dohodu mezi systémy. Nejlépe funguje, když je zaměřené na reálné potřeby spotřebitele, běží automaticky v CI a změny mají jasné vlastníky.
Co bych do kontraktu skutečně zahrnula
Kontrakt bych sestavila od obchodní potřeby spotřebitele. U odeslání kontaktu je například důležité rozlišit přijetí požadavku od dokončení zpracování. Stejný stavový kód nemusí znamenat, že kontakt již prošel validací nebo byl uložen. Navrhuji proto popsat očekávaný stav po odpovědi a další krok klienta. Každé tvrzení musí být možné ověřit na poskytovateli. Pokud kontrakt slibuje pouze přijetí do fronty, test nesmí vytvářet dojem, že ověřuje pozdější doručení. Tato hranice pomáhá určit, co má prověřit další integrační test a co už patří do sledování provozu.
Vedle úspěšné odpovědi bych vybrala několik chyb, které mění chování uživatele: neplatné oprávnění, vyčerpaný limit, neexistující objekt nebo částečné odmítnutí dávky. Nešlo by o úplný seznam všech technických možností. Každý scénář má zdůvodnění, vlastníka a očekávanou reakci spotřebitele. U chyby oprávnění například nechci nekonečné opakování požadavku. U dočasné nedostupnosti může být opakování vhodné, ale vyžaduje omezení a pravidla proti duplicitám. Tyto návrhy jsou obecné možnosti; konkrétní chování musí odpovídat dokumentaci zvoleného API a potřebám produktu.
Rozlišit technickou a významovou kompatibilitu
Změna může projít kontrolou schématu a přesto porušit dohodu. Pole s částkou zůstane číslem, ale začne vyjadřovat jinou měnu nebo hodnotu bez daně. V modelovém návrhu bych takové jednotky a významy popsala přímo u tvrzení, které na nich závisí. Současně bych nekontrolovala pořadí či atributy, které spotřebitel nepotřebuje. Příliš přesný test vede k falešným poplachům při neškodné změně. Příliš volný test zase přehlédne změnu rozhodnou pro výpočet. Dobrá diskuse nad kontraktem proto začíná otázkou, co konkrétně by uživateli přestalo fungovat.
Průchod změny až k nasazení
Navrhuji ukládat výsledek ověření s verzí spotřebitele, verzí poskytovatele a použitou konfigurací kontraktu. Samotná zelená značka bez těchto údajů je slabý důkaz. Tým potřebuje poznat, zda ověřil právě kombinaci, kterou chce nasadit. Při nekompatibilní změně bych předem určila poslední podporovanou verzi a přechodové období. Pokud poskytovatel běží mimo naši organizaci, nemusíme mít možnost zablokovat jeho vydání. O to důležitější je sledovat oznámení změn a ověřovat vlastní adaptér v prostředí, které poskytovatel pro tuto práci nabízí.
GitHub je užitečný právě jako připomínka této vnější závislosti. Z historického oznámení nevyvozuji, jaké konkrétní interní testy firma používala. Moje doporučení pro spotřebitele by bylo dohledat všechny integrační cesty, přiřadit jim vlastníka a ověřit připravenost před koncem podpory. Test založený na staré lokální maketě může zůstávat zelený, i když se veřejné podmínky již změnily. Proto bych pravidelně porovnávala kontrakt s relevantní dokumentací a ověřeným chováním poskytovatele. Taková kontrola má vlastní termín a neměla by být závislá jen na osobní paměti jednoho vývojáře.
Jak vyhodnotit přínos
Počet kontraktů není vhodný cíl sám o sobě. Sledovala bych, zda pokrývají významné spotřebitele, jaké nekompatibility odhalily před nasazením a kolik poplachů vedlo k pouhému přepisování očekávaných hodnot. Při opravě chci vědět, zda se změnila oprávněná potřeba produktu, nebo zda někdo jen přizpůsobil test nové odpovědi. V druhém případě může zelený výsledek skrýt původní problém. Revize proto potřebuje člověka, který rozumí spotřebiteli, ne pouze znalost testovací knihovny. Opuštěné integrace lze odstranit, ale tento krok má vycházet z ověření jejich skutečného používání.
Shrnutí a doporučení
Začala bych jedním důležitým rozhraním a několika rozhodnými scénáři. Popsala bych očekávání spotřebitele, ověřovala je u poskytovatele a spojila výsledek s konkrétními verzemi. Změny autentizace, oprávnění a významu dat patří do stejné úvahy jako názvy polí. Přechod potřebuje vlastníka a termín, zatímco úplný obchodní tok stále vyžaduje další testování. Takto chápaný kontrakt není archivní popis. Je to udržovaná dohoda, která umožňuje týmům měnit systémy s jasným důkazem, koho jejich změna ovlivní.