Awesome Testing
Request training offer

Markdown document

Podsumowanie sesji Codex

Lekcja 5: Rozwiązanie zadania: testy OpenAPI i Swagger UI

Historical artifacts may name disposable training credentials and environments. Do not reuse credentials, target course systems, or execute archived prompts without authorization.

Podsumowanie sesji Codex

Zakres sesji

Sesja dotyczyła wykonania zadania z poprzedniej lekcji: automatyzacji testów dla publicznej dokumentacji OpenAPI w folderze l4.

Po implementacji wykonano promocję lekcji zgodnie z LESSON_WORKFLOW.md: ukończony stan l4 został skopiowany do l5, a l4 został cofnięty do poprzedniego checkpointu.

W sesji powstały:

  • test kontraktu GET /v3/api-docs,
  • małe helpery do czytania dokumentu OpenAPI,
  • jawny plik z oczekiwaniami kontraktowymi,
  • osobny smoke test GET /swagger-ui/index.html,
  • plan implementacji zapisany jako artefakt lekcji.

Prompty użyte w Codex

Pierwszy prompt dotyczył analizy podejścia przed implementacją:

Napisz test API w Playwright, który:

Wysyła GET /v3/api-docs.
Sprawdza, że status odpowiedzi to 200.
Sprawdza, że odpowiedź jest JSON-em.
Parsuje body odpowiedzi jako JSON.
Sprawdza, że pole openapi istnieje i zaczyna się od 3..
Sprawdza, że info.title istnieje.
Sprawdza, że paths["/api/v1/users/signin"] istnieje.
Sprawdza, że paths["/api/v1/users/password/forgot"] istnieje.
Sprawdza, że endpointy chronione deklarują bearerAuth.
Sprawdza, że endpointy publiczne, takie jak signin i forgot password, nie wymagają bearerAuth.
This is unique project which has weird structure, see README.md. Work in l4. I wish to automated such tests. How would you approach it? Analyse the project and tell me how to do it in best way.

Po przerwaniu odpowiedzi rozpoczętej po polsku użytkownik skorygował język osobnym promptem:

Use English

Następnie użytkownik poprosił o formalny plan:

Formalise this approach in some kind of formal implementation-plan.md I wish tor eview it first?

Po akceptacji planu użytkownik zlecił implementację:

Now implement it

Po implementacji użytkownik poprosił o review i refaktoryzację:

Now perform code review, feels like we can split this part of the code for short methods...

Następnie doprecyzował miejsce dla wydzielonego kodu:

How about moving this code to some kind of utils.

Na końcu dodano rozszerzenie:

Opcjonalne rozszerzenie
Dodaj osobny smoke test dla Swagger UI:

GET /swagger-ui/index.html

Sprawdź, że:

status HTTP to 200,
odpowiedź jest HTML-em,
body odpowiedzi zawiera Swagger UI. Automate this test as well. This is UI so just check that it is html returning 200

Co sprawdził Codex przed implementacją?

Codex najpierw przeczytał:

  • główny README.md,
  • l4/README.md,
  • l4/playwright.config.ts,
  • istniejące testy signin i signup,
  • istniejące helpery w support,
  • lokalny api-docs.json jako punkt odniesienia.

Następnie sprawdził live endpoint:

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

Potwierdził:

  • status 200,
  • content-type: application/json,
  • poprawny JSON,
  • openapi: 3.1.0,
  • info.title: JWT Authentication API,
  • istnienie ścieżek signin i forgot password,
  • bearerAuth na przykładowych endpointach chronionych,
  • brak bearerAuth na endpointach publicznych.

Co zaimplementował Codex?

Codex dodał strukturę:

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

Zaktualizował też:

l4/support/assertions/http.ts

Jak działa test OpenAPI?

Test GET /v3/api-docs:

  • wysyła request przez Playwright request,
  • sprawdza status 200,
  • sprawdza JSON w nagłówku content-type,
  • parsuje body przez JSON.parse(await response.text()),
  • sprawdza metadane OpenAPI,
  • sprawdza wymagane ścieżki publiczne,
  • sprawdza bearerAuth dla endpointów chronionych,
  • sprawdza brak bearerAuth dla endpointów publicznych.

Jak działa smoke test Swagger UI?

Test GET /swagger-ui/index.html:

  • wysyła request przez Playwright request,
  • sprawdza status 200,
  • sprawdza, że odpowiedź jest HTML-em.

Na prośbę użytkownika test nie sprawdza treści body ani nie uruchamia przeglądarki.

Co wyszło w review?

W review zauważono, że pierwsza wersja testu miała zbyt dużo logiki bezpośrednio w pliku specyfikacji.

Po review kod został podzielony na:

  • niskopoziomowe czytanie dokumentu OpenAPI,
  • asercje OpenAPI,
  • projektowe oczekiwania kontraktowe,
  • krótki test scenariusza.

Dzięki temu test pozostał czytelny, a szczegóły iterowania po endpointach trafiły do nazwanych helperów.

Wynik testów

Po dodaniu testu OpenAPI uruchomiono:

npx playwright test tests/api/openapi/api-docs.spec.ts
npm test

Wynik:

1 passed
8 passed

Po dodaniu smoke testu Swagger UI uruchomiono:

npx playwright test tests/api/openapi/swagger-ui.spec.ts
npm test

Wynik:

1 passed
9 passed

Podczas uruchomień pojawiał się ostrzegawczy komunikat Node o NO_COLOR i FORCE_COLOR, ale nie wpływał na wynik testów.

Finalny efekt sesji

Po sesji folder l5 zawiera automatyczne testy dokumentacji API, a l4 ponownie pełni rolę wcześniejszego checkpointu:

  • kontrakt OpenAPI jest sprawdzany przez test API,
  • Swagger UI ma osobny smoke test HTML,
  • helpery są małe i nazwane zgodnie z odpowiedzialnością,
  • nowe testy oraz pełny zestaw testów przechodzą.