Podsumowanie sesji Codex

Ta sesja rozpoczęła się jako fork wcześniejszej rozmowy opisanej w lekcji 21. Fork zachował gotowy checkpoint l17, testy i raporty błędów, ale od tego miejsca praca dotyczyła nowego zakresu: jakości procesu raportowania, ponownej weryfikacji pokrycia oraz przygotowania materiałów dla deweloperów i stakeholderów.

Zakres sesji

Punktem wyjścia był folder l17 z 142 testami Playwright API. W poprzedniej rozmowie dwa brakujące według repozytoryjnego kontraktu endpointy otrzymały dedykowane specy, a suite zakończył się wynikiem 142/142. W tym forku użytkownik poprosił o dwa kolejne usprawnienia procesu.

Pierwsze dotyczyło repozytoryjnego skilla testów API. Każda nieoczekiwana odpowiedź 5xx, rozbieżność kontraktu, problem z autoryzacją albo cleanupem miały automatycznie uruchamiać triage: zachowanie dowodów, bezpieczną reprodukcję i utworzenie raportu błędu bez oczekiwania na dodatkową prośbę użytkownika.

Drugie usprawnienie dotyczyło dokumentacji. Dwa rozrastające się plany testów miały zostać zastąpione jednym aktualnym raportem Markdown dla zespołu technicznego oraz estetycznym, samodzielnym raportem HTML dla stakeholderów. Raporty miały pokazywać nie tylko liczbę zielonych testów, lecz również realne luki i następne działania.

Prompty użyte w Codex

Najważniejszy prompt otwierający fork dotyczył przebudowy skilla i raportów:

Dobra, to teraz tak. Chciałbym, żebyś zmienił naszego skilla do testowania,
żeby on zwracał większą uwagę na błędy. W momencie, kiedy widzimy błąd, to
powinien zgłaszać raport, powinien spróbować to zeprodukować. Nie powinno być
tak, że ja muszę się upominać o to. Także dajmy na to większą emfazę w skillu.
Poza tym wydaje mi się, że mamy już nieaktualne te test plany. Wydaje się to być
trochę out of date. Także przygotujmy jeden raport pokrycia i statusu w
Markdownie dla nas, dla deweloperów, zamiast tych dwóch test planów. I
przygotujmy jeszcze jeden raport pokrycia i tego, co zrobiliśmy, dla
stakeholderów. I ten raport powinien być estetyczny wizualnie, ładny i powinien
być w HTML-u, tak żebyśmy mogli to wrzucić albo gdzieś hostować na potrzeby
naszego zarządu, naszych szefów.

Użytkownik wskazał następnie właściwy checkpoint:

work in l17 now

Po pierwszej wersji raportu użytkownik poprosił o bardziej decyzyjne metryki:

Tylko widzę, że nie napisałeś mi jasno, które endpointy mamy niepokryte przez
testy automatyczne i jaki mamy coverage, jeśli chodzi o końcówki endpointy.
Więc to bym chciał mieć w raporcie, bo chciałbym, żeby to dawało mi informacje,
co mogę zrobić dalej.

Najważniejsza korekta przyszła po zakwestionowaniu wyniku 100% i przekazaniu aktualnego Swaggera:

Sprawdź mi proszę, że na pewno mamy 100% endpointów pokrytych, bo wydaje mi się
to nierealne. Zresztą jeden endpoint odnośnie inwentory doszedł później, więc
upewnij się proszę, że faktycznie mamy aż tak duże pokrycie.

Co sprawdził Codex przed zmianami?

Codex przeczytał instrukcje repozytorium, skill testów API, skill tworzenia skilli oraz standardy przygotowania warstwy frontendowej. Następnie sprawdził stan l17: 47 plików spec, 142 odkrywane testy, klientów HTTP, fixture, dwa raporty błędów backendu oraz oba istniejące plany testów.

Pierwszy audyt został wykonany względem repozytoryjnego api-docs.json. Plik zawierał 42 operacje HTTP i dla każdej z nich dało się wskazać dedykowany spec. Na tej podstawie powstał początkowy wynik 42/42 operacji. Był on spójny z lokalnym snapshotem kontraktu, ale nie z aktualnym API.

To rozróżnienie okazało się kluczowe: zielony suite i komplet względem starego pliku OpenAPI nie oznaczały kompletnego pokrycia bieżącego produktu.

Jak zweryfikowano aktualny kontrakt?

Po uwadze użytkownika Codex pobrał bieżące dokumenty /v3/api-docs z obu środowisk używanych przez l17 i porównał każdą parę metoda + ścieżka oraz udokumentowane statusy z repozytoryjnym snapshotem i specami.

Swagger aitesters.byst.re zawierał 55 operacji, 44 szablony ścieżek i 191 udokumentowanych kombinacji operacja + status. Środowisko kursowe awesome.byst.re zawierało 53 operacje, 43 szablony ścieżek i 188 kombinacji. Różnicą były dwie operacje lokalnego outboxa email dostępne wyłącznie na aitesters.

Audyt potwierdził, że l17 automatyzuje 42 operacje na 32 szablonach ścieżek. Dla pełniejszego środowiska oznaczało to:

32/44 szablony ścieżek, czyli 72,7%,
42/55 operacji HTTP, czyli 76,4%,
121/191 udokumentowanych odpowiedzi, czyli 63,4%,
13 operacji całkowicie bez automatyzacji,
18 operacji z częściowym pokryciem statusów,
24 operacje z pełną udokumentowaną macierzą statusów.

Brakujące operacje obejmowały cztery operacje inventory, siedem operacji 2FA i SSO oraz dwie operacje lokalnego email outboxa. Uwaga użytkownika o później dodanym inventory była więc trafna: właśnie ta powierzchnia nie występowała w starym api-docs.json i nie miała testów w l17.

Co zmieniono w skillu testów API?

Skill otrzymał obowiązkową bramkę obsługi defektów. Za sygnał błędu uznawane są teraz między innymi nieoczekiwane 5xx, rozbieżności statusu lub schematu, niespójne uwierzytelnienie i walidacja, nieudany cleanup, destrukcyjne efekty uboczne oraz zachowanie przerywane.

Po wykryciu sygnału agent ma zachować pierwsze dowody, wykonać do trzech bezpiecznych prób przez curl, porównać wynik z kontraktem i kodem backendu, utworzyć albo zaktualizować raport w bug-reports/, podlinkować go w raporcie pokrycia i nie zamieniać wadliwego zachowania w oczekiwaną asercję regresyjną.

Po korekcie wyniku 100% skill otrzymał również bramkę świeżości kontraktu. Przed publikacją metryk musi pobrać /v3/api-docs z każdego środowiska w zakresie, porównać go z repozytoryjnym snapshotem i użyć bieżącego kontraktu jako mianownika. Gdy środowiska mają różne powierzchnie, raport ma podawać osobne wyniki.

Jak przebudowano raportowanie?

l17/api-test-plan.md został skrócony do jednego bieżącego raportu dla deweloperów i QA. Stary api-test-plan-history.md usunięto, ponieważ historia implementacji jest dostępna w Git, a szczegółowe dowody defektów pozostają w bug-reports/.

Raport techniczny pokazuje definicję pokrycia, trzy poziomy metryk, wszystkie 13 nieautomatyzowanych operacji, wszystkie 18 operacji częściowych, statusy brakujących odpowiedzi, przyczynę luki i rekomendowane następne działanie. Rozdziela też wynik dla aitesters od wyniku dla autorytatywnego środowiska kursowego.

Powstał również l17/api-coverage-report.html: samodzielny raport dla stakeholderów bez zewnętrznych bibliotek i zasobów. Zawiera czytelne KPI, pokrycie domenowe, rejestr brakujących operacji, rejestr niepełnych macierzy, dwa potwierdzone defekty backendu, ograniczenia testowalności i priorytety dla QA, security, platformy oraz backendu.

Jakie korekty wynikły z review?

Najważniejszą korektę wymusiło review użytkownika. Pierwotne 100% było poprawne wyłącznie względem starego snapshotu, dlatego wszystkie raporty zostały przeliczone względem live Swaggera. W finalnej wersji nie ma już twierdzenia, że każdy endpoint jest pokryty.

Review wizualne wykryło też problem techniczny w HTML. Pierwszy pełnostronicowy screenshot zawierał duże puste obszary, ponieważ sekcje poza viewportem miały opacity: 0 do czasu uruchomienia IntersectionObserver. Efekt wejścia został uproszczony tak, aby treść była zawsze widoczna, a animacja pasków nie blokowała wydruku ani pełnego zrzutu strony.

Drugi przebieg sprawdził widok desktopowy 1440 px i mobilny 390 px. Strona nie miała poziomego overflow, błędów w konsoli ani niedostępnych linków do lokalnych raportów. Tabele zawierały dokładnie 13 i 18 wierszy, zgodnie z audytem.

Wynik walidacji

Obszar	Wynik
Live Swagger `aitesters`	55 operacji, 44 ścieżki, 191 odpowiedzi
Live Swagger `awesome`	53 operacje, 43 ścieżki, 188 odpowiedzi
Pokrycie operacji `aitesters`	42/55, czyli 76,4%
Pokrycie szablonów ścieżek `aitesters`	32/44, czyli 72,7%
Pokrycie odpowiedzi `aitesters`	121/191, czyli 63,4%
HTML desktop/mobile	brak overflow i błędów konsoli
Linki raportu HTML	wszystkie lokalne cele zwróciły `200`
Walidacja skilla	`Skill is valid!`
`git diff --check`	bez błędów

W tym forku nie zmieniano testów Playwright, klientów HTTP ani fixture, dlatego nie uruchamiano ponownie suite tylko dla zmian dokumentacyjnych, skilla i HTML. Ostatni pełny wynik checkpointu l17 pozostaje 142/142, ale raport jasno oddziela zielony wynik istniejących testów od pokrycia aktualnego kontraktu.

Finalny efekt sesji

Sesja pokazała dwa ważne mechanizmy kontroli jakości pracy z agentem. Po pierwsze, wykryty błąd produktu nie może pozostać wzmianką wymagającą dodatkowego przypomnienia od człowieka. Powinien automatycznie przejść przez reprodukcję, raport i ocenę wpływu na pokrycie.

Po drugie, procent pokrycia jest wiarygodny tylko wtedy, gdy jego mianownik pochodzi z aktualnego kontraktu. Liczba zielonych testów i komplet względem lokalnego pliku OpenAPI mogą dać fałszywe poczucie bezpieczeństwa, jeśli API rozwinęło się po zapisaniu snapshotu.

Finalnym rezultatem jest jeden aktualny raport techniczny, samodzielny raport HTML dla stakeholderów oraz skill, który wymusza defect triage i kontrolę świeżości kontraktu. Najbliższym sensownym incrementem jest automatyzacja czterech operacji inventory, a następnie bezpiecznych przepływów 2FA i SSO.