Kurs JavaScript i React · Moduł 13: Testowanie React

React Testing Library - Panel Kontroli Misji

10 min czytania ·
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:

ZnacznikRola
<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-insensitive

Zwykł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):

  1. getByRole - dostępność, jak użytkownik widzi element
  2. getByLabelText - formularze
  3. getByPlaceholderText - gdy brak etykiety
  4. getByText - elementy nieinteraktywne
  5. getByDisplayValue - aktualna wartość pola
  6. getByAltText - obrazy
  7. getByTitle - atrybut title
  8. 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. 1. Co robi funkcja cleanup() w React Testing Library i kiedy jest automatycznie wywoływana?

  2. 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 }).

  1. Zadanie z kodemPraktyka: Komponent FuelGauge
  2. PytanieAutomatyczne czyszczenie w RTL
  3. PytanieRóżnica między getBy i queryBy
  4. PytaniePriorytet selektorów RTL
  5. Ułóż w kolejnościSkładnia screen.getByRole z opcjami
  6. Zadanie z kodemPraktyka: Formularz z walidacją
  7. Ułóż w kolejnościSkładnia renderowania w RTL
  8. PytanieZapytania findBy w RTL
  9. Zadanie z kodemPraktyka: Komponenty interaktywne

Przydatne artykuły