React

Le query giuste di Testing Library, in ordine

Le query di Testing Library hanno un ordine: ruolo, etichetta, testo, test id. La query sbagliata rende il test fragile o inutile.

In sintesi

  • La scala è ruolo, etichetta, testo, test id: scendi solo se il livello sopra non esiste.
  • queryBy serve per l'assenza, findBy per ciò che arriva dopo una richiesta.
  • Un test che non trova il ruolo segnala spesso un problema di accessibilità.

Testing Library ha una scala di priorità: prima il ruolo, poi l'etichetta, il testo e solo alla fine il data-testid.

La scala, dall'alto

  • getByRole: vede la pagina come uno screen reader e verifica anche il nome accessibile.
  • getByLabelText: per i campi con label associata; fallisce se l'associazione manca, ed è un buon segnale.
  • getByText: per i contenuti statici e i messaggi, non per i campi.
  • getByTestId: ultima risorsa, per le parti senza ruolo né testo, come un contenitore di layout.

La query giusta in pratica

import { render, screen } from "@testing-library/react";

render();

screen.getByRole("textbox", { name: /email/i });
screen.getByRole("button", { name: /accedi/i });
screen.queryByRole("alert");
screen.findByText(/benvenuto/i);

Le tre varianti cambiano il significato: getBy fallisce se l'elemento manca, queryBy restituisce null ed è l'unica usabile per verificare l'assenza, findBy attende e serve per ciò che arriva dopo una richiesta.

Gli errori che dicono qualcosa

  • Found multiple elements: due elementi hanno lo stesso nome accessibile, quindi l'etichetta è ambigua.
  • Unable to find role: manca il ruolo semantico, spesso perché il clic è su un div.
  • Not wrapped in act: un aggiornamento arriva fuori dall'attesa; usa await su findBy.

Il comando

npx vitest run -t "login"

Il filtro -t esegue solo i test con quel nome: utile mentre si sistema una query, senza aspettare l'intera suite.

Tre componenti su cui provare le query: input, login-form e multistep-form. Per sfogliare per categoria parti da 111.985 componenti.

La limitazione

Un ruolo corretto non garantisce un'interazione corretta: la query trova il pulsante anche se è coperto, disabilitato o fuori schermo. jsdom non calcola il layout, quindi quei difetti restano invisibili.

Dove continuare

Il quadro dei cinque test è in Testing Library: cinque test; la checklist è in componenti React accessibili; come si legge la documentazione è in documentazione React.

Domande frequenti

Meglio getByRole o getByTestId?

getByRole, quando esiste. Verifica anche il nome accessibile; il test id resta per le parti senza ruolo né testo.

Quando uso queryBy?

Solo per verificare che un elemento non ci sia: restituisce null invece di lanciare.

Perché findBy e non waitFor?

findBy combina attesa e query ed è più corto; waitFor serve quando l'attesa riguarda più asserzioni.

getByText trova il testo dentro un pulsante?

Sì, ma è fragile: il nome del pulsante cambia con il ruolo. Meglio getByRole con name.

Le query distinguono maiuscole e minuscole?

No di default: il confronto ignora il caso e normalizza gli spazi.