Vai al contenuto

Test di regressione visiva in un design system con un browser fisso

Design · 18 novembre 2026 · 7 min di lettura

Loops winding across a grid of tiles in black, white and grey

Il test di regressione visiva di un design system è un controllo che disegna ogni stato di ogni componente, confronta ciascuna immagine con una baseline approvata e fa fallire la pull request quando cambiano pixel che nessuno voleva cambiare. Trova quello che la code review non vede: un token di padding modificato per un bottone che sposta altri quaranta componenti, un peso del font che salta dopo l'aggiornamento di una dipendenza, un tema scuro che perde un bordo.

Alla fine di questa guida la libreria ne ha uno. A ogni pull request ogni story di Storybook viene fotografata nello stesso browser, sempre quello, con soglie calibrate sul componente. Su un branch senza modifiche il controllo non trova differenze; una modifica voluta mostra esattamente le story che tocca, e nessun'altra.

Cosa serve prima di cominciare

  • Una libreria di componenti con le sue story, una per ogni stato da proteggere (variante, dimensione, tema, disabilitato, errore).
  • Una pipeline di CI che parte a ogni pull request.
  • Docker nella CI, oppure un servizio esterno che si occupa del rendering.
  • Una persona, con un nome, che approva i cambi di baseline. Senza un responsabile, ogni differenza la accetta chi ha più fretta.

Passo 1: ogni stato diventa una story

L'unità del test visivo è la story. La documentazione di Storybook lo dice chiaramente: con i test visivi attivi, ogni story diventa automaticamente un test. La copertura quindi si decide quando si scrivono le story. Un bottone con tre varianti, tre dimensioni e due temi ha 18 stati: una story che li mette tutti in griglia costa meno di 18 story separate e li mostra comunque tutti.

Nel primo giro le pagine restano fuori. Una pagina intera mescola una dozzina di componenti con contenuti reali, e una differenza lì può voler dire qualsiasi cosa. Le story di componente falliscono con un nome: è cambiato Button/Primary/Dark, e chi rivede sa dove guardare.

Un conto veloce fissa il budget del passo 5. Quaranta componenti con una media di sei story ciascuno, in due temi, fanno 480 snapshot a ogni esecuzione completa.

Passo 2: fissare il browser che disegna la baseline

È il passo che le suite instabili saltano più spesso. La guida di Playwright ai confronti visivi avverte che il rendering del browser cambia con il sistema operativo, la versione, le impostazioni, l'hardware, l'alimentazione e la modalità headless, e che per avere screenshot coerenti serve lo stesso ambiente che ha generato la baseline. L'antialiasing dei font su macOS e su Linux è abbastanza diverso da far fallire ogni story che contiene testo.

Per questo la baseline non si genera mai su un portatile. Si genera nello stesso container che usa la CI. Playwright pubblica un'immagine ufficiale apposta, legata alla versione (mcr.microsoft.com/playwright:v1.64.1-noble mentre scriviamo, secondo la pagina su Docker). Anche in locale il comando di aggiornamento gira dentro quell'immagine:

docker run --rm -v $(pwd):/work -w /work mcr.microsoft.com/playwright:v1.64.1-noble npx playwright test --update-snapshots

Playwright dà a ogni baseline il nome del browser e della piattaforma (chromium-linux), così una baseline fatta su Mac e una fatta su Linux non si confondono. L'immagine si aggiorna in una pull request a parte, la baseline si rigenera in quella stessa pull request, e lì dentro non cambia nient'altro.

Passo 3: fermare tutto quello che si muove

Due esecuzioni dello stesso codice devono produrre lo stesso snapshot. Tutto ciò che dipende dall'ora, dal caso o dalla rete lo impedisce. Una parte la risolve già toHaveScreenshot di Playwright, come spiega il suo riferimento delle asserzioni:

  • Le animazioni sono disattivate di default. Animazioni e transizioni CSS finite vengono portate alla fine, quelle infinite tornano allo stato iniziale.
  • Il cursore di testo è nascosto di default.
  • L'asserzione aspetta due screenshot consecutivi identici prima del confronto, e così assorbe gli spostamenti di layout tardivi.

Il resto tocca alle story. Si fissa la data che il componente vede. Si dà un seme a ogni dato casuale. Avatar e immagini arrivano da file locali. Prima dello scatto si aspetta document.fonts.ready, così un font di ripiego non finisce mai in una baseline. Per i contenuti che devono restare vivi, come un orario relativo, l'opzione mask copre il locator con un riquadro pieno. Va usata con parsimonia: un'area mascherata è un'area che il test non controlla più.

Passo 4: tarare la soglia sul componente

Due numeri decidono quando una differenza fa fallire il test. threshold dice quanto deve cambiare un singolo pixel per contare, misurato nello spazio colore YIQ da 0 (severo) a 1 (permissivo), con 0,2 come valore predefinito. maxDiffPixels o maxDiffPixelRatio dice quanti pixel cambiati il test tollera.

L'errore tipico è un rapporto unico per tutta la suite. Una cattura di 1280 × 800 contiene 1.024.000 pixel, quindi un rapporto dell'1% tollera 10.240 pixel cambiati. Un bottone di 120 × 40 ne occupa 4.800. Con quella regola un bottone può sparire da una pagina e il test passa lo stesso. Le story ritagliate sul componente tengono i conti onesti: su una cattura piccola, un maxDiffPixels assoluto e basso (qualche decina di pixel per il rumore dell'antialiasing) trova un bordo cambiato di un pixel e ignora le oscillazioni sotto il pixel.

La soglia di una singola story si alza solo con un commento che spiega il perché, come quando si disattiva una regola di lint su una riga.

Passo 5: scegliere dove girano gli snapshot

Le opzioni oneste sono due, e decide il conto degli snapshot fatto al passo 1.

In hosting, con Chromatic. Lo gestisce il team di Storybook, la revisione si fa in un'interfaccia web e i piani a pagamento testano anche Safari, Firefox ed Edge. La pagina dei prezzi di Chromatic indica un piano gratuito con 5.000 snapshot al mese, Starter a 179 dollari al mese per 35.000 e Pro a 399 dollari per 85.000. TurboSnap fotografa solo le story toccate da una modifica, e quelle non toccate valgono una frazione di snapshot (la pagina dei prezzi equipara 35.000 snapshot fatturati a 175.000 turbosnap, un quinto ciascuno). Con 480 snapshot a esecuzione completa, il piano gratuito copre una decina di esecuzioni complete al mese; con TurboSnap attivo, una pull request che tocca due componenti costa molto meno.

In casa, con Playwright. Nessuna fattura per snapshot. Le baseline sono file PNG nel repository, la revisione è il report HTML di Playwright e i browser coperti sono quelli elencati nella configurazione. Il costo si sposta sullo spazio in git e sul tempo di chi legge i report.

Di base scegliamo Playwright in casa per le librerie sotto qualche centinaio di story con un solo responsabile, e un servizio in hosting quando contribuiscono più team e serve una coda di revisione condivisa. I passi da 1 a 4 restano identici in entrambi i casi.

Passo 6: trasformare ogni differenza in una decisione

Un test visivo che fallisce fa una sola domanda: la modifica era voluta? La risposta sta nella pull request che l'ha causata. Se era voluta, la stessa pull request aggiorna la baseline e il responsabile approva la nuova immagine accanto alla vecchia. Se non lo era, si corregge il codice e la baseline resta com'è.

Due regole tengono pulita la coda. Gli aggiornamenti di baseline non si raccolgono mai in un commit separato del tipo «aggiorna snapshot», perché così si perde quale modifica al codice ha spostato quale immagine. E una differenza in un componente condiviso è una questione di versione: un layout che si sposta per chi aggiorna senza toccare il proprio codice può essere una modifica incompatibile, come spieghiamo nell'articolo sul versionamento di un design system.

Come verificare che la suite funzioni

  • Lanciare la suite due volte sul main senza modifiche. Entrambe le esecuzioni devono dare zero differenze. Una story instabile qui verrà ignorata per sempre.
  • Cambiare apposta un token, per esempio un raggio da 6 a 8 pixel. Devono fallire le story che lo usano, e solo quelle.
  • Togliere il bordo di un componente in un branch di prova. Il confronto deve fallire con il nome della story di quel componente.

Gli errori più comuni e come correggerli

  • In CI falliscono tutte le story, in locale passano. La baseline viene da un altro sistema operativo. Va rigenerata dentro il container fissato (passo 2).
  • Dopo un aggiornamento falliscono tutte le story con del testo. Con il test runner è cambiata anche la versione del browser. Si rigenera la baseline in una pull request che contiene solo l'aggiornamento.
  • La stessa story fallisce una volta su dieci. Qualcosa si muove ancora: un web font, un'immagine caricata in lazy loading, un valore senza seme. Va trovato prima di alzare la soglia.
  • È passata una regressione vera. Controllare le maschere e il rapporto. Una maschera grande o un rapporto calcolato sulla pagina nascondono interi componenti (passo 4).

I test visivi sono uno dei controlli contro il drift che descriviamo nell'articolo su come un design system si degrada. Vedono che cosa è cambiato sullo schermo. Il perché non lo vedono, ed è a questo che serve la revisione del passo 6.

Domande frequenti

Preferisci che lo facciamo noi?

Progettiamo e sviluppiamo questo tipo di lavoro per i clienti. Raccontaci di cosa hai bisogno.