Refaktor starego CSS z AI bez regresji wizualnych
Motyw sklepu ma dziesięć lat. Siatka Bootstrapa 3 z .row i .col-md-4, karty produktów na float: left z clearfixem, menu na display: inline-block, odstępy ustawiane marginesami, które ktoś kiedyś dobrał na oko. Działa, ale każda zmiana to ryzyko, więc nikt go nie rusza. Aż do dnia, w którym prosisz asystenta AI: „przepisz layout na flex i grid, bez zmiany wyglądu”.
Dziesięć minut później masz diff na półtora tysiąca linii. Strona główna na twoim laptopie wygląda identycznie. Lista produktów też. Wdrażasz. Następnego dnia przychodzą trzy zgłoszenia: w karcie produktu odstępy między ceną, nazwą i przyciskiem są dwa razy większe niż wcześniej; produkty z długą nazwą bez spacji – „Lampa-biurowa-LED-z-regulacją-3000K–6500K” – rozpychają kafelek poza siatkę; a menu na tablecie zawija się do drugiej linii, choć wcześniej się mieściło.
Żadna z tych zmian nie była zamierzona. Model zrobił dokładnie to, o co prosiłeś – przepisał CSS i „nie zmienił wyglądu” na tych ekranach, które sam sobie wyobraził. Nikt, łącznie z tobą, nie sprawdził pozostałych.
Dlaczego refaktor CSS tak trudno sprawdzić
Refaktor JavaScriptu ma siatki bezpieczeństwa: typy w TypeScripcie zgłaszają, że funkcja dostaje inny argument, testy jednostkowe – że zwraca inny wynik. CSS nie ma ani jednego, ani drugiego. Poprawność arkusza stylów to wyłącznie to, jak wygląda strona: piksele w konkretnym oknie, z konkretną treścią, w konkretnej przeglądarce.
Do tego CSS jest nielokalny. Zmiana w jednej regule wpływa na elementy w zupełnie innym miejscu – przez kaskadę, dziedziczenie, zapadanie się marginesów albo zmianę rozmiaru rodzica. W artykule o natywnym nestingu pokazywałem, jak przeniesienie kodu z SCSS do CSS bez zmiany ani jednego znaku w selektorach zmieniło kolor przycisku na drugim końcu strony – przez inną specyficzność :is(). Diff tego nie pokazuje. Pokazuje to dopiero wyrenderowana strona.
Model AI ma tu jeszcze jeden problem: nie widzi strony, dopóki mu jej nie pokażesz. Ocenia swój refaktor po kodzie, a w kodzie „flex z gap: 16px” wygląda jak dokładny odpowiednik „floatów z margin: 16px”. Na ekranie – nie zawsze.
Siatka bezpieczeństwa: zrzuty ekranu przed zmianą
Rozwiązanie jest stare i sprawdzone: testy regresji wizualnej. Przed refaktorem robisz zrzuty ekranu kluczowych stron w kilku szerokościach, po każdej zmianie robisz je ponownie i porównujesz piksel po pikselu. Playwright ma to wbudowane w toHaveScreenshot().
tsx
// playwright.config.tsimport { defineConfig } from "@playwright/test"export default defineConfig({testDir: "./tests",use: { baseURL: "http://localhost:3000" },expect: {toHaveScreenshot: { maxDiffPixelRatio: 0.001 },},projects: [{ name: "mobile", use: { viewport: { width: 390, height: 844 } } },{ name: "tablet", use: { viewport: { width: 820, height: 1180 } } },{ name: "desktop", use: { viewport: { width: 1440, height: 900 } } },],})
tsx
// tests/visual.spec.tsimport { test, expect } from "@playwright/test"const pages = ["/","/kategoria/lampy","/produkt/lampa-biurowa-led","/produkt/produkt-z-bardzo-dluga-nazwa","/koszyk",]for (const path of pages) {test("wygląd " + path, async ({ page }) => {await page.goto(path)await page.evaluate(async () => {await document.fonts.ready})await expect(page).toHaveScreenshot({fullPage: true,mask: [page.locator("[data-dynamic]")],})})}
Pierwsze uruchomienie – na kodzie sprzed refaktoru – zapisuje wzorcowe zrzuty w katalogu obok testu. Każde kolejne porównuje z nimi aktualny wygląd i kończy się błędem, jeśli różni się więcej niż 0,1% pikseli. Przy błędzie Playwright zapisuje w test-results trzy obrazy: wzorzec, aktualny zrzut i mapę różnic, na której zmienione piksele są zaznaczone na czerwono.
Zwróć uwagę na listę stron. Jest w niej produkt „z bardzo długą nazwą” – to nie przypadek. Zrzuty sprawdzają tylko to, co pokazują, więc strona testowa musi zawierać przypadki brzegowe: długie słowa, brak zdjęcia, produkt na promocji z dwiema cenami, pusty koszyk. Jedna strona z typową treścią przepuści większość regresji z wstępu.
Stabilne zrzuty: zanim zaczniesz im ufać
Test, który czasem przechodzi, a czasem nie, jest gorszy niż brak testu – po trzecim fałszywym alarmie wszyscy przestają czytać wyniki. Cztery źródła niestabilności warto wyeliminować od razu:
- Fonty. Zrzut zrobiony, zanim załaduje się webfont, pokazuje font zastępczy.
document.fonts.readyw teście czeka, aż fonty będą gotowe. - Animacje.
toHaveScreenshot()domyślnie zatrzymuje animacje i przejścia CSS, ale animacje sterowane JavaScriptem – karuzele, liczniki – trzeba zatrzymać samemu albo zamaskować. - Dynamiczna treść. Data, licznik „kupiono 14 razy w tym tygodniu”, losowe polecane produkty. Oznacz je atrybutem i przekaż do
mask– Playwright zasłoni je jednolitym prostokątem. - System operacyjny. Ten sam CSS renderuje się nieco inaczej na macOS, Windowsie i Linuksie – inny antyaliasing fontów, inne paski przewijania. Playwright dopisuje nazwę platformy do nazw plików wzorców, ale w praktyce najprościej robić zrzuty zawsze w tym samym środowisku, na przykład w oficjalnym obrazie Dockera Playwrighta, lokalnie i w CI.
Refaktor małymi krokami
Z testami wizualnymi zmienia się sposób, w jaki prosisz AI o refaktor. Zamiast „przepisz cały layout”, prowadzisz go przez pętlę: jeden komponent, testy, przegląd różnic, następny komponent.
markdown
## Refaktor CSS- Przed pierwszą zmianą: npx playwright test – wszystkie testy muszą przejść.- Jeden komponent na krok (np. karta produktu, potem siatka listy, potem menu).- Po każdym kroku: npx playwright test.- Nigdy nie uruchamiaj testów z --update-snapshots i nie usuwaj ani nienadpisuj plików w katalogach *-snapshots.- Jeśli test nie przechodzi: wskaż stronę i szerokość, opisz różnicęna podstawie obrazu diff z test-results i podaj przyczynę w CSS.Nie poprawiaj dalej, dopóki nie potwierdzę, czy różnica jest zamierzona.
Taki fragment w CLAUDE.md albo innym pliku z zasadami – o którym pisałem w artykule o tym, dlaczego AI pisze CSS jak w 2015 roku – zmienia charakter współpracy. Agent, który może sam uruchomić testy i obejrzeć obraz różnic, przestaje oddawać kod, który „powinien wyglądać tak samo”. Oddaje kod, o którym wie, że wygląda tak samo – albo konkretną listę miejsc, gdzie nie wygląda, z wyjaśnieniem dlaczego.
Mały krok ma też drugą zaletę: gdy test nie przechodzi po zmianie jednego komponentu, wiadomo, gdzie szukać przyczyny. Po przepisaniu całego motywu naraz czerwona mapa różnic na stronie produktu może mieć dziesięć niezależnych źródeł.
Pułapka: AI naprawia test zamiast CSS
To najważniejszy powód, dla którego reguła o --update-snapshots stoi w zasadach osobno i bez wyjątków. Model, któremu każesz „doprowadzić do przechodzących testów”, ma dwie drogi: poprawić CSS albo zaktualizować wzorce. Druga jest krótsza, zawsze się udaje i z punktu widzenia polecenia jest poprawna – testy przechodzą.
bash
# To polecenie zapisuje aktualny wygląd jako nowy wzorzec.# Po nim każda regresja staje się „oczekiwanym wyglądem”.npx playwright test --update-snapshots
Po takiej „naprawie” zielone testy niczego już nie gwarantują, a regresja z wstępu jest zapisana w repozytorium jako wzorzec. Model nie robi tego złośliwie – po prostu nie odróżnia sam z siebie zamierzonej zmiany wyglądu od błędu, bo to decyzja projektowa, a nie techniczna.
Dlatego decyzję o aktualizacji wzorców zawsze podejmuje człowiek, po obejrzeniu mapy różnic. Warto to też zabezpieczyć poza plikiem z zasadami: w code review każda zmiana w katalogach *-snapshots powinna być widoczna i uzasadniona, a w CI testy wizualne uruchamiaj bez możliwości aktualizacji wzorców. Gdy zmiana wyglądu jest zamierzona – na przykład nowy odstęp w karcie – zaktualizuj wzorce w osobnym commicie, który zawiera tylko tę zmianę.
Co najczęściej się przesuwa przy przejściu z floatów na flex i grid
Większość regresji z takiego refaktoru ma kilka powtarzalnych źródeł. Warto je znać, bo pozwalają szybko przeczytać mapę różnic – i dopisać je do zasad, żeby model unikał ich od początku.
Marginesy przestają się zapadać. W zwykłym przepływie blokowym pionowe marginesy sąsiednich elementów się zapadają: dwa elementy z margin-block: 16px są od siebie oddalone o 16px, nie 32px. W kontenerze flex i grid zapadanie nie występuje.
css
/* Przed: elementy blokowe, odstęp między nimi 16px */.product-info > * {margin-block: 16px;}/* Po zmianie rodzica na flex: odstęp 32px */.product-info {display: flex;flex-direction: column;}/* Poprawnie: odstęp z gap, marginesy wyzerowane */.product-info {display: flex;flex-direction: column;gap: 16px;}.product-info > * {margin-block: 0;}
To właśnie „dwa razy większe odstępy w karcie produktu” z wstępu. Ta sama zasada działa też między rodzicem a pierwszym dzieckiem: margines górny nagłówka, który wcześniej „wychodził” poza kontener, w kontenerze flex zostaje w środku i przesuwa treść w dół.
Elementy flex nie chcą się zwężać poniżej treści. Domyślne min-width: auto w elementach flexa oznacza, że element nie zmniejszy się poniżej szerokości swojego najdłuższego niełamliwego fragmentu – długiego słowa, adresu URL, obrazka. Floaty i bloki po prostu pozwalały tekstowi wyjść poza ramkę, flex rozpycha cały kafelek.
css
.product-card__body {min-width: 0; /* pozwala zwęzić element poniżej treści */}.product-card__title {overflow-wrap: anywhere; /* łamie długie słowa bez spacji */}/* W gridzie ten sam problem rozwiązuje minmax(0, 1fr) zamiast 1fr */.product-grid {display: grid;grid-template-columns: repeat(auto-fill, minmax(min(240px, 100%), 1fr));}
Znikają odstępy między elementami inline-block. Menu zbudowane na display: inline-block miało między pozycjami kilka pikseli odstępu – nie z CSS, tylko ze spacji i znaków nowej linii w HTML-u, które przeglądarka renderuje jak tekst. Flex ignoruje te białe znaki, więc menu po refaktorze jest węższe o kilka pikseli na każdej pozycji – albo, jeśli model „wyrównał” to większym gap, szersze i zawija się na tablecie.
Ujemne marginesy siatki Bootstrapa. .row w Bootstrapie 3 ma margin: 0 -15px, a kolumny padding: 0 15px, żeby zewnętrzne krawędzie treści pokrywały się z kontenerem. Zamiana na grid z gap: 30px bez usunięcia paddingu kolumn albo bez korekty kontenera przesuwa zewnętrzne krawędzie o 15px – drobna, ale widoczna różnica w wyrównaniu z nagłówkiem i stopką.
Pułapki i dobre praktyki
- Najpierw wzorce, potem refaktor. Zrzuty ekranu muszą powstać na kodzie sprzed zmian. Wzorce zrobione po refaktorze utrwalają jego błędy.
- Strony testowe z przypadkami brzegowymi. Długie nazwy, brak zdjęć, dwie ceny, pusty koszyk – zrzuty łapią tylko to, co pokazują.
- Stabilność przed zaufaniem. Czekaj na fonty, maskuj dynamiczne treści, rób zrzuty zawsze w tym samym środowisku.
- Jeden komponent na krok. Krótka pętla zmiana–test–przegląd pozwala od razu wskazać przyczynę każdej różnicy.
- Zakaz
--update-snapshotsdla AI. Model, który ma doprowadzić testy do zielonego koloru, najłatwiej zrobi to, aktualizując wzorce. Tę decyzję zawsze podejmuje człowiek, w osobnym commicie. - Znaj typowe przesunięcia. Brak zapadania marginesów we flex i grid,
min-width: auto, białe znaki międzyinline-blocki ujemne marginesy.rowtłumaczą większość czerwonych map różnic. - Wsparcie przeglądarek.
gapwe flexie działa od Chrome 84, Firefox 63 i Safari 14.1, aoverflow-wrap: anywhereod Chrome 80, Firefox 65 i Safari 15.4 – jeśli refaktor ma wspierać starsze urządzenia, sprawdź to przed zamianą marginesów nagap.
Podsumowanie
Refaktor starego CSS to zadanie, w którym AI jest szybkie i przekonujące, a jego błędy są niewidoczne w diffie – bo poprawność CSS to wygląd strony, a nie kod. Testy regresji wizualnej w Playwright dają mu brakującą siatkę bezpieczeństwa: wzorcowe zrzuty sprzed zmian, porównanie po każdym kroku i mapę różnic, którą może obejrzeć zarówno człowiek, jak i agent. Dwie zasady decydują o tym, czy ta siatka działa: wzorce powstają przed refaktorem i tylko człowiek decyduje o ich aktualizacji – bo model poproszony o zielone testy najprościej osiągnie je, zapisując regresję jako nowy wzorzec. A gdy mapa różnic zrobi się czerwona, przyczyna zwykle jest jedną z kilku znanych: marginesy, które we flexie przestały się zapadać, min-width: auto, zniknięte odstępy między inline-block albo ujemne marginesy starej siatki.