Testy kontraktowe API: od czego zacząć

Kontrakt, czyli obietnica API

Kontrakt API to umowa między dostawcą a konsumentem: jakie endpointy istnieją, jakie dane przyjmują i co zwracają. Zwykle jest zapisany w specyfikacji OpenAPI (Swagger), w WSDL dla SOAP albo w schemacie GraphQL. Problem w tym, że specyfikacja i rzeczywiste działanie API rozjeżdżają się szybciej, niż ktokolwiek to zauważa.

W jednym z projektów w ramach testów API porównywałem odpowiedzi API z dokumentacją Swagger. Rozbieżności wychodziły regularnie: inne nazwy pól, inne typy, pola opcjonalne, które w praktyce były wymagane.

Test kontraktowy a test integracyjny

• Test integracyjny sprawdza, czy dwa systemy działają razem: czy zamówienie złożone w aplikacji trafia do magazynu.
• Test kontraktowy sprawdza, czy odpowiedź API ma kształt, który obiecano: czy pole status jest tekstem z określonej listy, a createdAt datą w formacie ISO 8601.

Testy kontraktowe są szybsze, stabilniejsze i łatwiej wskazują winnego. Gdy test nie przejdzie, wiesz, że to zmiana w API, a nie problem ze środowiskiem.

Walidacja schematu JSON

Najprostszy test kontraktowy to walidacja odpowiedzi względem JSON Schema. W RestAssured wygląda to tak:

@Test
void orderMatchesContract() {
    given().auth().oauth2(token)
    .when().get("/api/orders/{id}", orderId)
    .then().statusCode(200)
        .body(matchesJsonSchemaInClasspath("schemas/order.json"));
}

Schemat order.json możesz wygenerować z OpenAPI, a potem doprecyzować: dodać required, dozwolone wartości (enum) i formaty. Taki test złapie usunięte pole, zmianę typu i nową, nieopisaną wartość statusu.

W Postmanie to samo zrobisz w zakładce testów kolekcji:

const schema = pm.collectionVariables.get("orderSchema");
pm.test("odpowiedź zgodna z kontraktem", () => {
  pm.response.to.have.jsonSchema(JSON.parse(schema));
});

Od czego zacząć

1. Wybierz 5-10 endpointów, z których korzystają inne zespoły lub partnerzy. Tam zmiana kontraktu boli najbardziej.
2. Zacznij od odpowiedzi poprawnych (200, 201). Potem dodaj błędy: 400 z opisem walidacji, 401, 403, 404.
3. Trzymaj schematy w repozytorium razem z testami. Zmiana kontraktu będzie widoczna w code review.
4. Uruchamiaj testy przy każdej zmianie backendu. Kilkadziesiąt testów kontraktowych wykonuje się w sekundy.

Testy kontraktowe nie zastąpią testów scenariuszy biznesowych. Sprawdzają kształt danych, a nie to, czy logika jest poprawna.

Testy negatywne

Kontrakt obejmuje też błędy. Sprawdź, czy API:

• odrzuca brakujące pola wymagane z czytelnym komunikatem,
• nie zwraca szczegółów implementacji (stack trace, nazwy tabel) w odpowiedzi 500,
• zwraca 401 bez tokenu i 403 z tokenem bez uprawnień,
• respektuje limity długości i zakresy wartości.

Podsumowanie

Testy kontraktowe to najtańszy sposób, żeby zmiana w jednym serwisie nie zepsuła pięciu innych. Zacznij od walidacji schematu kilku najważniejszych endpointów i podepnij ją pod CI. Jeśli potrzebujesz pomocy przy testach API, napisz do mnie. Jeśli szukasz zespołu, który zaprojektuje backend i integracje, zajmuje się tym moja spółka, software house 2Simple.