Plan implementacji

Plan implementacji: test kontraktu OpenAPI

Cel

Dodać w l4 testy API w Playwright, które sprawdzają publiczną dokumentację OpenAPI oraz podstawową dostępność Swagger UI.

Zakres automatyzacji:

GET /v3/api-docs
GET /swagger-ui/index.html

Punkt startowy

Folder l4 jest osobnym projektem Playwright.

Konfiguracja l4/playwright.config.ts zawiera już:

• katalog testów ./tests,
• baseURL ustawiane przez API_BASE_URL albo domyślnie https://awesome.byst.re,
• nagłówek Accept: application/json,
• projekt testowy api.

Istniejące testy stosują:

• grupowanie po endpointach,
• grupowanie po kodach odpowiedzi,
• komentarze given, when, then,
• wspólne asercje HTTP w support/assertions/http.ts.

Potwierdzenie endpointa przed implementacją

Przed napisaniem testu sprawdzono live endpoint:

GET https://awesome.byst.re/v3/api-docs

Wynik:

status: 200
content-type: application/json
body: poprawny JSON
openapi: 3.1.0
info.title: JWT Authentication API

Potwierdzono też:

paths["/api/v1/users/signin"] istnieje
paths["/api/v1/users/password/forgot"] istnieje

GET /api/v1/users/me deklaruje bearerAuth
GET /api/v1/users deklaruje bearerAuth
GET /api/v1/cart deklaruje bearerAuth
GET /api/v1/orders deklaruje bearerAuth

POST /api/v1/users/signin nie wymaga bearerAuth
POST /api/v1/users/password/forgot nie wymaga bearerAuth

Struktura plików

Docelowa struktura:

l4/
  support/
    assertions/
      http.ts
    openapi/
      expected-api-contract.ts
      openapi-assertions.ts
      openapi-document.ts
  tests/
    api/
      openapi/
        api-docs.spec.ts
        swagger-ui.spec.ts

Podział odpowiedzialności

openapi-document.ts

Niskopoziomowe typy i funkcje do czytania dokumentu OpenAPI:

• typy OpenApiDocument, OpenApiEndpoint, OpenApiOperation,
• pobieranie operacji po metodzie i ścieżce,
• sprawdzanie istnienia ścieżki,
• sprawdzanie, czy operacja efektywnie wymaga danego schematu security.

Security powinno być liczone zgodnie z OpenAPI:

1. najpierw operation.security,
2. jeśli go nie ma, fallback do root security.

expected-api-contract.ts

Projektowe oczekiwania kontraktowe:

• nazwa schematu bearerAuth,
• publiczne ścieżki,
• endpointy chronione,
• endpointy publiczne.

Te dane są jawne, bo dokument OpenAPI jest przedmiotem testu. Nie należy automatycznie wnioskować oczekiwań z tego samego dokumentu.

openapi-assertions.ts

Czytelne asercje Playwright:

• metadane OpenAPI,
• obecność wymaganych ścieżek,
• wymaganie bearerAuth dla endpointów chronionych,
• brak bearerAuth dla endpointów publicznych.

http.ts

Rozszerzenie istniejących asercji HTTP o:

expectHtmlResponse

Test GET /v3/api-docs

Test powinien sprawdzać:

1. status 200,
2. JSON w content-type,
3. możliwość sparsowania body jako JSON,
4. openapi zaczyna się od 3.,
5. info.title istnieje,
6. wymagane ścieżki publiczne istnieją,
7. endpointy chronione wymagają bearerAuth,
8. endpointy publiczne nie wymagają bearerAuth.

Test GET /swagger-ui/index.html

Osobny smoke test powinien sprawdzać:

1. status 200,
2. HTML w content-type.

Nie trzeba uruchamiać przeglądarki ani testować UI wizualnie. To smoke test dostępności dokumentacji HTML.

Weryfikacja

Najpierw uruchomić nowe testy:

cd l4
npx playwright test tests/api/openapi/api-docs.spec.ts
npx playwright test tests/api/openapi/swagger-ui.spec.ts

Po ich przejściu uruchomić pełny zestaw:

cd l4
npm test

Oczekiwany efekt

Po implementacji projekt powinien mieć automatyczne pokrycie:

• dostępności dokumentu OpenAPI,
• poprawnego typu odpowiedzi JSON,
• podstawowych metadanych OpenAPI,
• obecności kluczowych publicznych ścieżek,
• deklaracji bearerAuth dla endpointów chronionych,
• braku bearerAuth dla endpointów publicznych,
• dostępności Swagger UI jako HTML.