# The right Testing Library queries, in priority order

Testing Library queries have an order: role, label, text, test id. The wrong query makes a test fragile or meaningless.

> Page: https://ui.eneawork.it/blog/testing-library-query-corrette
> Markdown: https://ui.eneawork.it/blog/testing-library-query-corrette.md

*2026-11-01*

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

Il catalogo EneUI conta 111.985 componenti, 1.556 blocchi e 12.808 icone da 1.472 librerie, misurati da /api/stats il 1 novembre 2026. La cifra viene da una query all'endpoint, non da una stima: conta i record pubblicati, non la qualità dei componenti.

## La scala, dall'alto

## 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

## 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.

## Record vivi nel catalogo

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.

## FAQ

### 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.