React Testing Library — Test Componenti User-Centric che Riducono i Bug in Produzione

Il test che passa in locale e si rompe in produzione è il problema più costoso che un team React possa affrontare. Non perché i test siano scritti male, ma perché sono scritti nel modo sbagliato: testano l'implementazione, non il comportamento. Noi, di Meteora Web, abbiamo visto progetti con copertura al 90% e bug gravi in produzione, perché i test verificavano i dettagli interni dei componenti invece di quello che l'utente vede e tocca. React Testing Library esiste per risolvere esattamente questo problema. In questa guida vediamo come scrivere test che simulano l'uso reale, riducono i falsi positivi e proteggono il fatturato, non solo il codice.

Perché i test tradizionali falliscono con i componenti React?

I test che montano un componente e verificano lo stato interno o i metodi di classe sono fragili. Un refactoring che non cambia il comportamento rompe decine di test. Un test che controlla wrapper.state() o component.instance().method() non dice nulla su cosa vede l'utente. React Testing Library inverte la prospettiva: non testi il componente, testi l'interazione con la pagina. Se l'utente non può trovare un bottone, cliccarlo e vedere il risultato, il test fallisce. Se il bottone c'è ma il testo è cambiato da "Salva" a "Invia", il test fallisce. Questo è il comportamento reale.

Il principio guida: più simile a come il software viene usato

La libreria si basa su un principio semplice: i test devono interrogare il DOM come farebbe un utente. Niente accesso diretto allo stato interno, niente chiamate a metodi privati. Si usa il testo visibile, i ruoli ARIA, le etichette dei form. Se un elemento non è accessibile a un utente, non dovrebbe essere testato. Questo elimina la maggior parte dei test fragili e rende la suite più lenta a rompersi ma più veloce a dare fiducia.

Errore comune: testare con container.querySelector('.btn-primary'). Se qualcuno cambia la classe CSS, il test fallisce senza motivo. Con getByRole('button', { name: /salva/i }) il test resiste al refactoring e verifica l'accessibilità.

Come si configura React Testing Library in un progetto esistente?

La configurazione è minima, ma va fatta bene. Con un progetto creato da create-react-app la libreria è già inclusa. Con Vite o Next.js serve un'installazione manuale. Ecco i passaggi per un progetto Vite con Vitest, la scelta più comune per i progetti nuovi.

npm install -D @testing-library/react @testing-library/jest-dom @testing-library/user-event vitest jsdom

Poi configura vitest.config.ts per usare jsdom e aggiungi il setup per i matcher di jest-dom.

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    environment: 'jsdom',
    setupFiles: './src/test/setup.ts',
  },
});

Nel file setup.ts importa i matcher:

import '@testing-library/jest-dom/vitest';

Ora puoi scrivere test che usano render, screen e userEvent.

Nota operativa: se usi Next.js, la configurazione è simile ma con next/jest e il supporto per i componenti server. Noi, di Meteora Web, preferiamo Vitest per la velocità, ma Jest funziona ugualmente.

Quali query user-centric usare per trovare gli elementi nel DOM?

React Testing Library offre diverse query, ma non tutte sono uguali. La priorità d'uso segue l'ordine di accessibilità:

• getByRole — la prima scelta per bottoni, link, heading. Usa il ruolo ARIA e il nome accessibile.
• getByLabelText — per gli input di un form, associati alla label.
• getByPlaceholderText — solo se non c'è una label, come fallback.
• getByText — per elementi non interattivi come paragrafi o span.
• getByTestId — ultima risorsa, solo per elementi dinamici senza testo stabile.

Questa gerarchia non è un capriccio. Ogni query che usa il ruolo e il nome accessibile verifica che il componente sia utilizzabile da screen reader e da utenti con disabilità. Un test che usa getByRole è più robusto e più accessibile allo stesso tempo.

import { render, screen } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import LoginForm from './LoginForm';

test('mostra errore se la password è troppo corta', async () => {
  render(<LoginForm />);
  const user = userEvent.setup();

  await user.type(screen.getByLabelText(/email/i), 'utente@esempio.it');
  await user.type(screen.getByLabelText(/password/i), '123');
  await user.click(screen.getByRole('button', { name: /accedi/i }));

  expect(screen.getByText(/la password deve avere almeno 8 caratteri/i)).toBeInTheDocument();
});

Errore comune: usare getByTestId per tutto. Se il componente cambia struttura, il test si rompe. Usalo solo quando non esiste un'alternativa accessibile.

Come testare le interazioni utente con userEvent invece di fireEvent?

fireEvent è la vecchia API, userEvent è quella moderna. La differenza è sostanziale: fireEvent scatena un evento sintetico, userEvent simula l'interazione reale del browser. Con userEvent, una digitazione in un input attiva tutti gli eventi intermedi — keyDown, keyPress, keyUp, input, change — esattamente come farebbe un utente. Questo cattura bug che fireEvent ignora, come la gestione della composizione dei caratteri o la sincronizzazione con librerie di terze parti.

import { render, screen } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import SearchBar from './SearchBar';

test('chiama onSearch dopo la digitazione e il submit', async () => {
  const onSearch = vi.fn();
  render(<SearchBar onSearch={onSearch} />);
  const user = userEvent.setup();

  const input = screen.getByRole('searchbox');
  await user.type(input, 'React Testing Library');
  await user.keyboard('{Enter}');

  expect(onSearch).toHaveBeenCalledWith('React Testing Library');
});

Perché conviene: userEvent è più lento ma più affidabile. In una suite con centinaia di test, la differenza di velocità è trascurabile rispetto ai bug che cattura. Noi lo usiamo come default in tutti i progetti.

Come gestire le chiamate API nei test senza renderli lenti o fragili?

I test che fanno chiamate di rete reali sono lenti, non deterministici e si rompono quando il server non è disponibile. La soluzione è il mocking, ma va fatto nel modo giusto. Non mockare il modulo HTTP, mocka il livello di servizio o usa MSW (Mock Service Worker) per intercettare le richieste a livello di rete. MSW è la scelta migliore perché non richiede di modificare il codice del componente e simula il comportamento reale del server.

import { setupServer } from 'msw/node';
import { http, HttpResponse } from 'msw';

const server = setupServer(
  http.get('/api/prodotti', () => {
    return HttpResponse.json([{ id: 1, nome: 'Prodotto A' }]);
  })
);

beforeAll(() => server.listen());
afterEach(() => server.resetHandlers());
afterAll(() => server.close());

test('mostra la lista dei prodotti', async () => {
  render(<ProductList />);
  expect(await screen.findByText('Prodotto A')).toBeInTheDocument();
});

Con MSW, il test verifica che il componente gestisca correttamente la risposta del server, inclusi gli stati di errore e caricamento. Se il server restituisce un errore 500, il componente deve mostrare un messaggio di errore. Questo è un test che protegge il fatturato, perché un errore non gestito in produzione significa utenti persi.

Errore comune: mockare fetch con vi.fn() e dimenticare di ripristinarlo. Con MSW non hai questo problema, perché il server viene resettato automaticamente dopo ogni test.

Come testare componenti asincroni con findBy e waitFor senza flaky test?

I componenti che caricano dati in modo asincrono sono il terreno fertile per i test flaky. Un test che usa getByText subito dopo il render fallisce perché il dato non è ancora arrivato. La soluzione è usare findBy — che combina getBy e waitFor — oppure waitFor esplicito per condizioni più complesse.

test('mostra il prezzo dopo il caricamento', async () => {
  render(<ProductDetail productId={1} />);
  
  expect(screen.getByText(/caricamento/i)).toBeInTheDocument();
  expect(await screen.findByText('€ 49,99')).toBeInTheDocument();
});

La regola è: se il dato arriva da una promessa, usa findBy o waitFor. Non usare getBy per elementi che non sono ancora nel DOM. Questo vale anche per gli stati di errore: findByText(/errore/i) aspetta che l'errore appaia.

Perché conviene: i test flaky minano la fiducia nel test suite. Quando un test fallisce a caso, il team inizia a ignorarlo. Con findBy, il test aspetta il tempo necessario e fallisce solo se il comportamento è realmente sbagliato.

Cosa fare adesso

Ecco le azioni concrete per portare React Testing Library nel tuo progetto e iniziare a scrivere test user-centric oggi stesso:

• Installa e configura la libreria nel tuo progetto, seguendo i passaggi sopra. Se usi Vite, copia la configurazione di vitest.config.ts e setup.ts.
• Sostituisci i test esistenti che usano fireEvent e getByTestId con userEvent e getByRole. Inizia dai componenti più critici, come i form di login e checkout.
• Integra MSW per mockare le API. Se hai già dei mock manuali, migra a MSW per ridurre la fragilità e migliorare la velocità.
• Scrivi un test per il flusso principale del tuo prodotto: login, ricerca, aggiunta al carrello. Se quel test passa, il core business è protetto.
• Misura la copertura ma non fossilizzarti sul numero. Una copertura alta con test sbagliati è peggio di una copertura bassa con test giusti. Guarda la qualità, non la percentuale.

Noi, di Meteora Web, usiamo React Testing Library in ogni progetto React che segue il nostro stack. È il modo più diretto per ridurre i bug in produzione e dare al cliente un prodotto che funziona davvero. Se vuoi approfondire, parti dalla nostra guida completa a React o leggi come gestiamo gli eventi in Laravel per un approccio full-stack.