Come usare Playwright per i test con screenshot

I test con screenshot in Playwright servono a rilevare modifiche dell'interfaccia prima della pubblicazione. Il test apre una pagina, attende uno stato stabile, acquisisce un'immagine e la confronta con un riferimento approvato. È questa la differenza tra la normale automazione degli screenshot e i test di regressione visiva.

Gli esempi usano la pagina delle funzioni di Shotomatic, https://www.shotomatic.com/features, come destinazione pubblica. Lo stesso schema è ancora più utile nella tua app, dove puoi controllare dati, stato di accesso, animazioni e selettori di test.

Se devi soltanto creare file immagine da un elenco di URL, parti dalla normale automazione degli screenshot con Playwright. Questo articolo riguarda invece i test: immagini di riferimento, confronto, progetti per browser e revisione.

Quando vale la pena usare i test con screenshot

I test con screenshot sono utili quando una normale asserzione potrebbe non rilevare facilmente un errore visivo.

Buoni candidati:

• pagine marketing con sezioni principali, prezzi o registrazione importanti;
• componenti di un design system con molti stati;
• schermate di pagamento, onboarding o dashboard in cui conta il layout;
• pagine responsive che si rompono spesso alle larghezze mobile;
• pagine in cui una modifica CSS può spostare o nascondere contenuti senza altri segnali.

Candidati poco adatti:

• pagine con feed, annunci, orari o contenuti degli utenti che cambiano continuamente;
• pagine in cui la resa visiva non è importante;
• percorsi già coperti meglio da asserzioni su testo, ruoli o comportamento;
• siti interi con centinaia di pagine instabili e nessun processo di revisione.

Parti da poche schermate importanti. I test diventano rumorosi quando chiedi loro di controllare tutto.

Installa Playwright Test

In un progetto Node nuovo o esistente, l'installatore ufficiale di Playwright può creare la struttura del test runner, il file di configurazione, i test di esempio e la fase di installazione dei browser:

$ npm init playwright@latest

L'installatore chiede se usare TypeScript o JavaScript, dove salvare i test, se aggiungere un flusso GitHub Actions e se installare i browser. Dopo la configurazione, esegui i test:

$ npx playwright test

Gli esempi di questo articolo usano file TypeScript nella cartella tests/.

Crea il primo test con screenshot

Crea tests/features-page.spec.ts:

import { expect, test } from "@playwright/test";

test("features page has a stable desktop layout", async ({ page }) => {
  await page.goto("https://www.shotomatic.com/features");

  await expect(
    page.getByRole("heading", {
      name: /Shotomatic Features/i,
    }),
  ).toBeVisible();

  await expect(page).toHaveScreenshot("features-page-desktop.png", {
    fullPage: true,
  });
});

La differenza rispetto a page.screenshot() sta nell'asserzione. toHaveScreenshot() di Playwright Test crea un'immagine di riferimento oppure esegue il confronto. La prima esecuzione scrive il riferimento mancante; quelle successive confrontano lo screenshot attuale con l'immagine salvata.

Esegui il test:

$ npx playwright test tests/features-page.spec.ts

Alla prima esecuzione, Playwright scrive una nuova immagine prevista perché il riferimento non esiste ancora. Controllala prima di inserirla nel repository. Un'immagine di riferimento è un'aspettativa del test, non un file casuale.

Verifica una parte più piccola della pagina

Gli screenshot a pagina intera rilevano ampi cambiamenti di layout, ma falliscono più facilmente a causa di modifiche non correlate nella parte inferiore. Per molti gruppi è più semplice mantenere il riferimento di una sezione o di un componente.

import { expect, test } from "@playwright/test";

test("features comparison cards stay aligned", async ({ page }) => {
  await page.goto("https://www.shotomatic.com/features");

  const comparisonHeading = page.getByRole("heading", {
    name: /Choose a workflow/i,
  });
  const comparisonSection = page.locator("section").filter({
    has: comparisonHeading,
  });

  await expect(comparisonHeading).toBeVisible();
  await expect(comparisonSection).toHaveScreenshot("features-comparison-section.png");
});

Usa gli screenshot di un locator se la domanda da verificare è locale: questa sezione ha ancora l'aspetto corretto? Usa quelli della pagina quando conta il layout complessivo.

Aggiungi progetti per browser e dispositivi

Il test runner di Playwright può eseguire lo stesso test in più progetti denominati. È qui che un test con screenshot si differenzia da un semplice script di acquisizione: browser, dispositivo, viewport e nome dello snapshot diventano tutti parte della matrice.

Esempio di playwright.config.ts:

import { defineConfig, devices } from "@playwright/test";

export default defineConfig({
  testDir: "./tests",
  use: {
    baseURL: "https://www.shotomatic.com",
    trace: "on-first-retry",
  },
  projects: [
    {
      name: "desktop-chromium",
      use: {
        ...devices["Desktop Chrome"],
        viewport: { width: 1440, height: 1000 },
      },
    },
    {
      name: "mobile-safari",
      use: {
        ...devices["iPhone 13"],
      },
    },
  ],
});

Ora usa URL relativi nel test:

import { expect, test } from "@playwright/test";

test("features page visual baseline", async ({ page }) => {
  await page.goto("/features");
  await expect(page.getByRole("main")).toBeVisible();

  await expect(page).toHaveScreenshot("features-page.png", {
    fullPage: true,
  });
});

Playwright conserva snapshot diversi per ogni progetto, così i riferimenti desktop e mobile possono convivere senza fingere che debbano coincidere. È più utile di un singolo screenshot della viewport quando vuoi verificare l'interfaccia su più dimensioni di dispositivo.

Rendi stabile lo stato della pagina

Molti errori intermittenti negli screenshot dipendono da uno stato instabile della pagina. Durante le asserzioni, Playwright disabilita per impostazione predefinita animazioni e transizioni CSS, ma dati variabili, contenuti ritardati, annunci ed elementi specifici dell'utente possono comunque spostare i pixel.

Prima di acquisire, attendi una condizione precisa:

await page.goto("/features");
await expect(page.getByRole("main")).toBeVisible();
await expect(page.getByText("Hands-Free Capture")).toBeVisible();

Non affidarti principalmente a un timeout fisso. Se la pagina richiede una scheda, un titolo, una tabella o un'immagine caricata per essere pronta, attendi direttamente quella condizione.

Se la pagina carica i contenuti fuori dalla viewport soltanto durante lo scorrimento, scorri prima dello screenshot a pagina intera:

await page.evaluate(async () => {
  const delay = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
  const viewportHeight = window.innerHeight;

  for (let y = 0; y < document.body.scrollHeight; y += viewportHeight) {
    window.scrollTo(0, y);
    await delay(100);
  }

  window.scrollTo(0, 0);
});

Un helper di questo tipo va bene quando serve alla pagina. Tienilo vicino al test, così chi lo manterrà in futuro capirà perché esiste lo scorrimento.

Nascondi o maschera gli elementi variabili

Alcune parti della pagina non devono partecipare al confronto: orari, avatar, annunci, nomi degli utenti, indicatori di caricamento o miniature video.

Hai due opzioni comuni.

Maschera locator specifici:

await expect(page).toHaveScreenshot("features-page.png", {
  fullPage: true,
  mask: [page.locator("[data-testid='release-date']")],
});

Oppure applica un foglio di stile durante l'acquisizione:

await expect(page).toHaveScreenshot("features-page.png", {
  fullPage: true,
  stylePath: "./tests/screenshot.css",
});

Esempio di tests/screenshot.css:

[data-testid="release-date"],
[data-testid="animated-cursor"] {
  visibility: hidden !important;
}

Non nascondere parti reali dell'interfaccia soltanto per superare il test. Le maschere servono ai contenuti variabili che non fanno parte della verifica visiva.

Imposta con cautela una soglia di differenza

Playwright può accettare una quantità limitata di pixel diversi:

await expect(page).toHaveScreenshot("features-page.png", {
  fullPage: true,
  maxDiffPixels: 100,
});

È utile per piccole differenze di rendering, ma può anche nascondere regressioni reali. Mantieni bassa la soglia, documentane il motivo e prova prima a rendere deterministica la pagina.

Puoi anche condividere i valori predefiniti delle asserzioni in playwright.config.ts:

import { defineConfig } from "@playwright/test";

export default defineConfig({
  expect: {
    toHaveScreenshot: {
      maxDiffPixels: 100,
    },
  },
});

Controlla e aggiorna le immagini di riferimento

Quando un test con screenshot non passa, la domanda non è "come lo rendiamo verde?", ma "questa modifica visiva era prevista?".

Se si tratta di un errore, correggi l'interfaccia ed esegui di nuovo il test. Se il cambiamento è intenzionale, aggiorna il riferimento:

$ npx playwright test --update-snapshots

Controlla poi la nuova immagine nella pull request. Tratta gli aggiornamenti degli snapshot come modifiche al codice: chi li approva deve capire che cosa è cambiato e perché.

Esegui i test con screenshot nella CI

I confronti tra screenshot sono sensibili all'ambiente. Font, sistema operativo, versione del browser, hardware e modalità headless possono cambiare i pixel. Per risultati stabili, genera e confronta i riferimenti nello stesso ambiente.

In pratica, di solito conviene:

• inserire nel repository i riferimenti generati nella CI o in un contenitore locale equivalente;
• eseguire il progetto degli screenshot nelle pull request;
• non mescolare riferimenti creati su macOS con la CI Linux, a meno di accettare le differenze;
• aggiornare intenzionalmente Playwright e i file binari dei browser;
• controllare gli snapshot modificati prima di approvarli.

Usa il report HTML o il visualizzatore delle trace di Playwright quando un errore è difficile da interpretare. Un test visivo non superato richiede più contesto di revisione rispetto al solo stato rosso della build.

Quando serve ancora la normale automazione degli screenshot

I test con screenshot sono controlli di qualità dell'interfaccia gestiti nel codice. Non svolgono lo stesso lavoro della raccolta di immagini per revisione, report, archivi o contenuti.

Usa la normale automazione con Playwright quando ti servono file risultanti da più URL.

Usa l'automazione con Puppeteer se vuoi un piccolo script incentrato su Chrome e non ti serve Playwright Test.

Usa Website Capture in Shotomatic per acquisire senza codice un elenco di URL: aggiungi gli indirizzi, regola le opzioni, controlla i risultati ed esporta senza mantenere una suite di test. Può bastare quando un gruppo controlla manualmente gli screenshot responsive. Per un esito automatico positivo o negativo, mantieni invece la procedura in Playwright Test.

Errori comuni

• Verificare una porzione troppo grande della pagina: parti dalle sezioni importanti prima di usare riferimenti a pagina intera.
• Acquisire dati instabili: usa dati di test fissi, maschere o stili per i contenuti che cambiano a ogni esecuzione.
• Aggiornare gli snapshot alla cieca: modifica i riferimenti soltanto dopo aver controllato la differenza visiva.
• Generare i riferimenti su una macchina e confrontarli su un'altra: mantieni coerente l'ambiente di rendering.
• Trattare i test visivi come test di comportamento: abbina gli screenshot alle normali asserzioni su testo, ruoli, navigazione e interazioni.

Domande frequenti

Playwright può eseguire test con screenshot?

Sì. Playwright Test include asserzioni per gli screenshot con expect(page).toHaveScreenshot() ed expect(locator).toHaveScreenshot().

In che cosa differiscono i test con screenshot dal semplice salvataggio delle immagini?

Salvare gli screenshot crea file immagine. Un test confronta i nuovi screenshot con immagini di riferimento approvate e non supera la prova quando la differenza oltrepassa la soglia consentita.

Dove conserva Playwright le immagini di riferimento?

Per impostazione predefinita, Playwright conserva le immagini in una cartella che prende il nome dal file di test con il suffisso -snapshots. Puoi personalizzare il percorso con snapshotPathTemplate nella configurazione.

Come si aggiornano le immagini di riferimento in Playwright?

Dopo aver verificato che la modifica visiva sia intenzionale, esegui Playwright Test con --update-snapshots.

Conviene usare test con screenshot per ogni pagina?

No. Usali per stati importanti e stabili dell'interfaccia. Verifica il comportamento con le normali asserzioni e riserva le immagini di riferimento alle pagine o ai componenti in cui contano le modifiche al layout.

Riferimenti

Gli esempi sono stati verificati sulla documentazione ufficiale attuale:

• Guida all'installazione di Playwright per configurare Playwright Test;
• guida ai confronti visivi per toHaveScreenshot(), immagini di riferimento, aggiornamenti e opzioni di confronto;
• API PageAssertions.toHaveScreenshot() per fullPage, mask, stylePath, maxDiffPixels, threshold e opzioni correlate;
• guida alle asserzioni per le asserzioni web con nuovi tentativi automatici;
• guida all'esecuzione e al debug dei test e guida al visualizzatore delle trace per controllare i test non superati.