TeaPie: rýchle a skriptovateľné API testy (nielen) pre C# .NET vývojárov

Prečo ďalší nástroj na API testy?
Ako vývojári často balansujeme medzi rýchlym “curl a ide sa ďalej” a robustnými test suitami, ktoré sú síce bohaté, no ťažkopádne. TeaPie (TEsting API Extension) stavia most – píšeš HTTP testy priamo v .http súboroch, pričom setup, validácie a testy dopíšeš v C# skriptoch. Všetko sa spúšťa cez jednoduché CLI a keďže testy vedia byť súčasťou repozitára, ich zmeny sú prehľadné v PRs.

Hello, TeaPie!
Na to, aby si si TeaPie rozbehal aj lokálne u seba, bude ti stačiť mať nainštalovaný .NET 8+. Samotný nástroj TeaPie.Tool si vieš nainštalovať pomocou príkazu:

dotnet tool install -g TeaPie.Tool

Ak to u teba beží na prvý pokus, gratulujem! V opačnom prípade určite pozri dokumentáciu.

Jednoduchý HTTP request
Nejako začať musíme, preto si spravme jednoduchý HTTP request na známu {JSON} Placeholder dummy API.

001-Create-Post-req.http

Na spustenie tohto requestu ti odporúčame použiť Visual Studio Code s naším rozšírením TeaPie Extensions, ale existujú aj iné prostredia a nástroje. Spustíš príkaz TeaPie: Run HTTP Request (F8) a výsledok ti bude interpretovaný takto:

Môj prvý test
To, či sa nový post “naozaj vytvoril”, nám spravidla indikuje status code v odpovedi. Preto si poď s nami napísať prvý test. K súboru .http si môžeš jednoducho pridať testovací C# skript, stačí vytvoriť súbor s rovnakým názvom, ale s inou koncovkou -test.csx :

001-Create-Post-test.csx

Keďže nepracujeme so C# projektom, ale so skriptovacím jazykom, nemáme k dispozícií ladiace prvky. Preto sme pridali príkaz, ktorý za teba skontroluje, či sa skript dá skompilovať. Ak nie, vypíše ti aj to, kde máš chybu:

teapie compile "001-Create-Post-test.csx"

Ups, ušla nám bodkočiarka… Po oprave si spustíme náš prvý test:

teapie test "001-Create-Post-req.http"

Ak preferuješ našu VS Code extension oproti CLI, použi F5, alebo príkaz TeaPie: Run Test (v pravo hore je aj play tlačidlo), ktorý to napíše do konzoly za teba.

Premenné
Ručne kopírovať tú istú URL je otrava a hlavne nepraktické, preto si uložme adresu do premenných. Môžeme tak urobiť napríklad v inicializačnom skripte, ktorý stačí pomenovať init.csx a vložiť ho do rovnakého priečinka, ako máš test.

init.csx

tp.SetVariable("ApiBaseUrl", "https://jsonplaceholder.typicode.com");

Samozrejme, určite by si si takúto premennú radšej uložil do prostredia (či?)… Klikni tu, a dozvieš sa viac o prostrediach.

Premenná je uložená, teraz si ju poďme prečítať v .http súbore. Rovno pridajme ďalší HTTP request do toho súboru (áno aj to nám umožňuje .http súbor), ktorý sa pokúsi získať práve “vytvorený” post:

001-Create-Post-req.http

Všimni si, že atribút @name nám umožnil čítať telo z requestu/response aj pomocou JPath. Týmto sa výrazne zjednodušuje odovzdávanie si dát medzi requestami v rámci jedného .http súboru.

Test case? Čo to je?
Test case je základnou stavebnou jednotkou v TeaPie prostredi. Pozostáva minimálne z request súboru (.http) a voliteľných C# skriptov:

Každý priečinok, v ktorom sa nachádza aspoň jeden test case sa dá považovať za kolekciu, ktorá sa dá samostatne spúšťať, jednoducho, zadaním cestou k tomuto priečinku:

Direktívy
Skvelou výhodou frameworku TeaPie sú direktívy, ktoré sa dajú používať ako v skriptoch, tak aj v .http súboroch. Povedzme, že sme si definovali ako vyzerá post v samostatnom súbore:

Post.csx

V inom skripte si ho vieme jednoducho naimportovať pomnocou direktív a k tomu ešte použiť ľubovoľné NuGet balíčky:

001-Create-Post-init.csx

Keď už máme vytvorený nový, náhodný post uložený v premennej, môžeme ho použiť v HTTP requeste. Doteraz sme testovali status code pomocou skriptu, ale môžeme to urobiť aj jednoduchšie, použitím vstavanej direktívy TEST-EXPECT-STATUS:

001-Create-Post-req.http

Aby sme sa zbytočne neškatuľkovali, direktívy si môžeš vytvoriť vlastné – podľa svojho gusta. Jednoducho si ju nakonfiguruješ v skripte a potom ju použiješ pri HTTP requeste. Viac o tom, náješ tu.

Autentifikácia
Bezpečnosť je dôležitá, preto na ňu netreba zabúdať ani pri APIs. TeaPie ponúka vstavané autentifikačné mechanizmy, ako aj možnosť vytvárať si vlastné. Použitie je už potom jednoduché, pred každým HTTP requestom si nastavíš, ktorý mechanizmus sa má použiť:

Vlastný provider si jednoducho zaregistruješ cez tp.RegisterAuthProvider(...) v ľubovoľnom skripte, ktorý zbehne pred prvým použitím providera. Viac si môžeš naštudovať tu.

Retrying
Vieš ako to chodí v asynchrónnom svete, niekedy treba klopať na dvere viackrát, aby boli otvorené. Z tohto dôvodu sme pridali do nástroja aj možnosť definovať si vlastné retrying stratégie. Celý mechanizmus je založený na známej Polly.Core knižnici.

Postup je rovnaký, ako pri predchádzajúcich funkcionalitách – v skripte si nakonfiguruješ svoju stratégiu a pri definícii HTTP requestu ju použiješ pomocou direktívy. Viac tu.

Reporty
O výsledkoch priebežne informuje výpis v konzole a na konci behu sa vygeneruje sumár výsledkov. Okrem toho je podporené generovanie JUnit XML, ktoré je priamo použiteľné v GitHub Actions/Azure DevOps. Ak by ti to však nestačilo, nie je problém nakonfigurovať si vlastné reportovacie triedy, ktoré ti vygenerujú sumarizáciu v tvojom štýle. Viac tu.

Logovanie
Bežnou súčasťou každého CLI nástroja je možnosť škálovateľného logovania. Inak tomu nie je ani v prípade nástroja TeaPie. Logovanie je priamočiare a prístupné odkiaľkoľvek z kódu:

tp.Logger.LogInformation("RunId: {RunId}", tp.GetVariable<Guid>("RunId"));

Pre viac info o logovaní klikaj tu.

Integrácia s CI pipelinami
Keďže sa vykonávanie testov robí pomocou spúšťania CLI toolu, integrácia s CI pipelinami je jednoduchá. Spustenie testov je v podstate len ďalší proces, ktorý beží v danom prostredí.

Kedy siahnuť po TeaPie?

• Potrebuješ testy blízko kódu a chceš ich reviewovať v PR
• Chceš retry, vlastné autentifikačné mechanizmy, prostredia a reporty bez ťažkopádnej infra
• Cítiš sa doma v .http a chceš si pomôcť C# skriptmi (NuGet, #load, vlastné testy a triedy)

Ak ti sedí aspoň jeden use-case, skús dať šancu bezplatnému nástroju TeaPie.

Záver
TeaPie je praktický, skriptovateľný a “repo-native” prístup k API testovaniu. Vďaka .http súborom a C# skriptom získavaš produktivitu bez kompromisov: rýchly štart, čisté PRs, predvídateľné spúšťanie v CI a možnosť prispôsobiť si všetko od vlastnej autentifikácie až po generovanie reportov pre svoje potreby. Skús ho na najbližšom endpointe – a možno si konečne stihneš dať aj ten čaj s koláčom. 🍵🥧

PS: TeaPie je open-source projekt, preto budeme radi, ak nám ho pomôžeš vylepšiť tu.