Kurs JavaScript i React · Moduł 13: Testowanie React
React Testing Library - Panel Kontroli Misji
W tej lekcji9
Wyobraź sobie test, który sprawdza, czy w stanie komponentu zmienna isOpen ma wartość true. Zmieniasz nazwę zmiennej na expanded, aplikacja działa identycznie, a test pada. Taki test pilnuje szczegółów implementacji, a nie tego, co widzi pilot. Po kilku refaktoryzacjach zespół przestaje ufać testom, bo czerwone światło zapala się bez powodu.
React Testing Library (RTL) to biblioteka, która zmienia sposób, w jaki testujemy komponenty React. Zamiast testować wewnętrzną implementację, RTL skupia się na tym, co użytkownik widzi i robi - dokładnie jak panel kontroli misji, który pokazuje pilotowi tylko to, co istotne.
Główna zasada RTL
"Im bardziej Twoje testy przypominają sposób, w jaki oprogramowanie jest używane, tym więcej pewności Ci dają." - Kent C. Dodds
Z tej zasady wynika cała reszta: szukamy elementów tak jak użytkownik, po roli, etykiecie i tekście, a nie po klasach CSS czy nazwach zmiennych.
Renderowanie komponentów
Funkcja render to podstawa RTL - montuje komponent w dokumencie jsdom, czyli implementacji DOM działającej w Node.js (to nie jest wirtualny DOM Reacta). Obiekt screen daje dostęp do zapytań na całym dokumencie:
import { render, screen } from '@testing-library/react';
import SpaceshipDashboard from './SpaceshipDashboard';
test('renders spaceship dashboard', () => {
render(<SpaceshipDashboard pilotName="Nova" />);
// Komponent jest teraz dostępny do testowania
expect(screen.getByText('Welcome, Nova!')).toBeInTheDocument();
});Po render komponent jest w dokumencie, a screen.getByText szuka go tak, jak czytałby go użytkownik. Nie musisz po sobie sprzątać: RTL po każdym teście automatycznie wywołuje cleanup, czyli odmontowuje komponenty, gdy test runner udostępnia globalną funkcję afterEach. Jest robi to zawsze, a Vitest po włączeniu opcji globals: true. Dzięki temu każdy test zaczyna z pustym dokumentem i nie widzi pozostałości poprzednich.
Zapytania (queries) - Wyszukiwanie Elementów
RTL oferuje trzy rodziny zapytań, każda do innego celu. Różnią się zachowaniem, gdy elementu nie ma.
getBy - Szuka i wymaga znalezienia
Używaj getBy, gdy element musi istnieć. Zapytanie rzuca błąd, jeśli go nie ma, a także wtedy, gdy pasuje więcej niż jeden element:
// Rzuca błąd, jeśli element NIE istnieje
const heading = screen.getByText('Mission Control');
const input = screen.getByRole('textbox');
const img = screen.getByAltText('spaceship');Dla wielu elementów istnieje wariant getAllBy, który zwraca tablicę. Razem z queryAllBy i within poznasz go bliżej w dalszej części lekcji.
queryBy - Szuka, ale nie wymaga
queryBy przydaje się do sprawdzania, że czegoś nie ma na ekranie:
// Zwraca null, jeśli element NIE istnieje (nie rzuca błędu)
const error = screen.queryByText('Error occurred');
expect(error).not.toBeInTheDocument();Gdybyś użył tu getByText, test padłby na samym wyszukiwaniu, zanim dotarłby do asercji.
findBy - Szuka asynchronicznie
findBy czeka, aż element się pojawi, więc zwraca Promise i wymaga await:
// Czeka na pojawienie się elementu (zwraca Promise)
const data = await screen.findByText('Data loaded');
expect(data).toBeInTheDocument();Pod spodem to połączenie getBy z waitFor. Domyślnie czeka do 1000 ms, a potem zgłasza błąd.
Rodzaje selektorów
Każda rodzina zapytań ma warianty. Nazwa zapytania to rodzina plus sposób szukania, np. getByRole czy findByText.
ByRole - Najlepsza praktyka!
Rola ARIA to to, czym element jest dla czytnika ekranu: przycisk, nagłówek, pole tekstowe. Opcja name odpowiada dostępnej nazwie, czyli najczęściej tekstowi lub etykiecie:
// Szuka po roli ARIA - najlepszy sposób!
screen.getByRole('button', { name: 'Launch' });
screen.getByRole('heading', { level: 1 });
screen.getByRole('textbox', { name: /pilot name/i });
screen.getByRole('checkbox', { checked: true });
screen.getByRole('link', { name: 'Dashboard' });Jeśli getByRole nie znajduje przycisku, często oznacza to problem z dostępnością w samym komponencie, a nie w teście. Żeby korzystać z tego zapytania świadomie, musisz wiedzieć dwie rzeczy: skąd element ma rolę i skąd ma nazwę.
Role wbudowane w znaczniki
Test ma znaleźć listę misji, a w kodzie komponentu nie ma żadnego atrybutu role? Nie musi go być. Większość znaczników HTML ma rolę domyślną (niejawną), którą przeglądarka i RTL odczytują same:
| Znacznik | Rola |
|---|---|
<button> | button |
<a href="..."> | link |
<h1> do <h6> | heading (opcja level to numer nagłówka) |
<input type="text">, <textarea> | textbox |
<input type="checkbox"> | checkbox |
<select> | combobox |
<ul> lub <ol> oraz <li> | list oraz listitem |
<table>, <tr>, <th>, <td> | table, row, columnheader, cell |
Dwie pułapki warto zapamiętać. Link bez atrybutu href nie ma roli link, a lista rozwijana <select> jest dla czytnika ekranu polem combobox, więc szukasz jej przez getByRole('combobox'), a nie "select".
Role nadawane atrybutem role
Wskaźnik paliwa, komunikat ostrzegawczy czy zakładki budujesz zwykle z elementów div i p, które nie mają własnej roli. Wtedy nadajesz ją jawnie atrybutem role, a stan opisujesz atrybutami aria-*:
function ShieldMeter({ level }) {
return (
<div>
<div
role="progressbar"
aria-label="Shield level"
aria-valuenow={level}
aria-valuemin={0}
aria-valuemax={100}
/>
{level < 20 && <p role="alert">Shields critical!</p>}
</div>
);
}role="progressbar" zamienia zwykły div we wskaźnik postępu: aria-valuenow, aria-valuemin i aria-valuemax podają jego wartość i zakres, a aria-label nadaje mu nazwę. role="alert" oznacza pilny komunikat, który czytnik ekranu przeczyta od razu. Spokojniejsze informacje, np. "Skanowanie zakończone", dostają role="status", a zakładki trzy role naraz: tablist na kontenerze, tab na każdym przycisku i tabpanel na treści.
Test sprawdza wskaźnik i ostrzeżenie tak, jak odczytałby je czytnik ekranu:
test('warns when shields are critical', () => {
render(<ShieldMeter level={15} />);
const meter = screen.getByRole('progressbar', { name: 'Shield level' });
expect(meter).toHaveAttribute('aria-valuenow', '15');
expect(screen.getByRole('alert')).toHaveTextContent('Shields critical!');
});Zauważ, że komunikatu nie szukamy opcją name. Role alert i status nie biorą nazwy z treści, więc tekst sprawdza matcher toHaveTextContent, a toHaveAttribute porównuje wartość atrybutu. Oba pochodzą z jest-dom, o którym za chwilę.
Skąd element ma nazwę
Opcja name porównuje dostępną nazwę elementu, czyli to, co czytnik ekranu przeczyta razem z rolą. Nazwa pochodzi najczęściej z jednego z trzech źródeł:
// 1. Z treści elementu: przyciski, linki, nagłówki
// <button>Launch</button>
screen.getByRole('button', { name: 'Launch' });
// 2. Z aria-label, gdy element nie ma czytelnego tekstu
// <button aria-label="Close panel">×</button>
screen.getByRole('button', { name: 'Close panel' });
// 3. Z etykiety powiązanej przez htmlFor i id...
// <label htmlFor="pilot">Pilot name</label>
// <input id="pilot" type="text" />
screen.getByRole('textbox', { name: 'Pilot name' });
// ...albo z etykiety, która otacza pole
// <label><input type="checkbox" /> Autopilot</label>
screen.getByRole('checkbox', { name: 'Autopilot' });Dla RTL pole bez etykiety ma pustą nazwę, nawet jeśli ma placeholder, więc zapytanie z opcją name go nie znajdzie. To dobra wiadomość: test od razu wskazuje brak etykiety, a placeholder znika po wpisaniu tekstu, więc etykiety nie zastąpi.
Filtrowanie po stanie: checked, pressed, selected
Gdy na ekranie jest kilka elementów tej samej roli, możesz wybrać ten w określonym stanie:
// Zaznaczone pole wyboru (checkbox albo radio)
screen.getByRole('checkbox', { name: 'Autopilot', checked: true });
// Wciśnięty przełącznik: <button aria-pressed="true">Orbit</button>
screen.getByRole('button', { pressed: true });
// Wybrana zakładka albo wybrana opcja listy rozwijanej
screen.getByRole('tab', { selected: true });
screen.getByRole('option', { name: 'Mars', selected: true });checked czyta stan pola wyboru, pressed atrybut aria-pressed przycisków działających jak włącznik, a selected atrybut aria-selected zakładek albo zaznaczenie opcji w <select>. Gdy zapytanie z takim filtrem nie znajduje elementu, wiesz od razu, że komponent pokazuje inny stan, niż zakładał test.
ByText - Szuka po tekście
Tekst sprawdza się przy elementach nieinteraktywnych, jak komunikaty i akapity:
screen.getByText('Mission Status: Active');
screen.getByText(/mission/i); // regex, case-insensitiveZwykły napis musi pasować w całości, a wyrażenie regularne pozwala szukać fragmentu bez względu na wielkość liter.
ByLabelText - Szuka po etykiecie formularza
Pola formularza najlepiej znajdować po etykiecie, tak jak robi to użytkownik:
// <label htmlFor="speed">Speed</label>
// <input id="speed" />
screen.getByLabelText('Speed');Zapytanie działa tylko wtedy, gdy label jest poprawnie powiązany z polem, więc test przy okazji pilnuje dostępności.
ByPlaceholderText - Szuka po placeholderze
Placeholder to podpowiedź w pustym polu:
screen.getByPlaceholderText('Enter coordinates');Traktuj go jako zapasowy wybór, bo placeholder znika po wpisaniu tekstu i nie zastępuje etykiety.
ByTestId - Ostateczność
Atrybut data-testid to znacznik widoczny tylko dla testów:
// <div data-testid="fuel-gauge">...</div>
screen.getByTestId('fuel-gauge');Użytkownik go nie widzi, więc test oparty na nim mówi najmniej o prawdziwym doświadczeniu.
Priorytet selektorów
RTL zaleca następujący priorytet (od najlepszego):
- getByRole - dostępność, jak użytkownik widzi element
- getByLabelText - formularze
- getByPlaceholderText - gdy brak etykiety
- getByText - elementy nieinteraktywne
- getByDisplayValue - aktualna wartość pola
- getByAltText - obrazy
- getByTitle - atrybut title
- getByTestId - ostateczność, gdy nic innego nie pasuje
Wiele elementów i zapytania wewnątrz elementu
Lista misji ma kilka kart, tabela kilka wierszy, a powiadomienia często mają przyciski o tej samej nazwie. getBy rzuciłby tu błąd, bo pasuje więcej niż jeden element. Na takie sytuacje każda rodzina zapytań ma wariant All, a funkcja within zawęża szukanie do wnętrza jednego elementu. Załóżmy, że CrewTable pokazuje tabelę z wierszem nagłówka i jednym wierszem na każdego członka załogi:
import { render, screen, within } from '@testing-library/react';
test('lists the crew in a table', () => {
const crew = [
{ name: 'Nova', role: 'Pilot' },
{ name: 'Astro', role: 'Engineer' },
];
render(<CrewTable crew={crew} />);
// getAllBy zwraca tablicę i rzuca błąd, gdy nic nie pasuje
const rows = screen.getAllByRole('row');
expect(rows).toHaveLength(3); // nagłówek i dwie osoby
// within ogranicza zapytania do wnętrza jednego wiersza
const cells = within(rows[1]).getAllByRole('cell');
expect(cells[0]).toHaveTextContent('Nova');
// queryAllBy zwraca pustą tablicę zamiast błędu
expect(screen.queryAllByRole('alert')).toHaveLength(0);
});getAllBy (i jego asynchroniczny odpowiednik findAllBy) rzuca błąd, gdy nie znajdzie ani jednego elementu, a queryAllBy zwraca wtedy pustą tablicę, dlatego nadaje się do sprawdzenia, że elementy zniknęły. within(element) daje te same zapytania co screen, ale szuka tylko w środku wskazanego elementu. Tak samo znajdziesz przycisk zamknięcia w jednym konkretnym powiadomieniu: within(screen.getByRole('alert')).getByRole('button', { name: 'Close' }). Funkcję within importujesz z @testing-library/react, razem z render i screen.
Matchery jest-dom
Biblioteka @testing-library/jest-dom dodaje specjalne matchery. Podłączasz ją raz, importując @testing-library/jest-dom w pliku jest.setup.js, który w pierwszej lekcji wskazałeś w opcji setupFilesAfterEnv:
// Widoczność
expect(element).toBeVisible();
expect(element).toBeInTheDocument();
// Atrybuty i stan
expect(button).toBeDisabled();
expect(input).toBeRequired();
expect(input).toHaveValue('Apollo');
expect(checkbox).toBeChecked();
expect(link).toHaveAttribute('href', '/dashboard');
// Klasy CSS
expect(element).toHaveClass('active');
// Tekst
expect(element).toHaveTextContent('Mission');
// Style
expect(element).toHaveStyle({ color: 'rgb(0, 128, 0)' });toBeInTheDocument sprawdza tylko obecność w dokumencie, a toBeVisible dodatkowo, czy element nie jest ukryty np. przez display: none. toHaveStyle porównuje styl obliczony przez jsdom, który zwraca kolory w zapisie rgb(...), dlatego kolor podajesz jako rgb(0, 128, 0) albo #008000: sama nazwa green nie przejdzie.
Renderowanie z kontekstem
Często komponenty potrzebują providerów (Router, Theme, Store). Zamiast powtarzać je w każdym teście, tworzymy własną funkcję renderującą z opcją wrapper:
function renderWithProviders(ui, options = {}) {
function Wrapper({ children }) {
return (
<ThemeProvider theme="dark">
<MissionProvider>
{children}
</MissionProvider>
</ThemeProvider>
);
}
return render(ui, { wrapper: Wrapper, ...options });
}
// Użycie
test('renders themed dashboard', () => {
renderWithProviders(<Dashboard />);
expect(screen.getByText('Dark Mode')).toBeInTheDocument();
});renderWithProviders przyjmuje te same argumenty co render, więc testy wyglądają niemal identycznie, a konfiguracja siedzi w jednym miejscu.
Debug - kiedy testy nie przechodzą
Gdy test nie przechodzi i nie wiesz dlaczego, użyj screen.debug() do podejrzenia aktualnego stanu DOM:
test('shows mission status', () => {
render(<MissionPanel />);
// Wyświetla aktualny stan DOM w konsoli
screen.debug();
// Możesz też debugować konkretny element
const panel = screen.getByRole('main');
screen.debug(panel);
});screen.debug() wyświetli HTML całego wyrenderowanego komponentu, co pomaga zrozumieć, dlaczego selektor nie znajduje elementu. To jak system diagnostyczny na statku kosmicznym - gdy coś nie działa, najpierw sprawdzasz logi!
Moja rada: zaczynaj od getByRole i schodź niżej w priorytecie tylko wtedy, gdy musisz. W kolejnej lekcji dodamy do tego symulację kliknięć i pisania.
React Testing Library to fundament nowoczesnego testowania komponentów React. Zamiast testować detale implementacji, testujesz to, co naprawdę ważne - doświadczenie użytkownika.
Kod do tej lekcji: App.jsx
import React, { useState } from 'react';
const MISSIONS = [
{ id: 1, name: 'Apollo 11', status: 'completed', crew: 3 },
{ id: 2, name: 'Artemis I', status: 'active', crew: 0 },
{ id: 3, name: 'Mars Explorer', status: 'planned', crew: 6 },
{ id: 4, name: 'Jupiter Probe', status: 'active', crew: 4 },
];
const STATUS_LABELS = {
completed: 'zakończona',
active: 'aktywna',
planned: 'planowana',
};
// Zapytanie RTL, które znajdzie element powyżej w jego obecnym stanie
function Query({ code }) {
return <code className="query">{code}</code>;
}
function MissionCard({ mission, selected, onSelect }) {
return (
<li className={'mission-card status-' + mission.status}>
<h3>{mission.name}</h3>
<p>Status: <span className="badge">{STATUS_LABELS[mission.status]}</span></p>
<p>Załoga: {mission.crew}</p>
<button
aria-label={'Wybierz misję ' + mission.name}
aria-pressed={selected}
onClick={onSelect}
>
Wybierz
</button>
</li>
);
}
function MissionList() {
const [query, setQuery] = useState('');
const [onlyActive, setOnlyActive] = useState(false);
const [selected, setSelected] = useState(null);
const visible = MISSIONS.filter(
(m) =>
m.name.toLowerCase().includes(query.toLowerCase()) &&
(!onlyActive || m.status === 'active')
);
const statusText = selected ? 'Wybrana misja: ' + selected : 'Nie wybrano misji';
const pressedVisible = visible.some((m) => m.name === selected);
return (
<div className="mission-list">
<div className="field">
<label htmlFor="search">Szukaj misji</label>
<input
id="search"
type="text"
value={query}
placeholder="Wpisz nazwę misji..."
onChange={(e) => setQuery(e.target.value)}
/>
<Query code="screen.getByRole('textbox', { name: 'Szukaj misji' })" />
</div>
<div className="field">
<label className="checkbox">
<input
type="checkbox"
checked={onlyActive}
onChange={(e) => setOnlyActive(e.target.checked)}
/>
Tylko aktywne
</label>
<Query code={"screen.getByRole('checkbox', { name: 'Tylko aktywne', checked: " + onlyActive + " })"} />
</div>
<p role="status" className="selected-info">{statusText}</p>
<Query code={"expect(screen.getByRole('status')).toHaveTextContent('" + statusText + "')"} />
<Query
code={pressedVisible
? "screen.getByRole('button', { name: 'Wybierz misję " + selected + "', pressed: true })"
: "expect(screen.queryByRole('button', { pressed: true })).toBeNull()"}
/>
{visible.length > 0 ? (
<>
<Query code={"expect(screen.getAllByRole('listitem')).toHaveLength(" + visible.length + ")"} />
<ul className="cards">
{visible.map((m) => (
<MissionCard
key={m.id}
mission={m}
selected={selected === m.name}
onSelect={() => setSelected(m.name)}
/>
))}
</ul>
</>
) : (
<>
<p className="no-results">Nie znaleziono misji</p>
<Query code="expect(screen.queryAllByRole('listitem')).toHaveLength(0)" />
</>
)}
</div>
);
}
export default function App() {
return (
<div className="app">
<h1>React Testing Library - Panel kontroli</h1>
<p className="note">
Podgląd nie uruchamia Jest. Pod elementami widzisz zapytania RTL, które
znajdą je w obecnym stanie: wpisz nazwę, zaznacz pole albo wybierz misję
i patrz, jak zmieniają się opcje checked i pressed.
</p>
<MissionList />
</div>
);
}Hasła z dokumentacji w tej lekcji
Widzisz błąd w tej lekcji?
Sprawdź się
Odpowiedz na pytania z tej lekcji. Wybierz odpowiedź, a od razu zobaczysz, czy jest poprawna.
1. Co robi funkcja cleanup() w React Testing Library i kiedy jest automatycznie wywoływana?
2. Jaka jest kluczowa różnica między getBy a queryBy w React Testing Library?
To 2 z 4 pytań do tej lekcji. Pozostałe rozwiążesz w grze.
Zadania praktyczne w grze
- Edytor kodu
Dokończ wskaźnik paliwa tak, żeby test znalazł go tak jak użytkownik czytnika ekranu. ___BLANK1___: isLow jest prawdą, gdy poziom paliwa jest mniejszy niż 20. ___BLANK2___: pasek ma rolę progressbar, więc test znajdzie go przez getByRole('progressbar', { name: 'Poziom paliwa' }) (nazwę daje aria-label, a poziom aria-valuenow). ___BLANK3___: ostrzeżenie o niskim poziomie ma rolę alert, którą czytnik ekranu ogłasza od razu. ___BLANK4___: przycisk Zatankuj dodaje 25 punktów procentowych, ale poziom nie może przekroczyć 100.
- Układanie w poziomie
Ułóż poprawną składnię wyszukiwania przycisku Submit za pomocą getByRole:
- Edytor kodu
Dokończ formularz rekrutacji załogi CrewForm tak, żeby dało się go przetestować przez React Testing Library. ___BLANK1___: etykieta Imię załoganta wskazuje przez htmlFor id pola tekstowego (crew-name), więc test znajdzie je przez getByLabelText('Imię załoganta'). ___BLANK2___: błąd imienia pojawia się, gdy imię po obcięciu spacji z początku i końca ma mniej niż 2 znaki. ___BLANK3___: błąd roli pojawia się, gdy nie wybrano żadnej roli (pusta wartość listy). Błędy mają role="alert", a przy poprawnych danych formularz wywołuje onSubmit({ name, role }) z obciętym imieniem i czyści pola.
- Układanie w pionie
Ułóż składnię renderowania i sprawdzania komponentu w RTL:
- Edytor kodu
Dokończ dwa komponenty panelu sterowania. ToggleSwitch to checkbox w etykiecie, więc test znajdzie go przez getByRole('checkbox', { name: 'Osłony' }). ___BLANK1___: checkbox jest kontrolowany, jego zaznaczenie pochodzi ze stanu on. ___BLANK2___: po kliknięciu stan przyjmuje nowe zaznaczenie z obiektu zdarzenia (pole checked elementu event.target), a status obok zmienia się na włączone albo wyłączone. NavigationList pokazuje przyciski celów podróży. ___BLANK3___: aria-pressed przycisku jest true tylko dla wybranego celu, a dla pozostałych false, więc test znajdzie wybrany cel przez getByRole('button', { pressed: true }).
Zadania po tej lekcji
- Zadanie z kodemPraktyka: Komponent FuelGauge
- PytanieAutomatyczne czyszczenie w RTL
- PytanieRóżnica między getBy i queryBy
- PytaniePriorytet selektorów RTL
- Ułóż w kolejnościSkładnia screen.getByRole z opcjami
- Zadanie z kodemPraktyka: Formularz z walidacją
- Ułóż w kolejnościSkładnia renderowania w RTL
- PytanieZapytania findBy w RTL
- Zadanie z kodemPraktyka: Komponenty interaktywne